pi-crew 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [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).
+
+### Bug Fixes (Critical — data loss prevention)
+
+- **`rotateEventLog` destroyed ALL events** — `atomicWriteFile("")` then `rename` replaced the file with empty content *before* the rename, so the archive received an empty file. Now copies content to archive first, then truncates in place. Also handles sub-millisecond timestamp collisions.
+- **`compactEventLog` recovery loop replaced the file per-event** — each `atomicWriteFile` iteration overwrote the compacted log + previous recoveries, leaving only the last event. Now accumulates missing events into one `appendFileSync`.
+- **Mailbox `delivery.json` lost-update race** — `appendMailboxMessage`, `acknowledgeMailboxMessage`, and `replayPendingMailboxMessages` all had unlocked read-modify-write cycles. Now wrapped in `withFileLockSync`.
+- **`observation-store.save()` non-atomic write** — raw `writeFileSync` could leave a truncated file on crash. Now uses `atomicWriteJson`.
+- **`background-runner` DEBUG log noise** — 10 trace-level `console.log` statements gated behind `PI_CREW_DEBUG` env var.
+
+### Features (UX)
+
+- **Command argument autocomplete** — 13 run-scoped and team-scoped commands now implement `getArgumentCompletions` so Pi's built-in Tab-completion surfaces run IDs (with status icon + goal preview), team names, workflow names, and task IDs. No more memorizing long generated run IDs.
+- **Custom message renderers** — `crew:run-started`, `crew:run-completed`, and `crew:resume-directive` entries now render with a clean crew-branded look (🚀/✅/❌ status icons, theme colors) instead of raw JSON blobs.
+- **Natural-language crew routing** — type `crew status`, `team dashboard`, `crew help`, `teams`, etc. and pi-crew rewrites it to the equivalent slash command. Only transforms interactive input; never shadows explicit slash commands.
+
+### Tests
+
+- +125 tests (4795 pass / 0 fail). New coverage: cascading replace engine (31), safe-paths traversal defense (21), atomic-write symlink prevention (15), command completions (20), message renderers (12), input router (18), event-log rotate regression (9).
+
+### Research
+
+This release was driven by 4 deep research rounds (11–14), documented in `research-findings/`.
+
 ## [0.7.2] — Fix: Knowledge Injection into Workers + HITL for All Workflows (2026-06-15)
 
 ### Bug Fixes

package/package.json

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

package/src/extension/command-completions.ts

@@ -0,0 +1,118 @@
+/**
+ * Command argument autocomplete helpers (Round 13 UX quick-win).
+ *
+ * Pi's built-in slash-command autocomplete calls a command's
+ * `getArgumentCompletions(argumentPrefix)` when the user types
+ * `/command <prefix><TAB>`. Returning AutocompleteItem[] surfaces those
+ * suggestions; returning null falls back to file completion.
+ *
+ * These helpers provide run-id, team, and workflow completions without
+ * requiring the user to memorize long generated IDs.
+ */
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { listRecentRuns } from "./run-index.ts";
+import { discoverTeams, allTeams } from "../teams/discover-teams.ts";
+import { discoverWorkflows, allWorkflows } from "../workflows/discover-workflows.ts";
+import { discoverAgents, allAgents } from "../agents/discover-agents.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+
+const MAX_RUN_SUGGESTIONS = 15;
+
+function filterByPrefix(items: AutocompleteItem[], prefix: string): AutocompleteItem[] | null {
+	const trimmed = prefix.trim();
+	const filtered = trimmed === ""
+		? items
+		: items.filter((item) => item.value.startsWith(trimmed) || item.label.toLowerCase().includes(trimmed.toLowerCase()));
+	return filtered.length > 0 ? filtered.slice(0, MAX_RUN_SUGGESTIONS) : null;
+}
+
+function statusIcon(status: TeamRunManifest["status"]): string {
+	switch (status) {
+		case "running":
+		case "planning":
+			return "▶";
+		case "queued":
+			return "⏳";
+		case "completed":
+			return "✓";
+		case "failed":
+		case "blocked":
+			return "✗";
+		case "cancelled":
+			return "⊘";
+		default:
+			return "•";
+	}
+}
+
+/**
+ * Suggest recent run IDs for run-scoped commands (/team-status, /team-cancel, …).
+ * Falls back to `process.cwd()` because Pi does not pass cwd into
+ * `getArgumentCompletions` — this is correct in the interactive TUI where the
+ * process cwd matches the session cwd.
+ */
+export function suggestRunIds(_prefix: string, cwd?: string): AutocompleteItem[] | null {
+	const resolvedCwd = cwd ?? process.cwd();
+	const runs = listRecentRuns(resolvedCwd, MAX_RUN_SUGGESTIONS);
+	if (runs.length === 0) return null;
+	const items: AutocompleteItem[] = runs.map((run) => ({
+		value: run.runId,
+		label: run.runId,
+		description: `${statusIcon(run.status)} ${run.status} · ${run.team} · ${(run.goal ?? "").slice(0, 48)}`,
+	}));
+	return filterByPrefix(items, _prefix);
+}
+
+/** Suggest task IDs within a specific run (for /team-result <runId> <taskId>). */
+export async function suggestTaskIds(runId: string, prefix: string, cwd?: string): Promise<AutocompleteItem[] | null> {
+	const resolvedCwd = cwd ?? process.cwd();
+	// Dynamic import to avoid pulling state-store into the hot command-registration path.
+	const { loadRunManifestById } = await import("../state/state-store.ts");
+	const loaded = loadRunManifestById(resolvedCwd, runId);
+	if (!loaded) return null;
+	const items: AutocompleteItem[] = loaded.tasks.map((task) => ({
+		value: task.id,
+		label: task.id,
+		description: `${task.status} · ${task.role} · ${task.title?.slice(0, 40) ?? ""}`,
+	}));
+	return filterByPrefix(items, prefix);
+}
+
+/** Suggest available teams for /team-run <team>. */
+export function suggestTeams(prefix: string, cwd?: string): AutocompleteItem[] | null {
+	const resolvedCwd = cwd ?? process.cwd();
+	const teams = allTeams(discoverTeams(resolvedCwd));
+	if (teams.length === 0) return null;
+	const items: AutocompleteItem[] = teams.map((team) => ({
+		value: team.name,
+		label: team.name,
+		description: team.defaultWorkflow ? `workflow=${team.defaultWorkflow}` : undefined,
+	}));
+	return filterByPrefix(items, prefix);
+}
+
+/** Suggest available workflows. */
+export function suggestWorkflows(prefix: string, cwd?: string): AutocompleteItem[] | null {
+	const resolvedCwd = cwd ?? process.cwd();
+	const workflows = allWorkflows(discoverWorkflows(resolvedCwd));
+	if (workflows.length === 0) return null;
+	const items: AutocompleteItem[] = workflows.map((wf) => ({
+		value: wf.name,
+		label: wf.name,
+		description: `${wf.steps?.length ?? 0} steps`,
+	}));
+	return filterByPrefix(items, prefix);
+}
+
+/** Suggest available agents. */
+export function suggestAgents(prefix: string, cwd?: string): AutocompleteItem[] | null {
+	const resolvedCwd = cwd ?? process.cwd();
+	const agents = allAgents(discoverAgents(resolvedCwd));
+	if (agents.length === 0) return null;
+	const items: AutocompleteItem[] = agents.map((agent) => ({
+		value: agent.name,
+		label: agent.name,
+		description: agent.description?.slice(0, 60),
+	}));
+	return filterByPrefix(items, prefix);
+}

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

@@ -0,0 +1,93 @@
+/**
+ * Natural-language crew input routing (Round 13 UX).
+ *
+ * Pi fires the `input` event before skill/template expansion and before
+ * before_agent_start. A handler can transform the text (e.g. rewrite
+ * "crew status" → "/team-status"), or fully handle it.
+ *
+ * This module matches a small set of natural-language crew phrases and
+ * rewrites them to the equivalent slash command, so users do not need to
+ * memorize command names. Slash-command input (text starting with "/") is
+ * always passed through unchanged — we never shadow explicit commands.
+ */
+import type { InputEvent, InputEventResult } from "@earendil-works/pi-coding-agent";
+
+/**
+ * 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.
+ *
+ * Rules intentionally only match at the START of the input and require a
+ * word boundary, so ordinary sentences mentioning "crew" are untouched.
+ */
+export function rewriteCrewInput(text: string): string | null {
+	const trimmed = text.trim();
+	// Never transform explicit slash commands or inputs that don't start with
+	// a crew/team keyword phrase.
+	if (trimmed.startsWith("/")) return null;
+	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 ? `${entry.command} ${rest}` : entry.command;
+	}
+	return null;
+}
+
+/**
+ * Pi `input` event handler. Transforms matching crew phrases; passes
+ * everything else through unchanged.
+ */
+export function handleCrewInput(event: InputEvent): InputEventResult {
+	// Only transform interactive user input — never programmatic/scripted input.
+	if (event.source !== "interactive") return { action: "continue" };
+	const rewritten = rewriteCrewInput(event.text);
+	if (!rewritten) return { action: "continue" };
+	return { action: "transform", text: rewritten, images: event.images };
+}
+
+/** Register the crew input router on a Pi instance. Safe to call once. */
+export function registerCrewInputRouter(pi: { on?: (event: "input", handler: (e: InputEvent) => InputEventResult) => void }): void {
+	pi.on?.("input", handleCrewInput);
+}

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/message-renderers.ts

@@ -0,0 +1,109 @@
+/**
+ * Custom message renderers for pi-crew session entries (Round 13 UX).
+ *
+ * pi-crew emits CustomMessageEntry rows via `pi.appendEntry()` for run
+ * lifecycle events (crew:run-started, crew:run-completed,
+ * crew:resume-directive). Without a registered renderer these display as
+ * raw JSON in the conversation. These renderers give them a clean,
+ * crew-branded look using the active theme.
+ */
+import { Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, MessageRenderOptions, Theme } from "@earendil-works/pi-coding-agent";
+
+interface CrewMessageDetails {
+	runId?: string;
+	team?: string;
+	workflow?: string;
+	agent?: string;
+	goal?: string;
+	status?: string;
+	taskCount?: number;
+	timestamp?: number;
+}
+
+type MessageLike = {
+	content: string | Array<{ type: string; text?: string }>;
+	details?: CrewMessageDetails;
+};
+
+function extractText(message: MessageLike): string {
+	if (typeof message.content === "string") return message.content;
+	return (message.content ?? []).map((c) => c.text ?? "").join("");
+}
+
+function statusLevel(status: string | undefined): "success" | "error" | "warning" | "muted" {
+	switch (status) {
+		case "completed":
+			return "success";
+		case "failed":
+		case "blocked":
+			return "error";
+		case "cancelled":
+			return "warning";
+		default:
+			return "muted";
+	}
+}
+
+function statusIcon(status: string | undefined): string {
+	switch (status) {
+		case "completed":
+			return "✅";
+		case "failed":
+		case "blocked":
+			return "❌";
+		case "cancelled":
+			return "🚫";
+		case "running":
+		case "planning":
+			return "🚀";
+		default:
+			return "•";
+	}
+}
+
+/** Truncate a string to maxLen chars with an ellipsis. */
+function truncate(text: string, maxLen: number): string {
+	return text.length > maxLen ? `${text.slice(0, maxLen - 1)}…` : text;
+}
+
+/** Render crew:run-started entries as a branded launch line. */
+export function renderRunStarted(message: MessageLike, _options: MessageRenderOptions, theme: Theme): Text {
+	const details = message.details ?? {};
+	const goal = details.goal ? truncate(details.goal, 70) : "";
+	const team = details.team ?? details.agent ?? "direct";
+	const workflow = details.workflow ?? "default";
+	const text = `🚀 crew run ${details.runId ?? ""} started — ${team}/${workflow}${goal ? ` — ${goal}` : ""}`;
+	return new Text(theme.fg("accent", theme.bold("crew ")) + theme.fg("text", text), 0, 0);
+}
+
+/** Render crew:run-completed entries with a status-colored summary. */
+export function renderRunCompleted(message: MessageLike, _options: MessageRenderOptions, theme: Theme): Text {
+	const details = message.details ?? {};
+	const status = details.status;
+	const level = statusLevel(status);
+	const icon = statusIcon(status);
+	const goal = details.goal ? truncate(details.goal, 60) : "";
+	const tasks = details.taskCount !== undefined ? ` · ${details.taskCount} tasks` : "";
+	const text = `${icon} crew run ${details.runId ?? ""} ${status ?? "finished"}${tasks}${goal ? ` — ${goal}` : ""}`;
+	return new Text(theme.fg(level, theme.bold("crew ")) + theme.fg(level, text), 0, 0);
+}
+
+/** Render crew:resume-directive entries as an informational system note. */
+export function renderResumeDirective(message: MessageLike, _options: MessageRenderOptions, theme: Theme): Text {
+	const text = extractText(message) || "Context compacted — resuming in-flight crew work.";
+	return new Text(theme.fg("muted", theme.bold("crew ") + text), 0, 0);
+}
+
+/** Register all crew message renderers. Safe to call once at extension load. */
+export function registerCrewMessageRenderers(
+	pi: { registerMessageRenderer?: ExtensionAPI["registerMessageRenderer"] },
+): void {
+	// Optional chaining guards against older Pi versions (and test stubs)
+	// without registerMessageRenderer.
+	// The renderers return Text (a Component) — cast through never to match
+	// the MessageRenderer<T> signature which expects Component | undefined.
+	pi.registerMessageRenderer?.("crew:run-started", renderRunStarted as never);
+	pi.registerMessageRenderer?.("crew:run-completed", renderRunCompleted as never);
+	pi.registerMessageRenderer?.("crew:resume-directive", renderResumeDirective as never);
+}

package/src/extension/register.ts

@@ -109,6 +109,10 @@ import {
 	sendFollowUp,
 } from "./registration/subagent-helpers.ts";
 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 { registerTeamTool } from "./registration/team-tool.ts";
 import { handleTeamTool } from "./team-tool.ts";
 import { persistScheduledJobUpdate } from "./team-tool/handle-schedule.ts";
@@ -212,6 +216,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();
@@ -1217,6 +1222,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);
@@ -2035,4 +2048,21 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 			}
 		},
 	});
+
+	// Round 13 UX: render pi-crew lifecycle entries (crew:run-started,
+	// crew:run-completed, crew:resume-directive) with a branded look instead
+	// of raw JSON. No-op on Pi versions without registerMessageRenderer.
+	registerCrewMessageRenderers(pi);
+
+	// Round 13 UX: natural-language crew input routing. Lets users type
+	// "crew status" instead of remembering /team-status. Only transforms
+	// 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);
 }

package/src/extension/registration/commands.ts

@@ -23,6 +23,7 @@ import { handleTeamManagerCommand } from "../team-manager-command.ts";
 import { loadRunManifestById } from "../../state/state-store.ts";
 import type { TeamRunManifest } from "../../state/types.ts";
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
+import { suggestRunIds, suggestTaskIds, suggestTeams } from "../command-completions.ts";
 import * as path from "node:path";
 // Heavy UI modules — lazy-loaded because they're only used in /crew commands.
 // RunDashboard (288ms), DurableTextViewer (658ms), Overlays are unnecessary at Pi startup.
@@ -153,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) {
@@ -203,6 +270,8 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 
 	pi.registerCommand("team-run", {
 		description: "Manually start a pi-crew run (agent may also use the team tool autonomously)",
+		// Round 13 UX: suggest team names for Tab-completion of the first positional arg.
+		getArgumentCompletions: (argumentPrefix: string) => suggestTeams(argumentPrefix),
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const result = await handleTeamTool(parseRunArgs(args), { ...teamCommandContext(ctx), metricRegistry: deps.getMetricRegistry?.(), startForegroundRun: (runner, runId) => deps.startForegroundRun(ctx as ExtensionContext, runner, runId), abortForegroundRun: deps.abortForegroundRun, onRunStarted: undefined });
 			await notifyCommandResult(ctx, commandText(result));
@@ -219,15 +288,21 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 		["team-export", "export", "Export a pi-crew run bundle to artifacts/export"],
 		["team-cancel", "cancel", "Cancel a pi-crew run"],
 	] as const) {
-		pi.registerCommand(name, { description, handler: async (args: string, ctx: ExtensionCommandContext) => {
-			const runId = args.trim() || undefined;
-			const result = await handleTeamTool({ action, runId }, { ...teamCommandContext(ctx), getRunSnapshotCache: deps.getRunSnapshotCache });
-			await notifyCommandResult(ctx, commandText(result));
-		} });
+		pi.registerCommand(name, {
+			description,
+			// Round 13 UX: suggest recent run IDs for Tab-completion.
+			getArgumentCompletions: (argumentPrefix: string) => suggestRunIds(argumentPrefix),
+			handler: async (args: string, ctx: ExtensionCommandContext) => {
+				const runId = args.trim() || undefined;
+				const result = await handleTeamTool({ action, runId }, { ...teamCommandContext(ctx), getRunSnapshotCache: deps.getRunSnapshotCache });
+				await notifyCommandResult(ctx, commandText(result));
+			},
+		});
 	}
 
 	pi.registerCommand("team-invalidate", {
 		description: "Invalidate the snapshot cache for a run so the UI refreshes immediately: <runId>",
+		getArgumentCompletions: (argumentPrefix: string) => suggestRunIds(argumentPrefix),
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const runId = args.trim() || undefined;
 			if (!runId) {
@@ -241,6 +316,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 
 	pi.registerCommand("team-retry", {
 		description: "Retry failed/cancelled pi-crew tasks: <runId> [taskId]",
+		getArgumentCompletions: (argumentPrefix: string) => suggestRunIds(argumentPrefix),
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const tokens = args.trim().split(/\s+/).filter(Boolean);
 			const runId = tokens.shift();
@@ -256,6 +332,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 
 	pi.registerCommand("team-respond", {
 		description: "Respond to a waiting pi-crew task: <runId> <taskId|--all> <message>",
+		getArgumentCompletions: (argumentPrefix: string) => suggestRunIds(argumentPrefix),
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const tokens = args.trim().split(/\s+/).filter(Boolean);
 			const runId = tokens.shift();
@@ -269,6 +346,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 
 	pi.registerCommand("team-follow-up", {
 		description: "Send a follow-up prompt to a pi-crew task: <runId> <taskId> <prompt>",
+		getArgumentCompletions: (argumentPrefix: string) => suggestRunIds(argumentPrefix),
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const tokens = args.trim().split(/\s+/).filter(Boolean);
 			const runId = tokens.shift();
@@ -285,6 +363,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 
 	pi.registerCommand("team-api", {
 		description: "Run safe pi-crew API interop operations: <runId> <operation> [key=value]",
+		getArgumentCompletions: (argumentPrefix: string) => suggestRunIds(argumentPrefix),
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const tokens = args.trim().split(/\s+/).filter(Boolean);
 			const positional = tokens.filter((token) => !token.includes("=") && !token.startsWith("--"));
@@ -329,7 +408,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 		await notifyCommandResult(ctx, commandText(result));
 	} });
 
-	pi.registerCommand("team-forget", { description: "Forget a pi-crew run by deleting its state and artifacts", handler: async (args: string, ctx: ExtensionCommandContext) => {
+	pi.registerCommand("team-forget", { description: "Forget a pi-crew run by deleting its state and artifacts", getArgumentCompletions: (argumentPrefix: string) => suggestRunIds(argumentPrefix), handler: async (args: string, ctx: ExtensionCommandContext) => {
 		const tokens = args.trim().split(/\s+/).filter(Boolean);
 		const runId = tokens.find((token) => !token.startsWith("--"));
 		const result = await handleTeamTool({ action: "forget", runId, force: tokens.includes("--force"), confirm: tokens.includes("--confirm") }, teamCommandContext(ctx));
@@ -340,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));
@@ -415,7 +441,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 
 	pi.registerCommand("team-cleanup", { description: "Open a simple pi-crew interactive manager", handler: handleTeamManagerCommand });
 
-	pi.registerCommand("team-result", { description: "Open a pi-crew agent result viewer: <runId> [taskId]", handler: async (args: string, ctx: ExtensionCommandContext) => {
+	pi.registerCommand("team-result", { description: "Open a pi-crew agent result viewer: <runId> [taskId]", getArgumentCompletions: async (argumentPrefix: string) => { const parts = argumentPrefix.trim().split(/\s+/); return parts.length <= 1 ? suggestRunIds(parts[0] ?? "") : suggestTaskIds(parts[0] ?? "", parts[1] ?? ""); }, handler: async (args: string, ctx: ExtensionCommandContext) => {
 		const [runId, rawTaskId] = args.trim().split(/\s+/).filter(Boolean);
 		const selected = await selectAgentTask(ctx, runId, rawTaskId);
 		const loaded = selected ? loadRunManifestById(ctx.cwd, selected.runId) : undefined; // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
@@ -430,7 +456,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 		await notifyCommandResult(ctx, commandText(result));
 	} });
 
-	pi.registerCommand("team-transcript", { description: "Open a pi-crew transcript viewer: <runId> [taskId]", handler: async (args: string, ctx: ExtensionCommandContext) => {
+	pi.registerCommand("team-transcript", { description: "Open a pi-crew transcript viewer: <runId> [taskId]", getArgumentCompletions: async (argumentPrefix: string) => { const parts = argumentPrefix.trim().split(/\s+/); return parts.length <= 1 ? suggestRunIds(parts[0] ?? "") : suggestTaskIds(parts[0] ?? "", parts[1] ?? ""); }, handler: async (args: string, ctx: ExtensionCommandContext) => {
 		const [runId, taskId] = args.trim().split(/\s+/).filter(Boolean);
 		if (await openTranscriptViewer(ctx, runId, taskId)) return;
 		const result = await handleTeamTool({ action: "api", runId, config: { operation: "read-agent-transcript", agentId: taskId } }, teamCommandContext(ctx));

package/src/runtime/background-runner.ts

@@ -46,6 +46,15 @@ import {
 	runtimeResolutionState,
 } from "./runtime-resolver.ts";
 
+/**
+ * Debug logger gated behind PI_CREW_DEBUG env var. Writes to background.log
+ * (console is redirected there). Eliminates log noise in normal operation
+ * while keeping diagnostics available when explicitly enabled.
+ */
+function debugLog(message: string): void {
+	if (process.env.PI_CREW_DEBUG) console.log(message);
+}
+
 /**
  * Heartbeat mechanism: periodically write a heartbeat file so the stale reconciler
  * can distinguish "process died" from "process still alive but quiet".
@@ -222,8 +231,7 @@ function runCleanup(
 	exitDueToRejection: boolean,
 	eventsPath?: string,
 ): void {
-	console.log(
-		`[background-runner] DEBUG: runCleanup, exitDueToRejection=${exitDueToRejection}`,
+	console.log(`[background-runner] runCleanup, exitDueToRejection=${exitDueToRejection}`,
 	);
 	stopInterruptGuard();
 	stopParentGuard();
@@ -492,8 +500,7 @@ async function main(): Promise<void> {
 		runId: manifest.runId,
 		data: { pid: process.pid },
 	});
-	console.log(
-		`[background-runner] DEBUG: async.started written, pid=${process.pid}`,
+	debugLog(`[background-runner] async.started written, pid=${process.pid}`,
 	);
 	writeAsyncStartMarker(manifest, {
 		pid: process.pid,
@@ -505,7 +512,7 @@ async function main(): Promise<void> {
 		manifest.runId,
 	);
 	const stopInterruptGuard = startInterruptGuard(manifest, abortController, stopParentGuard);
-	console.log(`[background-runner] DEBUG: heartbeat+interrupt guard started`);
+	debugLog(`[background-runner] heartbeat+interrupt guard started`);
 	// NOTE: Keep-alive interval is NOT unref'd (unlike heartbeat and interrupt
 	// guard intervals which ARE unref'd). This is intentional — during jiti
 	// compilation of team-runner.ts, the event loop must not drain prematurely.
@@ -514,25 +521,22 @@ async function main(): Promise<void> {
 	const keepAlive = setInterval(() => {}, 5000);
 
 	try {
-		console.log(`[background-runner] DEBUG: about to call discoverAgents`);
+		debugLog(`[background-runner] about to call discoverAgents`);
 		const agents = allAgents(discoverAgents(cwd));
-		console.log(
-			`[background-runner] DEBUG: discoverAgents done, ${agents.length} agents`,
+		debugLog(`[background-runner] discoverAgents done, ${agents.length} agents`,
 		);
 		try { fs.fsyncSync(fs.openSync(manifest.eventsPath, "a")); } catch { /* best-effort */ } // FORCE flush so we see this before death
-		console.log(
-			`[background-runner] DEBUG: calling directTeamAndWorkflowFromRun`,
+		debugLog(`[background-runner] calling directTeamAndWorkflowFromRun`,
 		);
 		const direct = directTeamAndWorkflowFromRun(manifest, tasks, agents);
-		console.log(`[background-runner] DEBUG: direct done, finding team`);
+		debugLog(`[background-runner] direct done, finding team`);
 		const team =
 			direct?.team ??
 			allTeams(discoverTeams(cwd)).find(
 				(candidate) => candidate.name === manifest.team,
 			);
 		if (!team) throw new Error(`Team '${manifest.team}' not found.`);
-		console.log(
-			`[background-runner] DEBUG: team=${team.name}, finding workflow`,
+		debugLog(`[background-runner] team=${team.name}, finding workflow`,
 		);
 		const baseWorkflow =
 			direct?.workflow ??
@@ -541,9 +545,9 @@ async function main(): Promise<void> {
 			);
 		if (!baseWorkflow)
 			throw new Error(`Workflow '${manifest.workflow ?? ""}' not found.`);
-		console.log(`[background-runner] DEBUG: workflow=${baseWorkflow.name}`);
+		debugLog(`[background-runner] workflow=${baseWorkflow.name}`);
 		const workflow = expandParallelResearchWorkflow(baseWorkflow, cwd);
-		console.log(`[background-runner] DEBUG: loading config`);
+		debugLog(`[background-runner] loading config`);
 		const loadedConfig = loadConfig(cwd);
 		const runConfig =
 			manifest.runConfig &&
@@ -597,7 +601,7 @@ async function main(): Promise<void> {
 		// NOTE: abortController is already created above (before heartbeat/interrupt guard start)
 		// so it is available here and its signal is passed through to executeTeamRun → child-pi.
 
-		console.log(`[background-runner] DEBUG: calling executeTeamRun`);
+		debugLog(`[background-runner] calling executeTeamRun`);
 		let result;
 		try {
 			result = await executeTeamRun({
@@ -615,15 +619,12 @@ async function main(): Promise<void> {
 				workspaceId: manifest.ownerSessionId ?? manifest.cwd,
 				signal: abortController.signal,
 			});
-			console.log(
-				`[background-runner] DEBUG: executeTeamRun returned, status=${result.manifest.status}`,
+			console.log(`[background-runner] executeTeamRun returned, status=${result.manifest.status}`,
 			);
 		} catch (execError) {
-			console.log(
-				`[background-runner] DEBUG: executeTeamRun THREW: ${execError instanceof Error ? execError.message : String(execError)}`,
+			console.log(`[background-runner] executeTeamRun THREW: ${execError instanceof Error ? execError.message : String(execError)}`,
 			);
-			console.log(
-				`[background-runner] DEBUG: stack: ${execError instanceof Error ? execError.stack : "N/A"}`,
+			console.log(`[background-runner] stack: ${execError instanceof Error ? execError.stack : "N/A"}`,
 			);
 			throw execError;
 		}
@@ -634,8 +635,7 @@ async function main(): Promise<void> {
 			runId: manifest.runId,
 			data: { status: manifest.status, tasks: tasks.length },
 		});
-		console.log(
-			`[background-runner] DEBUG: async.completed written, status=${manifest.status}`,
+		console.log(`[background-runner] async.completed written, status=${manifest.status}`,
 		);
 		if (
 			manifest.status === "failed" ||
@@ -682,8 +682,7 @@ async function main(): Promise<void> {
 			message,
 		});
 		process.exitCode = 1;
-		console.log(
-			`[background-runner] DEBUG: catch block, error=${error instanceof Error ? error.message : String(error)}`,
+		console.log(`[background-runner] catch block, error=${error instanceof Error ? error.message : String(error)}`,
 		);
 	} finally {
 		// FIX Issue #4: Use shared runCleanup() function for consistent cleanup

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-rotation.ts

@@ -113,15 +113,20 @@ export function compactEventLog(eventsPath: string, config?: Partial<RotationCon
 			const missingEvents = kept.filter((e) => e.metadata?.seq === undefined || !afterSeqs.has(e.metadata.seq));
 			let recoveredCount = 0;
 			let recoveryFailed = false;
-			for (const event of missingEvents) {
+			if (missingEvents.length > 0) {
+				// BUGFIX (Round 12 C2): the previous loop called atomicWriteFile PER event,
+				// which REPLACES the entire file each iteration — destroying the
+				// compacted log and all previously-recovered events, leaving only the
+				// LAST missing event. FIX: accumulate all missing events into one
+				// string and append in a single write (appendFileSync appends without
+				// destroying existing content).
+				const recoveryLines = missingEvents.map((e) => JSON.stringify(e) + "\n").join("");
 				try {
-					// Use atomicWriteFile for recovery append too — safer than plain appendFileSync
-					atomicWriteFile(eventsPath, JSON.stringify(event) + "\n");
-					recoveredCount++;
+					fs.appendFileSync(eventsPath, recoveryLines);
+					recoveredCount = missingEvents.length;
 				} catch (err) {
 					recoveryFailed = true;
-					// FIX: Log when recovery append fails to avoid silent event loss
-					logInternalError("event-log-rotation.recovery", err, `eventsPath=${eventsPath} lostEvent=${JSON.stringify(event).slice(0, 100)}`);
+					logInternalError("event-log-rotation.recovery", err, `eventsPath=${eventsPath} lostEvents=${missingEvents.length}`);
 				}
 			}
 			return {
@@ -159,12 +164,24 @@ export function rotateEventLog(eventsPath: string): boolean {
 	return withEventLogLockSync(eventsPath, () => {
 		try {
 			const ts = new Date().toISOString().replace(/[:.]/g, "-");
-			const archivePath = `${eventsPath}.${ts}.archive.jsonl`;
-			// Step 1: create new empty file at eventsPath FIRST
-			// This ensures eventsPath always exists for readers
-			atomicWriteFile(eventsPath, "");
-			// Step 2: rename old content to archive (after new file is in place)
-			fs.renameSync(eventsPath, archivePath);
+			let archivePath = `${eventsPath}.${ts}.archive.jsonl`;
+			// Round 12: avoid timestamp collisions when two rotations happen within
+			// the same millisecond (copyFileSync would silently overwrite the
+			// first archive). Append a counter until the path is free.
+			let collision = 1;
+			while (fs.existsSync(archivePath)) {
+				archivePath = `${eventsPath}.${ts}.${collision}.archive.jsonl`;
+				collision++;
+			}
+			// BUGFIX (Round 12 C1): the previous order (atomicWriteFile empty THEN
+			// rename) destroyed ALL events — atomicWriteFile replaces the file
+			// in place, so the rename then moved an EMPTY file to the archive.
+			// FIX: copy current content to the archive first (archive is populated,
+			// original still intact), then truncate the original to empty in place.
+			// copyFileSync + writeFileSync("") ensures eventsPath ALWAYS exists
+			// (no missing-file window for concurrent readers).
+			fs.copyFileSync(eventsPath, archivePath);
+			fs.writeFileSync(eventsPath, "", "utf-8");
 			return true;
 		} catch (error) {
 			logInternalError("event-log.rotate", error, `eventsPath=${eventsPath}`);

package/src/state/mailbox.ts

@@ -408,10 +408,16 @@ export function appendMailboxMessage(manifest: TeamRunManifest, message: Omit<Ma
 	// 3.3 — rotate mailbox file if it has grown past 10 MB. Cheap stat
 	// check; rotates at most once per append.
 	rotateMailboxFileIfNeeded(mailboxFile(manifest, complete.direction, complete.taskId));
-	const delivery = readDeliveryState(manifest);
-	delivery.messages[complete.id] = complete.status;
-	delivery.updatedAt = createdAt;
-	writeDeliveryState(manifest, delivery);
+	// BUGFIX (Round 12 C3): the delivery.json read-modify-write below was
+	// UNLOCKED, so concurrent appendMailboxMessage calls could interleave and
+	// clobber each other's delivery entries (lost-update race). FIX: wrap the
+	// entire read-modify-write in a file lock on the delivery file.
+	withFileLockSync(deliveryFile(manifest, true), () => {
+		const delivery = readDeliveryState(manifest);
+		delivery.messages[complete.id] = complete.status;
+		delivery.updatedAt = createdAt;
+		writeDeliveryState(manifest, delivery);
+	});
 	return complete;
 }
 
@@ -437,12 +443,16 @@ export function readMailboxMessage(manifest: TeamRunManifest, messageId: string)
 }
 
 export function acknowledgeMailboxMessage(manifest: TeamRunManifest, messageId: string): MailboxDeliveryState {
-	const delivery = readDeliveryState(manifest);
-	if (!delivery.messages[messageId]) throw new Error(`Mailbox message '${messageId}' not found.`);
-	delivery.messages[messageId] = "acknowledged";
-	delivery.updatedAt = new Date().toISOString();
-	writeDeliveryState(manifest, delivery);
-	return delivery;
+	// BUGFIX (Round 12 I6): unlocked read-modify-write on delivery.json could
+	// clobber concurrent appends. FIX: wrap in a file lock.
+	return withFileLockSync(deliveryFile(manifest, true), () => {
+		const delivery = readDeliveryState(manifest);
+		if (!delivery.messages[messageId]) throw new Error(`Mailbox message '${messageId}' not found.`);
+		delivery.messages[messageId] = "acknowledged";
+		delivery.updatedAt = new Date().toISOString();
+		writeDeliveryState(manifest, delivery);
+		return delivery;
+	});
 }
 
 /**
@@ -503,14 +513,18 @@ export function updateMailboxMessageReply(manifest: TeamRunManifest, originalMes
 }
 
 export function replayPendingMailboxMessages(manifest: TeamRunManifest): MailboxReplayResult {
-	const delivery = readDeliveryState(manifest);
-	const pending = readAllInboxMessages(manifest).filter((message) => message.status !== "acknowledged" && delivery.messages[message.id] !== "acknowledged");
-	if (!pending.length) return { messages: [], updatedAt: delivery.updatedAt };
-	const updatedAt = new Date().toISOString();
-	for (const message of pending) delivery.messages[message.id] = "delivered";
-	delivery.updatedAt = updatedAt;
-	writeDeliveryState(manifest, delivery);
-	return { messages: pending, updatedAt };
+	// BUGFIX (Round 12 I6): unlocked read-modify-write on delivery.json could
+	// clobber concurrent appends/acknowledgments. FIX: wrap in a file lock.
+	return withFileLockSync(deliveryFile(manifest, true), () => {
+		const delivery = readDeliveryState(manifest);
+		const pending = readAllInboxMessages(manifest).filter((message) => message.status !== "acknowledged" && delivery.messages[message.id] !== "acknowledged");
+		if (!pending.length) return { messages: [], updatedAt: delivery.updatedAt };
+		const updatedAt = new Date().toISOString();
+		for (const message of pending) delivery.messages[message.id] = "delivered";
+		delivery.updatedAt = updatedAt;
+		writeDeliveryState(manifest, delivery);
+		return { messages: pending, updatedAt };
+	});
 }
 
 export function validateMailbox(manifest: TeamRunManifest, options: { repair?: boolean; signal?: AbortSignal } = {}): MailboxValidationReport {

package/src/state/observation-store.ts

@@ -8,10 +8,11 @@
  * Actual capture hooks into the lifecycle events (Pattern 12).
  */
 
-import { mkdirSync, readFileSync, writeFileSync, existsSync, appendFileSync } from "node:fs";
+import { readFileSync, existsSync, appendFileSync } from "node:fs";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { logInternalError } from "../utils/internal-error.ts";
+import { atomicWriteJson } from "./atomic-write.ts";
 
 // ── Types ────────────────────────────────────────────────────────────────
 
@@ -153,12 +154,13 @@ export class ObservationStore {
 	 */
 	save(): void {
 		try {
-			// Use path.dirname for cross-platform support (handles both \ and /)
-			mkdirSync(path.dirname(this.storePath), { recursive: true });
-			writeFileSync(this.storePath, JSON.stringify({
+			// BUGFIX (Round 12 I4): use atomicWriteJson (temp-file + rename) instead
+			// of raw writeFileSync, so a crash mid-write cannot leave a truncated /
+			// empty file that breaks load() on restart.
+			atomicWriteJson(this.storePath, {
 				observations: this.observations,
 				compressed: this.compressed,
-			}, null, 2), "utf-8");
+			});
 		} catch (error) {
 			logInternalError("observation-store.save", error, `path=${this.storePath}`);
 		}

package/src/state/state-store.ts

@@ -213,8 +213,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",