pi-crew 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/agents/agent-config.ts

@@ -24,4 +24,7 @@ export interface AgentConfig {
 	inheritProjectContext?: boolean;
 	inheritSkills?: boolean;
 	routing?: RoutingMetadata;
+	memory?: "user" | "project" | "local";
+	disabled?: boolean;
+	override?: { source: "config"; path: string };
 }

package/src/agents/discover-agents.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentConfig, ResourceSource } from "./agent-config.ts";
+import { loadConfig } from "../config/config.ts";
 import { parseCsv, parseFrontmatter } from "../utils/frontmatter.ts";
 import { packageRoot, projectPiRoot, userPiRoot } from "../utils/paths.ts";
 
@@ -14,6 +15,10 @@ function parseCost(value: string | undefined): "free" | "cheap" | "expensive" |
 	return value === "free" || value === "cheap" || value === "expensive" ? value : undefined;
 }
 
+function parseMemory(value: string | undefined): "user" | "project" | "local" | undefined {
+	return value === "user" || value === "project" || value === "local" ? value : undefined;
+}
+
 function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig | undefined {
 	try {
 		const content = fs.readFileSync(filePath, "utf-8");
@@ -40,6 +45,8 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 			systemPromptMode: frontmatter.systemPromptMode === "append" ? "append" : "replace",
 			inheritProjectContext: frontmatter.inheritProjectContext === "true",
 			inheritSkills: frontmatter.inheritSkills === "true",
+			memory: parseMemory(frontmatter.memory),
+			disabled: frontmatter.disabled === "true" || frontmatter.enabled === "false",
 			routing: triggers || useWhen || avoidWhen || cost || category ? { triggers, useWhen, avoidWhen, cost, category } : undefined,
 		};
 	} catch {
@@ -56,18 +63,40 @@ function readAgentDir(dir: string, source: ResourceSource): AgentConfig[] {
 		.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+function applyAgentOverrides(agents: AgentConfig[], cwd: string): AgentConfig[] {
+	const loaded = loadConfig(cwd);
+	const config = loaded.config.agents;
+	const overrides = config?.overrides ?? {};
+	return agents
+		.filter((agent) => !(config?.disableBuiltins && agent.source === "builtin"))
+		.map((agent) => {
+			const overrideEntry = Object.entries(overrides).find(([name]) => name.toLowerCase() === agent.name.toLowerCase());
+			if (!overrideEntry) return agent;
+			const [, override] = overrideEntry;
+			return {
+				...agent,
+				disabled: override.disabled ?? agent.disabled,
+				model: override.model === false ? undefined : override.model ?? agent.model,
+				fallbackModels: override.fallbackModels === false ? undefined : override.fallbackModels ?? agent.fallbackModels,
+				thinking: override.thinking === false ? undefined : override.thinking ?? agent.thinking,
+				tools: override.tools === false ? undefined : override.tools ?? agent.tools,
+				override: { source: "config", path: loaded.path },
+			};
+		});
+}
+
 export function discoverAgents(cwd: string): AgentDiscoveryResult {
 	return {
-		builtin: readAgentDir(path.join(packageRoot(), "agents"), "builtin"),
-		user: readAgentDir(path.join(userPiRoot(), "agents"), "user"),
-		project: readAgentDir(path.join(projectPiRoot(cwd), "agents"), "project"),
+		builtin: applyAgentOverrides(readAgentDir(path.join(packageRoot(), "agents"), "builtin"), cwd),
+		user: applyAgentOverrides(readAgentDir(path.join(userPiRoot(), "agents"), "user"), cwd),
+		project: applyAgentOverrides(readAgentDir(path.join(projectPiRoot(cwd), "agents"), "project"), cwd),
 	};
 }
 
 export function allAgents(discovery: AgentDiscoveryResult): AgentConfig[] {
 	const byName = new Map<string, AgentConfig>();
 	for (const agent of [...discovery.builtin, ...discovery.user, ...discovery.project]) {
-		byName.set(agent.name, agent);
+		byName.set(agent.name.toLowerCase(), agent);
 	}
-	return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+	return [...byName.values()].filter((agent) => !agent.disabled).sort((a, b) => a.name.localeCompare(b.name));
 }

package/src/config/config.ts

@@ -41,6 +41,25 @@ export interface CrewControlConfig {
 	needsAttentionAfterMs?: number;
 }
 
+export interface CrewWorktreeConfig {
+	setupHook?: string;
+	setupHookTimeoutMs?: number;
+	linkNodeModules?: boolean;
+}
+
+export interface AgentOverrideConfig {
+	disabled?: boolean;
+	model?: string | false;
+	fallbackModels?: string[] | false;
+	thinking?: string | false;
+	tools?: string[] | false;
+}
+
+export interface CrewAgentsConfig {
+	disableBuiltins?: boolean;
+	overrides?: Record<string, AgentOverrideConfig>;
+}
+
 export interface PiTeamsConfig {
 	asyncByDefault?: boolean;
 	executeWorkers?: boolean;
@@ -50,6 +69,8 @@ export interface PiTeamsConfig {
 	limits?: CrewLimitsConfig;
 	runtime?: CrewRuntimeConfig;
 	control?: CrewControlConfig;
+	worktree?: CrewWorktreeConfig;
+	agents?: CrewAgentsConfig;
 }
 
 export interface LoadedPiTeamsConfig {
@@ -109,6 +130,23 @@ function mergeConfig(base: PiTeamsConfig, override: PiTeamsConfig): PiTeamsConfi
 			...withoutUndefined((override.control ?? {}) as Record<string, unknown>),
 		};
 	}
+	if (base.worktree || override.worktree) {
+		merged.worktree = {
+			...(base.worktree ?? {}),
+			...withoutUndefined((override.worktree ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.agents || override.agents) {
+		merged.agents = {
+			...(base.agents ?? {}),
+			...withoutUndefined((override.agents ?? {}) as Record<string, unknown>),
+			overrides: {
+				...(base.agents?.overrides ?? {}),
+				...(override.agents?.overrides ?? {}),
+			},
+		};
+	}
+	if (merged.agents?.overrides && Object.keys(merged.agents.overrides).length === 0) delete merged.agents.overrides;
 	return merged;
 }
 
@@ -159,21 +197,33 @@ function parseAutonomousConfig(value: unknown): PiTeamsAutonomousConfig | undefi
 	};
 }
 
-function parsePositiveInteger(value: unknown): number | undefined {
-	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+const LIMIT_CEILINGS = {
+	maxConcurrentWorkers: 1024,
+	maxTaskDepth: 100,
+	maxChildrenPerTask: 1000,
+	maxRunMinutes: 1440,
+	maxRetriesPerTask: 100,
+	maxTasksPerRun: 10_000,
+	heartbeatStaleMs: 24 * 60 * 60 * 1000,
+	runtimeMaxTurns: 10_000,
+	runtimeGraceTurns: 1_000,
+} as const;
+
+function parsePositiveInteger(value: unknown, max = Number.MAX_SAFE_INTEGER): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= max ? value : undefined;
 }
 
 function parseLimitsConfig(value: unknown): CrewLimitsConfig | undefined {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
 	const obj = value as Record<string, unknown>;
 	const limits: CrewLimitsConfig = {
-		maxConcurrentWorkers: parsePositiveInteger(obj.maxConcurrentWorkers),
-		maxTaskDepth: parsePositiveInteger(obj.maxTaskDepth),
-		maxChildrenPerTask: parsePositiveInteger(obj.maxChildrenPerTask),
-		maxRunMinutes: parsePositiveInteger(obj.maxRunMinutes),
-		maxRetriesPerTask: parsePositiveInteger(obj.maxRetriesPerTask),
-		maxTasksPerRun: parsePositiveInteger(obj.maxTasksPerRun),
-		heartbeatStaleMs: parsePositiveInteger(obj.heartbeatStaleMs),
+		maxConcurrentWorkers: parsePositiveInteger(obj.maxConcurrentWorkers, LIMIT_CEILINGS.maxConcurrentWorkers),
+		maxTaskDepth: parsePositiveInteger(obj.maxTaskDepth, LIMIT_CEILINGS.maxTaskDepth),
+		maxChildrenPerTask: parsePositiveInteger(obj.maxChildrenPerTask, LIMIT_CEILINGS.maxChildrenPerTask),
+		maxRunMinutes: parsePositiveInteger(obj.maxRunMinutes, LIMIT_CEILINGS.maxRunMinutes),
+		maxRetriesPerTask: parsePositiveInteger(obj.maxRetriesPerTask, LIMIT_CEILINGS.maxRetriesPerTask),
+		maxTasksPerRun: parsePositiveInteger(obj.maxTasksPerRun, LIMIT_CEILINGS.maxTasksPerRun),
+		heartbeatStaleMs: parsePositiveInteger(obj.heartbeatStaleMs, LIMIT_CEILINGS.heartbeatStaleMs),
 	};
 	return Object.values(limits).some((entry) => entry !== undefined) ? limits : undefined;
 }
@@ -189,8 +239,8 @@ function parseRuntimeConfig(value: unknown): CrewRuntimeConfig | undefined {
 		mode: parseRuntimeMode(obj.mode),
 		preferLiveSession: typeof obj.preferLiveSession === "boolean" ? obj.preferLiveSession : undefined,
 		allowChildProcessFallback: typeof obj.allowChildProcessFallback === "boolean" ? obj.allowChildProcessFallback : undefined,
-		maxTurns: parsePositiveInteger(obj.maxTurns),
-		graceTurns: parsePositiveInteger(obj.graceTurns),
+		maxTurns: parsePositiveInteger(obj.maxTurns, LIMIT_CEILINGS.runtimeMaxTurns),
+		graceTurns: parsePositiveInteger(obj.graceTurns, LIMIT_CEILINGS.runtimeGraceTurns),
 		inheritContext: typeof obj.inheritContext === "boolean" ? obj.inheritContext : undefined,
 		promptMode: obj.promptMode === "replace" || obj.promptMode === "append" ? obj.promptMode : undefined,
 		groupJoin: obj.groupJoin === "off" || obj.groupJoin === "group" || obj.groupJoin === "smart" ? obj.groupJoin : undefined,
@@ -208,6 +258,54 @@ function parseControlConfig(value: unknown): CrewControlConfig | undefined {
 	return Object.values(control).some((entry) => entry !== undefined) ? control : undefined;
 }
 
+function parseWorktreeConfig(value: unknown): CrewWorktreeConfig | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const obj = value as Record<string, unknown>;
+	const worktree: CrewWorktreeConfig = {
+		setupHook: typeof obj.setupHook === "string" && obj.setupHook.trim() ? obj.setupHook.trim() : undefined,
+		setupHookTimeoutMs: parsePositiveInteger(obj.setupHookTimeoutMs, 300_000),
+		linkNodeModules: typeof obj.linkNodeModules === "boolean" ? obj.linkNodeModules : undefined,
+	};
+	return Object.values(worktree).some((entry) => entry !== undefined) ? worktree : undefined;
+}
+
+function parseStringArrayOrFalse(value: unknown): string[] | false | undefined {
+	if (value === false) return false;
+	if (typeof value === "string") return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+	if (Array.isArray(value)) return value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0).map((entry) => entry.trim());
+	return undefined;
+}
+
+function parseAgentOverride(value: unknown): AgentOverrideConfig | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const obj = value as Record<string, unknown>;
+	const override: AgentOverrideConfig = {
+		disabled: typeof obj.disabled === "boolean" ? obj.disabled : undefined,
+		model: typeof obj.model === "string" || obj.model === false ? obj.model : undefined,
+		fallbackModels: parseStringArrayOrFalse(obj.fallbackModels),
+		thinking: typeof obj.thinking === "string" || obj.thinking === false ? obj.thinking : undefined,
+		tools: parseStringArrayOrFalse(obj.tools),
+	};
+	return Object.values(override).some((entry) => entry !== undefined) ? override : undefined;
+}
+
+function parseAgentsConfig(value: unknown): CrewAgentsConfig | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const obj = value as Record<string, unknown>;
+	const overrides: Record<string, AgentOverrideConfig> = {};
+	if (obj.overrides && typeof obj.overrides === "object" && !Array.isArray(obj.overrides)) {
+		for (const [name, rawOverride] of Object.entries(obj.overrides)) {
+			const parsed = parseAgentOverride(rawOverride);
+			if (parsed) overrides[name] = parsed;
+		}
+	}
+	const agents: CrewAgentsConfig = {
+		disableBuiltins: typeof obj.disableBuiltins === "boolean" ? obj.disableBuiltins : undefined,
+		overrides: Object.keys(overrides).length > 0 ? overrides : undefined,
+	};
+	return Object.values(agents).some((entry) => entry !== undefined) ? agents : undefined;
+}
+
 function parseConfig(raw: unknown): PiTeamsConfig {
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
 	const obj = raw as Record<string, unknown>;
@@ -220,6 +318,8 @@ function parseConfig(raw: unknown): PiTeamsConfig {
 		limits: parseLimitsConfig(obj.limits),
 		runtime: parseRuntimeConfig(obj.runtime),
 		control: parseControlConfig(obj.control),
+		worktree: parseWorktreeConfig(obj.worktree),
+		agents: parseAgentsConfig(obj.agents),
 	};
 }
 

package/src/extension/async-notifier.ts

@@ -13,7 +13,9 @@ function isFinished(status: string): boolean {
 export function startAsyncRunNotifier(ctx: ExtensionContext, state: AsyncNotifierState, intervalMs = 5000): void {
 	if (state.interval) clearInterval(state.interval);
 	for (const run of listRuns(ctx.cwd)) {
-		if (isFinished(run.status)) state.seenFinishedRunIds.add(run.runId);
+		// Treat all pre-existing runs as seen. This avoids noisy error toasts when
+		// an old active/stale run is later inspected and transitions to failed.
+		state.seenFinishedRunIds.add(run.runId);
 	}
 	state.interval = setInterval(() => {
 		try {

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

@@ -0,0 +1,82 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { TeamToolParamsValue } from "../schema/team-tool-schema.ts";
+import { handleTeamTool } from "./team-tool.ts";
+import { parseLiveControlRealtimeMessage, publishLiveControlRealtime } from "../runtime/live-control-realtime.ts";
+
+export interface EventBusLike {
+	on(event: string, handler: (data: unknown) => void): (() => void) | void;
+	emit(event: string, data: unknown): void;
+}
+
+export type RpcReply<T = unknown> = { success: true; data?: T } | { success: false; error: string };
+export const PI_CREW_RPC_VERSION = 1;
+
+export interface PiCrewRpcHandle {
+	unsubscribe(): void;
+}
+
+function requestId(raw: unknown): string | undefined {
+	return raw && typeof raw === "object" && !Array.isArray(raw) && typeof (raw as { requestId?: unknown }).requestId === "string" ? (raw as { requestId: string }).requestId : undefined;
+}
+
+function reply(events: EventBusLike, channel: string, id: string | undefined, payload: RpcReply): void {
+	if (!id) return;
+	events.emit(`${channel}:reply:${id}`, payload);
+}
+
+function textOf(result: Awaited<ReturnType<typeof handleTeamTool>>): string {
+	return result.content?.map((item) => item.type === "text" ? item.text : "").join("\n") ?? "";
+}
+
+function on(events: EventBusLike, channel: string, handler: (raw: unknown) => void): () => void {
+	const unsub = events.on(channel, handler);
+	return typeof unsub === "function" ? unsub : () => {};
+}
+
+export function registerPiCrewRpc(events: EventBusLike | undefined, getCtx: () => ExtensionContext | undefined): PiCrewRpcHandle | undefined {
+	if (!events) return undefined;
+	const unsubs = [
+		on(events, "pi-crew:rpc:ping", (raw) => reply(events, "pi-crew:rpc:ping", requestId(raw), { success: true, data: { version: PI_CREW_RPC_VERSION } })),
+		on(events, "pi-crew:rpc:run", async (raw) => {
+			const id = requestId(raw);
+			try {
+				const ctx = getCtx();
+				if (!ctx) throw new Error("No active pi-crew session context.");
+				const params: TeamToolParamsValue = raw && typeof raw === "object" && !Array.isArray(raw) ? { ...(raw as object), action: "run" } as TeamToolParamsValue : { action: "run" };
+				const result = await handleTeamTool(params, ctx);
+				reply(events, "pi-crew:rpc:run", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: result.details });
+			} catch (error) {
+				reply(events, "pi-crew:rpc:run", id, { success: false, error: error instanceof Error ? error.message : String(error) });
+			}
+		}),
+		on(events, "pi-crew:rpc:status", async (raw) => {
+			const id = requestId(raw);
+			try {
+				const ctx = getCtx();
+				if (!ctx) throw new Error("No active pi-crew session context.");
+				const runId = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as { runId?: string }).runId : undefined;
+				const result = await handleTeamTool({ action: "status", runId }, ctx);
+				reply(events, "pi-crew:rpc:status", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: { text: textOf(result), details: result.details } });
+			} catch (error) {
+				reply(events, "pi-crew:rpc:status", id, { success: false, error: error instanceof Error ? error.message : String(error) });
+			}
+		}),
+		on(events, "pi-crew:live-control", (raw) => {
+			const request = parseLiveControlRealtimeMessage(raw);
+			if (request) publishLiveControlRealtime(request);
+		}),
+		on(events, "pi-crew:rpc:live-control", async (raw) => {
+			const id = requestId(raw);
+			try {
+				const ctx = getCtx();
+				if (!ctx) throw new Error("No active pi-crew session context.");
+				const obj = raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
+				const result = await handleTeamTool({ action: "api", runId: typeof obj.runId === "string" ? obj.runId : undefined, config: { operation: typeof obj.operation === "string" ? obj.operation : "steer-agent", agentId: obj.agentId, message: obj.message, prompt: obj.prompt } }, ctx);
+				reply(events, "pi-crew:rpc:live-control", id, result.isError ? { success: false, error: textOf(result) } : { success: true, data: { text: textOf(result), details: result.details } });
+			} catch (error) {
+				reply(events, "pi-crew:rpc:live-control", id, { success: false, error: error instanceof Error ? error.message : String(error) });
+			}
+		}),
+	];
+	return { unsubscribe: () => unsubs.forEach((unsub) => unsub()) };
+}

package/src/extension/register.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, ExtensionCommandContext, ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, ToolDefinition } from "@mariozechner/pi-coding-agent";
 import { loadConfig } from "../config/config.ts";
 import { registerAutonomousPolicy } from "./autonomous-policy.ts";
 import { TeamToolParams, type TeamToolParamsValue } from "../schema/team-tool-schema.ts";
@@ -9,6 +9,7 @@ import { handleTeamManagerCommand } from "./team-manager-command.ts";
 import { handleTeamTool, type TeamToolDetails } from "./team-tool.ts";
 import { listRuns } from "./run-index.ts";
 import { RunDashboard, type RunDashboardSelection } from "../ui/run-dashboard.ts";
+import { registerPiCrewRpc, type PiCrewRpcHandle } from "./cross-extension-rpc.ts";
 
 function parseRunArgs(args: string): TeamToolParamsValue {
 	const tokens = args.match(/"[^"]*"|'[^']*'|\S+/g)?.map((token) => token.replace(/^['"]|['"]$/g, "")) ?? [];
@@ -64,15 +65,22 @@ function setNestedConfig(config: Record<string, unknown>, key: string, value: un
 
 export function registerPiTeams(pi: ExtensionAPI): void {
 	const notifierState: AsyncNotifierState = { seenFinishedRunIds: new Set() };
+	let currentCtx: ExtensionContext | undefined;
+	let rpcHandle: PiCrewRpcHandle | undefined;
 	registerAutonomousPolicy(pi);
+	rpcHandle = registerPiCrewRpc((pi as unknown as { events?: Parameters<typeof registerPiCrewRpc>[0] }).events, () => currentCtx);
 
 	pi.on("session_start", (_event, ctx) => {
+		currentCtx = ctx;
 		notifyActiveRuns(ctx);
 		const loadedConfig = loadConfig(ctx.cwd);
 		startAsyncRunNotifier(ctx, notifierState, loadedConfig.config.notifierIntervalMs ?? 5000);
 	});
 	pi.on("session_shutdown", () => {
 		stopAsyncRunNotifier(notifierState);
+		currentCtx = undefined;
+		rpcHandle?.unsubscribe();
+		rpcHandle = undefined;
 	});
 
 	const tool: ToolDefinition = {
@@ -167,7 +175,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 			const config: Record<string, unknown> = { operation };
 			for (const token of tokens.filter((item) => item.includes("="))) {
 				const [key, ...rest] = token.split("=");
-				if (key) config[key] = rest.join("=");
+				if (key) config[key] = parseScalar(rest.join("="));
 			}
 			const result = await handleTeamTool({ action: "api", runId, config }, ctx);
 			await notifyCommandResult(ctx, commandText(result));
@@ -255,7 +263,15 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 				if (selection.action === "reload") continue;
 				const result = selection.action === "api"
 					? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-manifest" } }, ctx)
-					: await handleTeamTool({ action: selection.action, runId: selection.runId }, ctx);
+					: selection.action === "agents"
+						? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "agent-dashboard" } }, ctx)
+						: selection.action === "agent-events"
+							? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-events", limit: 50 } }, ctx)
+							: selection.action === "agent-output"
+								? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-output", maxBytes: 32_000 } }, ctx)
+								: selection.action === "agent-transcript"
+									? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-transcript" } }, ctx)
+									: await handleTeamTool({ action: selection.action, runId: selection.runId }, ctx);
 				await notifyCommandResult(ctx, commandText(result));
 				return;
 			}

package/src/extension/result-watcher.ts

@@ -0,0 +1,89 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createFileCoalescer } from "../utils/file-coalescer.ts";
+
+export interface ResultWatcherEvents {
+	emit(event: string, data: unknown): void;
+}
+
+export interface ResultWatcherHandle {
+	start(): void;
+	prime(): void;
+	stop(): void;
+}
+
+export interface ResultWatcherOptions {
+	eventName?: string;
+	completionTtlMs?: number;
+}
+
+function readJson(filePath: string): unknown | undefined {
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+	} catch {
+		return undefined;
+	}
+}
+
+function completionKey(payload: unknown, file: string): string {
+	if (!payload || typeof payload !== "object" || Array.isArray(payload)) return `file:${file}`;
+	const obj = payload as Record<string, unknown>;
+	const id = [obj.runId, obj.sessionId, obj.id, obj.status].filter((entry): entry is string => typeof entry === "string" && entry.length > 0).join(":");
+	return id || `file:${file}`;
+}
+
+export function createResultWatcher(events: ResultWatcherEvents, resultsDir: string, eventNameOrOptions: string | ResultWatcherOptions = "pi-crew:run-result"): ResultWatcherHandle {
+	const options = typeof eventNameOrOptions === "string" ? { eventName: eventNameOrOptions } : eventNameOrOptions;
+	const eventName = options.eventName ?? "pi-crew:run-result";
+	const completionTtlMs = options.completionTtlMs ?? 5 * 60_000;
+	const seen = new Map<string, number>();
+	let watcher: fs.FSWatcher | undefined;
+	let restartTimer: ReturnType<typeof setTimeout> | undefined;
+	const coalescer = createFileCoalescer((file) => {
+		const filePath = path.join(resultsDir, file);
+		if (!file.endsWith(".json") || !fs.existsSync(filePath)) return;
+		const payload = readJson(filePath);
+		if (payload !== undefined) {
+			const now = Date.now();
+			for (const [key, expiresAt] of seen) if (expiresAt <= now) seen.delete(key);
+			const key = completionKey(payload, file);
+			if (!seen.has(key)) {
+				seen.set(key, now + completionTtlMs);
+				events.emit(eventName, payload);
+			}
+		}
+		try { fs.unlinkSync(filePath); } catch {}
+	}, 50);
+	const scheduleRestart = () => {
+		if (restartTimer) clearTimeout(restartTimer);
+		restartTimer = setTimeout(() => {
+			restartTimer = undefined;
+			try { handle.start(); } catch {}
+		}, 3000);
+		restartTimer.unref?.();
+	};
+	const handle: ResultWatcherHandle = {
+		start() {
+			fs.mkdirSync(resultsDir, { recursive: true });
+			watcher?.close();
+			watcher = fs.watch(resultsDir, (event, file) => {
+				if (event !== "rename" || !file) return;
+				coalescer.schedule(file.toString());
+			});
+			watcher.on("error", scheduleRestart);
+			watcher.unref?.();
+		},
+		prime() {
+			if (!fs.existsSync(resultsDir)) return;
+			for (const file of fs.readdirSync(resultsDir).filter((entry) => entry.endsWith(".json"))) coalescer.schedule(file, 0);
+		},
+		stop() {
+			watcher?.close();
+			watcher = undefined;
+			if (restartTimer) clearTimeout(restartTimer);
+			restartTimer = undefined;
+			coalescer.clear();
+		},
+	};
+	return handle;
+}