feat(overseer): inbox substrate + v0 prioritizer (Step 2.5)

cli/src/agent/runnerLifecycle.test.ts

@@ -23,6 +23,23 @@ function createMockApiSession() {
     } 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;
 
@@ -85,3 +102,95 @@ describe('createRunnerLifecycle', () => {
         });
     });
 });
+
+// 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

@@ -24,7 +24,27 @@ 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
@@ -98,6 +118,18 @@ 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
@@ -110,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()
         })
 

cli/src/api/apiSession.ts

@@ -748,6 +748,21 @@ export class ApiSessionClient extends EventEmitter {
         })
     }
 
+    /**
+     * tiann/hapi#913: wait until any pending `update-metadata` writes have
+     * been acked by the hub (or the timeout elapses). `updateMetadata` is
+     * fire-and-forget at the call site because it's invoked on the hot path
+     * for every turn; this helper lets the few callers who actually need
+     * durability — fresh ACP session-id pre-registration is the canonical
+     * case — synchronously gate on persistence without changing every
+     * caller's signature.
+     *
+     * Returns true when the lock drained, false when the timeout fired.
+     */
+    async flushMetadata(timeoutMs: number = 5_000): Promise<boolean> {
+        return await this.drainLock(this.metadataLock, timeoutMs)
+    }
+
     async flush(options?: { timeoutMs?: number }): Promise<void> {
         const deadlineMs = Date.now() + (options?.timeoutMs ?? 5_000)