pi-crew 0.11.18 → 0.11.19

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-crew",
-	"version": "0.11.18",
+	"version": "0.11.19",
 	"description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
 	"author": "baphuongna",
 	"license": "MIT",
@@ -136,7 +136,7 @@
 		"@earendil-works/pi-agent-core": "*",
 		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "*",
+		"@earendil-works/pi-tui": ">=1.0.4 <2.0.0",
 		"@sinclair/typebox": "*"
 	},
 	"dependencies": {
@@ -153,7 +153,7 @@
 		"@earendil-works/pi-agent-core": "^1.0.4",
 		"@earendil-works/pi-ai": "^1.0.4",
 		"@earendil-works/pi-coding-agent": "^1.0.4",
-		"@earendil-works/pi-tui": "^1.0.4",
+		"@earendil-works/pi-tui": "1.0.4",
 		"@sinclair/typebox": "^0.34.52",
 		"@types/node": "^25.9.8",
 		"tsx": "^4.23.15",

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

@@ -133,7 +133,8 @@ End-to-end verification discipline for pi-crew changes. Distilled from the broke
 | `scripts/wc-gate.mjs` | T11b |
 | `scripts/test-runner.mjs` (the runner itself) | T1 (exercises it) + `test/unit/scripts/test-runner-exit.test.ts` (21 tests: exit codes, cancelled-guard red-green, missing-file pre-check, batch shard empirical) + ONE batch-mode run (`PI_CREW_TEST_BATCH_SIZE=2 node scripts/test-runner.mjs --shard=0/1 <3 small files>`). **Home isolation per-suite từ 2026-10-11** (set CẢ `PI_CREW_HOME` + `PI_TEAMS_HOME` — mirror pair, đặt 1 tên là defeatable; sweep prefix `pi-crew-` cover orphan `pi-crew-test-home-*`; opt-out `PI_CREW_TEST_NO_HOME_ISOLATION=1`) → khi đụng isolation: leak detector = đếm run-dirs `~/.pi/agent/extensions/pi-crew/state/runs/` before/after một suite, KHÔNG được tăng. Dev script — NOT bundled, no T3/T4 needed |
 | `scripts/check-lazy-imports.mjs` | Run the gate on a clean tree (`node scripts/check-lazy-imports.mjs` exit 0) + re-probe the pattern battery vs the KNOWN GAPS comment (round-3 lesson: a skip-rule fix can OPEN a new false-skip hole — probe both directions; fixture suite `test/unit/scripts/check-lazy-imports-gate.test.ts` 4 tests probe cả 2 hướng). **AST-based từ Δ2 (2026-10-11, esbuild strip + acorn)**: per-entry budget `{maxFiles}` là RATCHET — bump chỉ khi chủ ý + justify trong commit; hosted-git-info allowlist ĐÃ xóa (2026-10-12, dead require dropped — gate strict trở lại). NOT bundled |
-| `src/runtime/verification/verify-gate.ts` + task-runner gate mount (U13) | T7 smoke ×2 — (a) goal whose checks PASS → run must reach `completed` (NOT `blocked`) + `task.verifier_pre_gate` event with `skipVerifier:true` + verifier result artifact carries gate summary; (b) goal whose checks FAIL (e.g. `false` command) → LLM verifier spawns WITH gate context. **Guards the U13×effectiveness interplay** (live-caught 2026-10-10: green-gated verifier = no usage/transcript by design → effectiveness guard false-blocked the run → sync calls hung forever; fixed by counting `diagnostics.verifyGate` as observable work — `effectiveness-guard.test.ts` pins it) |
+| `src/runtime/verification/verify-gate.ts` + task-runner gate mount (U13) | T7 smoke ×2 — (a) goal whose checks PASS → run must reach `completed` (NOT `blocked`) + `task.verifier_pre_gate` event with `skipVerifier:true` + verifier result artifact carries gate summary; (b) goal whose checks FAIL (e.g. `false` command) → LLM verifier spawns WITH gate context. **Guards the U13×effectiveness interplay** (live-caught 2026-10-10: green-gated verifier = no usage/transcript by design → effectiveness guard false-blocked the run → sync calls hung forever; fixed by counting `diagnostics.verifyGate` as observable work — `effectiveness-guard.test.ts` pins it). U13-ADJ (2026-10-13): layer-3 determinism `PI_CREW_VERIFY_DETERMINISM` DEFAULT OFF — battery recipe KHÔNG đổi trừ khi flag bật; khi bật: rerun critical-check cuối cùng PASS, flaky/executor-death → INCONCLUSIVE (không FAILED), không rerun khi checks đã FAILED; belt never-fail-task giờ wrap cả writeArtifact skip-path + finalizer NGỒI NGOÀI try (throw lan truyền, không fall-through spawn) |
+| `src/state/coordination/**` (run-lock socket U21, 2026-10-13) | T7 + pinned `test/unit/state/coordination/{process-lock,run-lock-socket}.test.ts` (U21-1..6) — escape hatch `PI_CREW_RUN_LOCK_SOCKET=0` (pre-U21 bit-for-bit). Semantics MỚI khi socket ON (default): stale-steal một LIVE holder giờ WAIT trong deadline `staleMs*2` thay vì dual-entry (test cũ `run-lock-steal-live-holder-warn.test.ts` giờ env-scoped socket=0). **Test-rule cho mọi lock-freeze tương lai**: PHẢI await acquired-signal deterministic từ body (pattern `team-tool-resume-liveness` F1 sau 2026-10-13) — socket-listen là MACROTASK, assumption "acquisition thắng race với await kế tiếp" đã sai 1 lần (RR-011 token từng vô hình với contender same-process trong cửa sổ file→socket) |
 | `PI_CREW_STATE_BACKEND=sqlite` (U8 state backend) | Unit: `sqlite-run-state.test.ts` + `state-store-sqlite-parity.test.ts` (incl. coalesced-mirror pin). LIVE: one fast-fix run with the env set → assert `state.sqlite` exists, **sqlite tasks reach terminal status** (live-caught 2026-10-10: `saveRunTasksCoalesced` hot path skipped the db — manifest+tasks.json completed while sqlite stuck at createRun `queued`), events.jsonl still written (audit spine), JSON mirrors present |
 | `PI_CREW_CHILD_PI_MODE=rpc` / `PI_CREW_CHILD_PI_POOL` (U14 transport) | Unit: `child-pi-rpc-mode.test.ts` (18) + `owned-process-u15.test.ts` (11). LIVE: one async run with env set → workers' status.json carry rpc transport markers, run green, `pgrep -f "mode rpc"` clean after completion (no orphan rpc processes), json default unaffected |
 | `src/runtime/live-session/**` shared-services rework (U4) | Unit: `live-session-u4` suite (10 — init<50ms via `session_created.elapsedMs`, recursion assert, D4 planning-window replay, hung-tool drop). LIVE: T8 md5 + one fast-fix run (live-session path opt-in) — session_created.elapsedMs < 50ms in events |
@@ -178,6 +179,8 @@ End-to-end verification discipline for pi-crew changes. Distilled from the broke
 > **Steering channel filename is RUN-KIND-DEPENDENT — the #1 way to fake a failure** (cost this session a full false-negative investigation): **team workflow runs** poll `<artifactsRoot>/steering/<taskId>.jsonl` (`child-executor.ts:562` → env `PI_CREW_STEERING_FILE` → `prompt-runtime.ts:855`), e.g. `01_assess.jsonl`, `adaptive-01-executor.jsonl`; **crew_agent / direct subagent runs** use the agent-slot name `<slot>-agent.jsonl` (e.g. `01_01-agent.jsonl`). A watcher writing `01_01-agent.jsonl` into a team run's steering dir writes a file **no component reads** (0-byte `<taskId>.jsonl` sits untouched, the phantom file accumulates bytes) — it looks exactly like the boot-window loss but is a probe bug. Always derive the name from the run kind, or write every `*.jsonl` present in the dir (see Tier 9g).
 >
 > **2026-10-12 update (test-state leak fix + U11 hybrid worker + Δ-wave, commits `468fe609`..`a56129ec`, 8 commits)**: (1) **Unit-test state leak vào user root (fix 2 tầng)** — fixture chạy từ bare `/tmp` cwd (không repo marker) đẩy run-state vào `~/.pi/agent/extensions/pi-crew/` qua no-repo fallback của `scopeBaseRoot()`; async-notifier mỗi live session toast các fixture failure thành `Error: pi-crew run failed: team_… (inline-seam-fixture/none)` (104 run-dir rò từ tháng 6, dọn 2026-10-11). Tầng 1: runner isolation per-suite (`PI_CREW_HOME` + `PI_TEAMS_HOME` — CẢ HAI, mirror pair 1-tên defeatable); tầng 2: run-index temp-cwd guard (non-temp root × TERMINAL × bare-temp cwd không marker ⇒ ẩn khỏi listing; by-ID vẫn resolve). Probe rule: leak detector đếm run-dirs user-root before/after suite. (2) **U11 hybrid 2-tier worker (DEFAULT-OFF)** — embedded tier trên U4 stack, shared slot budget 2 tier, fallback 2-faults, events `tier.decision/fault/fallback`; LIVE acceptance `team_20261011150612`: embedded `session_created.elapsedMs` **9ms** vs subprocess spawn **317ms** (~35-60×); row decision-table mới ở trên kèm STALE-BUNDLE SIGNATURE. (3) **Δ-wave benches + gates**: `check-lazy-imports` AST hóa (budget ratchet 523, fixture 4 tests); **b14** run-index scan (readdir vô hại 1.4µs/dir — per-entry work 0.3ms/dir mới là chi phí; notifier recent-40 an toàn mọi scale; F4: scan-cache bucket TTL non-sliding + `set()` reset bucket rỗng — scan >1s tự roll bucket giữa chừng, cần decision record nếu bucket nào phục vụ scan >1s); **b15** broker scan-cost (Δ3 verdict NO-GO có bằng chứng: N≤11 tasks/run thực tế, scan 0.006-0.05ms/call vs I/O floor 8.1ms — candidate indexes parked tới khi run thật >50 tasks); `hosted-git-info` dead-require dropped (KHÔNG resolve ở đâu cả — nested `node_modules/@peer/...` không nằm resolution path của pi-crew; generic parser là de-facto path 100% thời gian). (4) **U12 track** — 7 blacklist items mới từ upstream `cdaf6c227`, triggers 1/4 → vẫn track-only (`docs/reviews/pi-upstream-tracking-u12.md`). Suite anchors @ 2026-10-12 (`a56129ec`): unit **9063 tests / 9060 pass / 0 fail / 3 skipped / 0 cancelled**, integration **144 / 140 pass / 0 fail / 4 skipped** (EXIT=0, env scrub), `test:critical` **120**, bundle **1,758,732 B (1717.5 KB)** md5 `472cb93254c69f7302b99e47269e02ea`, event registry **182 registered / 147 emitted** (`tier.*` registered; DRIFT 3 = mailbox cũ đã biết, owner broker lane).
+>
+> **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).
 
 ## Core principle: disk ≠ live Pi
 

package/src/config/env-allowlist-registry.ts

@@ -257,6 +257,14 @@ const CREW_ENV_FORWARDING_DECL: Record<string, CrewEnvForwardDecision> = {
 	PI_CREW_CLASSIFIER_MODEL: { kind: "gap", reason: "child-executor retry classifier (runner)" },
 	PI_CREW_VERIFY_GATE: { kind: "gap", reason: "verify-gate pre-gate before verifier spawns (runner)" },
 	PI_CREW_VERIFY_GATE_TIMEOUT_MS: { kind: "gap", reason: "verify-gate per-check timeout (runner)" },
+	PI_CREW_VERIFY_DETERMINISM: {
+		kind: "gap",
+		reason: "U13-ADJ layer-3 determinism rerun toggle — resolved in the runner before the verifier spawns; deliberately unforwarded (each process decides its own gate determinism tier, exactly like PI_CREW_VERIFY_GATE above)",
+	},
+	PI_CREW_RUN_LOCK_SOCKET: {
+		kind: "gap",
+		reason: "U21 run-lock dual-guard toggle — withRunLock also runs in the runner; deliberately unforwarded this wave (socket dies with each process, so a host-vs-runner toggle mismatch is harmless: each process just picks its own admission tier)",
+	},
 	PI_CREW_RPC_DIALOG_ANSWER: { kind: "gap", reason: "rpc-worker dialog policy (runner)" },
 	PI_CREW_RPC_TURN_TIMEOUT_MS: { kind: "gap", reason: "rpc-worker turn timeout (runner)" },
 	PI_CREW_MAX_AUTO_FALLBACKS: { kind: "gap", reason: "model-fallback cap resolved in the runner" },

package/src/config/env-vars.ts

@@ -472,6 +472,12 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_CREW_STATE_BACKEND",
 		doc: "U8 (upgrade-spec 2026-10-09) run-state store backend select: 'sqlite' stores manifest+tasks+worker-status in <runId>/state.sqlite via node:sqlite with ONE transaction per batch write (all-or-nothing; manifest.json/tasks.json stay written as read-side mirrors for legacy consumers — loads read the db); unset or any other value keeps the default JSON file backend. events.jsonl audit spine unchanged in both modes (state-store.ts / sqlite-run-state.ts isSqliteStateBackend)",
 	},
+	PI_CREW_RUN_LOCK_SOCKET: {
+		name: "PI_CREW_RUN_LOCK_SOCKET",
+		parser: "boolean",
+		default: true,
+		doc: "U21 (upgrade 2026-10-13) run-lock dual-guard toggle: '0'/'false'/'no' disables the kernel process-socket SUPPLEMENT on the ASYNC withRunLock path (pre-U21 file-lock-only behaviour, bit-for-bit); default ON. Host-process read only — never passed to children (the socket name is derived from the run dir path). The SYNC withRunLockSync path is always file-only by design (locks.ts acquireRunLockGuarded)",
+	},
 	PI_CREW_CHILD_PI_MODE: {
 		name: "PI_CREW_CHILD_PI_MODE",
 		doc: "U14 (upgrade-spec 2026-10-09) child-pi protocol v2 transport select: 'rpc' spawns task workers over pi --mode rpc (SDK RpcClient wire — steer receipts, clear_queue hygiene, multi-prompt reuse; child-pi-rpc.ts), 'json' / unset keeps the --mode json -p stdio path (phase-1 default; both modes fully regression-tested). Surface TUI panes are unaffected",
@@ -505,6 +511,11 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		default: "120000",
 		doc: "U13 per-check timeout in ms for the deterministic verify_gate pre-gate commands. Invalid/≤0 → 120000, mirroring runPhaseGates (runtime/verification/verify-gate.ts resolveVerifyGateTimeoutMs)",
 	},
+	PI_CREW_VERIFY_DETERMINISM: {
+		name: "PI_CREW_VERIFY_DETERMINISM",
+		parser: "boolean",
+		doc: "U13-ADJ (upgrade 2026-10-13, PHASE 4) layer-3 determinism rerun, DEFAULT OFF: '1' reruns the most critical default check (usually test:critical) once after a GREEN gate; disagreement (flaky) or a rerun executor failure downgrades the verdict to INCONCLUSIVE (never FAILED, never a task failure) with a 'deterministic-check: flaky <name>' note. Flag off keeps the gate bit-for-bit pre-U13-ADJ (runtime/verification/verify-gate.ts resolveVerifyDeterminismEnabled)",
+	},
 	PI_CREW_RPC_DIALOG_ANSWER: {
 		name: "PI_CREW_RPC_DIALOG_ANSWER",
 		doc: "W7 EXPERIMENTAL dialog auto-answer policy for RPC-mode extension_ui_request dialogs (select/confirm/input/editor): 'cancel' (default) answers {cancelled:true} — universal safe answer; 'block' leaves the server promise pending (debug). Auto-confirm deliberately NOT implemented (security); invalid → 'cancel' (rpc-worker.ts resolveDialogAnswerPolicy)",

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

@@ -131,6 +131,42 @@ export async function runMockChildPi(
 			stderr: "[MOCK] rate limit: mock failure",
 		};
 
+	// U16 (usage ledger): same happy-path shape as json-success, but the
+	// message_end events carry the REAL message-level usage shape — usage
+	// nested under message.role="assistant" with cost as an OBJECT
+	// ({input, output, cacheRead, cacheWrite, total} per @earendil-works/pi-ai
+	// Usage) — so the lifetimeUsage accumulator and the subprocess usage
+	// parsers see exactly what a real child pi emits. Two events so the
+	// accumulation (sum) across messages is asserted, not a single snapshot.
+	if (mock === "json-usage-ledger") {
+		const text = `[MOCK] JSON usage ledger for ${input.agent.name}`;
+		const usageEvent = (tokens: { input: number; output: number; cacheRead: number; cacheWrite: number }, cost: number) =>
+			JSON.stringify({
+				type: "message_end",
+				message: {
+					role: "assistant",
+					usage: {
+						...tokens,
+						totalTokens: tokens.input + tokens.output + tokens.cacheRead + tokens.cacheWrite,
+						cost: {
+							input: 0.01,
+							output: 0.01,
+							cacheRead: 0.005,
+							cacheWrite: 0.005,
+							total: cost,
+						},
+					},
+				},
+			});
+		const stdout = [
+			JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } }),
+			usageEvent({ input: 10, output: 5, cacheRead: 40, cacheWrite: 3 }, 0.035),
+			usageEvent({ input: 7, output: 2, cacheRead: 20, cacheWrite: 1 }, 0.0203),
+		].join("\n");
+		await observe(input, `${stdout}\n`);
+		return { exitCode: 0, stdout, stderr: "" };
+	}
+
 	// RR-013 (F04) test seam: reproduce the MuxSurface A1 degrade result WITHOUT a
 	// real multiplexer. child-executor's `childResult.surface?.degraded` branch is
 	// the ONLY producer of TaskExecutionResult.surfaceLost, and runTeamTask offers

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

@@ -43,6 +43,7 @@ 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,
@@ -234,8 +235,13 @@ type LiveSessionLike = {
 	steer?: (text: string) => Promise<void>;
 	abort?: () => Promise<void> | void;
 	dispose?: () => void;
-	getStats?: () => unknown;
-	stats?: unknown;
+	/** 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 };
+	};
 	bindExtensions?: (bindings?: Record<string, unknown>) => Promise<void>;
 	getActiveToolNames?: () => string[];
 	setActiveToolsByName?: (names: string[]) => void;
@@ -525,15 +531,6 @@ function finalAssistantText(event: unknown): string[] {
 	return textFromContent(message.content);
 }
 
-function numberField(obj: Record<string, unknown> | undefined, keys: string[]): number | undefined {
-	if (!obj) return undefined;
-	for (const key of keys) {
-		const value = obj[key];
-		if (typeof value === "number" && Number.isFinite(value)) return value;
-	}
-	return undefined;
-}
-
 /**
  * F7: resolve the enabledModels allowlist for the current project, but only
  * if the `reliability.scopeModels` toggle is ON. Returns an empty
@@ -794,18 +791,12 @@ function filterActiveTools(session: LiveSessionLike, agent: AgentConfig, role?:
 	session.setActiveToolsByName(active);
 }
 
-function usageFromStats(stats: unknown): UsageState | undefined {
-	const obj = asRecord(stats);
-	if (!obj) return undefined;
-	const input = numberField(obj, ["input", "inputTokens", "input_tokens"]);
-	const output = numberField(obj, ["output", "outputTokens", "output_tokens"]);
-	const cacheRead = numberField(obj, ["cacheRead", "cache_read"]);
-	const cacheWrite = numberField(obj, ["cacheWrite", "cache_write"]);
-	const cost = numberField(obj, ["cost"]);
-	const turns = numberField(obj, ["turns", "turnCount", "turn_count"]);
-	return [input, output, cacheRead, cacheWrite, cost, turns].some((value) => value !== undefined)
-		? { input, output, cacheRead, cacheWrite, cost, turns }
-		: 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. Exported for unit tests. */
+export function usageFromStats(stats: unknown): UsageState | undefined {
+	return usageFromValue(stats);
 }
 
 /**
@@ -1798,7 +1789,9 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 						emit: emitEmbedded,
 					})
 				: undefined;
-		const usage = usageFromStats(typeof session.getStats === "function" ? session.getStats() : session.stats);
+		// 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?.());
 		updateLiveAgentStatus(agentId, "completed");
 		markLiveAgentCompleted(agentId);
 		return {

package/src/runtime/output/pi-json-output.ts

@@ -1,3 +1,5 @@
+import { usageFromValue } from "../session-usage.ts";
+
 export interface ParsedPiUsage {
 	input?: number;
 	output?: number;
@@ -24,14 +26,6 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
 	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
 }
 
-function numberField(obj: Record<string, unknown>, keys: string[]): number | undefined {
-	for (const key of keys) {
-		const value = obj[key];
-		if (typeof value === "number" && Number.isFinite(value)) return value;
-	}
-	return undefined;
-}
-
 function mergeUsage(target: ParsedPiUsage, source: ParsedPiUsage): ParsedPiUsage {
 	return {
 		input: source.input ?? target.input,
@@ -43,24 +37,17 @@ function mergeUsage(target: ParsedPiUsage, source: ParsedPiUsage): ParsedPiUsage
 	};
 }
 
+/**
+ * U16: usage extraction is delegated to the single shared parser
+ * (`usageFromValue` in session-usage.ts) so the subprocess tier accepts BOTH
+ * cost shapes — the session-level aggregate NUMBER and the message-level
+ * OBJECT with `total` (@earendil-works/pi-ai `Usage.cost`) — instead of
+ * silently dropping the object form. Same field aliases as before
+ * (inputTokens/input_tokens/cost_usd/…) and same nested fallbacks
+ * (usage/message/tokenUsage/tokens/stats).
+ */
 function extractUsage(value: unknown): ParsedPiUsage | undefined {
-	const obj = asRecord(value);
-	if (!obj) return undefined;
-	const direct: ParsedPiUsage = {
-		input: numberField(obj, ["input", "inputTokens", "input_tokens"]),
-		output: numberField(obj, ["output", "outputTokens", "output_tokens"]),
-		cacheRead: numberField(obj, ["cacheRead", "cache_read", "cacheReadTokens", "cache_read_tokens"]),
-		cacheWrite: numberField(obj, ["cacheWrite", "cache_write", "cacheWriteTokens", "cache_write_tokens"]),
-		cost: numberField(obj, ["cost", "costUsd", "cost_usd"]),
-		turns: numberField(obj, ["turns", "turnCount", "turn_count"]),
-	};
-	if (Object.values(direct).some((entry) => entry !== undefined)) return direct;
-	// Pi --mode json nests usage under message for message_end / turn_end events.
-	for (const key of ["usage", "message", "tokenUsage", "tokens", "stats"]) {
-		const nested = extractUsage(obj[key]);
-		if (nested) return nested;
-	}
-	return undefined;
+	return usageFromValue(value);
 }
 
 function textFromContent(content: unknown): string[] {

package/src/runtime/recovery/crash-recovery.ts

@@ -959,6 +959,10 @@ export async function reconcileAllStaleRuns(
 	// so locks whose holder died (kill -9 / crash) do not linger. The sweep is
 	// strictly safer than acquire-time steal (stale AND holder-dead only), so a
 	// live holder is never disturbed. Best-effort.
+	// U21 (2026-10-13): socket holders need no sweep — the kernel process socket
+	// of an async run-lock holder dies with its process. This sweep covers the
+	// SYNC path (withRunLockSync, file-only by design) + legacy file-only holders;
+	// remove after the file-lock migration window closes.
 	try {
 		const runsRoots = [
 			path.join(projectCrewRoot(cwd), DEFAULT_PATHS.state.runsSubdir),

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

@@ -24,6 +24,33 @@ export interface RetryAttemptInfo {
 	attemptId: string;
 }
 
+/**
+ * U9-ADJ (upgrade 2026-10-13 §U9): terminal sentinel thrown when the retry
+ * loop stops because the `noProgress` hook detected a stuck loop. Distinct
+ * from ordinary give-up (exhaustion throws the ORIGINAL error untouched):
+ * this carries `reason: "no_progress"` plus the attempt info, with the
+ * original error preserved as `cause`. Callers distinguish the two exits via
+ * `error instanceof RetryNoProgressError` or `reason === "no_progress"`.
+ */
+export class RetryNoProgressError extends Error {
+	readonly reason: "no_progress";
+	readonly attempt: number;
+	readonly attemptId: string;
+	readonly durationMsLast: number;
+
+	constructor(details: { attempt: number; attemptId: string; durationMsLast: number; error: Error }) {
+		super(
+			`Retry loop stopped after attempt ${details.attempt} (${details.attemptId}): no progress between attempts (last attempt took ${details.durationMsLast}ms). Original error: ${details.error.message}`,
+			{ cause: details.error },
+		);
+		this.name = "RetryNoProgressError";
+		this.reason = "no_progress";
+		this.attempt = details.attempt;
+		this.attemptId = details.attemptId;
+		this.durationMsLast = details.durationMsLast;
+	}
+}
+
 export interface RetryHooks {
 	onAttemptFailed?: (attempt: number, error: Error, nextDelayMs: number, info: RetryAttemptInfo) => void;
 	onRetryGivenUp?: (attempts: number, error: Error, info: RetryAttemptInfo) => void;
@@ -40,6 +67,29 @@ export interface RetryHooks {
 	 * (classifyAmbientNoiseGate), dormant unless runtime.classifierEnabled.
 	 */
 	shouldRetry?: (attempt: number, error: Error, info: RetryAttemptInfo) => boolean | Promise<boolean>;
+	/**
+	 * U9-ADJ (upgrade 2026-10-13 §U9): no-progress gate consulted after a
+	 * failed attempt ONCE `shouldRetry` (if present) has approved queueing the
+	 * next one, and BEFORE onAttemptFailed + backoff sleep. The CALLER owns the
+	 * "no progress" semantics (e.g. compare checkpoint depth / error identity
+	 * between attempts) — the executor stays generic and task-agnostic.
+	 * `lastResult` / `previousResult` are the `Error`s thrown by the just-failed
+	 * attempt and the one before it (`previousResult` is `undefined` on the
+	 * first failure — nothing to compare yet); `durationMsLast` is the wall
+	 * time of the just-failed attempt in ms. Returning true stops the loop with
+	 * `RetryNoProgressError` (`reason: "no_progress"`) instead of spawning the
+	 * next attempt — `onRetryGivenUp` still fires first (same terminal contract
+	 * as the cancellation exit). SOFT: a throwing/rejecting hook is logged via
+	 * 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.
+	 */
+	noProgress?: (context: {
+		attempt: number;
+		lastResult: unknown;
+		previousResult: unknown;
+		durationMsLast: number;
+	}) => boolean | Promise<boolean>;
 }
 
 export const DEFAULT_RETRY_POLICY: RetryPolicy = {
@@ -91,13 +141,18 @@ export async function executeWithRetry<T>(
 		maxAttempts: Math.max(1, policy.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts),
 	};
 	let lastError: Error | undefined;
+	// U9-ADJ: result (thrown Error) of the PREVIOUS failed attempt, fed to the
+	// noProgress hook as `previousResult`. `undefined` until a first failure.
+	let previousFailedResult: unknown;
 	for (let attempt = 1; attempt <= normalized.maxAttempts; attempt += 1) {
 		throwIfCancelled(hooks.signal);
 		const info = retryAttemptInfo(attempt, hooks);
+		const attemptStartedAtMs = Date.now();
 		try {
 			return await fn(attempt, info);
 		} catch (error) {
 			lastError = asError(error);
+			const durationMsLast = Date.now() - attemptStartedAtMs;
 			// Never retry if aborted — sleep() would immediately reject on every attempt.
 			if (hooks.signal?.aborted) {
 				hooks.onRetryGivenUp?.(attempt, lastError, info);
@@ -124,6 +179,41 @@ export async function executeWithRetry<T>(
 					throw lastError;
 				}
 			}
+			// U9-ADJ: no-progress gate — consulted once per failed attempt, after
+			// retryability + shouldRetry, BEFORE the backoff sleep + next spawn.
+			// Only the caller knows task semantics, so it compares the just-failed
+			// 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.
+			if (hooks.noProgress) {
+				let noProgressDecision = false;
+				try {
+					noProgressDecision = await hooks.noProgress({
+						attempt,
+						lastResult: lastError,
+						previousResult: previousFailedResult,
+						durationMsLast,
+					});
+				} catch (noProgressError) {
+					logInternalError(
+						"retry-executor.noProgress",
+						noProgressError,
+						"soft-fail: treating as progress, retry stays queued",
+						"error",
+					);
+					noProgressDecision = false;
+				}
+				if (noProgressDecision === true) {
+					hooks.onRetryGivenUp?.(attempt, lastError, info);
+					throw new RetryNoProgressError({
+						attempt,
+						attemptId: info.attemptId,
+						durationMsLast,
+						error: lastError,
+					});
+				}
+			}
+			previousFailedResult = lastError;
 			const delay = calculateRetryDelay(attempt, normalized);
 			hooks.onAttemptFailed?.(attempt, lastError, delay, info);
 			try {

package/src/runtime/session-usage.ts

@@ -13,7 +13,45 @@ function numberField(obj: Record<string, unknown>, keys: string[]): number | und
 	return undefined;
 }
 
-function usageFromValue(value: unknown): UsageState | undefined {
+/**
+ * U16 (D2 — two-tier cost): cost arrives EITHER as a session-level aggregate
+ * NUMBER (SDK `SessionStats.cost`) OR as a message-level OBJECT with a `total`
+ * field (`@earendil-works/pi-ai` `Usage.cost = {input, output, cacheRead,
+ * cacheWrite, total}`). Accept both; an object without a finite `total` yields
+ * undefined — never NaN.
+ */
+function costField(obj: Record<string, unknown>): number | undefined {
+	for (const key of ["cost", "costUsd", "cost_usd"]) {
+		const raw = obj[key];
+		if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+		const record = asRecord(raw);
+		const total = record ? record.total : undefined;
+		if (typeof total === "number" && Number.isFinite(total)) return total;
+	}
+	return undefined;
+}
+
+function mergeUsageFields(primary: UsageState, fallback: UsageState): UsageState {
+	return {
+		input: primary.input ?? fallback.input,
+		output: primary.output ?? fallback.output,
+		cacheRead: primary.cacheRead ?? fallback.cacheRead,
+		cacheWrite: primary.cacheWrite ?? fallback.cacheWrite,
+		cost: primary.cost ?? fallback.cost,
+		turns: primary.turns ?? fallback.turns,
+	};
+}
+
+/**
+ * U16: the single usage-shape parser (session-level `SessionStats` AND
+ * message-level `Usage`). Flat/direct fields win; nested payloads
+ * (`usage`/`message`/`tokenUsage`/`tokens`/`stats`) fill only the MISSING
+ * fields, so the SDK session shape `{tokens: {…}, cost}` maps completely while
+ * flat legacy shapes parse unchanged. `message` restores the legacy
+ * pi-json-output.ts nested key (git d29df7dd — Pi --mode json nests usage
+ * under `message` for message_end/turn_end events) for back-compat.
+ */
+export function usageFromValue(value: unknown): UsageState | undefined {
 	const obj = asRecord(value);
 	if (!obj) return undefined;
 	const direct: UsageState = {
@@ -21,14 +59,15 @@ function usageFromValue(value: unknown): UsageState | undefined {
 		output: numberField(obj, ["output", "outputTokens", "output_tokens"]),
 		cacheRead: numberField(obj, ["cacheRead", "cache_read", "cacheReadTokens", "cache_read_tokens"]),
 		cacheWrite: numberField(obj, ["cacheWrite", "cache_write", "cacheWriteTokens", "cache_write_tokens"]),
-		cost: numberField(obj, ["cost", "costUsd", "cost_usd"]),
+		cost: costField(obj),
 		turns: numberField(obj, ["turns", "turnCount", "turn_count"]),
 	};
-	if (Object.values(direct).some((entry) => entry !== undefined)) return direct;
-	for (const key of ["usage", "tokenUsage", "tokens", "stats"]) {
+	let merged: UsageState | undefined = Object.values(direct).some((entry) => entry !== undefined) ? direct : undefined;
+	for (const key of ["usage", "message", "tokenUsage", "tokens", "stats"]) {
 		const nested = usageFromValue(obj[key]);
-		if (nested) return nested;
+		if (nested) merged = merged ? mergeUsageFields(merged, nested) : nested;
 	}
+	if (merged) return merged;
 	const message = asRecord(obj.message);
 	return message ? usageFromValue(message.usage) : undefined;
 }
@@ -48,6 +87,10 @@ function compactUsage(total: UsageState, foundKeys: Set<keyof UsageState>): Usag
 	if (foundKeys.size === 0) return undefined;
 	const compact: UsageState = {};
 	for (const key of foundKeys) compact[key] = total[key];
+	// U16 (Fix D): stable ledger schema — once ANY usage was seen, `cost` is
+	// always present (0 when no source ever reported it) so downstream
+	// consumers can rely on `usage.cost` being a number.
+	compact.cost = compact.cost ?? 0;
 	return compact;
 }
 

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

@@ -70,7 +70,7 @@ import { buildSyntheticTerminalEvidence, cancellationReasonFromSignal } from "..
 import { checkProcessLiveness } from "../process-status.ts";
 import { DEFAULT_RETRY_POLICY } from "../recovery/retry-executor.ts";
 import { runWorker } from "../run-worker.ts";
-import { parseSessionUsage } from "../session-usage.ts";
+import { parseSessionUsage, usageFromValue } from "../session-usage.ts";
 import { recordSupervisorContact, supervisorContactFromEvent } from "../supervisor-contact.ts";
 import type { ResultSource, TaskExecutionResult } from "./post-execution.ts";
 import type { StreamBridgeHandle, TaskExecutionContext } from "./pre-execution.ts";
@@ -937,7 +937,10 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 						if (event && typeof event === "object" && (event as Record<string, unknown>).type === "message_end") {
 							const msg = (event as Record<string, unknown>).message as Record<string, unknown> | undefined;
 							if (msg?.role === "assistant") {
-								const usage = msg.usage as Record<string, number> | undefined;
+								// U16 (Fix D): parse via the shared parser so message-level usage
+								// (cost is an OBJECT {…, total} per @earendil-works/pi-ai Usage)
+								// contributes cost + cacheRead to the ledger too.
+								const usage = usageFromValue(msg.usage);
 								if (usage) {
 									// RT-8: spread before accumulating lifetimeUsage instead of
 									// mutating in place — preserves the immutable-snapshot invariant.
@@ -946,7 +949,9 @@ export async function runChildProcessTask(ctx: TaskExecutionContext): Promise<Ta
 										lifetimeUsage: {
 											input: (task.lifetimeUsage?.input ?? 0) + (usage.input ?? 0),
 											output: (task.lifetimeUsage?.output ?? 0) + (usage.output ?? 0),
+											cacheRead: (task.lifetimeUsage?.cacheRead ?? 0) + (usage.cacheRead ?? 0),
 											cacheWrite: (task.lifetimeUsage?.cacheWrite ?? 0) + (usage.cacheWrite ?? 0),
+											cost: (task.lifetimeUsage?.cost ?? 0) + (usage.cost ?? 0),
 										},
 									};
 								}

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

@@ -178,7 +178,7 @@ export async function prepareTaskExecutionContext(
 		// it outlives the worker, which would blind the stale-reconciler's
 		// PID-liveness gate forever.
 		agentProgress: input.task.agentProgress ?? emptyCrewAgentProgress(),
-		// Lifetime usage accumulator — survives compaction unlike session.stats
+		// Lifetime usage accumulator — survives compaction unlike session stats snapshots
 		lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
 		...(dependencyContextText ? { dependencyContextText } : {}),
 	} as TeamTaskState;