pi-crew 0.11.37 → 0.11.39

package/src/runtime/child-pi/child-pi-kill.ts

@@ -29,6 +29,7 @@ import { spawn } from "node:child_process";
 import { DEFAULT_CHILD_PI } from "../../config/defaults.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { TailCaptureStage } from "../compaction/compact-stages/tail-capture-stage.ts";
+import { type ProcIdentity, readProcIdentity, reapGroup, resolveReapGroupEnabled } from "../process/reap-group.ts";
 import { HARD_KILL_MS } from "./child-pi-constants.ts";
 import { adoptOwnedProcess, disposeAllOwnedProcesses, type OwnedProcess } from "./owned-process.ts";
 
@@ -44,6 +45,34 @@ const childHardKillTimers = new Map<number, NodeJS.Timeout>();
 // once the owner reaches its terminal state.
 const ownedByPid = new Map<number, OwnedProcess>();
 
+// Wave 11a (F1): the /proc identity snapshot of each registered child, taken
+// AT REGISTRATION (while the child is definitely alive). This is the only
+// pre-exit record of the child's pgid/starttime — once the root exits, /proc is
+// gone and `adoptOwnedProcess`'s live pgid resolution (owned-process.ts) has
+// nothing left to read, so a still-live group becomes unreachable. killProcessTree
+// uses this snapshot for the exited-root case; the 60 s sweep prunes it once the
+// owner is terminal.
+const identityByPid = new Map<number, ProcIdentity>();
+
+// Wave 11a injection seam (same shape as zombie-scanner.ts `__test`): tests seed
+// identity snapshots and swap the group reaper without a real child process.
+let reapGroupImpl: typeof reapGroup = reapGroup;
+export const __test = {
+	/** Seed the exit-time identity snapshot for a pid (as registerActiveChild would). */
+	seedIdentity(pid: number, identity: ProcIdentity | undefined): void {
+		if (identity === undefined) identityByPid.delete(pid);
+		else identityByPid.set(pid, identity);
+	},
+	/** Drop every seeded/recorded identity snapshot. */
+	clearIdentities(): void {
+		identityByPid.clear();
+	},
+	/** Replace the group reaper (undefined restores the real one). */
+	setReapGroup(fn: typeof reapGroup | undefined): void {
+		reapGroupImpl = fn ?? reapGroup;
+	},
+};
+
 // Periodic cleanup of dead child process entries to prevent memory leaks.
 // If a child process never emits exit/close (zombie), the entry would leak.
 setInterval(() => {
@@ -57,7 +86,10 @@ setInterval(() => {
 	// U15: prune adopted owners that reached terminal state (group confirmed
 	// gone via dispose or drain-reconcile). Non-terminal owners stay routable.
 	for (const [pid, owner] of ownedByPid) {
-		if (owner.terminated) ownedByPid.delete(pid);
+		if (!owner.terminated) continue;
+		ownedByPid.delete(pid);
+		// Wave 11a: the owner confirmed its group is gone — the snapshot is spent.
+		identityByPid.delete(pid);
 	}
 }, 60_000).unref();
 
@@ -69,6 +101,11 @@ export function registerActiveChild(pid: number, child: ChildProcess): void {
 	// (authoritative /proc check on Linux — the rpc branch child, spawned
 	// without detached, lands on the single-process fallback automatically).
 	ownedByPid.set(pid, adoptOwnedProcess(child, { name: `child-pi:${pid}` }));
+	// Wave 11a (F1): snapshot the identity NOW — the child is alive here, so
+	// /proc is readable. killProcessTree's exited-root branch reaps the group
+	// from this snapshot after the root is gone.
+	const identity = readProcIdentity(pid);
+	if (identity) identityByPid.set(pid, identity);
 }
 
 /**
@@ -220,7 +257,36 @@ export function killProcessTree(pid: number | undefined, child?: ChildProcess):
 		void owned.dispose();
 		return;
 	}
-	if (child && child.exitCode !== null) return;
+	if (child && child.exitCode !== null) {
+		// Wave 11a (F1): an EXITED ROOT IS NOT AN EMPTY GROUP. The root may have
+		// backgrounded descendants that are still alive in its process group; the
+		// pre-wave early-out returned here and left them running forever. We reap
+		// the group only when the registration-time snapshot PROVES the root was
+		// its own group leader (pgid === pid) — reapGroup re-validates everything
+		// (uid/pgid/starttime) and refuses on a recycled pgid. No snapshot, or a
+		// non-leader root, keeps the pre-wave behaviour exactly (no signal, and
+		// nothing logged above debug).
+		const identity = identityByPid.get(pid);
+		if (identity?.pgid === pid && resolveReapGroupEnabled()) {
+			const result = reapGroupImpl(pid, pid, { name: `child-pi:exited-root:${pid}`, expected: identity });
+			// MINOR #5 (review): the SIGKILL escalation is fire-and-forget here (this
+			// caller is sync), so it must be explicitly swallowed — `reapGroup` never
+			// rejects by contract, but a `void` promise is exactly what turns an
+			// unexpected rejection into a FATAL unhandled rejection on Node 22.
+			void result.pending.catch(() => {
+				/* settle-only: the escalation verdict is not actionable here */
+			});
+			identityByPid.delete(pid);
+		} else {
+			logInternalError(
+				"child-pi.kill-exited-root-no-snapshot",
+				new Error(`exited root pid=${pid} has no group-leader snapshot; no signal sent`),
+				`pid=${pid}`,
+				"debug",
+			);
+		}
+		return;
+	}
 	killProcessPid(pid);
 	child?.once("exit", () => clearHardKillTimer(pid));
 }

package/src/runtime/child-pi/child-pi-spawn.ts

@@ -37,6 +37,13 @@ import {
 	requireInferenceBrokerIfEnabled,
 } from "./inference-broker.ts";
 
+// v0.11.38 W10-1 (pi-subagents lesson #10): pi platform env that selects
+// short-lived prompt-cache retention for single-run worker processes
+// (long-retention cache writes carry a higher per-write surcharge — wasted on
+// a worker that exits after one task). Surface panes and RPC warm sessions do
+// NOT set this (their sessions persist and benefit from long-lived cache).
+export const PI_CACHE_RETENTION_ENV = "PI_CACHE_RETENTION";
+
 // ── Env allowlist (base set always passed to children) ──────────────────
 // Provider API keys are injected dynamically via buildScopedAllowList() only
 // when a model is assigned to the task (per-task key scoping).
@@ -191,6 +198,10 @@ export function buildChildPiSpawnOptions(
 		},
 		stdio: ["ignore", "pipe", "pipe"], // stdin=ignore: child doesn't wait for input; task comes via CLI args
 		detached: process.platform !== "win32",
+		// Wave 11a (GAP-5): `setsid` is NOT a Node spawn option — it is silently
+		// ignored. Group leadership comes from `detached` alone (POSIX setsid() in
+		// the child). Kept verbatim instead of deleted: removing it would suggest a
+		// behaviour change that never happened.
 		setsid: true,
 		// NOTE: setsid creates a new session; the child process becomes the session leader
 		// and its parent becomes that session leader (still the team-runner in the same
@@ -246,6 +257,7 @@ export function buildFinalChildPiSpawnOptions(
 	builtEnv: Record<string, string | undefined>,
 	model?: string,
 	modelChain?: (string | undefined)[],
+	workerCacheSplit?: boolean,
 ): SpawnOptions {
 	// (a) Canary: builtEnv must contain ONLY PI_CREW_*/PI_TEAMS_* keys.
 	assertOnlyControlEnvKeys(builtEnv);
@@ -267,6 +279,14 @@ export function buildFinalChildPiSpawnOptions(
 	if (inferenceSnapshot.active && builtEnv[INFERENCE_TOKEN_ENV]) {
 		spawnOptions.env[PI_AGENT_DIR_ENV] = inferenceSnapshot.scopedAgentDir ?? "";
 	}
+	// (c″) v0.11.38 W10-1 (pi-subagents lesson #10): cache TTL split. Worker
+	// processes are single-run and short-lived — pi's default prompt-cache
+	// retention is long (higher per-write surcharge). Only the headless worker
+	// branch opts in; surface panes and RPC warm sessions keep the parent's
+	// default (they persist and benefit from long-lived cache).
+	if (workerCacheSplit) {
+		spawnOptions.env[PI_CACHE_RETENTION_ENV] = "short";
+	}
 	// (d) Return the composed SpawnOptions for spawn(...).
 	return spawnOptions;
 }

package/src/runtime/child-pi/child-pi.ts

@@ -850,7 +850,9 @@ async function runChildPiInner(input: ChildPiRunInput): Promise<ChildPiRunResult
 			// Compose the final SpawnOptions: canary + filter + spread are now
 			// owned by buildFinalChildPiSpawnOptions (see child-pi-spawn.ts, BLOCKER 2 / S5).
 			// R6-8: modelChain threads the candidate chain for provider-key scoping.
-			const spawnOptions = buildFinalChildPiSpawnOptions(input.cwd, mergedEnv, builtEnv, input.model, input.modelChain);
+			// v0.11.38 W10-1: workerCacheSplit — headless single-run workers opt into
+			// short prompt-cache retention (see PI_CACHE_RETENTION_ENV).
+			const spawnOptions = buildFinalChildPiSpawnOptions(input.cwd, mergedEnv, builtEnv, input.model, input.modelChain, true);
 			// v0.11.36 OS boundary: when the sandbox is on, the headless spawn is
 			// wrapped in bwrap. Mounts: cwd RW (the worker edits the project), the
 			// scoped inference agent dir RW (pi writes session state under it), and

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/heartbeat/worker-heartbeat.ts

@@ -1,6 +1,10 @@
 export interface WorkerHeartbeatState {
 	workerId: string;
 	pid?: number;
+	/** Wave 11a (F3): spawn-time identity of `pid` (see `readProcIdentity`). */
+	pgid?: number;
+	starttime?: string;
+	uid?: number;
 	lastSeenAt: string;
 	lastStdoutAt?: string;
 	lastEventAt?: string;

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 {