pi-crew 0.9.51 → 0.9.53

package/src/extension/registration/lifecycle-handlers.ts

@@ -1,923 +0,0 @@
-/**
- * Lifecycle handler installer for pi-crew.
- *
- * Owns:
- *   • `session_start` — heavy setup (config, scheduler, render loop, watchers,
- *     deferred crash recovery). This is the bulk of the orchestrator's
- *     per-session work, extracted here so `register.ts` stays thin.
- *   • `session_shutdown` — reason-aware cleanup (quit/reload aborts
- *     foreground runs; resume/new/fork preserves them).
- *   • `session_before_switch` — graceful session switch handoff.
- *
- * Imports here are kept top-level (non-lazy) on purpose: this module IS
- * where the heavy work happens, so there is no cold-start benefit to
- * deferring it. The session_start handler internally uses lazy imports
- * for its own per-call optional work (foreground-watchdog, atomic-write).
- */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { loadConfig } from "../../config/config.ts";
-import { DEFAULT_UI } from "../../config/defaults.ts";
-import { pruneFinishedRuns, pruneUserLevelRuns } from "../../extension/run-maintenance.ts";
-import { type BrokerSpawnCredentials, setActiveBrokerIssuer } from "../../runtime/broker-issuer.ts";
-import { reconcileAllStaleRuns } from "../../runtime/crash-recovery.ts";
-import { CrewBroker } from "../../runtime/crew-broker.ts";
-import { listLiveAgents } from "../../runtime/live-agent-manager.ts";
-import type { createManifestCache } from "../../runtime/manifest-cache.ts";
-import { cleanupOrphanWorkers } from "../../runtime/orphan-worker-registry.ts";
-import { cleanupLegacyOrphanTempDirs, cleanupOrphanTempDirs, currentCrewDepth } from "../../runtime/pi-args.ts";
-import { CrewScheduler, type ScheduledJob } from "../../runtime/scheduler.ts";
-import { tryRegisterSessionCleanup } from "../../runtime/session-resources.ts";
-import { createSessionSnapshot } from "../../runtime/session-snapshot.ts";
-import { applyCrewSettingsToConfig, loadCrewSettings } from "../../runtime/settings-store.ts";
-import { loadRunManifestById } from "../../state/state-store.ts";
-import type { TeamRunManifest } from "../../state/types.ts";
-import { terminateActiveChildPiProcesses } from "../../subagents/spawn.ts";
-import { summarizeHeartbeats } from "../../ui/heartbeat-aggregator.ts";
-import { requestRender, setExtensionWidget } from "../../ui/pi-ui-compat.ts";
-import {
-	registerPiCrewPowerbarSegments,
-	requestPowerbarUpdate,
-	resetPowerbarDedupState,
-	updatePiCrewPowerbar,
-} from "../../ui/powerbar-publisher.ts";
-import { RenderScheduler } from "../../ui/render-scheduler.ts";
-import { runEventBus } from "../../ui/run-event-bus.ts";
-import type { createRunSnapshotCache } from "../../ui/run-snapshot-cache.ts";
-import { updateCrewWidget } from "../../ui/widget/index.ts";
-import { logInternalError } from "../../utils/internal-error.ts";
-import { projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
-import { RunWatcherRegistry } from "../../utils/run-watcher-registry.ts";
-import { extractBrokerSessionId } from "../../utils/session-utils.ts";
-import { getBrokerSocketPath } from "../../utils/socket-path.ts";
-import { startAsyncRunNotifier, stopAsyncRunNotifier } from "../async-notifier.ts";
-import { registerCrewAutocomplete } from "../crew-autocomplete.ts";
-import { notifyActiveRuns } from "../session-summary.ts";
-import { persistScheduledJobUpdate } from "../team-tool/handle-schedule.ts";
-import { handleTeamTool } from "../team-tool.ts";
-import { runArtifactCleanup } from "./artifact-cleanup.ts";
-import type { RegistrationContext } from "./registration-types.ts";
-
-/**
- * Register all session-lifecycle handlers on the ExtensionAPI. The caller
- * (`register.ts`) must have already wired the orchestrator-side cleanup
- * functions into `ctx.cleanupRuntime` and `ctx.cleanupSessionResourcesOnly`.
- */
-export function installSessionLifecycleHandlers(pi: ExtensionAPI, ctx: RegistrationContext): void {
-	installSessionShutdownHandler(pi, ctx);
-	installSessionStartHandler(pi, ctx);
-	installSessionBeforeSwitchHandler(pi, ctx);
-}
-
-/**
- * session_shutdown:
- *   • reason="quit" / "reload" → full cleanup (abort foreground runs).
- *   • reason="resume" / "new" / "fork" → resource cleanup only (preserve
- *     foreground runs; they share the process with the session).
- */
-function installSessionShutdownHandler(pi: ExtensionAPI, ctx: RegistrationContext): void {
-	pi.on("session_shutdown", (event) => {
-		const reason = typeof event === "object" && event !== null && "reason" in event ? (event as { reason: string }).reason : undefined;
-		if (reason === "quit" || reason === "reload") {
-			// Actual shutdown — abort foreground runs and cleanup everything
-			ctx.cleanupRuntime();
-		} else {
-			// Session switch (resume/new/fork) — cleanup resources but preserve foreground runs
-			ctx.cleanupSessionResourcesOnly();
-		}
-	});
-}
-
-/**
- * session_before_switch:
- *   Bump generation, deactivate delivery coordinator, stop async notifier,
- *   abort session-bound subagents. Foreground team runs are NOT aborted here.
- */
-function installSessionBeforeSwitchHandler(pi: ExtensionAPI, ctx: RegistrationContext): void {
-	pi.on("session_before_switch", () => {
-		ctx.sessionGeneration++;
-		const pendingCount = ctx.lifecycleState.deliveryCoordinator?.getPendingCount() ?? 0;
-		try {
-			const activeRuns = ctx.currentCtx
-				? ctx
-						.getManifestCache(ctx.currentCtx.cwd)
-						.list(50)
-						.filter((run) => run.status === "running" || run.status === "queued" || run.status === "blocked")
-				: [];
-			const snapshot = createSessionSnapshot(activeRuns, pendingCount, ctx.sessionGeneration);
-			if (pendingCount > 0 || snapshot.activeRunIds.length > 0)
-				logInternalError("register.session-before-switch", undefined, JSON.stringify(snapshot));
-		} catch (error) {
-			logInternalError("register.session-before-switch.snapshot", error);
-		}
-		if (pendingCount > 0) {
-			logInternalError("register.session-before-switch", `Switching session with ${pendingCount} pending deliveries`);
-		}
-		ctx.lifecycleState.deliveryCoordinator?.deactivate();
-		resetPowerbarDedupState();
-		stopAsyncRunNotifier(ctx.notifierState);
-		ctx.stopSessionBoundSubagents();
-	});
-}
-
-/**
- * session_start — the bulk of pi-crew's per-session work.
- *
- * Pipeline:
- *   1. Resolve session metadata + restore brief mode (best-effort).
- *   2. Bump generation, set currentCtx, register autocomplete (once).
- *   3. Schedule deferred crash recovery (orphan cleanup, stale-reconcile,
- *      auto-prune). MUST run in setTimeout(0) — these block 100ms-1s on
- *      Windows and cannot stall the session_start event.
- *   4. Synchronously: load config + crew settings, start CrewScheduler,
- *      configure notifications/observability/delivery-coordinator,
- *      register Pi-side powerbar segments, start async notifier,
- *      kick off the render scheduler + preload loop + bounded watchers.
- */
-function installSessionStartHandler(pi: ExtensionAPI, ctx: RegistrationContext): void {
-	pi.on("session_start", (_event, extensionCtx) => {
-		runArtifactCleanup(extensionCtx.cwd);
-
-		// Restore brief mode state from session entries (best-effort).
-		try {
-			const entries = extensionCtx.sessionManager?.getEntries?.();
-			if (entries) {
-				// LAZY: brief-mode is only used inside the session-start restore path.
-				import("../../ui/tool-renderers/brief-mode.ts")
-					.then(({ restoreBriefState }) => {
-						restoreBriefState(entries);
-					})
-					.catch(() => {
-						/* non-critical */
-					});
-			}
-		} catch {
-			/* non-critical */
-		}
-
-		ctx.cleanedUp = false;
-		ctx.sessionGeneration++;
-		const ownerGeneration = ctx.sessionGeneration;
-		ctx.currentCtx = extensionCtx;
-		// 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 (!ctx.crewAutocompleteRegistered) {
-			ctx.crewAutocompleteRegistered = true;
-			registerCrewAutocomplete(extensionCtx);
-		}
-		notifyActiveRuns(extensionCtx);
-
-		const currentSessionId = extractBrokerSessionId(extensionCtx);
-		// Phase 0 broker: feed the captured session_id to the controller so
-		// it can issue tokens for child runs in this session. The controller
-		// already gates by flag + root-session; this is a no-op when disabled.
-		ctx.brokerController?.setSessionId(currentSessionId);
-
-		// 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(() => {
-			void runDeferredSessionCleanup(pi, ctx, ownerGeneration, currentSessionId, extensionCtx);
-		}, 0);
-
-		const loadedConfig = loadConfig(extensionCtx.cwd);
-		const crewSettings = loadCrewSettings(extensionCtx.cwd);
-		applyCrewSettingsToConfig(loadedConfig.config, crewSettings);
-
-		// Start scheduler with event-based executor
-		const sessionId =
-			extensionCtx.sessionManager?.getSessionId?.() ??
-			(typeof extensionCtx === "object" && extensionCtx !== null && "sessionId" in extensionCtx
-				? (extensionCtx as Record<string, unknown>).sessionId
-				: undefined);
-		ctx.crewScheduler = setupCrewScheduler(pi, ctx, extensionCtx, sessionId);
-
-		// Wire scheduler into handle-schedule.ts so handlers can add/list jobs.
-		// Uses a global symbol so the module doesn't need a direct circular import.
-		(globalThis as Record<symbol | string, unknown>)[Symbol.for("pi-crew:scheduler")] = ctx.crewScheduler;
-		// Load scheduled jobs from settings if present
-		if (Array.isArray(crewSettings.scheduledJobs)) {
-			for (const job of crewSettings.scheduledJobs) {
-				try {
-					ctx.crewScheduler.add(job as ScheduledJob);
-				} catch {
-					/* skip invalid */
-				}
-			}
-		}
-		ctx.autoRecoveryLast.clear();
-		ctx.configureNotifications(extensionCtx);
-		ctx.configureObservability(extensionCtx);
-		ctx.configureDeliveryCoordinator();
-		if (typeof sessionId === "string" && sessionId) ctx.lifecycleState.deliveryCoordinator?.activate(sessionId);
-		tryRegisterSessionCleanup(pi, () => {
-			terminateActiveChildPiProcesses();
-			ctx.cleanupRuntime();
-		});
-		registerPiCrewPowerbarSegments(pi.events, loadedConfig.config.ui);
-		startAsyncRunNotifier(extensionCtx, ctx.notifierState, loadedConfig.config.notifierIntervalMs ?? DEFAULT_UI.notifierIntervalMs, {
-			generation: ownerGeneration,
-			isCurrent: (generation) => generation === ctx.sessionGeneration && ctx.currentCtx === extensionCtx && !ctx.cleanedUp,
-		});
-		const cache = ctx.getManifestCache(extensionCtx.cwd);
-		updateCrewWidget(extensionCtx, ctx.widgetState, loadedConfig.config.ui, cache, ctx.getRunSnapshotCache(extensionCtx.cwd));
-		updatePiCrewPowerbar(
-			pi.events,
-			extensionCtx.cwd,
-			loadedConfig.config.ui,
-			cache,
-			ctx.getRunSnapshotCache(extensionCtx.cwd),
-			extensionCtx,
-			ctx.widgetState.notificationCount ?? 0,
-		);
-		setupRenderLoop(pi, ctx, extensionCtx, loadedConfig);
-	});
-}
-
-/**
- * Heavy cleanup that runs after session_start returns.
- *
- * Wrapped in setTimeout(0) so the session_start event is not blocked by
- * the synchronous I/O involved (readdirSync, readFileSync) — observed to
- * take 100ms-1s+ on Windows with many runs on disk.
- */
-async function runDeferredSessionCleanup(
-	pi: ExtensionAPI,
-	ctx: RegistrationContext,
-	ownerGeneration: number,
-	currentSessionId: string | undefined,
-	extensionCtx: ExtensionContext,
-): Promise<void> {
-	if (ctx.cleanedUp || ctx.sessionGeneration !== ownerGeneration) return; // session switched while we waited
-
-	// 2.7: load crash-recovery lazily once per session_start cleanup batch.
-	let crashRecovery: Awaited<ReturnType<typeof ctx.importCrashRecovery>> | undefined;
-	try {
-		crashRecovery = await ctx.importCrashRecovery();
-	} catch (error) {
-		logInternalError("register.sessionStart.lazyCrashRecovery", error);
-		return;
-	}
-	if (ctx.cleanedUp || ctx.sessionGeneration !== ownerGeneration) return;
-	const { cancelOrphanedRuns: cancelOrphanedRunsFn, purgeStaleActiveRunIndex: purgeStaleActiveRunIndexFn } = crashRecovery;
-
-	// Auto-cancel orphaned runs
-	if (currentSessionId) {
-		try {
-			const { cancelled } = (
-				cancelOrphanedRunsFn as (
-					cwd: string,
-					cache: ReturnType<typeof createManifestCache>,
-					sessionId: string,
-				) => { cancelled: string[] }
-			)(extensionCtx.cwd, ctx.getManifestCache(extensionCtx.cwd), currentSessionId);
-			if (cancelled.length > 0) {
-				ctx.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);
-		}
-	}
-
-	// Startup cleanup (Fix A): run orphan-temp-dir cleanup
-	try {
-		const orphanTmp = cleanupOrphanTempDirs();
-		const legacyTmp = cleanupLegacyOrphanTempDirs();
-		if (orphanTmp.cleaned > 0 || legacyTmp.cleaned > 0) {
-			ctx.notifyOperator({
-				id: `startup_temp_cleanup_${Date.now()}`,
-				severity: "info",
-				source: "temp-cleanup",
-				title: `Startup cleanup: removed ${orphanTmp.cleaned + legacyTmp.cleaned} orphan temp dir(s)`,
-				body: `${orphanTmp.cleaned} from ~/.pi/agent/pi-crew/tmp/ + ${legacyTmp.cleaned} legacy /tmp/pi-crew-*`,
-			});
-		}
-	} catch (error) {
-		logInternalError("register.sessionStart.startupTempCleanup", error);
-	}
-
-	// Orphan worker cleanup (Fix B): kill stale background-runner processes
-	try {
-		const orphanWorkers = cleanupOrphanWorkers(currentSessionId);
-		if (orphanWorkers.killed > 0) {
-			ctx.notifyOperator({
-				id: `orphan_workers_cleanup`,
-				severity: "info",
-				source: "worker-cleanup",
-				title: `Cleaned up ${orphanWorkers.killed} orphan worker(s)`,
-				body: `Background workers from previous (SIGKILL'd) sessions were terminated (pruned ${orphanWorkers.pruned} dead, kept ${orphanWorkers.kept}).`,
-			});
-		}
-	} catch (error) {
-		logInternalError("register.sessionStart.orphanWorkers", error);
-	}
-
-	// Global purge of stale active-run-index entries
-	try {
-		const { purged } = purgeStaleActiveRunIndexFn();
-		if (purged.length > 0) {
-			ctx.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.globalIndexPurge", error);
-	}
-
-	// Reconcile stale runs found on disk
-	try {
-		const staleResults = reconcileAllStaleRuns(extensionCtx.cwd, ctx.getManifestCache(extensionCtx.cwd)) ?? [];
-		if (staleResults.length > 0) {
-			ctx.notifyOperator({
-				id: "stale_reconcile",
-				severity: "info",
-				source: "crash-recovery",
-				title: `Reconciled ${staleResults.length} stale run(s)`,
-				body: `Found and repaired ghost runs from previous sessions: ${staleResults.map((r) => r.runId).join(", ")}`,
-			});
-		}
-	} catch (error) {
-		logInternalError("register.sessionStart.reconcileStale", error);
-	}
-
-	// Auto-prune finished project-level run directories
-	try {
-		const { removed } = pruneFinishedRuns(extensionCtx.cwd, 10);
-		if (removed.length > 0) {
-			ctx.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);
-	}
-
-	// Auto-prune finished user-level run directories
-	try {
-		const { removed } = pruneUserLevelRuns(10);
-		if (removed.length > 0) {
-			ctx.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);
-	}
-}
-
-/**
- * Build a CrewScheduler wired to the current session. The scheduler's
- * executor closure invokes handleTeamTool lazily — the heavy team-tool
- * import only fires when a scheduled job actually runs.
- */
-function setupCrewScheduler(
-	pi: ExtensionAPI,
-	ctx: RegistrationContext,
-	extensionCtx: ExtensionContext,
-	sessionId: string | undefined,
-): CrewScheduler {
-	const crewScheduler = new CrewScheduler();
-	crewScheduler.start({
-		emit: (event) => {
-			if (ctx.cleanedUp) return;
-			pi.events?.emit?.("crew-scheduler", event);
-		},
-		executor: (job) => {
-			let runParams: { action: string; team: string; goal: string };
-			try {
-				runParams = JSON.parse(job.prompt);
-			} catch {
-				runParams = {
-					action: "run",
-					team: "default",
-					goal: job.prompt,
-				};
-			}
-			if (runParams.action !== "run") return `scheduled-${job.id}-${Date.now()}`;
-			const agentId = `scheduled-${job.id}-${Date.now()}`;
-			setImmediate(async () => {
-				try {
-					const runResult = await handleTeamTool(
-						{
-							action: "run",
-							team: runParams.team,
-							goal: runParams.goal,
-							async: true,
-						},
-						{ cwd: extensionCtx.cwd, sessionId },
-					);
-					const runId = runResult?.details?.runId;
-					if (runId && typeof runId === "string") {
-						crewScheduler?.recordSpawnedRun(job.id, runId);
-						// Update run manifest with scheduler provenance for traceability
-						try {
-							const cwd = extensionCtx.cwd ?? process.cwd();
-							const loaded = loadRunManifestById(cwd, runId);
-							if (loaded) {
-								// LAZY: defer dynamic import of atomic-write.ts to its call site.
-								const { atomicWriteJson } = await import("../../state/atomic-write.ts");
-								atomicWriteJson(loaded.manifest.stateRoot + "/manifest.json", {
-									...loaded.manifest,
-									schedulerJobId: job.id,
-									schedulerName: job.name,
-								});
-							}
-						} catch {
-							/* best-effort provenance tracking */
-						}
-					}
-					try {
-						const updatedJob = crewScheduler?.list().find((j) => j.id === job.id);
-						if (updatedJob) persistScheduledJobUpdate(extensionCtx.cwd, updatedJob);
-					} catch {
-						/* best-effort */
-					}
-					crewScheduler?.update(job.id, {
-						runCount: job.runCount + 1,
-						lastRun: new Date().toISOString(),
-						lastStatus: "success",
-					});
-				} catch (err) {
-					logInternalError("scheduler.execute", err);
-					crewScheduler?.update(job.id, { lastStatus: "error" });
-				}
-			});
-			return agentId;
-		},
-		finalizer: () => {},
-		runCancelFn: (runId: string) => {
-			try {
-				handleTeamTool({ action: "cancel", runId, confirm: true }, { cwd: extensionCtx.cwd, sessionId }).catch((err) =>
-					logInternalError("scheduler.runCancelFn", err, `runId=${runId}`),
-				);
-			} catch (err) {
-				logInternalError("scheduler.runCancelFn.sync", err, `runId=${runId}`);
-			}
-		},
-	});
-	return crewScheduler;
-}
-
-/**
- * Build the render scheduler + preload loop + bounded run watchers.
- *
- * Render path:
- *   - RenderScheduler fires renderTick() every `effectiveRefreshMs()`.
- *   - 160ms when live agents OR background runs are active (spinner-friendly),
- *     else the configured `dashboardLiveRefreshMs` (default DEFAULT_UI.refreshMs).
- *   - renderTick reads from a pre-computed frame (`lastPreloadedManifests`) —
- *     zero fs I/O on the hot path.
- *
- * Watchers:
- *   - pts/2 hang fix (2026-06-16): a SINGLE non-recursive watcher on the
- *     `runs/` root (new-run detection) plus per-active-run watchers
- *     reconciled each preload tick. Total inotify cost: O(active runs).
- */
-function setupRenderLoop(
-	pi: ExtensionAPI,
-	ctx: RegistrationContext,
-	extensionCtx: ExtensionContext,
-	loadedConfig: ReturnType<typeof loadConfig>,
-): void {
-	ctx.disposeRenderSchedulerSubscriptions();
-	ctx.renderScheduler?.dispose();
-	ctx.terminalStatus?.dispose();
-	ctx.terminalStatus = undefined;
-	ctx.terminalStatusActive = false;
-
-	// Phase 12: Async preloading — renderTick reads only a pre-computed frame.
-	let preloading = false;
-	let lastPreloadedConfig: ReturnType<typeof loadConfig> | undefined;
-	let lastPreloadedManifests: TeamRunManifest[] = [];
-	let lastFrameManifestCache: ReturnType<typeof createManifestCache> | undefined;
-	let lastFrameSnapshotCache: ReturnType<typeof createRunSnapshotCache> | undefined;
-
-	const ownerGeneration = ctx.sessionGeneration;
-
-	const buildFrame = async (): Promise<boolean> => {
-		if (!ctx.currentCtx) return false;
-		lastPreloadedConfig = loadConfig(ctx.currentCtx.cwd);
-		lastFrameManifestCache = ctx.getManifestCache(ctx.currentCtx.cwd);
-		lastFrameSnapshotCache = ctx.getRunSnapshotCache(ctx.currentCtx.cwd);
-		const manifests = lastFrameManifestCache.list(20);
-		lastPreloadedManifests = manifests;
-		// pts/2 hang fix: reconcile per-run watchers against the ACTIVE set only.
-		{
-			const onRunChange = (runId: string): void => {
-				if (ctx.cleanedUp || ctx.sessionGeneration !== ownerGeneration) return;
-				// FLICKER FIX: rebuild-in-place instead of deleting the entry. The
-				// file just changed on disk, so force a fresh snapshot while keeping
-				// the entry populated — deleting it left a window where the widget's
-				// `get()` returned undefined and dropped the run to "(loading…)".
-				try {
-					ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).refresh(runId);
-				} catch (error) {
-					logInternalError("register.runWatcher.refresh", error, runId);
-				}
-				ctx.renderScheduler?.schedule({ runId });
-			};
-			const onWatchErr = (error: unknown): void => {
-				logInternalError("register.runWatcher.change", error);
-			};
-			const active = manifests
-				.filter((r) => r.status === "running" || r.status === "queued" || r.status === "planning")
-				.map((r) => ({ runId: r.runId, runDir: r.stateRoot }));
-			ctx.crewRunWatchers?.reconcile(active, onRunChange, onWatchErr);
-			ctx.userCrewWatchers?.reconcile(active, onRunChange, onWatchErr);
-		}
-		const runIds = manifests.map((r) => r.runId);
-		await lastFrameSnapshotCache.preloadAllStale(runIds);
-		return true;
-	};
-
-	const backgroundPreload = (): void => {
-		if (!ctx.currentCtx || preloading) return;
-		preloading = true;
-		buildFrame()
-			.then((ok) => {
-				preloading = false;
-				if (ok) ctx.renderScheduler?.schedule();
-			})
-			.catch((error: unknown) => {
-				preloading = false;
-				logInternalError("register.backgroundPreload", error);
-			});
-	};
-
-	const startPreloadLoop = (intervalMs: number, dynamicMs?: () => number): void => {
-		if (ctx.preloadTimer) clearTimeout(ctx.preloadTimer);
-		const tick = (): void => {
-			backgroundPreload();
-			const nextMs = dynamicMs?.() ?? intervalMs;
-			ctx.preloadTimer = setTimeout(tick, nextMs);
-			ctx.preloadTimer.unref();
-		};
-		ctx.preloadTimer = setTimeout(tick, intervalMs);
-		ctx.preloadTimer.unref();
-	};
-
-	const renderTick = (): void => {
-		if (!ctx.currentCtx) return;
-		const config = lastPreloadedConfig?.config.ui;
-		const activeCache = lastFrameManifestCache ?? ctx.getManifestCache(ctx.currentCtx.cwd);
-		const snapshotCache = lastFrameSnapshotCache ?? ctx.getRunSnapshotCache(ctx.currentCtx.cwd);
-		const manifests = lastPreloadedManifests;
-		if (!lastPreloadedConfig) backgroundPreload();
-		if (ctx.uiState.liveSidebarRunId || ctx.uiState.dashboardOpen) {
-			const placement = config?.widgetPlacement ?? DEFAULT_UI.widgetPlacement;
-			if (ctx.widgetState.lastVisibility !== "hidden" || ctx.widgetState.lastPlacement !== placement) {
-				setExtensionWidget(ctx.currentCtx, "pi-crew", undefined, { placement });
-				setExtensionWidget(ctx.currentCtx, "pi-crew-active", undefined, { placement });
-				ctx.widgetState.lastVisibility = "hidden";
-				ctx.widgetState.lastPlacement = placement;
-				ctx.widgetState.lastKey = "pi-crew-active";
-				ctx.widgetState.model = undefined;
-			}
-			requestRender(ctx.currentCtx);
-		} else {
-			updateCrewWidget(ctx.currentCtx, ctx.widgetState, config, activeCache, snapshotCache, manifests);
-		}
-		requestPowerbarUpdate(
-			pi.events,
-			ctx.currentCtx.cwd,
-			config,
-			activeCache,
-			snapshotCache,
-			ctx.currentCtx,
-			ctx.widgetState.notificationCount ?? 0,
-			manifests,
-		);
-		// Health notifications: only warn about genuinely running runs.
-		const currentSessionGen = ctx.sessionGeneration;
-		const currentSessionId = ctx.currentCtx ? (ctx.currentCtx as { sessionId?: string }).sessionId : undefined;
-		const sessionManifests = manifests.filter(
-			(run) =>
-				!run.ownerSessionId ||
-				run.ownerSessionId === currentSessionId ||
-				(run as unknown as Record<string, unknown>).ownerSessionGeneration === currentSessionGen,
-		);
-		const now = Date.now();
-		for (const run of sessionManifests) {
-			if (run.status !== "running") continue;
-			try {
-				const snapshot = snapshotCache.get(run.runId);
-				if (!snapshot) continue;
-				if (snapshot.manifest.status !== "running") continue;
-				const summary = summarizeHeartbeats(snapshot, { now });
-				const maybeNotifyHealth = (kind: string, count: number, title: string, body: string): void => {
-					if (count <= 0) return;
-					const key = `${kind}_${run.runId}`;
-					const previous = ctx.autoRecoveryLast.get(key);
-					if (previous !== undefined && now - previous.lastAccessAt < 5 * 60_000) return;
-					// Defensive cap: evict entry with oldest lastAccessAt before inserting/updating.
-					while (ctx.autoRecoveryLast.size >= ctx.AUTO_RECOVERY_LAST_MAX_ENTRIES) {
-						let oldestKey: string | undefined;
-						let oldestAccess = Infinity;
-						for (const [k, v] of ctx.autoRecoveryLast) {
-							if (v.lastAccessAt < oldestAccess) {
-								oldestAccess = v.lastAccessAt;
-								oldestKey = k;
-							}
-						}
-						if (oldestKey === undefined) break;
-						ctx.autoRecoveryLast.delete(oldestKey);
-					}
-					ctx.autoRecoveryLast.set(key, {
-						insertedAt: now,
-						lastAccessAt: now,
-					});
-					ctx.notifyOperator({
-						id: key,
-						severity: "warning",
-						source: "health",
-						runId: run.runId,
-						title,
-						body,
-					});
-				};
-				maybeNotifyHealth(
-					"recovery_dead_workers",
-					summary.dead,
-					`Run ${run.runId} has ${summary.dead} dead worker(s).`,
-					"Open /team-dashboard → 5 health → R recovery / K kill stale / D diagnostic.",
-				);
-				maybeNotifyHealth(
-					"recovery_missing_heartbeat",
-					summary.missing,
-					`Run ${run.runId} has ${summary.missing} worker(s) missing heartbeat.`,
-					"Open /team-dashboard → 5 health → inspect health actions.",
-				);
-			} catch (error) {
-				logInternalError("register.health-notification", error, run.runId);
-			}
-		}
-	};
-
-	const fallbackMs = loadedConfig.config.ui?.dashboardLiveRefreshMs ?? DEFAULT_UI.refreshMs;
-	const liveRefreshMs = 160;
-	const hasActiveWork = (): boolean => {
-		if (listLiveAgents().some((a) => a.status === "running")) return true;
-		return lastPreloadedManifests.some((r) => r.status === "running" || r.status === "queued" || r.status === "planning");
-	};
-	const effectiveRefreshMs = () => (hasActiveWork() ? liveRefreshMs : fallbackMs);
-	ctx.renderScheduler = new RenderScheduler(pi.events, renderTick, {
-		fallbackMs: effectiveRefreshMs,
-		onInvalidate: (payload: unknown) => {
-			const runId =
-				typeof payload === "object" &&
-				payload !== null &&
-				"runId" in payload &&
-				typeof (payload as { runId: unknown }).runId === "string"
-					? (payload as { runId: string }).runId
-					: undefined;
-			// FLICKER FIX: never hard-delete snapshot entries from a render-scheduler
-			// invalidate. A no-runId payload — emitted by EVERY fallback tick
-			// (~every 160ms while a run is active) — previously ran
-			// `invalidate(undefined)` → `entries.clear()`, wiping ALL snapshots.
-			// The next `renderTick` then saw `get() === undefined` for every run,
-			// so `activeWidgetRuns` dropped them to "(loading…)" until the async
-			// preload rebuilt the cache — an endless visible flicker. For a
-			// specific runId we now refresh-if-stale (stale-while-revalidate) so
-			// the widget always sees a populated snapshot; a no-runId tick does
-			// nothing (renderTick itself repaints; the cache's own
-			// run:state/worker:lifecycle subscription refreshes affected runs).
-			if (!runId) return;
-			try {
-				ctx.getRunSnapshotCache(extensionCtx.cwd).refreshIfStale(runId);
-			} catch (error) {
-				logInternalError("register.renderScheduler.refresh", error, runId);
-			}
-		},
-	});
-	// Fix D: bridge internal runEventBus events to renderScheduler so the UI
-	// re-renders within debounceMs of any agent lifecycle event.
-	const sched = ctx.renderScheduler;
-	const unsubscribeRunEvents = runEventBus.onAny((event) => {
-		sched.schedule({
-			runId: event.runId,
-			source: "runEventBus",
-			type: event.type,
-		});
-	});
-	ctx.renderSchedulerUnsubscribers.push(unsubscribeRunEvents);
-	startPreloadLoop(fallbackMs, effectiveRefreshMs);
-
-	// Bounded run watcher setup (pts/2 hang fix 2026-06-16).
-	const crewRunWatcherOnChange = (runId: string): void => {
-		if (ctx.cleanedUp || ctx.sessionGeneration !== ownerGeneration) return;
-		// FLICKER FIX: rebuild-in-place instead of deleting the entry (see
-		// onRunChange above). A hard delete left `get()` returning undefined for
-		// a frame, dropping the run to "(loading…)" and causing visible flicker.
-		try {
-			ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).refresh(runId);
-		} catch (error) {
-			logInternalError("register.crewRunWatcher.refresh", error, runId);
-		}
-		ctx.renderScheduler?.schedule({ runId });
-	};
-	const crewRunWatcherOnError = (error: unknown): void => {
-		logInternalError("register.crewRunWatchers.error", error);
-	};
-	try {
-		ctx.crewRunWatchers?.closeAll();
-		ctx.crewRunWatchers = undefined;
-		const crewRunsDir = path.join(projectCrewRoot(extensionCtx.cwd), "state", "runs");
-		if (fs.existsSync(crewRunsDir)) {
-			ctx.crewRunWatchers = new RunWatcherRegistry();
-			ctx.crewRunWatchers.setRootWatcher(crewRunsDir, crewRunWatcherOnChange, crewRunWatcherOnError);
-		}
-	} catch (error) {
-		logInternalError("register.crewRunWatchers.start", error);
-	}
-	try {
-		ctx.userCrewWatchers?.closeAll();
-		ctx.userCrewWatchers = undefined;
-		const userRunsDir = path.join(userCrewRoot(), "state", "runs");
-		if (fs.existsSync(userRunsDir)) {
-			ctx.userCrewWatchers = new RunWatcherRegistry();
-			ctx.userCrewWatchers.setRootWatcher(userRunsDir, crewRunWatcherOnChange, crewRunWatcherOnError);
-		}
-	} catch (error) {
-		logInternalError("register.userCrewWatchers.start", error);
-	}
-	// Kick an immediate preload so the first buildFrame reconciles per-run
-	// watchers for any runs that are already active on session start.
-	backgroundPreload();
-}
-
-// =============================================================================
-// Phase 0 inter-pi broker lifecycle controller (sub-task 0.5)
-// =============================================================================
-//
-// `installCrewBrokerLifecycleController` wires the per-session broker into
-// the existing extension lifecycle. The controller:
-//
-//  - is a no-op unless broker.enabled is true AND the current process is the
-//    root pi session (PI_CREW_KIND !== "subagent" AND currentCrewDepth === 0).
-//    Children NEVER install a broker.
-//  - lazily constructs a single CrewBroker instance per session_id. listen()
-//    is deferred until the first child run actually requests broker credentials.
-//  - issues a heap-only token per child run via `issueForChild`. The token
-//    NEVER leaves the parent's heap and the child's env (PI_CREW_BROKER_TOKEN).
-//    It is never written to disk.
-//  - retains the broker across session switches when the session_id is
-//    unchanged; on a session_id change, stops the old broker and binds a new
-//    one on the next acquire.
-//  - stops the broker during session_shutdown BEFORE the runtime cleanup path.
-//
-// The gate is re-evaluated on every `issueForChild` call (cheap env+depth
-// check) so the kill switch (PI_CREW_BROKER=0) takes effect immediately.
-
-export interface CrewBrokerLifecycleController {
-	/** Issue credentials for a child run. Returns undefined when the broker
-	 *  is disabled, this process is a subagent, or no session_id is known. */
-	issueForChild(runId: string): Promise<BrokerSpawnCredentials | undefined>;
-	/** Stop the broker (idempotent). Called on session_shutdown. */
-	stop(): Promise<void>;
-	/** Test/lifecycle seam: remember the most recent session_id for token issuance. */
-	setSessionId(sessionId: string | undefined): void;
-}
-
-function isRootSession(env: NodeJS.ProcessEnv = process.env): boolean {
-	if (env.PI_CREW_KIND === "subagent") return false;
-	try {
-		return currentCrewDepth(env) === 0;
-	} catch {
-		return false;
-	}
-}
-
-export function installCrewBrokerLifecycleController(_pi: ExtensionAPI, _ctx: RegistrationContext): CrewBrokerLifecycleController {
-	let broker: CrewBroker | null = null;
-	let brokerSessionId: string | undefined;
-	let starting: Promise<CrewBroker> | null = null;
-	let cachedSessionId: string | undefined;
-
-	function effectiveEnabled(): boolean {
-		// Env wins over config. PI_CREW_BROKER=1 forces on, =0 forces off.
-		const envOverride = process.env.PI_CREW_BROKER;
-		if (envOverride === "0") return false;
-		// Config block: read fresh so a runtime config update takes effect.
-		try {
-			const cfg = loadConfig().config.broker;
-			if (envOverride === "1") return cfg !== undefined ? cfg.enabled !== false : true;
-			// Phase 4 (v0.9.47) default-on: enabled unless explicitly disabled.
-			return cfg?.enabled !== false;
-		} catch {
-			// Fail-safe: config load failed → keep broker disabled.
-			return false;
-		}
-	}
-
-	async function getOrStartBroker(sessionId: string): Promise<CrewBroker> {
-		if (broker && brokerSessionId === sessionId) return broker;
-		if (broker && brokerSessionId !== sessionId) {
-			try {
-				await broker.stop();
-			} catch {
-				/* ignore */
-			}
-			broker = null;
-			brokerSessionId = undefined;
-		}
-		if (!broker && !starting) {
-			starting = (async () => {
-				const cfg = (() => {
-					try {
-						return loadConfig().config.broker;
-					} catch {
-						return undefined;
-					}
-				})();
-				const b = new CrewBroker({
-					sessionId,
-					socketPath: getBrokerSocketPath(sessionId),
-					maxFrameBytes: cfg?.maxFrameBytes ?? 262144,
-					outboundQueueCap: cfg?.outboundQueueCap ?? 256,
-					enabled: true,
-					cwd: process.cwd(),
-				});
-				try {
-					await b.start();
-					broker = b;
-					brokerSessionId = sessionId;
-					return b;
-				} finally {
-					starting = null;
-				}
-			})();
-		}
-		return starting!;
-	}
-
-	const issueForChild = async (runId: string): Promise<BrokerSpawnCredentials | undefined> => {
-		if (!runId || typeof runId !== "string") return undefined;
-		if (!isRootSession(process.env)) return undefined;
-		if (!effectiveEnabled()) return undefined;
-		const sessionId = cachedSessionId;
-		if (!sessionId) return undefined;
-		try {
-			const b = await getOrStartBroker(sessionId);
-			const token = b.issueRunToken(runId);
-			return { socketPath: b.socketPath, token };
-		} catch {
-			return undefined;
-		}
-	};
-
-	// Publish this issuer as the process-local active issuer so runChildPi can
-	// default `brokerIssuer` without the registration context being threaded
-	// through every runner call site. The issuer self-gates (root + flag), so
-	// publishing it unconditionally is safe even when the broker is disabled.
-	setActiveBrokerIssuer(issueForChild);
-
-	return {
-		issueForChild,
-		stop: async () => {
-			setActiveBrokerIssuer(undefined);
-			if (broker) {
-				try {
-					await broker.stop();
-				} catch {
-					/* ignore */
-				}
-				broker = null;
-				brokerSessionId = undefined;
-			}
-		},
-		/** Test seam: remember the most recent session_id for token issuance. */
-		setSessionId: (sessionId: string | undefined) => {
-			// Runtime validation: cap the length and charset to defend against
-			// a hostile extension supplying a huge or pathological id. The
-			// socket path is already hash-derived (4..32 hex), so a longer
-			// sessionId is harmless on disk but wastes heap.
-			if (typeof sessionId !== "string") return;
-			if (sessionId.length === 0 || sessionId.length > 256) return;
-			cachedSessionId = sessionId;
-		},
-	};
-}
-
-/** Marker used by tests to confirm the controller object identity. */
-export const __test__brokerControllerMarker = true;