pi-crew 0.9.65 → 0.9.67

package/src/prompt/scratchpad-lifecycle.ts

@@ -32,6 +32,7 @@ import * as path from "node:path";
 import { type Static, Type } from "@sinclair/typebox";
 import { defineTool, type ExtensionAPI, type ToolDefinition } from "../extension/pi-api.ts";
 import { EngineManager, type ExecuteResult } from "../runtime/scratchpad/engine.ts";
+import { appendEventFireAndForget } from "../state/event-log/event-log.ts";
 // D5/MAJOR-S1: PI_CREW_PARENT_PID + PI_CREW_GUEST build the guest's zombie-
 // backstop env (PI_CREW_KIND_ENV is already exported above).
 import { type ArtifactWriteOptions, writeArtifact } from "../state/stores/artifact-store.ts";
@@ -56,8 +57,43 @@ export const PI_CREW_SCRATCHPAD_RESTORE_ENV = "PI_CREW_SCRATCHPAD_RESTORE";
 // an integrity/authn control (NIT-CA-1).
 export const PI_CREW_SCRATCHPAD_RESTORE_MTIME_ENV = "PI_CREW_SCRATCHPAD_RESTORE_MTIME";
 
+// I5 (plan): scratchpad adoption/value metric. The events path + run id are
+// threaded from the team-runner via child-pi-spawn so the worker (where the
+// execute handler runs) can append fire-and-forget metric events. Absent in
+// non-team contexts (e.g. direct tests) → emission is silently skipped.
+export const PI_CREW_EVENTS_PATH_ENV = "PI_CREW_EVENTS_PATH";
+export const PI_CREW_RUN_ID_ENV = "PI_CREW_BROKER_RUN_ID";
+
 /** Per-cell wall-clock bound (D9/Q2): the ONLY default anti-hang limit. */
 export const EXECUTE_CELL_TIMEOUT_MS = 120_000;
+
+// I5: fire-and-forget metric emission. Events are written ONLY when the worker
+// was spawned by a team-runner that threads PI_CREW_EVENTS_PATH; in any other
+// context (tests, standalone) the path is absent and we no-op. Fire-and-forget
+// is mandatory — the cell hot path must never block on the event log (H1).
+function emitScratchpadMetric(
+	type: "scratchpad.cell" | "scratchpad.restored",
+	env: NodeJS.ProcessEnv,
+	data: Record<string, unknown>,
+	appendEvent: typeof appendEventFireAndForget = appendEventFireAndForget,
+): void {
+	const eventsPath = env[PI_CREW_EVENTS_PATH_ENV];
+	const runId = env[PI_CREW_RUN_ID_ENV];
+	if (!eventsPath || !runId) return;
+	// Fire-and-forget semantics (H1): a throwing writer (sync or async) must
+	// never break the cell. The real appendEventFireAndForget already catches
+	// async; this guard also absorbs a sync throw from a bad writer.
+	try {
+		appendEvent(eventsPath, {
+			type,
+			runId,
+			taskId: env[PI_CREW_TASK_ID_ENV],
+			data,
+		});
+	} catch {
+		// Metric is best-effort — drop the event, never the cell.
+	}
+}
 /** Debounce window for the post-cell snapshot (D5/F8). */
 export const SNAPSHOT_DEBOUNCE_MS = 1500;
 /** SEC-10: cap a single cell so a giant payload cannot OOM the esbuild
@@ -92,11 +128,12 @@ export interface ExecuteDetails {
 export const SCRATCHPAD_DOCTRINE: string[] = [
 	"State compounds: variables persist across scratchpad calls in the task's persistent namespace. Don't re-derive what a previous cell already computed.",
 	"Write small cells and run many: the cell's result is the value of its final (trailing) expression.",
-	"The runtime is Node.js — use child_process for shell commands; there is no Bun.",
+	"The runtime is Node.js — shell commands go through the built-in sh(cmd, args[]) helper (it refuses null/empty arguments, so a missing variable can never leak into the command). Never interpolate variables into raw child_process/exec strings — use sh().",
 	"Writes are surgical; reads are full: read all the data you need, write the minimum.",
 	"Non-serializable variables (functions/classes) are reported in the snapshot's failed list — do not rely on them across calls.",
-	"If you see <rlm_engine_reset> or a snapshot-restore notice, re-verify variables before use.",
-	"Tool calls inside scratchpad are await expressions — await the result before the next cell.",
+	"A message starting [scratchpad] means the namespace was restored or reset — re-verify variables before using them, especially inside shell commands.",
+	// LAZY: the doctrine example string mentions await import('node:fs') as example TEXT — not a real dynamic import.
+	"Prefer scratchpad over bash when a later step reuses an earlier step's data. Example — cell 1: const raw = await import('node:fs').then(m => m.readFileSync('out.json','utf8')); const failures = JSON.parse(raw).tests.filter(t => !t.ok); failures.length — cell 2: failures.slice(0,3).map(t => t.name) // no re-read, no re-parse. For a single one-shot command, bash is cheaper — use it. Keep namespace values small — do not park large parsed objects across cells (they are V8-serialized into every snapshot).",
 ];
 
 // ── singleton engine + debounce timer (per worker process) ─────────────────
@@ -285,6 +322,9 @@ export interface ScratchpadSnapshotDeps {
 	/** Injected for tests; production defaults to the real artifact-store writer.
 	 *  Return type is loose (unknown) — the flush ignores the descriptor. */
 	writeArtifact?: ScratchpadWriteArtifact;
+	/** I5: injected for tests (failing-writer path); production defaults to the
+	 *  real fire-and-forget event appender. Never awaited on the cell path. */
+	appendEvent?: typeof appendEventFireAndForget;
 	env?: NodeJS.ProcessEnv;
 	logInternalError?: typeof logInternalError;
 }
@@ -435,10 +475,10 @@ export function createExecuteTool(engine: EngineManager, deps: Partial<Scratchpa
 		name: "scratchpad",
 		label: "Execute JavaScript",
 		description:
-			"Chạy JavaScript trong namespace bền vững của task. State (biến gán ở cell trước) tồn tại qua các lần gọi. Kết quả cell = giá trị biểu thức cuối.",
+			"Run JavaScript in the task's persistent namespace. State (variables assigned in earlier cells) persists across calls. The cell's result is the value of its final expression.",
 		parameters: ExecuteParams,
 		renderShell: "default",
-		promptSnippet: "scratchpad(code) — chạy JS trong namespace bền vững của task",
+		promptSnippet: "scratchpad(code) — run JS in the task's persistent namespace",
 		promptGuidelines: SCRATCHPAD_DOCTRINE,
 		async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
 			const env = deps.env ?? process.env;
@@ -470,9 +510,30 @@ export function createExecuteTool(engine: EngineManager, deps: Partial<Scratchpa
 					restoreNotice = r
 						? `[scratchpad] restored ${r.restored.length} vars from attempt-${pending.attempt}; restored: [${truncateNameList(r.restored)}]; failed: [${truncateNameList(r.failed.map((f) => f.name))}]`
 						: "[scratchpad] snapshot restore: no state to restore (fail-open)";
+					// I5: metric — restoredCount/failedCount only (names already in the
+					// model-facing notice; never embed paths). Fire-and-forget.
+					emitScratchpadMetric(
+						"scratchpad.restored",
+						env,
+						{
+							status: r ? (r.restored.length > 0 ? "restored" : "empty") : "rejected",
+							attempt: pending.attempt,
+							restoredCount: r?.restored.length ?? 0,
+							failedCount: r?.failed.length ?? 0,
+						},
+						deps.appendEvent,
+					);
 				} catch (error) {
 					logInternalError("scratchpad.restore", error);
 					restoreNotice = "[scratchpad] snapshot restore failed; continuing with empty namespace";
+					// I5: a restore that THREW is still a restore attempt — record it so a
+					// corrupt/unreadable snapshot is visible to the metric, not silent.
+					emitScratchpadMetric(
+						"scratchpad.restored",
+						env,
+						{ status: "failed", attempt: pending.attempt, restoredCount: 0, failedCount: 0 },
+						deps.appendEvent,
+					);
 				}
 			}
 			// 3. Ping-before-execute (S-2/N2-2): skip on idle so the first cell of a
@@ -523,6 +584,20 @@ export function createExecuteTool(engine: EngineManager, deps: Partial<Scratchpa
 			if (result.status === "ok") {
 				scheduleScratchpadSnapshot({ ...deps, engine });
 			}
+			// I5: metric — exactly one scratchpad.cell per cell, fire-and-forget.
+			// resultBytes approximates the rendered output size (best-effort, never
+			// blocks the cell path).
+			emitScratchpadMetric(
+				"scratchpad.cell",
+				env,
+				{
+					status: result.status,
+					durationMs: result.durationMs,
+					codeLength: params.code.length,
+					resultBytes: result.result?.length ?? 0,
+				},
+				deps.appendEvent,
+			);
 			const text = restoreNotice ? `${restoreNotice}\n\n${renderExecuteResult(result)}` : renderExecuteResult(result);
 			return {
 				content: [{ type: "text", text }],

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

@@ -259,6 +259,12 @@ export function prepareSpawnContext(
 	});
 	// Pass steering file path to child for real-time steer injection
 	if (input.steeringFile) built.env.PI_CREW_STEERING_FILE = input.steeringFile;
+	// I5: run/task identity is threaded ALWAYS (not broker-gated) so the worker's
+	// scratchpad metric events (emitScratchpadMetric) can write runId/taskId even
+	// when the inter-pi broker is disabled. Control-namespace keys — pass
+	// assertOnlyControlEnvKeys.
+	if (input.runId) built.env.PI_CREW_BROKER_RUN_ID = input.runId;
+	if (input.agentId) built.env.PI_CREW_BROKER_TASK_ID = input.agentId;
 	// Phase 0 inter-pi broker: inject socket path + token (control-namespace keys,
 	// safe under assertOnlyControlEnvKeys). Only when the parent broker issued
 	// credentials for this run — i.e. the broker is enabled AND this run is
@@ -267,12 +273,7 @@ export function prepareSpawnContext(
 	if (input.brokerSpawn?.socketPath && input.brokerSpawn.token) {
 		built.env.PI_CREW_BROKER_SOCKET = input.brokerSpawn.socketPath;
 		built.env.PI_CREW_BROKER_TOKEN = input.brokerSpawn.token;
-		// The child needs its own runId + taskId to complete the broker `hello`
-		// (the token is validated against the runId; the taskId binds the
-		// connection for message routing). Both are control-namespace keys so
-		// they pass assertOnlyControlEnvKeys. agentId is the per-task id.
-		if (input.runId) built.env.PI_CREW_BROKER_RUN_ID = input.runId;
-		if (input.agentId) built.env.PI_CREW_BROKER_TASK_ID = input.agentId;
+		// runId/taskId are threaded unconditionally above (I5); nothing to add here.
 	}
 	// Phase 1 scratchpad: opt in the persistent Bun-free JS evaluator (execute
 	// tool) for this worker. Gated by role/agent (S-6 read-only roles never;
@@ -289,7 +290,12 @@ export function prepareSpawnContext(
 			// artifactsRoot after F4/S-1).
 			built.env.PI_CREW_ARTIFACTS_ROOT = input.artifactsRoot;
 		}
-		// F4/S-1: the RAW (unredacted) snapshot must NEVER land in artifactsRoot —
+		// I5: thread the run's events path so the worker's scratchpad execute
+		// handler can append fire-and-forget metric events (scratchpad.cell /
+		// scratchpad.restored). Optional — absent in non-team contexts.
+		if (input.eventsPath) {
+			built.env.PI_CREW_EVENTS_PATH = input.eventsPath;
+		} // F4/S-1: the RAW (unredacted) snapshot must NEVER land in artifactsRoot —
 		// point it at a temp dir; the worker reads it then writeArtifact()
 		// (redact+atomic) is the ONLY writer into artifactsRoot.
 		// R3-1: built.tempDir is only created by buildPiWorkerArgs when the agent

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

@@ -1,11 +1,8 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
 import type { AgentConfig } from "../../agents/agent-config.ts";
 import { DEFAULT_CHILD_PI } from "../../config/defaults.ts";
 import { registerChildProcess, unregisterChildProcess } from "../../extension/crew-cleanup.ts";
-import { atomicWriteFile } from "../../state/atomic-write.ts";
 import type { WorkerExitStatus } from "../../state/types.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { redactSecretString } from "../../utils/redaction.ts";
@@ -17,6 +14,7 @@ import { buildFinalChildPiSpawnOptions, prepareSpawnContext } from "./child-pi-s
 import { ChildPiSteeringController } from "./child-pi-steering.ts";
 // Internal helpers for active-child bookkeeping (extracted to child-pi-kill.ts).
 import { ChildPiLineObserver } from "./child-pi-streams.ts";
+import { runMockChildPi } from "./mock-fixtures.ts";
 
 // ── Re-exports from child-pi-kill.ts (H-7 decomposition step 2) ──
 // killProcessTree is internal (not previously exported) — keep that invariant.
@@ -147,6 +145,10 @@ export interface ChildPiRunInput {
 	thinkingOverride?: string;
 	/** Root directory for artifacts (used to validate transcriptPath). */
 	artifactsRoot?: string;
+	/** I5: run events JSONL path — threaded to the worker so its scratchpad
+	 * execute handler can append fire-and-forget metric events. Optional;
+	 * absent in non-team contexts (emission silently skipped). */
+	eventsPath?: string;
 	/** Phase 1 scratchpad: model-fallback attempt index (0-based) for per-attempt
 	 * snapshot relativePath `scratchpad/<taskId>.attempt-<attempt>.snapshot.json`
 	 * (C3). Optional — worker defaults to attempt 0 when unset (e.g. custom
@@ -253,146 +255,10 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			stdout: "",
 			stderr: `pi-crew depth guard blocked child worker: depth ${depth.depth} >= max ${depth.maxDepth}`,
 		};
-	const mock = process.env.PI_TEAMS_MOCK_CHILD_PI;
-	if (mock) {
-		// SECURITY (Issue #2): Mock mode security model is intentionally asymmetric.
-		// PI_TEAMS_MOCK_CHILD_PI is in the allowlist (passed to children) but
-		// PI_CREW_ALLOW_MOCK is NOT in the allowlist — it is only checked in the
-		// parent process scope. This means:
-		//   (1) If an attacker sets PI_CREW_ALLOW_MOCK in the parent's environment,
-		//       it will NOT be passed to child processes (safe).
-		//   (2) Mock mode activation in the child always fails the PI_CREW_ALLOW_MOCK
-		//       check, so mock mode can only be triggered from the parent process.
-		// This asymmetry is intentional: PI_CREW_ALLOW_MOCK must be set in the Pi root
-		// process (the entry point that spawns children), not inherited from a parent.
-		// Setup hooks cannot inject PI_CREW_ALLOW_MOCK into the parent's env.
-		const allowMock = process.env.PI_CREW_ALLOW_MOCK === "1" || process.env.PI_CREW_ALLOW_MOCK === "true";
-		if (!allowMock) {
-			return {
-				exitCode: 1,
-				stdout: "",
-				stderr: "Mock mode requires PI_CREW_ALLOW_MOCK=1",
-			};
-		}
-		// SECURITY: Log mock mode activation prominently for audit trail
-		logInternalError("child-pi.mock", new Error(`Mock mode active: ${mock}`), "NOT running real agents");
-		if (mock === "success") {
-			const stdout = `[MOCK] Success for ${input.agent.name}\n`;
-			await observeStdoutChunk(input, stdout);
-			return { exitCode: 0, stdout, stderr: "" };
-		}
-		if (mock === "json-success" || mock === "adaptive-plan") {
-			const text =
-				mock === "adaptive-plan" && effectiveTask.includes("ADAPTIVE_PLAN_JSON_START")
-					? `[MOCK] Adaptive plan\nADAPTIVE_PLAN_JSON_START\n${JSON.stringify({
-							phases: [
-								{
-									name: "research",
-									tasks: [
-										{
-											role: "explorer",
-											task: "Explore adaptive target",
-										},
-										{
-											role: "analyst",
-											task: "Analyze adaptive target",
-										},
-										{
-											role: "planner",
-											task: "Plan adaptive target",
-										},
-									],
-								},
-								{
-									name: "build",
-									tasks: [
-										{
-											role: "executor",
-											task: "Implement adaptive target",
-										},
-									],
-								},
-								{
-									name: "check",
-									tasks: [
-										{
-											role: "reviewer",
-											task: "Review adaptive target",
-										},
-										{
-											role: "test-engineer",
-											task: "Test adaptive target",
-										},
-										{
-											role: "writer",
-											task: "Summarize adaptive target",
-										},
-									],
-								},
-							],
-						})}\nADAPTIVE_PLAN_JSON_END`
-					: `[MOCK] JSON success for ${input.agent.name}`;
-			const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
-			await observeStdoutChunk(input, stdout);
-			return { exitCode: 0, stdout, stderr: "" };
-		}
-		if (mock === "retryable-failure")
-			return {
-				exitCode: 1,
-				stdout: "",
-				stderr: "[MOCK] rate limit: mock failure",
-			};
-		// E2E fallback-chain fixture: invocation #1 returns a SILENT retryable
-		// failure (exit code 0, no real assistant text, message_end carries a
-		// retryable-pattern errorMessage). Invocation #2+ delegates to the
-		// standard json-success shape. Counter lives in os.tmpdir() keyed by
-		// process.pid + mock name so concurrent test processes don't collide.
-		// The test cleans up the file in its finally block.
-		if (mock === "retryable-failure-then-success") {
-			const counterFile = path.join(os.tmpdir(), `pi-crew-mock-counter-${process.pid}-retryable-failure-then-success`);
-			let count = 0;
-			try {
-				const raw = fs.readFileSync(counterFile, "utf-8");
-				const parsed = Number.parseInt(raw.trim(), 10);
-				if (Number.isFinite(parsed) && parsed >= 0) count = parsed;
-			} catch {
-				// file missing or unreadable — first invocation in this process
-			}
-			count += 1;
-			try {
-				atomicWriteFile(counterFile, String(count));
-			} catch (error) {
-				logInternalError("child-pi.mock-counter-write", error as Error, `file=${counterFile}`);
-			}
-			if (count === 1) {
-				// Silent retryable failure: exit 0, no real text, message_end
-				// carries errorMessage matching `/provider[_ ]?error/i` so that
-				// `detectRetryableModelFailureFromOutput` surfaces it as an error
-				// and `isRetryableModelFailure` routes the next attempt to the
-				// next candidate model. `stopReason:"error"` (NOT "stop") so
-				// `isFinalAssistantEvent` does NOT prematurely terminate the run.
-				const failureEvent = {
-					type: "message_end",
-					message: {
-						role: "assistant",
-						content: [],
-						errorMessage: "Provider error: api_error",
-						stopReason: "error",
-					},
-				};
-				const stdout = `${JSON.stringify(failureEvent)}\n`;
-				await observeStdoutChunk(input, stdout);
-				return { exitCode: 0, stdout, stderr: "" };
-			}
-			// Subsequent invocations: delegate to json-success shape so the
-			// fallback chain's second attempt succeeds and the run completes.
-			const text = `[MOCK] JSON success for ${input.agent.name}`;
-			const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
-			await observeStdoutChunk(input, stdout);
-			return { exitCode: 0, stdout, stderr: "" };
-		}
-		return { exitCode: 1, stdout: "", stderr: `[MOCK] failure: ${mock}` };
-	}
+	// H3 phase 3 (2026-08-10): mock-mode fixtures extracted to mock-fixtures.ts.
+	// Returns undefined when mock mode is NOT active → fall through to spawn.
+	const mockResult = await runMockChildPi(input, effectiveTask, observeStdoutChunk);
+	if (mockResult) return mockResult;
 	// H-7 step 6: spawn/env/args preparation extracted to child-pi-spawn.ts.
 	// prepareSpawnContext builds the worker args, attaches the steering file env,
 	// and handles the pre-spawn abort check (returns an immediate-abort result
@@ -406,7 +272,19 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 	if (!brokerSpawn && brokerIssuer && input.runId) {
 		try {
 			brokerSpawn = await brokerIssuer(input.runId, input.agentId);
-		} catch {
+		} catch (error) {
+			// H8 (2026-08-10): surface the silent degradation. Previously this
+			// swallowed ALL issuer failures (token-rotation race, broker socket
+			// down, key fetch network error) with zero observability — the child
+			// spawned without broker credentials and the run just looked "slow".
+			// logInternalError writes to the internal-error channel (sampled +
+			// bounded); it does NOT propagate, so the child still runs without
+			// broker acceleration (the durable-first invariant is preserved).
+			logInternalError(
+				"child-pi.broker-issuer-failed",
+				error instanceof Error ? error : new Error(String(error)),
+				`runId=${input.runId} agentId=${input.agentId ?? "?"} — child will spawn without broker credentials`,
+			);
 			brokerSpawn = undefined;
 		}
 	}

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

@@ -0,0 +1,171 @@
+/**
+ * Mock-mode fixture runner for child Pi workers (H3 phase 3).
+ *
+ * Extracted from `runChildPi` (src/runtime/child-pi/child-pi.ts) on
+ * 2026-08-10 — the mock branch was ~140 self-contained lines embedded in the
+ * 840-line spawn orchestrator. Behaviour is byte-identical.
+ *
+ * Security model (unchanged): PI_TEAMS_MOCK_CHILD_PI is in the env allowlist
+ * (passed to children) but PI_CREW_ALLOW_MOCK is NOT — mock mode can only be
+ * activated from the parent process scope, never inherited by a child.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { atomicWriteFile } from "../../state/atomic-write.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import type { ChildPiRunInput, ChildPiRunResult } from "./child-pi.ts";
+
+/**
+ * Run a mock child if mock mode is active (PI_TEAMS_MOCK_CHILD_PI set).
+ * Returns `undefined` when mock mode is NOT active — the caller falls through
+ * to the real spawn path.
+ *
+ * @param input          The child run input (agent, env…).
+ * @param effectiveTask  The task text after inherit-context prepend.
+ * @param observe        Callback that feeds a stdout chunk through the line
+ *                       observer (owned by child-pi.ts).
+ */
+export async function runMockChildPi(
+	input: ChildPiRunInput,
+	effectiveTask: string,
+	observe: (input: ChildPiRunInput, text: string) => Promise<void>,
+): Promise<ChildPiRunResult | undefined> {
+	const mock = process.env.PI_TEAMS_MOCK_CHILD_PI;
+	if (!mock) return undefined;
+
+	// SECURITY (Issue #2): see module docstring — PI_CREW_ALLOW_MOCK is only
+	// checked in the parent process scope; it is never passed to children.
+	const allowMock = process.env.PI_CREW_ALLOW_MOCK === "1" || process.env.PI_CREW_ALLOW_MOCK === "true";
+	if (!allowMock) {
+		return {
+			exitCode: 1,
+			stdout: "",
+			stderr: "Mock mode requires PI_CREW_ALLOW_MOCK=1",
+		};
+	}
+	// SECURITY: Log mock mode activation prominently for audit trail
+	logInternalError("child-pi.mock", new Error(`Mock mode active: ${mock}`), "NOT running real agents");
+
+	if (mock === "success") {
+		const stdout = `[MOCK] Success for ${input.agent.name}\n`;
+		await observe(input, stdout);
+		return { exitCode: 0, stdout, stderr: "" };
+	}
+
+	if (mock === "json-success" || mock === "adaptive-plan") {
+		const text =
+			mock === "adaptive-plan" && effectiveTask.includes("ADAPTIVE_PLAN_JSON_START")
+				? `[MOCK] Adaptive plan\nADAPTIVE_PLAN_JSON_START\n${JSON.stringify({
+						phases: [
+							{
+								name: "research",
+								tasks: [
+									{
+										role: "explorer",
+										task: "Explore adaptive target",
+									},
+									{
+										role: "analyst",
+										task: "Analyze adaptive target",
+									},
+									{
+										role: "planner",
+										task: "Plan adaptive target",
+									},
+								],
+							},
+							{
+								name: "build",
+								tasks: [
+									{
+										role: "executor",
+										task: "Implement adaptive target",
+									},
+								],
+							},
+							{
+								name: "check",
+								tasks: [
+									{
+										role: "reviewer",
+										task: "Review adaptive target",
+									},
+									{
+										role: "test-engineer",
+										task: "Test adaptive target",
+									},
+									{
+										role: "writer",
+										task: "Summarize adaptive target",
+									},
+								],
+							},
+						],
+					})}\nADAPTIVE_PLAN_JSON_END`
+				: `[MOCK] JSON success for ${input.agent.name}`;
+		const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
+		await observe(input, stdout);
+		return { exitCode: 0, stdout, stderr: "" };
+	}
+
+	if (mock === "retryable-failure")
+		return {
+			exitCode: 1,
+			stdout: "",
+			stderr: "[MOCK] rate limit: mock failure",
+		};
+
+	// E2E fallback-chain fixture: invocation #1 returns a SILENT retryable
+	// failure (exit code 0, no real assistant text, message_end carries a
+	// retryable-pattern errorMessage). Invocation #2+ delegates to the
+	// standard json-success shape. Counter lives in os.tmpdir() keyed by
+	// process.pid + mock name so concurrent test processes don't collide.
+	// The test cleans up the file in its finally block.
+	if (mock === "retryable-failure-then-success") {
+		const counterFile = path.join(os.tmpdir(), `pi-crew-mock-counter-${process.pid}-retryable-failure-then-success`);
+		let count = 0;
+		try {
+			const raw = fs.readFileSync(counterFile, "utf-8");
+			const parsed = Number.parseInt(raw.trim(), 10);
+			if (Number.isFinite(parsed) && parsed >= 0) count = parsed;
+		} catch {
+			// file missing or unreadable — first invocation in this process
+		}
+		count += 1;
+		try {
+			atomicWriteFile(counterFile, String(count));
+		} catch (error) {
+			logInternalError("child-pi.mock-counter-write", error as Error, `file=${counterFile}`);
+		}
+		if (count === 1) {
+			// Silent retryable failure: exit 0, no real text, message_end
+			// carries errorMessage matching `/provider[_ ]?error/i` so that
+			// `detectRetryableModelFailureFromOutput` surfaces it as an error
+			// and `isRetryableModelFailure` routes the next attempt to the
+			// next candidate model. `stopReason:"error"` (NOT "stop") so
+			// `isFinalAssistantEvent` does NOT prematurely terminate the run.
+			const failureEvent = {
+				type: "message_end",
+				message: {
+					role: "assistant",
+					content: [],
+					errorMessage: "Provider error: api_error",
+					stopReason: "error",
+				},
+			};
+			const stdout = `${JSON.stringify(failureEvent)}\n`;
+			await observe(input, stdout);
+			return { exitCode: 0, stdout, stderr: "" };
+		}
+		// Subsequent invocations: delegate to json-success shape so the
+		// fallback chain's second attempt succeeds and the run completes.
+		const text = `[MOCK] JSON success for ${input.agent.name}`;
+		const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
+		await observe(input, stdout);
+		return { exitCode: 0, stdout, stderr: "" };
+	}
+
+	return { exitCode: 1, stdout: "", stderr: `[MOCK] failure: ${mock}` };
+}

package/src/runtime/crew-agent-records.ts

@@ -299,9 +299,26 @@ export function saveCrewAgents(manifest: TeamRunManifest, records: CrewAgentReco
 	withAgentsLock(manifest, () => {
 		fs.mkdirSync(manifest.stateRoot, { recursive: true });
 		const filePath = agentsPath(manifest);
+		// Index file (agents.json) is the authoritative record — always full
+		// durability.
 		atomicWriteJson(filePath, redactSecrets(records));
 		asyncAgentReaderCache.delete(filePath);
-		for (const record of records) writeCrewAgentStatus(manifest, record);
+		for (const record of records) {
+			// H2 (2026-08-10): per-task status.json is a DENORMALIZED read
+			// optimization for the dashboard/notifier, not an authoritative
+			// record — agents.json + events.jsonl cover crash recovery.
+			// Previously EVERY record (including running/queued progress
+			// snapshots) got a full fsync: N+1 fsyncs per saveCrewAgents call
+			// (50-task team ≈ 750ms blocking). Only TERMINAL records keep
+			// full durability (F4: notifier/dashboard must see the final
+			// state immediately); non-terminal per-task status is best-effort
+			// coalesced like the upsertCrewAgent non-terminal path.
+			if (TERMINAL_AGENT_STATUSES.has(record.status ?? "")) {
+				writeCrewAgentStatus(manifest, record);
+			} else {
+				writeCrewAgentStatusCoalesced(manifest, record);
+			}
+		}
 	});
 }
 

package/src/runtime/output/output-validator.ts

@@ -9,13 +9,41 @@
  * (headings, code blocks, URLs) after compression.
  */
 
-/** Role-specific output format patterns — constructed fresh per call to avoid /g lastIndex leak */
+/**
+ * Why relax: real worker LLMs emit markdown handoffs (`## Handoff`,
+ * `### Summary`, `## Follow-ups`, `- bullet`, `**bold**`) instead of the
+ * caveman formats (`file:line — text`, `PASS:`/`FAIL:`, emoji findings)
+ * these patterns originally required. Each role pattern below ORs its
+ * strict contract with a markdown-structured alternation so structured
+ * handoffs validate while empty/garbage output still fails.
+ *
+ * What changed: added the MARKDOWN_STRUCTURED alternation to every role.
+ * What is preserved: the strict patterns still match verbatim, and the
+ * structural-preservation checks (code blocks, URLs, headings) in
+ * validateWorkerOutput are UNCHANGED.
+ */
+
+/** Accepts atx headings (`## X`), bold (`**x**`), bullets (`- x` / `* x`), and numbered lists (`1. x`) */
+const MARKDOWN_STRUCTURED = /^(?:#{1,6}\s|\*\*|[-*]\s|\d+\.\s)/m;
+
+/** Strict per-role contract patterns (kept verbatim; `.source` is embedded in the alternations below) */
+const STRICT_ROLE_PATTERNS: Record<string, RegExp> = {
+	explorer: /^(\S+:\d+|Defs:|Refs:|Callers:|Tests:|Sites:|No match\.|totals:)/m,
+	executor: /^(\S+:\d+(-\d+)? — .{1,80}\.|verified:|too-big\.|needs-confirm\.|ambiguous\.|regressed\.)/m,
+	reviewer: /^([^:\s]+:\d+:\s+\p{Emoji_Presentation}|No issues\.|totals:)/mu,
+	"security-reviewer": /^([^:\s]+:\d+:\s+\p{Emoji_Presentation}|No issues\.|totals:)/mu,
+	verifier: /^(PASS:|FAIL:)/m,
+};
+
+/** Role-specific output format patterns — constructed fresh per call to avoid /g lastIndex leak.
+ * Each factory: strict contract OR markdown-structured alternation. */
 const ROLE_PATTERN_DEFS: Record<string, () => RegExp> = {
-	explorer: () => /^(\S+:\d+|Defs:|Refs:|Callers:|Tests:|Sites:|No match\.|totals:)/m,
-	executor: () => /^(\S+:\d+(-\d+)? — .{1,80}\.|verified:|too-big\.|needs-confirm\.|ambiguous\.|regressed\.)/m,
-	reviewer: () => /^([^:\s]+:\d+:\s+\p{Emoji_Presentation}|No issues\.|totals:)/mu,
-	"security-reviewer": () => /^([^:\s]+:\d+:\s+\p{Emoji_Presentation}|No issues\.|totals:)/mu,
-	verifier: () => /^(PASS:|FAIL:)/m,
+	explorer: () => new RegExp(`(?:${STRICT_ROLE_PATTERNS.explorer.source})|(?:${MARKDOWN_STRUCTURED.source})`, "m"),
+	executor: () => new RegExp(`(?:${STRICT_ROLE_PATTERNS.executor.source})|(?:${MARKDOWN_STRUCTURED.source})`, "m"),
+	reviewer: () => new RegExp(`(?:${STRICT_ROLE_PATTERNS.reviewer.source})|(?:${MARKDOWN_STRUCTURED.source})`, "mu"),
+	"security-reviewer": () =>
+		new RegExp(`(?:${STRICT_ROLE_PATTERNS["security-reviewer"].source})|(?:${MARKDOWN_STRUCTURED.source})`, "mu"),
+	verifier: () => new RegExp(`(?:${STRICT_ROLE_PATTERNS.verifier.source})|(?:${MARKDOWN_STRUCTURED.source})`, "m"),
 };
 
 /** Fresh RegExp factories for structural preservation checks (avoids /g lastIndex leak) */