pi-crew 0.11.39 → 0.11.41

package/package.json

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

package/skills/real-test-pi-crew/SKILL.md

@@ -120,6 +120,7 @@ End-to-end verification discipline for pi-crew changes. Distilled from the broke
 | `src/config/` (kể cả migration-validator) | T1 → T11c |
 | `src/runtime/child-pi/` (spawn/kill/steer) | T7 → T9g |
 | `src/runtime/process/**` (reap-group.ts / run-descendant-sweep.ts) + `child-pi-kill.ts` exited-root branch + `orphan-reaper.ts` identity admission + `crash-recovery.ts` terminal-sweep lane + state fields `childPgid/childStartTime/childUid` + heartbeat `pgid/starttime/uid` (wave-11 class: runtime spawn/kill/teardown + startup reconcile + state schema ADDITIVE) | T1 → pinned unit `test/unit/runtime/process/{reap-group,run-descendant-sweep}.test.ts` + `test/unit/runtime/recovery/reconcile-terminal-run-descendant-sweep.test.ts` + `test/unit/runtime/stale-reconciler-run-descendant-sweep.test.ts` + `test/unit/runtime/stale-reconciler-reap-escalation.test.ts` (5 file / 78 tests @ `f578c223`) → **integration live repro** `node scripts/test-runner.mjs test/integration/run-descendant-sweep-live.test.ts` (A1–A5: spawn leak THẬT → sweep reap ~100 ms; **negative control bắt buộc SỐNG**: no-marker / interactive-tty / parent-còn-sống) → off-path proof `PI_CREW_REAP_GROUP=0` + `PI_CREW_REAP_RUN_DESCENDANTS=0` (unit xanh trên CẢ hai trạng thái switch; KHÔNG để ambient `=0` sót lại làm run thật câm) → T9a `team action='doctor' focus='zombies'` (mảng `runDescendants` report-only + dòng cảnh báo no descent proof ⇒ NOT reaped) |
+| `test/**` — bất kỳ fixture nào spawn một process THẬT (đặc biệt `detached: true`), hoặc test fixture rò rỉ process (orphan còn sống sau khi assert throw) | T1 file vừa sửa (`node scripts/test-runner.mjs <file>` ×2 — teardown là timing-sensitive) + `pgrep -af "setInterva[l]"` phải RỖNG sau mỗi lần chạy + (khi đụng helper) `node scripts/test-runner.mjs test/unit/helpers/fixture-process.test.ts`. **Rule (wave 12c, `test/helpers/README.md`)**: fixture DETACHED ⇒ `spawnFixture`+`reapFixture` trong `finally` (pid-only `child.kill()` KHÔNG phải teardown: không chạm tree, vô hiệu trước fixture nuốt SIGTERM, và không chạy nếu throw TRƯỚC `finally`/trong setup hook) + snapshot identity ngay sau spawn (chống pgid reuse) + `registerFixtureTrap()` cho cửa sổ abort sớm; fixture NON-DETACHED ⇒ pid kill + comment lý do (group reap giết runner). Cảnh báo: `spawnFixture` THROW khi `detached:false` — đúng theo thiết kế |
 | `src/runtime/mcp-proxy.ts` / `src/runtime/model/pi-args.ts` (worker argv build + MCP role-gate — G2/G3 surface, SDD-2) | T7 (`argv-flags.smoke.ts` với `PI_CREW_SMOKE=1`) → T9b-W loadout theo role (post-G2: read-only KHÔNG có MCP trên live-session path là ĐÚNG — xem mục full-loadout sanity 9b) + pinned suites `mcp-proxy.test.ts` / `phase6-runtime-hardening.test.ts` / `child-pi-timeout`+`child-pi-surface` (argv/spill) |
 | `src/runtime/async-runner.ts` / `src/runtime/background-runner.ts` (spawn, allowlist, entry-guard, `executeBackgroundRun` core) | T1 → T9b async (event `async.spawned` KHÔNG được có `data.inline:true` — battery phải chứng minh runner DETACHED thật) → T7; đụng `BACKGROUND_RUNNER_ENV_ALLOWLIST` → thêm T10b/T10c (quirk F4-2026-08-30: mux env bị strip ⇒ async headless âm thầm) |
 | `src/runtime/surface/` | T10a → T10b → T10c (dò herdr bằng `HERDR_ENV=1`, KHÔNG phải `$TMUX`) |
@@ -194,6 +195,8 @@ End-to-end verification discipline for pi-crew changes. Distilled from the broke
 
 > **2026-10-24 đính chính (wave 11c — battery findings F1+F2, mục 4b/7b của `docs/real-test/reports/real-test-2026-10-24-wave11-battery.md`)**: (1) **F2 sync-run miss ĐÃ FIX** — run sync/foreground không có `manifest.async.pid` nên leak mang `PI_CREW_PARENT_PID=<session pi pid>` không bao giờ qua descent proof (đúng rule 11 — an toàn nhưng bỏ sót vĩnh viễn). Từ 11c mọi manifest mới record `sessionPid` (= `process.pid` tại `createRunManifest`); `sweepTerminalRunDescendants` + doctor dry-run đưa nó vào `proofParents` với guard dead-only như mọi parent khác — session còn sống ⇒ KHÔNG là proof (user có thể đang dùng). Run async vẫn dùng `async.pid` primary. Battery addendum sẽ chứng minh bằng E2E sync-leak thật. (2) **F1 test-isolation ĐÃ FIX** — suite `run-descendant-sweep.test.ts` giờ pin `PI_CREW_REAP_RUN_DESCENDANTS=1` trong beforeEach (restore verbatim afterEach, pattern của `stale-reconciler-run-descendant-sweep`): 17/78 test không đỏ nữa khi ambient `=0`; pinned 78→82 (a20 + g8–g10); decision-table yêu cầu "unit xanh trên CẢ HAI trạng thái switch" giữ nguyên.
 
+> **2026-10-24 update (wave 12 — test-fixture teardown, commits `75542295`→`a97714d2` + wave-12c F4/F6; spec `fixwave12-fixture-teardown-2026-10-24/SPEC.md`)**: lớp leak THỨ HAI, khác wave 11: 2 process `node -e "process.on('SIGTERM',()=>{}); setInterval(...)"` sống >6 h sau khi run `team_20261024024905_4cf882558c7c2b6d` completed — **test fixture**, không phải worker descendant: spawn `detached:true` (group riêng ⇒ group kill của runner không tới được) + teardown pid-only `child.kill()` (vô hiệu trước fixture nuốt SIGTERM) + không handle ⇒ không ai reap. Wave-11 sweep từ chối reap là **hành vi ĐÚNG** (không proof descent). (1) **Surface mới `test/helpers/fixture-process.ts`** — `spawnFixture` (THROW khi `detached:false`: child non-detached chia sẻ group của RUNNER, group kill sẽ giết runner + mọi file sibling; snapshot `readProcIdentity` NGAY sau spawn, normalise pgid=pid), `reapFixture` (group reap + escalation SIGTERM→SIGKILL, refusal chứng minh pid lạ ⇒ KHÔNG signal gì, pid-fallback cho non-Linux, không bao giờ throw), `registerFixtureTrap` (`after()` + `process.on("exit")` sync flush cho cửa sổ abort sớm). Rule viết 1 lần: `test/helpers/README.md`. (2) **GAP-1 (HIGH, wave 12c-F3)** — `background-runner-sigint-cleanup`: grandchild detached của harness giờ được reap theo group trong `finally` (harness giữ pid-only ĐÚNG — non-detached). (3) **GAP-2/GAP-3 (wave 12c-F3)** — fake `rg` tự ghi pid + reap group; `inference-broker` giữ `ChildProcess`, spawn detached + `reapFixture`/trap. (4) **GAP-4 (wave 12c-F4)** — `reap-group.test.ts`: teardown qua `reapTree` (leader-snapshot + group reap **TRƯỚC**, rồi pid kills idempotent) và `spawnTree()` tự reap group trên đường FAIL (timeout 15 s / spawn error / JSON hỏng) — trước đó leader biết, kids không ⇒ mồ côi toàn bộ. GAP-5 sweep: `guest-zombie` (detached thật) chuyển sang helper; 4 file còn lại là NON-detached ⇒ giữ pid kill + comment `// non-detached: pid-only by design (shares runner's group)`. (5) **Wave-12a bug tự gây** — thêm `test/unit/helpers/` mà không đăng ký shard weight ⇒ 4 test shard-partition fail (`ebe0138c`). (6) Battery cho wave này: T1 từng file đã sửa ×2 + `pgrep -af "setInterva[l]"` RỖNG + `test:unit` không tăng fail so baseline. (7) **Wave 12d lesson** — teardown test có async writer (`appendEventAsync` → `fs.promises.mkdir`) phải dùng `removeDirWithRetry` (`test/helpers/rm-retry.ts`: settle 250 ms + retry EBUSY/EPERM/ENOTEMPTY); `rmSync` trần ⇒ `ENOTEMPTY` dưới load vì writer tái tạo `runs/<runId>/` sau khi dir đã bị xoá.
+
 ## Core principle: disk ≠ live Pi
 
 Two locations hold pi-crew state:
@@ -1264,6 +1267,7 @@ When a tier fails, the recovery is usually quick. Match the symptom to the cause
 | `team action='schedule' interval=<ms>` always says `Invalid schedule "<N>ms". Use "5m", …` | handle-schedule builds `${interval}ms`; both interval parsers lacked an `ms` unit — every numeric interval died. Fixed 2026-09-21 | The suggested "5m" formats only work via `cron`/`once` params, not `interval` (interval is schema-typed as a plain ms number) |
 | Runs keep appearing under one scheduled job; children of YOUR pi process; machine thrashing | **Interval ≥ 2^31-1 ms (≥24.8 days) overflowed the Node timer to a 1ms hot loop** (fixed 2026-09-22 — clamped hops). Check `.crew/audit/prune.jsonl` for interleaved auto-prunes. Contain: remove job, then `pkill -f '[b]ackground-runner.ts --cwd <root>'` | Any new timer scheduling must clamp below MAX_TIMER_DELAY_MS — grep for `setInterval(`/`setTimeout(` with computed delays |
 | Live sweep/reap probe chạy "xanh" nhưng KHÔNG process nào bị reap (doctor `runDescendants` liệt kê mà không có gì chết) | **Ambient `PI_CREW_REAP_GROUP=0` / `PI_CREW_REAP_RUN_DESCENDANTS=0` còn trong shell** (sót từ probe off-path trước) — cả 2 switch default ON và được FORWARD sang background runner, ambient là đủ để câm sạch cả sweep lẫn group-reap; ngược lại quên set khi test off-path thì nhánh degrade không được chứng minh | Trước MỌI live repro: `env \| grep PI_CREW_REAP` phải RỖNG; chỉ set `=0` CHỦ ĐÍCH khi chạy nhánh off-path (unit phải xanh trên CẢ hai trạng thái switch), unset ngay sau (wave 11 lesson — 2 kill switch KHÔNG được set ngoài ý muốn theo cả 2 hướng) |
+| Process MỒ CÔI còn sống mang marker `PI_CREW_KIND=subagent` / `PI_CREW_TASK_ID` (hoặc đúng shape `node -e "setInterval(...)"`) trong khi run đã `completed` từ lâu, parent đã chết và process đã re-parent sang systemd | **Test-fixture teardown, KHÔNG phải runtime bug** (wave 12 incident: 2 fixture sống >6 h): fixture spawn DETACHED (group riêng ⇒ group kill của test runner không tới) + teardown pid-only `child.kill()` (vô hiệu trước fixture nuốt SIGTERM) + không ai giữ handle. Wave-11 sweep TỪ CHỐI reap là ĐÚNG — không chứng minh được descent của một run đã terminal | Kiểm `test/helpers/README.md`: detached ⇒ `spawnFixture`+`reapFixture` trong `finally`; non-detached ⇒ pid kill + comment. Grep suite vừa chạy tìm `detached: true` + `finally { … child.kill(` = thủ phạm; sửa teardown rồi `pgrep -af "setInterva[l]"` phải RỖNG. Đừng "fix" bằng cách nới wave-11 sweep cho process không proof descent |
 
 ## Release gate — battery → push → GitHub Actions GREEN → publish (canonical, 2026-10-14)
 
@@ -1442,6 +1446,7 @@ Use this to answer "đủ full tính năng chưa?" without re-deriving. Every us
 | Steer delivery incl. boot window (pre-bind retry) | `src/prompt/prompt-runtime.ts` (poll + `createSeenSteerIdSet.unmark`), `src/runtime/child-pi/child-pi-spawn.ts:283` (env), `src/runtime/task-runner/child-executor.ts:562` (filename) | `prompt-runtime-steer-boot-window.test.ts` (4) + **Tier 9g** live (watcher at +0.5s; lab variant with `PI_CREW_STEERING_FILE` + `pi --extension <repo>/src/prompt/prompt-runtime.ts`) |
 | Worker process-GROUP reaping (wave 11a F5 — đường group-signal DUY NHẤT) | `src/runtime/process/reap-group.ts` (`reapGroup` / `assertSafeGroup` guard-ladder 8 rung + escalation SIGTERM→poll→SIGKILL + `flushReapEscalationsSync`), wired `child-pi-kill.ts` exited-root (snapshot pgid/starttime trước khi root chết) + `orphan-reaper.ts` identity-proven admission | unit `node scripts/test-runner.mjs test/unit/runtime/process/reap-group.test.ts`; kill switch `PI_CREW_REAP_GROUP=0` (default ON — degrade về pid-only pre-wave; được FORWARD sang background runner); live: spawn worker có group con → kill root → group bị reap; **negative control bắt buộc: process cùng uid nhưng ngoài ladder (không leader-proof / không snapshot khớp) phải SỐNG** |
 | Run-descendant sweep (wave 11b F7 — reap leak sống sót SAU run terminal) | `src/runtime/process/run-descendant-sweep.ts` (`collectRunDescendants`/`reapRunDescendants`, 1 snapshot `/proc`/pass) + `crash-recovery.ts` `selectUnsweptTerminalRunIds` lane (terminal ≥ 60 s, oldest-first, cap 25/pass, window 200, retry `descendantSweepPending` 10 phút) | unit sweep suites (xem decision-table row wave 11) + **integration live repro** `node scripts/test-runner.mjs test/integration/run-descendant-sweep-live.test.ts` (A1–A5) + report `docs/real-test/reports/real-test-2026-10-24-wave11-descendant-reaping.md`; kill switch `PI_CREW_REAP_RUN_DESCENDANTS=0` (no-op hoàn toàn); marker ladder `PI_CREW_BROKER_RUN_ID` (nhánh run-id cần recorded parent ĐÃ CHẾT) → `PI_CREW_KIND=subagent`+`PI_CREW_TASK_ID` → `PI_CREW_PARENT_PID`; **negative control bắt buộc: no-marker / interactive-tty / parent-sống phải SỐNG** |
+| Fixture test spawn/reap (wave 12 — `test/helpers/`): đường DUY NHẤT một test được spawn + reap một process tree | `test/helpers/fixture-process.ts` (`spawnFixture` — từ chối `detached:false`, snapshot identity ngay sau spawn; `reapFixture` — group reap qua `reapGroup` + escalation SIGTERM→SIGKILL, pid-fallback cho non-Linux, KHÔNG BAO GIỜ throw; `registerFixtureTrap` — `after()` + `process.on("exit")` flush) + rule viết 1 lần ở `test/helpers/README.md` | unit `test/unit/helpers/fixture-process.test.ts` (h1–h5: refuse non-detached, reap tree nuốt SIGTERM < 2 s, idempotent, mismatch ⇒ không signal, trap 1 lần); regression theo file: `pgrep -af "setInterva[l]"` RỖNG sau mỗi lần chạy; GAP-4 pin `reap-group.test.ts` (teardown `reapTree` = leader-snapshot + group reap TRƯỚC, kể cả đường `spawnTree()` fail giữa đường) |
 
 ---
 

package/src/runtime/foreground-watchdog.ts

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

package/src/runtime/process/reap-group.ts

@@ -112,6 +112,18 @@ export interface ReapGroupOptions {
 	expected?: ProcIdentity;
 	/** Diagnostic label used in log messages. */
 	name?: string;
+	/**
+	 * uid source for the same-uid rungs (5 and the dead-path uid proof). Default
+	 * `() => process.getuid?.()` — production behaviour is unchanged. The seam
+	 * exists because `process.getuid` is undefined on win32, which made the uid
+	 * rungs untestable there without a process-wide monkeypatch.
+	 *
+	 * Read PER CALL and never cached: unlike `selfIdentity()` (which is cached
+	 * because a process cannot change its group), this is an injected value with
+	 * no invariant of its own, and caching it would make the first caller win for
+	 * the lifetime of the module.
+	 */
+	getuid?: () => number | undefined;
 }
 
 /** Sync verdict + the authoritative async verdict. */
@@ -226,6 +238,11 @@ export function __setSelfIdentityReaderForTest(reader: ((pid: number) => ProcIde
 	selfIdentityReader = reader ?? readProcIdentity;
 }
 
+/** Default uid source for the same-uid rungs: the real process uid, when the
+ *  runtime has one (POSIX). win32 has none ⇒ `undefined` ⇒ the rungs degrade
+ *  exactly as they did before the seam existed. */
+const defaultGetuid = (): number | undefined => process.getuid?.();
+
 /**
  * Run the refusal ladder. Returns the FIRST failing rung, or undefined when the
  * group is safe to signal. Pure with respect to injected `readIdentity` /
@@ -251,7 +268,7 @@ export function assertSafeGroup(pgid: number, candidatePid: number, opts: ReapGr
 	// state in which `kill(-pgid)` could take out the host session.
 	if (self.pgid === undefined) return "identity-missing";
 	if (pgid === process.pid || pgid === process.ppid || pgid === self.pgid) return "pgid-init-or-self";
-	const selfUid = typeof process.getuid === "function" ? process.getuid() : undefined;
+	const selfUid = (opts.getuid ?? defaultGetuid)();
 	// Rung 4: a LIVE candidate identity, or (dead candidate) leader-proof.
 	const live = readIdentity(candidatePid);
 	if (!live) {

package/src/runtime/process/run-descendant-sweep.ts

@@ -232,6 +232,18 @@ export interface SweepOptions {
 	 * and the doctor path are unchanged.
 	 */
 	snapshot?: ProcSnapshot;
+	/**
+	 * uid source for the same-uid rung (safety rung 3). Default
+	 * `() => process.getuid?.()` — production behaviour is unchanged. The seam
+	 * exists because `process.getuid` is undefined on win32, which made the rung
+	 * untestable there without a process-wide monkeypatch.
+	 *
+	 * It is honoured by BOTH halves of a sweep — discovery (`buildProcSnapshot`,
+	 * `collectRunDescendants`) and the group reap — so an injected uid is never
+	 * compared here and then ignored one call deeper (see the propagation note at
+	 * the `reapGroup` call site in `reapRunDescendants`).
+	 */
+	getuid?: () => number | undefined;
 }
 
 /** Sweep verdict: what was signalled, what was refused, what is still in flight. */
@@ -248,6 +260,10 @@ export interface RunSweepResult {
 	descendants: RunDescendant[];
 }
 
+/** Default uid source: the real process uid when the runtime has one (POSIX),
+ *  `undefined` on win32 — the pre-seam behaviour, unchanged. */
+const defaultGetuid = (): number | undefined => process.getuid?.();
+
 // ── default /proc readers (all best-effort, none throw) ──────────────────────
 
 /** `/proc/<pid>/environ` as a key=value record; undefined when unreadable. */
@@ -399,7 +415,7 @@ export function buildProcSnapshot(opts: SweepOptions = {}): ProcSnapshot {
 	const readIdentity = opts.readIdentity ?? readProcIdentity;
 	const readEnviron = opts.readEnviron ?? readProcEnviron;
 	const readTtyNr = opts.readTtyNr ?? readProcTtyNr;
-	const selfUid = typeof process.getuid === "function" ? process.getuid() : undefined;
+	const selfUid = (opts.getuid ?? defaultGetuid)();
 	const pids: number[] = [];
 	const entries = new Map<number, ProcSnapshotEntry>();
 	for (const pid of (opts.listPids ?? listProcPids)()) {
@@ -482,7 +498,7 @@ export function collectRunDescendants(markers: RunMarkers, opts: SweepOptions =
 	if ((opts.platform ?? process.platform) !== "linux") return [];
 	const readIdentity = opts.readIdentity ?? readProcIdentity;
 	const candidateStartMs = opts.candidateStartMs ?? defaultCandidateStartMs;
-	const selfUid = typeof process.getuid === "function" ? process.getuid() : undefined;
+	const selfUid = (opts.getuid ?? defaultGetuid)();
 	// Our own group: never a candidate's target group (belt to reap-group's rung).
 	const selfPgrp = readIdentity(process.pid)?.pgid;
 	// 11b.4 (LOW-4): ONE /proc view per call — supplied by the caller (a whole
@@ -715,6 +731,12 @@ export function reapRunDescendants(markers: RunMarkers, opts: SweepOptions = {})
 			...(opts.gracefulMs !== undefined ? { gracefulMs: opts.gracefulMs } : {}),
 			...(opts.capMs !== undefined ? { capMs: opts.capMs } : {}),
 			...(opts.platform !== undefined ? { platform: opts.platform } : {}),
+			// F5 propagation (wave 12b): the uid source MUST reach the ladder too.
+			// Discovery already used `opts.getuid`; forwarding only at that half would
+			// let a caller assert one uid policy and execute another (the sweep would
+			// prove a group safe against the injected uid while the ladder compared
+			// against the real one) — a silent split-brain, worse than no seam at all.
+			...(opts.getuid !== undefined ? { getuid: opts.getuid } : {}),
 		});
 		if (reap.refusal !== undefined) {
 			// Nothing was signalled. Leave the key unset so a later tick can retry