pi-crew 0.7.3 → 0.7.5

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # 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.
+
+### Features (UX)
+
+- **Editor autocomplete provider** — registered via Pi's `addAutocompleteProvider`. As you type `crew <prefix>` or `team <prefix>` at the start of the input line, Pi's popup now suggests natural-language crew phrases and shows the slash command they map to (e.g. `crew status → /team-status`, `team dashboard → /team-dashboard`). `crew` and `team` are interchangeable keywords, driven by a single `CREW_PHRASES` source of truth shared with the input router.
+- **Keyboard shortcut** — `alt+s` opens the pi-crew settings overlay (config + theme picker). `openTeamSettingsOverlay(ctx)` was extracted from the settings command handler so the shortcut reuses the exact same overlay (DRY). `alt+s` was chosen to avoid Pi's built-in keymap (Pi only binds `alt+v` and `alt+arrow`/`alt+enter` among alt+letter keys).
+
+### Bug Fixes
+
+- **createRunManifest swallowed the real write error** — `saveManifestAndTasksAtomicSync` returns `error: String(err)`, but `createRunManifest` passed it to `errors.fileWrite` as a fake `ErrnoException`; `.code` was `undefined` → every write failure showed `": unknown"`, hiding the actual cause. Now surfaces the real error string in the thrown context, so CI logs and production callers see *why* the write failed.
+- **`atomicWriteFile` Windows path-form correctness** — must NEVER rewrite the write target to a different realpath form. Callers build `filePath` via `canonicalizePath` (`realpathSync.native`) and later stat/read it at that exact path; rewriting it (even to a "canonical" form) made the file land on a divergent path that Windows treated as separate → `existsSync`/`readFileSync` failed after a "successful" write. `canonicalize()` is now used ONLY as an mkdir fallback on Windows `EPERM`, never to change the write target.
+
+### Tests / CI
+
+- **Cap `--test-concurrency` at 2 on all CI platforms.** After the Round 13/14 test additions pushed every GitHub Actions runner past its filesystem-contention threshold, `state-store.test.ts` write-then-stat tests flaked on Windows (Windows Defender locks fresh temp files → rename `EPERM` exhausts atomic-write retries) and macOS (`/var/folders` tmp contention under load). `scripts/test-runner.mjs` now clamps the CI-requested concurrency (`4 → 2`) so the FS has room to flush; local dev is unaffected. Green on all 3 platforms (run 27556451997). 8× concurrent local runs reproduced nothing — pure CI infra contention, not a deterministic bug.
+- +20 tests for the new features (crew-autocomplete: 16, crew-shortcuts: 4).
+
 ## [0.7.3] — Reliability hardening + UX quick wins (2026-06-15)
 
 This release fixes 4 critical data-loss bugs found by the Round 12 reliability audit and adds three UX quick wins from the Round 13 UX research (+125 tests from the Round 14 coverage sprint).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.7.3",
+  "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/crew-autocomplete.ts

@@ -0,0 +1,139 @@
+/**
+ * Crew editor autocomplete provider (Round 13 UX).
+ *
+ * Wraps Pi's built-in autocomplete provider and adds natural-language crew
+ * phrase completion: when the user types `crew <prefix>` or `team <prefix>`
+ * at the start of the input line, we suggest the matching phrases (e.g.
+ * "crew status → /team-status"). This teaches users the natural-language
+ * phrases that the input router (crew-input-router.ts) will rewrite on
+ * submit — so they discover the feature without reading docs.
+ *
+ * For any non-crew input we delegate to the wrapped (`current`) provider, so
+ * slash-command, file (`@`), and command-argument completion all keep working
+ * unchanged.
+ */
+import type {
+	AutocompleteItem,
+	AutocompleteProvider,
+	AutocompleteSuggestions,
+} from "@earendil-works/pi-tui";
+import { CREW_PHRASES } from "./crew-input-router.ts";
+
+/** Max phrases to suggest. */
+const MAX_PHRASES = 12;
+
+/**
+ * If the text before the cursor is a crew-natural-language trigger, return the
+ * query word (the partial keyword after `crew `/`team `), or `undefined` when
+ * it is not a crew trigger.
+ *
+ * Triggers look like `crew ` or `team ` optionally followed by a partial word
+ * made of word characters, anchored at the start of the line.
+ */
+function extractCrewQuery(textBeforeCursor: string): string | undefined {
+	// Anchor at start of line; require the `crew|team` keyword + whitespace,
+	// then an optional partial word. We do NOT trigger mid-word on the keyword
+	// itself (e.g. "cre" alone is not a trigger) — the keyword must be complete.
+	const match = textBeforeCursor.match(/^(?:crew|team)\s+([\w-]*)$/i);
+	return match?.[1];
+}
+
+/** Filter the shared phrase list by a partial keyword prefix. */
+export function suggestCrewPhrases(query: string): AutocompleteItem[] {
+	const q = query.toLowerCase();
+	// Phrases are keyed by their keyword after "crew "/"team " (or the bare
+	// word for "teams"). Build a lookup keyword per phrase.
+	const seen = new Set<string>();
+	const items: AutocompleteItem[] = [];
+	for (const entry of CREW_PHRASES) {
+		// Derive the autocomplete keyword: for "crew status" → "status";
+		// for "teams" → "teams".
+		const parts = entry.phrase.split(/\s+/);
+		const keyword = parts.length > 1 ? parts.slice(1).join(" ") : entry.phrase;
+		if (seen.has(entry.phrase)) continue;
+		if (q && !keyword.toLowerCase().startsWith(q)) continue;
+		seen.add(entry.phrase);
+		items.push({
+			value: entry.phrase,
+			label: entry.phrase,
+			description: `→ ${entry.command}`,
+		});
+		if (items.length >= MAX_PHRASES) break;
+	}
+	return items;
+}
+
+/**
+ * Create a crew autocomplete provider that wraps `current`. When the input is
+ * a crew natural-language trigger, returns phrase suggestions; otherwise
+ * delegates to `current`.
+ */
+export function createCrewAutocompleteProvider(
+	current: AutocompleteProvider,
+): AutocompleteProvider {
+	return {
+		async getSuggestions(
+			lines: string[],
+			cursorLine: number,
+			cursorCol: number,
+			options: { signal: AbortSignal; force?: boolean },
+		): Promise<AutocompleteSuggestions | null> {
+			// Only trigger on the first line (Pi's main input is single-line;
+			// multiline editors are out of scope and would surprise the user).
+			if (cursorLine === 0) {
+				const currentLine = lines[cursorLine] ?? "";
+				const before = currentLine.slice(0, cursorCol);
+				const query = extractCrewQuery(before);
+				if (query !== undefined) {
+					const items = suggestCrewPhrases(query);
+					if (items.length > 0) {
+						// prefix = the full text to replace (e.g. "crew st").
+						// The default applyCompletion replaces the trailing
+						// `prefix`-length chars with item.value.
+						return { items, prefix: before };
+					}
+					// Triggered but no matches — return empty rather than
+					// falling through to file/command completion, so the user
+					// doesn't get a confusing file list while typing a phrase.
+					return { items: [], prefix: before };
+				}
+			}
+			return current.getSuggestions(lines, cursorLine, cursorCol, options);
+		},
+
+		applyCompletion(
+			lines: string[],
+			cursorLine: number,
+			cursorCol: number,
+			item: AutocompleteItem,
+			prefix: string,
+		): { lines: string[]; cursorLine: number; cursorCol: number } {
+			// Delegate to the wrapped provider. For a non-slash, non-@ prefix
+			// the default applyCompletion replaces the trailing `prefix`-length
+			// chars with item.value — which is exactly the full phrase. This
+			// matches our prefix contract (prefix = full text to cursor).
+			return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+		},
+
+		shouldTriggerFileCompletion(
+			lines: string[],
+			cursorLine: number,
+			cursorCol: number,
+		): boolean {
+			// Suppress file-completion trigger inside a crew phrase so the
+			// editor doesn't pop a file list over our phrase suggestions.
+			if (cursorLine === 0) {
+				const before = (lines[cursorLine] ?? "").slice(0, cursorCol);
+				if (extractCrewQuery(before) !== undefined) return false;
+			}
+			return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+		},
+	};
+}
+
+/** Register the crew autocomplete provider on a Pi UI context. Safe to call once. */
+export function registerCrewAutocomplete(
+	ctx: { ui?: { addAutocompleteProvider?: (factory: (current: AutocompleteProvider) => AutocompleteProvider) => void } },
+): void {
+	ctx.ui?.addAutocompleteProvider?.((current) => createCrewAutocompleteProvider(current));
+}

package/src/extension/crew-input-router.ts

@@ -12,17 +12,47 @@
  */
 import type { InputEvent, InputEventResult } from "@earendil-works/pi-coding-agent";
 
-/** Rules: phrase prefix (lowercased) → slash-command rewrite. */
-const ROUTING_RULES: ReadonlyArray<{ match: RegExp; command: string; needsArg?: boolean }> = [
-	// Inspection — no runId needed (lists all runs).
-	{ match: /^(crew|team)\s+status\b/i, command: "/team-status" },
-	{ match: /^(crew|team)\s+list\b/i, command: "/team-status" },
-	{ match: /^(crew|team)\s+(dashboard|board|panel)\b/i, command: "/team-dashboard" },
-	{ match: /^(crew|team)\s+(help|commands)\b/i, command: "/team-help" },
-	{ match: /^teams\b/i, command: "/teams" },
-	{ match: /^(crew|team)\s+(doctor|diagnos\w*)/i, command: "/team-doctor" },
+/**
+ * Natural-language crew phrases → slash-command mapping.
+ *
+ * Single source of truth shared by:
+ *  - the `input`-event router (rewrites submitted text), and
+ *  - the editor autocomplete provider (suggests phrases as you type).
+ *
+ * Each entry maps a phrase (what the user types) to a slash command.
+ * The router matches when submitted text STARTS WITH a phrase (word boundary);
+ * the autocomplete matches when the line starts with `crew `/`team ` and the
+ * partial word is a prefix of a phrase's keyword.
+ */
+export const CREW_PHRASES: ReadonlyArray<{ phrase: string; command: string }> = [
+	{ phrase: "crew status", command: "/team-status" },
+	{ phrase: "crew list", command: "/team-status" },
+	{ phrase: "crew dashboard", command: "/team-dashboard" },
+	{ phrase: "crew board", command: "/team-dashboard" },
+	{ phrase: "crew panel", command: "/team-dashboard" },
+	{ phrase: "crew help", command: "/team-help" },
+	{ phrase: "crew commands", command: "/team-help" },
+	{ phrase: "crew doctor", command: "/team-doctor" },
+	{ phrase: "crew diagnose", command: "/team-doctor" },
+	{ phrase: "teams", command: "/teams" },
 ];
 
+/**
+ * Build a case-insensitive anchored regex from a phrase. The leading `crew `
+ * keyword is treated as interchangeable with `team ` (so "crew status" matches
+ * both "crew status" and "team status"). Bare phrases like "teams" match
+ * verbatim.
+ */
+function phraseToRegex(phrase: string): RegExp {
+	const kw = phrase.match(/^(crew|team)\s+(.*)$/i);
+	if (kw) {
+		const rest = kw[2].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		return new RegExp(`^(?:crew|team)\\s+${rest}\\b`, "i");
+	}
+	const escaped = phrase.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return new RegExp(`^${escaped}\\b`, "i");
+}
+
 /**
  * Try to rewrite a natural-language crew phrase into a slash command.
  * Returns the rewritten command string, or `null` if no rule matches.
@@ -35,12 +65,12 @@ export function rewriteCrewInput(text: string): string | null {
 	// Never transform explicit slash commands or inputs that don't start with
 	// a crew/team keyword phrase.
 	if (trimmed.startsWith("/")) return null;
-	for (const rule of ROUTING_RULES) {
-		const match = trimmed.match(rule.match);
+	for (const entry of CREW_PHRASES) {
+		const match = trimmed.match(phraseToRegex(entry.phrase));
 		if (!match) continue;
 		// Carry any remaining args after the matched phrase forward.
 		const rest = trimmed.slice(match[0].length).trim();
-		return rest ? `${rule.command} ${rest}` : rule.command;
+		return rest ? `${entry.command} ${rest}` : entry.command;
 	}
 	return null;
 }

package/src/extension/crew-shortcuts.ts

@@ -0,0 +1,56 @@
+/**
+ * Crew keyboard shortcuts (Round 13 UX).
+ *
+ * Registers a small set of keyboard shortcuts for fast access to the most
+ * useful pi-crew overlays. Keys are chosen to avoid collisions with Pi's
+ * built-in keymap (see analysis of pi-tui core/keybindings defaults):
+ *
+ *   alt+s → open the pi-crew settings overlay (config + theme picker)
+ *
+ * `alt+<letter>` combos are safe: Pi only binds `alt+v`, `alt+enter`, and the
+ * alt+arrow navigation keys. `alt+s` is mnemonic (settings) and free.
+ *
+ * Shortcuts are guarded by `hasUI` so they never fire in print/RPC mode, and
+ * by the optional `registerShortcut` API so older Pi versions degrade
+ * gracefully (no-op).
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { KeyId } from "@earendil-works/pi-tui";
+
+type ShortcutHandler = (ctx: ExtensionContext) => Promise<void> | void;
+
+interface ShortcutRegistration {
+	/** Pi KeyId, e.g. "alt+s". */
+	key: KeyId;
+	description: string;
+	handler: ShortcutHandler;
+}
+
+const CREW_SHORTCUTS: ReadonlyArray<ShortcutRegistration> = [
+	{
+		key: "alt+s",
+		description: "pi-crew: open settings (config + theme picker)",
+		// Lazy-import the overlay so this module stays lightweight at load time
+		// (avoids pulling the full commands.ts dependency tree into every
+		// process that imports this module, e.g. the unit test).
+		handler: async (ctx) => {
+			const { openTeamSettingsOverlay } = await import("./registration/commands.ts");
+			await openTeamSettingsOverlay(ctx);
+		},
+	},
+];
+
+/**
+ * Register all crew keyboard shortcuts on a Pi instance. Safe to call once at
+ * extension load. No-ops when `registerShortcut` is unavailable (older Pi).
+ */
+export function registerCrewShortcuts(
+	pi: { registerShortcut?: (shortcut: KeyId, options: { description?: string; handler: ShortcutHandler }) => void },
+): void {
+	for (const sc of CREW_SHORTCUTS) {
+		pi.registerShortcut?.(sc.key, { description: sc.description, handler: sc.handler });
+	}
+}
+
+/** Exported for tests / introspection. */
+export const CREW_SHORTCUT_KEYS: readonly KeyId[] = CREW_SHORTCUTS.map((s) => s.key);

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

@@ -111,6 +111,9 @@ import {
 import { registerSubagentTools } from "./registration/subagent-tools.ts";
 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";
@@ -214,6 +217,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	let sessionGeneration = 0;
 	let rpcHandle: PiCrewRpcHandle | undefined;
 	let cleanedUp = false;
+	let crewAutocompleteRegistered = false;
 	let manifestCache = createManifestCache(process.cwd());
 	let runSnapshotCache = createRunSnapshotCache(process.cwd());
 	let cacheCwd = process.cwd();
@@ -1219,6 +1223,14 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		sessionGeneration++;
 		const ownerGeneration = sessionGeneration;
 		currentCtx = ctx;
+		// Round 13 UX: register the crew natural-language autocomplete provider
+		// once we have a UI context. Guarded so repeated session_start events
+		// don't stack wrappers (each wrapper delegates, but stacking wastes
+		// call depth).
+		if (!crewAutocompleteRegistered) {
+			crewAutocompleteRegistered = true;
+			registerCrewAutocomplete(ctx);
+		}
 		if (widgetState.interval) clearInterval(widgetState.interval);
 		widgetState.interval = undefined;
 		notifyActiveRuns(ctx);
@@ -2048,4 +2060,19 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	// interactive input that starts with a crew/team keyword phrase; never
 	// shadows explicit slash commands.
 	registerCrewInputRouter(pi);
+
+	// Round 13 UX: keyboard shortcuts. alt+s opens the settings overlay
+	// (config + theme picker). Keys chosen to avoid Pi's built-in keymap.
+	// (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/extension/registration/commands.ts

@@ -154,6 +154,72 @@ function teamCommandContext(ctx: ExtensionCommandContext): ExtensionCommandConte
 	return withSessionId(ctx);
 }
 
+/**
+ * Open the pi-crew settings overlay (config editor + theme picker).
+ *
+ * Extracted from the `team-settings` command so it is reusable from a
+ * keyboard shortcut. Takes the base `ExtensionContext` (the shortcut
+ * handler's context) — uses only `hasUI`, `cwd`, and `ui` fields, so both
+ * `ExtensionContext` and `ExtensionCommandContext` satisfy it.
+ */
+export async function openTeamSettingsOverlay(ctx: ExtensionContext): Promise<void> {
+	if (!ctx.hasUI) return;
+	const [{ updateConfig, parseConfig }, { asCrewTheme }, { createSettingsOverlay }] = await Promise.all([
+		import("../../config/config.ts"),
+		import("../../ui/theme-adapter.ts"),
+		import("../../ui/settings-overlay.ts"),
+	]);
+	const loaded = loadConfig(ctx.cwd);
+	const config = loaded.config as Record<string, unknown>;
+	await ctx.ui.custom<undefined>((_tui, _theme, _keybindings, done) => {
+		const theme = asCrewTheme(_theme);
+		const { overlay } = createSettingsOverlay(config, theme, (id: string, value: unknown) => {
+			try {
+				const patch: Record<string, unknown> = {};
+				const keys = id.split(".");
+				let target: Record<string, unknown> = patch;
+				for (let i = 0; i < keys.length - 1; i++) {
+					if (!target[keys[i]!] || typeof target[keys[i]!] !== "object") target[keys[i]!] = {};
+					target = target[keys[i]!] as Record<string, unknown>;
+				}
+				target[keys[keys.length - 1]!] = value;
+				if (value === undefined) { updateConfig({}, { unsetPaths: [id] }); }
+				else { updateConfig(parseConfig(patch)); }
+			} catch (error) {
+				ctx.ui.notify(`Failed to save: ${error instanceof Error ? error.message : String(error)}`, "error");
+			}
+		}, () => done(undefined), async (action: string, value: unknown) => {
+			// Action callbacks (Pi theme switch) write to a different store
+			// than pi-crew config (e.g. ~/.pi/agent/settings.json).
+			try {
+				if (action === "piTheme" && typeof value === "string") {
+					// Live theme switch: ctx.ui.setTheme() swaps the global theme,
+					// persists it to settings.json, and triggers a UI redraw — no
+					// restart needed. Falls back to file-write + restart hint if
+					// the live API is unavailable (e.g. non-TUI mode).
+					if (typeof ctx.ui.setTheme === "function") {
+						const res = ctx.ui.setTheme(value);
+						if (res.success) {
+							ctx.ui.notify(`Theme: ${value} (applied live)`, "info");
+						} else {
+							const { setPiTheme } = await import("../../ui/theme-discovery.ts");
+							setPiTheme(value);
+							ctx.ui.notify(`Theme saved as '${value}' but failed to apply: ${res.error ?? "unknown"}. Restart Pi.`, "warning");
+						}
+					} else {
+						const { setPiTheme } = await import("../../ui/theme-discovery.ts");
+						setPiTheme(value);
+						ctx.ui.notify(`Pi theme set to '${value}'. Restart Pi to apply.`, "info");
+					}
+				}
+			} catch (error) {
+				ctx.ui.notify(`Failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+			}
+		});
+		return overlay;
+	}, { overlay: true, overlayOptions: { width: "90%", maxHeight: "85%", anchor: "center" } });
+}
+
 async function handleHealthDashboardAction(ctx: ExtensionCommandContext, selection: RunDashboardSelection): Promise<void> {
 	const loaded = loadRunManifestById(ctx.cwd, selection.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 	if (!loaded) {
@@ -353,60 +419,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 	description: "View or update pi-crew settings: interactive UI or [list|get <key>|set <key> <value>|unset <key>|path|scope]",
 	handler: async (args: string, ctx: ExtensionCommandContext) => {
 		if (ctx.hasUI && !args.trim()) {
-			const [{ updateConfig, parseConfig }, { asCrewTheme }, { createSettingsOverlay }] = await Promise.all([
-				import("../../config/config.ts"),
-				import("../../ui/theme-adapter.ts"),
-				import("../../ui/settings-overlay.ts"),
-			]);
-			const loaded = loadConfig(ctx.cwd);
-			const config = loaded.config as Record<string, unknown>;
-			await ctx.ui.custom<undefined>((_tui, _theme, _keybindings, done) => {
-				const theme = asCrewTheme(_theme);
-				const { overlay } = createSettingsOverlay(config, theme, (id: string, value: unknown) => {
-					try {
-						const patch: Record<string, unknown> = {};
-						const keys = id.split(".");
-						let target: Record<string, unknown> = patch;
-						for (let i = 0; i < keys.length - 1; i++) {
-							if (!target[keys[i]!] || typeof target[keys[i]!] !== "object") target[keys[i]!] = {};
-							target = target[keys[i]!] as Record<string, unknown>;
-						}
-						target[keys[keys.length - 1]!] = value;
-						if (value === undefined) { updateConfig({}, { unsetPaths: [id] }); }
-						else { updateConfig(parseConfig(patch)); }
-					} catch (error) {
-						ctx.ui.notify(`Failed to save: ${error instanceof Error ? error.message : String(error)}`, "error");
-					}
-				}, () => done(undefined), async (action: string, value: unknown) => {
-					// Action callbacks (Pi theme switch) write to a different store
-					// than pi-crew config (e.g. ~/.pi/agent/settings.json).
-					try {
-						if (action === "piTheme" && typeof value === "string") {
-							// Live theme switch: ctx.ui.setTheme() swaps the global theme,
-							// persists it to settings.json, and triggers a UI redraw — no
-							// restart needed. Falls back to file-write + restart hint if
-							// the live API is unavailable (e.g. non-TUI mode).
-							if (typeof ctx.ui.setTheme === "function") {
-								const res = ctx.ui.setTheme(value);
-								if (res.success) {
-									ctx.ui.notify(`Theme: ${value} (applied live)`, "info");
-								} else {
-									const { setPiTheme } = await import("../../ui/theme-discovery.ts");
-									setPiTheme(value);
-									ctx.ui.notify(`Theme saved as '${value}' but failed to apply: ${res.error ?? "unknown"}. Restart Pi.`, "warning");
-								}
-							} else {
-								const { setPiTheme } = await import("../../ui/theme-discovery.ts");
-								setPiTheme(value);
-								ctx.ui.notify(`Pi theme set to '${value}'. Restart Pi to apply.`, "info");
-							}
-						}
-					} catch (error) {
-						ctx.ui.notify(`Failed: ${error instanceof Error ? error.message : String(error)}`, "error");
-					}
-				});
-				return overlay;
-			}, { overlay: true, overlayOptions: { width: "90%", maxHeight: "85%", anchor: "center" } });
+			await openTeamSettingsOverlay(ctx);
 			return;
 		}
 		const result = await handleTeamTool({ action: "settings", config: { args: args.trim() } }, teamCommandContext(ctx));

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/atomic-write.ts

@@ -284,31 +284,36 @@ export const __test__renameWithRetryAsync = renameWithRetryAsync;
 
 export function atomicWriteFile(filePath: string, content: string, expectedHash?: string): void {
 	if (!isSymlinkSafePath(filePath)) throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
-	// On Windows, resolve parent dir through realpathSync to handle short-name
-	// vs long-name path alias (e.g. RUNNER~1 vs runneradmin). Without this,
-	// mkdirSync may succeed but openSync fails with ENOENT because the OS
-	// sees the paths as different locations.
-	let dirPath = path.dirname(filePath);
-	if (process.platform === "win32") {
+	// On Windows the parent directory may be referenced via a short-name alias
+	// (e.g. RUNNER~1 vs runneradmin). mkdirSync on one form can succeed while
+	// openSync on another form fails with ENOENT. We therefore ensure the dir
+	// exists, trying the canonical (realpathSync.native) form as a fallback on
+	// EPERM.
+	//
+	// CRITICAL: we NEVER rewrite `filePath`. The caller (e.g. createRunManifest)
+	// builds filePath via canonicalizePath() (realpathSync.native) and will later
+	// stat/read it back at that exact path. If we rewrote filePath to a different
+	// realpath form here, the written file would land on a path that diverges
+	// from the caller's path — making existsSync/readFileSync(callerPath) fail
+	// with ENOENT even though the write "succeeded". Writing to the original
+	// filePath guarantees the caller can always find the file it just wrote.
+	const canonicalize = (p: string): string => {
 		try {
-			const realDir = fs.realpathSync(dirPath);
-			if (realDir !== dirPath) dirPath = realDir;
+			const r = fs.realpathSync.native(p);
+			return r.startsWith("\\\\?\\") ? r.slice(4) : r;
 		} catch {
-			// dirPath may not exist yet — mkdirSync will create it
+			try { return fs.realpathSync(p); } catch { return p; }
 		}
-		filePath = path.join(dirPath, path.basename(filePath));
-	}
+	};
+	const dirPath = path.dirname(filePath);
 	try {
 		fs.mkdirSync(dirPath, { recursive: true });
 	} catch (error) {
 		if (process.platform === "win32" && (error as NodeJS.ErrnoException).code === "EPERM") {
-			try {
-				const realDir = fs.realpathSync(dirPath);
-				if (realDir !== dirPath) {
-					fs.mkdirSync(realDir, { recursive: true });
-					dirPath = realDir;
-				}
-			} catch { /* ignore – will fail at write time with better error */ }
+			// mkdir hit a short/long-name alias wall — retry with the canonical
+		// form. The write itself still targets the original filePath below.
+			const realDir = canonicalize(dirPath);
+			if (realDir !== dirPath) fs.mkdirSync(realDir, { recursive: true });
 		} else {
 			throw error;
 		}

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;
@@ -213,8 +244,14 @@ export function createRunManifest(params: {
 	// throw to ensure manifest and tasks are always consistent.
 	const result = saveManifestAndTasksAtomicSync(manifest, tasks);
 	if (!result.manifestWritten || !result.tasksWritten) {
-		throw errors.fileWrite(paths.stateRoot, result.error as unknown as NodeJS.ErrnoException)
-			.withContext(`saveManifestAndTasksAtomicSync: manifestWritten=${result.manifestWritten}, tasksWritten=${result.tasksWritten}`);
+		// Surface the underlying error message (result.error is String(err) from
+		// saveManifestAndTasksAtomicSync). Passing it through errors.fileWrite as a
+		// fake ErrnoException loses the message (reads .code → undefined →
+		// "unknown"). Include it explicitly in the thrown message so CI logs and
+		// production callers can see WHY the write failed instead of ": unknown".
+		const cause = result.error ? `: ${result.error}` : "";
+		throw errors.fileWrite(paths.stateRoot, { code: "EWRITEFAIL" } as NodeJS.ErrnoException)
+			.withContext(`saveManifestAndTasksAtomicSync: manifestWritten=${result.manifestWritten}, tasksWritten=${result.tasksWritten}${cause}`);
 	}
 	appendEvent(paths.eventsPath, {
 		type: "run.created",
@@ -500,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;
 	}