pi-crew 0.9.55 → 0.9.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.55",
+  "version": "0.9.56",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -33,7 +33,6 @@
     "*.mjs",
     "src/",
     "dist/index.mjs",
-    "dist/build-meta.json",
     "agents/",
     "teams/",
     "workflows/",

package/scripts/smoke-team-perf.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Tier 7 smoke (real-test-pi-crew): drive a REAL fast-fix team run via
+ * handleRun() directly — bypasses the `team` tool (which the agent context
+ * can't emit action='run' for). Exercises the live orchestration path that the
+ * perf-batch changes touched: team-runner dispatch (Promise.all hooks,
+ * saveCrewAgentsCoalesced, tasks.find→Map), event-log append (fsync best-effort
+ * + F3a + rotation counter), crew-agent-records (path memo), child-pi
+ * (BoundedTail), manifest-cache/state-store (cache-hit + resolveRunStateRoot memo).
+ *
+ * Usage:
+ *   npx tsx scripts/smoke-team-perf.ts                  # real model run
+ *   PI_TEAMS_MOCK_CHILD_PI=adaptive-plan npx tsx scripts/smoke-team-perf.ts  # fast/free mock
+ */
+import { handleRun } from "../src/extension/team-tool/run.ts";
+
+const goal =
+	"Smoke test: write the text 'pi-crew perf-batch smoke OK' to /tmp/pi-crew-perf-smoke.txt, " +
+	"confirm the file exists with that exact content, and report the file path. " +
+	"Keep it under 90 seconds; do NOT run any test or build commands.";
+
+const ctx = { cwd: process.cwd() };
+console.log("[smoke-team-perf] Launching fast-fix team run (real orchestration path)...");
+console.log("[smoke-team-perf] cwd:", ctx.cwd);
+const t0 = Date.now();
+let result;
+try {
+	result = await handleRun({ action: "run", team: "fast-fix", workflow: "fast-fix", goal }, ctx);
+} catch (error) {
+	const ms = Date.now() - t0;
+	console.error(`[smoke-team-perf] handleRun THREW after ${ms}ms:`, error);
+	process.exit(1);
+}
+const ms = Date.now() - t0;
+console.log(`\n[smoke-team-perf] Completed in ${(ms / 1000).toFixed(1)}s. isError=${result.isError}`);
+console.log("=== RESULT details ===");
+console.log(JSON.stringify(result.details, null, 2));
+const text = result.content?.[0];
+if (text && "text" in text) {
+	console.log("\n=== SUMMARY ===");
+	console.log(text.text);
+}
+process.exit(result.isError ? 1 : 0);

package/src/extension/registration/team-tool.ts

@@ -33,6 +33,7 @@ import { loadRunManifestById } from "../../state/state-store.ts";
 import { formatCompactToolProgress } from "../../ui/tool-progress-formatter.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { withSessionId } from "../team-tool/context.ts";
+import { formatTeamToolParamError } from "../team-tool/param-error.ts";
 import { toolResult } from "../tool-result.ts";
 
 const TEAM_TOOL_PROGRESS_TICK_MS = 1000;
@@ -101,7 +102,7 @@ export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps):
 			try {
 				// Defense-in-depth: validate params at runtime even though Pi framework already does
 				if (!Value.Check(TeamToolParams, params)) {
-					return toolResult("Invalid team tool parameters", { action: "list", status: "error" }, true);
+					return toolResult(formatTeamToolParamError(TeamToolParams, params), { action: "list", status: "error" }, true);
 				}
 				const resolved = params as TeamToolParamsValue;
 				const cwdOverride = resolveCwdOverride(ctx.cwd, resolved.cwd);

package/src/extension/team-tool/param-error.ts

@@ -0,0 +1,114 @@
+/**
+ * Friendly team-tool parameter validation error formatting.
+ *
+ * The team tool validates every call with `Value.Check(TeamToolParams, ...)`.
+ * On failure it used to return the opaque `"Invalid team tool parameters"` —
+ * which gave calling agents (LLMs) no clue WHAT was wrong, so they retried the
+ * same malformed shape indefinitely (observed in the wild: agents passing
+ * `goal` as an array/object, or `action` with wrong casing, then looping).
+ *
+ * `formatTeamToolParamError` produces an actionable message:
+ *   1. Targeted heuristics for the COMMON mistakes (action casing; goal/team/
+ *      runId passed as a non-string) — pinpoint the exact field, because the
+ *      TypeBox Union reports only a root-level "Expected union value".
+ *   2. TypeBox `Value.Errors` output (catches anything the heuristics miss).
+ *   3. Concrete correct-call examples for the common actions.
+ * Agents can self-correct from this instead of looping.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+
+/** Short human description of a received value (for error messages). */
+function describeValue(v: unknown): string {
+	if (v === null) return "null";
+	if (Array.isArray(v)) return `array (length ${v.length})`;
+	if (typeof v === "object") return "object";
+	if (typeof v === "string") return `string "${v.length > 40 ? `${v.slice(0, 37)}...` : v}"`;
+	return `${typeof v} (${String(v).slice(0, 40)})`;
+}
+
+/** Pinpoint the common agent mistakes that TypeBox Union can't field-locate. */
+function diagnoseCommonMistakes(params: unknown): string[] {
+	const hints: string[] = [];
+	if (typeof params !== "object" || params === null || Array.isArray(params)) {
+		return hints;
+	}
+	const p = params as Record<string, unknown>;
+
+	// action: casing / non-string
+	if ("action" in p) {
+		const a = p.action;
+		if (typeof a !== "string") {
+			hints.push(`  • 'action': must be a lowercase string (e.g. "run", "status", "list") — got ${describeValue(a)}.`);
+		} else if (a !== a.toLowerCase()) {
+			hints.push(`  • 'action': "${a}" has wrong casing — action is case-sensitive. Use "${a.toLowerCase()}".`);
+		}
+	}
+
+	// Flat-string fields that agents commonly pass as objects/arrays
+	const stringFields = ["goal", "team", "runId", "task", "role", "agent", "workflow", "model", "cwd", "chain"];
+	for (const f of stringFields) {
+		if (!(f in p)) continue;
+		const v = p[f];
+		if (typeof v === "string") continue;
+		if (Array.isArray(v)) {
+			hints.push(
+				`  • '${f}': must be a single flat string — got an array (length ${v.length}). Pass e.g. "${f}": "<value>", not a list.`,
+			);
+		} else if (typeof v === "object" && v !== null) {
+			hints.push(`  • '${f}': must be a single flat string — got an object. Pass e.g. "${f}": "<value>".`);
+		} else {
+			hints.push(`  • '${f}': must be a string — got ${describeValue(v)}.`);
+		}
+	}
+	return hints;
+}
+
+/**
+ * Build a helpful validation-failure message for a team-tool call.
+ *
+ * @param schema The TypeBox schema (TeamToolParams) that rejected the params.
+ * @param params The raw params the caller passed.
+ * @returns A multi-line message: what went wrong + correct-call examples.
+ */
+export function formatTeamToolParamError(schema: TSchema, params: unknown): string {
+	const issues = [...diagnoseCommonMistakes(params)];
+
+	try {
+		const errors = [...Value.Errors(schema, params)];
+		const seen = new Set<string>();
+		for (const e of errors) {
+			if (issues.length >= 8) break;
+			const key = `${e.path}|${e.type}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			const pathLabel = e.path ? `'${e.path}'` : "(schema)";
+			issues.push(`  • ${pathLabel}: ${e.message} — received ${describeValue(e.value)}`);
+		}
+	} catch {
+		/* Value.Errors itself threw — the heuristic issues are still shown */
+	}
+
+	if (issues.length === 0) {
+		issues.push("  • params did not match any valid team-tool action shape");
+	}
+
+	return [
+		"Invalid team tool parameters — the call was rejected by schema validation.",
+		"",
+		"What went wrong:",
+		...issues,
+		"",
+		"Correct call shapes — `action` is case-sensitive (lowercase); `goal`,",
+		"`team`, `runId`, `task`, `role` MUST be flat strings, never objects/arrays:",
+		'  • Run a team:       { "action": "run", "goal": "<what to achieve>", "team": "implementation" }',
+		'  • Suggest a team:   { "action": "recommend", "goal": "<what to achieve>" }',
+		'  • List recent runs: { "action": "list" }',
+		'  • Run status:       { "action": "status", "runId": "<runId>" }',
+		'  • Direct one agent: { "action": "run", "role": "<agent>", "task": "<one task>" }',
+		"",
+		'Common mistakes: `action` uppercase (use "run" not "Run"); `goal` passed',
+		"as an array/object instead of a single string; params nested instead of flat.",
+	].join("\n");
+}

package/src/extension/team-tool/status.ts

@@ -60,6 +60,11 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 	const phaseProgress = computePhaseProgress(tasks);
 	const allEvents = readEvents(manifest.eventsPath);
 	const events = allEvents.slice(-8);
+	// P1-8: pre-build the ack-timeout requestId set once (was O(events × messages)
+	// via allEvents.some() inside the mailbox loop).
+	const ackTimeoutRequestIds = new Set(
+		allEvents.filter((event) => event.type === "agent.group_join.ack_timeout").map((event) => String(event.data?.requestId ?? "")),
+	);
 	const attentionByTask = new Map(
 		allEvents.filter((event) => event.type === "task.attention" && event.taskId).map((event) => [event.taskId!, event]),
 	);
@@ -80,7 +85,7 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 		const ageMs = Date.now() - new Date(message.createdAt).getTime();
 		const requestId = String(message.data?.requestId ?? "unknown");
 		const timedOut = ack === "pending" && ackTimeoutMs !== undefined && Number.isFinite(ageMs) && ageMs > ackTimeoutMs;
-		if (timedOut && !allEvents.some((event) => event.type === "agent.group_join.ack_timeout" && event.data?.requestId === requestId)) {
+		if (timedOut && !ackTimeoutRequestIds.has(requestId)) {
 			appendEvent(manifest.eventsPath, {
 				type: "agent.group_join.ack_timeout",
 				runId: manifest.runId,

package/src/runtime/attention-events.ts

@@ -1,5 +1,6 @@
-import { appendEvent, readEvents } from "../state/event-log.ts";
+import { appendEvent, type TeamEvent } from "../state/event-log.ts";
 import type { CrewAttentionEventData, TeamRunManifest } from "../state/types.ts";
+import { readJsonlTail } from "../utils/incremental-reader.ts";
 
 export interface AppendTaskAttentionInput {
 	manifest: TeamRunManifest;
@@ -9,7 +10,7 @@ export interface AppendTaskAttentionInput {
 }
 
 export function appendTaskAttentionEvent(input: AppendTaskAttentionInput): boolean {
-	const recent = readEvents(input.manifest.eventsPath).slice(-200);
+	const recent = readJsonlTail<TeamEvent>(input.manifest.eventsPath, 256 * 1024).items.slice(-200);
 	const dedupKey = `${input.taskId ?? ""}:${input.data.reason}:${input.data.activityState}`;
 	const duplicate = recent.some(
 		(event) =>

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

@@ -87,6 +87,18 @@ function compactChildPiEvent(event: unknown): unknown | undefined {
 			stopReason: record.stopReason,
 		};
 	}
+	// P2-25: pass supervisor_contact events through with their full payload. The
+	// generic fallthrough below strips everything but `type`, which made the
+	// feature dead — the contact never reached recordSupervisorContact.
+	if (record.type === "supervisor_contact" || record.type === "crew_supervisor_contact") {
+		return {
+			type: record.type,
+			taskId: record.taskId,
+			reason: record.reason,
+			message: record.message,
+			data: record.data,
+		};
+	}
 	return record.type ? { type: record.type } : undefined;
 }
 

package/src/runtime/child-pi.ts

@@ -11,11 +11,12 @@ import { logInternalError } from "../utils/internal-error.ts";
 import { redactSecretString } from "../utils/redaction.ts";
 import { getActiveBrokerIssuer } from "./broker-issuer.ts";
 import { FINAL_DRAIN_MS, HARD_KILL_MS, POST_EXIT_STDIO_GUARD_MS, RESPONSE_TIMEOUT_MS } from "./child-pi-constants.ts";
-import { appendBoundedTail, clearHardKillTimer, killProcessTree, registerActiveChild, unregisterActiveChild } from "./child-pi-kill.ts";
+import { clearHardKillTimer, killProcessTree, registerActiveChild, unregisterActiveChild } from "./child-pi-kill.ts";
 import { buildFinalChildPiSpawnOptions, prepareSpawnContext } from "./child-pi-spawn.ts";
 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 { BoundedTail } from "./compact-stages/bounded-tail.ts";
 
 // ── Re-exports from child-pi-kill.ts (H-7 decomposition step 2) ──
 // killProcessTree is internal (not previously exported) — keep that invariant.
@@ -431,8 +432,10 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					ts: new Date().toISOString(),
 				});
 			}
-			let stdout = "";
-			let stderr = "";
+			// P0-1: O(1)-amortized bounded accumulators (segment ring) — replaces the O(n²)
+			// appendBoundedTail rebuild-per-line pattern that re-scanned 512 KiB every line.
+			const stdoutTail = new BoundedTail();
+			const stderrTail = new BoundedTail();
 			let settled = false;
 			let childExited = false;
 			let postExitGuardCleanup: (() => void) | undefined;
@@ -526,6 +529,8 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				if (noResponseTimer) clearTimeout(noResponseTimer);
 				noResponseTimer = setTimeout(() => {
 					responseTimeoutHit = true;
+					// P0-1: snapshot the bounded stderr accumulator once for this timer fire.
+					const stderr = stderrTail.value();
 					// Capture stderr at timeout moment for debugging
 					// SEC-1: redact secrets before embedding in lifecycle event so
 					// worker-emitted secrets (API keys etc.) don't bypass redaction.
@@ -569,8 +574,8 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 							const timeoutErr = `Child Pi produced no new output for ${responseTimeoutMs}ms; killed but did not exit within ${SAFETY_SETTLE_MS}ms (possible zombie).`;
 							void settle({
 								exitCode: null,
-								stdout,
-								stderr,
+								stdout: stdoutTail.value(),
+								stderr: stderrTail.value(),
 								error: timeoutErr,
 								exitStatus: {
 									exitCode: null,
@@ -600,7 +605,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				...input,
 				onStdoutLine: (line) => {
 					if (!steeringController.isHardAbortInitiated()) restartNoResponseTimer();
-					stdout = appendBoundedTail(stdout, `${line}\n`);
+					stdoutTail.push(`${line}\n`);
 					input.onStdoutLine?.(line);
 				},
 				onJsonEvent: (event) => {
@@ -913,9 +918,12 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			});
 			child.stderr?.on("data", (chunk: Buffer) => {
 				if (!steeringController.isHardAbortInitiated()) restartNoResponseTimer();
-				stderr = appendBoundedTail(stderr, chunk.toString("utf-8"));
+				stderrTail.push(chunk.toString("utf-8"));
 			});
 			child.on("error", (error) => {
+				// P0-1: snapshot the bounded accumulators once for this handler.
+				const stdout = stdoutTail.value();
+				const stderr = stderrTail.value();
 				// Reject pending operations with process error context
 				// SEC-1: redact stderr secrets embedded in the error message + excerpt.
 				const processError = new Error(
@@ -956,6 +964,8 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				});
 			});
 			child.on("exit", (code, signal) => {
+				// P0-1: snapshot the bounded stderr accumulator once for this handler.
+				const stderr = stderrTail.value();
 				if (child.pid) {
 					unregisterActiveChild(child.pid);
 					clearHardKillTimer(child.pid);
@@ -1017,6 +1027,9 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				}
 			});
 			child.on("close", (exitCode) => {
+				// P0-1: snapshot the bounded accumulators once for this handler.
+				const stdout = stdoutTail.value();
+				const stderr = stderrTail.value();
 				if (child.pid) {
 					unregisterActiveChild(child.pid);
 					clearHardKillTimer(child.pid);

package/src/runtime/compact-stages/bounded-tail.ts

@@ -0,0 +1,84 @@
+/**
+ * BoundedTail — O(1)-amortized bounded string accumulator (segment ring + running
+ * byte counter).
+ *
+ * Replaces the O(n²) `appendBoundedTail` rebuild-per-line pattern on the child stdout/stderr
+ * hot path. The defect (P0-1, verified 2026-07-29): the old accumulator did
+ * `new TailCaptureStage(...).apply(current + chunk)` on EVERY output line, so once the
+ * buffer filled to the 512 KiB cap each line re-scanned the whole buffer with
+ * `Buffer.byteLength` AND ran a per-character `while(...) tail = tail.slice(0,-1)` trim
+ * — 2.3 s (ASCII) to 112 s (multi-byte) of main-thread block per task.
+ *
+ * `push(chunk)` is O(chunk): it appends the segment and shifts whole leading segments
+ * while over cap, recomputing byte length only for the dropped segment — never the full
+ * buffer, never per-character. The single byte-exact boundary trim runs ONCE, in
+ * `value()`, which is read only at result-build / error time (rare).
+ *
+ * Output parity with the old `TailCaptureStage`-based path is preserved: under cap →
+ * verbatim; over cap → `[pi-crew captured output truncated to last X KiB]\n` + the last
+ * ≤maxBytes bytes snapped to a UTF-8 char boundary.
+ */
+import { DEFAULT_CHILD_PI } from "../../config/defaults.ts";
+
+const DEFAULT_MAX_BYTES = DEFAULT_CHILD_PI.maxCaptureBytes;
+
+/** Default marker, identical to the old appendBoundedTail/TailCaptureStage wording. */
+function defaultMarker(maxBytes: number): string {
+	return `[pi-crew captured output truncated to last ${Math.round(maxBytes / 1024)} KiB]`;
+}
+
+export class BoundedTail {
+	readonly #maxBytes: number;
+	readonly #marker: string;
+	#segs: string[] = [];
+	#bytes = 0;
+	#dropped = false;
+	#cached: string | undefined;
+	#dirty = false;
+
+	constructor(maxBytes: number = DEFAULT_MAX_BYTES, marker?: string) {
+		if (!(maxBytes > 0)) throw new Error(`BoundedTail: maxBytes must be > 0, got ${maxBytes}`);
+		this.#maxBytes = maxBytes;
+		this.#marker = marker ?? defaultMarker(maxBytes);
+	}
+
+	/** Append a chunk. O(chunk) amortized; never scans the full buffer. */
+	push(chunk: string): this {
+		if (!chunk) return this;
+		this.#segs.push(chunk);
+		this.#bytes += Buffer.byteLength(chunk, "utf-8");
+		// Drop whole leading segments while over cap. Stop at length 1 so a single
+		// oversized segment is trimmed exactly once in value() instead of per-char.
+		while (this.#bytes > this.#maxBytes && this.#segs.length > 1) {
+			const dropped = this.#segs.shift() as string;
+			this.#bytes -= Buffer.byteLength(dropped, "utf-8");
+			this.#dropped = true;
+		}
+		this.#dirty = true;
+		return this;
+	}
+
+	/** Materialize the bounded string. Computed at most once per push; cached otherwise. */
+	value(): string {
+		if (!this.#dirty && this.#cached !== undefined) return this.#cached;
+		const body = this.#segs.join("");
+		const result = this.#bound(body);
+		this.#cached = result;
+		this.#dirty = false;
+		return result;
+	}
+
+	/** Byte-exact bound with marker parity vs the old TailCaptureStage path. */
+	#bound(body: string): string {
+		if (Buffer.byteLength(body, "utf-8") <= this.#maxBytes) {
+			// Under cap: add the marker only if we dropped earlier segments.
+			return this.#dropped ? `${this.#marker}\n${body}` : body;
+		}
+		// Over cap (single segment larger than max, or a boundary segment): keep the
+		// last ≤maxBytes bytes snapped forward past any UTF-8 continuation bytes.
+		const buf = Buffer.from(body, "utf-8");
+		let start = Math.max(0, buf.length - this.#maxBytes);
+		while (start < buf.length && (buf[start] & 0xc0) === 0x80) start++;
+		return `${this.#marker}\n${buf.subarray(start).toString("utf-8")}`;
+	}
+}

package/src/runtime/concurrency.ts

@@ -1,4 +1,5 @@
 import { DEFAULT_CONCURRENCY } from "../config/defaults.ts";
+import { getWorkerCapCapacity } from "./global-worker-cap.ts";
 
 export interface ResolveBatchConcurrencyInput {
 	workflowName: string;
@@ -7,6 +8,8 @@ export interface ResolveBatchConcurrencyInput {
 	limitMaxConcurrentWorkers?: number;
 	allowUnboundedConcurrency?: boolean;
 	hardCap?: number;
+	/** Optional override for the global worker cap (test determinism). Defaults to getWorkerCapCapacity(). */
+	workerCap?: number;
 	readyCount: number;
 	workspaceMode?: "single" | "worktree";
 	readyRoles?: string[];
@@ -45,9 +48,12 @@ export function resolveBatchConcurrency(input: ResolveBatchConcurrencyInput): Ba
 	else if (teamMax !== undefined) source = "team";
 	else source = "workflow";
 	const hardCap = positiveInteger(input.hardCap) ?? DEFAULT_CONCURRENCY.hardCap;
-	const maxConcurrent = input.allowUnboundedConcurrency ? requested : Math.min(requested, hardCap);
+	// P1-7: consult the global worker cap so the scheduler doesn't over-dispatch
+	// (e.g. dispatch 4 while the global semaphore holds 2 on a 4-core machine).
+	const workerCap = positiveInteger(input.workerCap) ?? getWorkerCapCapacity();
+	const maxConcurrent = input.allowUnboundedConcurrency ? requested : Math.min(requested, hardCap, workerCap);
 	const readyCount = Math.max(0, Math.trunc(Number.isFinite(input.readyCount) ? input.readyCount : 0));
-	const cappedReason = maxConcurrent < requested ? `;capped:${hardCap}` : "";
+	const cappedReason = maxConcurrent < requested ? `;capped:hard=${hardCap},worker=${workerCap}` : "";
 	const unboundedReason = input.allowUnboundedConcurrency && requested > hardCap ? `;unbounded:${hardCap}` : "";
 	return {
 		maxConcurrent,

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

@@ -26,14 +26,39 @@ export function agentStateDir(manifest: TeamRunManifest, taskId: string): string
 	return path.join(agentsRoot(manifest), safeAgentTaskId(taskId));
 }
 
+// P1-5: per-task path memoization. The agent state dir + file paths cannot
+// change within a task, so the mkdir/lstat/resolveRealContainedPath validation
+// (≈30 syscalls each, incl. a full ancestor walk) only needs to run ONCE per
+// task — not on every event/output line (was ~60 syscalls/event for the double
+// ensureAgentStateDir call alone). FIFO-bounded so the cache can't grow with
+// run count.
+const ensuredAgentDirs = new Map<string, string>();
+const resolvedAgentFiles = new Map<string, string>();
+const AGENT_PATH_CACHE_MAX = 512;
+
+function bumpAgentPathCache(): void {
+	if (ensuredAgentDirs.size > AGENT_PATH_CACHE_MAX) {
+		const oldest = ensuredAgentDirs.keys().next().value;
+		if (oldest !== undefined) ensuredAgentDirs.delete(oldest);
+	}
+	if (resolvedAgentFiles.size > AGENT_PATH_CACHE_MAX) {
+		const oldest = resolvedAgentFiles.keys().next().value;
+		if (oldest !== undefined) resolvedAgentFiles.delete(oldest);
+	}
+}
+
 export function ensureAgentStateDir(manifest: TeamRunManifest, taskId: string): string {
 	const root = agentsRoot(manifest);
+	const dir = agentStateDir(manifest, taskId);
+	const cachedDir = ensuredAgentDirs.get(dir);
+	if (cachedDir !== undefined) return cachedDir;
 	fs.mkdirSync(root, { recursive: true });
 	if (fs.lstatSync(root).isSymbolicLink()) throw new Error(`Invalid agents root: ${root}`);
-	const dir = agentStateDir(manifest, taskId);
 	fs.mkdirSync(dir, { recursive: true });
 	if (fs.lstatSync(dir).isSymbolicLink()) throw new Error(`Invalid agent state directory: ${dir}`);
 	resolveRealContainedPath(root, path.basename(dir));
+	ensuredAgentDirs.set(dir, dir);
+	bumpAgentPathCache();
 	return dir;
 }
 
@@ -45,8 +70,26 @@ function safeExistingAgentFile(manifest: TeamRunManifest, taskId: string, fileNa
 }
 
 export function agentStateFile(manifest: TeamRunManifest, taskId: string, fileName: string): string {
+	const dir = agentStateDir(manifest, taskId);
+	const cacheKey = `${dir}\0${fileName}`;
+	const cached = resolvedAgentFiles.get(cacheKey);
+	if (cached !== undefined) return cached;
 	ensureAgentStateDir(manifest, taskId);
-	return safeExistingAgentFile(manifest, taskId, fileName);
+	const resolved = safeExistingAgentFile(manifest, taskId, fileName);
+	resolvedAgentFiles.set(cacheKey, resolved);
+	bumpAgentPathCache();
+	return resolved;
+}
+
+/** @internal Test-only: clear the path memoization cache. */
+export function __test_clearAgentPathCache(): void {
+	ensuredAgentDirs.clear();
+	resolvedAgentFiles.clear();
+}
+
+/** @internal Test-only: inspect cache occupancy (regression guard for P1-5). */
+export function __test_agentPathCacheStats(): { dirs: number; files: number } {
+	return { dirs: ensuredAgentDirs.size, files: resolvedAgentFiles.size };
 }
 
 export function agentStatusPath(manifest: TeamRunManifest, taskId: string): string {
@@ -250,6 +293,9 @@ export async function readCrewAgentsAsync(manifest: TeamRunManifest): Promise<Cr
 }
 
 export function saveCrewAgents(manifest: TeamRunManifest, records: CrewAgentRecord[]): void {
+	// P0-3: flush any pending coalesced (best-effort) write first so a stale
+	// debounced progress snapshot can't clobber this durable write.
+	flushPendingAgentWrites();
 	withAgentsLock(manifest, () => {
 		fs.mkdirSync(manifest.stateRoot, { recursive: true });
 		const filePath = agentsPath(manifest);

package/src/runtime/diagnostic-export.ts

@@ -4,11 +4,12 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { MetricRegistry } from "../observability/metric-registry.ts";
 import type { MetricSnapshot } from "../observability/metrics-primitives.ts";
 import { atomicWriteFile } from "../state/atomic-write.ts";
-import { readEvents, type TeamEvent } from "../state/event-log.ts";
+import type { TeamEvent } from "../state/event-log.ts";
 import { loadRunManifestById } from "../state/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { type HeartbeatSummary, summarizeHeartbeats } from "../ui/heartbeat-aggregator.ts";
 import type { RunUiSnapshot } from "../ui/snapshot-types.ts";
+import { readJsonlTail } from "../utils/incremental-reader.ts";
 import { isSecretKey, redactSecrets } from "../utils/redaction.ts";
 import { readCrewAgents } from "./crew-agent-records.ts";
 import { buildRecoveryLedger, type RecoveryLedgerEntry } from "./recovery-recipes.ts";
@@ -92,7 +93,7 @@ export async function exportDiagnostic(
 	if (!loaded) throw new Error(`Run '${runId}' not found.`);
 	const exportedAt = new Date().toISOString();
 	const safeTimestamp = exportedAt.replace(/[:.]/g, "-");
-	const recentEvents = readEvents(loaded.manifest.eventsPath).slice(-200);
+	const recentEvents = readJsonlTail<TeamEvent>(loaded.manifest.eventsPath, 256 * 1024).items.slice(-200);
 	const metricsSnapshot = options.registry?.snapshot();
 	const taskDiagnostics: Record<string, Record<string, unknown>> = {};
 	const terminalEvidence: Record<string, TeamTaskState["terminalEvidence"]> = {};

package/src/runtime/manifest-cache.ts

@@ -109,7 +109,11 @@ function parseManifestIfChanged(root: string, runId: string, filePath: string, p
 		return undefined;
 	}
 	if (previous && previous.mtimeMs === stat.mtimeMs && previous.size === stat.size) {
-		return validateManifestForRoot(root, runId, previous.manifest) ? previous : undefined;
+		// P1-9: the manifest file is unchanged, so its recorded paths and their
+		// containment verdict are unchanged too — skip the ~10-syscall
+		// validateManifestForRoot re-check on cache hit. list() and listActive()
+		// both scan within the same TTL window, so the second scan is now free.
+		return previous;
 	}
 	const manifest = parseManifest(filePath);
 	if (!manifest || !validateManifestForRoot(root, runId, manifest)) return undefined;

package/src/runtime/semaphore.ts

@@ -33,7 +33,10 @@ export class Semaphore {
 		// implementation let #queue grow without bound, risking memory
 		// exhaustion under sustained high concurrency with slow releases.
 		if (this.#queue.length >= Semaphore.MAX_QUEUE) {
-			throw new Error(`Semaphore queue full: ${this.#queue.length} waiters (max ${Semaphore.MAX_QUEUE}); cannot acquire slot`);
+			// P1-7: reject (don't throw) so callers can backpressure instead of crashing.
+			return Promise.reject(
+				new Error(`Semaphore queue full: ${this.#queue.length} waiters (max ${Semaphore.MAX_QUEUE}); cannot acquire slot`),
+			);
 		}
 		const { promise, resolve } = (() => {
 			let res: () => void;

package/src/runtime/supervisor-contact.ts

@@ -37,22 +37,21 @@ export function recordSupervisorContact(manifest: TeamRunManifest, payload: Omit
  * Parse a supervisor contact request from child Pi stdout.
  * Detects structured JSON lines with type "supervisor_contact".
  */
-export function parseSupervisorContactFromLine(line: string): Omit<SupervisorContactPayload, "timestamp" | "runId"> | undefined {
-	if (!line.trim()) return undefined;
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(line);
-	} catch {
-		return undefined;
-	}
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
-	const record = parsed as Record<string, unknown>;
+const SUPERVISOR_CONTACT_REASONS = ["decision_needed", "clarification", "approval", "error_escalation", "custom"] as const;
+
+/**
+ * Validate a parsed event object as a supervisor-contact payload. Shared by the
+ * event-based (current) and line-based (deprecated) entry points. Returns the
+ * normalized payload, or undefined if the event is not a supervisor contact.
+ */
+export function supervisorContactFromEvent(event: unknown): Omit<SupervisorContactPayload, "timestamp" | "runId"> | undefined {
+	if (!event || typeof event !== "object" || Array.isArray(event)) return undefined;
+	const record = event as Record<string, unknown>;
 	if (record.type !== "supervisor_contact" && record.type !== "crew_supervisor_contact") return undefined;
 	return {
 		taskId: typeof record.taskId === "string" ? record.taskId : "",
 		reason:
-			typeof record.reason === "string" &&
-			["decision_needed", "clarification", "approval", "error_escalation", "custom"].includes(record.reason)
+			typeof record.reason === "string" && (SUPERVISOR_CONTACT_REASONS as readonly string[]).includes(record.reason)
 				? (record.reason as SupervisorContactPayload["reason"])
 				: "custom",
 		message: typeof record.message === "string" ? record.message : String(record.message ?? ""),
@@ -62,3 +61,19 @@ export function parseSupervisorContactFromLine(line: string): Omit<SupervisorCon
 				: undefined,
 	};
 }
+
+/**
+ * @deprecated The compact pipeline now passes `supervisor_contact` events through
+ * to `onJsonEvent` with their full payload (P2-25 fix). Prefer
+ * `supervisorContactFromEvent` on the parsed event. Kept for backward compat.
+ */
+export function parseSupervisorContactFromLine(line: string): Omit<SupervisorContactPayload, "timestamp" | "runId"> | undefined {
+	if (!line.trim()) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(line);
+	} catch {
+		return undefined;
+	}
+	return supervisorContactFromEvent(parsed);
+}