feat(web): iOS-style nested cursor model picker (closes #48)

.gitignore

@@ -47,3 +47,6 @@ cli/npm/main/
 test-results/
 playwright-report/
 e2e-output/
+.xyz-harness
+.agents/
+.pi/

cli/package.json

@@ -83,4 +83,4 @@
     "@types/parse-path": "7.0.3"
   },
   "packageManager": "bun@1.3.14"
-}
+}

cli/src/agent/localHandoff.test.ts

@@ -12,6 +12,7 @@ describe('registerLocalHandoffHandler', () => {
         const lifecycle = {
             setArchiveReason: vi.fn(),
             setSessionEndReason: vi.fn(),
+            hasExplicitSessionEndReason: vi.fn(() => false),
             cleanupAndExit: vi.fn(async () => {})
         }
 

cli/src/agent/messageConverter.test.ts

@@ -50,6 +50,18 @@ describe('convertAgentMessage', () => {
         });
     });
 
+    it('converts agent errors into error wire payloads', () => {
+        const converted = convertAgentMessage({
+            type: 'error',
+            message: 'Cursor Agent failed: authentication required'
+        });
+
+        expect(converted).toEqual({
+            type: 'error',
+            message: 'Cursor Agent failed: authentication required'
+        });
+    });
+
     it('converts usage messages into token_count payloads', () => {
         const converted = convertAgentMessage({
             type: 'usage',

cli/src/agent/runnerLifecycle.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createRunnerLifecycle } from './runnerLifecycle';
+import type { RunnerLifecycle } from './runnerLifecycle';
+
+// Mock heavy deps
+vi.mock('@/ui/logger', () => ({
+    logger: {
+        debug: vi.fn(),
+        getLogPath: vi.fn(() => '/tmp/test.log'),
+    },
+}));
+
+vi.mock('@/ui/terminalState', () => ({
+    restoreTerminalState: vi.fn(),
+}));
+
+function createMockApiSession() {
+    return {
+        updateMetadata: vi.fn(),
+        sendSessionDeath: vi.fn(),
+        flush: vi.fn(),
+        close: vi.fn(),
+    } as unknown as Parameters<typeof createRunnerLifecycle>[0]['session'];
+}
+
+describe('createRunnerLifecycle', () => {
+    let lifecycle: RunnerLifecycle;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        lifecycle = createRunnerLifecycle({
+            session: createMockApiSession(),
+            logTag: 'test',
+        });
+    });
+
+    // --- D-9: hasExplicitSessionEndReason ---
+
+    describe('hasExplicitSessionEndReason', () => {
+        it('returns false initially', () => {
+            expect(lifecycle.hasExplicitSessionEndReason()).toBe(false);
+        });
+
+        it('returns true after setSessionEndReason is called', () => {
+            lifecycle.setSessionEndReason('completed');
+            expect(lifecycle.hasExplicitSessionEndReason()).toBe(true);
+        });
+
+        it('returns false after markCrash — markCrash does NOT set explicit flag', () => {
+            lifecycle.markCrash(new Error('boom'));
+            expect(lifecycle.hasExplicitSessionEndReason()).toBe(false);
+        });
+
+        it('stays true once set — subsequent markCrash does not clear it', () => {
+            lifecycle.setSessionEndReason('handoff');
+            lifecycle.markCrash(new Error('late crash'));
+            expect(lifecycle.hasExplicitSessionEndReason()).toBe(true);
+        });
+    });
+
+    // --- markCrash sets reason to 'error' but not explicit ---
+
+    describe('markCrash', () => {
+        it('sets sessionEndReason to error via sendSessionDeath during cleanup', async () => {
+            const session = createMockApiSession();
+            const lc = createRunnerLifecycle({ session, logTag: 'test' });
+            lc.markCrash(new Error('fatal'));
+
+            // cleanup triggers sendSessionDeath — verify 'error' reason
+            await lc.cleanup();
+            expect(session.sendSessionDeath).toHaveBeenCalledWith('error');
+        });
+    });
+
+    // --- setSessionEndReason + cleanup propagates correct reason ---
+
+    describe('setSessionEndReason + cleanup', () => {
+        it('sends explicit reason via sendSessionDeath during cleanup', async () => {
+            const session = createMockApiSession();
+            const lc = createRunnerLifecycle({ session, logTag: 'test' });
+            lc.setSessionEndReason('completed');
+
+            await lc.cleanup();
+            expect(session.sendSessionDeath).toHaveBeenCalledWith('completed');
+        });
+    });
+});

cli/src/agent/runnerLifecycle.ts

@@ -15,6 +15,7 @@ export type RunnerLifecycle = {
     setExitCode: (code: number) => void
     setArchiveReason: (reason: string) => void
     setSessionEndReason: (reason: SessionEndReason) => void
+    hasExplicitSessionEndReason: () => boolean
     markCrash: (error: unknown) => void
     cleanup: () => Promise<void>
     cleanupAndExit: (codeOverride?: number) => Promise<void>
@@ -25,6 +26,7 @@ export function createRunnerLifecycle(options: RunnerLifecycleOptions): RunnerLi
     let exitCode = 0
     let archiveReason = 'User terminated'
     let sessionEndReason: SessionEndReason = 'terminated'
+    let sessionEndReasonExplicit = false
     let cleanupStarted = false
     let cleanupPromise: Promise<void> | null = null
 
@@ -95,8 +97,11 @@ export function createRunnerLifecycle(options: RunnerLifecycleOptions): RunnerLi
 
     const setSessionEndReason = (reason: SessionEndReason) => {
         sessionEndReason = reason
+        sessionEndReasonExplicit = true
     }
 
+    const hasExplicitSessionEndReason = () => sessionEndReasonExplicit
+
     const markCrash = (error: unknown) => {
         logger.debug(`${logPrefix} Unhandled error:`, error)
         exitCode = 1
@@ -128,6 +133,7 @@ export function createRunnerLifecycle(options: RunnerLifecycleOptions): RunnerLi
         setExitCode,
         setArchiveReason,
         setSessionEndReason,
+        hasExplicitSessionEndReason,
         markCrash,
         cleanup,
         cleanupAndExit,

cli/src/agent/sessionConfigRpc.ts

@@ -31,10 +31,22 @@ export function resolveSessionConfigPermissionMode<TPermissionMode extends Permi
     return parsed.data as TPermissionMode
 }
 
+/** Extract `modelId` from either a plain string or a `{ provider, modelId }`
+ *  object (the form Pi sessions receive from the hub). Other agents only pass
+ *  plain strings; the object branch is here for schema consistency so this
+ *  function doesn't throw if the hub later sends the union form to any agent. */
 export function resolveNullableSessionModel(value: unknown): string | null {
     if (value === null) {
         return null
     }
+    // Pi sessions receive model as { provider, modelId }; extract modelId
+    if (typeof value === 'object' && value !== null) {
+        const modelObj = value as { modelId?: unknown }
+        if (typeof modelObj.modelId === 'string' && modelObj.modelId.trim().length > 0) {
+            return modelObj.modelId.trim()
+        }
+        throw new Error('Invalid model')
+    }
     if (typeof value !== 'string' || value.trim().length === 0) {
         throw new Error('Invalid model')
     }

cli/src/agent/sessionFactory.ts

@@ -100,9 +100,15 @@ function pickExistingSessionMetadata(metadata: Metadata | null | undefined): Par
     if (metadata.cursorSessionId !== undefined) preserved.cursorSessionId = metadata.cursorSessionId
     if (metadata.cursorSessionProtocol !== undefined) preserved.cursorSessionProtocol = metadata.cursorSessionProtocol
     if (metadata.kimiSessionId !== undefined) preserved.kimiSessionId = metadata.kimiSessionId
+    if (metadata.piSessionId !== undefined) preserved.piSessionId = metadata.piSessionId
     if (metadata.tools !== undefined) preserved.tools = metadata.tools
     if (metadata.slashCommands !== undefined) preserved.slashCommands = metadata.slashCommands
     if (metadata.worktree !== undefined) preserved.worktree = metadata.worktree
+    // Preserve cached Pi model list so the web can show models immediately
+    // on inactive-session view without waiting for an RPC round-trip.
+    if (metadata.piAvailableModels !== undefined) preserved.piAvailableModels = metadata.piAvailableModels
+    // Preserve provider-qualified Pi model selection (disambiguates duplicate modelIds).
+    if (metadata.piSelectedModel !== undefined) preserved.piSelectedModel = metadata.piSelectedModel
 
     return preserved
 }

cli/src/api/apiMachine.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { mkdtempSync, rmSync, mkdirSync } from 'node:fs'
+import { mkdtempSync, rmSync, mkdirSync, realpathSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
@@ -135,7 +135,9 @@ describe('ApiMachineClient listOpencodeModelsForCwd handler', () => {
                 availableModels: [{ modelId: 'x/y' }],
                 currentModelId: 'x/y'
             })
-            expect(listOpencodeModelsForCwdMock).toHaveBeenCalledWith(secondWorkspaceRoot)
+            // The handler realpaths the cwd (security: prevents symlink escape),
+            // so on macOS /var/folders/... resolves to /private/var/folders/...
+            expect(listOpencodeModelsForCwdMock).toHaveBeenCalledWith(realpathSync(secondWorkspaceRoot))
         } finally {
             rmSync(secondWorkspaceRoot, { recursive: true, force: true })
             client.shutdown()

cli/src/api/apiSession.ts

@@ -586,6 +586,14 @@ export class ApiSessionClient extends EventEmitter {
         })
     }
 
+    /** Hub waits for this before mergeSessions on Cursor ACP reopen (tiann/hapi#939). */
+    emitSessionReady(): void {
+        this.socket.emit('session-ready', {
+            sid: this.sessionId,
+            time: Date.now()
+        })
+    }
+
     emitMessagesConsumed(localIds: string[], options?: { clearQueuedThinkingGrace?: boolean }): void {
         if (localIds.length === 0) return
         // `clearQueuedThinkingGrace` is an opt-in signal for the hub to drop

cli/src/claude/claudeRemoteLauncher.ts

@@ -306,6 +306,14 @@ class ClaudeRemoteLauncher extends RemoteLauncherBase {
                             return permissionHandler.isAborted(toolCallId);
                         },
                         nextMessage: async () => {
+                            // Flush any pending outgoing messages before consuming the next user
+                            // turn. Without this, scheduleProcessing()'s setTimeout(fn,0) fires
+                            // after the microtask that sends messages-consumed, causing the hub
+                            // to stamp invokedAt on the next user message before it stores the
+                            // current turn's queued agent messages — making them sort permanently
+                            // below the next user message.
+                            await messageQueue.flush();
+
                             if (pending) {
                                 let p = pending;
                                 pending = null;