pi-crew 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [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.3",
   "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-input-router.ts

@@ -0,0 +1,63 @@
+/**
+ * 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";
+
+/** 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" },
+];
+
+/**
+ * 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 rule of ROUTING_RULES) {
+		const match = trimmed.match(rule.match);
+		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 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/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,8 @@ 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 { registerTeamTool } from "./registration/team-tool.ts";
 import { handleTeamTool } from "./team-tool.ts";
 import { persistScheduledJobUpdate } from "./team-tool/handle-schedule.ts";
@@ -2035,4 +2037,15 @@ 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);
 }

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.
@@ -203,6 +204,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 +222,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 +250,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 +266,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 +280,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 +297,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 +342,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));
@@ -415,7 +428,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 +443,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/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}`);
 		}