pi-crew 0.11.38 → 0.11.39

package/src/runtime/stale-reconciler.ts

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { getCrewEnv } from "../config/env-vars.ts";
 import { errors } from "../errors.ts";
 import { atomicWriteFile, atomicWriteJson } from "../state/atomic-write.ts";
+import { isTerminalTaskStatus } from "../state/contracts.ts";
 import { type ActiveRunRegistryEntry, activeRunEntries } from "../state/stores/active-run-registry.ts";
 import { getCurrentPlanRecord } from "../state/stores/plan-store.ts";
 import { loadManifestWithRecovery, loadTasksWithRecovery, saveRunManifest } from "../state/stores/state-store.ts";
@@ -11,9 +12,19 @@ import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { findRunStateDir } from "../utils/paths.ts";
 import { recordFromTask, upsertCrewAgent } from "./crew-agent-records.ts";
+import { currentCrewDepth } from "./model/pi-args.ts";
 import { reapRecordedWorkerOrphans } from "./process/orphan-reaper.ts";
+import { type ProcSnapshot, reapRunDescendants, resolveRunDescendantSweepEnabled } from "./process/run-descendant-sweep.ts";
 import { checkProcessLiveness } from "./process-status.ts";
 
+/**
+ * Synchronous shutdown flush — RE-EXPORTED so every caller of the escalation
+ * machinery (`drainReapEscalations` in this module, `flushReapEscalationsSync`
+ * in `process/reap-group.ts`) imports from one family. `reap-group.ts` owns the
+ * armed registry because it is the only module that may signal a group.
+ */
+export { flushReapEscalationsSync } from "./process/reap-group.ts";
+
 /** Age threshold for orphaned temp directory cleanup: 1 hour. */
 const ORPHAN_TEMP_DIR_AGE_THRESHOLD_MS = 60 * 60 * 1000;
 /** A `.cleanup-in-progress` sentinel older than this is abandoned — its owner
@@ -449,6 +460,93 @@ export function hasLiveRunClaim(runId: string, manifest: TeamRunManifest): boole
 	return false;
 }
 
+// ── armed group escalations (wave 11a review, MAJOR #3) ────────────────────
+//
+// `repairStaleRun` is SYNCHRONOUS by contract: it is reached from
+// `withRunLockSync` (crash-recovery) and from the sync
+// `reconcileOrphanedTempWorkspaces`, and 50+ tests pin its sync return value
+// (see the OPT-02 note in checkResultFile). It therefore CANNOT await the
+// SIGKILL escalation it arms when it reaps a worker process group. The pre-fix
+// code dropped the promise outright — `void Promise.allSettled(...).catch(...)`,
+// whose catch could never fire because allSettled never rejects — so a host
+// that returned and exited here could leave the escalation undelivered.
+//
+// Every armed escalation is now REGISTERED, and an async owner awaits
+// `drainReapEscalations()`: `reconcileAllStaleRuns` (crash-recovery.ts) does it
+// for the background sweep, and any other caller that wants the guarantee can.
+//
+// Why the keep-alive pin below: the escalation itself is a chain of UNREF'd
+// timers (reap-group.ts must never keep an idle run alive), so the event loop
+// would drain underneath a still-in-flight escalation and abandon the SIGKILL
+// (measured on Node 22: an unsettled top-level await over unref'd timers exits
+// 13). The drain therefore holds ONE ref'd interval of its own — and only while
+// it actually has something to await.
+const inflightReapEscalations = new Set<Promise<unknown>>();
+/** Keep-alive cadence for the drain (ms). Any value works: it only has to exist. */
+const DRAIN_KEEPALIVE_MS = 200;
+
+/** Register an armed escalation; the entry clears once it settles. Never throws. */
+function trackReapEscalation(promise: Promise<unknown>): void {
+	const settled = promise.catch((err) => {
+		logInternalError("stale-reconciler.reap-escalation", err, "group escalation rejected", "warn");
+	});
+	inflightReapEscalations.add(settled);
+	void settled.finally(() => inflightReapEscalations.delete(settled));
+}
+
+/**
+ * Await every group escalation this module armed (SIGKILL rung included) and
+ * clear the registry. Never throws; resolves only AFTER the in-flight
+ * escalations settled, and holds a ref'd keep-alive for exactly that window (an
+ * empty drain is an immediate no-op that creates no keep-alive at all).
+ */
+export async function drainReapEscalations(): Promise<void> {
+	const snapshot = [...inflightReapEscalations];
+	if (snapshot.length === 0) return;
+	// REF'd (not unref'd) on purpose: this is the only thing that keeps the
+	// process alive while an escalation is mid-flight. Cleared in `finally`, so
+	// it lives exactly as long as the wait.
+	const pin = setInterval(() => {
+		/* ref'd no-op: its ONLY job is to keep the loop alive */
+	}, DRAIN_KEEPALIVE_MS);
+	pin.ref();
+	try {
+		await Promise.allSettled(snapshot);
+	} catch (err) {
+		// allSettled never rejects — belt-and-braces only.
+		logInternalError("stale-reconciler.drainReapEscalations", err, undefined, "warn");
+	} finally {
+		clearInterval(pin);
+		for (const promise of snapshot) inflightReapEscalations.delete(promise);
+	}
+}
+
+// Wave 11a review test seam (same shape as child-pi-kill.ts `__test`): swap the
+// orphan reaper so the escalation registration can be driven by a deferred
+// promise — no real /proc read and no real signal.
+let reapRecordedWorkerOrphansImpl = reapRecordedWorkerOrphans;
+// Wave 11b.1 test seam (same shape as the orphan-reaper seam above): swap the
+// run-descendant sweep so its REACHABILITY can be pinned at reconcile level — a
+// real /proc scan and a real signal must never be part of a reconcile test.
+let reapRunDescendantsImpl: typeof reapRunDescendants = reapRunDescendants;
+export const __test = {
+	setReapRecordedWorkerOrphans(fn: typeof reapRecordedWorkerOrphans | undefined): void {
+		reapRecordedWorkerOrphansImpl = fn ?? reapRecordedWorkerOrphans;
+	},
+	setReapRunDescendants(fn: typeof reapRunDescendants | undefined): void {
+		reapRunDescendantsImpl = fn ?? reapRunDescendants;
+	},
+	/** Register a synthetic escalation (event-loop pin test — no real reap). */
+	trackEscalation(promise: Promise<unknown>): void {
+		trackReapEscalation(promise);
+	},
+	reset(): void {
+		reapRecordedWorkerOrphansImpl = reapRecordedWorkerOrphans;
+		reapRunDescendantsImpl = reapRunDescendants;
+		inflightReapEscalations.clear();
+	},
+};
+
 function repairStaleRun(
 	manifest: TeamRunManifest,
 	tasks: TeamTaskState[],
@@ -488,9 +586,9 @@ function repairStaleRun(
 	// worker re-parented to PID 1 stayed alive and burned a slot forever. This
 	// reaps only pids confirmed by the AUTHORITATIVE zombie signal (crew-subagent
 	// marker + dead crew-parent), so a live worker is never touched. Best-effort.
+	const reapTargets = onlyTaskIds ? tasks.filter((task) => onlyTaskIds.has(task.id)) : tasks;
 	try {
-		const reapTargets = onlyTaskIds ? tasks.filter((task) => onlyTaskIds.has(task.id)) : tasks;
-		const reapResult = reapRecordedWorkerOrphans(reapTargets);
+		const reapResult = reapRecordedWorkerOrphansImpl(reapTargets);
 		if (reapResult.reaped.length > 0) {
 			logInternalError(
 				"stale-reconciler",
@@ -499,12 +597,237 @@ function repairStaleRun(
 				"warn",
 			);
 		}
+		// Wave 11a (F2) + review MAJOR #3: the group path delivers SIGTERM
+		// synchronously and returns the SIGKILL escalation as a promise. This
+		// function is sync by contract (see the block above `repairStaleRun`), so
+		// the escalations are REGISTERED here and the async owner awaits
+		// `drainReapEscalations()` — nothing is dropped, nothing dangles.
+		for (const escalation of reapResult.pending) trackReapEscalation(escalation);
 	} catch (reapError) {
 		logInternalError("stale-reconciler", reapError, `orphan reap failed for ${manifest.runId}`, "warn");
 	}
+	// Wave 11b (F7): the worker-level reap above cannot reach pi's bash
+	// grandchildren — the bash tool spawns every command `detached`, so they own
+	// a group nothing rooted at the worker can signal (the 390 MB / 24 h leak
+	// after team_20261022110510 completed). The run-scoped sweep matches the env
+	// markers they INHERITED instead, and only once this run is terminal.
+	// NOTE (11b.1): the sweep is handed the POST-repair array, never the input
+	// `tasks` and never `reapTargets`. The terminal guard inside the helper is
+	// `tasks.every(isTerminalTaskStatus)`, and the input array still carries the
+	// `running`/`queued` statuses this function just cancelled — so the pre-11b.1
+	// call site passed a guard that could NEVER pass and the sweep was dead code
+	// on this path too. `repairedTasks` is exactly "what is left to run": all
+	// terminal when the whole run was repaired, still non-terminal (⇒ no sweep)
+	// on the individual-stale-subset branch, which is the behaviour we want.
+	sweepTerminalRunDescendants(manifest, repairedTasks);
 	return repairedTasks;
 }
 
+/**
+ * Wave 11b.2: persist "this run has been swept" so no later reconcile pass
+ * rescans /proc for it. `saveRunManifest` is the same helper every other writer
+ * in this module uses (sync by contract, atomic write, cache-repopulating), and
+ * the caller already holds the run lock on every path that reaches the sweep.
+ * The field is also set IN MEMORY so a caller that saves the manifest right
+ * after (updateRunStatus on the repair path) carries it along even when the
+ * write below fails. Never throws: the sweep already ran.
+ *
+ * 11b.4 (HIGH-2): `descendantSweepAt` records WHEN the last attempt ran, not
+ * that no work is left. When the attempt left a RETRYABLE skip behind (the same
+ * leak is still out there, we just could not signal it yet) `pending` is set so
+ * the startup lane re-selects the run after `TERMINAL_SWEEP_RETRY_MS` instead of
+ * never looking at it again — which is exactly how 11b.2/11b.3 could bury a real
+ * leak for good. A clean attempt clears the flag (and the field, so the manifest
+ * keeps its pre-11b.4 shape).
+ */
+function stampDescendantSweep(manifest: TeamRunManifest, pending: boolean): void {
+	try {
+		manifest.descendantSweepAt = new Date().toISOString();
+		if (pending) manifest.descendantSweepPending = true;
+		else delete manifest.descendantSweepPending;
+		saveRunManifest(manifest);
+	} catch (stampError) {
+		// Warn, never throw: the sweep is done; the worst case is one redundant
+		// (idempotent) rescan on the next reconcile pass.
+		logInternalError("stale-reconciler.run-descendant-sweep", stampError, `marker write failed for ${manifest.runId}`, "warn");
+	}
+}
+
+/**
+ * Skip reasons that mean "the leak may still be there, try again later" (11b.4).
+ *
+ * The complement is what must NOT be retried: `dry-run` (report only — the
+ * caller returns before stamping at all), `already-swept` (this incarnation was
+ * already signalled; the idempotency registry remembers it) and `group-refused`
+ * reasons that are permanent for the run.
+ */
+function isRetryableSweepSkip(reason: string): boolean {
+	return (
+		reason === "leader-alive-unmatched" || reason === "no-pgid" || reason === "interactive-tty" || reason.startsWith("group-refused:")
+	);
+}
+
+/** Recorded worker pids of a run's tasks (heartbeat / checkpoint), deduped. */
+function collectRecordedWorkerPids(tasks: TeamTaskState[]): number[] {
+	const pids = new Set<number>();
+	for (const task of tasks) {
+		const pid = task.heartbeat?.pid ?? task.checkpoint?.childPid;
+		if (typeof pid === "number" && Number.isInteger(pid) && pid > 1) pids.add(pid);
+	}
+	return [...pids];
+}
+
+/**
+ * Wave 11b.3: pids the run's mux-surface controller recorded per task
+ * (`manifest.surface.workerPids`, `ManifestSurfaceState` in state/types.ts —
+ * verified field, never invented). A pane pid that is still alive is the pane
+ * the operator may be watching, so the sweep must not treat it as a descendant.
+ */
+function collectSurfacePids(manifest: TeamRunManifest): number[] {
+	const pids = new Set<number>();
+	for (const pid of Object.values(manifest.surface?.workerPids ?? {})) {
+		if (typeof pid === "number" && Number.isInteger(pid) && pid > 1) pids.add(pid);
+	}
+	return [...pids];
+}
+
+/**
+ * Wave 11b (F7) + 11b.1 (reachability): run-scoped descendant sweep for a
+ * TERMINAL run. Two preconditions, in order:
+ *
+ *  1. TERMINAL only — a run that still has a live task may legitimately own
+ *     live descendants; sweeping it would kill in-flight work. `repairStaleRun`
+ *     passes its POST-repair array (the pre-repair one is never all-terminal,
+ *     which is what made the guard unsatisfiable before 11b.1); the
+ *     `result_exists` path passes the tasks checkResultFile just proved
+ *     terminal.
+ *  2. NEVER inside a worker — a worker process carries `PI_CREW_KIND=subagent`
+ *     and/or a non-zero crew depth, and every descendant it can see may belong
+ *     to its OWN (still-running) run. Only the host session / detached runner
+ *     may sweep, which is also why the kill switch is forwarded there.
+ *
+ * The pre-11b.1 third precondition ("every recorded ancestor must be dead") is
+ * GONE: it was all-or-nothing, so ONE surviving recorded worker aborted the
+ * sweep for the entire run and the leaked grandchildren — the incident this wave
+ * exists for — were never reaped. Descent is now proven PER CANDIDATE inside
+ * run-descendant-sweep.ts: a recorded ancestor (runner/worker) is never a
+ * candidate, and a `task-id` match additionally requires its recorded parent to
+ * be dead. A live recorded pid therefore no longer vetoes the sweep; it simply
+ * is not swept.
+ *
+ * Best-effort: never throws. When something was reaped the result is logged at
+ * `warn` (logInternalError has no `info` level; this mirrors the F2 reap above,
+ * whose success log is also `warn`), otherwise at `debug`. Escalations are
+ * registered with the existing drain owners.
+ *
+ * Wave 11b.2 — the SWEEP MARKER. A leak lives LONGER than its run (the incident
+ * run was `completed` a full day before its grandchildren died), so the sweep is
+ * not a run-lifecycle step at all: it has to be reachable from any later
+ * reconcile pass. `manifest.descendantSweepAt` is that reachability record —
+ * startup reconciliation (`reconcileAllStaleRuns`) enumerates TERMINAL runs that
+ * lack it, and this function stamps it after a REAL sweep so the /proc scan runs
+ * at most once per run. Stamped only when a sweep was actually attempted:
+ *  - never on a dry-run report (nothing was signalled ⇒ not swept),
+ *  - never when the kill switch (`PI_CREW_REAP_RUN_DESCENDANTS=0`) is off, so
+ *    turning it back on still finds the run (surface-runtime forwarded kill
+ *    switches must not silently burn the one-shot marker),
+ *  - never when the sweep throws (the failure stays retryable next pass).
+ * The persist is warn-only: the sweep already happened, so a write error must
+ * not fail the reconcile pass — at worst the run is swept again next pass, which
+ * is idempotent (its descendants are gone by then).
+ *
+ * Wave 11b.4 (HIGH-2) — the marker is no longer one-shot. An attempt that could
+ * not SIGNAL anything it had proven (a live unmatched group leader, a candidate
+ * with no usable pgid, a refused group reap, an interactive tty) used to stamp
+ * the run as done anyway, so the very leak the sweep exists for was never looked
+ * at again. Now the stamp always records the attempt time, and
+ * `descendantSweepPending` marks the run for a bounded retry after
+ * `TERMINAL_SWEEP_RETRY_MS`.
+ */
+export function sweepTerminalRunDescendants(
+	manifest: TeamRunManifest,
+	tasks: TeamTaskState[],
+	opts: { snapshot?: ProcSnapshot } = {},
+): void {
+	try {
+		if (!tasks.every((task) => isTerminalTaskStatus(task.status))) return;
+		if (getCrewEnv("PI_CREW_KIND") === "subagent") return;
+		if (currentCrewDepth() !== 0) return;
+		// Kill switch OFF ⇒ no scan, and NO marker: the run must stay eligible so
+		// that flipping the switch back on still reaps its leak.
+		if (!resolveRunDescendantSweepEnabled()) return;
+		const runnerPid = manifest.async?.pid;
+		const workerPids = collectRecordedWorkerPids(tasks);
+		// Wave 11c (battery 2026-10-24 F2): the pid that CREATED the run. A SYNC
+		// (foreground) run records no `async.pid`, so its leaked descendants carry
+		// `PI_CREW_PARENT_PID=<session pi pid>` — a pid no other field records, and
+		// the descent proof could never hold, so the leak was skipped forever.
+		// The sweep accepts it as a recorded PROOF parent only; the dead-only
+		// guard inside the sweep keeps a LIVE session from ever serving as proof
+		// (the operator may still be using that very pi — never reap under it).
+		const sessionPid = manifest.sessionPid;
+		// 11b.3: recorded surface pane pids — alive ones are excluded from the
+		// candidate set inside the sweep (safety rung 10), so a run that just went
+		// terminal cannot lose a pane the operator is still watching.
+		const surfacePids = collectSurfacePids(manifest);
+		const recordedPids = [
+			...(sessionPid !== undefined ? [sessionPid] : []),
+			...(runnerPid !== undefined ? [runnerPid] : []),
+			...workerPids,
+		];
+		// No recorded process ⇒ no marker can prove descent for the shapes this
+		// wave targets (the parent-pid / task-id branches both need a recorded
+		// parent), so skip the /proc scan entirely.
+		if (recordedPids.length === 0) return;
+		const startedAtMs = Date.parse(manifest.async?.spawnedAt ?? manifest.createdAt);
+		const result = reapRunDescendantsImpl(
+			{
+				runId: manifest.runId,
+				...(runnerPid !== undefined ? { runnerPid } : {}),
+				workerPids,
+				...(sessionPid !== undefined ? { sessionPid } : {}),
+				...(surfacePids.length > 0 ? { surfacePids } : {}),
+				taskIds: tasks.map((task) => task.id),
+				startedAtMs: Number.isFinite(startedAtMs) ? startedAtMs : 0,
+			},
+			// 11b.4 (LOW-4): a caller sweeping several runs in one pass shares ONE
+			// /proc snapshot; a lone call builds its own inside the sweep.
+			opts.snapshot === undefined ? {} : { snapshot: opts.snapshot },
+		);
+		// Same owner as the F2 escalations above — one drain mechanism, never two.
+		for (const escalation of result.pending) trackReapEscalation(escalation);
+		// A dry-run pass signalled nothing (every candidate carries reason
+		// "dry-run"), so it must not consume the one-shot marker.
+		if (result.skipped.some((skip) => skip.reason === "dry-run")) return;
+		// 11b.4 (HIGH-2): the marker records the attempt; `pending` records that
+		// something PROVEN could not be signalled yet, so the startup lane retries.
+		stampDescendantSweep(
+			manifest,
+			result.skipped.some((skip) => isRetryableSweepSkip(skip.reason)),
+		);
+		if (result.reaped.length > 0) {
+			logInternalError(
+				"stale-reconciler.run-descendant-sweep",
+				new Error(
+					`swept ${result.reaped.length} descendant process(es) of terminal run: ${result.reaped.map((descendant) => `${descendant.pid}(${descendant.matchedBy})`).join(",")}`,
+				),
+				manifest.runId,
+				"warn",
+			);
+		} else if (result.skipped.length > 0) {
+			logInternalError(
+				"stale-reconciler.run-descendant-sweep",
+				new Error(`no descendant reaped (${result.skipped.length} skipped)`),
+				manifest.runId,
+				"debug",
+			);
+		}
+	} catch (sweepError) {
+		// The sweep is cleanup, never a reason to fail a reconcile pass.
+		logInternalError("stale-reconciler.run-descendant-sweep", sweepError, manifest.runId, "debug");
+	}
+}
+
 /**
  * Three-phase stale run reconciliation.
  *
@@ -588,6 +911,18 @@ export function reconcileStaleRun(manifest: TeamRunManifest, tasks: TeamTaskStat
 		// NOTE (OPT-02): Remains sync — reconcileStaleRun is called from withRunLockSync in
 		// crash-recovery.ts and from sync reconcileOrphanedTempWorkspaces; cannot await here.
 		saveRunManifest(manifest);
+		// Wave 11b.1 (F7 reachability): the sweep MUST run on THIS path too.
+		// `result_exists` is the most common way a run becomes terminal, and the
+		// only pre-11b.1 caller was `repairStaleRun` — unreachable once a result
+		// file exists. That is exactly why the leak behind
+		// team_20261022110510 (6 grandchildren, 399 MB, 24 h) survived a run that
+		// was `completed` while the sweep's unit tests were green: a leak lives
+		// LONGER than its run, so "this run is finished" is the reason to sweep,
+		// never the reason to skip. Every task is terminal here (checkResultFile
+		// just proved it); the helper keeps its own guards (all tasks terminal,
+		// never inside a worker, kill switch) and this branch RETURNS, so the
+		// sweep still runs at most once per run per reconcile pass.
+		sweepTerminalRunDescendants(manifest, tasks);
 		return {
 			runId,
 			verdict: "result_exists",
@@ -1002,6 +1337,12 @@ export function reconcileOrphanedTempWorkspaces(
 	} catch {
 		/* skip if tmpdir unreadable */
 	}
+	// Wave 11a review (MAJOR #3): this scan repairs runs too, so it can arm the
+	// same group escalation. The function is sync (its callers are sync configurers
+	// and 5+ tests), so the best it can do is START the drain — the escalations are
+	// already registered with the module and any later `drainReapEscalations()`
+	// caller awaits them. The promise never rejects (allSettled + catch inside).
+	void drainReapEscalations();
 	return { repaired, cleanedDirs };
 }
 

package/src/runtime/task-runner/child-executor.ts

@@ -68,6 +68,7 @@ import { readEnabledModelsPatterns } from "../model/model-scope.ts";
 import { type ParsedPiJsonOutput, parsePiJsonOutput } from "../output/pi-json-output.ts";
 import { type ProgressEventSummary, shouldAppendProgressEventUpdate } from "../output/progress-event-coalescer.ts";
 import { buildSyntheticTerminalEvidence, cancellationReasonFromSignal } from "../process/cancellation.ts";
+import { readProcIdentity } from "../process/reap-group.ts";
 import { checkProcessLiveness } from "../process-status.ts";
 import { DEFAULT_RETRY_POLICY } from "../recovery/retry-executor.ts";
 import { runWorker } from "../run-worker.ts";
@@ -866,7 +867,10 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 						} catch (err) {
 							logInternalError("task-runner.ownership-write", err, `pid=${pid}, taskId=${task.id}`);
 						}
-						({ task, tasks } = checkpointTask(manifest, tasks, task, "child-spawned", pid));
+						// Wave 11a (F3): persist the spawn-time identity alongside the pid so a
+						// later reaper can prove the process (starttime/pgid/uid) instead of
+						// guessing from a pid that may already have been recycled.
+						({ task, tasks } = checkpointTask(manifest, tasks, task, "child-spawned", pid, readProcIdentity(pid)));
 						// Security review (T1/WP-1 round 1, security-1 replay fix): scope the
 						// steering file to ONE worker incarnation on EVERY spawn. Steering
 						// lines are id-less; each new worker process reads the file from
@@ -1035,10 +1039,17 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 							// Surface pid was previously never persisted into task state - the
 							// heartbeat-watcher PID-liveness gate (alive -> downgrade dead->stale)
 							// had nothing to check. Pin it once from the worker.started self-report.
+							// Wave 11a (F3): also pin the spawn-time identity (pgid/starttime/uid)
+							// so the orphan reaper can prove this pid later; a /proc read that
+							// races the exit simply contributes nothing (all fields optional).
+							const surfaceIdentity = readProcIdentity(pidFromStart);
 							task = {
 								...task,
 								heartbeat: touchWorkerHeartbeat(task.heartbeat ?? createWorkerHeartbeat(task.id), {
 									pid: pidFromStart,
+									...(surfaceIdentity?.pgid !== undefined ? { pgid: surfaceIdentity.pgid } : {}),
+									...(surfaceIdentity?.starttime !== undefined ? { starttime: surfaceIdentity.starttime } : {}),
+									...(surfaceIdentity?.uid !== undefined ? { uid: surfaceIdentity.uid } : {}),
 								}),
 							};
 						}

package/src/runtime/task-runner/state-helpers.ts

@@ -7,6 +7,7 @@ import { loadRunManifestById, saveRunTasksCoalesced } from "../../state/stores/s
 import type { TaskCheckpointState, TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { recordFromTask, upsertCrewAgent } from "../crew-agent-records.ts";
+import type { ProcIdentity } from "../process/reap-group.ts";
 
 export function updateTask(tasks: TeamTaskState[], updated: TeamTaskState): TeamTaskState[] {
 	return tasks.map((task) => (task.id === updated.id ? updated : task));
@@ -283,11 +284,37 @@ export function checkpointTask(
 	task: TeamTaskState,
 	phase: TaskCheckpointState["phase"],
 	childPid?: number,
+	identity?: ProcIdentity,
 ): { task: TeamTaskState; tasks: TeamTaskState[] } {
+	// Wave 11a review (MAJOR #4): CARRY the spawn-time identity over exactly like
+	// `childPid`. This function is also called on phase transitions that know
+	// nothing about the process ("child-stdout-final", "artifact-written"); those
+	// calls used to REBUILD the checkpoint without the three identity fields and
+	// silently erase them, so a later reaper lost the pid proof F3 exists to
+	// provide. Only a DEFINED argument overrides the carried value, so a caller
+	// that passes nothing keeps the pre-wave record shape byte-for-byte.
+	const previous = task.checkpoint;
+	const carriedPid = childPid ?? previous?.childPid;
+	// MINOR #6 (review): the identity belongs to ONE pid. Carrying it over a
+	// CHANGE of `childPid` (retry / re-spawn) would pair a fresh pid with the old
+	// incarnation's starttime — the reaper's reuse-proof field would then be a
+	// lie that REFUSES the real child (or, worse, matches an unrelated pid). So
+	// carry identity only while the child stays the same one.
+	const sameChild = childPid === undefined || childPid === previous?.childPid;
+	const carriedPgid = identity?.pgid ?? (sameChild ? previous?.childPgid : undefined);
+	const carriedStartTime = identity?.starttime ?? (sameChild ? previous?.childStartTime : undefined);
+	const carriedUid = identity?.uid ?? (sameChild ? previous?.childUid : undefined);
 	const checkpoint: TaskCheckpointState = {
 		phase,
 		updatedAt: new Date().toISOString(),
-		...(childPid ? { childPid } : task.checkpoint?.childPid ? { childPid: task.checkpoint.childPid } : {}),
+		...(carriedPid !== undefined ? { childPid: carriedPid } : {}),
+		// Wave 11a (F3): persist the spawn-time identity so a later reaper can
+		// PROVE the pid (starttime) instead of guessing. Only defined fields are
+		// spread, so a caller that passes nothing keeps the pre-wave record shape
+		// and old records/state files keep loading unchanged.
+		...(carriedPgid !== undefined ? { childPgid: carriedPgid } : {}),
+		...(carriedStartTime !== undefined ? { childStartTime: carriedStartTime } : {}),
+		...(carriedUid !== undefined ? { childUid: carriedUid } : {}),
 	};
 	const nextTask = { ...task, checkpoint };
 	const nextTasks = persistSingleTaskUpdate(manifest, updateTask(tasks, nextTask), nextTask);

package/src/state/stores/state-store.ts

@@ -475,6 +475,14 @@ export function createRunManifest(params: {
 		tasksPath: paths.tasksPath,
 		eventsPath: paths.eventsPath,
 		artifacts: [],
+		// Wave 11c (battery F2): record the SPAWNING process pid at creation — for
+		// a SYNC/foreground run (no async runner ever spawned) this is the only
+		// recorded parent its leaked descendants can name in PI_CREW_PARENT_PID,
+		// and without it the descendant sweep could never prove their descent.
+		// Sync-vs-async is NOT known at creation time (the async dispatch happens
+		// after this), so every run records it; async runs keep using
+		// `manifest.async.pid` as their primary recorded runner.
+		sessionPid: process.pid,
 		...(params.ownerSessionId ? { ownerSessionId: params.ownerSessionId } : {}),
 		runKind: params.runKind ?? "team-run",
 		...(params.args !== undefined ? { args: params.args } : {}),

package/src/state/types.ts

@@ -368,6 +368,18 @@ export interface TeamRunManifest {
 	eventsPath: string;
 	artifacts: ArtifactDescriptor[];
 	async?: AsyncRunState;
+	/** Wave 11c (battery 2026-10-24 F2): pid of the process that CREATED the
+	 *  run — `process.pid` at createRunManifest time (the session pi for a
+	 *  foreground team-tool dispatch; the detached runner itself when it
+	 *  creates sub-runs). A SYNC (foreground) run records no `async.pid`, so a
+	 *  leaked descendant carrying `PI_CREW_PARENT_PID=<session pi pid>` could
+	 *  never satisfy the run-descendant sweep's descent proof and was skipped
+	 *  forever; `sweepTerminalRunDescendants` now accepts this pid as a
+	 *  recorded proof parent (DEAD-only, like every other proof parent — a
+	 *  live session is never proof, the operator may still be using it).
+	 *  Purely additive/optional: absent on every manifest written before 11c,
+	 *  and async runs keep `async.pid` as their primary recorded runner. */
+	sessionPid?: number;
 	/** @deprecated-plan-pointer T2/R4 (ADR-4 §2): dual-write era — PlanRecord at
 	 *  `<stateRoot>/plans/plans.json` is authoritative; this field is kept (never
 	 *  dropped) as the pre-v2 fallback and legacy UI surface. Deprecate-only. */
@@ -437,6 +449,26 @@ export interface TeamRunManifest {
 	/** MuxSurface A1 (spec §8.3): pane/pid/lockout state of this run. Absent on
 	 *  runs that never booted a surface worker and on older manifests. */
 	surface?: ManifestSurfaceState;
+	/** Wave 11b.2 (F7 reachability): ISO timestamp of the LAST completed
+	 *  run-descendant sweep for this run (`sweepTerminalRunDescendants`).
+	 *  Purely additive/optional — absent on every manifest written before
+	 *  11b.2, and absent means "never swept" (⇒ still eligible for the
+	 *  startup sweep). Startup reconciliation enumerates terminal runs that
+	 *  lack it, because a leak OUTLIVES its run: the incident run was
+	 *  `completed` the day before its 6 grandchildren were finally reaped.
+	 *  Stamped only after a REAL sweep (never on dry-run, kill switch off, or
+	 *  a throwing sweep) so a failed attempt is retried on the next pass. */
+	descendantSweepAt?: string;
+	/** Wave 11b.4 (HIGH-2): the last sweep attempt PROVED descendants it could
+	 *  not signal (a live unmatched group leader, a candidate with no usable
+	 *  pgid, a refused group reap, an interactive tty). Without this the run
+	 *  would be stamped as done and the leak never looked at again — the exact
+	 *  failure mode 11b.2 introduced. Purely additive/optional: absent (or
+	 *  `false`) means "nothing left to retry". Startup reconciliation re-selects
+	 *  a pending run once `TERMINAL_SWEEP_RETRY_MS` has elapsed since
+	 *  `descendantSweepAt`, so a permanently un-signallable leak does not burn a
+	 *  /proc scan on every pass. */
+	descendantSweepPending?: boolean;
 }
 
 export interface RunModelContext {
@@ -621,6 +653,16 @@ export interface TaskCheckpointState {
 	phase: "started" | "child-spawned" | "child-stdout-final" | "artifact-written";
 	updatedAt: string;
 	childPid?: number;
+	/**
+	 * Wave 11a (F3): spawn-time process identity of `childPid`, written from
+	 * `readProcIdentity(pid)` right after the spawn. `starttime` is the
+	 * PID-reuse-proof field and `pgid` is only meaningful when the child leads
+	 * its own group (detached spawn). All three are OPTIONAL: records written
+	 * before this wave keep loading unchanged.
+	 */
+	childPgid?: number;
+	childStartTime?: string;
+	childUid?: number;
 }
 
 export interface TaskAttemptState {