pi-crew 0.2.2 → 0.2.4

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

@@ -1,98 +1,159 @@
-import * as fs from "node:fs";
-import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@mariozechner/pi-coding-agent";
-import { loadConfig } from "../../config/config.ts";
-import { TeamToolParams, type TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import type { CrewWidgetState } from "../../ui/crew-widget.ts";
-import { updateCrewWidget } from "../../ui/crew-widget.ts";
-import { updatePiCrewPowerbar } from "../../ui/powerbar-publisher.ts";
-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";
-// 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";
-
-export interface RegisterTeamToolDeps {
-	foregroundControllers: Map<string | symbol, AbortController>;
-	startForegroundRun: (ctx: ExtensionContext, runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
-	abortForegroundRun: (runId: string) => boolean;
-	openLiveSidebar: (ctx: ExtensionContext, runId: string) => void;
-	getManifestCache: (cwd: string) => ReturnType<typeof createManifestCache>;
-	getRunSnapshotCache?: (cwd: string) => ReturnType<typeof createRunSnapshotCache>;
-	getMetricRegistry?: () => MetricRegistry | undefined;
-	widgetState: CrewWidgetState;
-	onJsonEvent?: (taskId: string, runId: string, event: unknown) => void;
-}
-
-export function resolveCwdOverride(baseCwd: string, override: string | undefined): { ok: true; cwd: string } | { ok: false; error: string } {
-	if (!override) return { ok: true, cwd: baseCwd };
-	try {
-		const resolved = resolveRealContainedPath(baseCwd, override);
-		const stat = fs.statSync(resolved);
-		if (!stat.isDirectory()) return { ok: false, error: `cwd override is not a directory: ${resolved}` };
-		return { ok: true, cwd: resolved };
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		return { ok: false, error: `Invalid cwd override: ${message}` };
-	}
-}
-
-export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps): void {
-	const tool: ToolDefinition = {
-		name: "team",
-		label: "Team",
-		description: "Coordinate Pi teams. Use proactively for complex multi-file work, planning, implementation, tests, reviews, security audits, research, async/background runs, and worktree-isolated execution. Use action='recommend' when unsure which team/workflow to choose. Destructive actions require explicit user confirmation.",
-		promptSnippet: "Use the team tool proactively for coordinated multi-agent work. If unsure, call { action: 'recommend', goal } first, then run or plan with the suggested team/workflow.",
-		parameters: TeamToolParams as never,
-		async execute(_id, params, signal, _onUpdate, ctx) {
-			const controller = new AbortController();
-			const toolKey = Symbol();
-			deps.foregroundControllers.set(toolKey, controller);
-			const abort = (): void => controller.abort();
-			signal?.addEventListener("abort", abort, { once: true });
-			try {
-				const resolved = params as TeamToolParamsValue;
-				const cwdOverride = resolveCwdOverride(ctx.cwd, resolved.cwd);
-				if (!cwdOverride.ok) return toolResult(cwdOverride.error, { action: resolved.action ?? "list", status: "error" }, true);
-				const toolCtx = withSessionId({ ...ctx, cwd: cwdOverride.cwd });
-				// Phase 1.5: Auto-set session name from team run context
-				if (resolved.action === "run" && resolved.goal && !pi.getSessionName()) {
-					const runLabel = resolved.team ?? resolved.agent ?? "direct";
-					pi.setSessionName(`pi-crew: ${runLabel}/${resolved.workflow ?? "default"} — ${resolved.goal.slice(0, 60)}`);
-				}
-				const output = await handleTeamTool(resolved, { ...toolCtx, signal: controller.signal, metricRegistry: deps.getMetricRegistry?.(), startForegroundRun: (runner, runId) => deps.startForegroundRun(toolCtx, runner, runId), abortForegroundRun: deps.abortForegroundRun, onRunStarted: (runId) => deps.openLiveSidebar(toolCtx, runId), onJsonEvent: deps.onJsonEvent });
-				if (resolved.action === "run" && !output.isError && typeof output.details?.runId === "string") {
-					pi.appendEntry("crew:run-started", {
-						runId: output.details.runId,
-						team: resolved.team,
-						workflow: resolved.workflow,
-						agent: resolved.agent,
-						goal: resolved.goal,
-						status: output.details?.status,
-						timestamp: Date.now(),
-					});
-				}
-				const config = loadConfig(toolCtx.cwd).config.ui;
-				const cache = deps.getManifestCache(toolCtx.cwd);
-				const snapshotCache = deps.getRunSnapshotCache?.(toolCtx.cwd);
-				updateCrewWidget(toolCtx, deps.widgetState, config, cache, snapshotCache);
-				updatePiCrewPowerbar(pi.events, toolCtx.cwd, config, cache, snapshotCache, toolCtx);
-				return output;
-			} finally {
-				signal?.removeEventListener("abort", abort);
-				deps.foregroundControllers.delete(toolKey);
-			}
-		},
-	};
-	pi.registerTool(tool);
-}
+import * as fs from "node:fs";
+import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@mariozechner/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import { TeamToolParams, type TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import type { CrewWidgetState } from "../../ui/crew-widget.ts";
+import { updateCrewWidget } from "../../ui/crew-widget.ts";
+import { updatePiCrewPowerbar } from "../../ui/powerbar-publisher.ts";
+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";
+// 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) {
+		// LAZY: team-tool.ts imports many modules — defer until first use.
+		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";
+import { loadRunManifestById } from "../../state/state-store.ts";
+import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
+import { formatCompactToolProgress } from "../../ui/tool-progress-formatter.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+
+const TEAM_TOOL_PROGRESS_TICK_MS = 1000;
+
+type OnUpdate = (chunk: { content: { type: "text"; text: string }[] }) => void;
+
+export interface RegisterTeamToolDeps {
+	foregroundControllers: Map<string | symbol, AbortController>;
+	startForegroundRun: (ctx: ExtensionContext, runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
+	abortForegroundRun: (runId: string) => boolean;
+	openLiveSidebar: (ctx: ExtensionContext, runId: string) => void;
+	getManifestCache: (cwd: string) => ReturnType<typeof createManifestCache>;
+	getRunSnapshotCache?: (cwd: string) => ReturnType<typeof createRunSnapshotCache>;
+	getMetricRegistry?: () => MetricRegistry | undefined;
+	widgetState: CrewWidgetState;
+	onJsonEvent?: (taskId: string, runId: string, event: unknown) => void;
+}
+
+export function resolveCwdOverride(baseCwd: string, override: string | undefined): { ok: true; cwd: string } | { ok: false; error: string } {
+	if (!override) return { ok: true, cwd: baseCwd };
+	try {
+		const resolved = resolveRealContainedPath(baseCwd, override);
+		const stat = fs.statSync(resolved);
+		if (!stat.isDirectory()) return { ok: false, error: `cwd override is not a directory: ${resolved}` };
+		return { ok: true, cwd: resolved };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { ok: false, error: `Invalid cwd override: ${message}` };
+	}
+}
+
+export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps): void {
+	const tool: ToolDefinition = {
+		name: "team",
+		label: "Team",
+		description: "Coordinate Pi teams. Use proactively for complex multi-file work, planning, implementation, tests, reviews, security audits, research, async/background runs, and worktree-isolated execution. Use action='recommend' when unsure which team/workflow to choose. Destructive actions require explicit user confirmation.",
+		promptSnippet: "Use the team tool proactively for coordinated multi-agent work. If unsure, call { action: 'recommend', goal } first, then run or plan with the suggested team/workflow.",
+		parameters: TeamToolParams as never,
+		async execute(_id, params, signal, onUpdate, ctx) {
+			const controller = new AbortController();
+			const toolKey = Symbol();
+			deps.foregroundControllers.set(toolKey, controller);
+			const abort = (): void => controller.abort();
+			signal?.addEventListener("abort", abort, { once: true });
+			const stopProgress = startTeamToolProgressBinder(onUpdate as OnUpdate | undefined);
+			try {
+				const resolved = params as TeamToolParamsValue;
+				const cwdOverride = resolveCwdOverride(ctx.cwd, resolved.cwd);
+				if (!cwdOverride.ok) return toolResult(cwdOverride.error, { action: resolved.action ?? "list", status: "error" }, true);
+				const toolCtx = withSessionId({ ...ctx, cwd: cwdOverride.cwd });
+				// Phase 1.5: Auto-set session name from team run context
+				if (resolved.action === "run" && resolved.goal && !pi.getSessionName()) {
+					const runLabel = resolved.team ?? resolved.agent ?? "direct";
+					pi.setSessionName(`pi-crew: ${runLabel}/${resolved.workflow ?? "default"} — ${resolved.goal.slice(0, 60)}`);
+				}
+				const output = await handleTeamTool(resolved, { ...toolCtx, signal: controller.signal, metricRegistry: deps.getMetricRegistry?.(), startForegroundRun: (runner, runId) => deps.startForegroundRun(toolCtx, runner, runId), abortForegroundRun: deps.abortForegroundRun, onRunStarted: (runId) => { stopProgress.attach(toolCtx.cwd, runId); deps.openLiveSidebar(toolCtx, runId); }, onJsonEvent: deps.onJsonEvent });
+				if (resolved.action === "run" && !output.isError && typeof output.details?.runId === "string") {
+					pi.appendEntry("crew:run-started", {
+						runId: output.details.runId,
+						team: resolved.team,
+						workflow: resolved.workflow,
+						agent: resolved.agent,
+						goal: resolved.goal,
+						status: output.details?.status,
+						timestamp: Date.now(),
+					});
+				}
+				const config = loadConfig(toolCtx.cwd).config.ui;
+				const cache = deps.getManifestCache(toolCtx.cwd);
+				const snapshotCache = deps.getRunSnapshotCache?.(toolCtx.cwd);
+				updateCrewWidget(toolCtx, deps.widgetState, config, cache, snapshotCache);
+				updatePiCrewPowerbar(pi.events, toolCtx.cwd, config, cache, snapshotCache, toolCtx);
+				return output;
+			} finally {
+				signal?.removeEventListener("abort", abort);
+				deps.foregroundControllers.delete(toolKey);
+				stopProgress.stop();
+			}
+		},
+	};
+	pi.registerTool(tool);
+}
+
+interface TeamToolProgressBinder {
+	attach: (cwd: string, runId: string) => void;
+	stop: () => void;
+}
+
+function startTeamToolProgressBinder(onUpdate: OnUpdate | undefined): TeamToolProgressBinder {
+	if (!onUpdate) {
+		return { attach: () => {}, stop: () => {} };
+	}
+	const startedAt = Date.now();
+	let cwd: string | undefined;
+	let runId: string | undefined;
+	const tick = (): void => {
+		try {
+			if (!cwd || !runId) {
+				const elapsed = Math.max(0, Math.round((Date.now() - startedAt) / 1000));
+				onUpdate({ content: [{ type: "text", text: `team status=starting elapsed=${elapsed}s` }] });
+				return;
+			}
+			const loaded = loadRunManifestById(cwd, runId);
+			if (!loaded) {
+				const elapsed = Math.max(0, Math.round((Date.now() - startedAt) / 1000));
+				onUpdate({ content: [{ type: "text", text: `team run=${runId} elapsed=${elapsed}s (manifest pending)` }] });
+				return;
+			}
+			let agents;
+			try { agents = readCrewAgents(loaded.manifest); } catch { /* ignore */ }
+			const text = formatCompactToolProgress({
+				agentId: runId,
+				status: loaded.manifest.status,
+				runId,
+				startedAt,
+				manifest: loaded.manifest,
+				tasks: loaded.tasks,
+				agents,
+			});
+			onUpdate({ content: [{ type: "text", text }] });
+		} catch (error) {
+			logInternalError("team-tool.progress", error, `runId=${runId ?? ""}`);
+		}
+	};
+	tick();
+	const timer = setInterval(tick, TEAM_TOOL_PROGRESS_TICK_MS);
+	if (typeof timer.unref === "function") timer.unref();
+	return {
+		attach: (boundCwd, boundRunId) => { cwd = boundCwd; runId = boundRunId; tick(); },
+		stop: () => clearInterval(timer),
+	};
+}

package/src/extension/registration/viewers.ts

@@ -2,6 +2,9 @@ import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import { loadRunManifestById } from "../../state/state-store.ts";
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
 import { loadConfig } from "../../config/config.ts";
+import { listLiveAgents, type LiveAgentHandle } from "../../runtime/live-agent-manager.ts";
+import { LiveConversationOverlay } from "../../ui/live-conversation-overlay.ts";
+import { asCrewTheme } from "../../ui/theme-adapter.ts";
 // Lazy-loaded: DurableTranscriptViewer is 658ms — only needed for /crew transcript command
 import type { DurableTranscriptViewer as DurableTranscriptViewerType } from "../../ui/transcript-viewer.ts";
 let _cachedViewer: typeof DurableTranscriptViewerType | undefined;
@@ -46,3 +49,29 @@ export async function openTranscriptViewer(ctx: ExtensionCommandContext, initial
 	});
 	return true;
 }
+
+/** R2: Open live conversation overlay for a running live-session agent. */
+export async function openLiveConversation(ctx: ExtensionCommandContext, initialRunId: string | undefined, initialTaskId?: string): Promise<boolean> {
+	const selected = await selectAgentTask(ctx, initialRunId, initialTaskId);
+	if (!selected || !ctx.hasUI) return false;
+	const liveAgents = listLiveAgents();
+	const handle = liveAgents.find((h) => h.runId === selected.runId && (selected.taskId ? h.taskId === selected.taskId : true));
+	if (!handle) return false;
+	const theme = asCrewTheme({});
+	await ctx.ui.custom<undefined>((tui: any, _theme: any, _keybindings: any, done: (result: undefined) => void) => {
+		const columns = tui?.terminal?.columns ?? 80;
+		const rows = tui?.terminal?.rows ?? 24;
+		const overlay = new LiveConversationOverlay(handle, theme, columns, rows);
+		return {
+			render(width: number) { return overlay.render(width); },
+			handleInput(data: string) {
+				if (data === "\x1b" || data === "q") { overlay.close(); done(undefined); }
+			},
+			invalidate() { /* overlay polls */ },
+		};
+	}, {
+		overlay: true,
+		overlayOptions: { width: "90%", maxHeight: "85%", anchor: "center" },
+	});
+	return true;
+}

package/src/extension/result-watcher.ts

@@ -1,128 +1,128 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "../utils/completion-dedupe.ts";
-import { closeWatcher, watchWithErrorHandler } from "../utils/fs-watch.ts";
-import { createFileCoalescer } from "../utils/file-coalescer.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-
-export interface ResultWatcherEvents {
-	emit(event: string, data: unknown): void;
-}
-
-export interface ResultWatcherHandle {
-	start(): void;
-	prime(): void;
-	stop(): void;
-}
-
-interface ResultWatcherDependencies {
-	watch?: typeof watchWithErrorHandler;
-}
-
-export interface ResultWatcherOptions extends ResultWatcherDependencies {
-	eventName?: string;
-	completionTtlMs?: number;
-	isCurrent?: () => boolean;
-}
-
-const RESULT_WATCHER_RESTART_MS = 3000;
-const RESULT_WATCHER_POLL_MS = 1000;
-
-function shouldFallBackToPolling(error: unknown): boolean {
-	const code = error && typeof error === "object" ? (error as { code?: unknown }).code : undefined;
-	return code === "EMFILE" || code === "ENOSPC" || code === "EPERM";
-}
-
-function readJson(filePath: string): unknown | undefined {
-	try {
-		return JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
-	} catch (error) {
-		logInternalError("result-watcher.parse", error, `filePath=${filePath}`);
-		return undefined;
-	}
-}
-
-export function createResultWatcher(events: ResultWatcherEvents, resultsDir: string, eventNameOrOptions: string | ResultWatcherOptions = "pi-crew:run-result"): ResultWatcherHandle {
-	const options: ResultWatcherOptions = typeof eventNameOrOptions === "string" ? { eventName: eventNameOrOptions } : eventNameOrOptions;
-	const eventName = options.eventName ?? "pi-crew:run-result";
-	const completionTtlMs = options.completionTtlMs ?? 5 * 60_000;
-	const watch = options.watch ?? watchWithErrorHandler;
-	const isCurrent = options.isCurrent ?? (() => true);
-	const seen = getGlobalSeenMap("pi-crew.result-watcher");
-	let watcher: fs.FSWatcher | null | undefined;
-	let restartTimer: ReturnType<typeof setTimeout> | undefined;
-	let pollTimer: ReturnType<typeof setInterval> | undefined;
-	const coalescer = createFileCoalescer((file) => {
-		if (!isCurrent()) return;
-		const filePath = path.join(resultsDir, file);
-		if (!file.endsWith(".json") || !fs.existsSync(filePath)) return;
-		const payload = readJson(filePath);
-		if (payload === undefined) {
-			coalescer.schedule(file, RESULT_WATCHER_POLL_MS);
-			return;
-		}
-		const key = buildCompletionKey(payload && typeof payload === "object" && !Array.isArray(payload) ? payload as Record<string, unknown> : {}, `file:${file}`);
-		if (!markSeenWithTtl(seen, key, Date.now(), completionTtlMs)) {
-			events.emit(eventName, payload);
-		}
-		try {
-			fs.unlinkSync(filePath);
-		} catch (error) {
-			logInternalError("result-watcher.unlink", error, `filePath=${filePath}`);
-		}
-	}, 50);
-	const poll = () => {
-		if (!isCurrent() || !fs.existsSync(resultsDir)) return;
-		for (const file of fs.readdirSync(resultsDir).filter((entry) => entry.endsWith(".json"))) coalescer.schedule(file, 0);
-	};
-	const startPolling = () => {
-		if (pollTimer) return;
-		pollTimer = setInterval(poll, RESULT_WATCHER_POLL_MS);
-		pollTimer.unref();
-		poll();
-	};
-	const stopPolling = () => {
-		if (pollTimer) clearInterval(pollTimer);
-		pollTimer = undefined;
-	};
-	const scheduleRestart = (error?: unknown) => {
-		if (shouldFallBackToPolling(error)) startPolling();
-		if (restartTimer) clearTimeout(restartTimer);
-		restartTimer = setTimeout(() => {
-			restartTimer = undefined;
-			try {
-				if (!isCurrent()) return;
-				fs.mkdirSync(resultsDir, { recursive: true });
-				handle.start();
-			} catch (error) {
-				logInternalError("result-watcher.restart", error, `resultsDir=${resultsDir}`);
-			}
-		}, RESULT_WATCHER_RESTART_MS);
-		restartTimer.unref();
-	};
-	const handle: ResultWatcherHandle = {
-		start() {
-			if (!isCurrent()) return;
-			fs.mkdirSync(resultsDir, { recursive: true });
-			if (watcher) closeWatcher(watcher);
-			watcher = watch(resultsDir, (event, fileName) => {
-				if (event !== "rename" || !fileName) return;
-				coalescer.schedule(fileName.toString());
-			}, scheduleRestart);
-			if (watcher) stopPolling();
-			watcher?.unref();
-		},
-		prime() {
-			poll();
-		},
-		stop() {
-			if (restartTimer) clearTimeout(restartTimer);
-			restartTimer = undefined;
-			closeWatcher(watcher);
-			watcher = undefined;
-			stopPolling();
-			coalescer.clear();
-		},
-	};
-	return handle;
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "../utils/completion-dedupe.ts";
+import { closeWatcher, watchWithErrorHandler } from "../utils/fs-watch.ts";
+import { createFileCoalescer } from "../utils/file-coalescer.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+
+export interface ResultWatcherEvents {
+	emit(event: string, data: unknown): void;
+}
+
+export interface ResultWatcherHandle {
+	start(): void;
+	prime(): void;
+	stop(): void;
+}
+
+interface ResultWatcherDependencies {
+	watch?: typeof watchWithErrorHandler;
+}
+
+export interface ResultWatcherOptions extends ResultWatcherDependencies {
+	eventName?: string;
+	completionTtlMs?: number;
+	isCurrent?: () => boolean;
+}
+
+const RESULT_WATCHER_RESTART_MS = 3000;
+const RESULT_WATCHER_POLL_MS = 1000;
+
+function shouldFallBackToPolling(error: unknown): boolean {
+	const code = error && typeof error === "object" ? (error as { code?: unknown }).code : undefined;
+	return code === "EMFILE" || code === "ENOSPC" || code === "EPERM";
+}
+
+function readJson(filePath: string): unknown | undefined {
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+	} catch (error) {
+		logInternalError("result-watcher.parse", error, `filePath=${filePath}`);
+		return undefined;
+	}
+}
+
+export function createResultWatcher(events: ResultWatcherEvents, resultsDir: string, eventNameOrOptions: string | ResultWatcherOptions = "pi-crew:run-result"): ResultWatcherHandle {
+	const options: ResultWatcherOptions = typeof eventNameOrOptions === "string" ? { eventName: eventNameOrOptions } : eventNameOrOptions;
+	const eventName = options.eventName ?? "pi-crew:run-result";
+	const completionTtlMs = options.completionTtlMs ?? 5 * 60_000;
+	const watch = options.watch ?? watchWithErrorHandler;
+	const isCurrent = options.isCurrent ?? (() => true);
+	const seen = getGlobalSeenMap("pi-crew.result-watcher");
+	let watcher: fs.FSWatcher | null | undefined;
+	let restartTimer: ReturnType<typeof setTimeout> | undefined;
+	let pollTimer: ReturnType<typeof setInterval> | undefined;
+	const coalescer = createFileCoalescer((file) => {
+		if (!isCurrent()) return;
+		const filePath = path.join(resultsDir, file);
+		if (!file.endsWith(".json") || !fs.existsSync(filePath)) return;
+		const payload = readJson(filePath);
+		if (payload === undefined) {
+			coalescer.schedule(file, RESULT_WATCHER_POLL_MS);
+			return;
+		}
+		const key = buildCompletionKey(payload && typeof payload === "object" && !Array.isArray(payload) ? payload as Record<string, unknown> : {}, `file:${file}`);
+		if (!markSeenWithTtl(seen, key, Date.now(), completionTtlMs)) {
+			events.emit(eventName, payload);
+		}
+		try {
+			fs.unlinkSync(filePath);
+		} catch (error) {
+			logInternalError("result-watcher.unlink", error, `filePath=${filePath}`);
+		}
+	}, 50);
+	const poll = () => {
+		if (!isCurrent() || !fs.existsSync(resultsDir)) return;
+		for (const file of fs.readdirSync(resultsDir).filter((entry) => entry.endsWith(".json"))) coalescer.schedule(file, 0);
+	};
+	const startPolling = () => {
+		if (pollTimer) return;
+		pollTimer = setInterval(poll, RESULT_WATCHER_POLL_MS);
+		pollTimer.unref();
+		poll();
+	};
+	const stopPolling = () => {
+		if (pollTimer) clearInterval(pollTimer);
+		pollTimer = undefined;
+	};
+	const scheduleRestart = (error?: unknown) => {
+		if (shouldFallBackToPolling(error)) startPolling();
+		if (restartTimer) clearTimeout(restartTimer);
+		restartTimer = setTimeout(() => {
+			restartTimer = undefined;
+			try {
+				if (!isCurrent()) return;
+				fs.mkdirSync(resultsDir, { recursive: true });
+				handle.start();
+			} catch (error) {
+				logInternalError("result-watcher.restart", error, `resultsDir=${resultsDir}`);
+			}
+		}, RESULT_WATCHER_RESTART_MS);
+		restartTimer.unref();
+	};
+	const handle: ResultWatcherHandle = {
+		start() {
+			if (!isCurrent()) return;
+			fs.mkdirSync(resultsDir, { recursive: true });
+			if (watcher) closeWatcher(watcher);
+			watcher = watch(resultsDir, (event, fileName) => {
+				if (event !== "rename" || !fileName) return;
+				coalescer.schedule(fileName.toString());
+			}, scheduleRestart);
+			if (watcher) stopPolling();
+			watcher?.unref();
+		},
+		prime() {
+			poll();
+		},
+		stop() {
+			if (restartTimer) clearTimeout(restartTimer);
+			restartTimer = undefined;
+			closeWatcher(watcher);
+			watcher = undefined;
+			stopPolling();
+			coalescer.clear();
+		},
+	};
+	return handle;
+}