brl-subagent 2.4.0 → 2.5.1

package/src/runner.ts

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