pi-crew 0.9.53 → 0.9.55

package/src/runtime/process-lifecycle.ts

@@ -0,0 +1,491 @@
+/**
+ * Owned-process lifecycle abstraction (P0 item #3).
+ *
+ * Distilled and adapted from gajae-code's `runtime/process-lifecycle.ts`.
+ *
+ * Two complementary primitives:
+ *
+ *   F1(a) {@link spawnOwnedProcess} / {@link OwnedProcess} — wraps a
+ *         `child_process.spawn` child with explicit ownership: escalating
+ *         (SIGTERM → grace → SIGKILL) teardown, idempotent `dispose()`, bounded
+ *         `awaitExit()`, abort-signal wiring, and postmortem registration so
+ *         an owned child can never outlive its owner.
+ *
+ *   F1(b) {@link registerResourceOwner} — a generic postmortem registry for
+ *         NON-process resources (timers, sockets, Workers, VM contexts) with
+ *         `disposeAllOwners()` / `disposeOwner(name)`.
+ *
+ * ╔═══════════════════════════════════════════════════════════════════════════╗
+ * ║  IMPORTANT — INCREMENTAL, NOT FULL MIGRATION                              ║
+ * ║  pi-crew ALREADY has sophisticated kill logic in child-pi.ts              ║
+ * ║  (killProcessTree, escalating SIGTERM→grace→SIGKILL, hard-kill timer,    ║
+ * ║  post-exit stdio guard) and async-runner.ts does detached/setsid spawns.  ║
+ * ║  Those paths are NOT rewritten here. This module provides a clean         ║
+ * ║  ownership primitive for NEW code paths that need guaranteed teardown     ║
+ * ║  without re-implementing the escalation dance each time.                  ║
+ * ╚═══════════════════════════════════════════════════════════════════════════╝
+ *
+ * Cross-platform: on Windows there is no SIGTERM; teardown uses
+ * `taskkill /F /T /PID` escalation directly (force-kill the whole tree).
+ * See `.crew/knowledge.md` gotchas: BSD/Windows signal handling differs.
+ */
+import { type ChildProcess, type SpawnOptions, spawn } from "node:child_process";
+import { logInternalError } from "../utils/internal-error.ts";
+
+// ── tunables ──────────────────────────────────────────────────────────────────
+
+const DEFAULT_GRACEFUL_MS = 2_000;
+/** Hard cap on how long dispose() waits after SIGKILL before giving up, so a
+ *  wedged/unkillable child can never block shutdown forever. */
+const SIGKILL_REAP_CAP_MS = 2_000;
+/** After the root child exits on its own, how long to wait for the process
+ *  group to drain before deregistering. Clean servers drain immediately. */
+const ROOT_EXIT_DRAIN_MS = 250;
+
+const isPosix = process.platform !== "win32";
+
+const delay = (ms: number): Promise<void> =>
+	new Promise((resolve) => {
+		setTimeout(resolve, Math.max(0, ms));
+	});
+
+/** Poll `predicate` until true or `timeoutMs` elapses. Returns the final value. */
+async function pollUntil(predicate: () => boolean, timeoutMs: number, intervalMs = 20): Promise<boolean> {
+	if (predicate()) return true;
+	const deadline = Date.now() + Math.max(0, timeoutMs);
+	while (Date.now() < deadline) {
+		await delay(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+		if (predicate()) return true;
+	}
+	return predicate();
+}
+
+/** Whether a POSIX process group still has any member (zombies count as alive). */
+function groupAlive(pgid: number): boolean {
+	try {
+		process.kill(-pgid, 0);
+		return true;
+	} catch (err) {
+		// EPERM => the group exists but we cannot signal it; treat as alive.
+		return (err as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+// ── F1(a) OwnedProcess ────────────────────────────────────────────────────────
+
+/** Options for {@link spawnOwnedProcess}. */
+export interface SpawnOwnedOptions {
+	cwd?: string;
+	env?: Record<string, string | undefined>;
+	/** stdin mode passed through to the child. Defaults to `"ignore"`. */
+	stdin?: "pipe" | "ignore";
+	/** When aborted, the owned process tree is disposed (escalating kill). */
+	signal?: AbortSignal;
+	/** Grace period (ms) between SIGTERM and SIGKILL on dispose. Default 2000. */
+	gracefulMs?: number;
+	/**
+	 * Spawn the child as its own process-group leader so the whole descendant
+	 * tree can be signalled on dispose. Defaults to `true` on POSIX. Has no
+	 * effect on Windows, where teardown falls back to single-process kill.
+	 */
+	processGroup?: boolean;
+	/** Label used in diagnostics. */
+	name?: string;
+	/** Extra SpawnOptions merged in (e.g. windowsHide). */
+	extraOptions?: SpawnOptions;
+}
+
+/** Result of a bounded {@link OwnedProcess.awaitExit}. */
+export interface AwaitExitResult {
+	/** `true` when the process has exited; `false` when the timeout fired first. */
+	exited: boolean;
+	/** Exit code if known, else `null`. */
+	code: number | null;
+}
+
+/** Exit callback signature for {@link OwnedProcess.onExit}. */
+export type OwnedExitCallback = (code: number | null, signal: NodeJS.Signals | null) => void;
+
+/**
+ * A spawned child process owned by the runtime with guaranteed teardown.
+ *
+ * Implemented as a class so callers retain a strong handle and so `dispose()`
+ * can be idempotent (concurrent/repeated calls return the same in-flight
+ * promise). Never throws from `dispose()` / `awaitExit()`.
+ */
+export class OwnedProcess {
+	readonly child: ChildProcess;
+	readonly pid: number | undefined;
+	/** Process-group id (POSIX detached only); `undefined` on Windows / opt-out. */
+	readonly pgid: number | undefined;
+	private readonly gracefulMs: number;
+	private readonly name: string | undefined;
+	private disposed = false;
+	private disposePromise: Promise<void> | undefined;
+	private deregistered = false;
+	/** Terminal once teardown/reconciliation has confirmed the group is gone. */
+	private terminated = false;
+	private exitPromise: Promise<{
+		code: number | null;
+		signal: NodeJS.Signals | null;
+	}>;
+	private exitCallbacks = new Set<OwnedExitCallback>();
+	private onAbort: (() => void) | undefined;
+	private readonly abortSignal: AbortSignal | undefined;
+
+	constructor(child: ChildProcess, opts: SpawnOwnedOptions, registerSelf: (owner: OwnedProcess) => () => void) {
+		this.child = child;
+		this.pid = child.pid;
+		this.gracefulMs = opts.gracefulMs ?? DEFAULT_GRACEFUL_MS;
+		this.name = opts.name;
+		this.abortSignal = opts.signal;
+
+		const useGroup = (opts.processGroup ?? true) && isPosix;
+		// On POSIX with `detached`, the child is its own process-group leader,
+		// so the group id equals its pid.
+		this.pgid = useGroup ? child.pid : undefined;
+
+		this.exitPromise = new Promise((resolve) => {
+			child.once("exit", (code, signal) => {
+				resolve({ code: code, signal: signal });
+				for (const cb of this.exitCallbacks) {
+					try {
+						cb(code, signal);
+					} catch (err) {
+						logInternalError("owned-process.onExit-callback", err, this.name ? `name=${this.name}` : undefined);
+					}
+				}
+			});
+		});
+
+		// Register for postmortem cleanup and wire abort.
+		const deregister = registerSelf(this);
+		this.deregisterFn = deregister;
+
+		// When the root exits on its own (not via dispose), reconcile ownership
+		// by the *group*: after a short drain window, deregister if the group is
+		// empty, otherwise reap the owned group (no child outlives its owner).
+		void this.exitPromise
+			.then(() => {
+				if (this.disposed) return; // dispose() owns deregistration
+				if (this.pgid === undefined) {
+					this.deregisterInternal();
+					return;
+				}
+				void (async () => {
+					const drained = await pollUntil(() => !groupAlive(this.pgid!), ROOT_EXIT_DRAIN_MS);
+					if (this.disposed) return;
+					if (drained) {
+						this.deregisterInternal();
+						return;
+					}
+					// Root exited but the owned group still has descendants: reap them.
+					await this.dispose();
+				})();
+			})
+			.catch(() => undefined);
+
+		if (this.abortSignal) {
+			if (this.abortSignal.aborted) {
+				void this.dispose();
+			} else {
+				this.onAbort = () => void this.dispose();
+				this.abortSignal.addEventListener("abort", this.onAbort, {
+					once: true,
+				});
+			}
+		}
+	}
+
+	private deregisterFn: () => void = () => {};
+
+	/** `true` once `dispose()` has started. */
+	get isDisposed(): boolean {
+		return this.disposed;
+	}
+
+	/**
+	 * Register a callback invoked exactly once when the root child exits.
+	 * If the child has already exited, the callback is invoked synchronously
+	 * with the cached exit info. Returns an unsubscribe function.
+	 */
+	onExit(callback: OwnedExitCallback): () => void {
+		this.exitCallbacks.add(callback);
+		// If already exited, the exitPromise is resolved; fire immediately.
+		// We race to detect resolution without awaiting.
+		let settled = false;
+		this.exitPromise.then((info) => {
+			if (settled) return; // callback may have been removed
+			if (this.exitCallbacks.has(callback)) {
+				try {
+					callback(info.code, info.signal);
+				} catch (err) {
+					logInternalError("owned-process.onExit-immediate", err, this.name ? `name=${this.name}` : undefined);
+				}
+			}
+		});
+		return () => {
+			settled = true;
+			this.exitCallbacks.delete(callback);
+		};
+	}
+
+	/**
+	 * Wait for the root child to exit, optionally bounded by `timeoutMs`.
+	 * With no timeout it resolves only when the child exits. Never rejects.
+	 */
+	async awaitExit(opts?: { timeoutMs?: number }): Promise<AwaitExitResult> {
+		const exitResult = this.exitPromise.then((info) => ({
+			exited: true as const,
+			code: info.code,
+		}));
+		if (opts?.timeoutMs === undefined) return exitResult;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const timeout = new Promise<AwaitExitResult>((resolve) => {
+			timer = setTimeout(() => resolve({ exited: false, code: this.child.exitCode }), Math.max(0, opts.timeoutMs!));
+		});
+		try {
+			return await Promise.race([exitResult, timeout]);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}
+
+	/** Signal the process tree with `signal` (group-aware on POSIX). */
+	private signalTree(signal: NodeJS.Signals): void {
+		const pid = this.child.pid;
+		if (pid === undefined) return;
+		if (this.pgid !== undefined) {
+			try {
+				process.kill(-this.pgid, signal);
+				return;
+			} catch {
+				/* group already gone */
+			}
+			return;
+		}
+		try {
+			this.child.kill(signal);
+		} catch {
+			/* already gone */
+		}
+	}
+
+	private deregisterInternal(): void {
+		if (this.deregistered) return;
+		this.deregistered = true;
+		this.terminated = true;
+		this.deregisterFn();
+		if (this.onAbort && this.abortSignal) {
+			this.abortSignal.removeEventListener("abort", this.onAbort);
+			this.onAbort = undefined;
+		}
+	}
+
+	/**
+	 * Idempotently terminate the owned process *group*: SIGTERM the group, wait
+	 * `gracefulMs`, then SIGKILL, polling liveness throughout. On Windows,
+	 * escalate directly to taskkill /F /T /PID. Removes the abort listener and
+	 * deregisters from the live-owner set only after teardown has completed.
+	 * Repeated/concurrent calls return the same in-flight promise. Never throws.
+	 */
+	dispose(): Promise<void> {
+		// Already terminal: never re-probe a recycled pgid.
+		if (this.terminated) {
+			this.disposed = true;
+			if (!this.disposePromise) this.disposePromise = Promise.resolve();
+			return this.disposePromise;
+		}
+		if (this.disposePromise) return this.disposePromise;
+		this.disposed = true;
+		if (this.onAbort && this.abortSignal) {
+			this.abortSignal.removeEventListener("abort", this.onAbort);
+			this.onAbort = undefined;
+		}
+		this.disposePromise = (async () => {
+			try {
+				if (!isPosix) {
+					await this.disposeWindows();
+					return;
+				}
+				if (this.pgid !== undefined) {
+					// Group ownership: reap until the whole group is gone, even if
+					// the root has already exited (it may have backgrounded children).
+					if (!groupAlive(this.pgid)) return;
+					this.signalTree("SIGTERM");
+					if (await pollUntil(() => !groupAlive(this.pgid!), this.gracefulMs)) return;
+					this.signalTree("SIGKILL");
+					if (!(await pollUntil(() => !groupAlive(this.pgid!), SIGKILL_REAP_CAP_MS))) {
+						console.warn(
+							`[pi-crew] owned process group still alive after SIGKILL (name=${this.name ?? "?"}, pgid=${this.pgid})`,
+						);
+					}
+					return;
+				}
+				// Single-process fallback (processGroup:false).
+				if (this.child.exitCode !== null) return;
+				this.signalTree("SIGTERM");
+				if ((await this.awaitExit({ timeoutMs: this.gracefulMs })).exited) return;
+				this.signalTree("SIGKILL");
+				await this.awaitExit({ timeoutMs: SIGKILL_REAP_CAP_MS });
+			} catch (err) {
+				logInternalError("owned-process.dispose", err, this.name ? `name=${this.name}` : undefined);
+			} finally {
+				// Deregister only after teardown completes so a postmortem firing
+				// mid-grace still sees the owner.
+				this.deregisterInternal();
+			}
+		})();
+		return this.disposePromise;
+	}
+
+	/** Windows teardown: no SIGTERM; escalate to taskkill /F /T /PID. */
+	private async disposeWindows(): Promise<void> {
+		const pid = this.child.pid;
+		if (pid === undefined) return;
+		if (this.child.exitCode !== null) return;
+		// First try a graceful taskkill (no /F), then escalate to /F /T.
+		const tryTaskkill = (force: boolean): Promise<void> =>
+			new Promise((resolve) => {
+				const args = ["/T", "/PID", String(pid), ...(force ? ["/F"] : [])];
+				const tk = spawn("taskkill", args, {
+					stdio: "ignore",
+					windowsHide: true,
+				});
+				tk.on("error", () => resolve());
+				tk.on("exit", () => resolve());
+			});
+		await tryTaskkill(false);
+		if ((await this.awaitExit({ timeoutMs: this.gracefulMs })).exited) return;
+		await tryTaskkill(true);
+		await this.awaitExit({ timeoutMs: SIGKILL_REAP_CAP_MS });
+	}
+}
+
+// ── live-owner set + postmortem ───────────────────────────────────────────────
+
+const liveOwners = new Set<OwnedProcess>();
+let ownedPostmortemRegistered = false;
+
+function ensureOwnedPostmortem(): void {
+	if (ownedPostmortemRegistered) return;
+	ownedPostmortemRegistered = true;
+	// Register a process-exit handler that disposes every live owned process.
+	// We wire both beforeExit (event-loop empty) and exit (synchronous final).
+	const drain = async (): Promise<void> => {
+		await Promise.all([...liveOwners].map((owner) => owner.dispose().catch(() => undefined)));
+	};
+	process.once("beforeExit", () => {
+		void drain().catch(() => undefined);
+	});
+}
+
+/**
+ * Spawn a child process owned by the runtime. The returned {@link OwnedProcess}
+ * is registered for postmortem cleanup and tears down its whole process group
+ * on dispose/abort.
+ *
+ * NOTE: this is for NEW ownership-scoped spawns. Do NOT use it to replace
+ * child-pi.ts's runChildPi (which has its own battle-tested escalation logic)
+ * or async-runner.ts's intentionally-detached background spawns.
+ */
+export function spawnOwnedProcess(command: string, args: readonly string[] = [], opts: SpawnOwnedOptions = {}): OwnedProcess {
+	ensureOwnedPostmortem();
+	const useGroup = (opts.processGroup ?? true) && isPosix;
+	const spawnOpts: SpawnOptions = {
+		cwd: opts.cwd,
+		env: opts.env as NodeJS.ProcessEnv | undefined,
+		stdio: [opts.stdin ?? "ignore", "pipe", "pipe"],
+		detached: useGroup,
+		windowsHide: true,
+		...opts.extraOptions,
+	};
+	const child = spawn(command, args as string[], spawnOpts);
+	const owner = new OwnedProcess(child, opts, (self) => {
+		liveOwners.add(self);
+		return () => {
+			liveOwners.delete(self);
+		};
+	});
+	return owner;
+}
+
+/** Number of currently live owned processes. Exposed for leak assertions/tests. */
+export function liveOwnedProcessCount(): number {
+	return liveOwners.size;
+}
+
+/** Dispose every live owned process. For owner-scoped teardown and tests. */
+export async function disposeAllOwnedProcesses(): Promise<void> {
+	await Promise.all([...liveOwners].map((owner) => owner.dispose().catch(() => undefined)));
+}
+
+// ── F1(b) generic resource owners ─────────────────────────────────────────────
+
+type ResourceDisposer = () => void | Promise<void>;
+
+const resourceOwners = new Map<string, ResourceDisposer>();
+let resourcePostmortemRegistered = false;
+
+function ensureResourcePostmortem(): void {
+	if (resourcePostmortemRegistered) return;
+	resourcePostmortemRegistered = true;
+	process.once("beforeExit", () => {
+		void disposeAllOwners().catch(() => undefined);
+	});
+}
+
+/**
+ * Register a non-process resource for postmortem/fatal-exit cleanup.
+ *
+ * Idempotent by `name`: re-registering the same name replaces the prior
+ * disposer (last wins). Returns an unregister function that removes the owner
+ * only while it is still the active registration for that name.
+ */
+export function registerResourceOwner(name: string, disposer: ResourceDisposer): () => void {
+	resourceOwners.set(name, disposer);
+	ensureResourcePostmortem();
+	let unregistered = false;
+	return () => {
+		if (unregistered) return;
+		unregistered = true;
+		if (resourceOwners.get(name) === disposer) {
+			resourceOwners.delete(name);
+		}
+	};
+}
+
+/** Number of registered resource owners. Exposed for leak assertions/tests. */
+export function resourceOwnerCount(): number {
+	return resourceOwners.size;
+}
+
+/**
+ * Run and clear every registered resource disposer. Attempts all disposers even
+ * if some throw, then surfaces the failures as an `AggregateError` so callers
+ * can distinguish "all closed" from "a resource may still be alive".
+ */
+export async function disposeAllOwners(): Promise<void> {
+	const disposers = [...resourceOwners.values()];
+	resourceOwners.clear();
+	const errors: unknown[] = [];
+	for (const disposer of disposers) {
+		try {
+			await disposer();
+		} catch (err) {
+			errors.push(err);
+		}
+	}
+	if (errors.length > 0) {
+		throw new AggregateError(errors, `${errors.length} resource disposer(s) failed during teardown`);
+	}
+}
+
+/** Dispose a single named resource owner. Returns true if it was registered. */
+export async function disposeOwner(name: string): Promise<boolean> {
+	const disposer = resourceOwners.get(name);
+	if (!disposer) return false;
+	resourceOwners.delete(name);
+	await disposer();
+	return true;
+}

package/src/runtime/process-status.ts

@@ -0,0 +1,154 @@
+import type { TeamRunManifest } from "../state/types.ts";
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+
+export { hasAsyncStartMarker } from "./async-marker.ts";
+
+export interface ProcessLiveness {
+	pid?: number;
+	alive: boolean;
+	detail: string;
+}
+
+/**
+ * How long (ms) a foreground team run with status "running" but no active agents
+ * survives before being flagged as orphaned. Reduced from 10min to 2min to
+ * improve UX: stuck foreground runs (e.g. planner with 0 tool calls) no longer
+ * linger for 10min before the dashboard shows them as stale.
+ */
+const ORPHANED_ACTIVE_RUN_MS = 2 * 60 * 1000;
+/** How long a completed run stays visible in the widget after completion. */
+const COMPLETED_VISIBILITY_GRACE_MS = 8_000;
+/** Errors (failed/cancelled) linger far longer so a failed run leaves a visible
+ * trace in the crew widget for ~10 min (F-5). Successful completions vanish
+ * quickly to keep the widget quiet. */
+const ERROR_VISIBILITY_GRACE_MS = 10 * 60 * 1000;
+/** Maximum age (ms) for an active run before it's considered stale.
+ * After this time, PID-only liveness is unreliable due to PID recycling. */
+const STALE_ACTIVE_RUN_MS = 30 * 60 * 1000;
+
+export function checkProcessLiveness(pid: number | undefined): ProcessLiveness {
+	if (pid === undefined || !Number.isInteger(pid) || pid <= 0) {
+		return { pid, alive: false, detail: "no pid recorded" };
+	}
+	try {
+		process.kill(pid, 0);
+		return { pid, alive: true, detail: "process is alive" };
+	} catch (error) {
+		const nodeError = error as NodeJS.ErrnoException;
+		if (nodeError.code === "EPERM")
+			return {
+				pid,
+				alive: true,
+				detail: "process exists but permission is denied",
+			};
+		if (nodeError.code === "ESRCH") return { pid, alive: false, detail: "process does not exist" };
+		const message = error instanceof Error ? error.message : String(error);
+		return { pid, alive: false, detail: message };
+	}
+}
+
+export function isActiveRunStatus(status: string): boolean {
+	return status === "queued" || status === "planning" || status === "running" || status === "waiting";
+}
+
+export function isFinishedRunStatus(status: string): boolean {
+	return status === "completed" || status === "failed" || status === "cancelled" || status === "blocked";
+}
+
+/**
+ * Secondary threshold: runs that have been "running" for more than this without
+ * any active agents (all queued, no progress) are also considered orphaned.
+ * This catches foreground team runs where the planner got stuck with 0 tool calls.
+ */
+const ORPHANED_NO_PROGRESS_MS = 5 * 60 * 1000;
+
+export function isLikelyOrphanedActiveRun(
+	run: TeamRunManifest,
+	agents: CrewAgentRecord[] = [],
+	now = Date.now(),
+	staleMs = ORPHANED_ACTIVE_RUN_MS,
+): boolean {
+	if (!isActiveRunStatus(run.status)) return false;
+	if (run.async?.pid !== undefined) return false;
+	const updatedAt = new Date(run.updatedAt).getTime();
+	if (!Number.isFinite(updatedAt)) return false;
+
+	// Primary check: run hasn't been updated in a while
+	if (now - updatedAt >= staleMs) {
+		if (agents.length === 0) return run.summary === "Creating workflow prompts and placeholder results.";
+		return agents.every((agent) => agent.status === "queued" && !agent.completedAt && !agent.progress);
+	}
+
+	// Secondary check: run has been running without any progress for too long
+	if (now - updatedAt >= ORPHANED_NO_PROGRESS_MS) {
+		// If no agent is "running" or has made progress, the run is likely stuck
+		const hasActiveAgent = agents.some((agent) => agent.status === "running" || agent.progress || agent.toolUses);
+		if (!hasActiveAgent && agents.length > 0) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+function hasDurableActiveAgentEvidence(agent: CrewAgentRecord): boolean {
+	if (agent.status === "running") {
+		// Running agents are actively executing — trust them.
+		// Activity evidence is only required for queued agents (zombie prevention).
+		return true;
+	}
+	if (agent.status === "queued") {
+		// Queued agents need actual activity evidence to distinguish from zombies:
+		// spawned-but-never-executed agents should not appear as active.
+		return Boolean(
+			(agent.progress && (agent.progress.toolCount > 0 || agent.progress.recentOutput.length > 0)) ||
+				(agent.jsonEvents && agent.jsonEvents > 0) ||
+				(agent.toolUses && agent.toolUses > 0),
+		);
+	}
+	return false;
+}
+
+export function hasStaleAsyncProcess(run: TeamRunManifest, now = Date.now()): boolean {
+	if (!isActiveRunStatus(run.status) || !run.async) return false;
+	const pidAlive = checkProcessLiveness(run.async.pid).alive;
+	if (!pidAlive) return true;
+	// PID is alive, but check if the run is suspiciously old.
+	// PID recycling means a stale PID could point to an unrelated process.
+	const updatedAt = new Date(run.updatedAt).getTime();
+	const age = now - updatedAt;
+	if (Number.isFinite(updatedAt) && age > STALE_ACTIVE_RUN_MS) {
+		// Additional evidence: if no agent has recent activity, treat as stale.
+		// The real process would have updated the manifest within 30 minutes.
+		return true;
+	}
+	return false;
+}
+
+export function isDisplayActiveRun(run: TeamRunManifest, agents: CrewAgentRecord[] = [], now = Date.now()): boolean {
+	if (hasStaleAsyncProcess(run, now) || isLikelyOrphanedActiveRun(run, agents, now)) return false;
+	// Hard filter: if an active-status run hasn't been updated in > STALE_ACTIVE_RUN_MS
+	// and has no async PID tracking, it's a ghost from a crashed process.
+	if (isActiveRunStatus(run.status) && !run.async) {
+		const updatedAt = new Date(run.updatedAt).getTime();
+		if (Number.isFinite(updatedAt) && now - updatedAt > STALE_ACTIVE_RUN_MS) return false;
+	}
+	// Grace period: show completed runs for a few seconds so users see the result.
+	if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") {
+		const grace = run.status === "completed" ? COMPLETED_VISIBILITY_GRACE_MS : ERROR_VISIBILITY_GRACE_MS;
+		const lastAgentActivity = agents.reduce<number>((max, agent) => {
+			const ts = agent.completedAt ?? agent.startedAt;
+			const parsed = ts ? new Date(ts).getTime() : 0;
+			return Number.isFinite(parsed) && parsed > max ? parsed : max;
+		}, new Date(run.updatedAt).getTime());
+		if (Number.isFinite(lastAgentActivity) && now - lastAgentActivity < grace) return true;
+		return false;
+	}
+	if (!isActiveRunStatus(run.status)) return false;
+	// Keep the always-visible widget quiet until a worker actually exists.
+	// Empty active manifests can be created briefly at startup, by old fixture/scaffold
+	// runs, or from cross-cwd registry history; showing them causes noisy 0/0 rows and
+	// needless spinner redraws. The full dashboard can still list historical runs.
+	if (agents.length === 0) return false;
+	return agents.some(hasDurableActiveAgentEvidence);
+}

package/src/runtime/progress-event-coalescer.ts

@@ -0,0 +1,44 @@
+export interface ProgressEventSummary {
+	eventType: string;
+	currentTool?: string;
+	toolCount?: number;
+	tokens?: number;
+	turns?: number;
+	activityState?: string;
+	lastActivityAt?: string;
+}
+
+export interface ProgressEventCoalesceDecision {
+	shouldAppend: boolean;
+	reason: string;
+}
+
+export interface ProgressEventCoalesceInput {
+	previous?: ProgressEventSummary;
+	next: ProgressEventSummary;
+	nowMs: number;
+	lastAppendMs?: number;
+	minIntervalMs: number;
+	force?: boolean;
+	tokenThreshold?: number;
+}
+
+const DEFAULT_TOKEN_THRESHOLD = 256;
+
+function numericIncrease(previous: number | undefined, next: number | undefined): number {
+	return next !== undefined && previous !== undefined ? next - previous : next !== undefined ? next : 0;
+}
+
+export function shouldAppendProgressEventUpdate(input: ProgressEventCoalesceInput): ProgressEventCoalesceDecision {
+	if (input.force) return { shouldAppend: true, reason: "force" };
+	if (!input.previous) return { shouldAppend: true, reason: "first" };
+	if (input.previous.activityState !== input.next.activityState) return { shouldAppend: true, reason: "activity_changed" };
+	if (input.previous.currentTool !== input.next.currentTool) return { shouldAppend: true, reason: "tool_changed" };
+	if (numericIncrease(input.previous.toolCount, input.next.toolCount) > 0) return { shouldAppend: true, reason: "tool_count_increased" };
+	if (numericIncrease(input.previous.turns, input.next.turns) > 0) return { shouldAppend: true, reason: "turns_increased" };
+	const tokenIncrease = numericIncrease(input.previous.tokens, input.next.tokens);
+	if (tokenIncrease >= (input.tokenThreshold ?? DEFAULT_TOKEN_THRESHOLD)) return { shouldAppend: true, reason: "tokens_increased" };
+	if (input.lastAppendMs === undefined || input.nowMs - input.lastAppendMs >= input.minIntervalMs)
+		return { shouldAppend: true, reason: "interval" };
+	return { shouldAppend: false, reason: "coalesced" };
+}