feat: add Pi Coding Agent support

.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/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/codex/codexAppServerClient.ts

@@ -1,5 +1,6 @@
 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { logger } from '@/ui/logger';
+import { JsonLineParser } from '@/utils/jsonLineParser';
 import { killProcessByChildProcess } from '@/utils/process';
 import type {
     CollaborationModeListResponse,
@@ -69,10 +70,9 @@ function createAbortError(): Error {
     return error;
 }
 
-export class CodexAppServerClient {
+export class CodexAppServerClient extends JsonLineParser {
     private process: ChildProcessWithoutNullStreams | null = null;
     private connected = false;
-    private buffer = '';
     private nextId = 1;
     private readonly pending = new Map<number, PendingRequest>();
     private readonly requestHandlers = new Map<string, RequestHandler>();
@@ -103,7 +103,7 @@ export class CodexAppServerClient {
         });
 
         this.process.stdout.setEncoding('utf8');
-        this.process.stdout.on('data', (chunk) => this.handleStdout(chunk));
+        this.process.stdout.on('data', (chunk) => this.feed(chunk));
 
         this.process.stderr.setEncoding('utf8');
         this.process.stderr.on('data', (chunk) => {
@@ -354,23 +354,7 @@ export class CodexAppServerClient {
         this.writePayload(payload);
     }
 
-    private handleStdout(chunk: string): void {
-        this.buffer += chunk;
-        let newlineIndex = this.buffer.indexOf('\n');
-
-        while (newlineIndex >= 0) {
-            const line = this.buffer.slice(0, newlineIndex).trim();
-            this.buffer = this.buffer.slice(newlineIndex + 1);
-
-            if (line.length > 0) {
-                this.handleLine(line);
-            }
-
-            newlineIndex = this.buffer.indexOf('\n');
-        }
-    }
-
-    private handleLine(line: string): void {
+    protected handleLine(line: string): void {
         if (this.protocolError) {
             return;
         }
@@ -482,7 +466,7 @@ export class CodexAppServerClient {
     }
 
     private resetParserState(): void {
-        this.buffer = '';
+        this.reset();
         this.protocolError = null;
     }
 

cli/src/codex/runCodex.test.ts

@@ -56,7 +56,8 @@ const lifecycleMock = vi.hoisted(() => ({
     markCrash: vi.fn(),
     setExitCode: vi.fn(),
     setArchiveReason: vi.fn(),
-    setSessionEndReason: vi.fn()
+    setSessionEndReason: vi.fn(),
+    hasExplicitSessionEndReason: vi.fn(() => false)
 }))
 
 vi.mock('@/agent/runnerLifecycle', () => ({

cli/src/commands/agentCommandOptions.test.ts

@@ -69,3 +69,111 @@ describe('parseRemoteAgentCommandOptions', () => {
         expect(() => parseRemoteAgentCommandOptions(['--model-reasoning-effort'], OPENCODE_PERMISSION_MODES)).toThrow('Missing --model-reasoning-effort value')
     })
 })
+
+describe('parseRemoteAgentCommandOptions — pi flavor', () => {
+    // Pi RPC mode has no permission switching, so the command passes an empty
+    // allow-list. These tests cover the non-permission flags using a non-empty
+    // allow-list purely as a parser fixture — the parser's behavior is
+    // independent of the modes' contents.
+    const ALLOWED = OPENCODE_PERMISSION_MODES
+
+    it('accepts --model and stores it on options', () => {
+        const result = parseRemoteAgentCommandOptions(
+            ['--model', 'claude-sonnet-4-5'],
+            ALLOWED
+        )
+        expect(result.model).toBe('claude-sonnet-4-5')
+    })
+
+    it('--session-id stores the value as resumeSessionId (Pi-specific flag)', () => {
+        // Pi uses --session-id for exact session resume (RPC mode), not the
+        // generic --resume that other flavors use.
+        const result = parseRemoteAgentCommandOptions(
+            ['--session-id', 'pi-sess-123'],
+            ALLOWED
+        )
+        expect(result.resumeSessionId).toBe('pi-sess-123')
+    })
+
+    it('--resume is also accepted as an alias for session resume', () => {
+        // Some flavor paths pass --resume; the parser should accept it
+        // uniformly so callers do not need to branch on flavor.
+        const result = parseRemoteAgentCommandOptions(
+            ['--resume', 'sess-id'],
+            ALLOWED
+        )
+        expect(result.resumeSessionId).toBe('sess-id')
+    })
+
+    it('a later --resume overrides a prior --session-id (last-write-wins)', () => {
+        const result = parseRemoteAgentCommandOptions(
+            ['--session-id', 'first', '--resume', 'second'],
+            ALLOWED
+        )
+        expect(result.resumeSessionId).toBe('second')
+    })
+
+    it('rejects --session-id with no value', () => {
+        expect(() => parseRemoteAgentCommandOptions(
+            ['--session-id'],
+            ALLOWED
+        )).toThrow('Missing --session-id value')
+    })
+
+    it('parses --started-by runner', () => {
+        const result = parseRemoteAgentCommandOptions(
+            ['--started-by', 'runner'],
+            ALLOWED
+        )
+        expect(result.startedBy).toBe('runner')
+    })
+
+    it('parses --started-by terminal', () => {
+        const result = parseRemoteAgentCommandOptions(
+            ['--started-by', 'terminal'],
+            ALLOWED
+        )
+        expect(result.startedBy).toBe('terminal')
+    })
+
+    it('parses --hapi-starting-mode remote', () => {
+        const result = parseRemoteAgentCommandOptions(
+            ['--hapi-starting-mode', 'remote'],
+            ALLOWED
+        )
+        expect(result.startingMode).toBe('remote')
+    })
+
+    it('parses --hapi-starting-mode local', () => {
+        const result = parseRemoteAgentCommandOptions(
+            ['--hapi-starting-mode', 'local'],
+            ALLOWED
+        )
+        expect(result.startingMode).toBe('local')
+    })
+
+    it('rejects invalid --hapi-starting-mode', () => {
+        expect(() => parseRemoteAgentCommandOptions(
+            ['--hapi-starting-mode', 'invalid'],
+            ALLOWED
+        )).toThrow('Invalid --hapi-starting-mode')
+    })
+
+    it('handles a full pi invocation end-to-end', () => {
+        const result = parseRemoteAgentCommandOptions(
+            [
+                '--started-by', 'runner',
+                '--hapi-starting-mode', 'remote',
+                '--model', 'claude-sonnet-4-5',
+                '--session-id', 'pi-sess-full',
+            ],
+            ALLOWED
+        )
+        expect(result).toEqual({
+            startedBy: 'runner',
+            startingMode: 'remote',
+            model: 'claude-sonnet-4-5',
+            resumeSessionId: 'pi-sess-full',
+        })
+    })
+})