pi-crew 0.7.3 → 0.7.4

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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).

package/package.json

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

package/src/extension/crew-autocomplete.ts

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

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

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

package/src/extension/crew-shortcuts.ts

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

package/src/extension/register.ts

@@ -111,6 +111,8 @@ import {
 import { registerSubagentTools } from "./registration/subagent-tools.ts";
 import { registerCrewMessageRenderers } from "./message-renderers.ts";
 import { registerCrewInputRouter } from "./crew-input-router.ts";
+import { registerCrewAutocomplete } from "./crew-autocomplete.ts";
+import { registerCrewShortcuts } from "./crew-shortcuts.ts";
 import { registerTeamTool } from "./registration/team-tool.ts";
 import { handleTeamTool } from "./team-tool.ts";
 import { persistScheduledJobUpdate } from "./team-tool/handle-schedule.ts";
@@ -214,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();
@@ -1219,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);
@@ -2048,4 +2059,10 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	// interactive input that starts with a crew/team keyword phrase; never
 	// shadows explicit slash commands.
 	registerCrewInputRouter(pi);
+
+	// Round 13 UX: keyboard shortcuts. alt+s opens the settings overlay
+	// (config + theme picker). Keys chosen to avoid Pi's built-in keymap.
+	// (The crew autocomplete provider is registered from session_start once
+	// a UI context is available — see the session_start handler below.)
+	registerCrewShortcuts(pi);
 }

package/src/extension/registration/commands.ts

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

package/src/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/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",