pi-crew 0.1.49 → 0.2.0

package/src/extension/cross-extension-rpc.ts

@@ -1,82 +1,103 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-import type { TeamToolParamsValue } from "../schema/team-tool-schema.ts";
-import { handleTeamTool } from "./team-tool.ts";
-import { parseLiveControlRealtimeMessage, publishLiveControlRealtime } from "../runtime/live-control-realtime.ts";
-
-export interface EventBusLike {
-	on(event: string, handler: (data: unknown) => void): (() => void) | void;
-	emit(event: string, data: unknown): void;
-}
-
-export type RpcReply<T = unknown> = { success: true; data?: T } | { success: false; error: string };
-export const PI_CREW_RPC_VERSION = 1;
-
-export interface PiCrewRpcHandle {
-	unsubscribe(): void;
-}
-
-function requestId(raw: unknown): string | undefined {
-	return raw && typeof raw === "object" && !Array.isArray(raw) && typeof (raw as { requestId?: unknown }).requestId === "string" ? (raw as { requestId: string }).requestId : undefined;
-}
-
-function reply(events: EventBusLike, channel: string, id: string | undefined, payload: RpcReply): void {
-	if (!id) return;
-	events.emit(`${channel}:reply:${id}`, payload);
-}
-
-function textOf(result: Awaited<ReturnType<typeof handleTeamTool>>): string {
-	return result.content?.map((item) => item.type === "text" ? item.text : "").join("\n") ?? "";
-}
-
-function on(events: EventBusLike, channel: string, handler: (raw: unknown) => void): () => void {
-	const unsub = events.on(channel, handler);
-	return typeof unsub === "function" ? unsub : () => {};
-}
-
-export function registerPiCrewRpc(events: EventBusLike | undefined, getCtx: () => ExtensionContext | undefined): PiCrewRpcHandle | undefined {
-	if (!events) return undefined;
-	const unsubs = [
-		on(events, "pi-crew:rpc:ping", (raw) => reply(events, "pi-crew:rpc:ping", requestId(raw), { success: true, data: { version: PI_CREW_RPC_VERSION } })),
-		on(events, "pi-crew:rpc:run", async (raw) => {
-			const id = requestId(raw);
-			try {
-				const ctx = getCtx();
-				if (!ctx) throw new Error("No active pi-crew session context.");
-				const params: TeamToolParamsValue = raw && typeof raw === "object" && !Array.isArray(raw) ? { ...(raw as object), action: "run" } as TeamToolParamsValue : { action: "run" };
-				const result = await handleTeamTool(params, ctx);
-				reply(events, "pi-crew:rpc:run", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: result.details });
-			} catch (error) {
-				reply(events, "pi-crew:rpc:run", id, { success: false, error: error instanceof Error ? error.message : String(error) });
-			}
-		}),
-		on(events, "pi-crew:rpc:status", async (raw) => {
-			const id = requestId(raw);
-			try {
-				const ctx = getCtx();
-				if (!ctx) throw new Error("No active pi-crew session context.");
-				const runId = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as { runId?: string }).runId : undefined;
-				const result = await handleTeamTool({ action: "status", runId }, ctx);
-				reply(events, "pi-crew:rpc:status", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: { text: textOf(result), details: result.details } });
-			} catch (error) {
-				reply(events, "pi-crew:rpc:status", id, { success: false, error: error instanceof Error ? error.message : String(error) });
-			}
-		}),
-		on(events, "pi-crew:live-control", (raw) => {
-			const request = parseLiveControlRealtimeMessage(raw);
-			if (request) publishLiveControlRealtime(request);
-		}),
-		on(events, "pi-crew:rpc:live-control", async (raw) => {
-			const id = requestId(raw);
-			try {
-				const ctx = getCtx();
-				if (!ctx) throw new Error("No active pi-crew session context.");
-				const obj = raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
-				const result = await handleTeamTool({ action: "api", runId: typeof obj.runId === "string" ? obj.runId : undefined, config: { operation: typeof obj.operation === "string" ? obj.operation : "steer-agent", agentId: obj.agentId, message: obj.message, prompt: obj.prompt } }, ctx);
-				reply(events, "pi-crew:rpc:live-control", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: { text: textOf(result), details: result.details } });
-			} catch (error) {
-				reply(events, "pi-crew:rpc:live-control", id, { success: false, error: error instanceof Error ? error.message : String(error) });
-			}
-		}),
-	];
-	return { unsubscribe: () => unsubs.forEach((unsub) => unsub()) };
-}
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { TeamToolParamsValue } from "../schema/team-tool-schema.ts";
+// Lazy-loaded to avoid pulling team-tool.ts (and its entire runtime chain) into module load.
+import type { handleTeamTool as HandleTeamToolFn } from "./team-tool.ts";
+let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
+async function handleTeamTool(params: Parameters<typeof HandleTeamToolFn>[0], ctx: Parameters<typeof HandleTeamToolFn>[1]): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
+	if (!_cachedHandleTeamTool) {
+		const mod = await import("./team-tool.ts");
+		_cachedHandleTeamTool = mod.handleTeamTool;
+	}
+	return _cachedHandleTeamTool(params, ctx);
+}
+import { parseLiveControlRealtimeMessage, publishLiveControlRealtime } from "../runtime/live-control-realtime.ts";
+
+export interface EventBusLike {
+	on(event: string, handler: (data: unknown) => void): (() => void) | void;
+	emit(event: string, data: unknown): void;
+}
+
+export type RpcReply<T = unknown> = { success: true; data?: T } | { success: false; error: string };
+export const PI_CREW_RPC_VERSION = 1;
+
+export interface PiCrewRpcHandle {
+	unsubscribe(): void;
+}
+
+function requestId(raw: unknown): string | undefined {
+	return raw && typeof raw === "object" && !Array.isArray(raw) && typeof (raw as { requestId?: unknown }).requestId === "string" ? (raw as { requestId: string }).requestId : undefined;
+}
+
+function reply(events: EventBusLike, channel: string, id: string | undefined, payload: RpcReply): void {
+	if (!id) return;
+	events.emit(`${channel}:reply:${id}`, payload);
+}
+
+function textOf(result: Awaited<ReturnType<typeof handleTeamTool>>): string {
+	return result.content?.map((item) => item.type === "text" ? item.text : "").join("\n") ?? "";
+}
+
+function on(events: EventBusLike, channel: string, handler: (raw: unknown) => void): () => void {
+	const unsub = events.on(channel, handler);
+	return typeof unsub === "function" ? unsub : () => {};
+}
+
+export function registerPiCrewRpc(events: EventBusLike | undefined, getCtx: () => ExtensionContext | undefined): PiCrewRpcHandle | undefined {
+	if (!events) return undefined;
+	const unsubs = [
+		on(events, "pi-crew:rpc:ping", (raw) => reply(events, "pi-crew:rpc:ping", requestId(raw), { success: true, data: { version: PI_CREW_RPC_VERSION } })),
+		on(events, "pi-crew:rpc:run", async (raw) => {
+			const id = requestId(raw);
+			try {
+				const ctx = getCtx();
+				if (!ctx) throw new Error("No active pi-crew session context.");
+				// Validate payload: only allow known fields from TeamToolParamsValue
+				const ALLOWED_RPC_RUN_KEYS = new Set(["goal", "team", "workflow", "async", "cwd", "config", "skill", "model"]);
+				let params: TeamToolParamsValue;
+				if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+					const filtered: Record<string, unknown> = { ...(raw as object) };
+					// Strip any keys not in the allowlist to prevent injection of unexpected fields
+					for (const key of Object.keys(filtered)) {
+						if (!ALLOWED_RPC_RUN_KEYS.has(key)) delete filtered[key];
+					}
+					params = { ...filtered, action: "run" } as TeamToolParamsValue;
+				} else {
+					params = { action: "run" };
+				}
+				const result = await handleTeamTool(params, ctx);
+				reply(events, "pi-crew:rpc:run", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: result.details });
+			} catch (error) {
+				reply(events, "pi-crew:rpc:run", id, { success: false, error: error instanceof Error ? error.message : String(error) });
+			}
+		}),
+		on(events, "pi-crew:rpc:status", async (raw) => {
+			const id = requestId(raw);
+			try {
+				const ctx = getCtx();
+				if (!ctx) throw new Error("No active pi-crew session context.");
+				const runId = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as { runId?: string }).runId : undefined;
+				const result = await handleTeamTool({ action: "status", runId }, ctx);
+				reply(events, "pi-crew:rpc:status", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: { text: textOf(result), details: result.details } });
+			} catch (error) {
+				reply(events, "pi-crew:rpc:status", id, { success: false, error: error instanceof Error ? error.message : String(error) });
+			}
+		}),
+		on(events, "pi-crew:live-control", (raw) => {
+			const request = parseLiveControlRealtimeMessage(raw);
+			if (request) publishLiveControlRealtime(request);
+		}),
+		on(events, "pi-crew:rpc:live-control", async (raw) => {
+			const id = requestId(raw);
+			try {
+				const ctx = getCtx();
+				if (!ctx) throw new Error("No active pi-crew session context.");
+				const obj = raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
+				const result = await handleTeamTool({ action: "api", runId: typeof obj.runId === "string" ? obj.runId : undefined, config: { operation: typeof obj.operation === "string" ? obj.operation : "steer-agent", agentId: obj.agentId, message: obj.message, prompt: obj.prompt } }, ctx);
+				reply(events, "pi-crew:rpc:live-control", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: { text: textOf(result), details: result.details } });
+			} catch (error) {
+				reply(events, "pi-crew:rpc:live-control", id, { success: false, error: error instanceof Error ? error.message : String(error) });
+			}
+		}),
+	];
+	return { unsubscribe: () => unsubs.forEach((unsub) => unsub()) };
+}

package/src/extension/project-init.ts

@@ -2,12 +2,14 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { configPath as globalConfigPath } from "../config/config.ts";
 import { DEFAULT_UI } from "../config/defaults.ts";
+import { injectGuidance, standardGuidanceBlocks } from "../config/markers.ts";
 import { packageRoot, projectCrewRoot, projectPiRoot } from "../utils/paths.ts";
 
 export interface ProjectInitOptions {
 	copyBuiltins?: boolean;
 	overwrite?: boolean;
 	configScope?: "global" | "project" | "none";
+	ignoreMethod?: "gitignore" | "exclude";
 }
 
 export interface ProjectInitResult {
@@ -20,6 +22,8 @@ export interface ProjectInitResult {
 	configScope: "global" | "project" | "none";
 	configCreated: boolean;
 	configSkipped: boolean;
+	guidancePath: string;
+	guidanceModified: boolean;
 }
 
 function ensureDir(dir: string, createdDirs: string[]): void {
@@ -121,16 +125,44 @@ export function initializeProject(cwd: string, options: ProjectInitOptions = {})
 		copyBuiltinDir("workflows", workflowsDir, options.overwrite === true, copiedFiles, skippedFiles);
 	}
 
-	const gitignorePath = path.join(cwd, ".gitignore");
+	const ignoreMethod = options.ignoreMethod ?? "gitignore";
 	const desired = [`${ignorePrefix}/state/`, `${ignorePrefix}/artifacts/`, `${ignorePrefix}/worktrees/`, `${ignorePrefix}/imports/`];
+	const gitignorePath = ignoreMethod === "exclude"
+		? path.join(cwd, ".git", "info", "exclude")
+		: path.join(cwd, ".gitignore");
+	let gitignoreUpdated = false;
+	if (ignoreMethod === "exclude") {
+		// Ensure .git/info/ directory exists
+		const infoDir = path.dirname(gitignorePath);
+		if (!fs.existsSync(infoDir)) {
+			fs.mkdirSync(infoDir, { recursive: true });
+		}
+	}
 	const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, "utf-8") : "";
 	const missing = desired.filter((entry) => !existing.split(/\r?\n/).includes(entry));
-	let gitignoreUpdated = false;
 	if (missing.length > 0) {
 		const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-		fs.writeFileSync(gitignorePath, `${existing}${prefix}\n# pi-crew runtime state\n${missing.join("\n")}\n`, "utf-8");
+		const comment = "# pi-crew runtime state";
+		fs.writeFileSync(gitignorePath, `${existing}${prefix}\n${comment}\n${missing.join("\n")}\n`, "utf-8");
 		gitignoreUpdated = true;
 	}
 
-	return { createdDirs, copiedFiles, skippedFiles, gitignorePath, gitignoreUpdated, configPath, configScope, configCreated, configSkipped };
+	// Inject guidance into project AGENTS.md (or similar) using marker-based injection.
+	const guidancePath = path.join(cwd, "AGENTS.md");
+	const version = getPackageVersion();
+	const guidanceResult = injectGuidance(guidancePath, standardGuidanceBlocks(version));
+
+	return { createdDirs, copiedFiles, skippedFiles, gitignorePath, gitignoreUpdated, configPath, configScope, configCreated, configSkipped, guidancePath, guidanceModified: guidanceResult.modified };
+}
+
+/** Read the current package version from the nearest package.json. */
+function getPackageVersion(): string {
+	try {
+		const pkgPath = path.join(packageRoot(), "package.json");
+		const raw = fs.readFileSync(pkgPath, "utf-8");
+		const parsed: { version?: string } = JSON.parse(raw) as { version?: string };
+		return parsed.version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
 }

package/src/extension/register.ts

@@ -9,7 +9,7 @@ import { notifyActiveRuns } from "./session-summary.ts";
 import { LiveRunSidebar } from "../ui/live-run-sidebar.ts";
 import { registerPiCrewRpc, type PiCrewRpcHandle } from "./cross-extension-rpc.ts";
 import { stopCrewWidget, updateCrewWidget, type CrewWidgetState } from "../ui/crew-widget.ts";
-import { clearPiCrewPowerbar, disposePowerbarCoalescer, registerPiCrewPowerbarSegments, requestPowerbarUpdate, updatePiCrewPowerbar } from "../ui/powerbar-publisher.ts";
+import { clearPiCrewPowerbar, disposePowerbarCoalescer, registerPiCrewPowerbarSegments, requestPowerbarUpdate, resetPowerbarDedupState, updatePiCrewPowerbar } from "../ui/powerbar-publisher.ts";
 import { loadRunManifestById, updateRunStatus } from "../state/state-store.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { terminateActiveChildPiProcesses } from "../subagents/spawn.ts";
@@ -38,6 +38,7 @@ import { OTLPExporter } from "../observability/exporters/otlp-exporter.ts";
 import { HeartbeatWatcher } from "../runtime/heartbeat-watcher.ts";
 import { appendDeadletter } from "../runtime/deadletter.ts";
 import { cancelOrphanedRuns, detectInterruptedRuns, purgeStaleActiveRunIndex } from "../runtime/crash-recovery.ts";
+import { pruneFinishedRuns, pruneUserLevelRuns } from "../extension/run-maintenance.ts";
 import { DeliveryCoordinator } from "../runtime/delivery-coordinator.ts";
 import { OverflowRecoveryTracker } from "../runtime/overflow-recovery.ts";
 import { tryRegisterSessionCleanup } from "../runtime/session-resources.ts";
@@ -301,9 +302,9 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 				.finally(() => {
 					foregroundControllers.delete(key);
 					const ownerCurrent = isContextCurrent(ctx, ownerGeneration);
-					if (ownerCurrent && ctx.hasUI) {
-						setWorkingIndicator(ctx);
-						ctx.ui.setWorkingMessage();
+					if (ctx.hasUI) {
+						// Always clear working message/spinner — stale spinners for completed runs are confusing.
+						try { setWorkingIndicator(ctx); ctx.ui.setWorkingMessage(); } catch { /* ignore */ }
 					}
 					if (ownerCurrent && runId) {
 						const loaded = loadRunManifestById(ctx.cwd, runId);
@@ -344,7 +345,11 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	time("register.policy");
 	registerAutonomousPolicy(pi);
 	time("register.rpc");
-	rpcHandle = registerPiCrewRpc((pi as unknown as { events?: Parameters<typeof registerPiCrewRpc>[0] }).events, () => currentCtx);
+	function getPiEvents(): Parameters<typeof registerPiCrewRpc>[0] | undefined {
+		if (pi && typeof pi === "object" && "events" in pi) return (pi as unknown as Record<string, unknown>).events as Parameters<typeof registerPiCrewRpc>[0];
+		return undefined;
+	}
+	rpcHandle = registerPiCrewRpc(getPiEvents(), () => currentCtx);
 
 	const cleanupRuntime = (): void => {
 		if (cleanedUp) return;
@@ -410,34 +415,64 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		notifyActiveRuns(ctx);
 
 		// Auto-cancel orphaned runs from dead sessions
-		const currentSessionId = (ctx as unknown as Record<string, unknown>).sessionId as string | undefined;
-		if (currentSessionId) {
+		const currentSessionId = (typeof ctx === "object" && ctx !== null && "sessionId" in ctx ? (ctx as Record<string, unknown>).sessionId : undefined) as string | undefined;
+
+		// Defer ALL heavy cleanup to after the session_start handler returns.
+		// These operations involve synchronous directory scanning (readdirSync, readFileSync)
+		// which can take 100ms–1s+ on Windows. They MUST NOT block the session_start event.
+		setTimeout(() => {
+			if (cleanedUp || sessionGeneration !== ownerGeneration) return; // session switched while we waited
+
+			// Auto-cancel orphaned runs
+			if (currentSessionId) {
+				try {
+					const { cancelled } = cancelOrphanedRuns(ctx.cwd, getManifestCache(ctx.cwd), currentSessionId);
+					if (cancelled.length > 0) {
+						notifyOperator({ id: `orphan_cleanup`, severity: "info", source: "crash-recovery", title: `Cleaned up ${cancelled.length} orphaned run(s)`, body: `Runs from previous sessions were auto-cancelled: ${cancelled.join(", ")}` });
+					}
+				} catch (error) {
+					logInternalError("register.sessionStart.orphanCleanup", error);
+				}
+			}
+
+			// Global purge of stale active-run-index entries
 			try {
-				const { cancelled } = cancelOrphanedRuns(ctx.cwd, getManifestCache(ctx.cwd), currentSessionId);
-				if (cancelled.length > 0) {
-					notifyOperator({ id: `orphan_cleanup`, severity: "info", source: "crash-recovery", title: `Cleaned up ${cancelled.length} orphaned run(s)`, body: `Runs from previous sessions were auto-cancelled: ${cancelled.join(", ")}` });
+				const { purged } = purgeStaleActiveRunIndex();
+				if (purged.length > 0) {
+					notifyOperator({ id: `active_index_purge`, severity: "info", source: "crash-recovery", title: `Purged ${purged.length} stale active-run-index entr${purged.length === 1 ? "y" : "ies"}`, body: `Cleaned up global active run index` });
 				}
 			} catch (error) {
-				logInternalError("register.sessionStart.orphanCleanup", error);
+				logInternalError("register.sessionStart.globalIndexPurge", error);
 			}
-		}
 
-		// Global purge of stale active-run-index entries (temp dirs, dead workers, etc.)
-		try {
-			const { purged } = purgeStaleActiveRunIndex();
-			if (purged.length > 0) {
-				notifyOperator({ id: `active_index_purge`, severity: "info", source: "crash-recovery", title: `Purged ${purged.length} stale active-run-index entr${purged.length === 1 ? "y" : "ies"}`, body: `Cleaned up global active run index` });
+			// Auto-prune finished project-level run directories (keep 10 most recent)
+			try {
+				const { removed } = pruneFinishedRuns(ctx.cwd, 10);
+				if (removed.length > 0) {
+					notifyOperator({ id: `auto_prune_project`, severity: "info", source: "run-maintenance", title: `Auto-pruned ${removed.length} finished project run(s)`, body: `Removed old finished runs: ${removed.join(", ")}` });
+				}
+			} catch (error) {
+				logInternalError("register.sessionStart.autoPruneProject", error);
 			}
-		} catch (error) {
-			logInternalError("register.sessionStart.globalIndexPurge", error);
-		}
+
+			// Auto-prune finished user-level run directories (keep 10 most recent)
+			try {
+				const { removed } = pruneUserLevelRuns(10);
+				if (removed.length > 0) {
+					notifyOperator({ id: `auto_prune_user`, severity: "info", source: "run-maintenance", title: `Auto-pruned ${removed.length} finished user-level run(s)`, body: `Removed old finished runs: ${removed.join(", ")}` });
+				}
+			} catch (error) {
+				logInternalError("register.sessionStart.autoPruneUser", error);
+			}
+		}, 0);
+
 
 		const loadedConfig = loadConfig(ctx.cwd);
 		autoRecoveryLast.clear();
 		configureNotifications(ctx);
 		configureObservability(ctx);
 		configureDeliveryCoordinator();
-		const sessionId = ctx.sessionManager?.getSessionId?.() ?? (ctx as unknown as Record<string, unknown>).sessionId;
+		const sessionId = ctx.sessionManager?.getSessionId?.() ?? (typeof ctx === "object" && ctx !== null && "sessionId" in ctx ? (ctx as Record<string, unknown>).sessionId : undefined);
 		if (typeof sessionId === "string" && sessionId) deliveryCoordinator?.activate(sessionId);
 		tryRegisterSessionCleanup(pi, () => { terminateActiveChildPiProcesses(); cleanupRuntime(); });
 		registerPiCrewPowerbarSegments(pi.events, loadedConfig.config.ui);
@@ -542,7 +577,16 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		const fallbackMs = loadedConfig.config.ui?.dashboardLiveRefreshMs ?? DEFAULT_UI.refreshMs;
 		renderScheduler = new RenderScheduler(pi.events, renderTick, {
 			fallbackMs,
-			onInvalidate: () => getRunSnapshotCache(ctx.cwd).invalidate(),
+			onInvalidate: (payload: unknown) => {
+				// Invalidate only the specific run, not the entire cache.
+				// Full cache.clear() causes widget flicker — the widget component's
+				// render() may run before renderTick rebuilds the preloaded frame,
+				// seeing an empty cache and returning no agents.
+				const runId = typeof payload === "object" && payload !== null && "runId" in payload && typeof (payload as { runId: unknown }).runId === "string"
+					? (payload as { runId: string }).runId
+					: undefined;
+				getRunSnapshotCache(ctx.cwd).invalidate(runId);
+			},
 		});
 		// Start async preload loop — refreshes snapshot cache in background
 		startPreloadLoop(fallbackMs);
@@ -561,6 +605,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 			logInternalError("register.session-before-switch", `Switching session with ${pendingCount} pending deliveries`);
 		}
 		deliveryCoordinator?.deactivate();
+		resetPowerbarDedupState();
 		stopAsyncRunNotifier(notifierState);
 		stopSessionBoundSubagents();
 	});

package/src/extension/registration/commands.ts

@@ -1,20 +1,39 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { loadConfig } from "../../config/config.ts";
-import { handleTeamTool } from "../team-tool.ts";
+// Lazy-loaded: team-tool.ts pulls in entire runtime chain (1.4s+).
+import type { handleTeamTool as HandleTeamToolFn } from "../team-tool.ts";
+let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
+let _handleTeamToolPromise: Promise<typeof HandleTeamToolFn> | undefined;
+async function handleTeamTool(params: Parameters<typeof HandleTeamToolFn>[0], ctx: Parameters<typeof HandleTeamToolFn>[1]): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
+	if (!_cachedHandleTeamTool) {
+		if (!_handleTeamToolPromise) {
+			_handleTeamToolPromise = import("../team-tool.ts").then((mod) => {
+				_cachedHandleTeamTool = mod.handleTeamTool;
+				return mod.handleTeamTool;
+			});
+		}
+		const fn = await _handleTeamToolPromise;
+		return fn(params, ctx);
+	}
+	return _cachedHandleTeamTool(params, ctx);
+}
 import { withSessionId } from "../team-tool/context.ts";
 import { piTeamsHelp } from "../help.ts";
 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 { AnimatedMascot } from "../../ui/mascot.ts";
 import * as path from "node:path";
-import { RunDashboard, type RunDashboardSelection } from "../../ui/run-dashboard.ts";
-import { DurableTextViewer } from "../../ui/transcript-viewer.ts";
-import { ConfirmOverlay, type ConfirmOptions } from "../../ui/overlays/confirm-overlay.ts";
-import { MailboxDetailOverlay, type MailboxAction } from "../../ui/overlays/mailbox-detail-overlay.ts";
-import { MailboxComposeOverlay, type MailboxComposeResult } from "../../ui/overlays/mailbox-compose-overlay.ts";
-import { AgentPickerOverlay } from "../../ui/overlays/agent-picker-overlay.ts";
+// Heavy UI modules — lazy-loaded because they're only used in /crew commands.
+// RunDashboard (288ms), DurableTextViewer (658ms), Overlays are unnecessary at Pi startup.
+import type { RunDashboard as RunDashboardType, RunDashboardSelection } from "../../ui/run-dashboard.ts";
+import type { DurableTextViewer as DurableTextViewerType } from "../../ui/transcript-viewer.ts";
+import type { ConfirmOverlay as ConfirmOverlayType, ConfirmOptions } from "../../ui/overlays/confirm-overlay.ts";
+import type { MailboxDetailOverlay as MailboxDetailOverlayType, MailboxAction } from "../../ui/overlays/mailbox-detail-overlay.ts";
+import type { MailboxComposeOverlay as MailboxComposeOverlayType, MailboxComposeResult } from "../../ui/overlays/mailbox-compose-overlay.ts";
+import type { AgentPickerOverlay as AgentPickerOverlayType } from "../../ui/overlays/agent-picker-overlay.ts";
+import type { AnimatedMascot as AnimatedMascotType } from "../../ui/mascot.ts";
+// Eagerly import lightweight modules
 import { dispatchDiagnosticExport, dispatchHealthRecovery, dispatchKillStaleWorkers, dispatchMailboxAck, dispatchMailboxAckAll, dispatchMailboxCompose, dispatchMailboxNudge } from "../../ui/run-action-dispatcher.ts";
 import { DEFAULT_UI } from "../../config/defaults.ts";
 import { listRecentDiagnostic } from "../../runtime/diagnostic-export.ts";
@@ -35,13 +54,58 @@ export interface RegisterTeamCommandsDeps {
 	dismissNotifications?: () => void;
 }
 
+// Lazy-loaded UI module cache — avoids importing 900ms+ of UI at Pi startup.
+// These modules are only needed when user invokes /crew commands.
+let _uiCache: {
+	RunDashboard: typeof RunDashboardType;
+	DurableTextViewer: typeof DurableTextViewerType;
+	ConfirmOverlay: typeof ConfirmOverlayType;
+	MailboxDetailOverlay: typeof MailboxDetailOverlayType;
+	MailboxComposeOverlay: typeof MailboxComposeOverlayType;
+	AgentPickerOverlay: typeof AgentPickerOverlayType;
+	AnimatedMascot: typeof AnimatedMascotType;
+} | undefined;
+let _uiCachePromise: Promise<NonNullable<typeof _uiCache>> | undefined;
+async function ui(): Promise<NonNullable<typeof _uiCache>> {
+	if (!_uiCache) {
+		if (!_uiCachePromise) {
+			_uiCachePromise = (async () => {
+				const [rd, tv, co, md, mc, ap, ma] = await Promise.all([
+					import("../../ui/run-dashboard.ts"),
+					import("../../ui/transcript-viewer.ts"),
+					import("../../ui/overlays/confirm-overlay.ts"),
+					import("../../ui/overlays/mailbox-detail-overlay.ts"),
+					import("../../ui/overlays/mailbox-compose-overlay.ts"),
+					import("../../ui/overlays/agent-picker-overlay.ts"),
+					import("../../ui/mascot.ts"),
+				]);
+				const cache = {
+					RunDashboard: rd.RunDashboard,
+					DurableTextViewer: tv.DurableTextViewer,
+					ConfirmOverlay: co.ConfirmOverlay,
+					MailboxDetailOverlay: md.MailboxDetailOverlay,
+					MailboxComposeOverlay: mc.MailboxComposeOverlay,
+					AgentPickerOverlay: ap.AgentPickerOverlay,
+					AnimatedMascot: ma.AnimatedMascot,
+				};
+				_uiCache = cache;
+				return cache;
+			})();
+		}
+		return _uiCachePromise;
+	}
+	return _uiCache;
+}
+
 async function openConfirm(ctx: ExtensionCommandContext, options: ConfirmOptions): Promise<boolean> {
 	if (!ctx.hasUI) return false;
+	const { ConfirmOverlay } = await ui();
 	return await ctx.ui.custom<boolean>((_tui, theme, _keybindings, done) => new ConfirmOverlay(options, done, theme), { overlay: true, overlayOptions: { width: 64, maxHeight: "70%", anchor: "center" } });
 }
 
 async function handleMailboxDashboardAction(ctx: ExtensionCommandContext, runId: string): Promise<void> {
 	if (!ctx.hasUI) return;
+	const { MailboxDetailOverlay } = await ui();
 	const action = await ctx.ui.custom<MailboxAction | undefined>((_tui, theme, _keybindings, done) => new MailboxDetailOverlay({ runId, cwd: ctx.cwd, done, theme }), { overlay: true, overlayOptions: { width: "90%", maxHeight: "85%", anchor: "center" } });
 	if (!action || action.type === "close") return;
 	let resultMessage: string | undefined;
@@ -57,6 +121,7 @@ async function handleMailboxDashboardAction(ctx: ExtensionCommandContext, runId:
 		ok = result.ok;
 		resultMessage = result.message;
 	} else if (action.type === "compose") {
+		const { MailboxComposeOverlay } = await ui();
 		const compose = await ctx.ui.custom<MailboxComposeResult>((_tui, theme, _keybindings, done) => new MailboxComposeOverlay({ done, theme }), { overlay: true, overlayOptions: { width: "90%", maxHeight: "85%", anchor: "center" } });
 		if (compose.type === "cancel") return;
 		const result = await dispatchMailboxCompose(ctx as ExtensionContext, runId, compose.payload);
@@ -65,6 +130,7 @@ async function handleMailboxDashboardAction(ctx: ExtensionCommandContext, runId:
 	} else if (action.type === "nudge") {
 		let agentId = action.agentId;
 		if (!agentId) {
+			const { AgentPickerOverlay } = await ui();
 			const picked = await ctx.ui.custom<{ agentId: string } | undefined>((_tui, theme, _keybindings, done) => new AgentPickerOverlay({ cwd: ctx.cwd, runId, done, theme }), { overlay: true, overlayOptions: { width: 72, maxHeight: "75%", anchor: "center" } });
 			agentId = picked?.agentId;
 		}
@@ -272,6 +338,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 		if (ctx.hasUI && loaded) {
 			const agent = readCrewAgents(loaded.manifest).find((item) => item.taskId === selected?.taskId || item.id === selected?.taskId) ?? readCrewAgents(loaded.manifest)[0];
 			const resultText = agent?.resultArtifactPath ? commandText(await handleTeamTool({ action: "api", runId: selected?.runId ?? "", config: { operation: "read-agent-output", agentId: agent.taskId, maxBytes: 64_000 } }, teamCommandContext(ctx))) : "(no result)";
+			const { DurableTextViewer } = await ui();
 			await ctx.ui.custom<undefined>((_tui, theme, _keybindings, done) => new DurableTextViewer("pi-crew result", `${selected?.runId ?? ""}:${agent?.taskId ?? "unknown"}`, resultText.split(/\r?\n/), theme, done), { overlay: true, overlayOptions: { width: "90%", maxHeight: "85%", anchor: "center" } });
 			return;
 		}
@@ -292,6 +359,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 			const uiConfig = loadConfig(ctx.cwd).config.ui;
 			const rightPanel = (uiConfig?.dashboardPlacement ?? DEFAULT_UI.dashboardPlacement) === "right";
 			const width = rightPanel ? Math.min(90, Math.max(40, uiConfig?.dashboardWidth ?? DEFAULT_UI.dashboardWidth)) : "90%";
+			const { RunDashboard } = await ui();
 			const selection = await ctx.ui.custom<RunDashboardSelection | undefined>((_tui, theme, _keybindings, done) => new RunDashboard(runs, done, theme, { placement: rightPanel ? "right" : "center", showModel: uiConfig?.showModel, showTokens: uiConfig?.showTokens, showTools: uiConfig?.showTools, snapshotCache: deps.getRunSnapshotCache?.(ctx.cwd), runProvider: () => deps.getManifestCache(ctx.cwd).list(50), registry: deps.getMetricRegistry?.() }), { overlay: true, overlayOptions: rightPanel ? { width, minWidth: 40, maxHeight: "100%", anchor: "top-right", offsetX: 0, offsetY: 0, margin: { top: 0, right: 0, bottom: 0, left: 0 } } : { width, maxHeight: "90%", anchor: "center", margin: 2 } });
 			if (!selection) return;
 			if (selection.action === "reload") continue;
@@ -325,6 +393,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 		const effectArg = tokens.find((t) => ["random", "none", "typewriter", "scanline", "rain", "fade", "crt", "glitch", "dissolve"].includes(t));
 		const style = (styleArg as "cat" | "armin" | undefined) ?? uiConfig?.mascotStyle ?? DEFAULT_UI.mascotStyle;
 		const effect = (effectArg as "random" | "none" | "typewriter" | "scanline" | "rain" | "fade" | "crt" | "glitch" | "dissolve" | undefined) ?? uiConfig?.mascotEffect ?? DEFAULT_UI.mascotEffect;
+		const { AnimatedMascot } = await ui();
 		await ctx.ui.custom<undefined>((tui, theme, _keybindings, done) => new AnimatedMascot(theme, () => done(undefined), { frameIntervalMs: style === "armin" ? 33 : 180, autoCloseMs: 7000, requestRender: () => requestRenderTarget(tui), style, effect }), { overlay: true, overlayOptions: { width: style === "armin" ? 48 : 62, maxHeight: "85%", anchor: "center" } });
 	} });
 

package/src/extension/registration/subagent-tools.ts

@@ -1,7 +1,16 @@
 import type { ExtensionAPI, ToolDefinition } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { handleTeamTool } from "../team-tool.ts";
+// Lazy-loaded: team-tool.ts pulls in entire runtime chain.
+import type { handleTeamTool as HandleTeamToolFn } from "../team-tool.ts";
+let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
+async function handleTeamTool(params: Parameters<typeof HandleTeamToolFn>[0], ctx: Parameters<typeof HandleTeamToolFn>[1]): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
+	if (!_cachedHandleTeamTool) {
+		const mod = await import("../team-tool.ts");
+		_cachedHandleTeamTool = mod.handleTeamTool;
+	}
+	return _cachedHandleTeamTool(params, ctx);
+}
 import { checkSubagentSpawnPermission, currentCrewRole } from "../../runtime/role-permission.ts";
 import { readPersistedSubagentRecord, savePersistedSubagentRecord, type SubagentManager, type SubagentSpawnOptions } from "../../subagents/manager.ts";
 import { loadConfig } from "../../config/config.ts";

package/src/extension/registration/team-tool.ts

@@ -9,7 +9,16 @@ import type { createManifestCache } from "../../runtime/manifest-cache.ts";
 import type { createRunSnapshotCache } from "../../ui/run-snapshot-cache.ts";
 import type { MetricRegistry } from "../../observability/metric-registry.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
-import { handleTeamTool } from "../team-tool.ts";
+// Team tool handler — lazy-loaded because team-tool.ts imports many modules
+import type { handleTeamTool as HandleTeamToolFn } from "../team-tool.ts";
+let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
+async function handleTeamTool(params: Parameters<typeof HandleTeamToolFn>[0], ctx: Parameters<typeof HandleTeamToolFn>[1]): Promise<ReturnType<typeof HandleTeamToolFn>> {
+	if (!_cachedHandleTeamTool) {
+		const mod = await import("../team-tool.ts");
+		_cachedHandleTeamTool = mod.handleTeamTool;
+	}
+	return _cachedHandleTeamTool(params, ctx);
+}
 import { withSessionId } from "../team-tool/context.ts";
 import { toolResult } from "../tool-result.ts";