pi-crew 0.7.4 → 0.7.5

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.7.5] — Ambient context status + perf hardening + error taxonomy (2026-06-15)
+
+Three workstreams from the Round 11 API-gap and Round 15 perf/error audits: a new `context`-event feature, three performance fixes, and a full error-taxonomy expansion.
+
+### Features
+
+- **Ambient crew-status injection (GAP-2)** — registers Pi's `context` event handler so the parent agent stays continuously aware of in-flight crew runs on every LLM call, without calling the `team` tool. Injects a compact status note (runId/team/status/goal, capped at 3 inline) before the last message. **Transient and safe**: Pi uses the result only for that call (`agent-loop.ts:283-289`) — it never mutates persistent `state.messages`, so there's no accumulation or history corruption. No-op when zero runs are active. Toggle: `reliability.ambientStatusInjection`.
+
+### Performance (Round 15 audit)
+
+- **P1 (CRITICAL): throttle `persistSingleTaskUpdate` in `onJsonEvent`** — previously every child JSON event did a full locked read-parse-write of `tasks.json`; a 200-event task produced 200 such cycles. Now throttled to 500ms (in-memory progress stays fresh every event; final state force-flushed on completion).
+- **P4: `buildWorkspaceTree` TTL cache (30s)** — workers in a run share a cwd, so the recursive walk was repeated once per task.
+- **P5: `readKnowledge` mtime+size cache** — fired on every agent start (main + every worker), re-reading the same file N×/run.
+
+### Error experience (Round 15 audit)
+
+- **E1: extended CrewError taxonomy E007–E012** — the taxonomy previously covered only file I/O and discovery. The most common *runtime* failures (child timeout, model exhaustion, pre-step failure, event-log lock timeout, depth limit, stale run) now throw structured `CrewError`s with a machine-readable code, a default actionable help hint, and context. Wired into all six throw sites (`task-runner.ts`, `event-log.ts`, `pipeline-runner.ts`, `stale-reconciler.ts`).
+- **E2: model fallback exhaustion surfaces the full chain tried** ("All N candidates exhausted (tried: a → b → c). Last failure: …") instead of only the last attempt's raw error.
+- **E3: stale-reconcile error explains the heartbeat mechanism + remediation** instead of the bare "Stale run reconciled: <reason>".
+
+### Tests
+
+- +20 tests (context-status-injection: 11, errors E007–E012: 9). 4800+ pass / 0 fail.
+
+### Research
+
+This release was driven by the Round 11 Pi-API gap audit and the Round 15 performance/cost + error-experience audit, documented in `research-findings/`.
+
 ## [0.7.4] — Editor autocomplete + settings shortcut (2026-06-15)
 
 Round 13 UX quick wins round-out: the remaining two Pi extension API integrations plus a hard-won CI reliability fix after the state-store test flake re-emerged on Windows and macOS.

package/package.json

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

package/src/config/types.ts

@@ -178,6 +178,8 @@ export interface CrewReliabilityConfig {
 	autoRepairIntervalMs?: number;
 	/** Remove /tmp/pi-crew-* directories after their orphaned runs are reconciled. Default: true. */
 	cleanupOrphanedTempDirs?: boolean;
+	/** Inject a compact ambient crew-status note into the agent's context on every LLM call while crew runs are in-flight, so the agent stays continuously aware of active runs without calling the `team` tool. No-op when no runs are active. Default: true. */
+	ambientStatusInjection?: boolean;
 }
 
 export interface CrewOtlpConfig {

package/src/errors.ts

@@ -30,6 +30,14 @@ export const ErrorCode = {
   InvalidStatusTransition: "E004",  // Run/task status cannot legally transition
   ConfigError: "E005",              // Malformed config or missing required field
   ResourceNotFound: "E006",         // Agent/team/workflow not found in discovery paths
+  // E1 (Round 15): runtime failure categories that previously threw raw Error
+  // with no code, no help hint, and no context. Surfaces actionable guidance.
+  ChildTimeout: "E007",             // Child Pi worker became unresponsive and was killed
+  ModelExhausted: "E008",           // All model candidates in the fallback chain failed
+  PreStepFailed: "E009",            // A pre-step hook script returned a non-zero exit
+  EventLogLockTimeout: "E010",      // Could not acquire the event-log file lock
+  DepthLimitExceeded: "E011",       // Pipeline/chain recursion depth limit hit (circular dep)
+  RunStale: "E012",                 // Run reconciled as stale/zombie (heartbeat expired)
 } as const;
 
 export type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
@@ -41,6 +49,13 @@ const DEFAULT_HELP: Record<ErrorCode, string | undefined> = {
   [ErrorCode.InvalidStatusTransition]: "Verify the run status using `team status` before retrying.",
   [ErrorCode.ConfigError]: "Check the configuration file for syntax errors or missing required fields.",
   [ErrorCode.ResourceNotFound]: "Use `team list` to see available agents, teams, and workflows.",
+  // E1 (Round 15): help hints for the new runtime categories.
+  [ErrorCode.ChildTimeout]: "The child Pi worker produced no output for too long and was terminated. Re-run the team; if it recurs, raise the response timeout in config or reduce the task scope.",
+  [ErrorCode.ModelExhausted]: "Every model in the fallback chain failed. Check your API key/quota and the per-attempt errors, then retry or swap the model in config.",
+  [ErrorCode.PreStepFailed]: "The pre-step hook script exited non-zero. Inspect its stderr, or mark it optional in the workflow step (preStepOptional).",
+  [ErrorCode.EventLogLockTimeout]: "Another process holds the event-log lock. Check for orphaned `.lock` files or stale pi-crew processes, then retry.",
+  [ErrorCode.DepthLimitExceeded]: "A pipeline/chain exceeded the recursion depth limit, which usually indicates a circular stage dependency. Review step `dependsOn` chains.",
+  [ErrorCode.RunStale]: "The worker stopped heartbeating and was treated as a zombie. Re-run the team (resume or fresh); if it recurs, check `runtime.executeWorkers` / system load.",
 };
 
 /**
@@ -122,4 +137,55 @@ export const errors = {
       `${type} '${name}' not found in any discovery path`,
     );
   },
+
+  // E1 (Round 15): runtime failure constructors. These wrap the raw-throw
+  // sites identified in the Round 15 error-experience audit so failures carry
+  // a machine-readable code, a help hint, and structured context.
+  childTimeout(detail: { timeoutMs?: number; taskId?: string; stderr?: string }): CrewError {
+    const tail = detail.stderr ? ` Stderr tail: ${detail.stderr.slice(-400)}` : "";
+    const dur = detail.timeoutMs ? ` after ${detail.timeoutMs}ms of no output` : "";
+    return new CrewError(
+      ErrorCode.ChildTimeout,
+      `Child Pi worker became unresponsive${dur} and was terminated.${tail}`,
+    ).withContext(`worker execution${detail.taskId ? ` (task ${detail.taskId})` : ""}`);
+  },
+
+  modelExhausted(chain: string[], lastFailure?: string): CrewError {
+    const tried = chain.join(" → ");
+    const last = lastFailure ? ` Last failure: ${lastFailure}` : "";
+    return new CrewError(
+      ErrorCode.ModelExhausted,
+      `All ${chain.length} model candidates exhausted (tried: ${tried}).${last}`,
+    ).withContext("model fallback chain");
+  },
+
+  preStepFailed(script: string, exitCode: number | undefined, stderr?: string): CrewError {
+    const tail = stderr ? ` Stderr: ${stderr.slice(-400)}` : "";
+    return new CrewError(
+      ErrorCode.PreStepFailed,
+      `preStepScript '${script}' exited ${exitCode ?? "non-zero"}.${tail}`,
+    ).withContext("pre-step hook execution");
+  },
+
+  eventLogLockTimeout(eventsPath: string, timeoutMs: number): CrewError {
+    return new CrewError(
+      ErrorCode.EventLogLockTimeout,
+      `Event log lock timeout for ${eventsPath}: could not acquire lock within ${timeoutMs}ms`,
+    ).withContext("event-log append");
+  },
+
+  depthLimitExceeded(depth: number, kind = "pipeline"): CrewError {
+    return new CrewError(
+      ErrorCode.DepthLimitExceeded,
+      `${kind[0].toUpperCase() + kind.slice(1)} recursion depth limit exceeded (${depth}). Possible circular dependency.`,
+    ).withContext(`${kind} execution`);
+  },
+
+  runStale(reason: string, heartbeatAgeSeconds?: number): CrewError {
+    const age = heartbeatAgeSeconds !== undefined ? ` Last heartbeat was ${heartbeatAgeSeconds}s ago.` : "";
+    return new CrewError(
+      ErrorCode.RunStale,
+      `Stale run reconciled (reason=${reason}).${age} The worker stopped heartbeating and was treated as dead/zombie.`,
+    ).withContext("stale-run reconciliation");
+  },
 } as const;

package/src/extension/context-status-injection.ts

@@ -0,0 +1,143 @@
+/**
+ * context-status-injection.ts — Ambient crew-status injection (GAP-2).
+ *
+ * Registers a `context` event handler that keeps the parent agent continuously
+ * aware of in-flight crew runs. Without this, the agent "forgets" about active
+ * runs between turns unless it explicitly calls the `team` tool.
+ *
+ * ## How it works
+ *
+ * Pi's `context` event fires before EVERY LLM call (see Pi source
+ * `extensions/runner.ts:emitContext`). The handler receives the full messages
+ * array and may return a modified copy. Critically, the returned messages are
+ * used ONLY for that single LLM call (`agent-loop.ts:283-289` feeds the result
+ * straight into `convertToLlm` for the request) — they do NOT mutate the
+ * agent's persistent `state.messages`. So injection is transient per-call:
+ *   - No accumulation across turns (the note never enters history).
+ *   - No need to dedup against prior injections.
+ *   - No risk of corrupting the conversation transcript.
+ *
+ * The injected note is a compact 1–4 line ambient status, inserted BEFORE the
+ * last message so the last message remains the active turn driver (preserves
+ * the user/assistant/tool alternation the LLMs expect).
+ *
+ * ## Safety
+ *
+ * - No-op when zero runs are in-flight (returns undefined → Pi uses original
+ *   messages unchanged). Normal single-agent operation is completely unaffected.
+ * - `emitContext` already wraps handlers in try/catch and emits errors instead
+ *   of crashing the loop (Pi `runner.ts:933`), so a throw here can't break the
+ *   agent — but we also guard defensively.
+ * - Opt-out: `runtime.reliability.ambientStatusInjection: false` in config.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { Message } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ContextEvent } from "@earendil-works/pi-coding-agent";
+import { collectInFlightRuns } from "./registration/compaction-guard.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+
+/** Sentinel that marks an injected ambient-status user message. */
+export const AMBIENT_STATUS_SENTINEL = "[pi-crew ambient status";
+
+/** Cap the number of runs listed inline to keep the note compact. */
+const MAX_INLINE_RUNS = 3;
+/** Truncate long goals so one run can't dominate the context window. */
+const MAX_GOAL_LEN = 80;
+
+/**
+ * Build a compact, human+LLM-readable ambient status string for the given
+ * in-flight runs. Returns "" for an empty list (caller treats as no-op).
+ *
+ * Exported for unit testing.
+ */
+export function formatAmbientStatus(runs: TeamRunManifest[]): string {
+	if (runs.length === 0) return "";
+	const truncate = (s: string, n: number): string =>
+		s.length > n ? `${s.slice(0, n - 1)}…` : s;
+	const lines: string[] = [
+		`${AMBIENT_STATUS_SENTINEL} — environmental context, not a user request]`,
+		`${runs.length} pi-crew run${runs.length === 1 ? "" : "s"} in flight:`,
+	];
+	const shown = runs.slice(0, MAX_INLINE_RUNS);
+	for (const run of shown) {
+		const wf = run.workflow ? `, ${run.workflow}` : "";
+		lines.push(`• ${run.runId} (${run.status}, ${run.team}${wf}): ${truncate(run.goal ?? "(no goal)", MAX_GOAL_LEN)}`);
+	}
+	if (runs.length > MAX_INLINE_RUNS) {
+		lines.push(`• …and ${runs.length - MAX_INLINE_RUNS} more`);
+	}
+	lines.push("Inspect/join via the `team` tool: action=\"status\" (list), action=\"wait\" (join running), action=\"summary\"/action=\"get\" (results).");
+	return lines.join("\n");
+}
+
+/**
+ * Construct a user-role AgentMessage carrying the ambient status. Uses the
+ * `user` role (the Message union has no `system` role — the system prompt is a
+ * separate field). The sentinel prefix signals to the model that this is
+ * environmental information, not a typed user instruction.
+ *
+ * Exported for unit testing.
+ */
+export function buildStatusMessage(runs: TeamRunManifest[]): Message {
+	return {
+		role: "user",
+		content: [{ type: "text", text: formatAmbientStatus(runs) }],
+		timestamp: Date.now(),
+	};
+}
+
+/** Result type for the `context` event handler (mirrors Pi's ContextEventResult,
+ * which isn't re-exported from the coding-agent package entry). */
+export interface AmbientContextResult {
+	messages?: AgentMessage[];
+}
+
+/**
+ * Core handler logic, separated from the Pi registration so it is trivially
+ * unit-testable without a live ExtensionAPI.
+ *
+ * Returns `{messages}` with the ambient status inserted before the last
+ * message, or `undefined` to leave the context untouched (no in-flight runs).
+ *
+ * Exported for unit testing.
+ */
+export function handleContextEvent(event: ContextEvent, cwd: string): AmbientContextResult | undefined {
+	let runs: TeamRunManifest[] = [];
+	try {
+		runs = collectInFlightRuns(cwd);
+	} catch {
+		// State read failure → don't inject, don't crash. Pi catches handler
+		// errors anyway, but we avoid noisy error emission for a best-effort
+		// awareness feature.
+		return undefined;
+	}
+	if (runs.length === 0) return undefined;
+
+	const messages = [...event.messages];
+	const statusMsg = buildStatusMessage(runs);
+	// Insert BEFORE the last message so the genuine last message (the current
+	// turn driver — user prompt or tool result) stays last. When there are 0–1
+	// messages, appending is the only sensible option.
+	const insertAt = messages.length > 1 ? messages.length - 1 : messages.length;
+	messages.splice(insertAt, 0, statusMsg as unknown as AgentMessage);
+	return { messages };
+}
+
+/**
+ * Register the ambient-status `context` event handler. Reads the project cwd
+ * from the session context on each call (crew state is per-project).
+ *
+ * Pass `enabled: false` (from `runtime.reliability.ambientStatusInjection`) to
+ * disable the feature without unwiring the handler.
+ */
+export function registerContextStatusInjection(
+	pi: ExtensionAPI,
+	opts: { enabled?: boolean } = {},
+): void {
+	if (opts.enabled === false) return;
+	pi.on("context", (event: ContextEvent): AmbientContextResult | undefined => {
+		const cwd = typeof process.cwd === "function" ? process.cwd() : ".";
+		return handleContextEvent(event, cwd);
+	});
+}

package/src/extension/knowledge-injection.ts

@@ -29,17 +29,45 @@ export function knowledgePath(cwd: string): string {
 export function readKnowledge(cwd: string): string {
 	try {
 		const p = knowledgePath(cwd);
-		if (!fs.existsSync(p)) return "";
+		const stat = tryStat(p);
+		if (!stat) {
+			knowledgeCache.delete(p);
+			return "";
+		}
+		// P5 (Round 15): mtime+size cache. readKnowledge fires on every agent
+		// start (main session + every worker), re-reading the file each time.
+		// For a run with N workers this is N redundant readFileSync of the same
+		// file. Cache by (mtimeMs, size) and only re-read when the file changes.
+		const cacheKey = `${stat.mtimeMs}:${stat.size}`;
+		const cached = knowledgeCache.get(p);
+		if (cached && cached.key === cacheKey) return cached.content;
 		let content = fs.readFileSync(p, "utf8").trim();
 		if (content.length > MAX_KNOWLEDGE_BYTES) {
 			content = `${content.slice(0, MAX_KNOWLEDGE_BYTES)}\n\n<!-- knowledge.md truncated at ${MAX_KNOWLEDGE_BYTES} bytes -->`;
 		}
+		knowledgeCache.set(p, { key: cacheKey, content });
 		return content;
 	} catch {
 		return "";
 	}
 }
 
+/** Stat helper returning undefined on error (file missing, perms, etc.). */
+function tryStat(p: string): { mtimeMs: number; size: number } | undefined {
+	try {
+		const s = fs.statSync(p);
+		return { mtimeMs: s.mtimeMs, size: s.size };
+	} catch {
+		return undefined;
+	}
+}
+
+interface CachedKnowledge {
+	key: string;
+	content: string;
+}
+const knowledgeCache = new Map<string, CachedKnowledge>();
+
 /** Build the injected prompt fragment (empty if no knowledge). */
 export function buildKnowledgeFragment(cwd: string): string {
 	const content = readKnowledge(cwd);

package/src/extension/register.ts

@@ -113,6 +113,7 @@ import { registerCrewMessageRenderers } from "./message-renderers.ts";
 import { registerCrewInputRouter } from "./crew-input-router.ts";
 import { registerCrewAutocomplete } from "./crew-autocomplete.ts";
 import { registerCrewShortcuts } from "./crew-shortcuts.ts";
+import { registerContextStatusInjection } from "./context-status-injection.ts";
 import { registerTeamTool } from "./registration/team-tool.ts";
 import { handleTeamTool } from "./team-tool.ts";
 import { persistScheduledJobUpdate } from "./team-tool/handle-schedule.ts";
@@ -2065,4 +2066,13 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	// (The crew autocomplete provider is registered from session_start once
 	// a UI context is available — see the session_start handler below.)
 	registerCrewShortcuts(pi);
+
+	// GAP-2 (Round 11): ambient crew-status injection. Registers a `context`
+	// event handler that appends a compact in-flight-runs note to the agent
+	// context on every LLM call, so the agent never "forgets" active runs.
+	// Transient per-call (does not pollute history), and a no-op when no runs
+	// are in-flight. Toggle via runtime.reliability.ambientStatusInjection.
+	registerContextStatusInjection(pi, {
+		enabled: loadConfig(process.cwd()).config.reliability?.ambientStatusInjection !== false,
+	});
 }

package/src/runtime/pipeline-runner.ts

@@ -3,6 +3,7 @@ import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.
 import type { TeamConfig } from "../teams/team-config.ts";
 import type { AgentConfig } from "../agents/agent-config.ts";
 import { appendEventAsync } from "../state/event-log.ts";
+import { errors } from "../errors.ts";
 import { mapConcurrent } from "./parallel-utils.ts";
 
 /**
@@ -242,7 +243,8 @@ export class PipelineRunner {
 	): Promise<unknown[]> {
 		// CRITICAL-6: Prevent stack overflow from deep recursion
 		if (depth > 50) {
-			throw new Error(`Pipeline recursion depth limit exceeded (${depth}). Possible circular stage dependency.`);
+			// E1 (Round 15): structured CrewError (E011) with help hint.
+			throw errors.depthLimitExceeded(depth, "pipeline");
 		}
 
 		const fanOut = stage.fanOut ?? true;

package/src/runtime/stale-reconciler.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { errors } from "../errors.ts";
 import { recordFromTask, upsertCrewAgent } from "./crew-agent-records.ts";
 import { checkProcessLiveness } from "./process-status.ts";
 import { saveRunManifest } from "../state/state-store.ts";
@@ -272,6 +273,23 @@ function getRunningTaskStaleness(
 /**
  * Repair a stale run by marking it as failed and cancelling running tasks.
  */
+/**
+ * E3/E1 (Round 15): Build a human-actionable error string for a stale-reconciled
+ * task. Explains WHY the run was marked stale (the detected reason) and gives
+ * concrete remediation, instead of the bare 'Stale run reconciled: <reason>'.
+ * Now returns a structured CrewError (E012) so callers also get a machine-
+ * readable code + help hint; `.message` carries the same rich text as before.
+ */
+function buildStaleReconcileError(task: TeamTaskState, reason: string): Error {
+	const heartbeatAgeSeconds = task.heartbeat?.lastSeenAt ? Math.round((Date.now() - new Date(task.heartbeat.lastSeenAt).getTime()) / 1000) : undefined;
+	return errors.runStale(reason, heartbeatAgeSeconds);
+}
+
+/** @deprecated use buildStaleReconcileError (returns a structured CrewError). Kept for any external callers. */
+function formatStaleReconcileError(task: TeamTaskState, reason: string): string {
+	return buildStaleReconcileError(task, reason).message;
+}
+
 function repairStaleRun(
 	manifest: TeamRunManifest,
 	tasks: TeamTaskState[],
@@ -288,7 +306,8 @@ function repairStaleRun(
 				...task,
 				status: "cancelled" as const,
 				finishedAt: now,
-				error: `Stale run reconciled: ${reason}`,
+				// E3/E1 (Round 15): structured CrewError (E012) with code + help hint.
+				error: buildStaleReconcileError(task, reason).message,
 			};
 		}
 		return task;

package/src/runtime/task-runner.ts

@@ -11,6 +11,7 @@ import type {
 	VerificationEvidence,
 } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { errors } from "../errors.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
 import { appendEventAsync, appendEventFireAndForget } from "../state/event-log.ts";
 import { saveRunManifest } from "../state/state-store.ts";
@@ -288,7 +289,10 @@ export async function runTeamTask(
 				});
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
-				throw new Error(`preStepScript failed: ${input.step.preStepScript}: ${msg}`);
+				const exitCode = (err as NodeJS.ErrnoException & { status?: number }).status;
+				// E1 (Round 15): structured CrewError with code E009 + help hint,
+				// instead of a raw Error. Surfaces the script path, exit code, and stderr.
+				throw errors.preStepFailed(input.step.preStepScript, exitCode, msg);
 			}
 		}
 
@@ -383,6 +387,7 @@ export async function runTeamTask(
 			let lastAgentRecordPersistedAt = 0;
 			let lastHeartbeatPersistedAt = 0;
 			let lastRunProgressPersistedAt = 0;
+			let lastTaskProgressPersistedAt = 0;
 			let lastRunProgressSummary: ProgressEventSummary | undefined;
 			const persistHeartbeat = (force = false): void => {
 				const now = Date.now();
@@ -573,26 +578,23 @@ export async function runTeamTask(
 								const eventLine = typeof event === "object" && !Array.isArray(event) ? JSON.stringify(event) : String(event);
 								fs.appendFileSync(bgLogPath, `${eventLine}\n`);
 							}
-							// Apply agentProgress update first, then persist, then update in-memory array.
-							// This ensures disk state is always >= in-memory state, preventing
-							// fresher in-memory state from being lost on crash.
-							tasks = persistSingleTaskUpdate(manifest, tasks, {
-								...task,
-								agentProgress: applyAgentProgressEvent(
-									task.agentProgress ?? emptyCrewAgentProgress(),
-									event,
-									task.startedAt,
-								),
-							});
-							task = {
-								...task,
-								agentProgress: applyAgentProgressEvent(
-									task.agentProgress ?? emptyCrewAgentProgress(),
-									event,
-									task.startedAt,
-								),
-							};
+							// Always keep in-memory agentProgress fresh (cheap) so the UI/events see
+							// the latest progress, but THROTTLE the disk persist. Previously this
+							// did a full locked read-parse-write of tasks.json on EVERY child JSON
+							// event — a 200-event task produced 200 such cycles (Round 15 P1).
+							// Final state is force-flushed on task completion (persistHeartbeat(true)).
+							const nextProgress = applyAgentProgressEvent(
+								task.agentProgress ?? emptyCrewAgentProgress(),
+								event,
+								task.startedAt,
+							);
+							task = { ...task, agentProgress: nextProgress };
 							tasks = updateTask(tasks, task);
+							const progressNow = Date.now();
+							if (progressNow - lastTaskProgressPersistedAt >= 500) {
+								tasks = persistSingleTaskUpdate(manifest, tasks, task);
+								lastTaskProgressPersistedAt = progressNow;
+							}
 							// Bridge event to UI event bus for near-instant updates
 							const bridgeEvent = bridgeEventFromJsonEvent(
 								manifest.runId,
@@ -701,6 +703,15 @@ export async function runTeamTask(
 						? childResult.stderr ||
 							`Child Pi exited with ${childResult.exitCode}`
 						: undefined);
+				// E1/E7 (Round 15): when the child timed out, surface a structured
+				// CrewError (E007) so users get a code + actionable help hint instead
+				// of a bare 'no new output for N ms'. We keep .message as the task error.
+				if (childResult.exitStatus?.timedOut) {
+					error = errors.childTimeout({
+						taskId: task.id,
+						stderr: childResult.stderr,
+					}).message;
+				}
 				persistHeartbeat(true);
 				persistChildProgress({ type: "attempt_finished" }, true);
 				const attempt: ModelAttemptSummary = {
@@ -724,6 +735,16 @@ export async function runTeamTask(
 				if (!nextModel || !isRetryableModelFailure(error)) break;
 				logs.push(formatModelAttemptNote(attempt, nextModel), "");
 			}
+			// E2 (Round 15): when the fallback chain was used and STILL failed, surface
+			// that explicitly. Without this the task error only shows the last
+			// attempt's raw failure, so users can't tell whether to fix an API key,
+			// upgrade a plan, or change the model config. Include the chain tried +
+			// the final reason.
+			if (error && modelAttempts.length > 1) {
+				// E2/E1 (Round 15): structured CrewError (E008). Build via the factory so
+				// the error carries a code + help hint; keep its .message as the task error.
+				error = errors.modelExhausted(modelAttempts.map((a) => a.model), error).message;
+			}
 			// NEW-8 fix: register all attempt transcripts as artifacts, not just the used one.
 			// Earlier failed attempts' transcripts exist on disk but were invisible to the artifact system.
 			const successfulAttemptIndex = modelAttempts.findIndex(

package/src/runtime/workspace-tree.ts

@@ -252,7 +252,7 @@ function applyLineCap(
 	return { lines: kept, elided: removable.length };
 }
 
-// ── Public API ─────────────────────────────────────────────────────────
+// ── Public API ────────────────────────────────────────────────────────
 
 const emptyResult = (rootPath: string): WorkspaceTree => ({
 	rootPath,
@@ -261,11 +261,35 @@ const emptyResult = (rootPath: string): WorkspaceTree => ({
 	totalLines: 0,
 });
 
+/**
+ * Per-cwd TTL cache for the rendered workspace tree. Workers in the same run
+ * share a cwd, so the recursive walk was previously repeated once per task
+ * (Round 15 P4). The tree is informational context for the worker; short-lived
+ * staleness is acceptable, so a 30s TTL is safe and keeps prompts fresh during
+ * long active runs while eliminating redundant walks.
+ */
+const TREE_CACHE_TTL_MS = 30_000;
+interface CachedTree {
+	tree: WorkspaceTree;
+	expiresAt: number;
+}
+const treeCache = new Map<string, CachedTree>();
+
+function treeCacheKey(cwd: string, options?: WorkspaceTreeOptions): string {
+	// Cache is keyed on the inputs that affect the walk output.
+	return `${path.resolve(cwd)}|${options?.maxDepth ?? ""}|${options?.dirLimit ?? ""}|${options?.lineCap ?? ""}`;
+}
+
 export async function buildWorkspaceTree(
 	cwd: string,
 	options?: WorkspaceTreeOptions,
 ): Promise<WorkspaceTree> {
 	const rootPath = path.resolve(cwd);
+	const cacheKey = treeCacheKey(cwd, options);
+	const cached = treeCache.get(cacheKey);
+	if (cached && cached.expiresAt > Date.now()) {
+		return cached.tree;
+	}
 	try {
 		const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
 		const dirLimit = options?.dirLimit ?? DEFAULT_DIR_LIMIT;
@@ -286,12 +310,14 @@ export async function buildWorkspaceTree(
 		const { lines: capped, elided } = applyLineCap(lines, lineCap);
 		const rendered = capped.map((l) => l.text).join("\n");
 
-		return {
+		const result: WorkspaceTree = {
 			rootPath,
 			rendered,
 			truncated: dirTruncated || elided > 0,
 			totalLines: capped.length,
 		};
+		treeCache.set(cacheKey, { tree: result, expiresAt: Date.now() + TREE_CACHE_TTL_MS });
+		return result;
 	} catch {
 		return emptyResult(rootPath);
 	}

package/src/state/event-log.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { DEFAULT_EVENT_LOG } from "../config/defaults.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
+import { errors } from "../errors.ts";
 import { emitFromTeamEvent } from "../ui/run-event-bus.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { readJsonlSince, type IncrementalReadState } from "../utils/incremental-reader.ts";
@@ -105,9 +106,9 @@ export function withEventLogLockSync<T>(eventsPath: string, fn: () => T): T {
 				// SECURITY (HIGH #2 fix): Throw instead of continuing without lock.
 				// Previously this logged and broke out of the loop, executing the
 				// operation without lock protection. Now we throw so callers can retry.
-				throw new Error(
-					`Event log lock timeout for ${eventsPath}: could not acquire lock within ${timeout}ms`,
-				);
+				// E1 (Round 15): structured CrewError (E010) with help hint so users know
+				// to check for orphaned .lock dirs / stale processes.
+				throw errors.eventLogLockTimeout(eventsPath, timeout);
 			}
 			// Stale detection: if the owning process is dead, remove the stale lock.
 			try {

package/src/state/state-store.ts

@@ -17,6 +17,37 @@ import type { WorkflowConfig } from "../workflows/workflow-config.ts";
 import { toPiSessionId } from "../utils/session-utils.ts";
 import { HealthStore } from "./health-store.ts";
 
+/**
+ * stat() the manifest with a brief retry on Windows for the AV-scan window.
+ *
+ * On the GitHub Actions windows-latest runner, Windows Defender real-time
+ * scanning can make a freshly-written manifest.json briefly invisible to
+ * statSync (ENOENT) even though the write succeeded and the file is on disk.
+ * loadRunManifestById is called right after createRunManifest in tests and in
+ * production (e.g. refreshPersistedSubagentRecord), so without a retry the
+ * caller sees a phantom "missing" run.
+ *
+ * On non-Windows, ENOENT means the file genuinely doesn't exist — passthrough
+ * (throw immediately) with no retry. On Windows, ENOENT/EPERM/EBUSY/EAGAIN get
+ * a handful of short retries (~30ms worst case) before giving up and throwing
+ * so the caller's catch returns undefined as before.
+ */
+function statManifestWithWindowsRetry(manifestPath: string): fs.Stats {
+	if (process.platform !== "win32") return fs.statSync(manifestPath);
+	const retryable = new Set(["ENOENT", "EPERM", "EBUSY", "EAGAIN"]);
+	for (let attempt = 0; attempt < 5; attempt++) {
+		try {
+			return fs.statSync(manifestPath);
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (!retryable.has(code ?? "")) throw error;
+			const end = Date.now() + Math.min(8, 1 * 2 ** attempt);
+			while (Date.now() < end) { /* brief spin to ride out the AV scan window */ }
+		}
+	}
+	return fs.statSync(manifestPath); // last attempt — let caller's catch handle ENOENT
+}
+
 export interface RunPaths {
 	runId: string;
 	stateRoot: string;
@@ -506,7 +537,7 @@ export function loadRunManifestById(cwd: string, runId: string): { manifest: Tea
 
 	let manifestStat: fs.Stats;
 	try {
-		manifestStat = fs.statSync(manifestPath);
+		manifestStat = statManifestWithWindowsRetry(manifestPath);
 	} catch {
 		return undefined;
 	}