brl-subagent 2.5.0 → 2.5.1

package/AGENT.md

@@ -64,12 +64,19 @@ delegation-heavy work.
 - Graph with `dependsOn`: subtasks declare edges; the scheduler runs them in waves.
 - Background + act on wake: spawn a background run, then act when the completion message arrives. Never poll between spawn and wake.
 - Background fan-out: `tasks: [...], background: true` — one background agent per task, one id per task in task order, one wake per agent.
-- retryRunId: pass a failed run's id to re-run it with its recorded task and params; explicit parameters override the originals.
+- retryRunId: pass a failed or **interrupted** run's id to re-run it with its recorded task and params; explicit parameters override the originals. A run interrupted before durable task capture (a pre-enrichment registry entry) has no recorded task — pass `task` explicitly for those.
+
+## Interrupted runs and recovery
+
+- An interrupted run (its conductor died mid-run) stays visible with status **Interrupted** in `/brl-subagent history` and is listed by `/brl-subagent retry` alongside failed runs — including after a crash + fresh boot, where it is reconstructed from the durable per-run registry (plus the background agent record). Recover it with `retryRunId: <run-id>` (recorded params restored), or abandon it from that menu — abandon finalizes the run as stopped, drops its persisted session file, and sends **no** completion wake.
+- **Task persistence (O3):** a foreground/unit run persists its task, label, model, thinking level and full `originalParams` snapshot in the durable registry at dispatch, so after a crash + fresh boot its row shows the real task and `retryRunId` restores the recorded shape — the same 17 fields a same-session retry restores (including `force`; explicit caller values still win). A successful retry retires the source entry so the superseded run is not re-offered at the next boot; a failed retry start leaves it intact and retryable.
+- **Legacy rows:** an entry written before task persistence lacks those fields, so its row carries `(task unavailable)` and `retryRunId` cannot restore a task — pass `task` explicitly on the retry call. A background run keeps its task via its agent record.
+- The **recovery posture** (`/brl-subagent recovery`, default `offer`) controls whether a boot surfaces interrupted runs with one turn-boundary notice; `off` silences it. Nothing is auto-resumed today.
 
 ## Deadlines and retries
 
 - `timeout` (ms) is a **deadline, not a ceiling** — an explicit value is honored as given; 30 minutes is only the default for a background run that passes none. Background expiry aborts the session (the run ends `stopped`); foreground expiry kills the process.
-- `retryOnTimeout` applies to **foreground runs only**. A timed-out background run is not auto-retried: re-dispatch it with `retryRunId` if that is the right call.
+- `retryOnTimeout` applies to **foreground runs only**. A timed-out background run is not auto-retried: re-dispatch it with `retryRunId` if that is the right call. The same applies to an interrupted run — recovery is always an explicit `retryRunId` call, never automatic (auto mode is not yet accepted).
 
 ## Mechanics pointer
 

package/README.md

@@ -2,7 +2,7 @@
 
 > Multi-agent orchestration for [pi](https://github.com/earendil-works/pi) — chain, parallel, and dependency-graph delegation to isolated subagents with per-step model routing, preset-driven tool scoping, thinking-level control, and background execution with live monitoring, real abort, and per-agent timeouts.
 
-**Version:** 2.5.0 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
+**Version:** 2.5.1 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
 
 ---
 
@@ -14,7 +14,7 @@
 - **True background execution** — live monitor, real abort (`stop_subagent`), per-agent timeouts, and a 30-minute default deadline for runs that don't set one. Nothing orphans; nothing leaks.
 - **Preset-driven tool scoping** — every subagent runs with exactly the tools its job needs, restricted by preset or per-call `tools`/`excludeTools`, with auto-route that picks the right preset when you don't.
 - **Templates with slots** — saved, file-backed task templates with `${param}` placeholders for workflows you run again and again.
-- **Safety by default** — task-fence injection protection, sanitized error paths, owner-only persistence, and a 1300+ test suite pinning every contract against the real pi SDK.
+- **Safety by default** — task-fence injection protection, sanitized error paths, owner-only persistence, and a 1500+ test suite pinning every contract against the real pi SDK.
 
 ---
 
@@ -50,6 +50,7 @@ pi remove npm:brl-subagent    # uninstall
 | `/brl-subagent depth` | Set max recursion depth |
 | `/brl-subagent approval` | Set change approval mode |
 | `/brl-subagent completionnotify` | Set completion-push wake (all/failed/off) |
+| `/brl-subagent recovery` | Set recovery posture for interrupted runs (offer/off) |
 | `/brl-subagent costlimit` | Set session cost limit |
 | `/brl-subagent historyentries` | Set max history entries |
 | `/brl-subagent sla` | Configure SLA tracking |
@@ -104,13 +105,15 @@ All settings persist across sessions.
 | `gitMode` | string | — | `'branch'` creates a work branch, captures the diff, and switches back; `'none'` does nothing. Falls back to the configured default. |
 | `approvalMode` | string | — | `auto` / `writes` / `always`. Default is user config (`/brl-subagent approval`). `always` is rejected for background runs. |
 | `force` | boolean | `false` | Dispatch anyway past a capability pre-flight block; the block is downgraded to a warning. |
-| `retryRunId` | string | — | Re-run a previously failed run with its recorded task and params. |
+| `retryRunId` | string | — | Re-run a previously failed or interrupted run with its recorded task and params. |
 | `retryOnTimeout` | boolean | `false` | Retry once if a **foreground** subagent times out. The second timeout is a final failure. Background runs are not auto-retried — re-dispatch with `retryRunId`. |
 
 **Capability pre-flight:** before spawning, the extension checks that the resolved toolset can actually do the task — a run/execute/test/compile/benchmark task with no `bash`, or an exploration task (search/grep/find/list/locate/glob) with none of `find`/`ls`/`grep`/`bash`. Such a dispatch is **rejected** by default; `force: true` downgrades the rejection to a **warning**. `force` never suppresses an `outputFile`-without-write conflict — that stays a hard error. Warnings are surfaced in the returned result in every mode.
 
 **Retries (`retryRunId`):** a retry rebuilds the parameter object from a fixed set of fields, falling back to the original run's recorded values, with explicit values on the retry call winning: `task`, `label`, `model`, `preset`, `systemPrompt`, `inheritSystemPrompt`, `thinkingLevel`, `priority`, `outputFile`, `timeout`, `cwd`, `tools`, `excludeTools`, `noBuiltinTools`, plus the four **execution-shape** fields `background`, `gitMode`, `approvalMode` and `force`.
 
+**Interrupted runs:** a run whose conductor died mid-run is marked interrupted (it keeps its persisted session file) and is surfaced as **Interrupted** in `/brl-subagent history` and in `/brl-subagent retry` — including after a crash + fresh boot, when it is reconstructed from the durable per-run registry (plus the background agent record). Recover one with `retryRunId: <run-id>`, or abandon it from the retry menu — abandon finalizes it as stopped, prunes its session file, and sends no completion wake. A **foreground** run's task is not persisted, so its crashed row shows no task and a retry needs the task supplied explicitly; a background run keeps its task in its agent record. The recovery posture (`/brl-subagent recovery`, default `offer`) controls whether a boot announces interrupted runs with one turn-boundary notice; `off` silences it. Recovery is never automatic — there is no `auto` mode.
+
 **The execution-shape fields are restored, so a retry keeps the original's shape:** retrying a background run re-runs it in the background (with its completion wake), a `gitMode: 'branch'` retry keeps its work branch, an `approvalMode`-constrained retry keeps that gating, and a retry that was capability-blocked keeps its `force`. Passing any of them explicitly on the retry call overrides the recorded value. One qualification on `gitMode`: when neither the record nor the call carries one, the **configured** default still applies — so a user with a global `gitMode: 'branch'` gets a work branch on every retry, and one with the default `'none'` gets none. Do not assume "no work branch" without checking the effective `gitMode`.
 
 **Fan-out origins are the exception.** Parallel/chain/graph units are recorded per unit, and those records deliberately snapshot **no** `background`, so retrying a unit is a **single run in the foreground**. Pass `background: true` explicitly if you want a background retry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brl-subagent",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Subagent delegation for pi — blocking or background runs, chain/parallel/graph modes, presets and task templates, live monitor, and dispatch capability guards.",
   "keywords": [
     "pi-package"
@@ -37,12 +37,12 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^1.1.0",
-    "@earendil-works/pi-ai": "^1.1.0",
-    "@earendil-works/pi-coding-agent": "^1.1.0",
-    "@earendil-works/pi-tui": "^1.1.0",
+    "@earendil-works/pi-agent-core": "^1.2.0",
+    "@earendil-works/pi-ai": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-tui": "^1.2.0",
     "jiti": "^2.7.0",
-    "typebox": "^1.3.34",
+    "typebox": "1.3.27",
     "typescript": "7.0.2",
     "vitest": "^5.0.0"
   },

package/src/history.ts

@@ -16,23 +16,33 @@ import type { ExtensionContext, SessionManager } from "@earendil-works/pi-coding
 // Run pruning — R2: Disk usage policy
 // ---------------------------------------------------------------------------
 
+/**
+ * Order run records NEWEST-FIRST by `startedAt`, without mutating the input.
+ *
+ * The ONE ordering authority for run records (issue #330): sorts by
+ * `startedAt` descending using `Date.parse` comparisons and returns a new
+ * array. `Array.prototype.sort` is stable, so records sharing a `startedAt`
+ * keep their relative order (spawn-before-terminal for a finalized run).
+ */
+export function sortNewestFirst(runs: SubagentRun[]): SubagentRun[] {
+	return [...runs].sort(
+		(a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt),
+	);
+}
+
 /**
  * Prune a SubagentRun array to keep only the newest entries up to maxEntries.
- * Uses startedAt timestamp for ordering (newest first). If maxEntries is 0,
- * returns all entries (no limit). Returns a new array; does not mutate input.
+ * The result is always ordered NEWEST-FIRST by `startedAt` — including the
+ * `maxEntries === 0` unlimited path, which keeps every entry but still sorts.
+ * Returns a new array; does not mutate the input.
  */
 export function cleanupRuns(
 	runs: SubagentRun[],
 	maxEntries: number = MAX_RUN_HISTORY_ENTRIES,
 ): SubagentRun[] {
 	if (runs.length === 0) return [];
-	if (maxEntries === 0) return runs;
-
-	// Always sort newest-first for consistency, even when not truncating
-	const sorted = [...runs].sort(
-		(a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime(),
-	);
-
+	const sorted = sortNewestFirst(runs);
+	if (maxEntries === 0) return sorted;
 	if (sorted.length <= maxEntries) return sorted;
 	return sorted.slice(0, maxEntries);
 }

package/src/index.ts

@@ -51,6 +51,7 @@ import {
 	DEFAULT_PRIORITY,
 	type GitMode,
 	type BackgroundAgent,
+	type RecoveryMode,
 } from "./types";
 import { validateGraph, topologicalSort } from "./scheduler";
 import { resolveTemplate, loadAllTemplates, loadBuiltinTemplates, validateTemplatePresetRefs, extractParamNames } from "./templates";
@@ -74,7 +75,7 @@ import { modelIsAvailable } from "./model-availability";
 import { validatePreTask, diagnoseFailure, DEFAULT_BACKGROUND_DEADLINE_MS } from "./validate";
 import { findUnknownParams, KNOWN_DELEGATE_KEYS, resolveSubagentParams, snapshotOriginalParams } from "./params";
 import { delegateTaskParamsSchema } from "./schema";
-import { createSessionState } from "./state";
+import { createSessionState, resolveTerminalRunEntry } from "./state";
 import { makeLiveOnUpdate, createUnitRun, finalizeUnitRun, finalizeUnitRunCrash, pruneHistoryIfNeeded, registerLiveRun } from "./unit-run";
 import { buildSubagentPrompt, describePromptMode } from "./prompt";
 import { runSubagent, cleanupTempDirs, reapActiveChildren } from "./runner";
@@ -83,7 +84,7 @@ import {
 	currentProcessOwner,
 	newDispatchIdentity,
 } from "./recovery";
-import { markInterrupted } from "./run-registry";
+import { markInterrupted, listInflightRuns, clearInflightRun } from "./run-registry";
 import { acquireSlot, releaseSlot, updateStatus, updateProgressStatus } from "./concurrency";
 import { transcriptDisplayPath } from "./transcript-path";
 import {
@@ -103,6 +104,7 @@ import {
 	showApprovalModeSelector,
 	showApprovalDialog,
 	showCompletionNotifySelector,
+	showRecoverySelector,
 	showPresetManager,
 	showTemplateManager,
 	showSLAConfig,
@@ -117,13 +119,22 @@ import {
 	renderDelegateResult,
 } from "./tui";
 import { createLogger, setLogCwd, type Logger } from "./logging";
+import {
+	collectInterruptedRuns,
+	offeredInterruptedRuns,
+	buildRecoveryNotice,
+	resolveRecoveryNoticeDelivery,
+	abandonInterruptedRun,
+	visibleRunEntriesForSession,
+	type RecoveryAgentLookup,
+} from "./recovery-surface";
 import { Intercom } from "./messaging";
 import * as eventBus from "./event-bus";
 import {
 	buildCompletionMessage,
 	resolveDelivery,
 	sendCompletionNotification,
-	markTerminalSeen,
+	claimTerminalNotice,
 	resolveRunEntry,
 } from "./notify-completion";
 
@@ -197,6 +208,12 @@ export default function (pi: ExtensionAPI) {
 	// receives no ctx, so capture it in session_start where it is available.
 	let sessionCtx: ExtensionContext | undefined;
 
+	// Option B U3 (D2): "one recovery notice per boot". The boot scan may be
+	// followed by more session_starts in the same process (reload); without this
+	// guard every one would re-list the same interrupted runs. Reset on shutdown
+	// so a genuinely new session notifies again.
+	let recoveryNoticeDelivered = false;
+
 	// -------------------------------------------------------------------
 	// Config change callback
 	// -------------------------------------------------------------------
@@ -707,7 +724,7 @@ export default function (pi: ExtensionAPI) {
 				// so sweepStaleLiveSubagents finds a 'running' record for every
 				// foreground live entry (the #130 invariant gap that swept
 				// graph/chain entries immediately).
-				const { runId, run } = createUnitRun(merged, stepModel, chainPriority, globalParams.resolvedPreset?.name);
+				const { runId, run } = createUnitRun(merged, stepModel, chainPriority, globalParams.resolvedPreset?.name, state.config.recovery);
 				state.persistRun(pi, run, "unit");
 
 				// R2: Prune old run entries if history exceeds limit
@@ -1162,7 +1179,7 @@ export default function (pi: ExtensionAPI) {
 			// Issue #119: per-subtask run entry — created at spawn so the
 			// monitor drill-in shows per-unit priority and a post-hoc audit
 			// trail exists per subtask (mirrors single-mode run persistence).
-			const { runId, run } = createUnitRun(merged, stepModel, parallelPriority, globalParams.resolvedPreset?.name);
+			const { runId, run } = createUnitRun(merged, stepModel, parallelPriority, globalParams.resolvedPreset?.name, state.config.recovery);
 			state.persistRun(pi, run, "unit");
 
 			// R2: Prune old run entries if history exceeds limit
@@ -1799,7 +1816,7 @@ export default function (pi: ExtensionAPI) {
 					// so sweepStaleLiveSubagents finds a 'running' record for every
 					// foreground live entry (the #130 invariant gap that swept
 					// graph/chain entries immediately).
-					const { runId, run } = createUnitRun(merged, stepModel, graphPriority, globalParams.resolvedPreset?.name);
+					const { runId, run } = createUnitRun(merged, stepModel, graphPriority, globalParams.resolvedPreset?.name, state.config.recovery);
 					state.persistRun(pi, run, "unit");
 
 					// R2: Prune old run entries if history exceeds limit
@@ -2210,6 +2227,7 @@ export default function (pi: ExtensionAPI) {
 						preset: globalParams.resolvedPreset?.name,
 					}),
 					sanitizeCwd: merged.effectiveCwd,
+					recoveryPosture: state.config.recovery,
 				});
 			} catch (err) {
 				const message = sanitizeErrorMessage(
@@ -2280,6 +2298,8 @@ export default function (pi: ExtensionAPI) {
 			dispatchId?: string;
 			resumeOf?: string;
 			attempt?: number;
+			// Option B U3 (D4): recovery posture snapshot for the background run.
+			recoveryPosture?: RecoveryMode;
 		},
 	): Promise<BackgroundAgent> {
 		const { spawnBackgroundSession, setAgentFinalOutput, extractFinalOutput, updateAgentStatus } = await import('./session-manager');
@@ -2310,8 +2330,24 @@ export default function (pi: ExtensionAPI) {
 			dispatchId: spawn.dispatchId,
 			resumeOf: spawn.resumeOf,
 			attempt: spawn.attempt,
+			// Option B U3 (D4): recovery posture snapshot for the background run.
+			recoveryPosture: spawn.recoveryPosture,
 		});
 		
+		// Issue #318 (from #316 review): the two poller crash sites share one
+		// claimed notification envelope. Content is the only variable; the
+		// claim guard, display, details and deliverAs live here once.
+		const sendCrashNotice = (content: string): void => {
+			if (claimTerminalNotice(agent.id)) {
+				pi.sendMessage({
+					customType: "subagent-notification",
+					content,
+					display: true,
+					details: { agentId: agent.id }
+				}, { deliverAs: "followUp" });
+			}
+		};
+
 		// Register for live monitor
 		state.registerLiveSubagent(agent.id, {
 			id: agent.id,
@@ -2359,12 +2395,7 @@ export default function (pi: ExtensionAPI) {
 					}
 					state.failedSubagents++;
 					updateProgressStatus(state, ctx);
-					pi.sendMessage({
-						customType: "subagent-notification",
-						content: `Background agent "${agent.description}" crashed.`,
-						display: true,
-						details: { agentId: agent.id }
-					}, { deliverAs: "followUp" });
+					sendCrashNotice(`Background agent "${agent.description}" crashed.`);
 					return;
 				}
 				
@@ -2411,12 +2442,10 @@ export default function (pi: ExtensionAPI) {
 					if (agent.status === 'failed') {
 						state.failedSubagents++;
 						updateProgressStatus(state, ctx);
-						pi.sendMessage({
-							customType: "subagent-notification",
-							content: `Background agent "${agent.description}" failed.`,
-							display: true,
-							details: { agentId: agent.id }
-						}, { deliverAs: "followUp" });
+						// Issue #315: the terminal wake (`subagent-completion`, emitted by
+						// the session-manager settle) is the ONE notice for a failed run.
+						// The status here was set by that settle, so the wake already
+						// delivered — this legacy poller notice would duplicate it.
 					} else if (agent.status === 'stopped') {
 						// User-initiated stop (stop_subagent) or deadline abort
 						// (timeout/deadline) — not a failure.
@@ -2444,12 +2473,7 @@ export default function (pi: ExtensionAPI) {
 					}
 					state.failedSubagents++;
 					updateProgressStatus(state, ctx);
-					pi.sendMessage({
-						customType: "subagent-notification",
-						content: `Background agent "${agent.description}" crashed: ${sanitizeErrorMessage((err as Error).message, spawn.sanitizeCwd)}`,
-						display: true,
-						details: { agentId: agent.id }
-					}, { deliverAs: "followUp" });
+					sendCrashNotice(`Background agent "${agent.description}" crashed: ${sanitizeErrorMessage((err as Error).message, spawn.sanitizeCwd)}`);
 				}
 			}
 		}, 2000);
@@ -2646,8 +2670,15 @@ export default function (pi: ExtensionAPI) {
 				dispatchId: bgIdentity.dispatchId,
 				resumeOf: bgIdentity.resumeOf,
 				attempt: bgIdentity.attempt,
+				recoveryPosture: state.config.recovery,
 			});
 
+			// Retire-on-retry (O3 fold, decision 2026-10-11): the source interrupted
+			// registry entry is superseded once the new background run is actually
+			// spawned (a throwing spawn is caught below and leaves the source intact
+			// and retryable).
+			if (retrySourceRun) clearInflightRun(retrySourceRun.id);
+
 			// B2: Surface auto-route decisions in background spawn result too —
 			// preset name + matched-keyword evidence + restriction, derived from
 			// the RESOLVED toolOptions (reflects per-call overrides).
@@ -2692,7 +2723,7 @@ export default function (pi: ExtensionAPI) {
 		description: "Configure subagent model and thinking level",
 		getArgumentCompletions: (prefix: string) => {
 			const options = [
-				"history", "historyentries", "monitor", "dashboard", "preset", "templates", "retry", "completionnotify",
+				"history", "historyentries", "monitor", "dashboard", "preset", "templates", "retry", "completionnotify", "recovery",
 			];
 			const filtered = options.filter((o) => o.startsWith(prefix));
 			return filtered.length > 0
@@ -2709,6 +2740,7 @@ export default function (pi: ExtensionAPI) {
 				depth: () => showDepthInput(ctx, state, applyConfig),
 				approval: () => showApprovalModeSelector(ctx, state, applyConfig),
 				completionnotify: () => showCompletionNotifySelector(ctx, state, applyConfig),
+				recovery: () => showRecoverySelector(ctx, state, applyConfig),
 				costlimit: () => showCostLimitInput(ctx, state, applyConfig),
 				reset: () => resetState(ctx),
 				history: () => showRunHistory(ctx, state, () => state.persistState(pi)),
@@ -2717,7 +2749,7 @@ export default function (pi: ExtensionAPI) {
 				dashboard: () => showDashboard(ctx, state),
 				preset: () => showPresetManager(ctx, state),
 				templates: () => showTemplateManager(ctx, state),
-				retry: () => showRetryMenu(ctx, state),
+				retry: () => showRetryMenu(ctx, state, (id) => abandonProductionRun(ctx, id)),
 			sla: () => showSLAConfig(ctx, state, applyConfig),
 			"sla-stats": () => showSLAStats(ctx, state),
 			// E5: the compliance report menu (file access / secrets exposure /
@@ -2922,7 +2954,18 @@ export default function (pi: ExtensionAPI) {
 			// resolving templates first keeps a combined template + retryRunId call
 			// from silently disabling template resolution (issue #175 review).
 			if (params.retryRunId) {
-				const runEntry = state.findSpawnRunById(ctx, params.retryRunId);
+				// Fix A: prefer the session spawn entry (it carries `originalParams`);
+				// a run that exists ONLY in the durable registry after a fresh boot
+				// resolves through the visibility bridge instead of being rejected as
+				// not found — the id the boot notice names must resolve here.
+				let runEntry = state.findSpawnRunById(ctx, params.retryRunId);
+				if (!runEntry) {
+					const { getAgent } = await import("./session-manager");
+					runEntry = resolveTerminalRunEntry(
+						visibleRunsFor(ctx, getAgent),
+						params.retryRunId,
+					);
+				}
 				if (runEntry) {
 					retrySourceRun = runEntry;
 					params = resolveRetryParams(params, runEntry) as DelegateTaskParams;
@@ -3212,6 +3255,8 @@ export default function (pi: ExtensionAPI) {
 				attempt: identity.attempt,
 				owner: currentProcessOwner(),
 				childMarker: crypto.randomUUID(),
+				// U3 (D4): the session recovery posture at dispatch.
+				recoveryPosture: state.config.recovery,
 			};
 			state.persistRun(pi, run, "foreground");
 
@@ -3322,6 +3367,17 @@ export default function (pi: ExtensionAPI) {
 
 			let success = false;
 
+			// Retire-on-retry (O3 fold, decision 2026-10-11): the retry has passed
+			// every pre-spawn gate and is about to start, so the SOURCE interrupted
+			// registry entry is superseded — clear it here so the old run is not
+			// re-offered at every subsequent boot. A failed pre-start (circuit open,
+			// slot cancelled) returns ABOVE this point and leaves the source intact
+			// and retryable — but note it is NOT "one row only": the pre-existing
+			// pre-start path (`persistRun`, which precedes the circuit/slot gates)
+			// still leaves a dangling `running` NEW row behind until the backlogged
+			// dangling-row fix. `retrySourceRun` is set only on a `retryRunId` call.
+			if (retrySourceRun) clearInflightRun(retrySourceRun.id);
+
 			// F7 (issue #65): import BEFORE the try — the crash-path catch calls
 			// completeTranscript, and block-scoped consts declared inside the try
 			// are invisible in its catch (pre-fix, a crash here threw
@@ -3930,8 +3986,9 @@ export default function (pi: ExtensionAPI) {
 	// parse (only the one agent record a background entry names is read). For
 	// each in-flight run whose owner is dead, its orphaned marker-verified child
 	// is reaped and the record is marked: the registry entry always, plus the
-	// agent record for background runs. SILENT in the UI — the notice/offer
-	// surface is U3. Platforms without /proc skip the whole scan (one log line):
+	// agent record for background runs. The scan itself is SILENT in the UI —
+	// U3's `maybeSendRecoveryNotice` (below) is the one notice surface.
+	// Platforms without /proc skip the whole scan (one log line):
 	// pid-only liveness cannot rule out pid reuse, so nothing is killed or
 	// marked unverified.
 	async function performBootRecovery(): Promise<void> {
@@ -3964,6 +4021,83 @@ export default function (pi: ExtensionAPI) {
 		}
 	}
 
+	/**
+	 * Option B U3 Fix A: the recovery visibility bridge, wired for the two
+	 * extension consumers that resolve a run id (the retryRunId branch and the
+	 * abandon action). Session run entries UNIONED with synthetic durable
+	 * interrupted records the session has never seen (a genuine fresh boot), so
+	 * an id named by the boot notice resolves here instead of being rejected as
+	 * not found. `getAgent` is injected because the callers already load it
+	 * dynamically — this keeps the registry/agent reads in ONE place.
+	 */
+	function visibleRunsFor(
+		ctx: ExtensionContext,
+		getAgent: RecoveryAgentLookup,
+	): SubagentRun[] {
+		return visibleRunEntriesForSession(state.getRunEntries(ctx), getAgent);
+	}
+
+	/**
+	 * Option B U3 (D2): after the boot scan, send ONE notice at the next turn
+	 * boundary listing every unresolved interrupted run whose dispatch snapshot
+	 * (and the session posture) says "offer". Delivery is `nextTurn` — the notice
+	 * can never steer or arrive mid-turn (see `resolveRecoveryNoticeDelivery`).
+	 * Silent when there is nothing to offer; at most once per session start.
+	 */
+	async function maybeSendRecoveryNotice(ctx: ExtensionContext): Promise<void> {
+		if (recoveryNoticeDelivered) return;
+		recoveryNoticeDelivered = true;
+		// Session posture off silences the whole surface, regardless of per-run
+		// snapshots (a user opting out expects quiet).
+		if (state.config.recovery === "off") return;
+		try {
+			const { getAgent } = await import("./session-manager");
+			const offered = offeredInterruptedRuns(
+				collectInterruptedRuns({
+					listInflight: () => listInflightRuns(),
+					getAgent: (id) => getAgent(id),
+					findRun: (id) => state.findTerminalRunById(ctx, id),
+				}),
+			);
+			if (offered.length === 0) return;
+			pi.sendMessage(buildRecoveryNotice(offered), resolveRecoveryNoticeDelivery());
+			log.info("Recovery notice delivered", { count: offered.length });
+		} catch (err) {
+			// The notice is best-effort — it must never break session start.
+			log.warn("Recovery notice failed", { error: (err as Error).message });
+		}
+	}
+
+	/**
+	 * Option B U3 (D5): finalize ONE interrupted run as the existing terminal
+	 * `stopped` outcome and prune its U2 session dir. Wired through injected deps
+	 * so the pure core (`recovery-surface.ts`) stays testable; the run record is
+	 * written terminal (the run store's `status` union has no `stopped` — a
+	 * stopped outcome is represented as `failed` + `errorCategory: "aborted"`,
+	 * exactly as every other stop path does) and the background agent record is
+	 * flipped to `stopped`.
+	 */
+	async function abandonProductionRun(ctx: ExtensionContext, id: string): Promise<void> {
+		const { updateAgentStatus, pruneBackgroundSession, getAgent } = await import("./session-manager");
+		// Fix A: the abandon lookup routes through the visibility bridge, so a run
+		// that exists ONLY in the durable registry after a fresh boot is
+		// abandonable instead of resolving to undefined (the silent `false`).
+		const visible = visibleRunsFor(ctx, getAgent);
+		abandonInterruptedRun(id, {
+			getRun: (runId) => resolveTerminalRunEntry(visible, runId),
+			writeRun: (run) => {
+				state.persistRun(pi, run);
+				pruneHistoryIfNeeded(state, ctx, log);
+			},
+			markAgentStopped: (agentId) => {
+				const agent = updateAgentStatus(agentId, "stopped");
+				if (agent) log.info("Abandoned background agent record", { agentId });
+			},
+			retireRegistry: (runId) => clearInflightRun(runId),
+			pruneSession: (runId) => pruneBackgroundSession(runId),
+		});
+	}
+
 	pi.on("session_start", async (_event, ctx) => {
 		// Issue #147: capture the session context for the completion-push subscriber.
 		sessionCtx = ctx;
@@ -4018,6 +4152,10 @@ export default function (pi: ExtensionAPI) {
 		// records interrupted BEFORE anything else touches their worktrees.
 		await performBootRecovery();
 
+		// Option B U3 (D2): after the scan, surface every unresolved interrupted
+		// run ONCE, at the next turn boundary (never mid-turn).
+		await maybeSendRecoveryNotice(ctx);
+
 		updateStatus(state, ctx);
 	});
 
@@ -4048,6 +4186,8 @@ export default function (pi: ExtensionAPI) {
 		state.unseenSubagents = 0;
 		// Clear pending queue
 		state.pendingQueue.length = 0;
+		// U3: a new session boot may notify again.
+		recoveryNoticeDelivered = false;
 	});
 
 	// -------------------------------------------------------------------
@@ -4057,9 +4197,10 @@ export default function (pi: ExtensionAPI) {
 	// subagent:failed / subagent:stopped), so the conductor is woken via
 	// pi.sendMessage + triggerTurn when a background run reaches a terminal state.
 	// Delivery is always-on (minimum nextTurn); the completionNotify knob controls
-	// the WAKE (D1+D2 — see notify-completion.ts). The dedupe set defends the
-	// pathological double-emit path (first terminal event per id wins); it is
-	// capped simply (cleared when it exceeds 200 entries).
+	// the WAKE (D1+D2 — see notify-completion.ts). The shared terminal claim
+	// (issue #315) defends the pathological double-emit path (first terminal
+	// event or crash notice per id wins); it is capped simply (cleared when it
+	// exceeds 200 entries).
 	//
 	// Stopped-run degradation — ACCEPTED BY DESIGN (review #2, adjudicated
 	// 2026-09-01): subagent:stopped fires at stop time (updateAgentStatus) BEFORE
@@ -4068,7 +4209,6 @@ export default function (pi: ExtensionAPI) {
 	// resolveRunEntry returns may be the pre-finalize spawn entry. The wake is
 	// the point; details are best-effort — the notification must never throw or
 	// block on their absence.
-	const terminalSeen = new Set<string>();
 	const terminalTypes = ["subagent:completed", "subagent:failed", "subagent:stopped"] as const;
 	for (const type of terminalTypes) {
 		eventBus.on(type, (event) => {
@@ -4078,7 +4218,7 @@ export default function (pi: ExtensionAPI) {
 
 	async function deliverCompletionAlert(event: SubagentEvent): Promise<void> {
 		const id = event.agentId;
-		if (!markTerminalSeen(terminalSeen, id)) return;
+		if (!claimTerminalNotice(id)) return;
 		const ctx = sessionCtx;
 		if (!ctx) return;
 		try {