brl-subagent 2.4.0 → 2.5.0

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.4.0 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
+**Version:** 2.5.0 · **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 1200+ 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 1300+ test suite pinning every contract against the real pi SDK.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brl-subagent",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "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,10 +37,10 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^1.0.0",
-    "@earendil-works/pi-ai": "^1.0.0",
-    "@earendil-works/pi-coding-agent": "^1.0.0",
-    "@earendil-works/pi-tui": "^1.0.0",
+    "@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",
     "jiti": "^2.7.0",
     "typebox": "^1.3.34",
     "typescript": "7.0.2",

package/src/event-bus.ts

@@ -1,5 +1,10 @@
 // Purpose: In-memory lifecycle pub/sub (`subagent:*` events) for extensions and the completion wake.
 import type { SubagentEvent, SubagentEventType, SubagentEventListener } from './types';
+import { createLogger } from './logging';
+
+// Issue #265: listener failures route through the logger (file-only by default)
+// so raw console.error writes cannot corrupt the pi TUI.
+const log = createLogger('event-bus');
 
 // Event listeners by type
 const listeners = new Map<SubagentEventType, Set<SubagentEventListener>>();
@@ -49,7 +54,7 @@ export function emit(event: SubagentEvent): void {
         listener(event);
       } catch (err) {
         // Don't let listener errors break the event loop
-        console.error(`[event-bus] Listener error for ${event.type}:`, err);
+        log.error(`Listener error for ${event.type}`, { error: err instanceof Error ? err.message : String(err) });
       }
     }
   }
@@ -59,7 +64,7 @@ export function emit(event: SubagentEvent): void {
     try {
       listener(event);
     } catch (err) {
-      console.error(`[event-bus] Global listener error:`, err);
+      log.error('Global listener error', { error: err instanceof Error ? err.message : String(err) });
     }
   }
 }

package/src/git.ts

@@ -17,6 +17,11 @@ function gitOpts(cwd: string) {
 		cwd,
 		encoding: "utf-8" as const,
 		timeout: 10_000,
+		// Capture child stderr instead of inheriting it: expected git failures
+		// (e.g. deleting a checked-out branch) are caught and returned as
+		// {ok:false, error}; execFileSync still puts the captured stderr in the
+		// thrown error's message, so real failures stay diagnosable.
+		stdio: ["ignore", "pipe", "pipe"] as ["ignore", "pipe", "pipe"],
 	};
 }
 
@@ -33,6 +38,46 @@ export function getCurrentBranch(cwd: string): string {
 	return output.trim();
 }
 
+/**
+ * The starting state of HEAD, captured at spawn so teardown can restore it.
+ *
+ * `getCurrentBranch` alone is NOT enough to restore a detached HEAD: it
+ * returns the "HEAD" pseudo-ref, so a `git checkout HEAD` teardown is a no-op
+ * that stays on the work branch (stranding it and leaking the branch in CI PR
+ * builds, which check out a detached HEAD). The sha + attached-ness must be
+ * captured together.
+ *
+ * `detached` also governs DATA SAFETY at teardown (#308): a detached start has
+ * no branch of its own to retain a merged work branch, so the auto-approve path
+ * MUST preserve the work branch as the durable ref rather than delete it.
+ */
+export interface HeadState {
+	/** Commit HEAD pointed at when captured. */
+	sha: string;
+	/** True when HEAD was detached (no symbolic ref) at capture time. */
+	detached: boolean;
+	/**
+	 * Branch name when attached; the literal "HEAD" pseudo-ref when detached.
+	 * Attached callers can pass it straight to createWorkBranch/captureDiff.
+	 */
+	branch: string;
+}
+
+/**
+ * Capture the current HEAD state (sha + attached-ness) for later restoration.
+ * Throws if the cwd is not a git repository.
+ */
+export function getHeadState(cwd: string): HeadState {
+	const sha = execFileSync("git", ["rev-parse", "HEAD"], gitOpts(cwd)).trim();
+	try {
+		// Exits non-zero when HEAD is detached — that is the discriminator.
+		const branch = execFileSync("git", ["symbolic-ref", "--short", "-q", "HEAD"], gitOpts(cwd)).trim();
+		return { sha, detached: false, branch };
+	} catch {
+		return { sha, detached: true, branch: "HEAD" };
+	}
+}
+
 /**
  * Resolve the repository root that contains the given directory.
  * Returns undefined when the directory is not inside a repository, or when
@@ -105,6 +150,28 @@ export function switchToBranch(
 	}
 }
 
+/**
+ * Restore HEAD to the state captured by getHeadState.
+ * Detached starts are re-detached at the captured sha (`git checkout
+ * --detach <sha>`) instead of switching to the useless "HEAD" pseudo-ref;
+ * attached starts switch back to the original branch.
+ * Returns { ok: true } on success, { ok: false, error } on failure.
+ */
+export function restoreHead(
+	cwd: string,
+	state: HeadState,
+): { ok: true } | { ok: false; error: string } {
+	try {
+		const args = state.detached
+			? ["checkout", "--detach", state.sha]
+			: ["checkout", state.branch];
+		execFileSync("git", args, gitOpts(cwd));
+		return { ok: true };
+	} catch (err) {
+		return { ok: false, error: (err as Error).message };
+	}
+}
+
 /**
  * Merge a work branch into the current branch.
  * Uses --no-edit to prevent opening an editor.

package/src/history.ts

@@ -7,7 +7,9 @@
  */
 
 import type { SubagentRun, SubagentResult } from "./types";
-import { isSubagentError, getFinalOutput, isSubagentRunShape, classifyError, coherentFailureReason, CUSTOM_ENTRY_TYPES, MAX_RUN_HISTORY_ENTRIES } from "./types";
+import { isSubagentError, getFinalOutput, isSubagentRunShape, classifyError, coherentFailureReason, CUSTOM_ENTRY_TYPES, MAX_RUN_HISTORY_ENTRIES, DEFAULT_OUTPUT_CAP_BYTES } from "./types";
+import { isOutputTruncated } from "./sanitize";
+import { transcriptDisplayPath } from "./transcript-path";
 import type { ExtensionContext, SessionManager } from "@earendil-works/pi-coding-agent";
 
 // ---------------------------------------------------------------------------
@@ -200,3 +202,58 @@ export function formatRunDuration(ms: number): string {
 	const secs = Math.round((ms % 60_000) / 1000);
 	return `${min}m ${secs}s`;
 }
+
+// ---------------------------------------------------------------------------
+// Full-output honesty lines (issue #261)
+// ---------------------------------------------------------------------------
+
+/**
+ * Human-readable size for an output cap, e.g. `100 * 1024` → "100 KB".
+ * Byte caps are whole-KB by construction; sub-KB values (mostly tests) render
+ * as plain bytes.
+ */
+function formatCapSize(capBytes: number): string {
+	if (capBytes > 0 && capBytes % 1024 === 0) return `${capBytes / 1024} KB`;
+	return `${capBytes} B`;
+}
+
+/**
+ * Honest disclosure lines for a settled run's full-output view (issue #261).
+ *
+ * Always returns the transcript pointer. When the stored output hit the
+ * `capBytes` cap it also adds a disclosure that points at the transcript for
+ * the rest. Detection is deliberately two-signal:
+ *
+ *   1. `isOutputTruncated(run.fullOutput)` — the exact `capOutput` notice, true
+ *      only when the stored text was genuinely truncated;
+ *   2. `Buffer.byteLength` at/over `capBytes` — the length fallback, so an
+ *      UNCAPPED record (background/crash paths store raw `liveOutput`) that
+ *      already sits at or over the cap budget is still disclosed instead of
+ *      pretending the panel can show more than the cap's worth.
+ *
+ * Boundary precision: `capOutput` truncates only when the byte length is
+ * STRICTLY greater than the cap, so an output of exactly `capBytes` takes the
+ * length branch and is disclosed as "at or over" without carrying the notice.
+ * The notice branch alone is exact for "was truncated".
+ *
+ * Pure and pi-tui-free, so it is unit-testable in isolation.
+ */
+export function buildOutputHonestyLines(
+	run: Pick<SubagentRun, "id" | "fullOutput">,
+	capBytes: number = DEFAULT_OUTPUT_CAP_BYTES,
+): string[] {
+	const transcriptPath = transcriptDisplayPath(run.id);
+	const lines = [`Transcript: ${transcriptPath}`];
+	const output = run.fullOutput;
+	const size = formatCapSize(capBytes);
+	if (isOutputTruncated(output)) {
+		lines.push(
+			`Output was truncated at the ${size} cap — full text in the transcript: ${transcriptPath}`,
+		);
+	} else if (output && Buffer.byteLength(output, "utf8") >= capBytes) {
+		lines.push(
+			`Stored output is at or over the ${size} cap — full transcript: ${transcriptPath}`,
+		);
+	}
+	return lines;
+}

package/src/index.ts

@@ -58,13 +58,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";
@@ -76,8 +77,15 @@ import { delegateTaskParamsSchema } from "./schema";
 import { createSessionState } 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 } from "./run-registry";
 import { acquireSlot, releaseSlot, updateStatus, updateProgressStatus } from "./concurrency";
+import { transcriptDisplayPath } from "./transcript-path";
 import {
 	finalizeRunRecord,
 	resolveRetryParams,
@@ -700,7 +708,7 @@ export default function (pi: ExtensionAPI) {
 				// 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);
+				state.persistRun(pi, run, "unit");
 
 				// R2: Prune old run entries if history exceeds limit
 				pruneHistoryIfNeeded(state, ctx, log);
@@ -740,6 +748,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
@@ -1152,7 +1163,7 @@ export default function (pi: ExtensionAPI) {
 			// 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);
+			state.persistRun(pi, run, "unit");
 
 			// R2: Prune old run entries if history exceeds limit
 			pruneHistoryIfNeeded(state, ctx, log);
@@ -1210,6 +1221,7 @@ export default function (pi: ExtensionAPI) {
 					currentDepth + 1,
 					intercom,
 					subagentId,
+					run.childMarker,
 				);
 
 				// Fill SubTaskResult
@@ -1788,7 +1800,7 @@ export default function (pi: ExtensionAPI) {
 					// 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);
+					state.persistRun(pi, run, "unit");
 
 					// R2: Prune old run entries if history exceeds limit
 					pruneHistoryIfNeeded(state, ctx, log);
@@ -1825,6 +1837,7 @@ export default function (pi: ExtensionAPI) {
 							currentDepth + 1,
 							intercom,
 							subagentId,
+							run.childMarker,
 						);
 
 						const subTaskResult: SubTaskResult = {
@@ -2263,6 +2276,10 @@ 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;
 		},
 	): Promise<BackgroundAgent> {
 		const { spawnBackgroundSession, setAgentFinalOutput, extractFinalOutput, updateAgentStatus } = await import('./session-manager');
@@ -2289,6 +2306,10 @@ 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,
 		});
 		
 		// Register for live monitor
@@ -2522,6 +2543,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 +2627,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,6 +2643,9 @@ export default function (pi: ExtensionAPI) {
 				gitMode: bgResolved.resolvedGitMode,
 				originalParams: snapshotOriginalParams(params),
 				sanitizeCwd: bgResolved.effectiveCwd,
+				dispatchId: bgIdentity.dispatchId,
+				resumeOf: bgIdentity.resumeOf,
+				attempt: bgIdentity.attempt,
 			});
 
 			// B2: Surface auto-route decisions in background spawn result too —
@@ -2787,6 +2817,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
@@ -2890,6 +2924,7 @@ export default function (pi: ExtensionAPI) {
 			if (params.retryRunId) {
 				const runEntry = state.findSpawnRunById(ctx, 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 +3044,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 +3191,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 +3207,13 @@ 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(),
 			};
-			state.persistRun(pi, run);
+			state.persistRun(pi, run, "foreground");
 
 			// R2: Prune old run entries if history exceeds limit
 			pruneHistoryIfNeeded(state, ctx, log);
@@ -3178,11 +3222,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 +3234,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
@@ -3321,6 +3381,7 @@ export default function (pi: ExtensionAPI) {
 					childDepth,
 					undefined, // intercom
 					undefined, // subagentId
+					run.childMarker,
 				);
 
 				// Auto-retry on timeout
@@ -3368,6 +3429,7 @@ export default function (pi: ExtensionAPI) {
 						childDepth,
 						undefined, // intercom
 						undefined, // subagentId
+						run.childMarker,
 					);
 				}
 
@@ -3380,17 +3442,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 +3502,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 +3801,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 +3920,50 @@ 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. SILENT in the UI — the notice/offer
+	// surface is U3. 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 });
+		}
+	}
+
 	pi.on("session_start", async (_event, ctx) => {
 		// Issue #147: capture the session context for the completion-push subscriber.
 		sessionCtx = ctx;
@@ -3874,6 +4014,10 @@ 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();
+
 		updateStatus(state, ctx);
 	});
 
@@ -3883,6 +4027,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