brl-subagent 2.3.9 → 2.5.0

package/src/router.ts

@@ -1,3 +1,4 @@
+// Purpose: Auto-route: keyword classification of a task description to the best preset.
 /**
  * brl-subagent — Skill-based Routing
  *

package/src/run-registry.ts

@@ -0,0 +1,269 @@
+// Purpose: Durable per-run in-flight registry + the single run-record persist choke point that mirrors into it.
+/**
+ * Option B U1 — durable in-flight run registry.
+ *
+ * A foreground/chain/parallel/graph run's `SubagentRun` record lives ONLY as a
+ * session custom entry, so after a conductor crash a fresh process (pi's
+ * default `SessionManager.create` startup) cannot see it at all. The agent
+ * store (`.pi/subagents/<id>.json`) covers background runs only. This module
+ * closes that gap: one small JSON per IN-FLIGHT run at the cwd-relative path
+ * `.pi/run-registry/<runId>.json`, written before the run's effect and cleared
+ * when it reaches a terminal state.
+ *
+ * `persistRunRecord` is the single choke point every run-record write goes
+ * through (`state.persistRun` delegates here; the background path in
+ * session-manager calls it directly). It mirrors the record into the registry:
+ * a `running` record with a kind REGISTERS (or refreshes) an entry; a terminal
+ * record CLEARS it; a `running` record without a kind is left alone (the boot
+ * scan's `interruptedAt` mark is written through `markInterrupted`).
+ *
+ * WHERE THE INTERRUPTION MARK LIVES (commitment for U3): for foreground/unit
+ * runs the registry entry IS the durable interruption mark — the boot scan
+ * writes `interruptedAt` there, not into a session entry it cannot reach.
+ * Background runs additionally mark their `.pi/subagents/<id>.json` agent
+ * record (the existing double-mark). U3's interrupted-run surfacing reads the
+ * registry.
+ *
+ * Reads are parse-tolerant and never throw on a malformed or vanished entry;
+ * writes are atomic (temp file + rename) and owner-only (0o600), mirroring the
+ * agent store's F6 discipline.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ProcessOwner, SubagentRun } from "./types";
+import { CUSTOM_ENTRY_TYPES } from "./types";
+import { assertSafeAgentId } from "./sanitize";
+
+/** Which execution path owns an in-flight run (drives the boot scan's mark). */
+export type InflightRunKind = "foreground" | "unit" | "background";
+
+/** The durable per-run registry entry (one small JSON file per run id). */
+export interface InflightRun {
+	id: string;
+	dispatchId?: string;
+	attempt?: number;
+	kind: InflightRunKind;
+	owner?: ProcessOwner;
+	childMarker?: string;
+	startedAt: string;
+	cwd: string;
+	interruptedAt?: string;
+}
+
+/** Fields accepted when registering/updating an entry (cwd defaults to the process cwd). */
+export interface InflightRunInput {
+	id: string;
+	dispatchId?: string;
+	attempt?: number;
+	kind: InflightRunKind;
+	owner?: ProcessOwner;
+	childMarker?: string;
+	startedAt: string;
+	cwd?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Storage location
+// ---------------------------------------------------------------------------
+
+/**
+ * Registry directory, cwd-relative like the agent store (`.pi/subagents`).
+ * Test-only override, mirroring `__setStorageDir` — the shared temp-lifecycle
+ * fixture points it at a throwaway dir.
+ */
+let REGISTRY_DIR = ".pi/run-registry";
+
+/** TEST-ONLY: point the registry at an alternate directory. */
+export function __setRegistryDir(dir: string): void {
+	REGISTRY_DIR = dir;
+}
+
+/** The active registry directory (absolute or cwd-relative as configured). */
+export function registryDir(): string {
+	return REGISTRY_DIR;
+}
+
+// ---------------------------------------------------------------------------
+// Paths + atomic IO
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve an entry's file path, refusing anything that is not a safe UUID —
+ * ids reach this module from records loaded off disk, and `path.join` does not
+ * sanitize traversal segments (same F24 rule as the agent store).
+ */
+function resolvePath(id: string): string | null {
+	try {
+		assertSafeAgentId(id);
+	} catch {
+		return null;
+	}
+	return path.join(REGISTRY_DIR, `${id}.json`);
+}
+
+function ensureDir(): void {
+	fs.mkdirSync(REGISTRY_DIR, { recursive: true, mode: 0o700 });
+}
+
+/** True when `value` looks like a registry entry (id + kind + startedAt). */
+function isInflightRun(value: unknown): value is InflightRun {
+	if (!value || typeof value !== "object") return false;
+	const v = value as Record<string, unknown>;
+	if (typeof v.id !== "string" || typeof v.startedAt !== "string") return false;
+	return v.kind === "foreground" || v.kind === "unit" || v.kind === "background";
+}
+
+/** Parse one entry file; null on missing/corrupt/malformed. */
+function readEntry(file: string): InflightRun | null {
+	try {
+		const parsed: unknown = JSON.parse(fs.readFileSync(file, "utf-8"));
+		return isInflightRun(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Atomic, owner-only write: temp file in the same directory, then rename. */
+function writeAtomic(file: string, entry: InflightRun): boolean {
+	try {
+		ensureDir();
+		const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+		fs.writeFileSync(tmp, JSON.stringify(entry, null, 2), { encoding: "utf-8", mode: 0o600 });
+		fs.renameSync(tmp, file);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Copy only defined fields from an input onto an entry (never clobber with undefined). */
+function mergeInput(base: InflightRun, input: InflightRunInput): InflightRun {
+	const next: InflightRun = { ...base, id: input.id, kind: input.kind };
+	if (input.dispatchId !== undefined) next.dispatchId = input.dispatchId;
+	if (input.attempt !== undefined) next.attempt = input.attempt;
+	if (input.owner !== undefined) next.owner = input.owner;
+	if (input.childMarker !== undefined) next.childMarker = input.childMarker;
+	if (input.startedAt) next.startedAt = input.startedAt;
+	if (input.cwd !== undefined) next.cwd = input.cwd;
+	return next;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Register (or refresh) an in-flight run. A re-register preserves an existing
+ * `interruptedAt` so a later write cannot erase a boot-scan mark.
+ */
+export function registerInflightRun(input: InflightRunInput): boolean {
+	const file = resolvePath(input.id);
+	if (!file) return false;
+	const existing = readEntry(file);
+	const entry: InflightRun = {
+		...mergeInput(existing ?? { id: input.id, kind: input.kind, startedAt: input.startedAt, cwd: input.cwd ?? process.cwd() }, input),
+	};
+	return writeAtomic(file, entry);
+}
+
+/**
+ * Merge a defined-field patch into an existing entry. A missing entry is left
+ * missing (registration is `registerInflightRun`'s job, so a stray update can
+ * never resurrect a cleared run).
+ */
+export function updateInflightRun(input: InflightRunInput): boolean {
+	const file = resolvePath(input.id);
+	if (!file) return false;
+	const existing = readEntry(file);
+	if (!existing) return false;
+	return writeAtomic(file, mergeInput(existing, input));
+}
+
+/** Remove an entry (terminal finalize). Missing file is a no-op. */
+export function clearInflightRun(id: string): void {
+	const file = resolvePath(id);
+	if (!file) return;
+	try {
+		fs.unlinkSync(file);
+	} catch {
+		// Already cleared (or never registered) — the desired end state.
+	}
+}
+
+/** Every parseable in-flight entry; [] when the registry is absent. */
+export function listInflightRuns(): InflightRun[] {
+	let files: string[];
+	try {
+		files = fs.readdirSync(REGISTRY_DIR);
+	} catch {
+		return [];
+	}
+	const entries: InflightRun[] = [];
+	for (const file of files) {
+		if (!file.endsWith(".json")) continue;
+		const entry = readEntry(path.join(REGISTRY_DIR, file));
+		if (entry) entries.push(entry);
+	}
+	return entries;
+}
+
+/**
+ * Write the D3 `interruptedAt` mark onto an existing entry. Idempotent; returns
+ * false when the entry is absent, its id fails the write guard, or the write
+ * fails. Issue #304: this MUST never throw — the boot scan treats a false as a
+ * durable-write failure and counts it, whereas a thrown FS error would abort
+ * the whole scan via `performBootRecovery`'s catch-all. The boolean is the
+ * only truthful success signal, so callers must not assume the mark landed.
+ */
+export function markInterrupted(id: string, interruptedAt: string): boolean {
+	try {
+		const file = resolvePath(id);
+		if (!file) return false;
+		const existing = readEntry(file);
+		if (!existing) return false;
+		if (existing.interruptedAt) return true;
+		return writeAtomic(file, { ...existing, interruptedAt });
+	} catch {
+		// Belt-and-braces: the inner read/write helpers already swallow FS errors,
+		// but the scan's no-throw contract must not depend on that staying true.
+		return false;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// The persistence choke point
+// ---------------------------------------------------------------------------
+
+/** Project a run record into the registry input shape. */
+function toRegistryInput(run: SubagentRun, kind: InflightRunKind): InflightRunInput {
+	return {
+		id: run.id,
+		dispatchId: run.dispatchId,
+		attempt: run.attempt,
+		kind,
+		owner: run.owner,
+		childMarker: run.childMarker,
+		startedAt: run.startedAt,
+		cwd: process.cwd(),
+	};
+}
+
+/**
+ * The ONE run-record writer: append the session entry AND keep the registry in
+ * lockstep. `state.persistRun` delegates here and the background path calls it
+ * directly, so every write site is mirrored by construction.
+ *
+ * `kind` is required only at dispatch (`running`); terminal writes clear the
+ * registry and ignore it. A `running` write without a kind is a refresh with
+ * nothing to register — the boot scan's mark is a separate `markInterrupted`.
+ */
+export function persistRunRecord(pi: ExtensionAPI, run: SubagentRun, kind?: InflightRunKind): void {
+	if (run.status !== "running") {
+		clearInflightRun(run.id);
+	} else if (kind) {
+		registerInflightRun(toRegistryInput(run, kind));
+	}
+	pi.appendEntry(CUSTOM_ENTRY_TYPES.run, run);
+}

package/src/runner.ts

@@ -1,3 +1,4 @@
+// Purpose: Foreground execution: spawns the `pi` subprocess, parses its JSON-line stream, and folds usage.
 /**
  * brl-subagent — Process Runner
  *
@@ -25,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";
@@ -40,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)) {
@@ -219,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 });
@@ -705,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;
 
@@ -737,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)) {
@@ -788,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) => {
@@ -812,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:
@@ -841,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

@@ -1,3 +1,4 @@
+// Purpose: Input validation, environment allowlisting, and output sanitization (task, cwd, outputFile, agent ids).
 /**
  * brl-subagent — Sanitization (F1, F2, F3)
  *
@@ -7,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
@@ -208,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.
@@ -215,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;
 
@@ -226,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 {
@@ -353,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/scheduler.ts

@@ -1,3 +1,4 @@
+// Purpose: Dependency-graph scheduler: cycle detection, topological waves, and graph validation.
 /**
  * brl-subagent — Dependency Graph Scheduler
  *