pi-crew 0.11.37 → 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 } : {}),
 								}),
 							};
 						}
@@ -1193,6 +1204,9 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 			success: !error,
 			exitCode,
 			error,
+			// W10-7: capture THIS attempt's usage before the loop can move on —
+			// failed attempts' tokens otherwise vanish from every persisted record.
+			...(parsedOutput?.usage ? { usage: parsedOutput.usage } : {}),
 		};
 		modelAttempts.push(attempt);
 		task = {

package/src/runtime/task-runner/post-execution.ts

@@ -27,6 +27,7 @@ import type {
 	TeamRunManifest,
 	TeamTaskState,
 	TeamTaskStatus,
+	UsageState,
 	VerificationEvidence,
 } from "../../state/types.ts";
 import { captureWorktreeDiffAsync, captureWorktreeDiffStatAsync } from "../../worktree/worktree-manager.ts";
@@ -38,6 +39,7 @@ import { createWorkerHeartbeat, touchWorkerHeartbeat } from "../heartbeat/worker
 import type { ModelAttemptSummary } from "../model/model-fallback.ts";
 import { isStderrOnlyResult, type OutputValidationResult, validateWorkerOutput } from "../output/output-validator.ts";
 import type { ParsedPiJsonOutput } from "../output/pi-json-output.ts";
+import { permissionForRole } from "../role-permission.ts";
 import { writeTaskSharedOutput } from "../task-output-context.ts";
 import { evaluateCompletionMutationGuard } from "../verification/completion-guard.ts";
 import { createVerificationEvidence } from "../verification/green-contract.ts";
@@ -139,6 +141,87 @@ export type VerifierVerdict = "pass" | "fail" | "none";
  */
 const VERIFIER_VERDICT_LINE = /^[\s*_>#`=-]*(PASS|FAIL)[\s*_`]*(?=[:.\u2014\u2013-]|$|\()/i;
 
+/** W10-5: the critic/oracle decision-drift guardian marker (see
+ *  agents/critic.md + agents/oracle.md "Decision-drift guardian" sections). */
+const DRIFT_BLOCK_MARKER = /DRIFT-BLOCK\b/i;
+
+/**
+ * W10-8 (pi-subagents lesson #4): bounded `git status --porcelain` probe for
+ * READ-ONLY lanes — any entry (modified OR untracked) is an unexpected
+ * mutation. Returns undefined when the tree is clean or git fails (fail-open:
+ * a broken probe must not break task finalization). Note-only, never a fail.
+ */
+export async function detectReadLaneMutation(worktreePath: string): Promise<NonNullable<TeamTaskState["unexpectedMutation"]> | undefined> {
+	try {
+		// W10-8 one-shot git probe per read-only task — child_process is
+		// already in the platform; dynamic keeps it off the static import graph.
+		// LAZY: see above
+		const { execFile } = await import("node:child_process");
+		const out: string = await new Promise((resolve, reject) => {
+			execFile("git", ["status", "--porcelain"], { cwd: worktreePath, encoding: "utf-8", timeout: 10_000 }, (err, stdout) =>
+				err ? reject(err) : resolve(stdout),
+			);
+		});
+		const entries = out
+			.split("\n")
+			.map((l) => l.trim())
+			.filter((l) => l.length > 0);
+		if (entries.length === 0) return undefined;
+		return {
+			filesChanged: entries.length,
+			sample: entries.slice(0, 20).map((e) => e.slice(0, 200)),
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * W10-7 (v0.11.38, pi-subagents lesson #14 — usage reconciliation): compare
+ * the SUM of every model attempt's own cost (failed fallback attempts burn
+ * real tokens too, but task.usage carries only the FINAL run's numbers)
+ * against the final cost. Returns a usageReconcile note ONLY when the gap
+ * exceeds 5% AND at least two attempts reported usage — a single attempt is
+ * trivially self-consistent. Observability only: never fails the task.
+ */
+export function reconcileUsage(
+	attempts: ModelAttemptSummary[] | undefined,
+	finalUsage: UsageState | undefined,
+): { usageReconcile: NonNullable<TeamTaskState["usageReconcile"]> } | undefined {
+	if (!attempts || attempts.length < 2) return undefined;
+	// W10-7 batch-A threshold guard: with no final usage to reconcile AGAINST
+	// (finalUsage missing, or its cost not a finite number) the comparison is
+	// meaningless — an attempt-sum alone cannot prove a gap, and comparing to
+	// 0 would file a false 100%-gap alarm against missing data. No note.
+	if (typeof finalUsage?.cost !== "number" || !Number.isFinite(finalUsage.cost)) return undefined;
+	const costs = attempts.map((a) => (typeof a.usage?.cost === "number" && Number.isFinite(a.usage.cost) ? a.usage.cost : undefined));
+	const withUsage = costs.filter((c): c is number => c !== undefined);
+	if (withUsage.length < 2) return undefined;
+	const attemptTotal = withUsage.reduce((sum, c) => sum + c, 0);
+	const finalCost = finalUsage.cost;
+	if (attemptTotal <= 0) return undefined;
+	const deltaPct = Math.abs(attemptTotal - finalCost) / attemptTotal;
+	if (deltaPct <= 0.05) return undefined;
+	return {
+		usageReconcile: {
+			attemptTotalCostUsd: Number(attemptTotal.toFixed(6)),
+			finalRunCostUsd: finalCost,
+			deltaPct: Number((deltaPct * 100).toFixed(1)),
+			attemptsWithUsage: withUsage.length,
+		},
+	};
+}
+
+/**
+ * W10-8 visibility (batch A): the unexpectedMutation note lives on the task
+ * record where it is easy to miss — stamping it also emits ONE stderr line
+ * so a READ-ONLY lane violation shows up in the run log without new
+ * dependencies. Exported for the console-capture pin; fire-and-forget.
+ */
+export function warnReadLaneMutation(taskId: string, note: { filesChanged: number }): void {
+	console.warn(`[pi-crew:read-lane] unexpected mutation in READ-ONLY lane: ${taskId} files=${note.filesChanged}`);
+}
+
 /**
  * M3-2 (R47-3/V4, fix-wave 6): read the verifier verdict out of the
  * authoritative result sources.
@@ -173,7 +256,18 @@ export function extractVerifierVerdict(...sources: Array<string | undefined>): V
 			if (match[1]?.toUpperCase() === "FAIL") return "fail";
 			sawPass = true;
 		}
-		if (sawPass) return "pass";
+		if (sawPass) {
+			// W10-5 (v0.11.38, pi-subagents lesson #20 — oracle/drift-guardian): a
+			// verdict that flags a decision-drift contradiction (the `DRIFT-BLOCK:`
+			// marker the critic/oracle prompts mandate) is SELF-CONTRADICTORY as a
+			// pass — the worker saw a contradiction with an inherited decision and
+			// approved anyway. Degrade to "none" (not verified): the existing
+			// self-attested downgrade path then demands human/leader review instead
+			// of a green. FAIL still wins above — a flagged drift alongside FAIL is
+			// already the honest verdict.
+			if (DRIFT_BLOCK_MARKER.test(source)) return "none";
+			return "pass";
+		}
 	}
 	return "none";
 }
@@ -320,6 +414,7 @@ export async function finalizeTaskResult(ctx: TaskExecutionContext, execResult:
 				producer: task.id,
 			})
 		: undefined;
+
 	const diffStatArtifact = workspace.worktreePath
 		? writeArtifact(manifest.artifactsRoot, {
 				kind: "metadata",
@@ -328,6 +423,14 @@ export async function finalizeTaskResult(ctx: TaskExecutionContext, execResult:
 				producer: task.id,
 			})
 		: undefined;
+	// W10-8 (v0.11.38, pi-subagents lesson #4 — staged-files guard): a READ-ONLY
+	// lane that dirtied its worktree is a contract violation worth surfacing —
+	// note only (the diff artifact above is the evidence; the leader decides).
+	// `git diff` alone misses UNTRACKED files, hence status --porcelain.
+	const readLaneMutation =
+		workspace.worktreePath && permissionForRole(task.role) === "read_only"
+			? await detectReadLaneMutation(workspace.worktreePath)
+			: undefined;
 
 	// Capture unified patches from edit tool results
 	const patchArtifact = parsedOutput?.patches?.length
@@ -715,6 +818,9 @@ export async function finalizeTaskResult(ctx: TaskExecutionContext, execResult:
 		exitCode = exitCode === 0 ? 1 : exitCode;
 	}
 
+	// W10-8 batch-A visibility: emit the one-line stderr event exactly when
+	// the note below is stamped (only on detection).
+	if (readLaneMutation) warnReadLaneMutation(task.id, readLaneMutation);
 	task = {
 		...task,
 		status: error ? "failed" : noYield ? "needs_attention" : "completed",
@@ -722,6 +828,11 @@ export async function finalizeTaskResult(ctx: TaskExecutionContext, execResult:
 		exitCode,
 		modelAttempts,
 		usage: parsedOutput?.usage,
+		// W10-7 (v0.11.38): reconcile per-attempt costs (failed fallbacks burn
+		// real tokens that the final run's usage never shows) against the final
+		// cost — observability note only, >5% gap with >1 usage-carrying attempt.
+		...(reconcileUsage(modelAttempts, parsedOutput?.usage) ?? {}),
+		...(readLaneMutation ? { unexpectedMutation: readLaneMutation } : {}),
 		jsonEvents: parsedOutput?.jsonEvents,
 		agentProgress:
 			error && task.agentProgress?.currentTool

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);