brl-subagent 2.4.0 → 2.5.0

package/src/runner.ts

@@ -26,13 +26,16 @@ import type {
 import {
 	EMPTY_USAGE,
 	SIGKILL_GRACE_MS,
+	SIGKILL_POLL_MS,
 	TEMP_FILE_MODE,
 	MAX_TEMP_DIR_AGE_MS,
 	isProviderError,
 	classifyError,
 	SUBAGENT_ABORTED_MESSAGE,
+	SUBAGENT_SIGNAL_KILLED_MESSAGE,
 } from "./types";
-import { getSafeEnv, DEPTH_ENV_KEY, sanitizeErrorMessage } from "./sanitize";
+import { escalateKill, type EscalationTarget } from "./kill-escalation";
+import { getSafeEnv, DEPTH_ENV_KEY, CHILD_MARKER_ENV_KEY, sanitizeErrorMessage } from "./sanitize";
 import type { Logger } from "./logging";
 import type { Intercom } from "./messaging";
 import { extractMessages, formatPendingMessages } from "./messaging";
@@ -41,14 +44,159 @@ import type {
 	TranscriptContentBlock,
 	TranscriptToolCallBlock,
 } from "./transcript-tail";
+// ---------------------------------------------------------------------------
+// In-flight child registry (Option B U1)
+// ---------------------------------------------------------------------------
+
+/**
+ * One tracked foreground child. The registry is keyed by a UNIQUE internal
+ * spawn token (B5), never by the caller marker: two concurrent children may
+ * legitimately share a marker, and a marker-keyed map would collapse them —
+ * the first close would untrack the still-live second. `marker` is retained on
+ * the entry so reap/kill can still identify children by their caller marker.
+ */
+interface ActiveChild {
+	proc: ChildProcess;
+	/** The caller-supplied child marker, when one was supplied. */
+	marker?: string;
+}
+
+/**
+ * Foreground child processes currently in flight, keyed by a process-unique
+ * spawn token. `reapActiveChildren` terminates every entry on `session_shutdown`
+ * so a clean extension exit never leaves an orphaned `pi` subprocess burning
+ * tokens.
+ *
+ * The registry is process-local and best-effort: a hard `kill -9` of the
+ * conductor cannot run this handler, which is exactly the case the boot scan
+ * (`src/recovery.ts`) covers on the next start.
+ */
+const activeChildren = new Map<string, ActiveChild>();
+
+/** Monotonic counter making every registry key unique (B5). */
+let spawnTokenSeq = 0;
+
+/** TEST-ONLY: how many foreground children are currently registered. */
+export function activeChildCount(): number {
+	return activeChildren.size;
+}
+
+/** True once the child has really exited (a signal was delivered is not enough). */
+function childExited(proc: ChildProcess): boolean {
+	return proc.exitCode !== null || proc.signalCode !== null;
+}
+
+/** Default real sleep between SIGTERM and the escalation re-check. */
+const realSleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * SIGTERM → grace → SIGKILL timing for the single-child abort/timeout kill
+ * paths. Production uses the shared `SIGKILL_GRACE_MS` / `SIGKILL_POLL_MS`
+ * constants. The test-only setter below shortens them so the real-child
+ * escalation tests need not wait the full 5 s grace.
+ */
+const escalationTiming = { graceMs: SIGKILL_GRACE_MS, pollMs: SIGKILL_POLL_MS };
+
+/**
+ * Issue #306 nit 2: the timing seam is test-only and must be UNREACHABLE in
+ * production. This package ships raw `.ts` (loaded via jiti) with no build step
+ * to strip test code, so the strongest available guarantee is a runtime gate:
+ * outside the test environment the setter THROWS instead of mutating the
+ * process-wide SIGTERM→SIGKILL timing, so a stray internal import cannot move
+ * production behavior. `vitest` sets `NODE_ENV=test` and `VITEST=true` in every
+ * worker, so the recovery escalation tests still shorten the grace.
+ */
+function isTestEnvironment(): boolean {
+	return process.env.NODE_ENV === "test" || process.env.VITEST === "true";
+}
+
+/** TEST-ONLY: shorten (or reset with no argument) the abort/timeout escalation timing. Throws outside tests. */
+export function __setEscalationTimingForTest(timing?: { graceMs?: number; pollMs?: number }): void {
+	if (!isTestEnvironment()) {
+		throw new Error(
+			"__setEscalationTimingForTest() is test-only and cannot run in production.",
+		);
+	}
+	escalationTiming.graceMs = timing?.graceMs ?? SIGKILL_GRACE_MS;
+	escalationTiming.pollMs = timing?.pollMs ?? SIGKILL_POLL_MS;
+}
+
+/**
+ * Escalation target for one spawned child. `verifyDeath` defaults to the
+ * REAL-exit check (`childExited`) and may be overridden per site. The abort and
+ * timeout paths must use the real check (issue #303): `child.killed` flips
+ * when a signal is *sent*, not when the process dies, so gating the SIGKILL on
+ * it would let a SIGTERM-ignoring child survive the escalation.
+ */
+function childTarget(proc: ChildProcess, verifyDeath: () => boolean = () => childExited(proc)): EscalationTarget {
+	return {
+		terminate: () => {
+			proc.kill("SIGTERM");
+		},
+		forceKill: () => {
+			proc.kill("SIGKILL");
+		},
+		verifyDeath,
+	};
+}
+
+/**
+ * Terminate every registered in-flight child: SIGTERM all, wait up to the shared
+ * grace period (returning as soon as every child is dead — B4), then SIGKILL any
+ * survivor. Returns the pids targeted. Safe to call when nothing is in flight.
+ */
+export async function reapActiveChildren(log?: Logger): Promise<number[]> {
+	const pids: number[] = [];
+	const targets: EscalationTarget[] = [];
+	for (const [token, entry] of activeChildren) {
+		if (entry.proc.pid === undefined) {
+			activeChildren.delete(token);
+			continue;
+		}
+		pids.push(entry.proc.pid);
+		targets.push(childTarget(entry.proc));
+	}
+	if (targets.length === 0) return [];
+
+	await escalateKill(targets, {
+		graceMs: SIGKILL_GRACE_MS,
+		pollMs: SIGKILL_POLL_MS,
+		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+	});
+
+	log?.info("Reaped in-flight subagent children", { pids });
+	return pids;
+}
+
 // ---------------------------------------------------------------------------
 // Pi binary resolution
 // ---------------------------------------------------------------------------
 
 /**
  * Resolve the pi binary and command-line invocation for subprocess spawning.
+ *
+ * Precedence:
+ *   1. `BRL_PI_BIN` — an explicit override, read per call. A non-empty value
+ *      (after trimming surrounding whitespace) is used as the command;
+ *      whitespace-only is ignored and falls through. This exists for the
+ *      Tier-2 e2e harness
+ *      (issue #271): it spawns a synthetic node process that loads the
+ *      extension, so `process.argv[1]` is the HARNESS script, not pi's CLI.
+ *      Without this override the argv[1] heuristic below re-runs the harness
+ *      as if it were pi (a delegation no-op that still "passes"). Production
+ *      behaviour is unchanged while the variable is unset.
+ *   2. `process.argv[1]` — a real script path (the dev/pi-CLI case). Spawn it
+ *      with the current runtime.
+ *   3. A non-generic `process.execPath` (a bundled/custom binary) — spawn it
+ *      directly.
+ *   4. `"pi"` on PATH.
  */
 export function getPiInvocation(extraArgs: string[]): { command: string; args: string[] } {
+	const override = process.env.BRL_PI_BIN?.trim();
+	if (override) {
+		return { command: override, args: extraArgs };
+	}
+
 	const currentScript = process.argv[1];
 	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
 	if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
@@ -220,10 +368,16 @@ function attachAbortHandler(
 		// blind kill with no result access at all.
 		result.errorMessage = SUBAGENT_ABORTED_MESSAGE;
 		result.errorCategory = "aborted";
-		proc.kill("SIGTERM");
-		setTimeout(() => {
-			if (!proc.killed) proc.kill("SIGKILL");
-		}, SIGKILL_GRACE_MS);
+		// Issue #303: use childTarget's default REAL-exit check. `child.killed`
+		// only records that SIGTERM was SENT, so gating the SIGKILL on it declared
+		// a SIGTERM-ignoring child dead and skipped the force-kill. The same
+		// poll/early-exit wait `reapActiveChildren` uses means a cooperative child
+		// completes in ms while a stubborn one gets SIGKILL at the grace boundary.
+		void escalateKill([childTarget(proc)], {
+			graceMs: escalationTiming.graceMs,
+			pollMs: escalationTiming.pollMs,
+			sleep: realSleep,
+		});
 	};
 	if (signal.aborted) killProc();
 	else signal.addEventListener("abort", killProc, { once: true });
@@ -706,7 +860,7 @@ export function enrichFailureDiagnostics(result: SubagentResult, cwd?: string):
 	// Track 1 already stamped an honest source (user abort / timeout) — that is
 	// authoritative and must not be overlaid with the provider-error fallback.
 	const msg = result.errorMessage.toLowerCase();
-	if (msg.includes("aborted") || msg.includes("timed out")) return;
+	if (msg.includes("aborted") || msg.includes("timed out") || msg.includes("killed by external signal")) return;
 	const errorTurns = countModelErrorTurns(result.messages);
 	if (errorTurns === 0) return;
 
@@ -738,6 +892,7 @@ export async function runSubagent(
 	depth?: number,
 	intercom?: Intercom,
 	subagentId?: string,
+	childMarker?: string,
 ): Promise<SubagentResult> {
 	// E10: Inject pending intercom messages into the task prompt
 	if (intercom && subagentId && intercom.hasMessages(subagentId)) {
@@ -789,15 +944,29 @@ ${msgBlock}`;
 			const exitCode = await new Promise<number>((resolve) => {
 				const invocation = getPiInvocation(args);
 				const subDepth = depth !== undefined ? depth : undefined;
-				const envOverrides: Record<string, string> | undefined =
-					subDepth !== undefined ? { [DEPTH_ENV_KEY]: String(subDepth) } : undefined;
+				const envOverrides: Record<string, string> = {};
+				if (subDepth !== undefined) envOverrides[DEPTH_ENV_KEY] = String(subDepth);
+				// Option B U1: stamp the per-run marker so boot recovery can discover
+				// this child by scanning /proc/*/environ after a conductor crash.
+				if (childMarker) envOverrides[CHILD_MARKER_ENV_KEY] = childMarker;
+				const hasEnvOverrides = Object.keys(envOverrides).length > 0;
 				const proc = spawn(invocation.command, invocation.args, {
 					cwd,
 					shell: false,
 					stdio: ["ignore", "pipe", "pipe"],
-					env: getSafeEnv(envOverrides), // F2: Environment isolation + depth tracking
+					env: getSafeEnv(hasEnvOverrides ? envOverrides : undefined), // F2: Environment isolation + depth tracking
 				});
 
+				// Option B U1: register the child for shutdown reap. Keyed by the
+				// marker when present (guaranteed unique per run), else the intercom
+				// id, else a generated fallback.
+				// Option B U1 + B5: register the child under a UNIQUE spawn token, not the
+				// caller marker — two concurrent children may share a marker, and a
+				// marker-keyed map would collapse them (one close untracking the other).
+				// The marker is kept on the entry for reap/kill identification.
+				const registryToken = `spawn-${process.pid}-${++spawnTokenSeq}`;
+				activeChildren.set(registryToken, { proc, marker: childMarker });
+
 				let buffer = "";
 
 				proc.stdout.on("data", (data: Buffer) => {
@@ -813,15 +982,32 @@ ${msgBlock}`;
 					result.stderr += data.toString();
 				});
 
-				proc.on("close", (code) => {
+				proc.on("close", (code, signal) => {
+					activeChildren.delete(registryToken);
 					if (buffer.trim()) {
 						parseSubagentLine(buffer, result, onUpdate, getFinalOutputFn, log);
 					}
-					log?.info("Subagent process exited", { exitCode: code, pid: proc.pid });
-					resolve(code ?? 0);
+					log?.info("Subagent process exited", { exitCode: code, signal, pid: proc.pid });
+					// Issue #295: Node gives NO numeric code for a signal death
+					// (code === null) — the old `code ?? 0` fabricated a clean exit and
+					// masked a SIGKILL'd run as a success. Always record the non-zero
+					// sentinel -1, REGARDLESS of whether a reason was already staged:
+					// our own timeout/abort SIGTERM/SIGKILL lands here with code === null
+					// too, and a masked 0 would hide it behind the same false 'done'.
+					result.exitCode = code === null ? -1 : code;
+					if (code === null && !result.errorMessage && !result.errorCategory) {
+						// No reason staged (a timeout/abort stamp already carries its own)
+						// — this was an external kill we did not initiate. Stamp the cause
+						// and the signal name; classifyError maps it to the existing
+						// "crash" category (no new ErrorCategory value).
+						result.errorMessage = `${SUBAGENT_SIGNAL_KILLED_MESSAGE} (${signal ?? "unknown"})`;
+						log?.warn("Subagent killed by external signal", { signal, pid: proc.pid });
+					}
+					resolve(result.exitCode);
 				});
 
 				proc.on("error", (err) => {
+					activeChildren.delete(registryToken);
 					// F7 (issue #30): subprocess errors can embed the spawn command
 					// (absolute paths to the pi binary, temp files, cwd) — sanitize the
 					// errorMessage before it reaches the conductor. stderr is left RAW:
@@ -842,10 +1028,14 @@ ${msgBlock}`;
 					const timer = setTimeout(() => {
 						result.errorMessage = `Subagent timed out after ${timeout}ms`;
 						log?.warn("Subagent timed out", { timeout, pid: proc.pid });
-						proc.kill("SIGTERM");
-						setTimeout(() => {
-							if (!proc.killed) proc.kill("SIGKILL");
-						}, SIGKILL_GRACE_MS);
+						// Same REAL-exit check as the abort path (issue #303 — see there):
+						// `child.killed` flips on signal-sent, not process-death, so it would
+						// skip the SIGKILL for a SIGTERM-ignoring child.
+						void escalateKill([childTarget(proc)], {
+							graceMs: escalationTiming.graceMs,
+							pollMs: escalationTiming.pollMs,
+							sleep: realSleep,
+						});
 					}, timeout);
 					proc.on("close", () => clearTimeout(timer));
 				}

package/src/sanitize.ts

@@ -8,7 +8,7 @@
 
 import * as path from "node:path";
 import * as fs from "node:fs";
-import { EMPTY_USAGE } from "./types";
+import { EMPTY_USAGE, DEFAULT_OUTPUT_CAP_BYTES } from "./types";
 
 // ---------------------------------------------------------------------------
 // F1: Input sanitization
@@ -209,6 +209,28 @@ export function stripAnsi(str: string): string {
 	return str.replace(ANSI_ESCAPE_RE, "");
 }
 
+/**
+ * End-anchored trailing marker `capOutput` appends when it truncates output.
+ * Exported (issue #261) so callers can detect a genuinely capped record by its
+ * notice instead of re-deriving the format; a byte-length comparison cannot
+ * tell a capped record from an uncapped one (the background/crash paths store
+ * raw `liveOutput` without calling `capOutput`).
+ *
+ * Reworded in issue #275 to point at the transcript (run-history details now
+ * show the capped text). `capOutput` writes ONLY this suffix.
+ */
+export const OUTPUT_TRUNCATION_SUFFIX =
+	"omitted. Full text in the run transcript.]";
+
+/**
+ * Pre-#275 truncation marker, retained for DETECTION ONLY. Session files
+ * written before the reword persist records capped with this suffix; matching
+ * it keeps their truncation honesty line from silently regressing. No code
+ * writes this suffix.
+ */
+export const LEGACY_OUTPUT_TRUNCATION_SUFFIX =
+	"omitted. Full output available in run history details.]";
+
 /**
  * Cap output size to prevent subagent results from overwhelming
  * the conductor's context window or TUI.
@@ -216,7 +238,7 @@ export function stripAnsi(str: string): string {
  * Returns the original string if within limits, or a truncated version
  * with a clear notice about how much was omitted.
  */
-export function capOutput(output: string, maxBytes: number = 100 * 1024): string {
+export function capOutput(output: string, maxBytes: number = DEFAULT_OUTPUT_CAP_BYTES): string {
 	const byteLength = Buffer.byteLength(output, "utf8");
 	if (byteLength <= maxBytes) return output;
 
@@ -227,7 +249,24 @@ export function capOutput(output: string, maxBytes: number = 100 * 1024): string
 	}
 
 	const omitted = byteLength - Buffer.byteLength(truncated, "utf8");
-	return `${truncated}\n\n[Output truncated: ${formatBytes(omitted)} omitted. Full output available in run history details.]`;
+	return `${truncated}\n\n[Output truncated: ${formatBytes(omitted)} ${OUTPUT_TRUNCATION_SUFFIX}`;
+}
+
+/**
+ * True when `output` was truncated by `capOutput` — i.e. it carries the exact,
+ * end-anchored truncation notice. This is the authoritative "hit the cap"
+ * signal: `capOutput` returns the input unchanged while it fits, so a capped
+ * record always ends with this suffix and a non-capped one never does.
+ *
+ * Matches the legacy (#275) suffix too, so records persisted before the reword
+ * keep detecting as truncated.
+ */
+export function isOutputTruncated(output: string | undefined | null): boolean {
+	return (
+		typeof output === "string" &&
+		(output.endsWith(OUTPUT_TRUNCATION_SUFFIX) ||
+			output.endsWith(LEGACY_OUTPUT_TRUNCATION_SUFFIX))
+	);
 }
 
 function formatBytes(bytes: number): string {
@@ -354,6 +393,17 @@ export function buildCrashResult(mode: string, err: unknown, cwd: string): {
 /** Env var used to track subagent nesting depth. */
 export const DEPTH_ENV_KEY = "BRL_SUBAGENT_DEPTH";
 
+/**
+ * Option B U1: env var carrying the per-run child marker injected into a
+ * foreground child's environment. Boot recovery scans `/proc/<pid>/environ` for
+ * this exact `KEY=value` pair to discover an orphaned child whose conductor
+ * died. It is passed via spawn-time overrides (never inherited from the
+ * parent's environment, because it is not in SAFE_ENV_KEYS), so an unrelated
+ * process can never carry it. Linux/POSIX only; non-/proc platforms skip the
+ * scan (see recovery.ts).
+ */
+export const CHILD_MARKER_ENV_KEY = "BRL_SUBAGENT_CHILD_MARKER";
+
 /**
  * Read the current subagent depth from the environment.
  * Returns 0 for the main (conductor) process, 1+ for nested subagents.

package/src/session-manager.ts

@@ -1,9 +1,9 @@
 // Purpose: Background execution: SDK sessions (`createAgentSession`), agent records, timeouts, steering, and settle paths.
 import { randomUUID } from 'crypto';
 import { join } from 'path';
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs';
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync } from 'fs';
 import type { BackgroundAgent, AgentStatus, GitMode, SubagentResult, SubagentRun, ThinkingLevel, SubagentToolOptions, UsageStats, ErrorCategory } from './types';
-import { EMPTY_USAGE, CUSTOM_ENTRY_TYPES, classifyError, classifyTerminalOutcome, isProviderError, coherentFailureReason, SUBAGENT_ABORTED_MESSAGE } from './types';
+import { EMPTY_USAGE, classifyError, classifyTerminalOutcome, isProviderError, coherentFailureReason, SUBAGENT_ABORTED_MESSAGE } from './types';
 import { accumulateUsage } from './runner';
 import * as eventBus from './event-bus';
 import * as transcript from './transcript';
@@ -11,8 +11,11 @@ import { createEvent } from './event-bus';
 import { assertSafeAgentId, sanitizeErrorMessage } from './sanitize';
 import { wrapTask } from './prompt';
 import { createLogger } from './logging';
-import { getCurrentBranch, createWorkBranch, captureDiff, switchToBranch, deleteBranch, hasUncommittedChanges, getRepoRoot, commitAll, captureWorkingDiff } from './git';
+import { getCurrentBranch, getHeadState, restoreHead, createWorkBranch, captureDiff, deleteBranch, hasUncommittedChanges, getRepoRoot, commitAll, captureWorkingDiff } from './git';
+import type { HeadState } from './git';
 import { normalizeTimeout, DEFAULT_BACKGROUND_DEADLINE_MS } from './validate';
+import { currentProcessOwner } from './recovery';
+import { persistRunRecord } from './run-registry';
 
 const log = createLogger('brl-subagent');
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
@@ -85,7 +88,7 @@ function persistAgent(agent: BackgroundAgent): void {
   try {
     assertSafeAgentId(agent.id);
   } catch {
-    console.error(`[brl-subagent] Refusing to persist agent with invalid id: ${agent.id}`);
+    log.error(`Refusing to persist agent with invalid id: ${agent.id}`);
     return;
   }
   ensureStorageDir();
@@ -102,7 +105,7 @@ function persistAgent(agent: BackgroundAgent): void {
     writeFileSync(filePath, JSON.stringify(persistable, null, 2), { encoding: 'utf-8', mode: 0o600 });
   } catch (err) {
     // Log but never throw — persistence must not break execution
-    console.error(`[brl-subagent] Failed to persist agent ${agent.id}:`, err);
+    log.error(`Failed to persist agent ${agent.id}`, { error: err instanceof Error ? err.message : String(err) });
   }
 }
 
@@ -136,6 +139,54 @@ export function getAgent(id: string): BackgroundAgent | null {
   return agents.get(id) || loadAgent(id);
 }
 
+/**
+ * Option B U1: every agent record persisted on disk (cross-session — the
+ * `.pi/subagents/` store survives a process death; the conductor's session run
+ * entries do not). Boot recovery does NOT use this: it sources candidates from
+ * the durable run registry and reads background records ONE at a time by id
+ * (`recoverInflightRuns`'s `readAgentRecord`), precisely to avoid parsing the
+ * whole store; production has no caller for this sweep. Unreadable/corrupt
+ * files and unsafe ids are skipped, never thrown.
+ */
+export function listPersistedAgents(): BackgroundAgent[] {
+  let files: string[];
+  try {
+    if (!existsSync(STORAGE_DIR)) return [];
+    files = readdirSync(STORAGE_DIR);
+  } catch {
+    return [];
+  }
+  const records: BackgroundAgent[] = [];
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue;
+    const id = file.slice(0, -'.json'.length);
+    try {
+      assertSafeAgentId(id);
+    } catch {
+      continue;
+    }
+    const record = loadAgent(id);
+    if (record) records.push(record);
+  }
+  return records;
+}
+
+/**
+ * Option B U1 (D3): read-modify-write the interrupted mark onto a persisted
+ * agent record. Idempotent: an already-marked record is returned unchanged.
+ * Returns null when the record does not exist.
+ */
+export function markAgentInterrupted(id: string, interruptedAt: string): BackgroundAgent | null {
+  const agent = getAgent(id);
+  if (!agent) return null;
+  if (!agent.interruptedAt) {
+    agent.interruptedAt = interruptedAt;
+    agents.set(id, agent);
+    persistAgent(agent);
+  }
+  return agent;
+}
+
 /**
  * Update agent status
  */
@@ -320,15 +371,13 @@ export async function steerAgent(id: string, message: string): Promise<Backgroun
 }
 
 /**
- * Get transcript path for an agent
+ * Get transcript path for an agent.
+ *
+ * Issue #276: the format lives in `transcript-path.ts` (the single source).
+ * This re-export preserves the historical `session-manager.getTranscriptPath`
+ * surface for `index.ts`'s dynamic import and the existing tests.
  */
-export function getTranscriptPath(id: string): string {
-  // F24: reachable with LLM-controlled ids (get_agent_result). Throw on invalid
-  // ids — the tool caller surfaces it as an error. (Defense in depth: getAgent
-  // already validated before this is reached with a live agent.)
-  assertSafeAgentId(id);
-  return join('.pi', 'output', `agent-${id}.jsonl`);
-}
+export { transcriptPath as getTranscriptPath } from './transcript-path';
 
 /**
  * Spawn a background session using pi's session API
@@ -359,6 +408,11 @@ export async function spawnBackgroundSession(
     /** Issue #114: per-unit priority — recorded on the run entry + agent record
      *  so the drill-in header and history carry it (absent → no segment). */
     priority?: string;
+    /** Option B U1: durability identity. A retry inherits the original's
+     *  dispatchId and records resumeOf/attempt; a fresh dispatch omits them. */
+    dispatchId?: string;
+    resumeOf?: string;
+    attempt?: number;
   }
 ): Promise<BackgroundAgent> {
   // Serialize access to pi API to prevent concurrent import races
@@ -469,6 +523,13 @@ export async function spawnBackgroundSession(
   // Set session name
   session.setSessionName(`background-${id.slice(0, 8)}`);
   
+  // Option B U1: durability identity. Background runs have no child process
+  // (the session is in-process), so there is no childMarker — only the owner
+  // identity that a boot scan uses to tell a live conductor from a dead one.
+  const dispatchId = params.dispatchId ?? generateUUID();
+  const attempt = params.attempt ?? 1;
+  const owner = currentProcessOwner();
+
   // Create agent record
   const agent: BackgroundAgent = {
     id,
@@ -481,6 +542,10 @@ export async function spawnBackgroundSession(
     model: params.model || 'unknown',
     thinkingLevel: params.thinkingLevel || 'medium',
     priority: params.priority,
+    dispatchId,
+    resumeOf: params.resumeOf,
+    attempt,
+    owner,
   };
   
   agents.set(id, agent);
@@ -506,8 +571,12 @@ export async function spawnBackgroundSession(
     priority: params.priority,
     startedAt: new Date().toISOString(),
     originalParams: params.originalParams,
+    dispatchId,
+    resumeOf: params.resumeOf,
+    attempt,
+    owner,
   };
-  pi.appendEntry(CUSTOM_ENTRY_TYPES.run, run);
+  persistRunRecord(pi, run, "background");
 
   // Issue #98: keep the session run entry in lockstep with the agent record —
   // every terminal branch that flips agent.status also finalizes the run entry
@@ -576,7 +645,7 @@ export async function spawnBackgroundSession(
           ? { ...(run.originalParams ?? {}), errorCategory }
           : run.originalParams,
     };
-    pi.appendEntry(CUSTOM_ENTRY_TYPES.run, entry);
+    persistRunRecord(pi, entry);
     // Issue #179 (D6): the explicit settle line — the log's job is to record the
     // CLASSIFIED OUTCOME, which cwd alone can never convey.
     log.info("Background run settled", {
@@ -661,9 +730,14 @@ export async function spawnBackgroundSession(
   // hard failure — never spawn an unisolated background agent that was asked
   // for isolation (fail-loud, same principle as foreground's fallback but
   // background cannot warn-and-continue safely).
-  let originalBranch: string | undefined;
+  let headState: HeadState | undefined;
   let workBranchName: string | undefined;
   let releaseGitLock: (() => void) | undefined;
+  // Idempotency guard for cleanupWorkBranch: it must be safe to call from both
+  // the normal settle path and the catch-all that runs when a settle step
+  // throws FIRST (before its own cleanup call). Without this the second call
+  // would re-restore/re-delete and log spurious warnings.
+  let gitCleanupDone = false;
   const gitCwd = params.cwd ?? ctx.cwd;
   if (params.gitMode === 'branch') {
     // C2: serialize the FULL branch lifecycle per repo. The spawnQueue only
@@ -696,13 +770,13 @@ export async function spawnBackgroundSession(
           'requesting background gitMode=branch isolation'
         );
       }
-      originalBranch = getCurrentBranch(gitCwd);
-      const branchResult = createWorkBranch(gitCwd, originalBranch);
+      headState = getHeadState(gitCwd);
+      const branchResult = createWorkBranch(gitCwd, headState.sha);
       if (branchResult.ok) {
         workBranchName = branchResult.branch;
         log.info('Created work branch for background agent', {
           branch: workBranchName,
-          base: originalBranch,
+          base: headState.branch,
           agentId: id,
         });
       } else {
@@ -740,7 +814,8 @@ export async function spawnBackgroundSession(
   // uncommitted edits would leak into the base working tree on switch —
   // commitAll first makes the diff real and the switch clean.
   const cleanupWorkBranch = (): { gitBranch?: string; gitDiff?: string } => {
-    if (!workBranchName || !originalBranch) return {};
+    if (gitCleanupDone || !workBranchName || !headState) return {};
+    gitCleanupDone = true;
     const info: { gitBranch?: string; gitDiff?: string } = { gitBranch: workBranchName };
     // The lock MUST be released on every exit path — early returns included.
     try {
@@ -778,7 +853,7 @@ export async function spawnBackgroundSession(
             if (workingDiff) info.gitDiff = workingDiff;
           }
         }
-        const diffResult = captureDiff(gitCwd, originalBranch);
+        const diffResult = captureDiff(gitCwd, headState.sha);
         if (diffResult.ok && diffResult.diff.trim()) {
           // Merge committed + working diffs — either can exist alone.
           info.gitDiff = info.gitDiff
@@ -789,9 +864,12 @@ export async function spawnBackgroundSession(
         log.warn(`captureDiff failed for background agent ${id}`, { error: (err as Error).message });
       }
       try {
-        switchToBranch(gitCwd, originalBranch);
+        const restoreResult = restoreHead(gitCwd, headState);
+        if (!restoreResult.ok) {
+          log.warn(`restoreHead failed for background agent ${id}`, { error: restoreResult.error });
+        }
       } catch (err) {
-        log.warn(`switchToBranch failed for background agent ${id}`, { error: (err as Error).message });
+        log.warn(`restoreHead failed for background agent ${id}`, { error: (err as Error).message });
       }
       try {
         deleteBranch(gitCwd, workBranchName);
@@ -812,6 +890,11 @@ export async function spawnBackgroundSession(
   // terminal so no zombie 'running' record survives; never rethrow.
   const markTerminalBestEffort = (fallback: AgentStatus): void => {
     try {
+      // Issue #53 / review C: this catch-all fires when a settle handler step
+      // threw — possibly BEFORE the branch's own cleanupWorkBranch() call. Run
+      // it here too (idempotent) so a throw can never bypass branch teardown
+      // and strand the work branch in the repo working tree.
+      cleanupWorkBranch();
       // Issue #31 (PR #76 review): this catch-all fires when a settle handler
       // threw — either BEFORE the branch's own capture (ref still live: capture
       // now, it is the last chance to record the session's output) or AFTER it