pi-crew 0.11.7 → 0.11.9

package/src/extension/registration/render-loop.ts

@@ -0,0 +1,532 @@
+/**
+ * setupRenderLoop — the per-session render pipeline (RenderScheduler +
+ * preload loop + bounded run watchers + health-notification gates) plus the
+ * pure frame helpers it shares. Extracted verbatim from
+ * lifecycle-handlers.ts (QW#2, deep review 2026-10-01) so the lifecycle
+ * module stays focused on session_start/shutdown/before_switch wiring.
+ *
+ * The loop itself is driven end-to-end through
+ * `installSessionLifecycleHandlers` (see preload-idle-render.test.ts); the
+ * exported pure helpers are pinned directly by
+ * test/unit/extension/registration/lifecycle-health-filter.test.ts.
+ */
+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 { forgetDetachedRun, hasDetachedRuns, peekFinishedDetachedRunResults } from "../../runtime/detached-run-results.ts";
+import { listLiveAgents } from "../../runtime/live-session/live-agent-manager.ts";
+import type { createManifestCache } from "../../runtime/manifest-cache.ts";
+import { loadTasksWithRecovery } from "../../state/stores/manifest-io.ts";
+import type { TeamRunManifest } from "../../state/types.ts";
+import { overlayFreshTaskStatuses, summarizeHeartbeats } from "../../ui/heartbeat-aggregator.ts";
+import { requestRender, setExtensionWidget, toPiWidgetPlacement } from "../../ui/pi-ui-compat.ts";
+import { requestPowerbarUpdate } 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 { healthNotifyFingerprint, recordHealthNotifyDecision, resetHealthNotifyEntry } from "./health-notify-policy.ts";
+import type { RegistrationContext } from "./registration-types.ts";
+import { purgeQueuedAmbientNotifications } from "./subagent-helpers.ts";
+
+/**
+ * Hand over the outcome of runs detached by an agent-view switch.
+ *
+ * Delivered as a DISPLAYED session entry (not a follow-up queue item): an idle
+ * session never flushes a follow-up, so the queued variant left the result
+ * invisible. Each result is dropped from the registry only after its send
+ * succeeded, and only while the owning session is current — a worker's view
+ * session must never receive the parent run's report.
+ */
+export function deliverDetachedRunResults(pi: ExtensionAPI, extensionCtx: ExtensionContext): void {
+	if (!hasDetachedRuns()) return;
+	try {
+		// Agent views are in-document panes now, never sessions: the current
+		// session is always the main one, so detached results always deliver.
+		const inViewSession = false;
+		for (const { runId, text } of peekFinishedDetachedRunResults({ inViewSession })) {
+			pi.sendMessage({ customType: "pi-crew-run-result", content: text, display: true });
+			forgetDetachedRun(runId);
+			try {
+				extensionCtx.ui.notify(text.split("\n")[0] ?? `pi-crew run finished: ${runId}`, "info");
+			} catch {
+				/* toast is secondary to the session entry */
+			}
+		}
+	} catch (error) {
+		// Keep the entry: the next tick retries rather than losing the outcome.
+		logInternalError("register.detachedRunResults", error);
+	}
+}
+
+/**
+ * Phase 5 (Vector #3): keep only the CURRENT session's owned runs (plus
+ * ownerless runs) for health notifications. Previously the inline filter derived
+ * `currentSessionId` from a cast that was always `undefined` and compared
+ * against `ownerSessionGeneration` (a field absent from TeamRunManifest), so
+ * together they dropped EVERY owned run. Exported for unit testing.
+ */
+export function filterManifestsForHealthNotifications(
+	manifests: TeamRunManifest[],
+	currentSessionId: string | undefined,
+): TeamRunManifest[] {
+	return manifests.filter((run) => !run.ownerSessionId || run.ownerSessionId === currentSessionId);
+}
+
+/**
+ * bug-026 sub-issue C: runEventBus event types that mark a run TERMINAL,
+ * across BOTH type namespaces seen on the bus — dotted `run.*` strings (kept
+ * for parity with classifyEventChannel's WORKER_LIFECYCLE_TYPES, see
+ * src/ui/run-event-bus.ts:31-44) and underscore `run_*` (the native
+ * RunEventType namespace actually emitted by team-runner, e.g.
+ * `run_completed`). Exported for unit testing.
+ */
+export const TERMINAL_RUN_EVENT_TYPES: ReadonlySet<string> = new Set([
+	"run.completed",
+	"run.failed",
+	"run.cancelled",
+	"run_completed",
+	"run_failed",
+	"run_cancelled",
+]);
+
+/** True when a runEventBus event type marks the run terminal (either namespace). */
+export function isTerminalRunEventType(type: string): boolean {
+	return TERMINAL_RUN_EVENT_TYPES.has(type);
+}
+
+/** Pure filter: drop `runId` from a preloaded-manifest frame (bug-026 sub-issue C eviction). */
+export function evictRunFromManifests(manifests: TeamRunManifest[], runId: string): TeamRunManifest[] {
+	return manifests.filter((m) => m.runId !== runId);
+}
+
+/**
+ * F14 (RR-019): cheap signature of the preloaded-manifest frame. Only a
+ * CHANGED signature lets `backgroundPreload` count as render activity
+ * (`schedule()`); an identical signature means "nothing the widget would
+ * paint differently" and must NOT reset the render scheduler's idle
+ * counters (that defeated the R1 idle stop — see setupRenderLoop). Covers
+ * run identity, status transitions, and updatedAt bumps. Exported for tests.
+ */
+export function manifestsFrameSignature(manifests: TeamRunManifest[]): string {
+	return manifests.map((m) => `${m.runId}:${m.status}:${m.updatedAt}`).join("|");
+}
+
+/**
+ * Apply a runEventBus payload to a preloaded-manifest frame: evict the run on
+ * terminal events, pass through unchanged otherwise. This is the exact logic
+ * wired into the setupRenderLoop `runEventBus.onAny` subscription (bug-026
+ * sub-issue C); exported so tests can exercise it end-to-end against the
+ * real bus without spinning up the full render loop.
+ */
+export function applyTerminalRunEventToManifests(manifests: TeamRunManifest[], event: { type: string; runId: string }): TeamRunManifest[] {
+	return isTerminalRunEventType(event.type) ? evictRunFromManifests(manifests, event.runId) : manifests;
+}
+
+/**
+ * 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).
+ */
+export 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;
+	// F14: signature of the last frame backgroundPreload saw — only a change
+	// here counts as render activity.
+	let lastFrameSignature: string | undefined;
+
+	const ownerGeneration = ctx.sessionGeneration;
+
+	const buildFrame = async (): Promise<{ ok: boolean; changed: boolean }> => {
+		if (!ctx.currentCtx) return { ok: false, changed: 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;
+		// F14 (RR-019): compute the frame signature BEFORE the preload await so
+		// `changed` reflects what this tick saw, not a mid-preload mutation.
+		const frameSignature = manifestsFrameSignature(manifests);
+		const frameChanged = frameSignature !== lastFrameSignature;
+		lastFrameSignature = frameSignature;
+		// 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…)".
+				// PERF (2026-08-24): route through the coalesced ASYNC refresh —
+				// fs.watch can fire many times per second and the sync rebuild
+				// blocked the UI event loop. The entry stays populated until the
+				// async rebuild re-sets it in place; the render schedule below
+				// repaints while it lands.
+				try {
+					ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).scheduleRefresh(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 { ok: true, changed: frameChanged };
+	};
+
+	const backgroundPreload = (): void => {
+		if (!ctx.currentCtx || preloading) return;
+		preloading = true;
+		buildFrame()
+			.then(({ ok, changed }) => {
+				preloading = false;
+				// F14 (RR-019): preload completion is maintenance, NOT user activity.
+				// Only a genuinely CHANGED frame may call schedule() — an unchanged
+				// frame calling schedule() reset `lastEventAt`/`idleFallbackRenders`
+				// and re-armed the fallback loop that fallbackLoop() had just
+				// deliberately stopped (R1), rendering forever while idle. Real
+				// work still animates: runEventBus + fs.watch subscriptions call
+				// schedule() directly on genuine events.
+				if (ok && changed) 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;
+		deliverDetachedRunResults(pi, ctx.currentCtx);
+		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 = toPiWidgetPlacement(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.
+		// Phase 5 (Vector #3): derive currentSessionId via the working accessor.
+		// ctx is RegistrationContext; currentCtx holds the ExtensionContext whose
+		// sessionManager exposes getSessionId(). The previous cast to {sessionId?}
+		// was always undefined, and the ownerSessionGeneration clause referenced a
+		// field absent from TeamRunManifest — together they dropped EVERY owned
+		// run. Now only the current session's owned runs + ownerless runs pass.
+		const currentSessionId = ctx.currentCtx?.sessionManager?.getSessionId();
+		const sessionManifests = filterManifestsForHealthNotifications(manifests, currentSessionId);
+		const now = Date.now();
+		// FIX #2: clear path — when a run is detected terminal, dismiss any
+		// previously-emitted health notification for it AND drop its cooldown
+		// (autoRecoveryLast) so a future genuine re-occurrence can re-notify.
+		// Keeps the dashboard clean and stops the 5-min re-fire cycle.
+		const clearHealthNotifications = (runId: string): void => {
+			for (const kind of ["recovery_dead_workers", "recovery_missing_heartbeat"]) {
+				const key = `${kind}_${runId}`;
+				// FINDING 6: reset the fire budget (a genuine recurrence after
+				// this clear re-notifies) AND opportunistically purge
+				// still-QUEUED host follow-up copies of the original warning —
+				// the host drains the queue one message per turn boundary, so
+				// stale copies otherwise drip in for hours after the clear
+				// (live: 5h of "missing heartbeat" replays after the 2026-09-23
+				// zombie cleanup). The purge is feature-detected: hosts without
+				// clearQueuedUserMessagesMatching (e.g. 0.87.0) no-op here; the
+				// fire-cap policy bounds the backlog on every host.
+				resetHealthNotifyEntry({ entries: ctx.autoRecoveryLast, maxEntries: ctx.AUTO_RECOVERY_LAST_MAX_ENTRIES }, key);
+				ctx.notifyOperator({
+					id: key,
+					clear: true,
+					severity: "info",
+					source: "health",
+					runId,
+					title: `Cleared ${kind} for ${runId}`,
+				});
+				purgeQueuedAmbientNotifications(
+					pi,
+					(text) => text.includes(runId) && (text.includes("dead worker") || text.includes("missing heartbeat")),
+				);
+			}
+		};
+		// L2 (real-test 2026-10-07, report L2): rebuild-in-place, NEVER
+		// hard-delete. The health gates below used `invalidate(runId)`
+		// (entries.delete) on every tick for terminal/divergent runs — exactly
+		// what the FLICKER FIX invariant (run-snapshot-cache.ts scheduleRefresh
+		// docs + the onRunChange wiring above) forbids: for 1-n frames
+		// `snapshotCache.get(runId)` returned undefined and the widget/powerbar
+		// fell back to their disk-read branch around every run completion
+		// (visible flicker). Route through the coalesced ASYNC rebuild instead —
+		// the entry stays populated until the rebuild re-sets it in place. No
+		// renderScheduler.schedule() here: unlike the fs.watch onRunChange path
+		// we are ALREADY inside a renderTick, and list(20) keeps terminal runs
+		// in sessionManifests for many ticks, so a schedule() from the gates
+		// would reset lastEventAt on every tick and defeat the R1 idle stop
+		// (pinned by preload-idle-render.test.ts).
+		const refreshSnapshotInPlace = (runId: string): void => {
+			try {
+				snapshotCache.scheduleRefresh(runId);
+			} catch (error) {
+				logInternalError("register.renderLoop.snapshotRefresh", error, runId);
+			}
+		};
+		for (const run of sessionManifests) {
+			if (run.status !== "running") {
+				// GATE 1 — preloaded manifest says terminal. Refresh the snapshot in
+				// place (never delete) and clear previously-emitted health notifications
+				// so the dashboard stays clean (belt-and-suspenders with the FIX #1
+				// fresh-read gate).
+				refreshSnapshotInPlace(run.runId);
+				clearHealthNotifications(run.runId);
+				continue;
+			}
+			try {
+				// FIX #1: re-verify against a FRESH manifest read. The preloaded `run`
+				// (from lastPreloadedManifests) can lag the on-disk terminal
+				// transition; the manifest cache has a 500ms TTL + file watcher so it
+				// is the source of truth. A terminal run must NEVER reach
+				// maybeNotifyHealth. Also refresh the stale snapshot in place
+				// (never delete) and clear any previously-emitted health
+				// notification for this run.
+				const freshManifest = ctx.getManifestCache(extensionCtx.cwd).get(run.runId);
+				if (freshManifest?.status !== "running") {
+					refreshSnapshotInPlace(run.runId);
+					clearHealthNotifications(run.runId);
+					continue;
+				}
+				// L5: paint-path read through the read-only accessor — cached
+				// snapshot only; a lapsed TTL schedules the coalesced async refresh
+				// instead of ever rebuilding synchronously inside renderTick.
+				const snapshot = snapshotCache.readForRender(run.runId);
+				if (!snapshot) continue;
+				if (snapshot.manifest.status !== "running") {
+					// GATE 2 — a running manifest paired with a now-terminal snapshot is
+					// stale. Refresh it in place so subsequent ticks get the fresh view,
+					// and clear.
+					refreshSnapshotInPlace(run.runId);
+					clearHealthNotifications(run.runId);
+					continue;
+				}
+				// GATE 3 (FINDING 5) — task-status truth lives on DISK, not in the
+				// snapshot cache. A worker parked on `ask` writes running → waiting
+				// to tasks.json immediately, but the cached snapshot can lag that
+				// transition; in the window a parked (alive, silent-by-design)
+				// worker counted as active-without-heartbeat and fired a false
+				// "dead worker" (live: team_20260923100114, 01_explore parked on
+				// ask). Overlay FRESH statuses before summarizing; divergence also
+				// schedules an in-place rebuild so the cache syncs off the tick.
+				const freshTasks = loadTasksWithRecovery(freshManifest.tasksPath, freshManifest.eventsPath, run.runId);
+				const overlaid = overlayFreshTaskStatuses(snapshot, freshTasks);
+				if (overlaid !== snapshot) refreshSnapshotInPlace(run.runId);
+				const summary = summarizeHeartbeats(overlaid, { now });
+				const fingerprint = healthNotifyFingerprint(summary, overlaid.tasks.length);
+				const maybeNotifyHealth = (kind: string, count: number, title: string, body: string): void => {
+					if (count <= 0) return;
+					const key = `${kind}_${run.runId}`;
+					// FINDING 6: bounded re-fire — ≤ MAX_HEALTH_NOTIFY_FIRES per
+					// UNCHANGED fingerprint (5-min cooldown between fires). The
+					// old forever-re-arming cooldown fed the host follow-up queue
+					// duplicates that drained one-per-turn-boundary for hours.
+					// Policy detail + LRU eviction: health-notify-policy.ts.
+					const state = { entries: ctx.autoRecoveryLast, maxEntries: ctx.AUTO_RECOVERY_LAST_MAX_ENTRIES };
+					if (!recordHealthNotifyDecision(state, key, fingerprint, now)) return;
+					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 schedule the coalesced ASYNC refresh (L5,
+			// real-test 2026-10-07): refreshIfStale() did a SYNC full rebuild
+			// between paints (and a sync build for missing entries), blocking the
+			// event loop mid-render; scheduleRefresh keeps the entry populated and
+			// rebuilds off the tick. 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).scheduleRefresh(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) => {
+		// bug-026 sub-issue C: evict terminal runs from the preloaded manifest
+		// frame so a stale "running" entry cannot persist for the session
+		// lifetime. Additive to the renderTick GATE 1 / FIX #1 / GATE 2
+		// snapshot refreshes (which rebuild the snapshot cache entries in
+		// place) — those gates do not touch lastPreloadedManifests itself.
+		lastPreloadedManifests = applyTerminalRunEventToManifests(lastPreloadedManifests, 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.
+		// PERF (2026-08-24): coalesced ASYNC refresh — fs.watch can fire many
+		// times per second and the sync rebuild blocked the UI event loop; the
+		// render schedule below repaints while the rebuild lands.
+		try {
+			ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).scheduleRefresh(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();
+}

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

@@ -865,6 +865,9 @@ export async function handleDoctor(ctx: TeamContext, params: TeamToolParamsValue
 	// cleanup only closes multiplexer panes (zombie workers' panes + terminal
 	// runs' leaked panes) through the provider, gated on detect(). The user's
 	// main session never carries PI_CREW_KIND, so it can never appear here.
+	// R3-16: the scan ALSO reports "foreign" pi processes (AI_AGENT=pi /
+	// PI_CODING_AGENT=true CLI markers + pi-looking argv) — WARN listing only,
+	// never kill candidates, never fed to pane cleanup.
 	if (params.focus === "zombies") {
 		const scan = scanZombieSubagents();
 		const cleanup = await cleanupOrphanSurfacePanes({ cwd: ctx.cwd, scan });
@@ -877,6 +880,9 @@ export async function handleDoctor(ctx: TeamContext, params: TeamToolParamsValue
 				data: {
 					zombies: scan.zombies.length,
 					live: scan.live.length,
+					// R3-16: foreign pi processes — WARN-only report count (never killed,
+					// never pane-cleaned; see zombie-scanner.ts discriminator notes).
+					foreignPi: scan.foreign.length,
 					errors: scan.errors.length,
 					orphanPanes: cleanup.orphans.length,
 					panesClosed: cleanup.closed.length,

package/src/extension/team-tool/handle-settings.ts

@@ -35,7 +35,10 @@ const EFFECTIVE_DEFAULTS: Record<string, unknown> = {
 	"ui.showModel": true,
 	"ui.showTokens": true,
 	"ui.showTools": true,
-	"ui.dashboardPlacement": "center",
+	// L3 (2026-10-07): mirrors DEFAULT_UI.dashboardPlacement = "right"
+	// (defaults.ts) — G17: duplicated EFFECTIVE_DEFAULTS maps must track the
+	// canonical default or the settings overlay shows a stale value.
+	"ui.dashboardPlacement": "right",
 	"ui.dashboardWidth": 72,
 	"ui.autoOpenDashboard": false,
 	// G17 sync (2026-09-10 review): canonical DEFAULT_UI.widgetPlacement =

package/src/runtime/child-pi/child-pi-spawn.ts

@@ -270,6 +270,10 @@ export function prepareSpawnContext(
 		agent: input.agent,
 		model: input.model,
 		sessionEnabled: true,
+		// R3-15: human-facing `--name crew-<taskId>` session label (agentId IS the
+		// task id; anonymous spawns without one simply get no name — same
+		// optional-shape as sessionId/sessionDir above).
+		taskId: input.agentId,
 		// W2 (P1-1): deterministic session identity so crash-path tail-recovery
 		// can find the worker's session JSONL (see session-recovery.ts). Falls
 		// back to child-pi.ts deriveSessionPaths when unset (idempotent both ways).
@@ -281,6 +285,9 @@ export function prepareSpawnContext(
 		thinkingOverride: input.thinkingOverride,
 		systemPromptAppend: input.systemPromptAppend,
 		hermeticWorkers: input.hermeticWorkers,
+		// U9: version-gated flags (--no-mcp floor) — threaded by runChildPi's
+		// single-flight probe; undefined/null = unknown → builder emits nothing.
+		piVersion: input.piVersion,
 		// ADR-5 §3: depthOverride is pre-encoded into depthEnv by runChildPi
 		// (parent's record depth as base-env PI_CREW_DEPTH); forward it so the
 		// child env gets parentDepth+1 = the true grandchild depth.

package/src/runtime/child-pi/child-pi.ts

@@ -53,9 +53,10 @@ export { buildChildPiSpawnOptions, buildFinalChildPiSpawnOptions } from "./child
 // ── Re-export from child-pi-streams.ts (H-7 decomposition step 4) ──
 export { ChildPiLineObserver } from "./child-pi-streams.ts";
 
-import { checkCrewDepth, cleanupTempDir } from "../model/pi-args.ts";
+import { checkCrewDepth, cleanupTempDir, resolveHermeticWorkers } from "../model/pi-args.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../process/post-exit-stdio-guard.ts";
 import { classifyProcessCrash } from "../recovery/crash-classification.ts";
+import { probePiVersion } from "./pi-version.ts";
 
 /** Maximum size (bytes) for the ChildPiLineObserver's line accumulation buffer.
  * When exceeded, the buffer is force-flushed to prevent unbounded memory growth
@@ -226,6 +227,15 @@ export interface ChildPiRunInput {
 	 *  buildPiWorkerArgs (--no-extensions). Env PI_CREW_HERMETIC_WORKERS
 	 *  overrides either way; default TRUE. */
 	hermeticWorkers?: boolean;
+	/** U9 (pi 1.0.4 version floor): host pi binary version for the argv
+	 *  builder's version-gated flags (--no-mcp at the 1.0.4 floor). runChildPi
+	 *  OVERWRITES this with the single-flight probePiVersion() result whenever
+	 *  this spawn can consume a version-gated flag (parity non-hermetic + not
+	 *  pre-aborted); on hermetic spawns (the default — no version-gated flag
+	 *  consulted) the field passes through untouched and the probe is SKIPPED,
+	 *  keeping default-path spawns (and unit-test surface paths) free of a real
+	 *  `pi --version` child. See child-pi/pi-version.ts for the floor registry. */
+	piVersion?: string | null;
 	/** Root directory for artifacts (used to validate transcriptPath). */
 	artifactsRoot?: string;
 	/** I5: run events JSONL path — threaded to the worker so its scratchpad
@@ -312,6 +322,19 @@ export interface ChildPiRunResult {
 	exitStatus?: WorkerExitStatus;
 	/** True if the agent was hard-aborted (max_turns + grace exceeded). */
 	aborted?: boolean;
+	/**
+	 * DR5 (RPC double-execution guard, deep-review 2026-10-05 §2): set by the
+	 * RPC transport when a session event (message_start/message_end/…) was
+	 * observed after the prompt was sent but the turn never settled — i.e.
+	 * the agent turn HAD begun when the transport failed, even though no
+	 * assistant text was captured. `isEarlyRpcTransportFailure` treats this
+	 * as non-retryable: the turn may already have performed side effects, and
+	 * double-executing a task that already produced work is worse than
+	 * surfacing the transport error. An explicit result field (not an
+	 * error-string marker) so the contract is testable and greppable; the
+	 * stdio transport never sets it.
+	 */
+	rpcAgentStarted?: boolean;
 	/** True if the agent was steered to wrap up (hit soft turn limit) but finished in time. */
 	steered?: boolean;
 	/** #7 hardening: bounded digest of intermediate findings (last N tool results or
@@ -728,7 +751,19 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			brokerSpawn = undefined;
 		}
 	}
-	const spawnPrep = prepareSpawnContext(brokerSpawn ? { ...input, brokerSpawn } : input, effectiveTask, depthEnv);
+	// U9 (pi 1.0.4 version floor): resolve the host pi binary's version ONCE per
+	// process (probePiVersion — single-flight memoized, injectable exec seam,
+	// never rejects) and thread it into the argv builder via input. Probed ONLY
+	// when this spawn can consume a version-gated flag: the parity
+	// (non-hermetic) argv applies the --no-mcp floor at 1.0.4, while hermetic
+	// spawns (the default) are already MCP-clean via --no-extensions and consult
+	// no version-gated flag — skipping the probe there keeps every default-path
+	// spawn — and the unit-test surface paths — free of a real `pi --version`
+	// child. An already-aborted signal skips too: prepareSpawnContext's B5
+	// guard below returns before the argv is ever consumed.
+	const versionedInput: ChildPiRunInput =
+		!input.signal?.aborted && !resolveHermeticWorkers(input.hermeticWorkers) ? { ...input, piVersion: await probePiVersion() } : input;
+	const spawnPrep = prepareSpawnContext(brokerSpawn ? { ...versionedInput, brokerSpawn } : versionedInput, effectiveTask, depthEnv);
 	if (spawnPrep.kind === "aborted") return spawnPrep.result;
 	const { spawnSpec, mergedEnv, tempDir, builtEnv, builtArgs } = spawnPrep.ctx;
 	// W2 (session-file recovery): resolve the worker's deterministic session