pi-crew 0.9.53 → 0.9.55

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

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

package/src/extension/crew-autocomplete.ts

@@ -0,0 +1,131 @@
+/**
+ * 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-cleanup.ts

@@ -0,0 +1,168 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { cleanupAllTrackedTempDirs } from "../runtime/pi-args.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+
+// NOTE: globalProgressTracker import kept for documentation but not directly used
+// since we don't have agent IDs to untrack. Actual progress clearing should be
+// handled by the progress tracker itself on shutdown.
+// import { globalProgressTracker } from "../runtime/progress-tracker.ts";
+
+/**
+ * Registers cleanup handlers for graceful shutdown.
+ * Handles session_shutdown and SIGTERM/SIGHUP signals.
+ */
+
+// Module-level flag to ensure signal handlers are registered only once,
+// even if registerCleanupHandler is called multiple times (e.g., on extension
+// reload or during dev hot-reload). Without this, listeners stack up and
+// cleanupChildProcesses fires N times on shutdown.
+let signalHandlersRegistered = false;
+
+interface ChildProcessInfo {
+	pid: number;
+	runId: string;
+	agentId: string;
+	startedAt: number;
+}
+
+class ChildProcessRegistry {
+	private processes = new Map<number, ChildProcessInfo>();
+
+	register(pid: number, runId: string, agentId: string): void {
+		this.processes.set(pid, { pid, runId, agentId, startedAt: Date.now() });
+	}
+
+	unregister(pid: number): void {
+		this.processes.delete(pid);
+	}
+
+	getAllPids(): number[] {
+		return Array.from(this.processes.keys());
+	}
+
+	getInfo(pid: number): ChildProcessInfo | undefined {
+		return this.processes.get(pid);
+	}
+
+	clear(): void {
+		this.processes.clear();
+	}
+}
+
+export const childProcessRegistry = new ChildProcessRegistry();
+
+/**
+ * Optional UI timer disposal hook. Set by register.ts so the SIGTERM/SIGHUP
+ * signal handler can dispose terminal-status timers (idle re-assert loop +
+ * flash clear) that would otherwise keep the event loop alive.
+ */
+let terminalStatusDispose: (() => void) | undefined;
+
+export function registerCleanupHandler(pi: ExtensionAPI, opts?: { disposeTerminalStatus?: () => void }): void {
+	// Store the latest dispose fn at module level so the signal handler
+	// (registered once) always uses the current one even across re-registrations.
+	terminalStatusDispose = opts?.disposeTerminalStatus;
+	// Handle session_shutdown event
+	pi.on("session_shutdown", async () => {
+		console.log("[pi-crew] Session shutdown - cleaning up resources");
+
+		try {
+			// Kill all child-pi processes
+			await cleanupChildProcesses();
+
+			// Cleanup temp directories
+			await cleanupTempDirectories();
+
+			console.log("[pi-crew] Cleanup complete");
+		} catch (error) {
+			logInternalError("crew-cleanup.shutdown", error);
+		}
+	});
+
+	// Register signal handlers exactly once, even if registerCleanupHandler
+	// is called multiple times. This prevents listener stacking on extension
+	// reload and avoids double-cleanup on shutdown.
+	if (!signalHandlersRegistered) {
+		signalHandlersRegistered = true;
+		const handleSignal = async (signal: string): Promise<void> => {
+			console.log(`[pi-crew] Received ${signal} - starting cleanup`);
+			// Dispose UI timers so the idle re-assert loop / flash clear don't
+			// keep the event loop alive after child processes are killed.
+			try {
+				terminalStatusDispose?.();
+			} catch {
+				// Best-effort — must not block child cleanup on signal.
+			}
+			await cleanupChildProcesses();
+		};
+		process.on("SIGTERM", () => {
+			handleSignal("SIGTERM").catch((error) => {
+				logInternalError("crew-cleanup.SIGTERM", error);
+			});
+		});
+		process.on("SIGHUP", () => {
+			handleSignal("SIGHUP").catch((error) => {
+				logInternalError("crew-cleanup.SIGHUP", error);
+			});
+		});
+	}
+}
+
+async function cleanupChildProcesses(): Promise<void> {
+	const pids = childProcessRegistry.getAllPids();
+	if (pids.length === 0) return;
+	// Lazy-import to avoid eagerly pulling the heavy runtime/child-pi chain into the
+	// extension load path (check-lazy-imports) AND to avoid a static import cycle
+	// (child-pi.ts already imports registerChildProcess from this module).
+	// LAZY: defer child-pi.ts load (heavy runtime chain) + avoid static import cycle.
+	const { killProcessPid } = await import("../runtime/child-pi.ts");
+	for (const pid of pids) {
+		// killProcessPid signals the whole process GROUP (-pid on POSIX, taskkill /T on
+		// Windows) and escalates to SIGKILL after HARD_KILL_MS. A bare
+		// process.kill(pid, "SIGTERM") only reaches the direct child — grandchildren
+		// (bash/MCP the worker spawned) in the child's group survive as orphans, and
+		// a child that lags SIGTERM would linger forever with no escalation.
+		// NOTE: on graceful session_shutdown (reason=quit/reload) register.ts ALSO runs
+		// terminateActiveChildPiProcesses(); both are idempotent for a dying pid. This
+		// signal handler (SIGTERM/SIGHUP) is the SOLE teardown path when the Pi process
+		// is killed by signal, so it must be robust on its own.
+		try {
+			killProcessPid(pid);
+			console.log(`[pi-crew] Sent group SIGTERM (+SIGKILL escalation) to child process ${pid}`);
+		} catch (error: unknown) {
+			// Process may already be dead or not exist
+			const err = error as NodeJS.ErrnoException;
+			if (err.code !== "ESRCH" && err.code !== "ENOENT") {
+				logInternalError("crew-cleanup.kill", error, `pid=${pid}`);
+			}
+		}
+		childProcessRegistry.unregister(pid);
+	}
+
+	// Clear progress tracker
+	// Note: Can't call untrack on all because we don't track agent IDs here
+	// The progress tracker should clear itself on shutdown via session_dispose
+}
+
+async function cleanupTempDirectories(): Promise<void> {
+	// Clean up every temp dir created in this process. Previously this was
+	// a stub that just logged; it caused /tmp/pi-crew-* dirs to accumulate
+	// from killed test runs and child-pi invocations. See issue #<n>.
+	try {
+		const result = cleanupAllTrackedTempDirs();
+		if (result.cleaned > 0) {
+			console.log(`[pi-crew] Cleaned ${result.cleaned} tracked temp dirs (${result.failed} failed)`);
+		}
+	} catch (error) {
+		logInternalError("crew-cleanup.temp", error);
+	}
+}
+
+// Export for child-pi.ts to register processes
+export function registerChildProcess(pid: number, runId: string, agentId: string): void {
+	childProcessRegistry.register(pid, runId, agentId);
+}
+
+export function unregisterChildProcess(pid: number): void {
+	childProcessRegistry.unregister(pid);
+}

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,87 @@
+/**
+ * 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+c → open the pi-crew run dashboard overlay (mnemonic: **C**rew)
+ *
+ * OCCUPIED alt+ keys in the built-in keymap (must NOT reuse — verified against
+ * pi-tui TUI_KEYBINDINGS + pi core keybindings.js):
+ *   alt+b (cursor word left)   alt+f (cursor word right)
+ *   alt+d (delete word forward) alt+y (yank pop)
+ *   alt+v (paste)              alt+s (crew settings — this module)
+ *   alt+enter / alt+up/down/left/right / alt+backspace / alt+delete
+ * Free alt+<letter> keys include: a, c, e, g, h, i, j, k, l, m, n, o, p, q,
+ * r, t, u, w, x, z.
+ *
+ * NOTE: an earlier revision used `alt+d` for the dashboard; that collided
+ * with `tui.editor.deleteWordForward` and Pi's conflict detector stripped the
+ * editor binding. `alt+c` is free AND mnemonic.
+ *
+ * NOTE: alt+m (mailbox) and alt+t (status) were considered but are NOT wired
+ * — the mailbox overlay is run-scoped (requires a runId; reached via the
+ * dashboard) and there is no standalone status overlay (status is a text
+ * command). See the K-2 note accompanying openTeamDashboard in commands.ts.
+ *
+ * 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) => {
+			// LAZY: defer dynamic import of ./registration/commands.ts to its call site.
+			const { openTeamSettingsOverlay } = await import("./registration/commands.ts");
+			await openTeamSettingsOverlay(ctx);
+		},
+	},
+	{
+		key: "alt+c",
+		description: "pi-crew: open run dashboard (Crew)",
+		// Lazy-import so the heavy UI module chain (RunDashboard etc.) is only
+		// loaded on first use, not at extension load.
+		handler: async (ctx) => {
+			// LAZY: defer dynamic import of ./registration/commands.ts to its call site.
+			const { openTeamDashboard } = await import("./registration/commands.ts");
+			await openTeamDashboard(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/crew-vibes/cat-frames.ts

@@ -0,0 +1,18 @@
+/**
+ * ANSI art cat animation frames extracted from runner-spritesheet.png.
+ * Used when PUA font glyphs are not available (web terminals like gotty).
+ * Each frame is an array of strings (one per line).
+ */
+export const CAT_FRAMES: readonly string[][] = [
+	// Frame 0 — standing
+	["▄▄ ███▄ ", "▀▀█████▄", "  ██▀██ ", "  ▀▀  ▀▀"],
+	// Frame 1 — step 1
+	["  ████  ", "  █████▄", "▄██████▀", "  ██ ▀█▄"],
+	// Frame 2 — step 2
+	[" ▄██████", " █████▀ ", "███████ ", "▀██████ "],
+	// Frame 3 — step 3
+	["  ████  ", "▄█████▄ ", "▀██████▄", "▄█▀  ██ "],
+] as const;
+
+/** Number of animation frames. */
+export const CAT_FRAME_COUNT = CAT_FRAMES.length;