brl-subagent 2.5.0 → 2.5.1

package/src/runner.ts

@@ -34,7 +34,16 @@ import {
 	SUBAGENT_ABORTED_MESSAGE,
 	SUBAGENT_SIGNAL_KILLED_MESSAGE,
 } from "./types";
-import { escalateKill, type EscalationTarget } from "./kill-escalation";
+import {
+	escalateKill,
+	pidTarget,
+	processTarget,
+	supportsProcessGroupKill,
+	groupTarget,
+	type EscalationTarget,
+	type SignalGuard,
+} from "./kill-escalation";
+import { findByMarker, pidAlive, pidHasMarker, pidGone, groupHasMembers, killProcessGroup } from "./proc";
 import { getSafeEnv, DEPTH_ENV_KEY, CHILD_MARKER_ENV_KEY, sanitizeErrorMessage } from "./sanitize";
 import type { Logger } from "./logging";
 import type { Intercom } from "./messaging";
@@ -83,7 +92,10 @@ export function activeChildCount(): number {
 
 /** True once the child has really exited (a signal was delivered is not enough). */
 function childExited(proc: ChildProcess): boolean {
-	return proc.exitCode !== null || proc.signalCode !== null;
+	// `!= null` (not `!== null`): a real ChildProcess uses `null` before exit, but
+	// narrow test doubles omit the field (`undefined`), which must also read as
+	// "not exited" so the liveness re-check does not skip a live child's TERM.
+	return proc.exitCode != null || proc.signalCode != null;
 }
 
 /** Default real sleep between SIGTERM and the escalation re-check. */
@@ -121,41 +133,198 @@ export function __setEscalationTimingForTest(timing?: { graceMs?: number; pollMs
 	escalationTiming.pollMs = timing?.pollMs ?? SIGKILL_POLL_MS;
 }
 
+/**
+ * #322: TEST-ONLY registry seam. Register an arbitrary child (and optional
+ * marker) under a fresh unique spawn token so a test can drive the shutdown reap
+ * in isolation — with no `runSubagent` in the picture, the run's own exit sweep
+ * cannot be the killer and the reap's death assertion is attributable.
+ *
+ * Returns a deregister function that deletes that token. Throws outside the
+ * test environment (same runtime gate as `__setEscalationTimingForTest`): the
+ * registry is production state, and a stray import must never be able to point
+ * a real reap at a process the runner did not spawn.
+ */
+export function __registerActiveChildForTest(proc: ChildProcess, marker?: string): () => void {
+	if (!isTestEnvironment()) {
+		throw new Error(
+			"__registerActiveChildForTest() is test-only and cannot run in production.",
+		);
+	}
+	const token = `spawn-${process.pid}-${++spawnTokenSeq}`;
+	activeChildren.set(token, { proc, marker });
+	return () => {
+		activeChildren.delete(token);
+	};
+}
+
 /**
  * Escalation target for one spawned child. `verifyDeath` defaults to the
- * REAL-exit check (`childExited`) and may be overridden per site. The abort and
- * timeout paths must use the real check (issue #303): `child.killed` flips
- * when a signal is *sent*, not when the process dies, so gating the SIGKILL on
- * it would let a SIGTERM-ignoring child survive the escalation.
+ * REAL-exit check (`childExited`) AND — on a group target — group emptiness, and
+ * may be overridden per site. The abort and timeout paths must use the real
+ * check (issue #303): `child.killed` flips when a signal is *sent*, not when the
+ * process dies, so gating the SIGKILL on it would let a SIGTERM-ignoring child
+ * survive the escalation.
+ *
+ * #299 Option B D2: on POSIX the target ALSO signals the child's process group
+ * (best-effort) and unconditionally SIGKILLs it after the grace window
+ * (`groupTarget`), so an env-scrubbed grandchild — invisible to the marker scan
+ * — dies with the child on abort/timeout/shutdown. The direct `proc.kill`
+ * signal is never replaced. On Windows (`supportsProcessGroupKill()` false,
+ * D6) this is exactly today's direct-only target.
+ *
+ * #299 review (Major 1 + Major 2):
+ *   - The tracked `ChildProcess` handle is its OWN identity class — it is not
+ *     marker-derived, so there is no marker guard here; terminate/forceKill stay
+ *     unconditional (D5). We add only a TERMINATE-time liveness re-check (skip
+ *     when the child is already confirmed exited). The force-kill window is
+ *     in-session and µs-class: the live handle cannot be reused by a foreign
+ *     process while we hold it.
+ *   - Major 2: the default death check becomes `childExited(proc) &&
+ *     groupHasMembers(pid) === false` so a descendant still cleaning up keeps the
+ *     grace window open. #299 fix A.2 makes that reader THREE-state: only a
+ *     POSITIVELY empty group (`false`) permits the early exit; an UNKNOWN
+ *     inspection (`undefined`) keeps the target alive. When /proc is unavailable
+ *     as a PLATFORM (`groupHasMembers` false) it
+ *     degrades to child-exited liveness — the documented platform boundary.
  */
-function childTarget(proc: ChildProcess, verifyDeath: () => boolean = () => childExited(proc)): EscalationTarget {
+function childTarget(proc: ChildProcess, verifyDeath?: () => boolean): EscalationTarget {
+	const pid = proc.pid ?? 0;
+	const killDirect = (_pid: number, signal: NodeJS.Signals): void => {
+		proc.kill(signal);
+	};
+	const useGroup = supportsProcessGroupKill() && proc.pid !== undefined;
+	const base = useGroup
+		? groupTarget(pid, killDirect, killProcessGroup, pidAlive, groupHasMembers)
+		: pidTarget(pid, killDirect, pidAlive);
+	const defaultVerifyDeath = useGroup
+		? () => childExited(proc) && groupHasMembers(pid) === false
+		: () => childExited(proc);
 	return {
+		...base,
 		terminate: () => {
-			proc.kill("SIGTERM");
+			// #299 review Major 1: an already-exited child is not signaled again.
+			if (childExited(proc)) return;
+			base.terminate();
 		},
-		forceKill: () => {
-			proc.kill("SIGKILL");
-		},
-		verifyDeath,
+		verifyDeath: verifyDeath ?? defaultVerifyDeath,
 	};
 }
 
+/** Send a signal to a pid; the ONE production kill primitive for marker sweeps. */
+const killPid = (pid: number, signal: NodeJS.Signals): void => {
+	process.kill(pid, signal);
+};
+
+/**
+ * #299 Option A: union the marker-carrying descendants of the given markers into
+ * pid-based escalation targets. A spawned child stamps its own subprocesses with
+ * the same per-run marker env, so `findByMarker` surfaces grandchildren the
+ * `ChildProcess`-based targets cannot see. `excludePids` drops anything already
+ * targeted (the tracked direct children). Markers are per-run UUIDs, so a sweep
+ * cannot reach another run's tree.
+ *
+ * #299 review Major 1: every pid here is marker-derived, so its targets carry a
+ * `SignalGuard` that re-reads the LIVE marker (`pidHasMarker`) immediately before
+ * each signal. A pid that exited and was reused by a foreign process no longer
+ * carries the marker, so both the group and direct signals are SKIPPED and the
+ * skip is logged — never an unverified signal. `log` is optional (the sweep and
+ * shutdown calls pass their logger).
+ */
+function collectMarkerTargets(
+	markers: Iterable<string | undefined>,
+	excludePids: ReadonlySet<number>,
+	log?: Logger,
+): { pids: number[]; targets: EscalationTarget[] } {
+	const seen = new Set<number>();
+	const pids: number[] = [];
+	const targets: EscalationTarget[] = [];
+	// D3 (#299): a marker-verified pid is identity proof, so its group is also
+	// signaled best-effort. When the carrier is a group leader (the spawned child
+	// or a descendant that `setsid`'d) `-pid` reaches its env-scrubbed
+	// descendants; when it is merely a member, `-pid` is ESRCH and the direct
+	// signal still lands.
+	const groupKill = supportsProcessGroupKill() ? killProcessGroup : undefined;
+	for (const marker of markers) {
+		if (!marker) continue;
+		for (const pid of findByMarker(marker)) {
+			if (!Number.isInteger(pid) || pid <= 0) continue;
+			if (excludePids.has(pid) || seen.has(pid)) continue;
+			seen.add(pid);
+			pids.push(pid);
+			const guard: SignalGuard = {
+				isOwn: (targetPid) => pidHasMarker(targetPid, marker),
+				isGone: (targetPid) => pidGone(targetPid),
+				onSkip: (targetPid, signal, phase) =>
+					log?.warn("Skipped marker signal: pid no longer carries the run marker", {
+						pid: targetPid,
+						signal,
+						phase,
+						marker,
+					}),
+			};
+			targets.push(processTarget(pid, killPid, pidAlive, groupKill, groupHasMembers, guard));
+		}
+	}
+	return { pids, targets };
+}
+
+/**
+ * #299 Option A: kill every pid still carrying `marker` once the direct child has
+ * exited — the marker-inheriting descendants (grandchildren) that would
+ * otherwise survive the run in-session (probe 1c). No marker / no match is a
+ * no-op. Uses the same SIGTERM → grace → SIGKILL window (and test-only timing
+ * seam) as every other kill path; never rejects.
+ */
+async function sweepMarkerChildren(
+	marker: string | undefined,
+	excludePids: ReadonlySet<number>,
+	log?: Logger,
+): Promise<number[]> {
+	const { pids, targets } = collectMarkerTargets([marker], excludePids, log);
+	if (targets.length === 0) return [];
+	try {
+		await escalateKill(targets, {
+			graceMs: escalationTiming.graceMs,
+			pollMs: escalationTiming.pollMs,
+			sleep: realSleep,
+		});
+		log?.info("Swept leftover marker children after run exit", { marker, pids });
+	} catch (err) {
+		// A sweep must never block the run result from settling.
+		log?.warn("Marker sweep failed after run exit", { marker, error: String(err) });
+	}
+	return pids;
+}
+
 /**
  * Terminate every registered in-flight child: SIGTERM all, wait up to the shared
  * grace period (returning as soon as every child is dead — B4), then SIGKILL any
  * survivor. Returns the pids targeted. Safe to call when nothing is in flight.
+ *
+ * #299 Option A: each tracked entry's marker is also swept (`findByMarker`),
+ * because a marker-carrying grandchild is invisible to the `ChildProcess` handle
+ * and would otherwise survive a clean session_shutdown (probe 1b). Marker pids
+ * are deduped against the tracked pids and share the ONE escalation window, so
+ * the whole inherited tree dies together.
  */
 export async function reapActiveChildren(log?: Logger): Promise<number[]> {
 	const pids: number[] = [];
+	const trackedPids = new Set<number>();
 	const targets: EscalationTarget[] = [];
+	const markers: Array<string | undefined> = [];
 	for (const [token, entry] of activeChildren) {
 		if (entry.proc.pid === undefined) {
 			activeChildren.delete(token);
 			continue;
 		}
+		trackedPids.add(entry.proc.pid);
 		pids.push(entry.proc.pid);
 		targets.push(childTarget(entry.proc));
+		markers.push(entry.marker);
 	}
+	const swept = collectMarkerTargets(markers, trackedPids, log);
+	pids.push(...swept.pids);
+	targets.push(...swept.targets);
 	if (targets.length === 0) return [];
 
 	await escalateKill(targets, {
@@ -955,6 +1124,19 @@ ${msgBlock}`;
 					shell: false,
 					stdio: ["ignore", "pipe", "pipe"],
 					env: getSafeEnv(hasEnvOverrides ? envOverrides : undefined), // F2: Environment isolation + depth tracking
+					// #299 Option B D1: POSIX only — the child becomes its OWN session and
+					// process-group leader (`pgid == pid`), so every kill path can signal
+					// the whole tree (including env-scrubbed descendants) with
+					// `process.kill(-pid, sig)`. No `unref()`: we track the child, and the
+					// boot scan is its recovery path if the conductor crashes. Boundaries:
+					// (a) an env-scrubbed subtree whose leader is already dead before any
+					// sweep stays unreachable safely (only a surviving marker carrier is
+					// swept); (b) a descendant that calls `setsid` leaves the group by
+					// definition; (c) macOS has no /proc, so the boot scan is unchanged
+					// while the in-session group kill still works; (d) detached children no
+					// longer receive terminal-generated signals — the boot reap is their
+					// recovery path. Windows passes `false` (D6), exactly today's behavior.
+					detached: supportsProcessGroupKill(),
 				});
 
 				// Option B U1: register the child for shutdown reap. Keyed by the
@@ -982,6 +1164,24 @@ ${msgBlock}`;
 					result.stderr += data.toString();
 				});
 
+				// #299 Option A: sweep on `exit`, not `close`. `exit` is where the direct
+				// child is confirmed dead; `close` can be delayed indefinitely when a
+				// grandchild inherited the child's stdio and keeps the pipes open. Killing
+				// the leftover marker tree here also releases those pipes so the run can
+				// settle. Success, timeout, and abort all terminate the direct child and so
+				// all funnel through this ONE exit sweep (probe 1c). The per-run marker
+				// keeps it foreign-tree-safe; already-tracked concurrent children are
+				// excluded because two children may legitimately share a marker (B5).
+				let sweepPromise: Promise<number[]> | undefined;
+				proc.on("exit", () => {
+					const excludePids = new Set<number>();
+					for (const entry of activeChildren.values()) {
+						if (entry.proc.pid !== undefined) excludePids.add(entry.proc.pid);
+					}
+					if (proc.pid !== undefined) excludePids.add(proc.pid);
+					sweepPromise = sweepMarkerChildren(childMarker, excludePids, log);
+				});
+
 				proc.on("close", (code, signal) => {
 					activeChildren.delete(registryToken);
 					if (buffer.trim()) {
@@ -1003,7 +1203,10 @@ ${msgBlock}`;
 						result.errorMessage = `${SUBAGENT_SIGNAL_KILLED_MESSAGE} (${signal ?? "unknown"})`;
 						log?.warn("Subagent killed by external signal", { signal, pid: proc.pid });
 					}
-					resolve(result.exitCode);
+					// #299 Option A: settle only AFTER the exit sweep finished, so no
+					// in-session marker tree outlives the run (probe 1c). Result semantics
+					// above are untouched.
+					void (sweepPromise ?? Promise.resolve([])).then(() => resolve(result.exitCode));
 				});
 
 				proc.on("error", (err) => {

package/src/session-manager.ts

@@ -1,8 +1,8 @@
 // Purpose: Background execution: SDK sessions (`createAgentSession`), agent records, timeouts, steering, and settle paths.
 import { randomUUID } from 'crypto';
-import { join } from 'path';
-import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync } from 'fs';
-import type { BackgroundAgent, AgentStatus, GitMode, SubagentResult, SubagentRun, ThinkingLevel, SubagentToolOptions, UsageStats, ErrorCategory } from './types';
+import { basename, dirname, join, resolve } from 'path';
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, rmSync } from 'fs';
+import type { BackgroundAgent, AgentStatus, GitMode, RecoveryMode, SubagentResult, SubagentRun, ThinkingLevel, SubagentToolOptions, UsageStats, ErrorCategory } from './types';
 import { EMPTY_USAGE, classifyError, classifyTerminalOutcome, isProviderError, coherentFailureReason, SUBAGENT_ABORTED_MESSAGE } from './types';
 import { accumulateUsage } from './runner';
 import * as eventBus from './event-bus';
@@ -78,6 +78,90 @@ function ensureStorageDir(): void {
   mkdirSync(STORAGE_DIR, { recursive: true, mode: 0o700 });
 }
 
+// ---------------------------------------------------------------------------
+// Option B U2 (D1/D2): file-backed background sessions + retention.
+//
+// Background runs are persisted by the SDK's SessionManager-created files, one
+// per-run directory BESIDE the agent records (`.pi/subagents/sessions/<id>/`).
+// The directory NAME is the run→file mapping — no new record field is needed,
+// and no resume/re-drive/UI logic lives here (that is U3/U4). The per-run dir is
+// removed when the run reaches a TERMINAL state; a run marked interrupted (U1's
+// boot scan, D3) KEEPS its file until it is resolved by a later unit.
+//
+// Boundaries (stated once, referenced by the PR): no resume (U4); no UI/notice/
+// abandon (U3); background is in-process only; a session file has a single
+// writer (the settled run's own process).
+//
+// D5 measurement (one week of use):
+//   du -sh .pi/subagents/sessions
+//   find .pi/subagents/sessions -name '*.jsonl' | wc -l
+// The expected steady state is EMPTY between runs (terminal runs prune their
+// dir) plus one dir per currently-interrupted run — a non-empty count of
+// settled runs means a prune path regressed. There is no runtime metric.
+// ---------------------------------------------------------------------------
+
+/** Subdirectory of the agent-record store that holds per-run session dirs. */
+const SESSIONS_SUBDIR = 'sessions';
+
+/**
+ * The per-run session directory for `id`: `<STORAGE_DIR>/sessions/<id>`.
+ * The id is validated first — this path is fed to SessionManager.create() and
+ * to rmSync(), so a traversal id must never reach either.
+ */
+export function backgroundSessionDir(id: string): string {
+  assertSafeAgentId(id);
+  return join(STORAGE_DIR, SESSIONS_SUBDIR, id);
+}
+
+/**
+ * Remove ONE per-run session directory. Defensive by construction: the target
+ * must look like `<...>/sessions/<id>` (basename === id, parent basename ===
+ * 'sessions') before rmSync runs, so a caller can never delete a path outside
+ * the sessions tree. Idempotent (force: true); best-effort (never throws).
+ */
+function pruneSessionDir(id: string, dir: string): void {
+  try {
+    assertSafeAgentId(id);
+  } catch {
+    log.error(`Refusing to prune session dir for invalid id: ${id}`);
+    return;
+  }
+  const target = resolve(dir);
+  if (basename(target) !== id || basename(dirname(target)) !== SESSIONS_SUBDIR) {
+    log.error(`Refusing to prune session dir outside ${SESSIONS_SUBDIR}/: ${target}`);
+    return;
+  }
+  try {
+    rmSync(target, { recursive: true, force: true });
+  } catch (err) {
+    // Pruning is hygiene — it must never break execution or a settle path.
+    log.warn(`Failed to prune session dir for ${id}`, {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+/**
+ * U2 (D2): remove the persisted session for a finalized/abandoned background
+ * run. Validated (throws on an unsafe id) and idempotent — a missing directory
+ * is a success. Exposed for U3's abandon action to reuse; the internal settle
+ * path prunes the CAPTURED directory instead so a mid-run STORAGE_DIR change
+ * (tests swap it per case) can never mis-target.
+ *
+ * U3 (D5) documented boundary — abandon after a STORAGE_DIR change: this
+ * PUBLIC helper recomputes the root from the CURRENT STORAGE_DIR, so if the
+ * root moved between the spawn and the abandon it prunes the new root (a
+ * no-op when nothing lives there) and leaves the old-root session dir behind
+ * as debris. That is prod-safe today (only tests swap the root; production
+ * uses one root per process), so U3 does NOT try to track the captured dir
+ * across sessions — the run's `_sessionFile` is live-only process state and is
+ * not persisted (D4). Debris, if any, is bounded and inspectable under the old
+ * root.
+ */
+export function pruneBackgroundSession(id: string): void {
+  pruneSessionDir(id, backgroundSessionDir(id));
+}
+
 /**
  * Persist agent record to disk
  */
@@ -95,8 +179,10 @@ function persistAgent(agent: BackgroundAgent): void {
   const filePath = join(STORAGE_DIR, `${agent.id}.json`);
   // Strip live/non-serializable fields before stringify — `_sessionRef` holds the
   // ENTIRE live pi session graph (1.4MB+ for an empty session, and uninitialized
-  // getters like Theme can make JSON.stringify throw).
-  const { _sessionRef, ...persistable } = agent;
+  // getters like Theme can make JSON.stringify throw). `_sessionFile` (U2) is the
+  // on-disk session path — live-only bookkeeping for precise pruning, never a
+  // persisted record field (D4).
+  const { _sessionRef, _sessionFile, ...persistable } = agent;
   try {
     // F6 (issue #29): records contain task, error, result.messages (full
     // conversation) and finalOutput — write owner-only (0o600) so other local
@@ -413,6 +499,10 @@ export async function spawnBackgroundSession(
     dispatchId?: string;
     resumeOf?: string;
     attempt?: number;
+    /** Option B U3 (D4): recovery posture at dispatch — snapshotted onto the
+     *  agent record + run entry so the boot notice reads the posture the run
+     *  was actually dispatched under. Absent reads as "offer". */
+    recoveryPosture?: RecoveryMode;
   }
 ): Promise<BackgroundAgent> {
   // Serialize access to pi API to prevent concurrent import races
@@ -442,8 +532,16 @@ export async function spawnBackgroundSession(
     }
   }
   
-  // Create session manager for this background agent
-  const sessionManager = SessionManager.inMemory(effectiveCwd);
+  // Create the session manager for this background agent. U2 (D1): an explicit
+  // per-run sessionDir is REQUIRED — `inMemory` persists nothing (no post-hoc
+  // inspection, no U4 resume) and the SDK default (`~/.pi/agent/sessions/<cwd-key>/`,
+  // passed as `undefined`) would scatter our runs into the global store. The
+  // directory lives beside the agent record: `.pi/subagents/sessions/<id>/`.
+  const sessionManager = SessionManager.create(effectiveCwd, backgroundSessionDir(id));
+  // Capture the exact path the SDK will write. The settle path derives the
+  // prune target from THIS (not from a freshly-computed STORAGE_DIR path) so a
+  // change of STORAGE_DIR between spawn and settle cannot mis-target the delete.
+  const sessionFile: string | undefined = sessionManager.getSessionFile();
   const settingsManager = SettingsManager.create(effectiveCwd);
 
   // E20: Inject the subagent prompt into the session's system prompt.
@@ -546,6 +644,11 @@ export async function spawnBackgroundSession(
     resumeOf: params.resumeOf,
     attempt,
     owner,
+    // Option B U3 (D4): per-run recovery posture snapshot. Additive — absent
+    // reads as "offer" via `runRecoveryPosture`/the notice collector.
+    recoveryPosture: params.recoveryPosture,
+    // U2: live-only pointer to this run's session file (stripped before persist).
+    _sessionFile: sessionFile,
   };
   
   agents.set(id, agent);
@@ -575,6 +678,7 @@ export async function spawnBackgroundSession(
     resumeOf: params.resumeOf,
     attempt,
     owner,
+    recoveryPosture: params.recoveryPosture,
   };
   persistRunRecord(pi, run, "background");
 
@@ -582,6 +686,15 @@ export async function spawnBackgroundSession(
   // every terminal branch that flips agent.status also finalizes the run entry
   // ("done"/"failed"). The guard keeps the entry single-finalized even when a
   // settle handler throws after finalizing (markTerminalBestEffort catch-all).
+  //
+  // U2 (D2) retention: this is the SINGLE terminal choke point for a background
+  // run — git-setup refusal, a synchronous prompt throw, the .then completed /
+  // provider-failed / aborted branches, the .catch stopped / failed branches and
+  // the markTerminalBestEffort catch-all ALL land here exactly once (the
+  // runFinalized guard). Pruning here therefore covers every settle path. The
+  // index.ts poller crash notices are NOT settlements (they flip only the live
+  // UI state and leave the run/agent record to this settle); an interrupted run
+  // (U1 boot-scan mark) never reaches this function and KEEPS its file (D3).
   let runFinalized = false;
   const finalizeRunEntry = (
     status: "done" | "failed",
@@ -590,6 +703,15 @@ export async function spawnBackgroundSession(
   ): void => {
     if (runFinalized) return;
     runFinalized = true;
+    // U2 (D2): drop the persisted session now that the run is terminal. Done
+    // FIRST (before the run-entry write below) so a persist throw cannot leave
+    // a terminal run's session file behind. Interrupted runs keep theirs.
+    if (!agent.interruptedAt) {
+      pruneSessionDir(
+        id,
+        agent._sessionFile ? dirname(agent._sessionFile) : backgroundSessionDir(id),
+      );
+    }
     const usage = agent.result?.usage ?? EMPTY_USAGE;
     const finalOutput = agent.finalOutput ?? "";
     // Issue #179 (D1/D2): the classifier's explicit category wins (it knows the

package/src/state.ts

@@ -17,6 +17,7 @@ import type {
 	ThinkingLevel,
 	ApprovalMode,
 	CompletionNotifyMode,
+	RecoveryMode,
 	CircuitBreakerState,
 	Priority,
 } from "./types";
@@ -24,12 +25,15 @@ import type { TranscriptMessage } from "./transcript-tail";
 import {
 	isSubagentStateShape,
 	isSubagentRunShape,
+	isInterruptedRun,
 	CUSTOM_ENTRY_TYPES,
 	MAX_RUN_HISTORY_ENTRIES,
 	DEFAULT_MAX_SUBAGENT_DEPTH,
 	DEFAULT_SESSION_COST_LIMIT,
 	DEFAULT_COMPLETION_NOTIFY,
 	COMPLETION_NOTIFY_MODES,
+	DEFAULT_RECOVERY,
+	RECOVERY_MODES,
 	MAX_CONSECUTIVE_FAILURES,
 	CIRCUIT_BREAKER_RESET_MS,
 	CIRCUIT_DEGRADED_THINKING,
@@ -107,7 +111,10 @@ export function resolveTerminalRunEntry(
  * renders every run twice and the spawn row shows a stale "running" forever.
  * This collapses each id to its terminal-preferred entry via the ONE shared
  * rule (`resolveTerminalRunEntry`). Runs still in flight (spawn entry, no
- * terminal entry yet) are omitted: live state belongs to the monitor.
+ * terminal entry yet) are omitted: live state belongs to the monitor. U3 (D1)
+ * carves ONE exception — an INTERRUPTED run (running + `interruptedAt`, per
+ * `isInterruptedRun`) is surfaced, because the human must see it to recover or
+ * abandon it.
  *
  * Ordering is preserved from `entries`; callers pass `getRunEntries` output
  * (newest-first via `cleanupRuns`), which stays the single ordering authority —
@@ -120,11 +127,28 @@ export function collapseRunsForHistory(entries: SubagentRun[]): SubagentRun[] {
 		if (seen.has(entry.id)) continue;
 		seen.add(entry.id);
 		const resolved = resolveTerminalRunEntry(entries, entry.id);
-		if (resolved && resolved.status !== "running") display.push(resolved);
+		if (resolved && (resolved.status !== "running" || isInterruptedRun(resolved))) {
+			display.push(resolved);
+		}
 	}
 	return display;
 }
 
+/**
+ * U3 (D3): the retry surface's candidate projection — settled FAILED runs plus
+ * unresolved INTERRUPTED runs, one row per id. Built on the SAME
+ * terminal-preferred collapse the history list uses, so the two surfaces can
+ * never disagree about which record represents a run. The retry offer reuses
+ * the existing `retryRunId` machinery (recorded params restored by
+ * `resolveRetryParams`), so an interrupted run is recoverable without any new
+ * delegate_task parameter.
+ */
+export function retryableRuns(entries: SubagentRun[]): SubagentRun[] {
+	return collapseRunsForHistory(entries).filter(
+		(r) => r.status === "failed" || isInterruptedRun(r),
+	);
+}
+
 // ---------------------------------------------------------------------------
 // SessionState — session-bound mutable state
 // ---------------------------------------------------------------------------
@@ -196,6 +220,7 @@ export class SessionState {
 			gitMode: "none",
 			approvalMode: "writes",
 			completionNotify: DEFAULT_COMPLETION_NOTIFY,
+			recovery: DEFAULT_RECOVERY,
 			maxHistoryEntries: MAX_RUN_HISTORY_ENTRIES,
 			sessionCostLimit: DEFAULT_SESSION_COST_LIMIT,
 			perTaskCostEstimate: 0,
@@ -221,6 +246,7 @@ export class SessionState {
 			gitMode: this.config.gitMode,
 			approvalMode: this.config.approvalMode,
 			completionNotify: this.config.completionNotify,
+			recovery: this.config.recovery,
 			maxHistoryEntries: this.config.maxHistoryEntries,
 			sessionCostLimit: this.config.sessionCostLimit,
 			perTaskCostEstimate: this.config.perTaskCostEstimate,
@@ -288,6 +314,9 @@ export class SessionState {
 			COMPLETION_NOTIFY_MODES.includes(data.completionNotify as CompletionNotifyMode)
 				? data.completionNotify
 				: DEFAULT_COMPLETION_NOTIFY;
+		this.config.recovery = RECOVERY_MODES.includes(data.recovery as RecoveryMode)
+			? data.recovery
+			: DEFAULT_RECOVERY;
 		if (data.maxHistoryEntries !== undefined) this.config.maxHistoryEntries = data.maxHistoryEntries;
 		if (data.sessionCostLimit !== undefined) this.config.sessionCostLimit = data.sessionCostLimit;
 		if (data.perTaskCostEstimate !== undefined) this.config.perTaskCostEstimate = data.perTaskCostEstimate;
@@ -577,6 +606,7 @@ export class SessionState {
 		this.config.gitMode = "none";
 		this.config.approvalMode = "writes";
 		this.config.completionNotify = DEFAULT_COMPLETION_NOTIFY;
+		this.config.recovery = DEFAULT_RECOVERY;
 		this.config.maxHistoryEntries = MAX_RUN_HISTORY_ENTRIES;
 		this.config.sessionCostLimit = DEFAULT_SESSION_COST_LIMIT;
 		this.config.perTaskCostEstimate = 0;

package/src/tui-format.ts

@@ -7,7 +7,8 @@
  * without a TUI harness.
  */
 
-import { formatTokens } from "./types";
+import { formatTokens, isInterruptedRun } from "./types";
+import type { SubagentRun } from "./types";
 
 /** Braille spinner frames, indexed by Math.floor(now / 150) % 10. */
 export const LIVE_SPINNER_FRAMES: readonly string[] = [
@@ -50,3 +51,58 @@ export function formatLiveRowDim(
 ): string {
 	return `  [${id.slice(0, 8)}]  \u2191${formatTokens(usage.input)} \u2193${formatTokens(usage.output)}  ${elapsedStr}`;
 }
+
+/**
+ * Display name for a Run History / retry-surface row, shared by BOTH surfaces
+ * so they can never name the same run differently (Fix B item 5). Explicit
+ * label wins, else the task truncated to 60 chars, else the short id — the last
+ * case being a task-less foreground-interrupted row (no task persisted).
+ */
+export function runDisplayName(run: Pick<SubagentRun, "id" | "label" | "task">): string {
+	return run.label || run.task.slice(0, 60) || run.id.slice(0, 8);
+}
+
+// ---------------------------------------------------------------------------
+// U3 (D1/D3): Run History / retry-surface row projection
+// ---------------------------------------------------------------------------
+
+/**
+ * The human status of a Run History row. Keys on `isInterruptedRun` FIRST, so a
+ * run marked interrupted renders as `interrupted` and NEVER falls through to its
+ * raw `\"running\"` status (D1). The raw status is only consulted for an
+ * unmarked record.
+ */
+export type RunHistoryStatus = "interrupted" | "running" | "done" | "failed";
+
+export function runHistoryStatus(run: SubagentRun): RunHistoryStatus {
+	if (isInterruptedRun(run)) return "interrupted";
+	if (run.status === "done" || run.status === "failed") return run.status;
+	return "running";
+}
+
+/** Human label for a Run History row's status. */
+export function runHistoryStatusLabel(run: SubagentRun): string {
+	switch (runHistoryStatus(run)) {
+		case "interrupted":
+			return "Interrupted";
+		case "done":
+			return "Completed";
+		case "failed":
+			return "Failed";
+		default:
+			return "Running";
+	}
+}
+
+/**
+ * The offer text shown when a retry-surface row is selected. Names the run id
+ * and the `retryRunId` parameter explicitly (D3), so the conductor re-dispatches
+ * the recorded task/params without a new delegate_task parameter.
+ */
+export function buildRetryOfferMessage(run: SubagentRun): string {
+	const statusWord = isInterruptedRun(run) ? "interrupted" : "failed";
+	return (
+		`Ask the LLM to retry: "Use delegate_task with retryRunId: ${run.id} ` +
+		`to retry the ${statusWord} run ${run.id.slice(0, 8)} with its recorded params."`
+	);
+}