pi-crew 0.11.19 → 0.11.21

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-crew",
-	"version": "0.11.19",
+	"version": "0.11.21",
 	"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

@@ -182,6 +182,10 @@ End-to-end verification discipline for pi-crew changes. Distilled from the broke
 >
 > **2026-10-13 update (pi-durable wave U22/U16/U21/U13-ADJ/U9-ADJ, branch `feat/pi-durable-upgrade`, commits `85917a44`..`1acd01e7`, 15 commits; spec `sdd-pi-durable-2026-10-13/`)**: (1) **U22 events.jsonl durability** — worker-atomic-writer hardened (fsync file+dir, per-request timeout `PI_CREW_WORKER_ATOMIC_TIMEOUT_MS`, `on("exit")` drain, temp-dir cache; opt-in như cũ); torn-vs-poison unified scanner (`parseJsonlWindow`) trên CẢ 4 đường read + sidecar `<events>.poison.jsonl`. **Marker LIFETIME RULE (bài học M1 — 2 reviewer độc lập hội tụ, 9k-test suite KHÔNG bắt được)**: marker chỉ hợp lệ cho file instance nó sinh ra — rotate MOVE sidecar theo archive, compact DELETE sidecar, và mọi marker-hit được RE-PARSE 1 lần trước khi skip (dòng parse được = marker đã lành, prune ngay) — layer này tự chữa cả marker bẩn same-uid; read-path giờ CÓ write side-effect (trust note security review). `sweepOldArchives` quét cả `<archive>.poison.jsonl`. (2) **Parameter-property recurrence (US-011 = R3-1 tái diễn)**: `WorkerRequestBookkeeper` constructor(private …) giết strip-types child — bắt bởi gate của PHASE KẾ (không phải phase tác giả); reinforced rule: chạy 1 file test spawn-child sau mọi phase đụng constructor syntax. (3) **U21 run-lock dual-guard** (file→socket, release socket→file, WAIT giữ nguyên): RR-011 token đăng ký NGAY sau file-acquire (cửa sổ socket-listen macrotask từng để token "vô hình" — steal-corpse hazard); flake F1 `team-tool-resume-liveness` từng note 2026-10-07 thực chất là RACE ASSUMPTION — giờ fix bằng acquired-signal deterministic (class flaky đóng). Deferred: uid-namespace cho lock name (F2 LOW). (4) **U16 usage ledger**: SDK chỉ có `getSessionStats()` — cả `getStats` lẫn fallback `session.stats` đều chết (embedded usage luôn undefined trước fix); 1 parser duy nhất, cost number|object(`total`), lifetimeUsage đủ cacheRead+cost; LIVE evidence: `team action=summary` hiển thị cacheRead. (5) **U13-ADJ layer-3 + never-fail-task belt** (chi tiết row U13 ở decision table). (6) **U9-ADJ noProgress hook** (dormant — chưa có production caller) + `owner`/`intent` additive (validators permissive cả tasks.json lẫn sqlite). (7) **Process**: lazy-imports budget 523→525 (poison-marker + process-lock, ratchet justified); dist committed (T11j `--committed-hash` yêu cầu khớp fresh build); 2 MAJOR bắt bởi review ĐỘC LẬP sau khi mọi gate xanh — durability paths CẦN review round, unit xanh không đủ. Suite anchors @ 2026-10-13 (`1acd01e7`): unit **9147 tests / 9143 pass / 1 fail = `subagent-tools-integration` teardown-race flake (14/14 ×2 isolated — class đã biết 2026-09-26, KHÔNG phải regression) / 3 skipped**, integration **144 / 140 pass / 0 fail / 4 skipped**, `test:critical` **120**, bundle **1,776,600 B (1735.0 KB)** md5 `c197855f917997a404ae39111d8ccfdc` (`--committed-hash` OK).
 
+> **2026-10-14 update (pi-durable FOLLOW-UP: P1 usage-tracker 5-field + m5 usage-bridge, P2 F2 uid-namespace lock name, P3 F4 noProgress budget; branch `feat/pi-durable-followup` 6 commits trên v0.11.19 `f10da4cc`)**: (1) **F2** — `runLockSocketName` prefix uid (`${uid}:run:${abs}`, "noid" fallback): abstract namespace là SYSTEM-WIDE — cùng path 2 user = collision; deploy-window an toàn vì file-lock vẫn guard chính. (2) **F4** — noProgress hook race `NO_PROGRESS_HOOK_TIMEOUT_MS=5000` (constant KHÔNG env — hook dormant, tránh allowlist surface); timer resolve false + log riêng; throw-path bit-for-bit (sync-throw trước timer tạo → timer undefined → propagates); Promise.race subscribe loser ⇒ late rejection không unhandled. (3) **P1** — tracker 5-field (cacheRead+cost NUMBER — object phải qua parser ở caller); m5 tách `live-session/usage-bridge.ts` (1963→1926, headroom 74; lazy-import ratchet 525→526); LIVE: tasks.json run thật `cacheRead:8512` + `cost:0.00743`. (4) **X1 audit cwd-oracle trust vs 0.11.12: PARTIAL hướng an toàn** — core byte-identical; 2 delta default-ON đều GIẢM over-trust; không đường nào tin layer-1 nhiều hơn baseline. (5) **PROBE QUIRK (durable)**: `timeout N pi -p` + sync team tool — wrapper có thể KHÔNG thoát sau run completed (12-10 treo 20h, 14-10 ~9' cho tới KILL) — run bên trong vẫn hoàn tất xanh; lấy evidence TỪ RUN-DIR (không phụ thuộc wrapper), dọn bằng kill PID trực tiếp (không pattern). (6) **Gate exit qua pipe**: `cmd | tail; echo $?` bắt exit của TAIL — lazy-imports từng 526>525 mà exit hiển thị 0; dùng log-file/pipefail cho mọi gate exit. Suite anchors @ 2026-10-14 (`b683c723`+skill): unit **9159 / 9155 pass / 1 fail = heartbeat-pulse timing flake (4/4 ×2 isolated, class timing-under-load) / 3 skipped**, integration **144 / 140 / 0 / 4**, `test:critical` **120**, bundle **1777312 B (1735.7 KB)** md5 `f1e5cc77608acdb6ef155f7adc4ebad6` (committed==fresh). Deferred mới: `state/usage.ts` LifetimeUsage 3-field lệch triết lý cacheRead vs tracker (m6 unify).
+
+> **2026-10-14 update #2 (dup-noti idle-gate + release 0.11.20 follow-up, commits `afc4fe9c`..HEAD trên cùng wave)**: (1) **DUP-NOTI RCA + FIX (live-caught 6×: P3/X1/E5 + 3 shards)** — noti trùng KHÔNG phải do emit 2 lần mà do `sendUserMessage(deliverAs:"followUp")` KHÔNG retract được (SDK `clearQueue()` all-or-nothing — dùng là phá luôn steering của user): leader consume mid-turn (get_subagent_result wait=true) → message ĐÃ queue vẫn deliver ở turn boundary = 1 turn phí mỗi lần. Rule-2 re-check canh SAI cửa sổ (chặn emit mới, không unsend được). **Fix = idle-gate** trong `subagent-manager-setup.ts`: `leaderTurnActive(ctx.currentCtx.isIdle())` (capability-guarded — host thiếu = bit-for-bit, pinned bởi Rule1-3 integration chạy trên fallback) + `runWhenLeaderIdle` (retry 500ms, cap 10' — muộn hơn never nhưng re-check vẫn chặn consumed quá cap); coalescer flush idle-gate TRƯỚC splice; batch path NOTIFY_DEFER_MS bị subsume (đã xóa). **Probe-quirk mở rộng**: fresh `pi -p` + prompt nặng (đụng crew_agent/team tool) có thể treo 0-output trong khi prompt đơn giản OK (provider-side, không phải pi-crew) — idle-gate live-probe qua đường này có thể bị chặn bởi môi trường; khi đó dựa vào unit (5/5 pin đúng race semantics) + Rule1-3 14/14. (2) **Goal FALSE-GREEN fix**: `goalDeclaresReadOnly` (marker EN+VI literal, explicit-intent) + bước (1b) — live-proven run `14022151` ("goal declared read-only (no edits expected)"). (3) **m6**: state/usage.ts dead 3-field family xóa; RoleUsage +cacheRead; ledger-vs-display docblock (#38 chỉ đúng cho display/budget-proxy). (4) Suite anchors @ 0.11.20-tree (`8e70e66f`): unit **9146 / 9143 pass / 0 fail / 0 cancelled / 3 skipped** (composition đổi sau m6 −dead-describe), critical **120**, bundle **1,778,118 B (1736.4 KB)** md5 `8e70e66f543106b1ac34902bd4047302` (committed==fresh), census 15.
+
 ## Core principle: disk ≠ live Pi
 
 Two locations hold pi-crew state:
@@ -1252,6 +1256,27 @@ 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 |
 
+## Release gate — battery → push → GitHub Actions GREEN → publish (canonical, 2026-10-14)
+
+Local `npm run ci` là LINUX-ONLY — không thay được matrix 3-OS của GitHub Actions.
+Live-proven 2026-10-14: **0.11.19 và 0.11.20 đều publish khi CI GitHub ĐỎ** (local ci + pre-push
+hook xanh hết) — windows fail do child-env thiếu `SYSTEMROOT` (node con không khởi tạo Winsock được,
+stdout rỗng); macOS fail do transient ECONNREFUSED khiến accepting-probe 1 lần coi holder SỐNG là
+corpse → xóa file socket + rebind (STEAL lock) — fix bằng 3-strike takeover (`process-lock.ts`).
+
+**Quy trình BẮT BUỘC cho mọi release (theo thứ tự, không bỏ bước):**
+
+1. Cập nhật skill (wave entry) + CHANGELOG heading cho version sắp release — commit.
+2. Chạy battery theo decision table (đủ tier cho paths đổi) — xanh hết.
+3. `npm version patch` (tạo release commit + tag).
+4. `git push origin main --follow-tags` — pre-push hook tự chạy full unit local.
+5. **`gh run watch <runId> --exit-status` (hoặc poll `gh run list`) — CHỜ matrix 3-OS XANH TOÀN BỘ.**
+   CI đỏ ⇒ KHÔNG publish — fix, push lại, chờ lại. (Check nhanh fail: `gh run view <id>` +
+   `gh api repos/<o>/<r>/actions/jobs/<jobId>//logs` — KHÔNG grep "not ok" mù: tên test có thể
+   chứa literal "not ok" ("malformed JSON is not ok with a message") — grep kèm assertion block.)
+6. CHỈ KHI xanh: `npm publish` → poll `npm view <pkg> dist-tags.latest` → `gh release create`.
+7. Post-release: knowledge.md entry SHIPPED + dọn branch/scratch.
+
 ## Performance budget (per-tier soft limits)
 
 | Tier | Soft limit | Hard limit | What happens over hard limit |

package/src/extension/registration/subagent-manager-setup.ts

@@ -2,7 +2,7 @@
  * Subagent manager installer for pi-crew.
  *
  * Wires the SubagentManager singleton with:
- *   • a terminal-status callback (Rules 1 + 2 + 3):
+ *   • a terminal-status callback (Rules 1 + 2 + 3 + idle-gate):
  *     - Rule 1 (batch coalescing): explicit batchId → ONE consolidated notify
  *       when all members terminal.
  *     - Rule 2 (consume-race fix): resultConsumed re-check so a leader that
@@ -12,6 +12,12 @@
  *       produce 1 notice — not N drips delivered one-per-turn at turn
  *       boundaries (the symptom: leader joins all, then redundant per-agent
  *       "changed state" notices keep dripping in over later turns).
+ *     - Idle-gate (2026-10-14, dup-close): a queued followUp wake-up cannot be
+ *       retracted (clearQueue is all-or-nothing), so while the leader's turn
+ *       is active the emit is DEFERRED and the resultConsumed re-check re-runs
+ *       once the session is idle — the moment the message would actually
+ *       deliver. A leader that proactively joins the result mid-turn
+ *       (get_subagent_result wait=true) never sees the stale drip.
  *   • an internal event forwarder (subagent.stuck-blocked → notification),
  *   • a hard cap on concurrent subagents (4).
  *
@@ -27,13 +33,6 @@ import { sendAgentWakeUp } from "./subagent-helpers.ts";
 const MAX_CONCURRENT_SUBAGENTS = 4;
 const SUBAGENT_DEFAULT_TIMEOUT_MS = 1000;
 
-/**
- * Defer window for the BATCH path (explicit batchId). Gives the leader a chance
- * to consume batch members before the consolidated notify emits; the
- * resultConsumed re-check then suppresses.
- */
-const NOTIFY_DEFER_MS = 1500;
-
 /**
  * Coalesce window for NON-batch background completions (Rule 3). Completions
  * within this window (debounced — the timer resets on each new arrival) merge
@@ -46,6 +45,63 @@ const NOTIFY_DEFER_MS = 1500;
  */
 const NOTIFY_COALESCE_MS = 800;
 
+/**
+ * Idle-gate retry cadence (dup-close, 2026-10-14). A queued followUp wake-up
+ * CANNOT be retracted once `sendUserMessage` has queued it (the SDK's
+ * `clearQueue()` is all-or-nothing — it would also destroy the user's own
+ * pending steering). So while the leader's turn is ACTIVE we keep DEFERRING
+ * the emit and re-running the resultConsumed check; the wake-up only queues
+ * once the session is idle — the moment it will actually be delivered — which
+ * closes the duplicate class where the leader proactively joins the result
+ * mid-turn and then gets a stale "changed state" drip at the turn boundary
+ * (live-caught 6× 2026-10-13/14: P3/X1/E5 + 3 research shards).
+ */
+const IDLE_RETRY_MS = 500;
+
+/**
+ * Hard cap for the idle-gate deferral. Leader turns can be long; after the
+ * cap the wake-up is emitted anyway (late beats never) — the resultConsumed
+ * re-check still runs first, so a consumed agent never re-notifies even past
+ * the cap.
+ */
+const IDLE_EMIT_CAP_MS = 10 * 60_000;
+
+/**
+ * True when the leader's own turn is ACTIVE (session streaming). Capability-
+ * guarded: an older host without `ctx.isIdle` (or a bare/absent currentCtx)
+ * reports "not active" so the emit path stays bit-for-bit with the pre-gate
+ * behavior.
+ * @internal — exported for unit tests.
+ */
+export function leaderTurnActive(ctx: RegistrationContext): boolean {
+	const c = ctx.currentCtx;
+	if (!c || typeof c.isIdle !== "function") return false;
+	try {
+		return c.isIdle() === false;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Run `fn` once the leader turn is idle (or immediately when it already is /
+ * the host lacks the capability / the cap expires). `fn` must be safe to call
+ * late: it re-runs its own consume/owner re-checks first.
+ * @internal — exported for unit tests.
+ */
+export function runWhenLeaderIdle(ctx: RegistrationContext, fn: () => void): void {
+	const deadline = Date.now() + IDLE_EMIT_CAP_MS;
+	const attempt = (): void => {
+		if (ctx.cleanedUp) return;
+		if (!leaderTurnActive(ctx) || Date.now() >= deadline) {
+			fn();
+			return;
+		}
+		setTimeout(attempt, IDLE_RETRY_MS);
+	};
+	attempt();
+}
+
 /** A pending non-batch completion awaiting coalesced emit. */
 interface PendingCompletion {
 	agentId: string;
@@ -64,6 +120,7 @@ interface CompletionCoalescer {
 function createCompletionCoalescer(pi: ExtensionAPI, ctx: RegistrationContext): CompletionCoalescer {
 	let pending: PendingCompletion[] = [];
 	let timer: ReturnType<typeof setTimeout> | null = null;
+	let cycleDeadline = 0;
 
 	/** True if the completion is still deliverable (not consumed, current session). */
 	const isLive = (c: PendingCompletion): boolean => {
@@ -80,17 +137,29 @@ function createCompletionCoalescer(pi: ExtensionAPI, ctx: RegistrationContext):
 			pending = [];
 			return;
 		}
+		// Idle-gate (dup-close): defer the emit while the leader's own turn is
+		// active — a queued followUp cannot be retracted, so we only queue it at
+		// the moment it will actually be delivered. The consume re-check below
+		// then runs at THAT moment: a leader that joined the result mid-turn
+		// suppresses the notify entirely instead of receiving a stale drip.
+		// Past the cap we emit anyway (late beats never).
+		if (leaderTurnActive(ctx) && Date.now() < cycleDeadline) {
+			timer = setTimeout(flush, IDLE_RETRY_MS);
+			return;
+		}
 		const batch = pending.splice(0);
-		if (batch.length === 0) return;
-		// Rule 2: drop agents the leader already consumed during the window.
-		const live = batch.filter(isLive);
-		if (live.length === 0) return;
-		if (live.length === 1) emitIndividualCompletion(pi, ctx, live[0]!);
-		else emitConsolidatedCompletions(pi, ctx, live);
+		if (batch.length > 0) {
+			// Rule 2: drop agents the leader already consumed during the window.
+			const live = batch.filter(isLive);
+			if (live.length === 1) emitIndividualCompletion(pi, ctx, live[0]!);
+			else if (live.length > 1) emitConsolidatedCompletions(pi, ctx, live);
+		}
+		if (pending.length === 0) cycleDeadline = 0;
 	};
 
 	return {
 		enqueue(completion) {
+			if (pending.length === 0) cycleDeadline = Date.now() + IDLE_EMIT_CAP_MS;
 			pending.push(completion);
 			if (timer) clearTimeout(timer);
 			timer = setTimeout(flush, NOTIFY_COALESCE_MS);
@@ -250,9 +319,10 @@ function onTerminalStatus(
 	const agentRunId = record.runId;
 	const agentBatchId = record.batchId;
 
-	// Rule 1 (batch): defer + BatchBarrier consolidated emit.
+	// Rule 1 (batch): defer + BatchBarrier consolidated emit, idle-gated so the
+	// consume re-check runs at the moment the wake-up actually queues.
 	if (agentBatchId) {
-		setTimeout(() => {
+		runWhenLeaderIdle(ctx, () => {
 			if (ctx.cleanedUp) return;
 			const fresh = ctx.subagentManager.getRecord(agentId);
 			const persisted = ctx.currentCtx ? readPersistedSubagentRecord(ctx.currentCtx.cwd, agentId) : undefined;
@@ -290,7 +360,7 @@ function onTerminalStatus(
 			}
 			// Either we just emitted the consolidated notify, or we are still
 			// waiting for other members — in both cases do NOT emit individually.
-		}, NOTIFY_DEFER_MS);
+		});
 		return;
 	}
 

package/src/runtime/goal-workflow/goal-achievement.ts

@@ -10,6 +10,9 @@
  * the false-green is no longer SILENT. It is deliberately conservative:
  *   - read-only / doc-only workflows are never accused (they legitimately make
  *     no project-code edits; their outputs land in gitignored .crew/),
+ *   - a goal that EXPLICITLY declares read-only intent (marker phrase) is
+ *     never accused either, even when the workflow shape is mutating —
+ *     explicit intent beats workflow shape (see `goalDeclaresReadOnly`),
  *   - a false-green is only flagged for CODE-MUTATING runs (executor /
  *     test-engineer steps) in a git repo whose working tree is empty,
  *   - status is downgraded to "failed" ONLY when a corroborating signal (a
@@ -59,6 +62,38 @@ export function isGitWorkingTreeClean(cwd: string): { clean: boolean; repoRoot:
 	}
 }
 
+/**
+ * Goal-text markers that EXPLICITLY declare a read-only task. Each entry is
+ * matched as a substring, case-insensitively, against whitespace-collapsed
+ * lowercase goal text (`goalDeclaresReadOnly`). Keep this list short and
+ * literal — one phrase per line — so it is trivial to extend. Longer phrases
+ * already covered by a shorter entry are intentionally omitted (e.g.
+ * "do not modify, create, or delete" is covered by "do not modify").
+ */
+const READ_ONLY_GOAL_MARKERS: readonly string[] = [
+	"read-only",
+	"read only",
+	"do not modify",
+	"don't modify",
+	"no file modifications",
+	"không sửa",
+	"không chỉnh sửa",
+	"chỉ đọc",
+];
+
+/**
+ * Explicit-intent detector, deliberately conservative: returns true ONLY when
+ * the goal text contains one of the literal READ_ONLY_GOAL_MARKERS phrases
+ * (case-insensitive, whitespace-collapsed). No semantic guessing — a goal
+ * that merely *sounds* non-mutating is NOT suppressed. Battery/probe goal
+ * conventions use exactly these phrases.
+ */
+export function goalDeclaresReadOnly(goal: string | undefined): boolean {
+	if (typeof goal !== "string" || goal.length === 0) return false;
+	const normalized = goal.toLowerCase().replace(/\s+/g, " ").trim();
+	return READ_ONLY_GOAL_MARKERS.some((marker) => normalized.includes(marker));
+}
+
 /**
  * Assess whether a completed run achieved its goal. Pure function over manifest
  * + tasks + workflow — no side effects, easy to unit-test.
@@ -78,6 +113,18 @@ export function assessGoalAchievement(
 		};
 	}
 
+	// (1b) Explicit-intent detector: the WORKFLOW is mutating, but the GOAL TEXT
+	//      explicitly declares a read-only task — a clean tree is then EXPECTED,
+	//      never an accusation. Deliberately conservative (literal markers only,
+	//      no semantic guessing); battery/probe conventions use these phrases.
+	if (goalDeclaresReadOnly(manifest.goal)) {
+		return {
+			achieved: "unknown",
+			reason: "goal declared read-only (no edits expected)",
+			signals: [],
+		};
+	}
+
 	// (2) Need a git repo to inspect the working tree.
 	const tree = isGitWorkingTreeClean(manifest.cwd);
 	if (tree.clean === "unknown" || !tree.repoRoot) {

package/src/runtime/live-session/live-session-runtime.ts

@@ -43,8 +43,6 @@ import {
 // in a single place: the shared user prompt. See G3 fix.
 import { createStreamingOutput, type StreamingOutputHandle } from "../output/streaming-output.ts";
 import { buildSensitivePathConstraint } from "../sensitive-paths.ts";
-import { usageFromValue } from "../session-usage.ts";
-import { trackTaskUsage } from "../usage-tracker.ts";
 import {
 	buildYieldReminder,
 	DEFAULT_YIELD_CONFIG,
@@ -89,6 +87,7 @@ import {
 import { hasLiveControlRealtimeListeners, subscribeLiveControlRealtime } from "./live-control-realtime.ts";
 import { buildExtensionBridge } from "./live-extension-bridge.ts";
 import { collectLiveSessionHealth, formatLiveSessionDiagnostics } from "./live-session-health.ts";
+import { type SessionStatsLike, trackUsageFromMessageEndEvent, usageFromSessionStats } from "./usage-bridge.ts";
 
 /**
  * Module-scoped latch for the optional peer dependency import. When N
@@ -235,13 +234,8 @@ type LiveSessionLike = {
 	steer?: (text: string) => Promise<void>;
 	abort?: () => Promise<void> | void;
 	dispose?: () => void;
-	/** U16: SDK AgentSession session-level stats surface (aggregate tokens + cost);
-	 *  shaped like live-agent-manager's LiveSessionHandle so the session can be
-	 *  registered there without a cast (extra SDK fields like cost pass structurally). */
-	getSessionStats?: () => {
-		tokens?: { input?: number; output?: number; cacheWrite?: number; cacheRead?: number };
-		contextUsage?: { percent?: number | null; window?: number };
-	};
+	/** U16: SDK AgentSession session-level stats surface (aggregate tokens + cost) — shape: usage-bridge.ts (SessionStatsLike). */
+	getSessionStats?: () => SessionStatsLike;
 	bindExtensions?: (bindings?: Record<string, unknown>) => Promise<void>;
 	getActiveToolNames?: () => string[];
 	setActiveToolsByName?: (names: string[]) => void;
@@ -469,24 +463,6 @@ function applyModelProviderOverride(session: LiveSessionLike | undefined, provid
 	}
 }
 
-/**
- * Type-safe extractor for message role from streaming events.
- * Handles the case where message may be a Record with a role field.
- */
-function extractMessageRole(obj: Record<string, unknown> | undefined): string | undefined {
-	const message = obj?.message ? asRecord(obj.message) : undefined;
-	return isString(message?.role) ? message.role : undefined;
-}
-
-/**
- * Type-safe extractor for message usage from streaming events.
- * Handles the case where message may be a Record with usage data.
- */
-function extractMessageUsage(obj: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
-	const message = obj?.message ? asRecord(obj.message) : undefined;
-	return message?.usage && typeof message.usage === "object" ? (message.usage as Record<string, unknown>) : undefined;
-}
-
 /**
  * Type-safe extractor for tool name from streaming events.
  * Handles various event structures: { tool: { name } }, { toolName }, { name }.
@@ -791,13 +767,9 @@ function filterActiveTools(session: LiveSessionLike, agent: AgentConfig, role?:
 	session.setActiveToolsByName(active);
 }
 
-/** U16 (Fix B): thin adapter — session-stats parsing is delegated to the single
- *  shared parser (`usageFromValue`), which accepts BOTH the nested SDK
- *  `SessionStats` shape (`tokens.{input,output,cacheRead,cacheWrite}` + `cost`)
- *  and flat legacy shapes. Exported for unit tests. */
-export function usageFromStats(stats: unknown): UsageState | undefined {
-	return usageFromValue(stats);
-}
+// U16 (Fix B): the usageFromStats thin adapter moved to usage-bridge.ts (m5);
+// re-exported here so the historical import surface keeps working.
+export { usageFromStats } from "./usage-bridge.ts";
 
 /**
  * U4 hung-tool escape hatch marker error. Thrown when a timed-out prompt did
@@ -1531,17 +1503,9 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 							}
 						}
 					}
-					// Accumulate lifetime usage that survives compaction
-					if (obj?.type === "message_end" && extractMessageRole(obj) === "assistant") {
-						const u = extractMessageUsage(obj);
-						if (u) {
-							trackTaskUsage(input.task.id, {
-								input: typeof u.input === "number" ? u.input : 0,
-								output: typeof u.output === "number" ? u.output : 0,
-								cacheWrite: typeof u.cacheWrite === "number" ? u.cacheWrite : 0,
-							});
-						}
-					}
+					// P1: accumulate lifetime usage that survives compaction — message-level
+					// deltas incl. cacheRead + numeric cost (parsed in usage-bridge).
+					trackUsageFromMessageEndEvent(input.task.id, event);
 					input.onEvent?.(event);
 					const text = [...eventText(event), ...finalAssistantText(event)].join("\n");
 					if (text.trim()) {
@@ -1789,9 +1753,8 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 						emit: emitEmbedded,
 					})
 				: undefined;
-		// U16 (Fix A): the SDK surface is getSessionStats() — the old getStats()
-		// name and session.stats fallback were both dead against the real SDK.
-		const usage = usageFromStats(session.getSessionStats?.());
+		// U16 (Fix A): the real SDK surface is getSessionStats() — see usage-bridge.
+		const usage = usageFromSessionStats(session);
 		updateLiveAgentStatus(agentId, "completed");
 		markLiveAgentCompleted(agentId);
 		return {

package/src/runtime/live-session/usage-bridge.ts

@@ -0,0 +1,93 @@
+import type { UsageState } from "../../state/types.ts";
+import { usageFromValue } from "../session-usage.ts";
+import { trackTaskUsage } from "../usage-tracker.ts";
+
+/**
+ * m5 (P1): the live-session usage bridge, extracted from
+ * live-session-runtime.ts (1963 → ≤2000-line wc-gate relief). Owns every pure
+ * shape/parser helper that maps pi SDK session surfaces onto pi-crew's usage
+ * ledger — the runtime module keeps only the call sites.
+ */
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+function isString(value: unknown): value is string {
+	return typeof value === "string";
+}
+
+/**
+ * U16: SDK AgentSession session-level stats surface (aggregate tokens + cost);
+ * shaped like live-agent-manager's LiveSessionHandle so the session can be
+ * registered there without a cast (extra SDK fields like cost pass structurally).
+ */
+export interface SessionStatsLike {
+	tokens?: { input?: number; output?: number; cacheWrite?: number; cacheRead?: number };
+	contextUsage?: { percent?: number | null; window?: number };
+}
+
+/**
+ * Type-safe extractor for message role from streaming events.
+ * Handles the case where message may be a Record with a role field.
+ */
+function extractMessageRole(obj: Record<string, unknown> | undefined): string | undefined {
+	const message = obj?.message ? asRecord(obj.message) : undefined;
+	return isString(message?.role) ? message.role : undefined;
+}
+
+/**
+ * Type-safe extractor for message usage from streaming events.
+ * Handles the case where message may be a Record with usage data.
+ */
+function extractMessageUsage(obj: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+	const message = obj?.message ? asRecord(obj.message) : undefined;
+	return message?.usage && typeof message.usage === "object" ? (message.usage as Record<string, unknown>) : undefined;
+}
+
+/** U16 (Fix B): thin adapter — session-stats parsing is delegated to the single
+ *  shared parser (`usageFromValue`), which accepts BOTH the nested SDK
+ *  `SessionStats` shape (`tokens.{input,output,cacheRead,cacheWrite}` + `cost`)
+ *  and flat legacy shapes. Re-exported by live-session-runtime.ts to keep its
+ *  historical import surface green. */
+export function usageFromStats(stats: unknown): UsageState | undefined {
+	return usageFromValue(stats);
+}
+
+/** Minimal session surface the completion site needs. */
+interface SessionWithStats {
+	getSessionStats?: () => unknown;
+}
+
+/**
+ * U16 (Fix A): the SDK surface is getSessionStats() — the old getStats()
+ * name and session.stats fallback were both dead against the real SDK.
+ */
+export function usageFromSessionStats(session: SessionWithStats | undefined): UsageState | undefined {
+	return usageFromStats(session?.getSessionStats?.());
+}
+
+/**
+ * P1 (AC4): accumulate lifetime usage that survives compaction from one
+ * streaming event. Only assistant `message_end` events contribute. The
+ * message-level usage object is parsed by the SHARED parser so the new
+ * `cacheRead` field and the message-level cost OBJECT (`{…, total}`) both land
+ * as NUMBERS in the tracker — usage-tracker deltas accept numeric cost only
+ * (D2 aggregate tier). Non-finite fields parse to undefined and are skipped
+ * (pre-P1 the raw `typeof` check passed 0 — same arithmetic result).
+ */
+export function trackUsageFromMessageEndEvent(taskId: string, event: unknown): void {
+	const obj = asRecord(event);
+	if (obj?.type !== "message_end" || extractMessageRole(obj) !== "assistant") return;
+	const raw = extractMessageUsage(obj);
+	if (!raw) return;
+	const usage = usageFromValue(raw);
+	if (!usage) return;
+	trackTaskUsage(taskId, {
+		input: usage.input,
+		output: usage.output,
+		cacheWrite: usage.cacheWrite,
+		cacheRead: usage.cacheRead,
+		cost: usage.cost,
+	});
+}

package/src/runtime/recovery/retry-executor.ts

@@ -83,6 +83,10 @@ export interface RetryHooks {
 	 * logInternalError (the repo's console.error wrapper) and treated as false —
 	 * a broken detector must never change retry behavior. Unregistered ⇒
 	 * behaviour is bit-for-bit pre-U9-ADJ.
+	 * F4 (follow-up 2026-10-14 §P3): the hook must settle within
+	 * NO_PROGRESS_HOOK_TIMEOUT_MS (5s) — anything slower (or never-settling)
+	 * is treated as false and logged (retry-executor.noProgressTimeout), so a
+	 * hung detector can never hang the retry loop itself.
 	 */
 	noProgress?: (context: {
 		attempt: number;
@@ -130,6 +134,52 @@ function retryAttemptInfo(attempt: number, hooks: RetryHooks): RetryAttemptInfo
 	};
 }
 
+/**
+ * F4 (follow-up SPEC 2026-10-14 §P3): wall-clock budget for ONE `noProgress`
+ * hook invocation. Deliberately NOT configurable (no env var / no param): the
+ * hook is dormant (no production caller yet) and a new env-allowlist entry
+ * would be pure surface. Exceeded budget ⇒ hook treated as false (progress
+ * assumed, retry stays queued) + logInternalError("retry-executor.noProgressTimeout").
+ */
+const NO_PROGRESS_HOOK_TIMEOUT_MS = 5000;
+
+/**
+ * F4: race the `noProgress` hook against NO_PROGRESS_HOOK_TIMEOUT_MS. The
+ * timer RESOLVES false (never rejects); hook throws/rejections propagate
+ * unchanged so the existing soft-fail catch in executeWithRetry stays
+ * bit-for-bit. The timer handle is cleared the moment the race settles —
+ * fast hooks leave no pending handle behind, and a never-settling hook is
+ * abandoned once its budget resolved (no dangling handle keeps the loop alive).
+ */
+async function settleNoProgressHook(
+	hook: NonNullable<RetryHooks["noProgress"]>,
+	context: { attempt: number; lastResult: unknown; previousResult: unknown; durationMsLast: number },
+): Promise<boolean> {
+	let timedOut = false;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		return await Promise.race([
+			Promise.resolve(hook(context)),
+			new Promise<false>((resolve) => {
+				timer = setTimeout(() => {
+					timedOut = true;
+					resolve(false);
+				}, NO_PROGRESS_HOOK_TIMEOUT_MS);
+			}),
+		]);
+	} finally {
+		if (timer !== undefined) clearTimeout(timer);
+		if (timedOut) {
+			logInternalError(
+				"retry-executor.noProgressTimeout",
+				{ attempt: context.attempt, timeoutMs: NO_PROGRESS_HOOK_TIMEOUT_MS },
+				"soft-fail: treating as progress, retry stays queued",
+				"error",
+			);
+		}
+	}
+}
+
 export async function executeWithRetry<T>(
 	fn: (attempt: number, info: RetryAttemptInfo) => Promise<T>,
 	policy: RetryPolicy = DEFAULT_RETRY_POLICY,
@@ -185,10 +235,12 @@ export async function executeWithRetry<T>(
 			// attempt against the previous one and decides. true ⇒ stop the loop
 			// with the distinct no_progress reason (not ordinary give-up exhaustion).
 			// SOFT: hook errors are logged (logInternalError) and treated as false.
+			// F4: the hook races NO_PROGRESS_HOOK_TIMEOUT_MS — slow/never-settling
+			// hooks count as false (see settleNoProgressHook).
 			if (hooks.noProgress) {
 				let noProgressDecision = false;
 				try {
-					noProgressDecision = await hooks.noProgress({
+					noProgressDecision = await settleNoProgressHook(hooks.noProgress, {
 						attempt,
 						lastResult: lastError,
 						previousResult: previousFailedResult,

package/src/runtime/usage-tracker.ts

@@ -1,28 +1,57 @@
 import type { TeamRunManifest, TeamTaskState, UsageState } from "../state/types.ts";
 
+/**
+ * P1 (U16 follow-up) — 2-tier usage tracking. `LifetimeUsage` now carries all
+ * five ledger fields. The change is ADDITIVE: callers that still pass only
+ * input/output/cacheWrite deltas behave exactly as before.
+ */
 export interface LifetimeUsage {
 	input: number;
 	output: number;
 	cacheWrite: number;
+	/** P1: cumulative cache-read tokens (dropped from the ledger pre-P1). */
+	cacheRead: number;
+	/** P1: D2 aggregate cost — always a NUMBER, never the message-level cost object. */
+	cost: number;
 }
 
 export function emptyLifetimeUsage(): LifetimeUsage {
-	return { input: 0, output: 0, cacheWrite: 0 };
+	return { input: 0, output: 0, cacheWrite: 0, cacheRead: 0, cost: 0 };
 }
 
-export function addUsage(into: LifetimeUsage, delta: { input?: number; output?: number; cacheWrite?: number }): void {
+/**
+ * Usage delta for `addUsage`/`trackTaskUsage` — every field optional, absent
+ * fields are skipped. `cost` MUST be a NUMBER (the D2 aggregate tier):
+ * message-level cost OBJECTS (`{input, output, cacheRead, cacheWrite, total}`)
+ * are NOT handled here — callers must first pass them through the shared
+ * parser (`usageFromValue` in session-usage.ts), which extracts `cost.total`.
+ */
+export interface UsageDelta {
+	input?: number;
+	output?: number;
+	cacheWrite?: number;
+	cacheRead?: number;
+	cost?: number;
+}
+
+export function addUsage(into: LifetimeUsage, delta: UsageDelta): void {
 	if (typeof delta.input === "number") into.input += delta.input;
 	if (typeof delta.output === "number") into.output += delta.output;
 	if (typeof delta.cacheWrite === "number") into.cacheWrite += delta.cacheWrite;
+	if (typeof delta.cacheRead === "number") into.cacheRead += delta.cacheRead;
+	if (typeof delta.cost === "number") into.cost += delta.cost;
 }
 
-/** @internal */
-function lifetimeUsageFromState(state: UsageState | undefined): LifetimeUsage {
+/** @internal — exported for unit tests. */
+export function lifetimeUsageFromState(state: UsageState | undefined): LifetimeUsage {
 	if (!state) return emptyLifetimeUsage();
 	return {
 		input: state.input ?? 0,
 		output: state.output ?? 0,
 		cacheWrite: state.cacheWrite ?? 0,
+		// P1: legacy persisted states have no cacheRead/cost — both read as 0.
+		cacheRead: state.cacheRead ?? 0,
+		cost: state.cost ?? 0,
 	};
 }
 
@@ -31,13 +60,17 @@ export function usageStateFromLifetime(lifetime: LifetimeUsage): UsageState {
 		input: lifetime.input,
 		output: lifetime.output,
 		cacheWrite: lifetime.cacheWrite,
-		cacheRead: 0,
+		// P1: REAL values — the hard-coded `cacheRead: 0` (and the missing
+		// `cost` key) are gone. `cost` stays always-present-as-number, matching
+		// the stable-ledger convention (session-usage.ts compactUsage Fix D).
+		cacheRead: lifetime.cacheRead,
+		cost: lifetime.cost,
 	};
 }
 
 const taskUsageMap = new Map<string, LifetimeUsage>();
 
-export function trackTaskUsage(taskId: string, delta: { input?: number; output?: number; cacheWrite?: number }): void {
+export function trackTaskUsage(taskId: string, delta: UsageDelta): void {
 	const existing = taskUsageMap.get(taskId) ?? emptyLifetimeUsage();
 	addUsage(existing, delta);
 	taskUsageMap.set(taskId, existing);
@@ -60,8 +93,8 @@ export const getTaskUsage = getTrackedTaskUsage;
 export const getRunUsage = getTrackedTaskUsage;
 export const clearAllTaskUsage = clearAllTrackedTaskUsage;
 
-/** @internal */
-function aggregateTrackedUsageForRun(manifest: TeamRunManifest, tasks: TeamTaskState[]): UsageState {
+/** @internal — exported for unit tests. */
+export function aggregateTrackedUsageForRun(manifest: TeamRunManifest, tasks: TeamTaskState[]): UsageState {
 	const total = emptyLifetimeUsage();
 	for (const task of tasks) {
 		const tracked = getTrackedTaskUsage(task.id);