pi-crew 0.11.37 → 0.11.38

package/src/runtime/foreground-watchdog.ts

@@ -10,9 +10,17 @@
  * 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.
+ *
+ * Hung alerts are additionally DELIVERY-gated (WD-DELIVER-GUARD): the message
+ * is only handed to the host when the host will deliver it immediately, and
+ * the run state is re-read at that instant — an alert whose run finished in
+ * the meantime is dropped instead of nagging the user minutes late.
  */
 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 { loadRunManifestById } from "../state/stores/state-store.ts";
+import type { TeamTaskState } from "../state/types.ts";
 import { readCrewAgents } from "./crew-agent-records.ts";
 import { isActiveRunStatus, isLikelyOrphanedActiveRun } from "./process-status.ts";
 
@@ -20,10 +28,22 @@ export interface WatchdogOptions {
 	pi: ExtensionAPI;
 	cwd: string;
 	runId: string;
-	/** Check interval in ms. Default: 5 minutes. */
+	/**
+	 * Check interval in ms. Default: 5 minutes, or the
+	 * `PI_CREW_WATCHDOG_INTERVAL_MS` override when set (WD-INTERVAL).
+	 */
 	checkIntervalMs?: number;
 	/** Maximum time to monitor in ms. Default: 2 hours. */
 	maxMonitorMs?: number;
+	/**
+	 * WD-DELIVER-GUARD (2026-10-23): capability-guarded probe for "the host will
+	 * deliver a followUp message NOW" (`ctx.isIdle()`). When it reports false,
+	 * a hung alert is held in this module's pending map and retried at the idle
+	 * boundary instead of being handed to the host's unretractable followUp
+	 * queue (where it can land minutes later, for a run that already finished).
+	 * Absent / throwing → treated as idle (pre-guard behavior, fail-open).
+	 */
+	isSessionIdle?: () => boolean | undefined;
 }
 
 const DEFAULT_CHECK_INTERVAL_MS = 300_000; // 5 minutes
@@ -32,6 +52,302 @@ const DEFAULT_MAX_MONITOR_MS = 7_200_000; // 2 hours
 /** Active watchdog timers — keyed by runId for cleanup. */
 const activeWatchdogs = new Map<string, ReturnType<typeof setTimeout>>();
 
+/**
+ * WD-DEDUP (2026-10-23): hung-alert dedup state, keyed by runId at module
+ * scope so a *new* watchdog instance (or a re-armed one after stop/start)
+ * cannot re-alert for a run the user already heard about. Bounded FIFO —
+ * the oldest entry is evicted once the cap is reached, so long-lived
+ * sessions cannot leak memory on this map.
+ */
+interface HungAlertRecord {
+	/** A "run … appears hung" alert has already been emitted for this runId. */
+	alerted: boolean;
+	/** The one-time re-verify-skip debug log has already been emitted. */
+	skipLogged: boolean;
+	/**
+	 * WD-STALE-RECORD (2026-10-23): the one-time "record stale (all tasks
+	 * terminal) — skipped hung alert" notice has already been emitted.
+	 */
+	staleNoticeSent?: boolean;
+	/**
+	 * WD-DELIVER-GUARD (2026-10-23): the one-time "drop hung alert at delivery"
+	 * debug log has already been emitted for this runId.
+	 */
+	droppedAtDeliveryLogged?: boolean;
+}
+const HUNG_ALERT_RECORDS_CAP = 256;
+const hungAlertRecords = new Map<string, HungAlertRecord>();
+
+function hungAlertAlreadySent(runId: string): boolean {
+	return hungAlertRecords.get(runId)?.alerted === true;
+}
+
+/** Insert/update a record, evicting the oldest entry when the cap is hit. */
+function updateHungAlertRecord(runId: string, patch: Partial<HungAlertRecord>): void {
+	if (!hungAlertRecords.has(runId) && hungAlertRecords.size >= HUNG_ALERT_RECORDS_CAP) {
+		const oldest = hungAlertRecords.keys().next().value;
+		if (oldest !== undefined) hungAlertRecords.delete(oldest);
+	}
+	const prev = hungAlertRecords.get(runId) ?? { alerted: false, skipLogged: false, staleNoticeSent: false };
+	hungAlertRecords.set(runId, { ...prev, ...patch });
+}
+
+/** Debug log gated behind PI_CREW_DEBUG (same convention as background-runner). */
+function debugLog(message: string): void {
+	if (getCrewEnv("PI_CREW_DEBUG")) console.log(message);
+}
+
+/**
+ * WD-STALE-RECORD (2026-10-23): a run record whose manifest is still `running`
+ * but whose EVERY task is terminal is a stale record, not a hung run. The
+ * worker(s) finished; the manifest write is merely behind (finalize racing, or
+ * a finalize write lost to a crash). Alerting "appears hung" for such a run is
+ * the exact pain users reported (alert for a run that is actually done), so the
+ * re-verify gate treats it as terminal and stays silent.
+ *
+ * Fail-open by design: no tasks recorded (`[]`), a non-array, or an unreadable
+ * tasks.json (loadRunManifestById degrades to `tasks: []`) returns false so the
+ * legacy alert behavior is preserved — a broken tasks file must never silence
+ * a genuinely hung run.
+ */
+function areAllTasksTerminal(tasks: TeamTaskState[] | undefined): boolean {
+	if (!Array.isArray(tasks) || tasks.length === 0) return false;
+	return tasks.every((task) => TEAM_TERMINAL_TASK_STATUSES.has(task.status));
+}
+
+/**
+ * WD-INTERVAL (2026-10-23): resolve the poll interval. An explicit
+ * `checkIntervalMs` (tests / callers) wins, then the `PI_CREW_WATCHDOG_INTERVAL_MS`
+ * env override (live repro at 20s instead of 5 min), then the 5-minute default.
+ * Only positive finite values are honored — `0`/negative/garbage fall through.
+ */
+function resolveCheckIntervalMs(overrideMs: number | undefined): number {
+	if (typeof overrideMs === "number" && Number.isFinite(overrideMs) && overrideMs > 0) return overrideMs;
+	const configured = getCrewEnvInt("PI_CREW_WATCHDOG_INTERVAL_MS");
+	if (typeof configured === "number" && Number.isFinite(configured) && configured > 0) return configured;
+	return DEFAULT_CHECK_INTERVAL_MS;
+}
+
+/**
+ * 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.
+ */
+type ReverifyLoader = typeof loadRunManifestById;
+let reverifyLoader: ReverifyLoader = loadRunManifestById;
+
+/**
+ * WD-DELIVER-GUARD (2026-10-23) — the residual the emit-time gate cannot see.
+ *
+ * Real incident (run team_20261023050900): the alert was EMITTED while the run
+ * was still running (so emit-time re-verify was correct), then
+ * `pi.sendUserMessage(..., {deliverAs:"followUp"})` pushed it into the host's
+ * follow-up queue while the session was streaming (`agent-session.js`:
+ * `if (this.isStreaming) this.agent.followUp(appMessage)`) and the host
+ * DELIVERED it 28 minutes later — after `run.completed` had landed. The user
+ * still saw "appears hung" for a finished run. `clearQueue()` is all-or-
+ * nothing, so a queued item cannot be retracted: the only fix is to not hand
+ * it over until delivery is imminent.
+ *
+ * Mechanism: while the session is streaming, the alert stays in OUR pending
+ * map; at the idle boundary (the moment the host delivers immediately) the run
+ * state is re-read one final time. Run terminal (completed/failed/cancelled/
+ * blocked) or all tasks terminal ⇒ DROP (debug-logged once per runId, no
+ * user-facing noise). FAIL-OPEN: an unreadable/absent record still delivers —
+ * a broken state file must never swallow a genuine hung alert.
+ *
+ * BOTH exits re-verify: the idle boundary AND the delivery cap. A session that
+ * never idles (one tool call blocking past the cap) is not a license to hand
+ * over a stale alert — the cap exit runs the same classify/verify, so an
+ * unverified delivery is impossible. "Late beats never" only applies to alerts
+ * whose run still reads as hung.
+ */
+const DEFAULT_DELIVER_RETRY_MS = 500;
+const DEFAULT_DELIVER_CAP_MS = 10 * 60_000; // 10 min
+/** Defensive bound — a burst of distinct hung runs must not grow the map. */
+const HUNG_DELIVERY_CAP = 256;
+
+interface PendingHungDelivery {
+	/** Full alert text, handed over verbatim at the idle boundary. */
+	text: string;
+	/** Past this instant the alert is handed over anyway (late beats never). */
+	deadline: number;
+	/** Idle probe captured at queue time (see WatchdogOptions.isSessionIdle). */
+	isSessionIdle?: () => boolean | undefined;
+	timer?: ReturnType<typeof setTimeout>;
+}
+
+/** Hung alerts queued but not yet handed to the host, keyed by runId. */
+const pendingHungDeliveries = new Map<string, PendingHungDelivery>();
+
+let deliverRetryMs = DEFAULT_DELIVER_RETRY_MS;
+let deliverCapMs = DEFAULT_DELIVER_CAP_MS;
+/** Delivery-time state loader (separate seam from the emit-time re-verify). */
+let deliveryLoader: ReverifyLoader = loadRunManifestById;
+
+/** @internal Test seam — reset module-level hung-alert dedup + delivery state. */
+export function resetHungAlertDedupForTests(): void {
+	hungAlertRecords.clear();
+	for (const entry of pendingHungDeliveries.values()) {
+		if (entry.timer !== undefined) clearTimeout(entry.timer);
+	}
+	pendingHungDeliveries.clear();
+	reverifyLoader = loadRunManifestById;
+	deliveryLoader = loadRunManifestById;
+	deliverRetryMs = DEFAULT_DELIVER_RETRY_MS;
+	deliverCapMs = DEFAULT_DELIVER_CAP_MS;
+}
+
+/** @internal Test seam — snapshot of the dedup map size (cap/leak assertions). */
+export function hungAlertDedupSizeForTests(): number {
+	return hungAlertRecords.size;
+}
+
+/** @internal Test seam — force-mark a runId as already alerted (cap assertions). */
+export function markHungAlertForTests(runId: string): void {
+	updateHungAlertRecord(runId, { alerted: true });
+}
+
+/** @internal Test seam — replace the pre-emit re-verify loader (null = real). */
+export function setReverifyLoaderForTests(loader: ReverifyLoader | null): void {
+	reverifyLoader = loader ?? loadRunManifestById;
+}
+
+/** @internal Test seam — replace the DELIVERY-time state loader (null = real). */
+export function setDeliveryLoaderForTests(loader: ReverifyLoader | null): void {
+	deliveryLoader = loader ?? loadRunManifestById;
+}
+
+/** @internal Test seam — shrink the idle-gate retry/cap timings. */
+export function setDeliveryTimingForTests(retryMs?: number, capMs?: number): void {
+	deliverRetryMs = typeof retryMs === "number" && retryMs > 0 ? retryMs : DEFAULT_DELIVER_RETRY_MS;
+	deliverCapMs = typeof capMs === "number" && capMs > 0 ? capMs : DEFAULT_DELIVER_CAP_MS;
+}
+
+/** @internal Test seam — hung alerts queued but not yet handed to the host. */
+export function hungAlertDeliveryPendingForTests(): number {
+	return pendingHungDeliveries.size;
+}
+
+/**
+ * Delivery-time verdict for a queued hung alert. `hung` = hand it to the host;
+ * `dropped` = the run is provably no longer hung, stay silent.
+ */
+type DeliveryVerdict = { kind: "hung" } | { kind: "dropped"; reason: string };
+
+/**
+ * Read the run state at handoff time. This is the WD-DELIVER-GUARD decision
+ * point: it runs immediately before `pi.sendUserMessage`, i.e. at the moment
+ * the host will actually deliver the message (session idle).
+ *
+ * Drop conditions (the exact user-visible pain):
+ *   • manifest status terminal (completed/failed/cancelled/blocked), or
+ *   • manifest still active BUT every task is terminal (stale record — the
+ *     finalize/worker write is merely behind).
+ * FAIL-OPEN: a loader that throws, or a vanished manifest, yields `hung` — an
+ * unreadable record must never swallow a genuine alert.
+ */
+function classifyAtDelivery(cwd: string, runId: string): DeliveryVerdict {
+	let loaded: Awaited<ReturnType<ReverifyLoader>>;
+	try {
+		loaded = deliveryLoader(cwd, runId);
+	} catch {
+		return { kind: "hung" }; // unreadable state → fail-open
+	}
+	if (!loaded) return { kind: "hung" }; // indeterminate → fail-open
+	if (!isActiveRunStatus(loaded.manifest.status)) {
+		return { kind: "dropped", reason: `status=${loaded.manifest.status}` };
+	}
+	if (areAllTasksTerminal(loaded.tasks)) {
+		return { kind: "dropped", reason: `all ${loaded.tasks.length} task(s) terminal (manifest ${loaded.manifest.status})` };
+	}
+	return { kind: "hung" };
+}
+
+/** True when the host would deliver a followUp message right now. */
+function sessionLooksIdle(probe: (() => boolean | undefined) | undefined): boolean {
+	if (typeof probe !== "function") return true; // no capability → pre-guard behavior
+	try {
+		return probe() !== false;
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * Try to hand one pending hung alert to the host. Re-arms itself while the
+ * session is streaming (the host would queue instead of deliver) and, at the
+ * idle boundary or past the cap, re-reads the run state ONCE and either drops
+ * or delivers.
+ */
+function attemptHungAlertDelivery(pi: ExtensionAPI, cwd: string, runId: string, force: boolean): void {
+	const entry = pendingHungDeliveries.get(runId);
+	if (!entry) return;
+	if (entry.timer !== undefined) {
+		clearTimeout(entry.timer);
+		entry.timer = undefined;
+	}
+	if (!force && !sessionLooksIdle(entry.isSessionIdle) && Date.now() < entry.deadline) {
+		const timer = setTimeout(() => attemptHungAlertDelivery(pi, cwd, runId, false), deliverRetryMs);
+		timer.unref();
+		entry.timer = timer;
+		return;
+	}
+
+	// Fallthrough covers BOTH exits: the idle boundary and the cap expiry
+	// (`Date.now() >= entry.deadline`, session still streaming), plus any forced
+	// flush from the map cap. No exit skips the re-verify — an alert that got
+	// old is not evidence the run is still hung, so the same drop conditions
+	// apply here and the debug log names the reason it was dropped.
+	const verdict = classifyAtDelivery(cwd, runId);
+	pendingHungDeliveries.delete(runId);
+	if (verdict.kind === "dropped") {
+		if (!hungAlertRecords.get(runId)?.droppedAtDeliveryLogged) {
+			updateHungAlertRecord(runId, { droppedAtDeliveryLogged: true });
+			debugLog(`[foreground-watchdog] drop hung alert for ${runId} at delivery: run is no longer hung (${verdict.reason})`);
+		}
+		return;
+	}
+	try {
+		pi.sendUserMessage(entry.text, { deliverAs: "followUp" });
+	} catch {
+		/* non-critical */
+	}
+}
+
+/**
+ * Queue a hung alert for guarded delivery (WD-DELIVER-GUARD). One in flight
+ * per runId — a second notice for the same run while the first is still
+ * pending is dropped as redundant drip.
+ */
+function queueHungAlertDelivery(
+	pi: ExtensionAPI,
+	cwd: string,
+	runId: string,
+	text: string,
+	isSessionIdle: (() => boolean | undefined) | undefined,
+): void {
+	if (pendingHungDeliveries.has(runId)) {
+		debugLog(`[foreground-watchdog] hung alert for ${runId} already pending delivery — not stacking another`);
+		return;
+	}
+	pendingHungDeliveries.set(runId, { text, deadline: Date.now() + deliverCapMs, isSessionIdle });
+	if (pendingHungDeliveries.size > HUNG_DELIVERY_CAP) {
+		// Defensive: never let the map grow and never delay a real alert —
+		// flush the oldest pending alert immediately (verify-then-send).
+		const oldest = pendingHungDeliveries.keys().next().value;
+		if (oldest !== undefined) attemptHungAlertDelivery(pi, cwd, oldest, true);
+	}
+	attemptHungAlertDelivery(pi, cwd, runId, false);
+}
+
+/** Drop a still-pending (not yet handed-over) hung alert for a runId. */
+function cancelPendingHungDelivery(runId: string): void {
+	const entry = pendingHungDeliveries.get(runId);
+	if (!entry) return;
+	if (entry.timer !== undefined) clearTimeout(entry.timer);
+	pendingHungDeliveries.delete(runId);
+}
+
 /** Stop a specific watchdog by runId. */
 export function stopWatchdog(runId: string): void {
 	const timer = activeWatchdogs.get(runId);
@@ -39,6 +355,7 @@ export function stopWatchdog(runId: string): void {
 		clearTimeout(timer);
 		activeWatchdogs.delete(runId);
 	}
+	cancelPendingHungDelivery(runId);
 }
 
 /** @internal Stop all active watchdogs. Called on session shutdown (RC-01). */
@@ -47,6 +364,10 @@ export function stopAllWatchdogs(): void {
 		clearTimeout(timer);
 	}
 	activeWatchdogs.clear();
+	for (const entry of pendingHungDeliveries.values()) {
+		if (entry.timer !== undefined) clearTimeout(entry.timer);
+	}
+	pendingHungDeliveries.clear();
 }
 
 /**
@@ -62,7 +383,7 @@ export function stopAllWatchdogs(): void {
  */
 export function startForegroundWatchdog(opts: WatchdogOptions): void {
 	const { pi, cwd, runId } = opts;
-	const checkIntervalMs = opts.checkIntervalMs ?? DEFAULT_CHECK_INTERVAL_MS;
+	const checkIntervalMs = resolveCheckIntervalMs(opts.checkIntervalMs);
 	const maxMonitorMs = opts.maxMonitorMs ?? DEFAULT_MAX_MONITOR_MS;
 	const startTime = Date.now();
 
@@ -111,23 +432,79 @@ export function startForegroundWatchdog(opts: WatchdogOptions): void {
 			const agents = readCrewAgents(manifest);
 			const now = Date.now();
 			if (isLikelyOrphanedActiveRun(manifest, agents, now)) {
-				const detail = `status=${manifest.status}, updatedAt=${manifest.updatedAt}, agents=${agents.length}`;
-				consecutiveHungNotices += 1;
-				try {
-					if (consecutiveHungNotices <= HUNG_NOTICE_CAP) {
-						pi.sendUserMessage(
-							`pi-crew watchdog: run ${runId} appears hung (${detail}). Consider running team action='cancel' runId='${runId}' or team action='doctor'.`,
-							{ deliverAs: "followUp" },
-						);
-					} else if (consecutiveHungNotices === HUNG_NOTICE_CAP + 1) {
-						// One-time handoff, then silence — still monitoring, no more drips.
-						pi.sendUserMessage(
-							`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.`,
-							{ deliverAs: "followUp" },
+				// WD-DEDUP (2026-10-23): re-verify the run state right before any
+				// emit. A check armed by an older poll cycle can race the run
+				// reaching a terminal status — alerting "appears hung" for a run
+				// that already finished is exactly the repeated-alert pain.
+				// Terminal (or vanished) at re-verify → skip the emit entirely;
+				// the next cycle's terminal branch delivers the completion notice.
+				const reverified = reverifyLoader(cwd, runId);
+				if (!reverified || !isActiveRunStatus(reverified.manifest.status)) {
+					const reason = reverified ? `status=${reverified.manifest.status}` : "manifest gone";
+					if (!hungAlertRecords.get(runId)?.skipLogged) {
+						updateHungAlertRecord(runId, { skipLogged: true });
+						debugLog(`[foreground-watchdog] skip hung alert for ${runId}: re-verify saw ${reason}`);
+					}
+					// Fall through to the shared schedule — keep monitoring; the next
+					// cycle hits the terminal branch (completion notice) or !loaded.
+				} else if (areAllTasksTerminal(reverified.tasks)) {
+					// WD-STALE-RECORD: manifest still says running, but every task is
+					// terminal → the run is done and only the record is behind. Stay
+					// silent about "hung" and tell the user ONCE that the record is
+					// stale (per runId, module-scope — no spam across restarts).
+					if (!hungAlertRecords.get(runId)?.skipLogged) {
+						updateHungAlertRecord(runId, { skipLogged: true });
+						debugLog(
+							`[foreground-watchdog] skip hung alert for ${runId}: record stale (manifest ${reverified.manifest.status}, all ${reverified.tasks.length} task(s) terminal)`,
 						);
 					}
-				} catch {
-					/* non-critical */
+					if (!hungAlertRecords.get(runId)?.staleNoticeSent) {
+						updateHungAlertRecord(runId, { staleNoticeSent: true });
+						try {
+							pi.sendUserMessage(`pi-crew watchdog: run ${runId} record stale (all tasks terminal) — skipped hung alert.`, {
+								deliverAs: "followUp",
+							});
+						} catch {
+							/* non-critical */
+						}
+					}
+					// 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.
+								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} 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 */
+					}
 				}
 				// Keep monitoring (ARCH-5: silently past the cap — no more notices).
 			} else {

package/src/runtime/model/model-fallback.ts

@@ -3,6 +3,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { getCrewEnv } from "../../config/env-vars.ts";
 import { errors } from "../../errors.ts";
+import type { UsageState } from "../../state/types.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { fuzzyResolveModelId } from "./model-resolver.ts";
 import { checkModelScope } from "./model-scope.ts";
@@ -19,6 +20,10 @@ export interface ModelAttemptSummary {
 	success: boolean;
 	exitCode?: number | null;
 	error?: string;
+	/** W10-7 (v0.11.38): THIS attempt's own usage (from its parsed output) —
+	 *  failed-fallback attempts burned real tokens that task.usage (the FINAL
+	 *  run's usage) never shows; post-execution reconciles the two. */
+	usage?: UsageState;
 }
 
 export interface ModelLike {

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

@@ -1193,6 +1193,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