pi-crew 0.2.2 → 0.2.4

package/src/ui/render-scheduler.ts

@@ -1,143 +1,216 @@
-import { logInternalError } from "../utils/internal-error.ts";
-
-export interface RenderSchedulerEventBus {
-	on?: (event: string, handler: (payload: unknown) => void) => (() => void) | void;
-}
-
-export interface RenderSchedulerOptions {
-	debounceMs?: number;
-	fallbackMs?: number;
-	events?: string[];
-	onInvalidate?: (payload: unknown) => void;
-}
-
-const DEFAULT_EVENTS = [
-	"crew.run.created",
-	"crew.run.completed",
-	"crew.run.failed",
-	"crew.run.cancelled",
-	"crew.subagent.completed",
-	"crew.subagent.failed",
-	"crew.mailbox.updated",
-	"crew.mailbox.message",
-];
-
-/**
- * Coordinates UI renders with debounce + fallback polling.
- *
- * Critical: uses recursive setTimeout instead of setInterval + a rendering
- * guard (`rendering` / `pendingRender`) so that when render() takes longer
- * than the fallback interval, callbacks do NOT pile up and storm the event
- * loop.  Instead, overlapping schedules are collapsed into a single deferred
- * re-render.
- */
-export class RenderScheduler {
-	private readonly render: () => void;
-	private readonly onInvalidate?: (payload: unknown) => void;
-	private readonly debounceMs: number;
-	private readonly fallbackMs: number;
-	private debounceTimer: ReturnType<typeof setTimeout> | undefined;
-	private fallbackTimer: ReturnType<typeof setTimeout> | undefined;
-	private disposed = false;
-	private lastEventAt = 0;
-	private rendering = false;
-	private pendingRender = false;
-	private readonly unsubs: Array<() => void> = [];
-
-	constructor(events: RenderSchedulerEventBus | undefined, render: () => void, options: RenderSchedulerOptions = {}) {
-		this.render = render;
-		this.onInvalidate = options.onInvalidate;
-		this.debounceMs = options.debounceMs ?? 75;
-		this.fallbackMs = options.fallbackMs ?? 750;
-		for (const event of options.events ?? DEFAULT_EVENTS) this.subscribe(events, event);
-		this.fallbackTimer = setTimeout(() => this.fallbackLoop(), this.fallbackMs);
-		this.fallbackTimer.unref();
-	}
-
-	private subscribe(events: RenderSchedulerEventBus | undefined, event: string): void {
-		if (!events?.on) return;
-		const handler = (payload: unknown): void => this.schedule(payload);
-		try {
-			const unsub = events.on(event, handler);
-			if (typeof unsub === "function") this.unsubs.push(unsub);
-		} catch (error) {
-			logInternalError("render-scheduler.subscribe", error, event);
-		}
-	}
-
-	/** Recursive setTimeout — avoids setInterval timer storms. */
-	private fallbackLoop(): void {
-		if (this.disposed) return;
-		if (Date.now() - this.lastEventAt < this.fallbackMs) {
-			if (this.disposed) return;
-			this.fallbackTimer = setTimeout(() => this.fallbackLoop(), this.fallbackMs);
-			this.fallbackTimer.unref();
-			return;
-		}
-		this.schedule();
-		if (this.disposed) return;
-		this.fallbackTimer = setTimeout(() => this.fallbackLoop(), this.fallbackMs);
-		this.fallbackTimer.unref();
-	}
-
-	schedule(payload?: unknown): void {
-		if (this.disposed) return;
-		this.lastEventAt = Date.now();
-		try {
-			this.onInvalidate?.(payload);
-		} catch (error) {
-			logInternalError("render-scheduler.invalidate", error);
-		}
-		if (this.debounceTimer) clearTimeout(this.debounceTimer);
-		this.debounceTimer = setTimeout(() => {
-			this.debounceTimer = undefined;
-			this.flush();
-		}, this.debounceMs);
-		this.debounceTimer.unref();
-	}
-
-	/**
-	 * Flush a render.  If a render is already in progress the request is
-	 * collapsed: `pendingRender` is set and the caller that holds
-	 * `rendering==true` will loop one more time after finishing.
-	 */
-	flush(): void {
-		if (this.disposed) return;
-		if (this.rendering) {
-			this.pendingRender = true;
-			return;
-		}
-		this.rendering = true;
-		this.pendingRender = false;
-		let iterations = 0;
-		try {
-			do {
-				this.pendingRender = false;
-				this.render();
-				iterations += 1;
-				// Safety valve: 5 re-renders max per flush to prevent infinite loops
-				// if render() itself calls flush() synchronously.
-			} while (this.pendingRender && !this.disposed && iterations < 5);
-		} catch (error) {
-			logInternalError("render-scheduler.render", error);
-		} finally {
-			this.rendering = false;
-			// If we hit the iteration cap, schedule one more render to drain.
-			if (iterations >= 5 && this.pendingRender && !this.disposed) {
-				this.schedule();
-			}
-		}
-	}
-
-	dispose(): void {
-		if (this.disposed) return;
-		this.disposed = true;
-		if (this.debounceTimer) clearTimeout(this.debounceTimer);
-		if (this.fallbackTimer) clearTimeout(this.fallbackTimer);
-		this.debounceTimer = undefined;
-		this.fallbackTimer = undefined;
-		for (const unsub of this.unsubs.splice(0)) {
-			try { unsub(); } catch (error) { logInternalError("render-scheduler.unsubscribe", error); }
-		}
-	}
-}
+import { logInternalError } from "../utils/internal-error.ts";
+
+export interface RenderSchedulerEventBus {
+	on?: (event: string, handler: (payload: unknown) => void) => (() => void) | void;
+}
+
+export interface RenderSchedulerOptions {
+	debounceMs?: number;
+	/**
+	 * Maximum interval (ms) between auto-refreshes when no event arrives.
+	 * Can be a function returning a dynamic interval — useful to tick fast
+	 * while a run is active (e.g., 160ms aligned with spinner) and slow
+	 * down when idle (e.g., 1000ms) without burning CPU.
+	 */
+	fallbackMs?: number | (() => number);
+	events?: string[];
+	onInvalidate?: (payload: unknown) => void;
+	/**
+	 * 1.9: coalesce `onInvalidate` calls per-runId within this window so that
+	 * bursts of `crew.subagent.completed`-style events touching the same run
+	 * trigger a single cache invalidate instead of N. Set to 0 to disable.
+	 */
+	invalidateCoalesceMs?: number;
+}
+
+const DEFAULT_EVENTS = [
+	"crew.run.created",
+	"crew.run.completed",
+	"crew.run.failed",
+	"crew.run.cancelled",
+	"crew.subagent.completed",
+	"crew.subagent.failed",
+	"crew.mailbox.updated",
+	"crew.mailbox.message",
+];
+
+/**
+ * Coordinates UI renders with debounce + fallback polling.
+ *
+ * Critical: uses recursive setTimeout instead of setInterval + a rendering
+ * guard (`rendering` / `pendingRender`) so that when render() takes longer
+ * than the fallback interval, callbacks do NOT pile up and storm the event
+ * loop.  Instead, overlapping schedules are collapsed into a single deferred
+ * re-render.
+ */
+export class RenderScheduler {
+	private readonly render: () => void;
+	private readonly onInvalidate?: (payload: unknown) => void;
+	private readonly debounceMs: number;
+	private readonly fallbackProvider: () => number;
+	private readonly fallbackMs: number;
+	private readonly invalidateCoalesceMs: number;
+	private debounceTimer: ReturnType<typeof setTimeout> | undefined;
+	private fallbackTimer: ReturnType<typeof setTimeout> | undefined;
+	private invalidateTimer: ReturnType<typeof setTimeout> | undefined;
+	/** runId → most recent payload to forward when the coalesce window flushes. */
+	private invalidateBuffer = new Map<string, unknown>();
+	private disposed = false;
+	private lastEventAt = 0;
+	private rendering = false;
+	private pendingRender = false;
+	private readonly unsubs: Array<() => void> = [];
+
+	constructor(events: RenderSchedulerEventBus | undefined, render: () => void, options: RenderSchedulerOptions = {}) {
+		this.render = render;
+		this.onInvalidate = options.onInvalidate;
+		this.debounceMs = options.debounceMs ?? 75;
+		const fallback = options.fallbackMs ?? 750;
+		this.fallbackProvider = typeof fallback === "function" ? fallback : () => fallback;
+		this.fallbackMs = typeof fallback === "number" ? fallback : 750;
+		this.invalidateCoalesceMs = options.invalidateCoalesceMs ?? 50;
+		for (const event of options.events ?? DEFAULT_EVENTS) this.subscribe(events, event);
+		this.fallbackTimer = setTimeout(() => this.fallbackLoop(), this.currentFallbackMs());
+		this.fallbackTimer.unref();
+	}
+
+	private currentFallbackMs(): number {
+		try {
+			const value = this.fallbackProvider();
+			return Number.isFinite(value) && value > 0 ? value : 750;
+		} catch (error) {
+			logInternalError("render-scheduler.fallbackProvider", error);
+			return 750;
+		}
+	}
+
+	private subscribe(events: RenderSchedulerEventBus | undefined, event: string): void {
+		if (!events?.on) return;
+		const handler = (payload: unknown): void => this.schedule(payload);
+		try {
+			const unsub = events.on(event, handler);
+			if (typeof unsub === "function") this.unsubs.push(unsub);
+		} catch (error) {
+			logInternalError("render-scheduler.subscribe", error, event);
+		}
+	}
+
+	/** Recursive setTimeout — avoids setInterval timer storms. */
+	private fallbackLoop(): void {
+		if (this.disposed) return;
+		const fallbackMs = this.currentFallbackMs();
+		if (Date.now() - this.lastEventAt < fallbackMs) {
+			if (this.disposed) return;
+			this.fallbackTimer = setTimeout(() => this.fallbackLoop(), fallbackMs);
+			this.fallbackTimer.unref();
+			return;
+		}
+		this.schedule();
+		if (this.disposed) return;
+		this.fallbackTimer = setTimeout(() => this.fallbackLoop(), this.currentFallbackMs());
+		this.fallbackTimer.unref();
+	}
+
+	schedule(payload?: unknown): void {
+		if (this.disposed) return;
+		this.lastEventAt = Date.now();
+		this.invalidate(payload);
+		if (this.debounceTimer) clearTimeout(this.debounceTimer);
+		this.debounceTimer = setTimeout(() => {
+			this.debounceTimer = undefined;
+			this.flush();
+		}, this.debounceMs);
+		this.debounceTimer.unref();
+	}
+
+	/**
+	 * 1.9: forward `onInvalidate` immediately when the payload has no `runId`
+	 * (we cannot dedup it). When it carries a runId, buffer the latest payload
+	 * per runId and flush on a coalesce timer so high-frequency event bursts
+	 * (`crew.subagent.completed` for parallel tasks) collapse into one
+	 * invalidate per affected run.
+	 */
+	private invalidate(payload: unknown): void {
+		try {
+			const runId = typeof payload === "object" && payload !== null && "runId" in payload && typeof (payload as { runId: unknown }).runId === "string"
+				? (payload as { runId: string }).runId
+				: undefined;
+			if (runId === undefined || this.invalidateCoalesceMs <= 0) {
+				this.onInvalidate?.(payload);
+				return;
+			}
+			this.invalidateBuffer.set(runId, payload);
+			if (!this.invalidateTimer) {
+				this.invalidateTimer = setTimeout(() => this.flushInvalidate(), this.invalidateCoalesceMs);
+				this.invalidateTimer.unref();
+			}
+		} catch (error) {
+			logInternalError("render-scheduler.invalidate", error);
+		}
+	}
+
+	private flushInvalidate(): void {
+		this.invalidateTimer = undefined;
+		if (this.disposed) {
+			this.invalidateBuffer.clear();
+			return;
+		}
+		const buffered = this.invalidateBuffer;
+		this.invalidateBuffer = new Map();
+		for (const payload of buffered.values()) {
+			try {
+				this.onInvalidate?.(payload);
+			} catch (error) {
+				logInternalError("render-scheduler.invalidate.flush", error);
+			}
+		}
+	}
+
+	/**
+	 * Flush a render.  If a render is already in progress the request is
+	 * collapsed: `pendingRender` is set and the caller that holds
+	 * `rendering==true` will loop one more time after finishing.
+	 */
+	flush(): void {
+		if (this.disposed) return;
+		if (this.rendering) {
+			this.pendingRender = true;
+			return;
+		}
+		this.rendering = true;
+		this.pendingRender = false;
+		let iterations = 0;
+		try {
+			do {
+				this.pendingRender = false;
+				this.render();
+				iterations += 1;
+				// Safety valve: 5 re-renders max per flush to prevent infinite loops
+				// if render() itself calls flush() synchronously.
+			} while (this.pendingRender && !this.disposed && iterations < 5);
+		} catch (error) {
+			logInternalError("render-scheduler.render", error);
+		} finally {
+			this.rendering = false;
+			// If we hit the iteration cap, schedule one more render to drain.
+			if (iterations >= 5 && this.pendingRender && !this.disposed) {
+				this.schedule();
+			}
+		}
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		if (this.debounceTimer) clearTimeout(this.debounceTimer);
+		if (this.fallbackTimer) clearTimeout(this.fallbackTimer);
+		if (this.invalidateTimer) clearTimeout(this.invalidateTimer);
+		this.debounceTimer = undefined;
+		this.fallbackTimer = undefined;
+		this.invalidateTimer = undefined;
+		this.invalidateBuffer.clear();
+		for (const unsub of this.unsubs.splice(0)) {
+			try { unsub(); } catch (error) { logInternalError("render-scheduler.unsubscribe", error); }
+		}
+	}
+}

package/src/ui/run-action-dispatcher.ts

@@ -1,117 +1,118 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-import type { MetricRegistry } from "../observability/metric-registry.ts";
-// Lazy-loaded: team-tool.ts pulls in entire runtime chain.
-import type { handleTeamTool as HandleTeamToolFn } from "../extension/team-tool.ts";
-let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
-async function handleTeamTool(params: Parameters<typeof HandleTeamToolFn>[0], ctx: Parameters<typeof HandleTeamToolFn>[1]): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
-	if (!_cachedHandleTeamTool) {
-		const mod = await import("../extension/team-tool.ts");
-		_cachedHandleTeamTool = mod.handleTeamTool;
-	}
-	return _cachedHandleTeamTool(params, ctx);
-}
-import { isToolError, textFromToolResult } from "../extension/tool-result.ts";
-import { loadRunManifestById, saveRunTasks } from "../state/state-store.ts";
-import { appendEvent } from "../state/event-log.ts";
-import { readCrewAgents } from "../runtime/crew-agent-records.ts";
-import { exportDiagnostic } from "../runtime/diagnostic-export.ts";
-import type { MailboxDirection, MailboxMessage } from "../state/mailbox.ts";
-
-export interface RunActionResult {
-	ok: boolean;
-	message: string;
-	data?: unknown;
-}
-
-function okFromTool(result: Awaited<ReturnType<typeof handleTeamTool>>): RunActionResult {
-	return { ok: !isToolError(result), message: textFromToolResult(result), data: result };
-}
-
-function err(error: unknown): RunActionResult {
-	return { ok: false, message: error instanceof Error ? error.message : String(error) };
-}
-
-async function dispatchApi(ctx: ExtensionContext, runId: string, config: Record<string, unknown>): Promise<RunActionResult> {
-	try {
-		return okFromTool(await handleTeamTool({ action: "api", runId, config }, ctx));
-	} catch (error) {
-		return err(error);
-	}
-}
-
-function parseMailboxMessages(text: string): MailboxMessage[] {
-	try {
-		const parsed = JSON.parse(text) as unknown;
-		if (!Array.isArray(parsed)) return [];
-		return parsed.filter((item): item is MailboxMessage => Boolean(item) && typeof item === "object" && !Array.isArray(item) && typeof (item as { id?: unknown }).id === "string");
-	} catch {
-		return [];
-	}
-}
-
-export function dispatchMailboxAck(ctx: ExtensionContext, runId: string, messageId: string): Promise<RunActionResult> {
-	return dispatchApi(ctx, runId, { operation: "ack-message", messageId });
-}
-
-export function dispatchMailboxNudge(ctx: ExtensionContext, runId: string, agentId: string, message: string): Promise<RunActionResult> {
-	return dispatchApi(ctx, runId, { operation: "nudge-agent", agentId, message });
-}
-
-export function dispatchMailboxCompose(ctx: ExtensionContext, runId: string, payload: { from: string; to: string; body: string; taskId?: string; direction: MailboxDirection }): Promise<RunActionResult> {
-	return dispatchApi(ctx, runId, { operation: "send-message", ...payload });
-}
-
-export async function dispatchMailboxAckAll(ctx: ExtensionContext, runId: string): Promise<RunActionResult> {
-	const listed = await dispatchApi(ctx, runId, { operation: "read-mailbox", direction: "inbox" });
-	if (!listed.ok) return listed;
-	const messages = parseMailboxMessages(listed.message).filter((message) => message.status !== "acknowledged");
-	let count = 0;
-	for (const message of messages) {
-		const acked = await dispatchMailboxAck(ctx, runId, message.id);
-		if (!acked.ok) return { ok: false, message: `Acknowledged ${count}/${messages.length}; failed ${message.id}: ${acked.message}` };
-		count += 1;
-	}
-	return { ok: true, message: `Acknowledged ${count} messages.`, data: { count } };
-}
-
-export function dispatchHealthRecovery(ctx: ExtensionContext, runId: string): Promise<RunActionResult> {
-	return dispatchApi(ctx, runId, { operation: "foreground-interrupt", reason: "operator health recovery" });
-}
-
-export async function dispatchKillStaleWorkers(ctx: ExtensionContext, runId: string): Promise<RunActionResult> {
-	try {
-		const loaded = loadRunManifestById(ctx.cwd, runId);
-		if (!loaded) return { ok: false, message: `Run '${runId}' not found.` };
-		const currentMs = Date.now();
-		const staleMs = 60_000;
-		const now = new Date(currentMs).toISOString();
-		let count = 0;
-		const tasks = loaded.tasks.map((task) => {
-			if ((task.status !== "running" && task.status !== "queued") || !task.heartbeat || task.heartbeat.alive === false) return task;
-			const lastSeenMs = Date.parse(task.heartbeat.lastSeenAt);
-			if (!Number.isFinite(lastSeenMs) || currentMs - lastSeenMs <= staleMs) return task;
-			count += 1;
-			return { ...task, heartbeat: { ...task.heartbeat, alive: false, lastSeenAt: now } };
-		});
-		saveRunTasks(loaded.manifest, tasks);
-		appendEvent(loaded.manifest.eventsPath, { type: "worker.kill_stale", runId, message: `Marked ${count} stale worker heartbeat(s) dead.`, data: { count } });
-		return { ok: true, message: `Marked ${count} stale worker heartbeat(s) dead.`, data: { count } };
-	} catch (error) {
-		return err(error);
-	}
-}
-
-export async function dispatchDiagnosticExport(ctx: ExtensionContext, runId: string, options: { registry?: MetricRegistry } = {}): Promise<RunActionResult> {
-	try {
-		const exported = await exportDiagnostic(ctx, runId, options);
-		return { ok: true, message: `Diagnostic exported to ${exported.path}`, data: exported.path };
-	} catch (error) {
-		return err(error);
-	}
-}
-
-export function defaultNudgeAgentId(ctx: Pick<ExtensionContext, "cwd">, runId: string): string | undefined {
-	const loaded = loadRunManifestById(ctx.cwd, runId);
-	if (!loaded) return undefined;
-	return readCrewAgents(loaded.manifest).find((agent) => agent.status === "running" || agent.status === "queued")?.taskId;
-}
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { MetricRegistry } from "../observability/metric-registry.ts";
+// Lazy-loaded: team-tool.ts pulls in entire runtime chain.
+import type { handleTeamTool as HandleTeamToolFn } from "../extension/team-tool.ts";
+let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
+async function handleTeamTool(params: Parameters<typeof HandleTeamToolFn>[0], ctx: Parameters<typeof HandleTeamToolFn>[1]): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
+	if (!_cachedHandleTeamTool) {
+		// LAZY: avoid pulling team-tool.ts (and its entire runtime chain) into module load.
+		const mod = await import("../extension/team-tool.ts");
+		_cachedHandleTeamTool = mod.handleTeamTool;
+	}
+	return _cachedHandleTeamTool(params, ctx);
+}
+import { isToolError, textFromToolResult } from "../extension/tool-result.ts";
+import { loadRunManifestById, saveRunTasks } from "../state/state-store.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { readCrewAgents } from "../runtime/crew-agent-records.ts";
+import { exportDiagnostic } from "../runtime/diagnostic-export.ts";
+import type { MailboxDirection, MailboxMessage } from "../state/mailbox.ts";
+
+export interface RunActionResult {
+	ok: boolean;
+	message: string;
+	data?: unknown;
+}
+
+function okFromTool(result: Awaited<ReturnType<typeof handleTeamTool>>): RunActionResult {
+	return { ok: !isToolError(result), message: textFromToolResult(result), data: result };
+}
+
+function err(error: unknown): RunActionResult {
+	return { ok: false, message: error instanceof Error ? error.message : String(error) };
+}
+
+async function dispatchApi(ctx: ExtensionContext, runId: string, config: Record<string, unknown>): Promise<RunActionResult> {
+	try {
+		return okFromTool(await handleTeamTool({ action: "api", runId, config }, ctx));
+	} catch (error) {
+		return err(error);
+	}
+}
+
+function parseMailboxMessages(text: string): MailboxMessage[] {
+	try {
+		const parsed = JSON.parse(text) as unknown;
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((item): item is MailboxMessage => Boolean(item) && typeof item === "object" && !Array.isArray(item) && typeof (item as { id?: unknown }).id === "string");
+	} catch {
+		return [];
+	}
+}
+
+export function dispatchMailboxAck(ctx: ExtensionContext, runId: string, messageId: string): Promise<RunActionResult> {
+	return dispatchApi(ctx, runId, { operation: "ack-message", messageId });
+}
+
+export function dispatchMailboxNudge(ctx: ExtensionContext, runId: string, agentId: string, message: string): Promise<RunActionResult> {
+	return dispatchApi(ctx, runId, { operation: "nudge-agent", agentId, message });
+}
+
+export function dispatchMailboxCompose(ctx: ExtensionContext, runId: string, payload: { from: string; to: string; body: string; taskId?: string; direction: MailboxDirection }): Promise<RunActionResult> {
+	return dispatchApi(ctx, runId, { operation: "send-message", ...payload });
+}
+
+export async function dispatchMailboxAckAll(ctx: ExtensionContext, runId: string): Promise<RunActionResult> {
+	const listed = await dispatchApi(ctx, runId, { operation: "read-mailbox", direction: "inbox" });
+	if (!listed.ok) return listed;
+	const messages = parseMailboxMessages(listed.message).filter((message) => message.status !== "acknowledged");
+	let count = 0;
+	for (const message of messages) {
+		const acked = await dispatchMailboxAck(ctx, runId, message.id);
+		if (!acked.ok) return { ok: false, message: `Acknowledged ${count}/${messages.length}; failed ${message.id}: ${acked.message}` };
+		count += 1;
+	}
+	return { ok: true, message: `Acknowledged ${count} messages.`, data: { count } };
+}
+
+export function dispatchHealthRecovery(ctx: ExtensionContext, runId: string): Promise<RunActionResult> {
+	return dispatchApi(ctx, runId, { operation: "foreground-interrupt", reason: "operator health recovery" });
+}
+
+export async function dispatchKillStaleWorkers(ctx: ExtensionContext, runId: string): Promise<RunActionResult> {
+	try {
+		const loaded = loadRunManifestById(ctx.cwd, runId);
+		if (!loaded) return { ok: false, message: `Run '${runId}' not found.` };
+		const currentMs = Date.now();
+		const staleMs = 60_000;
+		const now = new Date(currentMs).toISOString();
+		let count = 0;
+		const tasks = loaded.tasks.map((task) => {
+			if ((task.status !== "running" && task.status !== "queued") || !task.heartbeat || task.heartbeat.alive === false) return task;
+			const lastSeenMs = Date.parse(task.heartbeat.lastSeenAt);
+			if (!Number.isFinite(lastSeenMs) || currentMs - lastSeenMs <= staleMs) return task;
+			count += 1;
+			return { ...task, heartbeat: { ...task.heartbeat, alive: false, lastSeenAt: now } };
+		});
+		saveRunTasks(loaded.manifest, tasks);
+		appendEvent(loaded.manifest.eventsPath, { type: "worker.kill_stale", runId, message: `Marked ${count} stale worker heartbeat(s) dead.`, data: { count } });
+		return { ok: true, message: `Marked ${count} stale worker heartbeat(s) dead.`, data: { count } };
+	} catch (error) {
+		return err(error);
+	}
+}
+
+export async function dispatchDiagnosticExport(ctx: ExtensionContext, runId: string, options: { registry?: MetricRegistry } = {}): Promise<RunActionResult> {
+	try {
+		const exported = await exportDiagnostic(ctx, runId, options);
+		return { ok: true, message: `Diagnostic exported to ${exported.path}`, data: exported.path };
+	} catch (error) {
+		return err(error);
+	}
+}
+
+export function defaultNudgeAgentId(ctx: Pick<ExtensionContext, "cwd">, runId: string): string | undefined {
+	const loaded = loadRunManifestById(ctx.cwd, runId);
+	if (!loaded) return undefined;
+	return readCrewAgents(loaded.manifest).find((agent) => agent.status === "running" || agent.status === "queued")?.taskId;
+}