brl-subagent 2.4.0 → 2.5.1

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";
@@ -58,13 +59,14 @@ import { pkgPath } from "./paths";
 
 import { sanitizeTask, validateCwd, validateOutputFile, stripAnsi, capOutput, getCurrentDepth, sanitizeErrorMessage, buildCrashResult } from "./sanitize";
 import {
-	getCurrentBranch,
 	hasUncommittedChanges,
 	createWorkBranch,
 	captureDiff,
-	switchToBranch,
+	getHeadState,
+	restoreHead,
 	deleteBranch,
 	mergeWorkBranch,
+	type HeadState,
 } from "./git";
 import { preflightCheck } from "./preflight";
 import { gateSessionCost, rejectApprovalAlwaysInBackground, runPreTaskValidation, validateDelegationTargets, formatValidationWarnings } from "./prelude";
@@ -73,11 +75,18 @@ 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 } from "./runner";
+import { runSubagent, cleanupTempDirs, reapActiveChildren } from "./runner";
+import {
+	recoverProduction,
+	currentProcessOwner,
+	newDispatchIdentity,
+} from "./recovery";
+import { markInterrupted, listInflightRuns, clearInflightRun } from "./run-registry";
 import { acquireSlot, releaseSlot, updateStatus, updateProgressStatus } from "./concurrency";
+import { transcriptDisplayPath } from "./transcript-path";
 import {
 	finalizeRunRecord,
 	resolveRetryParams,
@@ -95,6 +104,7 @@ import {
 	showApprovalModeSelector,
 	showApprovalDialog,
 	showCompletionNotifySelector,
+	showRecoverySelector,
 	showPresetManager,
 	showTemplateManager,
 	showSLAConfig,
@@ -109,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";
 
@@ -189,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
 	// -------------------------------------------------------------------
@@ -699,8 +724,8 @@ 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);
-				state.persistRun(pi, run);
+				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
 				pruneHistoryIfNeeded(state, ctx, log);
@@ -740,6 +765,9 @@ export default function (pi: ExtensionAPI) {
 						getFinalOutput,
 						log,
 						currentDepth + 1,
+						undefined, // intercom
+						undefined, // subagentId
+						run.childMarker,
 					);
 				} catch (err) {
 					// Issue #133 (mirrors the #119 R1/C1 discipline): finalize the
@@ -1151,8 +1179,8 @@ 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);
-			state.persistRun(pi, run);
+			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
 			pruneHistoryIfNeeded(state, ctx, log);
@@ -1210,6 +1238,7 @@ export default function (pi: ExtensionAPI) {
 					currentDepth + 1,
 					intercom,
 					subagentId,
+					run.childMarker,
 				);
 
 				// Fill SubTaskResult
@@ -1787,8 +1816,8 @@ 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);
-					state.persistRun(pi, run);
+					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
 					pruneHistoryIfNeeded(state, ctx, log);
@@ -1825,6 +1854,7 @@ export default function (pi: ExtensionAPI) {
 							currentDepth + 1,
 							intercom,
 							subagentId,
+							run.childMarker,
 						);
 
 						const subTaskResult: SubTaskResult = {
@@ -2197,6 +2227,7 @@ export default function (pi: ExtensionAPI) {
 						preset: globalParams.resolvedPreset?.name,
 					}),
 					sanitizeCwd: merged.effectiveCwd,
+					recoveryPosture: state.config.recovery,
 				});
 			} catch (err) {
 				const message = sanitizeErrorMessage(
@@ -2263,6 +2294,12 @@ export default function (pi: ExtensionAPI) {
 			originalParams?: SubagentRun["originalParams"];
 			/** cwd used to redact paths from crash notifications. */
 			sanitizeCwd: string;
+			// Option B U1: durability identity threaded onto the background records.
+			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');
@@ -2289,8 +2326,28 @@ export default function (pi: ExtensionAPI) {
 			// Issue #98/#108: snapshotOriginalParams is the single source of truth
 			// for the caller params a later retry restores.
 			originalParams: spawn.originalParams,
+			// Option B U1: durability identity for the agent record + run entry.
+			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,
@@ -2338,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;
 				}
 				
@@ -2390,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.
@@ -2423,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);
@@ -2522,6 +2567,10 @@ export default function (pi: ExtensionAPI) {
 			priority?: string;
 		},
 		singleTask: string,
+		// Option B U1: the spawn entry a retryRunId resolved to, so a retried
+		// background run inherits dispatchId/resumeOf/attempt (record identity,
+		// not a delegate param — D4).
+		retrySourceRun?: SubagentRun,
 	): Promise<ToolResult<undefined>> {
 		// Phase 6.5: Background execution — spawn session and return ID immediately.
 		// Resolve the preset and its model BEFORE the background branch so the
@@ -2602,6 +2651,8 @@ export default function (pi: ExtensionAPI) {
 				bgResolvedPreset?.promptGuideline,
 			);
 
+			// Option B U1: durability identity (retry inherits the original dispatch).
+			const bgIdentity = newDispatchIdentity(retrySourceRun);
 			const agent = await startBackgroundAgent(pi, ctx, {
 				task: singleTask,
 				type: params.preset || 'general-purpose',
@@ -2616,8 +2667,18 @@ export default function (pi: ExtensionAPI) {
 				gitMode: bgResolved.resolvedGitMode,
 				originalParams: snapshotOriginalParams(params),
 				sanitizeCwd: bgResolved.effectiveCwd,
+				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).
@@ -2662,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
@@ -2679,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)),
@@ -2687,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 /
@@ -2787,6 +2849,10 @@ export default function (pi: ExtensionAPI) {
 			onUpdate: AgentToolUpdateCallback<DelegateTaskDetails> | undefined,
 			ctx: ExtensionContext,
 		) {
+			// Option B U1: the run a retryRunId resolves to (spawn entry). Internal
+			// record identity — dispatchId/resumeOf/attempt are threaded onto the new
+			// record, NOT through the delegate-param surface (D4).
+			let retrySourceRun: SubagentRun | undefined;
 			// Issue #99: warn on unknown params — typebox allows additional properties
 			// by default (pi's validateToolArguments passes unknown keys through), so a
 			// typo like `thinkinglevel` or a schema-drifted param is otherwise silently
@@ -2888,8 +2954,20 @@ 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;
 				} else {
 					// Issue #98: a silent no-op here made retries of background runs
@@ -3009,7 +3087,7 @@ export default function (pi: ExtensionAPI) {
 			const singleTask = params.task!; // non-empty (sanitizer guarantees; isSingle confirms)
 
 			if (params.background) {
-				return spawnBackgroundRun(pi, ctx, params, singleTask);
+				return spawnBackgroundRun(pi, ctx, params, singleTask, retrySourceRun);
 			}
 
 			// R5: Check session cost limit before spawning
@@ -3156,6 +3234,10 @@ export default function (pi: ExtensionAPI) {
 
 			// Create run record
 			const runId = crypto.randomUUID();
+			// Option B U1: durability identity — a retry inherits the original
+			// dispatchId and records resumeOf/attempt; a fresh marker keys the
+			// child process for boot-time orphan discovery.
+			const identity = newDispatchIdentity(retrySourceRun);
 			const run: SubagentRun = {
 				id: runId,
 				task,
@@ -3168,8 +3250,15 @@ export default function (pi: ExtensionAPI) {
 				priority: params.priority,
 				startedAt: new Date().toISOString(),
 				originalParams: snapshotOriginalParams(params),
+				dispatchId: identity.dispatchId,
+				resumeOf: identity.resumeOf,
+				attempt: identity.attempt,
+				owner: currentProcessOwner(),
+				childMarker: crypto.randomUUID(),
+				// U3 (D4): the session recovery posture at dispatch.
+				recoveryPosture: state.config.recovery,
 			};
-			state.persistRun(pi, run);
+			state.persistRun(pi, run, "foreground");
 
 			// R2: Prune old run entries if history exceeds limit
 			pruneHistoryIfNeeded(state, ctx, log);
@@ -3178,11 +3267,11 @@ export default function (pi: ExtensionAPI) {
 			registerLiveRun(state, run, ctx);
 
 			// P3: Git integration — set up work branch if gitMode is "branch"
-			let originalBranch: string | undefined;
+			let headState: HeadState | undefined;
 			let workBranchName: string | undefined;
 			if (resolvedGitMode === "branch") {
 				try {
-					originalBranch = getCurrentBranch(resolvedCwd);
+					headState = getHeadState(resolvedCwd);
 
 					if (hasUncommittedChanges(resolvedCwd)) {
 						log.warn("Uncommitted changes detected; proceeding with branch-based workflow anyway", {
@@ -3190,40 +3279,56 @@ export default function (pi: ExtensionAPI) {
 						});
 					}
 
-					const branchResult = createWorkBranch(resolvedCwd, originalBranch);
+					const branchResult = createWorkBranch(resolvedCwd, headState.sha);
 					if (branchResult.ok) {
 						workBranchName = branchResult.branch;
 						log.info("Created work branch for subagent", {
 							branch: workBranchName,
-							base: originalBranch,
+							base: headState.branch,
 						});
 					} else {
 						log.error("Failed to create work branch, falling back to 'none'", {
 							error: branchResult.error,
 						});
-						originalBranch = undefined;
+						headState = undefined;
 					}
 				} catch (err) {
 					log.warn("Not a git repository or git error; falling back to gitMode 'none'", {
 						error: (err as Error).message,
 					});
-					originalBranch = undefined;
+					headState = undefined;
 					workBranchName = undefined;
 				}
 			}
 
-			// Helper to switch back to original branch and optionally delete work branch
+			// Helper to restore the starting HEAD and delete the work branch. The
+			// delete is NOT gated on the restore succeeding: the branch must never
+			// survive teardown. A still-checked-out branch simply makes deleteBranch
+			// fail (logged) rather than silently leaking the ref.
 			const cleanupGitBranch = () => {
-				if (workBranchName && originalBranch) {
-					try {
-						switchToBranch(resolvedCwd, originalBranch);
-						log.info("Switched back to original branch", { branch: originalBranch });
-						// Attempt to delete the work branch (non-critical)
-						deleteBranch(resolvedCwd, workBranchName);
-					} catch {
-						// Non-fatal: best-effort cleanup
+				if (!workBranchName) return;
+				if (headState) {
+					const restoreResult = restoreHead(resolvedCwd, headState);
+					if (restoreResult.ok) {
+						log.info("Restored original HEAD", {
+							branch: headState.branch,
+							detached: headState.detached,
+						});
+					} else {
+						log.warn("Failed to restore original HEAD during cleanup", {
+							branch: headState.branch,
+							error: restoreResult.error,
+						});
 					}
 				}
+				// Attempt to delete the work branch (non-critical)
+				const deleteResult = deleteBranch(resolvedCwd, workBranchName);
+				if (!deleteResult.ok) {
+					log.warn("Failed to delete work branch during cleanup", {
+						branch: workBranchName,
+						error: deleteResult.error,
+					});
+				}
 			};
 
 			// R1: Circuit breaker check — reject if circuit is open
@@ -3262,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
@@ -3321,6 +3437,7 @@ export default function (pi: ExtensionAPI) {
 					childDepth,
 					undefined, // intercom
 					undefined, // subagentId
+					run.childMarker,
 				);
 
 				// Auto-retry on timeout
@@ -3368,6 +3485,7 @@ export default function (pi: ExtensionAPI) {
 						childDepth,
 						undefined, // intercom
 						undefined, // subagentId
+						run.childMarker,
 					);
 				}
 
@@ -3380,17 +3498,23 @@ export default function (pi: ExtensionAPI) {
 				result.label = label;
 
 				// P3: Capture git diff if we created a work branch
-				if (workBranchName && originalBranch) {
-					const diffResult = captureDiff(resolvedCwd, originalBranch);
+				if (workBranchName && headState) {
+					// Diff against the captured starting sha rather than the branch
+					// name: a detached start's branch label is the "HEAD" pseudo-ref,
+					// for which `git diff HEAD...HEAD` is always empty.
+					const diffResult = captureDiff(resolvedCwd, headState.sha);
 					if (diffResult.ok) {
 						result.gitBranch = workBranchName;
 						result.gitDiff = diffResult.diff;
 					}
 
-					// Switch back to the original branch
-					const switchResult = switchToBranch(resolvedCwd, originalBranch);
-					if (switchResult.ok) {
-						log.info("Switched back to original branch", { branch: originalBranch });
+					// Restore the starting HEAD (branch, or detached sha)
+					const restoreResult = restoreHead(resolvedCwd, headState);
+					if (restoreResult.ok) {
+						log.info("Restored original HEAD", {
+							branch: headState.branch,
+							detached: headState.detached,
+						});
 
 						// P4: Change approval workflow — let user review the diff
 						const diffContent = (result.gitDiff ?? "").trim();
@@ -3434,13 +3558,42 @@ export default function (pi: ExtensionAPI) {
 									error: mergeResult.error,
 								});
 							}
-							deleteBranch(resolvedCwd, workBranchName);
+							// #308: a DETACHED start has no branch of its own to hold the
+							// merge result — teardown re-detached at the captured sha and
+							// the merge fast-forwarded THAT detached HEAD, so deleting the
+							// work branch would leave the committed work reachable only
+							// from the detached HEAD (silently lost on the next checkout).
+							// Keep the branch as the durable ref and log where the work
+							// lives. An ATTACHED start merged onto its own branch, which
+							// already retains the commit, so the temporary work branch is
+							// safe to drop.
+							if (headState.detached) {
+								log.info("detached checkout: work preserved on branch", {
+									branch: workBranchName,
+								});
+							} else {
+								deleteBranch(resolvedCwd, workBranchName);
+							}
 							workBranchName = undefined;
 						} else {
 							// No changes — just delete the empty branch
 							deleteBranch(resolvedCwd, workBranchName);
 							workBranchName = undefined;
 						}
+					} else {
+						log.warn("Failed to restore original HEAD after work-branch run", {
+							branch: headState.branch,
+							error: restoreResult.error,
+						});
+					}
+
+					// Nothing may leave teardown with the work branch still present: the
+					// approval flow above clears workBranchName on every terminal choice
+					// (including "apply", where keeping the branch is intentional), so a
+					// still-set name means the restore failed and the flow was skipped.
+					if (workBranchName) {
+						deleteBranch(resolvedCwd, workBranchName);
+						workBranchName = undefined;
 					}
 				}
 
@@ -3704,8 +3857,7 @@ export default function (pi: ExtensionAPI) {
 			}
 			
 			// Include transcript path
-			const { getTranscriptPath } = await import('./session-manager');
-			resultText += `\nTranscript: ${getTranscriptPath(params.agent_id)}`;
+			resultText += `\nTranscript: ${transcriptDisplayPath(params.agent_id)}`;
 			
 			return {
 				content: [{ type: "text" as const, text: resultText }],
@@ -3824,6 +3976,128 @@ export default function (pi: ExtensionAPI) {
 	// Session lifecycle — F7: Session-bound state initialization
 	// -------------------------------------------------------------------
 
+	// -------------------------------------------------------------------
+	// Option B U1: boot recovery — identity/liveness detection + child reap
+	// -------------------------------------------------------------------
+	// Runs AFTER restoreFromSession so config is ready. Candidate runs come from
+	// the DURABLE registry (`.pi/run-registry/`), NOT from this session's run
+	// entries: a crashed session's foreground/unit records are invisible to a
+	// default fresh startup, and the full `.pi/subagents/` store is too costly to
+	// 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. 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> {
+		try {
+			const { getAgent, markAgentInterrupted } = await import("./session-manager");
+			// `recoverProduction` owns the /proc platform guard (nothing is marked or
+			// killed without start-token verification) — see src/recovery.ts.
+			const summary = await recoverProduction({
+				log,
+				// Read THAT ONE agent record by id — never the whole store.
+				readAgentRecord: (id) => getAgent(id),
+				mark(record, interruptedAt) {
+					// Registry entry = the durable mark for every kind. Issue #304: its
+					// boolean is the durable-write result — do NOT drop it, or the boot
+					// summary would claim a mark that never landed. The scan counts a
+					// `false` as `markFailures` and warns with the id.
+					const durable = markInterrupted(record.id, interruptedAt);
+					if (record.kind === "agent") markAgentInterrupted(record.id, interruptedAt);
+					return durable;
+				},
+			});
+			// Report the scan whenever it did anything durable OR attempted a mark
+			// that failed — a failure-only boot must not be silent (issue #304).
+			if (summary.marked > 0 || summary.markFailures > 0) {
+				log.warn("Boot recovery marked interrupted runs", { ...summary });
+			}
+		} catch (err) {
+			// Recovery is best-effort hygiene — it must never break session start.
+			log.warn("Boot recovery scan failed", { error: (err as Error).message });
+		}
+	}
+
+	/**
+	 * 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;
@@ -3874,6 +4148,14 @@ export default function (pi: ExtensionAPI) {
 		// F5/F9: Safe state restoration with type guards
 		state.restoreFromSession(ctx);
 
+		// Option B U1: reap a dead conductor's orphaned children and mark the
+		// 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);
 	});
 
@@ -3883,6 +4165,14 @@ export default function (pi: ExtensionAPI) {
 			activeSubagents: state.activeSubagents,
 		});
 
+		// Option B U1: reap in-flight foreground children first, so a clean exit
+		// never orphans a subprocess (the crash case is covered by boot recovery).
+		try {
+			await reapActiveChildren(log);
+		} catch (err) {
+			log.warn("Shutdown reap failed", { error: (err as Error).message });
+		}
+
 		// Clear all live subagent sessions
 		state.subagentSessions.clear();
 		// Drop pending finalize claims too (PR #71 review: the claim set must
@@ -3896,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;
 	});
 
 	// -------------------------------------------------------------------
@@ -3905,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
@@ -3916,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) => {
@@ -3926,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 {