pi-crew 0.11.40 → 0.11.42

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-crew",
-	"version": "0.11.40",
+	"version": "0.11.42",
 	"description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
 	"author": "baphuongna",
 	"license": "MIT",

package/src/runtime/foreground-watchdog.ts

@@ -6,7 +6,9 @@
  * assistant has no way to know when a run completes or gets stuck without
  * manual polling. This watchdog monitors active runs and:
  *
- * 1. Detects hung runs (active status, no heartbeat update for >10 min)
+ * 1. Detects hung runs (active status, manifest not updated for >2 min with
+ *    no agent activity evidence — wave 13: a live registry claim or a fresh
+ *    task heartbeat withholds the verdict, see CLAIMED_RUN_HUNG_MS)
  * 2. Injects a followUp message via pi.sendUserMessage() so the assistant
  *    is automatically notified — no manual sleep+check needed.
  * 3. Cleans up after itself when the run completes or the session ends.
@@ -19,6 +21,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getCrewEnv, getCrewEnvInt } from "../config/env-vars.ts";
 import { TEAM_TERMINAL_TASK_STATUSES } from "../state/contracts.ts";
+import { activeRunEntries } from "../state/stores/active-run-registry.ts";
 import { loadRunManifestById } from "../state/stores/state-store.ts";
 import type { TeamTaskState } from "../state/types.ts";
 import { readCrewAgents } from "./crew-agent-records.ts";
@@ -128,6 +131,170 @@ function resolveCheckIntervalMs(overrideMs: number | undefined): number {
 	return DEFAULT_CHECK_INTERVAL_MS;
 }
 
+// ── Wave 13 (F1, GAP-0): hung-verdict liveness short-circuit ────────────────
+//
+// Live evidence (2026-10-24/25): five false "appears hung" alerts in one
+// session, all direct single-agent runs executing ONE long tool call (a
+// 20-min CI poll loop, a 20-min test suite). The hung verdict
+// (isLikelyOrphanedActiveRun: manifest stale ≥2 min + no agent activity
+// within 5 min) is structurally blind while a tool executes — every
+// liveness write is event-driven and no pi events fire mid-tool — so a
+// HEALTHY run reads as hung ~5-10 min into a long tool. The two signals
+// other consumers already trust, and this verdict ignores, are consulted
+// here IN THE WATCHDOG (never inside isLikelyOrphanedActiveRun — that
+// predicate is shared with the dashboard's isDisplayActiveRun, GAP-4):
+//   (a) a LIVE active-run-registry claim, and
+//   (b) a fresh task heartbeat (kept fresh through long tools by F2's
+//       live-executor timer).
+// The two branches are INDEPENDENT ORs: the registry drops non-async
+// entries once the manifest is >30 min stale, so past that horizon only the
+// heartbeat carries liveness — never require both.
+
+/**
+ * Wave 13 (F1, GAP-0): hard ceiling for how long a LIVE active-run-registry
+ * claim can shield a run from the watchdog's hung verdict. A claimed run
+ * whose NEWEST liveness evidence (claim assertion time, task heartbeats/
+ * activity) is older than this still alerts — a genuine in-process deadlock
+ * (claim held, nothing progressing) is still caught — while healthy claimed
+ * runs mid-long-tool are not false-alarmed by the 2-min ladder. 45 min is
+ * 1.5× the registry's own 30-min freshness horizon and 9× the 5-min activity
+ * shield, so only a truly stuck claim trips it. Unclaimed runs keep the
+ * fast 2-min ladder unchanged; ORPHANED_ACTIVE_RUN_MS (process-status.ts,
+ * shared with the dashboard — GAP-4) is NOT touched.
+ */
+export const CLAIMED_RUN_HUNG_MS = 45 * 60 * 1000;
+
+/**
+ * Wave 13 (F1): freshness window for task-heartbeat liveness evidence —
+ * mirrors ACTIVE_EVIDENCE_TTL_MS in stale-reconciler.ts (5 min).
+ */
+const TASK_HEARTBEAT_EVIDENCE_MS = 5 * 60 * 1000;
+
+/**
+ * Wave 13 (F1): read-only active-run-registry claim consult result.
+ * `claimedAtMs` is the registry entry's `updatedAt` (the moment the claim
+ * was asserted — registerActiveRun fires at dispatch); undefined when the
+ * entry carries no parseable timestamp.
+ */
+interface LiveRunClaim {
+	claimedAtMs?: number;
+}
+
+/**
+ * Wave 13 (F1, GAP-0): consult the active-run registry for a LIVE claim on
+ * `runId`. Read-only mirror of findLiveRegistryEntry (stale-reconciler G24):
+ * activeRunEntries() applies the full liveness filter itself (terminal
+ * status, dead async PID, >30-min-stale non-async manifests, symlink
+ * safety), so an entry found here means some live session/runner claims the
+ * run RIGHT NOW. Inlined via the registry store instead of importing
+ * stale-reconciler (its reaping graph must not enter the watchdog's import
+ * closure); the async-PID half of hasLiveRunClaim is deliberately omitted —
+ * async runs never reach this verdict path (isLikelyOrphanedActiveRun
+ * excludes them). Fail-open: any registry error ⇒ no claim — a broken
+ * registry must never shield a genuinely hung run (G24 contract).
+ */
+function consultActiveRunRegistry(runId: string): LiveRunClaim | undefined {
+	try {
+		const entry = activeRunEntries().find((item) => item.runId === runId);
+		if (!entry) return undefined;
+		const claimedAtMs = entry.updatedAt ? Date.parse(entry.updatedAt) : Number.NaN;
+		return { claimedAtMs: Number.isFinite(claimedAtMs) ? claimedAtMs : undefined };
+	} catch {
+		return undefined;
+	}
+}
+
+let liveClaimConsult: (runId: string) => LiveRunClaim | undefined = consultActiveRunRegistry;
+
+/** @internal Test seam — replace the registry claim consult (null = real). */
+export function setLiveClaimConsultForTests(consult: ((runId: string) => LiveRunClaim | undefined) | null): void {
+	liveClaimConsult = consult ?? consultActiveRunRegistry;
+}
+
+/**
+ * Wave 13 (F1): does any running/waiting task carry FRESH live evidence?
+ * Behavioral mirror of hasRecentActiveEvidence (stale-reconciler.ts): a
+ * running/waiting task whose `heartbeat.lastSeenAt` (with `alive !== false`)
+ * or `agentProgress.lastActivityAt` is within TASK_HEARTBEAT_EVIDENCE_MS
+ * counts. Absent/unreadable tasks (`[]`) ⇒ false — fail-open to the ladder,
+ * same as WD-STALE-RECORD.
+ */
+function hasFreshTaskHeartbeatEvidence(tasks: TeamTaskState[] | undefined, now: number): boolean {
+	if (!Array.isArray(tasks)) return false;
+	return tasks.some((task) => {
+		if (task.status !== "running" && task.status !== "waiting") return false;
+		const heartbeatAt = task.heartbeat?.lastSeenAt ? new Date(task.heartbeat.lastSeenAt).getTime() : Number.NaN;
+		if (task.heartbeat?.alive !== false && Number.isFinite(heartbeatAt) && now - heartbeatAt <= TASK_HEARTBEAT_EVIDENCE_MS) return true;
+		const activityAt = task.agentProgress?.lastActivityAt ? new Date(task.agentProgress.lastActivityAt).getTime() : Number.NaN;
+		return Number.isFinite(activityAt) && now - activityAt <= TASK_HEARTBEAT_EVIDENCE_MS;
+	});
+}
+
+/**
+ * Wave 13 (F1): newest liveness-evidence timestamp (epoch ms) among the
+ * claim assertion time and the running/waiting tasks' heartbeat/activity
+ * marks — everything EXCEPT manifest.updatedAt, which is the frozen
+ * artifact under judgment, not evidence (the registry's own filter already
+ * bounds it at 30 min for entry presence; counting it here would make the
+ * CLAIMED_RUN_HUNG_MS ceiling unreachable). undefined when no signal
+ * carries a finite timestamp.
+ */
+function newestClaimEvidenceMs(tasks: TeamTaskState[] | undefined, claim: LiveRunClaim): number | undefined {
+	let newest: number | undefined;
+	const consider = (ms: number): void => {
+		if (Number.isFinite(ms) && (newest === undefined || ms > newest)) newest = ms;
+	};
+	if (claim.claimedAtMs !== undefined) consider(claim.claimedAtMs);
+	for (const task of tasks ?? []) {
+		if (task.status !== "running" && task.status !== "waiting") continue;
+		const heartbeatAt = task.heartbeat?.lastSeenAt ? new Date(task.heartbeat.lastSeenAt).getTime() : Number.NaN;
+		consider(heartbeatAt);
+		const activityAt = task.agentProgress?.lastActivityAt ? new Date(task.agentProgress.lastActivityAt).getTime() : Number.NaN;
+		consider(activityAt);
+	}
+	return newest;
+}
+
+/** Wave 13 (F1): hung-verdict liveness short-circuit result. */
+interface LivenessShortCircuit {
+	/** True ⇒ the hung verdict is withheld this cycle (live evidence present). */
+	suppress: boolean;
+	/** Debug-log reason (PI_CREW_DEBUG-gated). */
+	reason: string;
+	/** Claim present but its evidence aged past CLAIMED_RUN_HUNG_MS — the alert detail must name it. */
+	claimExhausted: boolean;
+}
+
+/**
+ * Wave 13 (F1, GAP-0): should the hung verdict for this cycle be withheld?
+ * Two INDEPENDENT OR branches (never require both):
+ *   (b) a fresh task heartbeat (≤5 min) ⇒ suppress outright;
+ *   (a) a live registry claim ⇒ suppress while the newest liveness evidence
+ *       is ≤ CLAIMED_RUN_HUNG_MS old; past the ceiling the ladder proceeds
+ *       (claimExhausted ⇒ the alert names the claimed-run threshold).
+ * No claim and no fresh heartbeat ⇒ the existing 2-min ladder is unchanged
+ * (an unclaimed zombie still alerts fast).
+ */
+function assessClaimedRunLiveness(runId: string, tasks: TeamTaskState[] | undefined, now: number): LivenessShortCircuit {
+	if (hasFreshTaskHeartbeatEvidence(tasks, now)) {
+		return { suppress: true, reason: "fresh task heartbeat", claimExhausted: false };
+	}
+	const claim = liveClaimConsult(runId);
+	if (claim) {
+		const evidenceMs = newestClaimEvidenceMs(tasks, claim);
+		const evidenceAgeMs = evidenceMs !== undefined ? now - evidenceMs : undefined;
+		if (evidenceAgeMs !== undefined && evidenceAgeMs <= CLAIMED_RUN_HUNG_MS) {
+			return {
+				suppress: true,
+				reason: `live registry claim (newest evidence ${Math.max(0, Math.round(evidenceAgeMs / 1000))}s old)`,
+				claimExhausted: false,
+			};
+		}
+		return { suppress: false, reason: "claim evidence older than CLAIMED_RUN_HUNG_MS", claimExhausted: true };
+	}
+	return { suppress: false, reason: "no live claim", claimExhausted: false };
+}
+
 /**
  * Pre-emit state re-verify loader. Injectable for tests to simulate the run
  * going terminal between the cycle's initial read and the emit point.
@@ -471,39 +638,59 @@ export function startForegroundWatchdog(opts: WatchdogOptions): void {
 					// Keep monitoring: if the manifest eventually finalizes, the
 					// terminal branch delivers the completion notice.
 				} else {
-					const detail = `status=${manifest.status}, updatedAt=${manifest.updatedAt}, agents=${agents.length}`;
-					consecutiveHungNotices += 1;
-					try {
-						if (consecutiveHungNotices <= HUNG_NOTICE_CAP) {
-							// WD-DEDUP: alert-once per runId at module scope — even a
-							// fresh watchdog instance must not re-alert the same run.
-							if (!hungAlertAlreadySent(runId)) {
-								// Mark BEFORE queueing so a racing cycle cannot double-queue.
-								updateHungAlertRecord(runId, { alerted: true });
-								// WD-DELIVER-GUARD: the host queues a followUp while the
-								// session streams and delivers it arbitrarily later — so
-								// hand it over only at the idle boundary, re-verifying the
-								// run state at THAT moment.
+					// Wave 13 (F1, GAP-0): liveness short-circuit BEFORE any hung alert.
+					// The verdict above is structurally blind while a tool executes; a
+					// live registry claim or fresh task heartbeat withholds it. A
+					// suppressed cycle means the run left the hung state — reset the
+					// no-progress counter so a later genuine alert gets the full drip cap.
+					const liveness = assessClaimedRunLiveness(runId, reverified.tasks, now);
+					if (liveness.suppress) {
+						consecutiveHungNotices = 0;
+						debugLog(`[foreground-watchdog] suppress hung verdict for ${runId}: ${liveness.reason}`);
+					} else {
+						// Wave 13 (F3, GAP-2): the detail carries its EVIDENCE time (the
+						// manifest read the verdict was based on) — "as of <ISO>" — not the
+						// emit time, so a user re-checking can tell a stale/queued alert
+						// apart from one about the last few minutes. An exhausted claim
+						// names the claimed-run threshold so the user knows it is not the
+						// 2-min ladder.
+						const claimNote = liveness.claimExhausted
+							? `, claimed-run hung threshold exceeded (no live evidence for >${Math.round(CLAIMED_RUN_HUNG_MS / 60_000)} min)`
+							: "";
+						const detail = `status=${manifest.status}, updatedAt=${manifest.updatedAt}, agents=${agents.length}, as of ${manifest.updatedAt}${claimNote}`;
+						consecutiveHungNotices += 1;
+						try {
+							if (consecutiveHungNotices <= HUNG_NOTICE_CAP) {
+								// WD-DEDUP: alert-once per runId at module scope — even a
+								// fresh watchdog instance must not re-alert the same run.
+								if (!hungAlertAlreadySent(runId)) {
+									// Mark BEFORE queueing so a racing cycle cannot double-queue.
+									updateHungAlertRecord(runId, { alerted: true });
+									// WD-DELIVER-GUARD: the host queues a followUp while the
+									// session streams and delivers it arbitrarily later — so
+									// hand it over only at the idle boundary, re-verifying the
+									// run state at THAT moment.
+									queueHungAlertDelivery(
+										pi,
+										cwd,
+										runId,
+										`pi-crew watchdog: run ${runId} appears hung (${detail}). Consider running team action='cancel' runId='${runId}' or team action='doctor'.`,
+										opts.isSessionIdle,
+									);
+								}
+							} else if (consecutiveHungNotices === HUNG_NOTICE_CAP + 1) {
+								// One-time handoff, then silence — still monitoring, no more drips.
 								queueHungAlertDelivery(
 									pi,
 									cwd,
 									runId,
-									`pi-crew watchdog: run ${runId} appears hung (${detail}). Consider running team action='cancel' runId='${runId}' or team action='doctor'.`,
+									`pi-crew watchdog: run ${runId} is still hung after ${consecutiveHungNotices} checks — going quiet now. Intervene via team action='cancel' runId='${runId}', team action='doctor', or leave it; a completion notice will still fire.`,
 									opts.isSessionIdle,
 								);
 							}
-						} else if (consecutiveHungNotices === HUNG_NOTICE_CAP + 1) {
-							// One-time handoff, then silence — still monitoring, no more drips.
-							queueHungAlertDelivery(
-								pi,
-								cwd,
-								runId,
-								`pi-crew watchdog: run ${runId} is still hung after ${consecutiveHungNotices} checks — going quiet now. Intervene via team action='cancel' runId='${runId}', team action='doctor', or leave it; a completion notice will still fire.`,
-								opts.isSessionIdle,
-							);
+						} catch {
+							/* non-critical */
 						}
-					} catch {
-						/* non-critical */
 					}
 				}
 				// Keep monitoring (ARCH-5: silently past the cap — no more notices).

package/src/runtime/process/zombie-scanner.ts

@@ -97,11 +97,51 @@ export interface ForeignPiProcess {
 	cmd: string;
 }
 
+/** Wave-14 F4 (GAP-3): injectable seam for `scanZombieSubagents`.
+ *
+ *  Every ambient read the scanner performs is replaceable so classification
+ *  tests can drive a SYNTHETIC /proc on every OS (previously 7 tests skipped
+ *  forever on macOS/Windows CI). Defaults preserve behavior EXACTLY — each
+ *  read-site resolves `opts.X ?? <the previous inline expression>` (the same
+ *  injection pattern as reap-group.ts ReapGroupOptions, wave 12b). Production
+ *  callers are no-arg (doctor.ts, orphan-reaper.ts) and see zero change. */
+export interface ZombieScanOptions {
+	/** Platform gate. Default `process.platform`. */
+	platform?: NodeJS.Platform;
+	/** Real uid of the scanner process. Default `tryGetUid` (try/catch around
+	 *  `process.getuid?.()` — undefined on win32). */
+	getuid?: () => number | undefined;
+	/** File reader for /proc paths. Default `fs.readFileSync(p, "utf-8")` with
+	 *  read errors mapped to `undefined` (the previous per-helper catch). */
+	readProcFile?: (p: string) => string | undefined;
+	/** Candidate pid enumeration. Default: readdir of the real `/proc`. */
+	listProcPids?: () => number[];
+	/** Pid liveness probe. Default `isPidAlive` (`process.kill(pid, 0)` with the
+	 *  R7-A2 ESRCH/ENOENT semantics). */
+	pidAlive?: (pid: number) => boolean;
+	/** Scanner's own parent pid — the ancestor-chain starting point. Default
+	 *  `process.ppid`. Injection point for deterministic ancestor tests. */
+	getParentPid?: () => number;
+}
+
+/** Normalized /proc read: `undefined` = unreadable (missing, EPERM, …). */
+type ReadProcFile = (p: string) => string | undefined;
+
+/** Default seam reader — real fs with the previous per-helper catch folded in. */
+const defaultReadProcFile: ReadProcFile = (p) => {
+	try {
+		return fs.readFileSync(p, "utf-8");
+	} catch {
+		return undefined;
+	}
+};
+
 /** Read /proc/<pid>/environ as a key=value record. Returns {} if unreadable. */
-function readProcEnviron(pid: number): Record<string, string> {
+function readProcEnviron(pid: number, read: ReadProcFile = defaultReadProcFile): Record<string, string> {
 	try {
 		// /proc/<pid>/environ is NUL-separated key=value pairs.
-		const raw = fs.readFileSync(`/proc/${pid}/environ`, "utf-8");
+		const raw = read(`/proc/${pid}/environ`);
+		if (raw === undefined) return {};
 		const out: Record<string, string> = {};
 		for (const entry of raw.split("\0")) {
 			const eq = entry.indexOf("=");
@@ -114,9 +154,13 @@ function readProcEnviron(pid: number): Record<string, string> {
 }
 
 /** Read /proc/<pid>/stat to get ppid + starttime + elapsed. Returns undefined if unreadable. */
-function readProcStat(pid: number): { ppid: number; starttime: number | undefined; elapsedSec: number | undefined } | undefined {
+function readProcStat(
+	pid: number,
+	read: ReadProcFile = defaultReadProcFile,
+): { ppid: number; starttime: number | undefined; elapsedSec: number | undefined } | undefined {
 	try {
-		const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
+		const stat = read(`/proc/${pid}/stat`);
+		if (stat === undefined) return undefined;
 		// stat format: pid (comm) state ppid ... starttime ...
 		// Shared paren-aware cut (proc-stat.ts) — MUST index identically with
 		// surface-spawn's PI_CREW_PARENT_START_TIME capture.
@@ -125,7 +169,7 @@ function readProcStat(pid: number): { ppid: number; starttime: number | undefine
 		const ppid = Number.parseInt(rest[PROC_STAT_PPID_INDEX] ?? "", 10);
 		const starttimeTicksRaw = Number.parseInt(rest[PROC_STAT_STARTTIME_INDEX] ?? "", 10);
 		const starttime = Number.isFinite(starttimeTicksRaw) ? starttimeTicksRaw : undefined;
-		const elapsedSec = computeElapsedSec(starttime);
+		const elapsedSec = computeElapsedSec(starttime, read);
 		return { ppid: Number.isFinite(ppid) ? ppid : 0, starttime, elapsedSec };
 	} catch {
 		return undefined;
@@ -133,9 +177,10 @@ function readProcStat(pid: number): { ppid: number; starttime: number | undefine
 }
 
 /** /proc/uptime first field (seconds since boot); undefined when unreadable. */
-function readUptimeSec(): number | undefined {
+function readUptimeSec(read: ReadProcFile = defaultReadProcFile): number | undefined {
 	try {
-		const uptimeRaw = fs.readFileSync("/proc/uptime", "utf-8");
+		const uptimeRaw = read("/proc/uptime");
+		if (uptimeRaw === undefined) return undefined;
 		const uptimeSec = Number.parseFloat(uptimeRaw.split(" ")[0] ?? "");
 		return Number.isFinite(uptimeSec) ? uptimeSec : undefined;
 	} catch {
@@ -148,22 +193,22 @@ function readUptimeSec(): number | undefined {
  * ticks — boot time = now - uptime, so startedAt = boot + starttime/CLK_TCK.
  * Best-effort ISO string; undefined when /proc/uptime is unavailable.
  */
-function computeStartedAtIso(starttime: number | undefined): string | undefined {
+function computeStartedAtIso(starttime: number | undefined, read: ReadProcFile = defaultReadProcFile): string | undefined {
 	if (starttime === undefined || !Number.isFinite(starttime)) return undefined;
-	const uptimeSec = readUptimeSec();
+	const uptimeSec = readUptimeSec(read);
 	if (uptimeSec === undefined) return undefined;
 	const bootMs = Date.now() - uptimeSec * 1000;
 	return new Date(bootMs + (starttime / 100) * 1000).toISOString();
 }
 
-function computeElapsedSec(starttimeTicks: number | undefined): number | undefined {
+function computeElapsedSec(starttimeTicks: number | undefined, read: ReadProcFile = defaultReadProcFile): number | undefined {
 	if (starttimeTicks === undefined || !Number.isFinite(starttimeTicks)) return undefined;
 	try {
 		// Linux CLK_TCK is virtually always 100 (sysconf(_SC_CLK_TCK)). Reading it
 		// portably from Node requires a native addon; hardcoding 100 matches every
 		// mainstream Linux distro and keeps this dependency-free.
 		const ticksPerSec = 100;
-		const uptimeSec = readUptimeSec();
+		const uptimeSec = readUptimeSec(read);
 		if (uptimeSec === undefined) return undefined;
 		// starttime (ticks since boot) → process age in seconds = uptime - starttime/ticksPerSec.
 		const startAgeSec = starttimeTicks / ticksPerSec;
@@ -188,24 +233,26 @@ function isPidAlive(pid: number): boolean {
 	}
 }
 
-function readProcCmdline(pid: number): string {
-	return readProcCmdlineTokens(pid).join(" ").trim() || `pid ${pid}`;
+function readProcCmdline(pid: number, read: ReadProcFile = defaultReadProcFile): string {
+	return readProcCmdlineTokens(pid, read).join(" ").trim() || `pid ${pid}`;
 }
 
 /** /proc/<pid>/cmdline as argv tokens (NUL-split). Empty array if unreadable. */
-function readProcCmdlineTokens(pid: number): string[] {
+function readProcCmdlineTokens(pid: number, read: ReadProcFile = defaultReadProcFile): string[] {
 	try {
 		// /proc/<pid>/cmdline is NUL-separated argv.
-		const raw = fs.readFileSync(`/proc/${pid}/cmdline`, "utf-8");
+		const raw = read(`/proc/${pid}/cmdline`);
+		if (raw === undefined) return [];
 		return raw.split("\0").filter(Boolean);
 	} catch {
 		return [];
 	}
 }
 
-function readProcRssKb(pid: number): number {
+function readProcRssKb(pid: number, read: ReadProcFile = defaultReadProcFile): number {
 	try {
-		const status = fs.readFileSync(`/proc/${pid}/status`, "utf-8");
+		const status = read(`/proc/${pid}/status`);
+		if (status === undefined) return 0;
 		const match = status.match(/^VmRSS:\s+(\d+)\s+kB/m);
 		return match ? Number.parseInt(match[1] ?? "", 10) : 0;
 	} catch {
@@ -221,8 +268,8 @@ function readProcRssKb(pid: number): number {
  * non-Linux platforms the scanner returns an empty result with a note in
  * `errors` (zombie detection is best-effort; the doctor report still renders).
  */
-function listCandidatePids(): number[] {
-	if (process.platform !== "linux") return [];
+function listCandidatePids(platform: NodeJS.Platform = process.platform): number[] {
+	if (platform !== "linux") return [];
 	const pids: number[] = [];
 	try {
 		for (const entry of fs.readdirSync("/proc")) {
@@ -241,23 +288,30 @@ function listCandidatePids(): number[] {
  * any scan errors. Callers decide what to do with the result; this module
  * has no side effects.
  */
-export function scanZombieSubagents(): ZombieScanResult {
+export function scanZombieSubagents(opts: ZombieScanOptions = {}): ZombieScanResult {
+	// Wave-14 F4: resolve the seam ONCE — every default below is the exact
+	// previous inline expression, so no-arg callers are byte-for-byte behavior
+	// preserved (doctor.ts:990, orphan-reaper.ts:306).
+	const platform = opts.platform ?? process.platform;
+	const read = opts.readProcFile ?? defaultReadProcFile;
+	const pidAlive = opts.pidAlive ?? isPidAlive;
 	const result: ZombieScanResult = { zombies: [], live: [], foreign: [], errors: [] };
-	if (process.platform !== "linux") {
-		result.errors.push("zombie scan is Linux-only (/proc required); skipping on " + process.platform);
+	if (platform !== "linux") {
+		result.errors.push("zombie scan is Linux-only (/proc required); skipping on " + platform);
 		return result;
 	}
 
-	const myUid = tryGetUid();
+	const myUid = (opts.getuid ?? tryGetUid)();
 	// R3-16: self + ancestors are live hosting sessions (main session / crew
 	// host chain) — never reportable as foreign, even when they carry markers.
-	const ancestors = collectAncestorPids();
-	for (const pid of listCandidatePids()) {
+	const ancestors = collectAncestorPids(read, opts.getParentPid);
+	const listPids = opts.listProcPids ?? (() => listCandidatePids(platform));
+	for (const pid of listPids()) {
 		try {
 			// Cheap rejection first: only inspect processes we own (avoid scanning system procs).
-			if (myUid !== undefined && getProcUid(pid) !== myUid) continue;
+			if (myUid !== undefined && getProcUid(pid, read) !== myUid) continue;
 
-			const environ = readProcEnviron(pid);
+			const environ = readProcEnviron(pid, read);
 			// AUTHORITATIVE GATE: a process is a pi-crew sub-agent ONLY if it carries
 			// PI_CREW_KIND=subagent. The user's main session never sets this, so it can
 			// never be matched — this is the fix for accidentally killing main sessions.
@@ -271,18 +325,18 @@ export function scanZombieSubagents(): ZombieScanResult {
 				// them (pi-crew also scrubs these markers from worker env).
 				const hasPiMarker = environ.AI_AGENT === "pi" || environ.PI_CODING_AGENT === "true";
 				if (hasPiMarker && pid !== process.pid && !ancestors.has(pid)) {
-					const tokens = readProcCmdlineTokens(pid);
+					const tokens = readProcCmdlineTokens(pid, read);
 					if (looksLikePiBinary(tokens)) {
-						const foreignStat = readProcStat(pid);
+						const foreignStat = readProcStat(pid, read);
 						const ppid = foreignStat?.ppid ?? 0;
 						result.foreign.push({
 							pid,
 							ppid,
-							orphaned: ppid <= 1 || !isPidAlive(ppid),
+							orphaned: ppid <= 1 || !pidAlive(ppid),
 							headless: isHeadlessArgv(tokens),
-							rssKb: readProcRssKb(pid),
+							rssKb: readProcRssKb(pid, read),
 							elapsedSec: foreignStat?.elapsedSec,
-							cmd: readProcCmdline(pid),
+							cmd: readProcCmdline(pid, read),
 						});
 					}
 				}
@@ -290,7 +344,7 @@ export function scanZombieSubagents(): ZombieScanResult {
 			}
 
 			const crewParentPid = Number.parseInt(environ.PI_CREW_PARENT_PID ?? "", 10);
-			const stat = readProcStat(pid);
+			const stat = readProcStat(pid, read);
 			// Surface identity (T12): strict allowlist — an unrelated PI_CREW_SURFACE
 			// value must not half-populate the fields doctor relies on for pane close.
 			const surface = environ.PI_CREW_SURFACE === "tmux" || environ.PI_CREW_SURFACE === "herdr" ? environ.PI_CREW_SURFACE : undefined;
@@ -298,17 +352,17 @@ export function scanZombieSubagents(): ZombieScanResult {
 				pid,
 				ppid: stat?.ppid ?? 0,
 				crewParentPid: Number.isFinite(crewParentPid) ? crewParentPid : 0,
-				parentAlive: Number.isFinite(crewParentPid) && isPidAlive(crewParentPid),
+				parentAlive: Number.isFinite(crewParentPid) && pidAlive(crewParentPid),
 				role: environ.PI_CREW_ROLE,
 				surface,
 				surfacePaneId: environ.PI_CREW_SURFACE_PANE || undefined,
-				rssKb: readProcRssKb(pid),
+				rssKb: readProcRssKb(pid, read),
 				elapsedSec: stat?.elapsedSec,
 				// M-7: starttime (ticks) + derived wall-clock start — pid identity pin
 				// for kill-time PID-reuse checks and prompt-kill triage.
 				starttime: stat?.starttime,
-				startedAt: computeStartedAtIso(stat?.starttime),
-				cmd: readProcCmdline(pid),
+				startedAt: computeStartedAtIso(stat?.starttime, read),
+				cmd: readProcCmdline(pid, read),
 			};
 
 			if (entry.parentAlive) {
@@ -338,10 +392,11 @@ function tryGetUid(): number | undefined {
 	}
 }
 
-function getProcUid(pid: number): number | undefined {
+function getProcUid(pid: number, read: ReadProcFile = defaultReadProcFile): number | undefined {
 	try {
 		// /proc/<pid>/status has Uid: <real> <eff> <sav> <fs>
-		const status = fs.readFileSync(`/proc/${pid}/status`, "utf-8");
+		const status = read(`/proc/${pid}/status`);
+		if (status === undefined) return undefined;
 		const match = status.match(/^Uid:\s+(\d+)/m);
 		return match ? Number.parseInt(match[1] ?? "", 10) : undefined;
 	} catch {
@@ -393,13 +448,13 @@ function isHeadlessArgv(tokens: string[]): boolean {
  * it sit on this chain and carry markers when pi-in-pi). Bounded at 64 hops to
  * survive a hypothetical pid cycle.
  */
-function collectAncestorPids(): Set<number> {
+function collectAncestorPids(read: ReadProcFile = defaultReadProcFile, getParentPid?: () => number): Set<number> {
 	const chain = new Set<number>();
-	let current = process.ppid;
+	let current = getParentPid !== undefined ? getParentPid() : process.ppid;
 	let guard = 0;
 	while (current > 1 && guard++ < 64) {
 		chain.add(current);
-		const stat = readProcStat(current);
+		const stat = readProcStat(current, read);
 		if (!stat || stat.ppid <= 0) break;
 		current = stat.ppid;
 	}