brl-subagent 2.4.0 → 2.5.0

package/src/kill-escalation.ts

@@ -0,0 +1,94 @@
+// Purpose: The one SIGTERM → grace → SIGKILL escalation shared by foreground reap, abort/timeout, and boot recovery.
+/**
+ * Process kill escalation (Option B U1, review items B4 + B7).
+ *
+ * The SIGTERM → grace → SIGKILL sequence was duplicated four times with
+ * inconsistent wait semantics. This module owns the ONE sequence; each site
+ * supplies its own targets and death check:
+ *
+ *   - `runner.ts` `reapActiveChildren` — every tracked foreground child at once
+ *   - `runner.ts` abort handler          — one child
+ *   - `runner.ts` timeout handler        — one child
+ *   - `recovery.ts` `reapPids`           — every marker-verified orphan at once
+ *
+ * Order is terminate → wait → force-kill. With `pollMs` set the wait ends as
+ * soon as every target verifies dead (B4: the shutdown reap no longer blocks
+ * the full 5 s when children exit promptly), bounded by `graceMs`; without it
+ * the helper waits the full grace once (the boot scan's wait-once shape).
+ *
+ * `verifyDeath` is supplied per site but must always answer "is the process
+ * REALLY dead" — for a child, `exitCode`/`signalCode`; for a pid, `kill -0`
+ * liveness. It must never be a "a signal was delivered" check: `child.killed`
+ * flips when SIGTERM is SENT, so gating SIGKILL on it skips escalation for a
+ * SIGTERM-ignoring child (issue #303). What is shared is the
+ * terminate-then-escalate order and the no-throw-on-vanished discipline.
+ */
+
+/** A process handle the escalation helper can signal and liveness-check. */
+export interface EscalationTarget {
+	/** Send SIGTERM; may throw when the target is already gone. */
+	terminate(): void;
+	/** Send SIGKILL; may throw when the target is already gone. */
+	forceKill(): void;
+	/** True when the target is confirmed dead (so no SIGKILL is needed). */
+	verifyDeath(): boolean;
+}
+
+export interface EscalationOptions {
+	/** Grace window between SIGTERM and SIGKILL (ms). */
+	graceMs: number;
+	/** Sleep between SIGTERM and the liveness re-check (injectable). */
+	sleep(ms: number): Promise<void>;
+	/**
+	 * Poll interval for the early-exit wait (B4). When > 0 the helper returns as
+	 * soon as every target verifies dead, bounded by `graceMs`; when omitted the
+	 * helper waits the full `graceMs` once.
+	 */
+	pollMs?: number;
+	/** Injectable clock for the deadline (defaults to Date.now). */
+	now?(): number;
+}
+
+/**
+ * Escalate every target together: SIGTERM all, wait (at most) one grace window,
+ * then SIGKILL every target that still verifies alive. Returns the survivors.
+ * Never throws on a target that vanished mid-sequence.
+ */
+export async function escalateKill(
+	targets: EscalationTarget[],
+	options: EscalationOptions,
+): Promise<EscalationTarget[]> {
+	for (const target of targets) {
+		try {
+			target.terminate();
+		} catch {
+			// Already gone — the desired end state.
+		}
+	}
+
+	if (targets.length > 0) {
+		const pollMs = options.pollMs ?? 0;
+		if (pollMs > 0) {
+			const now = options.now ?? Date.now;
+			const deadline = now() + options.graceMs;
+			while (now() < deadline && !targets.every((target) => target.verifyDeath())) {
+				const remaining = Math.max(deadline - now(), 1);
+				await options.sleep(Math.min(pollMs, remaining));
+			}
+		} else {
+			await options.sleep(options.graceMs);
+		}
+	}
+
+	const survivors: EscalationTarget[] = [];
+	for (const target of targets) {
+		if (target.verifyDeath()) continue;
+		try {
+			target.forceKill();
+		} catch {
+			// Exited between the liveness check and the signal.
+		}
+		if (!target.verifyDeath()) survivors.push(target);
+	}
+	return survivors;
+}

package/src/logging.ts

@@ -48,6 +48,12 @@ const LOG_LEVEL_NAMES: readonly LogLevel[] = ["debug", "info", "warn", "error"];
 /** Current minimum log level — can be changed at runtime */
 let minLevel: LogLevel = resolveInitialLogLevel();
 
+/**
+ * Whether the console mirror is enabled — opt-in via BRL_LOG_CONSOLE (issue #265).
+ * File-only is the default so extension logging never corrupts the pi TUI.
+ */
+let consoleOutput: boolean = resolveInitialConsoleOutput();
+
 /**
  * Issue #235: the log verbosity knob was never wired, so the three `log.debug()`
  * call sites were permanently suppressed with no way to turn them on.
@@ -64,6 +70,22 @@ function resolveInitialLogLevel(): LogLevel {
 	return "info";
 }
 
+/**
+ * Issue #265: extension code runs inside pi's TUI process, so a raw console
+ * write lands wherever the renderer's cursor sits and corrupts the display.
+ * File-only is the default; `BRL_LOG_CONSOLE` opts the terminal mirror back in.
+ * Read ONCE at module load for the same reason as BRL_LOG_LEVEL — logger call
+ * sites are spread across the codebase. Accepts `1|true|yes`; anything else is
+ * off. `setConsoleOutput()` remains the programmatic override.
+ *
+ * Explicitly NOT gated on process.stdout.isTTY: in pi print mode stdout IS the
+ * result channel, so that test is exactly backwards.
+ */
+function resolveInitialConsoleOutput(): boolean {
+	const raw = process.env.BRL_LOG_CONSOLE?.trim().toLowerCase();
+	return raw === "1" || raw === "true" || raw === "yes";
+}
+
 // ---------------------------------------------------------------------------
 // Logger
 // ---------------------------------------------------------------------------
@@ -79,6 +101,15 @@ export function setLogLevel(level: LogLevel): void {
 	minLevel = level;
 }
 
+/**
+ * Programmatic override for the console mirror (issue #265). Mirrors
+ * setLogLevel: module-level state, so tests can toggle it without re-reading
+ * the environment.
+ */
+export function setConsoleOutput(enabled: boolean): void {
+	consoleOutput = enabled;
+}
+
 // Issue #179 (D6): createLogger() runs at MODULE LOAD (index.ts,
 // session-manager.ts) where the session cwd does not exist yet. The cwd is set
 // later from the session_start hook (ctx.cwd). All logger instances share this
@@ -121,9 +152,12 @@ export function createLogger(prefix: string, cwd?: string): Logger {
 
 		const line = JSON.stringify(entry);
 
-		// Console output
-		const consoleMethod = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
-		consoleMethod(`[${prefix}] ${level.toUpperCase()}: ${message}`);
+		// Console mirror — opt-in (issue #265). Off by default so a logger call
+		// can never corrupt the pi TUI renderer; BRL_LOG_CONSOLE opts back in.
+		if (consoleOutput) {
+			const consoleMethod = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
+			consoleMethod(`[${prefix}] ${level.toUpperCase()}: ${message}`);
+		}
 
 		// File output — resolved on each call because the cwd may be set after
 		// createLogger ran (module load) but before the first entry.

package/src/preflight.ts

@@ -22,6 +22,33 @@ export type PreflightResult = { ok: true } | { ok: false; error: string };
 // Checks
 // ---------------------------------------------------------------------------
 
+/**
+ * Walk PATH for an executable `pi`, returning the first match.
+ *
+ * Mirrors the spawn-time fallback in `getPiInvocation` (the bare `"pi"`
+ * case). Shared with the Tier-2 e2e harness (issue #271) so the preflight
+ * check and the harness resolve the real binary identically.
+ */
+export function resolvePiOnPath(): string | undefined {
+	const pathDirs = (process.env.PATH || "").split(path.delimiter);
+	const isWindows = process.platform === "win32";
+	const piNames = isWindows ? ["pi.cmd", "pi.exe", "pi"] : ["pi"];
+
+	for (const dir of pathDirs) {
+		for (const name of piNames) {
+			const fullPath = path.join(dir, name);
+			try {
+				fs.accessSync(fullPath, fs.constants.X_OK);
+				return fullPath;
+			} catch {
+				// Not found in this directory — continue searching
+			}
+		}
+	}
+
+	return undefined;
+}
+
 /**
  * Verify the pi binary is accessible via the same resolution logic used
  * at spawn time. When `getPiInvocation` falls back to "pi" on PATH, we
@@ -45,20 +72,8 @@ function checkPiBinary(): PreflightResult {
 	}
 
 	// "pi" fallback — search PATH
-	const pathDirs = (process.env.PATH || "").split(path.delimiter);
-	const isWindows = process.platform === "win32";
-	const piNames = isWindows ? ["pi.cmd", "pi.exe", "pi"] : ["pi"];
-
-	for (const dir of pathDirs) {
-		for (const name of piNames) {
-			const fullPath = path.join(dir, name);
-			try {
-				fs.accessSync(fullPath, fs.constants.X_OK);
-				return { ok: true };
-			} catch {
-				// Not found in this directory — continue searching
-			}
-		}
+	if (resolvePiOnPath()) {
+		return { ok: true };
 	}
 
 	return {

package/src/proc.ts

@@ -0,0 +1,140 @@
+// Purpose: Production process primitives — Linux/POSIX /proc reads, feature detection, and the default recovery deps.
+/**
+ * Option B U1 — production process wiring for the recovery engine.
+ *
+ * The recovery decision engine (`src/recovery-engine.ts`) is pure over the
+ * injected `RecoveryDeps`. This module supplies the REAL deps: the Linux/POSIX
+ * `/proc` start-time token (`/proc/<pid>/stat` field 22), the child-marker scan
+ * (`/proc/<pid>/environ`), cross-platform pid liveness, and the default
+ * `RecoveryDeps` assembly.
+ *
+ * PLATFORM BOUNDARY (required): the start token and marker scan are Linux/POSIX
+ * reads. `isProcAvailable()` feature-detects them (cached; the answer cannot
+ * change mid-process). Where they are unavailable, `pidAlive` still works but
+ * on its own cannot rule out pid reuse — so the boot scan skips entirely and
+ * nothing is killed or marked unverified (`recoverProduction`, src/recovery.ts).
+ *
+ * `__setProcAvailableForTest` is the injectable seam that lets a test exercise
+ * that platform guard without mocking `node:fs` module-wide.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ProcessOwner } from "./types";
+import { SIGKILL_GRACE_MS } from "./types";
+import { CHILD_MARKER_ENV_KEY } from "./sanitize";
+import type { RecoveryDeps } from "./recovery-engine";
+
+const PROC_ROOT = "/proc";
+
+let procAvailable: boolean | undefined;
+let procAvailableOverride: boolean | undefined;
+
+/**
+ * TEST-ONLY: force the `/proc` feature-detection answer (undefined restores the
+ * real detection and clears the cache). The production scan consults this
+ * through `isProcAvailable`, so the platform guard is exercisable in-repo.
+ */
+export function __setProcAvailableForTest(value: boolean | undefined): void {
+	procAvailableOverride = value;
+	procAvailable = undefined;
+}
+
+/**
+ * Feature-detect the Linux/POSIX `/proc` surface this module needs. Cached:
+ * the answer cannot change mid-process. Exported so the entry point can skip
+ * the whole scan with one log line on platforms without /proc.
+ */
+export function isProcAvailable(): boolean {
+	if (procAvailableOverride !== undefined) return procAvailableOverride;
+	if (procAvailable === undefined) {
+		try {
+			procAvailable = fs.existsSync(path.join(PROC_ROOT, "self", "stat"));
+		} catch {
+			procAvailable = false;
+		}
+	}
+	return procAvailable;
+}
+
+/**
+ * Read a process's start-time token — `/proc/<pid>/stat` field 22 (1-indexed),
+ * i.e. index 19 of the whitespace-split fields AFTER the `(comm)` field. The
+ * comm field is skipped by slicing at the LAST `)` so a name containing spaces
+ * or parens cannot shift the parse. Returns undefined when /proc is
+ * unavailable, the pid is invalid, or the process vanished.
+ */
+export function readStartToken(pid: number): string | undefined {
+	if (!isProcAvailable() || !Number.isInteger(pid) || pid <= 0) return undefined;
+	try {
+		const stat = fs.readFileSync(path.join(PROC_ROOT, String(pid), "stat"), "utf-8");
+		const close = stat.lastIndexOf(")");
+		if (close < 0) return undefined;
+		const rest = stat.slice(close + 1).trim();
+		if (!rest) return undefined;
+		const fields = rest.split(/\s+/);
+		const token = fields[19];
+		return token && /^\d+$/.test(token) ? token : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** The CURRENT process's owner identity (pid + start token; empty string when unavailable). */
+export function currentProcessOwner(): ProcessOwner {
+	return { pid: process.pid, start: readStartToken(process.pid) ?? "" };
+}
+
+/** Cross-platform pid liveness (`kill -0`). EPERM means the process exists. */
+export function pidAlive(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return (err as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/**
+ * Pids whose environment carries the marker. Scans `/proc/<pid>/environ` (NUL
+ * separated). Skips this process; unreadable/vanished processes are ignored.
+ * Returns [] — never a kill — when /proc is unavailable.
+ */
+export function findByMarker(marker: string): number[] {
+	if (!marker || !isProcAvailable()) return [];
+	const needle = `${CHILD_MARKER_ENV_KEY}=${marker}`;
+	const found: number[] = [];
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(PROC_ROOT);
+	} catch {
+		return [];
+	}
+	for (const entry of entries) {
+		if (!/^\d+$/.test(entry)) continue;
+		const pid = Number(entry);
+		if (pid === process.pid) continue;
+		try {
+			const environ = fs.readFileSync(path.join(PROC_ROOT, entry, "environ"), "utf-8");
+			if (environ.split("\0").includes(needle)) found.push(pid);
+		} catch {
+			// Vanished or not readable by this user — not a verified match.
+		}
+	}
+	return found;
+}
+
+/** The real production dependencies (Linux/POSIX /proc reads + process signals). */
+export function defaultRecoveryDeps(): RecoveryDeps {
+	return {
+		pidAlive,
+		startTokenOf: readStartToken,
+		findByMarker,
+		kill: (pid, signal) => {
+			process.kill(pid, signal);
+		},
+		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+		graceMs: SIGKILL_GRACE_MS,
+	};
+}

package/src/recovery-engine.ts

@@ -0,0 +1,262 @@
+// Purpose: Pure recovery decision engine — identity, owner liveness classification, and the boot-scan plan over injected process deps.
+/**
+ * Option B U1 — recovery decision engine (pure over `RecoveryDeps`).
+ *
+ * The engine decides, for one persisted `running` record, whether its
+ * conductor is still live, whether to reject ownership, and whether to reap a
+ * marker-verified orphan child. It performs NO process work itself: every
+ * effect goes through the injected `RecoveryDeps`, so the full matrix is
+ * unit-testable without spawning processes. The boot orchestration lives in
+ * `src/recovery.ts`; the production `/proc` wiring in `src/proc.ts`.
+ *
+ * Decision order (`decideRecovery`):
+ *   - status not "running" → skip
+ *   - `interruptedAt` already set → never re-mark, but re-check for a leftover
+ *     live marker child and reap it again (B2 revisit)
+ *   - absent owner → skip (`no-owner`)
+ *   - owner present but unparsable → mark-only (`owner-unverifiable`), no kill
+ *   - owner alive (pid + start token match) → leave untouched
+ *   - owner alive but token unreadable → skip (`ownership-unverifiable`)
+ *   - owner dead → reap marker-verified orphan children, then mark
+ *
+ * Reaping is the ONE `escalateKill` sequence (src/kill-escalation.ts): SIGTERM
+ * every pid, wait one grace window, SIGKILL any survivor.
+ */
+
+import type { ProcessOwner, SubagentRun } from "./types";
+import { resolveTerminalRunEntry } from "./state";
+import { escalateKill, type EscalationTarget } from "./kill-escalation";
+
+// ---------------------------------------------------------------------------
+// Dependency injection surface
+// ---------------------------------------------------------------------------
+
+/** The process primitives the decision engine needs (injected for testability). */
+export interface RecoveryDeps {
+	/** True when the pid exists (SIGCONT/`kill -0` semantics; EPERM counts as alive). */
+	pidAlive(pid: number): boolean;
+	/** The process start-time token, or undefined when /proc is unavailable/unreadable. */
+	startTokenOf(pid: number): string | undefined;
+	/** Pids whose environment carries `CHILD_MARKER_ENV_KEY=<marker>`; [] when /proc is unavailable. */
+	findByMarker(marker: string): number[];
+	/** Send a signal to a pid (may throw when the pid is already gone). */
+	kill(pid: number, signal: NodeJS.Signals): void;
+	/** Sleep between SIGTERM and SIGKILL. */
+	sleep(ms: number): Promise<void>;
+	/** Grace period in ms between SIGTERM and SIGKILL. */
+	graceMs: number;
+}
+
+/** Which persisted store a candidate record came from. */
+export type RecoveryKind = "run" | "agent";
+
+/** A persisted `running` record projected into the shape the engine reasons over. */
+export interface RecoveryRecord {
+	id: string;
+	kind: RecoveryKind;
+	status: string;
+	interruptedAt?: string;
+	owner?: ProcessOwner;
+	childMarker?: string;
+	/** Original record for the caller's write-back; opaque to this module. */
+	source?: unknown;
+}
+
+export type RecoverySkipReason =
+	| "not-running"
+	| "already-interrupted"
+	| "no-owner"
+	| "owner-alive"
+	| "ownership-unverifiable";
+
+export type RecoveryMarkReason = "owner-dead" | "child-orphaned" | "owner-unverifiable";
+
+/** What the engine decided to do with one record (before any process work). */
+export type RecoveryPlan =
+	| { decision: "skip"; reason: RecoverySkipReason }
+	| { decision: "mark"; reason: RecoveryMarkReason; reap: number[] }
+	/** Already-marked record re-checked this boot: reap leftovers, never re-mark. */
+	| { decision: "reap"; reason: "revisit-interrupted"; reap: number[] };
+
+/** The engine's verdict on an owner identity. */
+export type OwnerState = "alive" | "dead" | "unknown";
+
+/** The result of applying a plan (kills performed, survivors logged). */
+export interface RecoveryOutcome {
+	id: string;
+	kind: RecoveryKind;
+	decision: "skip" | "mark" | "reap";
+	reason: string;
+	reaped: number[];
+	survived: number[];
+}
+
+// ---------------------------------------------------------------------------
+// Candidate projection
+// ---------------------------------------------------------------------------
+
+/**
+ * Durability identity for a newly dispatched run record. A retry inherits the
+ * original's dispatchId and records `resumeOf`/`attempt`; a fresh dispatch
+ * mints a new dispatchId with attempt 1. These are RECORD fields, not
+ * delegate_task params (D4).
+ */
+export function newDispatchIdentity(source: SubagentRun | undefined): {
+	dispatchId: string;
+	resumeOf?: string;
+	attempt: number;
+} {
+	return {
+		dispatchId: source?.dispatchId ?? crypto.randomUUID(),
+		resumeOf: source?.id,
+		attempt: source ? (source.attempt ?? 1) + 1 : 1,
+	};
+}
+
+/**
+ * Collapse run entries to ONE per id before the scan, using the ONE shared
+ * preference rule (`resolveTerminalRunEntry`, src/state.ts): terminal-first;
+ * among non-terminal entries the D3 `interruptedAt` mark wins over the
+ * original spawn entry; otherwise the first entry seen. Ids keep their
+ * first-seen order. Delegating keeps the recovery scan and U3's display/retry
+ * lookup from diverging (the historical duplicate rule picked the marked clone
+ * while the resolver picked the unmarked spawn).
+ */
+export function dedupeRunEntriesById(runs: SubagentRun[]): SubagentRun[] {
+	const ids: string[] = [];
+	const seen = new Set<string>();
+	for (const run of runs) {
+		if (seen.has(run.id)) continue;
+		seen.add(run.id);
+		ids.push(run.id);
+	}
+	const collapsed: SubagentRun[] = [];
+	for (const id of ids) {
+		const resolved = resolveTerminalRunEntry(runs, id);
+		if (resolved) collapsed.push(resolved);
+	}
+	return collapsed;
+}
+
+// ---------------------------------------------------------------------------
+// The decision engine (pure over RecoveryDeps)
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify the recorded owner's liveness. `unknown` means the pid is alive but
+ * the start token could not be read, so pid reuse cannot be excluded — the
+ * caller must not act on it.
+ */
+export function classifyOwner(owner: ProcessOwner, deps: RecoveryDeps): OwnerState {
+	if (!deps.pidAlive(owner.pid)) return "dead";
+	// An empty recorded token means the WRITER could not read one (non-/proc
+	// platform). Even on a host that can read tokens now, the record's identity
+	// is unverifiable — never act on it.
+	if (!owner.start) return "unknown";
+	const token = deps.startTokenOf(owner.pid);
+	if (token === undefined) return "unknown";
+	return token === owner.start ? "alive" : "dead";
+}
+
+/**
+ * True when an owner carries a usable pid (positive integer). Anything else —
+ * a missing pid, a string, 0, a negative, NaN, a fraction — is UNPARSABLE
+ * ownership: the record is marked but the kill path is never touched.
+ */
+function hasParsableOwnerPid(owner: ProcessOwner): boolean {
+	return Number.isInteger(owner.pid) && owner.pid > 0;
+}
+
+/**
+ * Decide what to do with one persisted record. Pure — no process is touched.
+ * Reaping pids come ONLY from a marker scan: without a verified marker match
+ * the engine never proposes a kill. An unparsable owner is mark-only (see the
+ * module header's three-way owner policy): interrupt is certain, ownership is
+ * not, so `reap` is empty and the kill path stays untouched.
+ */
+export function decideRecovery(record: RecoveryRecord, deps: RecoveryDeps): RecoveryPlan {
+	if (record.status !== "running") return { decision: "skip", reason: "not-running" };
+	if (record.interruptedAt) {
+		// Already marked: NEVER re-mark (idempotent), but a SIGKILL survivor or a
+		// child whose marker was unreadable at mark time must stay revisitable.
+		// The registry entry is retained, so every later boot re-checks it.
+		const reap = record.childMarker ? deps.findByMarker(record.childMarker) : [];
+		return reap.length > 0
+			? { decision: "reap", reason: "revisit-interrupted", reap }
+			: { decision: "skip", reason: "already-interrupted" };
+	}
+	if (!record.owner) return { decision: "skip", reason: "no-owner" };
+	if (!hasParsableOwnerPid(record.owner)) {
+		return { decision: "mark", reason: "owner-unverifiable", reap: [] };
+	}
+
+	const ownerState = classifyOwner(record.owner, deps);
+	if (ownerState === "alive") return { decision: "skip", reason: "owner-alive" };
+	if (ownerState === "unknown") return { decision: "skip", reason: "ownership-unverifiable" };
+
+	const reap = record.childMarker ? deps.findByMarker(record.childMarker) : [];
+	return {
+		decision: "mark",
+		reason: reap.length > 0 ? "child-orphaned" : "owner-dead",
+		reap,
+	};
+}
+
+/**
+ * Escalate a set of pids together: SIGTERM every one, wait ONE grace window,
+ * then SIGKILL any survivor. Returns the pids still alive afterwards. Thin
+ * adapter over the shared `escalateKill` helper (src/kill-escalation.ts), which
+ * `recoverRecord` (one record) and `runBootScan` (the whole scan) both call, so
+ * a boot with N orphans waits one grace period total, never N.
+ */
+export async function reapPids(pids: number[], deps: RecoveryDeps): Promise<number[]> {
+	const unique = [...new Set(pids)];
+	const targets: EscalationTarget[] = unique.map((pid) => ({
+		terminate: () => {
+			deps.kill(pid, "SIGTERM");
+		},
+		forceKill: () => {
+			deps.kill(pid, "SIGKILL");
+		},
+		verifyDeath: () => !deps.pidAlive(pid),
+	}));
+	const survivors = await escalateKill(targets, {
+		graceMs: deps.graceMs,
+		sleep: deps.sleep,
+	});
+	const survivedSet = new Set(survivors);
+	return unique.filter((_, index) => survivedSet.has(targets[index]));
+}
+
+/**
+ * Apply a record's plan: SIGTERM every marker-verified orphan, wait the grace
+ * period, SIGKILL any survivor, then report. Never throws on a vanished pid.
+ */
+export async function recoverRecord(
+	record: RecoveryRecord,
+	deps: RecoveryDeps,
+): Promise<RecoveryOutcome> {
+	const plan = decideRecovery(record, deps);
+	if (plan.decision === "skip") {
+		return {
+			id: record.id,
+			kind: record.kind,
+			decision: "skip",
+			reason: plan.reason,
+			reaped: [],
+			survived: [],
+		};
+	}
+
+	const reaped = [...new Set(plan.reap)];
+	const survived = await reapPids(reaped, deps);
+
+	return {
+		id: record.id,
+		kind: record.kind,
+		decision: plan.decision,
+		reason: plan.reason,
+		reaped,
+		survived,
+	};
+}