[cold-review] feat(web): markdown Source | Preview toggle in session file pane

.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,196 @@
+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'];
+}
+
+function createMockApiSessionWithMetadataCapture() {
+    const metadataWrites: Array<Record<string, unknown>> = []
+    return {
+        updateMetadata: vi.fn((handler: (m: Record<string, unknown>) => Record<string, unknown>) => {
+            const next = handler({})
+            metadataWrites.push(next)
+            return next
+        }),
+        sendSessionDeath: vi.fn(),
+        flush: vi.fn(async () => {}),
+        close: vi.fn(async () => {}),
+        metadataWrites
+    } as unknown as Parameters<typeof createRunnerLifecycle>[0]['session'] & {
+        metadataWrites: Array<Record<string, unknown>>
+    }
+}
+
+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');
+        });
+    });
+});
+
+// tiann/hapi#914: the runnerLifecycle's default archiveReason is now
+// 'Hub restart' (was 'User terminated'). Out-of-band SIGTERM from the
+// hub-restart cascade keeps that default. Explicit user actions
+// (clicking Archive in the web UI, Ctrl-C in a local terminal,
+// uncaught exception) reassign the reason before archive metadata is
+// written.
+describe('createRunnerLifecycle archiveReason defaults (tiann/hapi#914)', () => {
+    it('uses Hub restart as the default archiveReason when no override is applied', async () => {
+        const session = createMockApiSessionWithMetadataCapture()
+        const lifecycle = createRunnerLifecycle({
+            session,
+            logTag: 'test'
+        })
+
+        await lifecycle.cleanup()
+
+        expect(session.metadataWrites).toHaveLength(1)
+        expect(session.metadataWrites[0]).toMatchObject({
+            lifecycleState: 'archived',
+            archivedBy: 'cli',
+            archiveReason: 'Hub restart'
+        })
+    })
+
+    it('writes the operator-supplied reason when setArchiveReason is called (e.g. KillSession RPC)', async () => {
+        const session = createMockApiSessionWithMetadataCapture()
+        const lifecycle = createRunnerLifecycle({
+            session,
+            logTag: 'test'
+        })
+
+        lifecycle.setArchiveReason('User terminated')
+        await lifecycle.cleanup()
+
+        expect(session.metadataWrites[0]).toMatchObject({
+            archiveReason: 'User terminated'
+        })
+    })
+
+    it('markCrash overrides the default reason to "Session crashed"', async () => {
+        const session = createMockApiSessionWithMetadataCapture()
+        const lifecycle = createRunnerLifecycle({
+            session,
+            logTag: 'test'
+        })
+
+        lifecycle.markCrash(new Error('boom'))
+        await lifecycle.cleanup()
+
+        expect(session.metadataWrites[0]).toMatchObject({
+            archiveReason: 'Session crashed'
+        })
+    })
+
+    // tiann/hapi#914 review round 4: clean agent-loop completions
+    // (runClaude / runCodex / runCursor / runGemini / runKimi /
+    // runOpencode all call setSessionEndReason('completed') without
+    // touching archiveReason) must not be archived as 'Hub restart'.
+    // The setSessionEndReason setter flips the default when the runner
+    // transitions to 'completed'.
+    it('setSessionEndReason("completed") flips the default reason to "Session completed"', async () => {
+        const session = createMockApiSessionWithMetadataCapture()
+        const lifecycle = createRunnerLifecycle({
+            session,
+            logTag: 'test'
+        })
+
+        lifecycle.setSessionEndReason('completed')
+        await lifecycle.cleanup()
+
+        expect(session.metadataWrites[0]).toMatchObject({
+            archiveReason: 'Session completed'
+        })
+    })
+
+    it('an explicit setArchiveReason before setSessionEndReason("completed") still wins', async () => {
+        const session = createMockApiSessionWithMetadataCapture()
+        const lifecycle = createRunnerLifecycle({
+            session,
+            logTag: 'test'
+        })
+
+        lifecycle.setArchiveReason('User terminated')
+        lifecycle.setSessionEndReason('completed')
+        await lifecycle.cleanup()
+
+        expect(session.metadataWrites[0]).toMatchObject({
+            archiveReason: 'User terminated'
+        })
+    })
+})

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>
@@ -23,8 +24,29 @@ export type RunnerLifecycle = {
 
 export function createRunnerLifecycle(options: RunnerLifecycleOptions): RunnerLifecycle {
     let exitCode = 0
-    let archiveReason = 'User terminated'
+    // tiann/hapi#914: default reason is 'Hub restart' (parent-driven SIGTERM
+    // is the most common non-user cause). Genuine user actions (clicking
+    // Archive in the web UI, or Ctrl-C in a local terminal) explicitly
+    // reassign this via `setArchiveReason` BEFORE `cleanupAndExit` runs:
+    //   - KillSession RPC handler  → 'User terminated' (see registerKillSessionHandler)
+    //   - SIGINT handler           → 'User terminated' (Ctrl-C in local terminal)
+    //   - uncaughtException/Reject → 'Session crashed' (via markCrash)
+    //
+    // Out-of-band SIGTERM (hub-restart cascade, systemd cgroup kill on
+    // hapi-runner.service stop, `kill <pid>` from the operator) keeps the
+    // default and is correctly labelled 'Hub restart' on the audit trail.
+    //
+    // Runner-internal stop paths (`hapi runner stop-session`, webhook-timeout
+    // cleanup at run.ts:587, orphan cleanup at run.ts:267) also currently
+    // hit this default - that is technically inaccurate but follows the
+    // friction-mode "smallest defensible change" rule for this PR. Finer
+    // attribution would require an IPC channel (stdio: 'ipc' on spawn) so
+    // the runner can stamp `setArchiveReason` before SIGTERMing; tracked as
+    // a follow-up to keep this PR focussed on the user-action lie that
+    // motivated #914.
+    let archiveReason = 'Hub restart'
     let sessionEndReason: SessionEndReason = 'terminated'
+    let sessionEndReasonExplicit = false
     let cleanupStarted = false
     let cleanupPromise: Promise<void> | null = null
 
@@ -95,8 +117,23 @@ export function createRunnerLifecycle(options: RunnerLifecycleOptions): RunnerLi
 
     const setSessionEndReason = (reason: SessionEndReason) => {
         sessionEndReason = reason
+        sessionEndReasonExplicit = true
+        // tiann/hapi#914 review round 4: every agent runner
+        // (runClaude / runCodex / runCursor / runGemini / runKimi /
+        // runOpencode) calls setSessionEndReason('completed') before
+        // cleanupAndExit() on the natural-exit path without setting an
+        // archive reason. With the SIGTERM-driven default of 'Hub restart',
+        // clean completions would otherwise be audit-trailed as restart
+        // cascades. Flip the default to 'Session completed' when the end
+        // reason transitions to 'completed' AND no caller has already
+        // overridden the archive reason.
+        if (reason === 'completed' && archiveReason === 'Hub restart') {
+            archiveReason = 'Session completed'
+        }
     }
 
+    const hasExplicitSessionEndReason = () => sessionEndReasonExplicit
+
     const markCrash = (error: unknown) => {
         logger.debug(`${logPrefix} Unhandled error:`, error)
         exitCode = 1
@@ -105,11 +142,19 @@ export function createRunnerLifecycle(options: RunnerLifecycleOptions): RunnerLi
     }
 
     const registerProcessHandlers = () => {
+        // tiann/hapi#914: SIGTERM is treated as the default reason ('Hub restart')
+        // because the runner is restarted by systemd as part of hub restart in
+        // production. If a future code path needs to distinguish "operator
+        // killed the host process" from "hub restart", it can call
+        // setArchiveReason() before the runner exits.
         process.on('SIGTERM', () => {
             void cleanupAndExit()
         })
 
+        // Ctrl-C in a local terminal is genuine user intent — keep the
+        // pre-#914 label so the audit trail still shows it.
         process.on('SIGINT', () => {
+            archiveReason = 'User terminated'
             void cleanupAndExit()
         })
 
@@ -128,6 +173,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()