fix(cli): runner-spawned children use 'Stopped by runner' as default archive reason

Addresses bot review of tiann#923: with the tiann#914 default-archiveReason flip to
'Hub restart', runner-driven SIGTERM paths (`hapi runner stop-session`,
webhook-timeout cleanup at run.ts:587, orphan-cleanup at run.ts:267) all
mislabel as 'Hub restart' which is also inaccurate audit-trail noise.

Smallest defensible change: parameterise the lifecycle default via
HAPI_DEFAULT_ARCHIVE_REASON env, and have the runner set
'Stopped by runner' on spawn. Terminal-launched sessions (no runner
parent, no env var) still default to 'Hub restart' since hub-restart
cascade documented at tiann#915 is the most plausible SIGTERM source for
those. Explicit overrides via setArchiveReason (KillSession RPC, SIGINT
Ctrl-C, markCrash uncaught exception) still win.

Two new unit tests cover the env-var default and the override
precedence.

Refs tiann#914.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: heavygee

cli/src/agent/runnerLifecycle.test.ts

@@ -70,4 +70,58 @@ describe('createRunnerLifecycle archiveReason defaults (tiann/hapi#914)', () =>
             archiveReason: 'Session crashed'
         })
     })
+
+    // tiann/hapi#914 review feedback: runner-spawned children should not
+    // get the 'Hub restart' label when the runner SIGTERMs them via
+    // stop-session, webhook-timeout cleanup, or orphan cleanup. The runner
+    // sets HAPI_DEFAULT_ARCHIVE_REASON on the child's spawn env so the
+    // default reason is path-accurate without changing every kill site.
+    it('honours HAPI_DEFAULT_ARCHIVE_REASON env as the default reason', async () => {
+        const session = makeFakeSession()
+        const original = process.env.HAPI_DEFAULT_ARCHIVE_REASON
+        process.env.HAPI_DEFAULT_ARCHIVE_REASON = 'Stopped by runner'
+        try {
+            const lifecycle = createRunnerLifecycle({
+                session: session as unknown as Parameters<typeof createRunnerLifecycle>[0]['session'],
+                logTag: 'test'
+            })
+
+            await lifecycle.cleanup()
+
+            expect(session.metadataWrites[0]).toMatchObject({
+                archiveReason: 'Stopped by runner'
+            })
+        } finally {
+            if (original === undefined) {
+                delete process.env.HAPI_DEFAULT_ARCHIVE_REASON
+            } else {
+                process.env.HAPI_DEFAULT_ARCHIVE_REASON = original
+            }
+        }
+    })
+
+    it('setArchiveReason still wins over HAPI_DEFAULT_ARCHIVE_REASON', async () => {
+        const session = makeFakeSession()
+        const original = process.env.HAPI_DEFAULT_ARCHIVE_REASON
+        process.env.HAPI_DEFAULT_ARCHIVE_REASON = 'Stopped by runner'
+        try {
+            const lifecycle = createRunnerLifecycle({
+                session: session as unknown as Parameters<typeof createRunnerLifecycle>[0]['session'],
+                logTag: 'test'
+            })
+
+            lifecycle.setArchiveReason('User terminated')
+            await lifecycle.cleanup()
+
+            expect(session.metadataWrites[0]).toMatchObject({
+                archiveReason: 'User terminated'
+            })
+        } finally {
+            if (original === undefined) {
+                delete process.env.HAPI_DEFAULT_ARCHIVE_REASON
+            } else {
+                process.env.HAPI_DEFAULT_ARCHIVE_REASON = original
+            }
+        }
+    })
 })

cli/src/agent/runnerLifecycle.ts

@@ -23,16 +23,24 @@ export type RunnerLifecycle = {
 
 export function createRunnerLifecycle(options: RunnerLifecycleOptions): RunnerLifecycle {
     let exitCode = 0
-    // 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:
+    // tiann/hapi#914: default reason is parent-driven SIGTERM (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, `kill <pid>` from host) keeps
-    // the default and is correctly labelled 'Hub restart' on the audit trail.
-    let archiveReason = 'Hub restart'
+    //
+    // The default is parameterised via `HAPI_DEFAULT_ARCHIVE_REASON` so that
+    // the runner (cli/src/runner/run.ts) can label children it spawns with
+    // 'Stopped by runner' — runner-driven SIGTERMs (stop-session command,
+    // webhook-timeout cleanup, orphan cleanup) are NOT hub restarts, and
+    // hub-restart cascades for runner-spawned children also flow through
+    // the runner in production. Terminal-launched sessions (no runner
+    // parent) fall back to 'Hub restart' since the most plausible
+    // out-of-band SIGTERM source for those is the systemd hub-restart
+    // cascade documented at tiann/hapi#915.
+    let archiveReason = process.env.HAPI_DEFAULT_ARCHIVE_REASON || 'Hub restart'
     let sessionEndReason: SessionEndReason = 'terminated'
     let cleanupStarted = false
     let cleanupPromise: Promise<void> | null = null

cli/src/runner/run.ts

@@ -456,7 +456,16 @@ export async function startRunner(options: { workspaceRoots?: string[] } = {}):
           stdio: ['ignore', 'pipe', 'pipe'],  // Capture stdout/stderr for debugging
           env: {
             ...process.env,
-            ...extraEnv
+            ...extraEnv,
+            // tiann/hapi#914 review: runner-spawned children get SIGTERMed
+            // by three runner paths (stopSession, webhook-timeout cleanup,
+            // orphan cleanup). All three are runner actions, not hub
+            // restarts and not user terminations. Override the lifecycle
+            // default so audit-trail archives accurately attribute to the
+            // runner. Genuine user actions (web Archive via KillSession
+            // RPC, terminal Ctrl-C via SIGINT) still override to
+            // 'User terminated' in runnerLifecycle.
+            HAPI_DEFAULT_ARCHIVE_REASON: 'Stopped by runner'
           }
         });