@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/interactive/slash-spec.ts

@@ -0,0 +1,453 @@
+import type { SlashCommand } from "./slash-commands.js";
+
+export interface CommandFlagSpec {
+	/** Primary flag, e.g. "--target". */
+	name: string;
+	/** Accepted synonyms, e.g. ["--worker-profile", "--worker"]. */
+	aliases?: ReadonlyArray<string>;
+	/** True when the flag consumes the next token as its value. */
+	takesValue?: boolean;
+	/** True when every occurrence should be retained instead of last-one-wins. */
+	repeatable?: boolean;
+	/** Closed set of legal values; parse failure produces the usage result. */
+	values?: ReadonlyArray<string>;
+	/** Usage placeholder, e.g. "profile" renders as `[--worker <profile>]`. */
+	valueName?: string;
+}
+
+export interface CommandPositionalSpec {
+	name: string; // e.g. "agent", "task"
+	required: boolean;
+	/** Greedy tail: consumes the rest of the line verbatim (task text, compact instructions). */
+	rest?: boolean;
+}
+
+export interface CommandArgsSpec {
+	flags?: ReadonlyArray<CommandFlagSpec>;
+	positionals?: ReadonlyArray<CommandPositionalSpec>;
+	/** Subcommands with their own args, e.g. share export/import. */
+	subcommands?: Record<string, CommandArgsSpec>;
+	/**
+	 * For commands shaped like `<name> <rest...>`, continue recognizing
+	 * declared flags after earlier positionals until the first non-declared-flag
+	 * token starts the rest text. Off by default so established rest commands
+	 * keep their byte-for-byte parsing.
+	 */
+	parseFlagsBeforeRest?: boolean;
+}
+
+export interface ParsedArgs {
+	flags: Map<string, string | true>;
+	flagValues: Map<string, string[]>;
+	positionals: string[];
+	rest?: string;
+	subcommand?: string;
+	error?: string; // human-readable cause used in the usage notice
+}
+
+function getFlagValuePlaceholder(flag: CommandFlagSpec): string {
+	if (flag.valueName) return flag.valueName;
+	if (flag.values && flag.values.length > 0) {
+		return flag.values.join("|");
+	}
+	return flag.name.replace(/^--/, "");
+}
+
+export function renderArgsSpec(spec: CommandArgsSpec): string {
+	const parts: string[] = [];
+
+	if (spec.flags) {
+		for (const flag of spec.flags) {
+			if (flag.takesValue) {
+				const placeholder = getFlagValuePlaceholder(flag);
+				parts.push(`[${flag.name} <${placeholder}>]`);
+			} else {
+				parts.push(`[${flag.name}]`);
+			}
+		}
+	}
+
+	if (spec.positionals) {
+		for (const pos of spec.positionals) {
+			if (pos.required) {
+				parts.push(`<${pos.name}>`);
+			} else {
+				parts.push(`[${pos.name}]`);
+			}
+		}
+	}
+
+	return parts.join(" ");
+}
+
+export function usageLine(entry: { name: string; args?: CommandArgsSpec }, subcommand?: string): string {
+	const prefix = `/${entry.name}`;
+	const argsSpec = entry.args ?? {};
+
+	if (subcommand && argsSpec.subcommands?.[subcommand]) {
+		const subSpec = argsSpec.subcommands[subcommand];
+		const subStr = renderArgsSpec(subSpec);
+		return `\nusage: ${prefix} ${subcommand}${subStr ? ` ${subStr}` : ""}\n`;
+	}
+
+	if (argsSpec.subcommands) {
+		const subParts: string[] = [];
+		const rootSpec: CommandArgsSpec = {
+			...(argsSpec.flags ? { flags: argsSpec.flags } : {}),
+			...(argsSpec.positionals ? { positionals: argsSpec.positionals } : {}),
+		};
+		const rootStr = renderArgsSpec(rootSpec);
+		if (rootStr.length > 0) subParts.push(`${prefix} ${rootStr}`);
+		for (const [subName, subSpec] of Object.entries(argsSpec.subcommands)) {
+			const subStr = renderArgsSpec(subSpec);
+			subParts.push(`${prefix} ${subName}${subStr ? ` ${subStr}` : ""}`);
+		}
+		return `\nusage: ${subParts.join(" | ")}\n`;
+	}
+
+	const argsStr = renderArgsSpec(argsSpec);
+	return `\nusage: ${prefix}${argsStr ? ` ${argsStr}` : ""}\n`;
+}
+
+export function parseArgs(spec: CommandArgsSpec, argsLine: string): ParsedArgs {
+	const flags = new Map<string, string | true>();
+	const flagValues = new Map<string, string[]>();
+	const positionals: string[] = [];
+	let subcommand: string | undefined;
+	let rest: string | undefined;
+
+	let currentSpec = spec;
+	let index = 0;
+
+	const skipWhitespace = () => {
+		while (index < argsLine.length) {
+			const char = argsLine[index];
+			if (char && /\s/.test(char)) {
+				index++;
+			} else {
+				break;
+			}
+		}
+	};
+
+	skipWhitespace();
+
+	if (currentSpec.subcommands && index < argsLine.length) {
+		const start = index;
+		while (index < argsLine.length) {
+			const char = argsLine[index];
+			if (char && !/\s/.test(char)) {
+				index++;
+			} else {
+				break;
+			}
+		}
+		const sub = argsLine.slice(start, index);
+		if (currentSpec.subcommands[sub]) {
+			subcommand = sub;
+			currentSpec = currentSpec.subcommands[sub];
+			skipWhitespace();
+		} else {
+			index = start;
+		}
+	}
+
+	const flagSpecs = currentSpec.flags ?? [];
+	const positionalSpecs = currentSpec.positionals ?? [];
+	let positionalIndex = 0;
+
+	const readToken = (): { token: string } | null => {
+		const tokenStart = index;
+		while (index < argsLine.length) {
+			const char = argsLine[index];
+			if (char && !/\s/.test(char)) {
+				index++;
+			} else {
+				break;
+			}
+		}
+		const token = argsLine.slice(tokenStart, index);
+		if (token.length === 0) return null;
+		return { token };
+	};
+
+	const consumeFlag = (matchedFlagSpec: CommandFlagSpec, token: string): string | null => {
+		const flagName = matchedFlagSpec.name;
+		if (matchedFlagSpec.takesValue) {
+			skipWhitespace();
+			if (index >= argsLine.length) return `Flag ${token} requires a value`;
+			const value = readToken();
+			if (value === null) return `Flag ${token} requires a value`;
+			const val = value.token;
+
+			if (matchedFlagSpec.values && !matchedFlagSpec.values.includes(val)) {
+				return `Invalid value for ${flagName}: ${val}`;
+			}
+
+			if (matchedFlagSpec.repeatable) {
+				const next = [...(flagValues.get(flagName) ?? []), val];
+				flagValues.set(flagName, next);
+				flags.set(flagName, next.join(" "));
+			} else {
+				flagValues.set(flagName, [val]);
+				flags.set(flagName, val);
+			}
+			return null;
+		}
+		flags.set(flagName, true);
+		return null;
+	};
+
+	const errorResult = (error: string): ParsedArgs => ({
+		flags,
+		flagValues,
+		positionals,
+		...(subcommand !== undefined ? { subcommand } : {}),
+		error,
+	});
+
+	while (index < argsLine.length) {
+		const currentPositionalSpec = positionalSpecs[positionalIndex];
+		if (currentPositionalSpec?.rest) {
+			if (currentSpec.parseFlagsBeforeRest) {
+				while (index < argsLine.length) {
+					const tokenStart = index;
+					const read = readToken();
+					if (read === null) break;
+					const matchedFlagSpec = flagSpecs.find((f) => f.name === read.token || f.aliases?.includes(read.token));
+					if (!matchedFlagSpec) {
+						index = tokenStart;
+						break;
+					}
+					const error = consumeFlag(matchedFlagSpec, read.token);
+					if (error) return errorResult(error);
+					skipWhitespace();
+				}
+			}
+			const restVal = argsLine.slice(index).trim();
+			if (restVal.length > 0) {
+				positionals.push(restVal);
+				rest = restVal;
+			}
+			positionalIndex++;
+			index = argsLine.length;
+			break;
+		}
+
+		const read = readToken();
+		if (read === null) break;
+		const token = read.token;
+
+		let isFlag = false;
+		let matchedFlagSpec: CommandFlagSpec | undefined;
+
+		if (token.startsWith("--")) {
+			matchedFlagSpec = flagSpecs.find((f) => f.name === token || f.aliases?.includes(token));
+			if (matchedFlagSpec) {
+				isFlag = true;
+			} else {
+				return errorResult(`Unknown flag: ${token}`);
+			}
+		}
+
+		if (isFlag && matchedFlagSpec) {
+			const error = consumeFlag(matchedFlagSpec, token);
+			if (error) return errorResult(error);
+		} else {
+			if (positionalIndex < positionalSpecs.length) {
+				positionals.push(token);
+				positionalIndex++;
+			} else {
+				return errorResult(`Unexpected argument: ${token}`);
+			}
+		}
+
+		skipWhitespace();
+	}
+
+	for (let idx = positionalIndex; idx < positionalSpecs.length; idx++) {
+		const spec = positionalSpecs[idx];
+		if (spec?.required) {
+			return {
+				flags,
+				flagValues,
+				positionals,
+				...(subcommand !== undefined ? { subcommand } : {}),
+				error: `Missing required argument: ${spec.name}`,
+			};
+		}
+	}
+
+	return {
+		flags,
+		flagValues,
+		positionals,
+		...(subcommand !== undefined ? { subcommand } : {}),
+		...(rest !== undefined ? { rest } : {}),
+	};
+}
+
+export interface ArgCompletion {
+	/** Replacement for the trailing (possibly empty) token under the cursor. */
+	token: string;
+	/** Grammar hint rendered beside the suggestion, e.g. a flag's value placeholder. */
+	hint?: string;
+}
+
+export interface ArgCompletionResult {
+	completions: ArgCompletion[];
+	/** Index in the argument text where the token under the cursor begins. */
+	tokenStart: number;
+}
+
+/**
+ * State reached after replaying the completed tokens of an argument line
+ * against a spec, mirroring parseArgs: which non-repeatable flags are spent,
+ * whether the cursor sits in a flag's value slot, how many positionals are
+ * filled, and whether free rest text has begun (after which nothing completes).
+ */
+interface CompletionWalk {
+	usedFlags: Set<string>;
+	awaitingValue: CommandFlagSpec | null;
+	positionalIndex: number;
+	restBegun: boolean;
+}
+
+function walkCompletedTokens(spec: CommandArgsSpec, tokens: ReadonlyArray<string>): CompletionWalk {
+	const flagSpecs = spec.flags ?? [];
+	const positionalSpecs = spec.positionals ?? [];
+	const walk: CompletionWalk = { usedFlags: new Set(), awaitingValue: null, positionalIndex: 0, restBegun: false };
+	for (const token of tokens) {
+		if (walk.awaitingValue) {
+			walk.awaitingValue = null;
+			continue;
+		}
+		const atRest = positionalSpecs[walk.positionalIndex]?.rest === true;
+		const flagsParseable = !atRest || spec.parseFlagsBeforeRest === true;
+		const matched =
+			flagsParseable && token.startsWith("--")
+				? flagSpecs.find((flag) => flag.name === token || flag.aliases?.includes(token))
+				: undefined;
+		if (matched) {
+			walk.usedFlags.add(matched.name);
+			if (matched.takesValue) walk.awaitingValue = matched;
+			continue;
+		}
+		if (atRest) {
+			walk.restBegun = true;
+			break;
+		}
+		walk.positionalIndex += 1;
+	}
+	return walk;
+}
+
+function flagCompletions(spec: CommandArgsSpec, walk: CompletionWalk, current: string): ArgCompletion[] {
+	const available = (spec.flags ?? []).filter((flag) => flag.repeatable === true || !walk.usedFlags.has(flag.name));
+	let rows = available.filter((flag) => flag.name.startsWith(current)).map((flag) => ({ flag, name: flag.name }));
+	// When the typed token matches no primary name, fall back to aliases so a
+	// legal spelling like --rewrite still completes instead of going silent.
+	if (rows.length === 0) {
+		rows = available.flatMap((flag) =>
+			(flag.aliases ?? []).filter((alias) => alias.startsWith(current)).map((alias) => ({ flag, name: alias })),
+		);
+	}
+	return rows.map(({ flag, name }) => ({
+		token: name,
+		...(flag.takesValue ? { hint: `<${getFlagValuePlaceholder(flag)}>` } : {}),
+	}));
+}
+
+/**
+ * Complete the trailing token of a slash command's argument text against its
+ * args spec: subcommand names in first position, declared flags wherever the
+ * grammar still parses flags, and closed value sets in a flag's value slot.
+ * Free text (positionals, open flag values, rest) never completes; returning
+ * null closes the suggestion list. The walk mirrors parseArgs so a completion
+ * is always a token the parser would accept.
+ */
+export function completeArgs(spec: CommandArgsSpec, argumentText: string): ArgCompletionResult | null {
+	const trailing = argumentText.match(/\S*$/)?.[0] ?? "";
+	const tokenStart = argumentText.length - trailing.length;
+	const current = trailing;
+	const completed = argumentText
+		.slice(0, tokenStart)
+		.split(/\s+/)
+		.filter((token) => token.length > 0);
+
+	const completions: ArgCompletion[] = [];
+	let active = spec;
+	let walkTokens = completed;
+
+	if (spec.subcommands) {
+		const first = completed[0];
+		if (first === undefined) {
+			for (const [name, subSpec] of Object.entries(spec.subcommands)) {
+				if (!name.startsWith(current)) continue;
+				const hint = renderArgsSpec(subSpec);
+				completions.push({ token: name, ...(hint.length > 0 ? { hint } : {}) });
+			}
+		} else if (spec.subcommands[first]) {
+			active = spec.subcommands[first];
+			walkTokens = completed.slice(1);
+		}
+	}
+
+	const walk = walkCompletedTokens(active, walkTokens);
+
+	if (walk.restBegun) {
+		return completions.length > 0 ? { completions, tokenStart } : null;
+	}
+
+	if (walk.awaitingValue) {
+		for (const value of walk.awaitingValue.values ?? []) {
+			if (value.startsWith(current)) completions.push({ token: value });
+		}
+		return completions.length > 0 ? { completions, tokenStart } : null;
+	}
+
+	const atRest = (active.positionals ?? [])[walk.positionalIndex]?.rest === true;
+	const flagsParseable = !atRest || active.parseFlagsBeforeRest === true;
+	if (flagsParseable && (current.length === 0 || current.startsWith("-"))) {
+		completions.push(...flagCompletions(active, walk, current));
+	}
+
+	return completions.length > 0 ? { completions, tokenStart } : null;
+}
+
+export function matchFromSpec(
+	entry: {
+		name: string;
+		aliases?: ReadonlyArray<string>;
+		aliasArgs?: Readonly<Record<string, string>>;
+		args?: CommandArgsSpec;
+		fromArgs?: (parsed: ParsedArgs, trimmed: string) => SlashCommand;
+	},
+	trimmed: string,
+): SlashCommand | null {
+	const nameOrAlias = [entry.name, ...(entry.aliases ?? [])];
+	let matchedPrefix: string | null = null;
+	let matchedTerm: string | null = null;
+	for (const term of nameOrAlias) {
+		const prefix = `/${term}`;
+		if (trimmed === prefix || trimmed.startsWith(`${prefix} `)) {
+			matchedPrefix = prefix;
+			matchedTerm = term;
+			break;
+		}
+	}
+	if (!matchedPrefix) return null;
+
+	// An alias that stands for a subcommand supplies that subcommand ahead of
+	// whatever was typed after it, so `/compact tidy up` parses as the line
+	// `/context compact tidy up` and reaches the same handler by the same route.
+	const implied = matchedTerm === null ? undefined : entry.aliasArgs?.[matchedTerm];
+	const argsLine = implied ? ` ${implied}${trimmed.slice(matchedPrefix.length)}` : trimmed.slice(matchedPrefix.length);
+	const parsed = parseArgs(entry.args ?? {}, argsLine);
+
+	if (entry.fromArgs) {
+		return entry.fromArgs(parsed, trimmed);
+	}
+
+	return null;
+}

package/src/interactive/status/controller.ts

@@ -0,0 +1,256 @@
+import { BusChannels, isRunAbortedPayload } from "../../core/bus-events.js";
+import type { ClioSettings } from "../../core/config.js";
+import type { SafeEventBus } from "../../core/event-bus.js";
+import type { ProvidersContract } from "../../domains/providers/index.js";
+import type { ChatLoop, ChatLoopEvent } from "../chat-loop.js";
+import { reduceStatus, type StatusInputEvent } from "./state-machine.js";
+import { type AgentStatus, type AgentStatusChangedPayload, INITIAL_STATUS } from "./types.js";
+import { TIER_THRESHOLDS_MS } from "./watchdog.js";
+
+export interface StatusControllerDeps {
+	chat: ChatLoop;
+	providers: ProvidersContract;
+	bus?: SafeEventBus;
+	getSettings?: () => Readonly<ClioSettings>;
+	now?: () => number;
+	setInterval?: (listener: () => void, ms: number) => unknown;
+	clearInterval?: (handle: unknown) => void;
+	setTimeout?: (listener: () => void, ms: number) => unknown;
+	clearTimeout?: (handle: unknown) => void;
+}
+
+export interface StatusController {
+	current(): AgentStatus;
+	subscribe(listener: (status: AgentStatus) => void): () => void;
+	/**
+	 * Drop the status the previous session ended on. An ended turn only settles
+	 * back to idle five seconds later, so a session started inside that window
+	 * would otherwise open reporting work it never did.
+	 */
+	reset(): void;
+	dispose(): void;
+}
+
+const TICK_INTERVAL_MS = 1000;
+const SETTLE_MS = 5000;
+const STATUS_EMIT_THROTTLE_MS = 100;
+/**
+ * A streaming worker publishes thousands of progress events per dispatch, and
+ * the watchdog only needs a signal coarser than its ten-second first tier, so
+ * one refresh per tick is enough. Coalescing keeps the reducer (and the
+ * provider lookup behind every apply) off the worker's stream rate.
+ */
+const DISPATCH_PROGRESS_COALESCE_MS = TICK_INTERVAL_MS;
+
+/**
+ * Worker/ACP stream evidence, as opposed to the heartbeats that ride the same
+ * channel: a worker keepalive, or the watchdog's own observation that one went
+ * stale, says nothing about whether the worker produced anything. The event
+ * crosses a process boundary untyped, so read it defensively.
+ */
+const HEARTBEAT_EVENT_TYPES = new Set(["heartbeat", "heartbeat_status"]);
+
+function isWorkerStreamEvidence(raw: unknown): boolean {
+	const event = (raw as { event?: unknown } | null | undefined)?.event;
+	if (typeof event !== "object" || event === null) return false;
+	const type = (event as { type?: unknown }).type;
+	return typeof type === "string" && type.length > 0 && !HEARTBEAT_EVENT_TYPES.has(type);
+}
+
+function statusMetadata(status: AgentStatus): AgentStatusChangedPayload["metadata"] {
+	if (status.tool) return { toolName: status.tool.toolName };
+	if (status.retry) return { attempt: status.retry.attempt };
+	if (status.dispatch) return { agentName: status.dispatch.agentName };
+	if (status.phase === "ended" && status.summary) return { reason: status.summary.stopReason };
+	return undefined;
+}
+
+export function createStatusController(deps: StatusControllerDeps): StatusController {
+	const now = deps.now ?? Date.now;
+	const setIntervalFn = deps.setInterval ?? ((listener, ms) => setInterval(listener, ms));
+	const clearIntervalFn =
+		deps.clearInterval ??
+		((handle) => {
+			clearInterval(handle as ReturnType<typeof setInterval>);
+		});
+	const setTimeoutFn = deps.setTimeout ?? ((listener, ms) => setTimeout(listener, ms));
+	const clearTimeoutFn =
+		deps.clearTimeout ??
+		((handle) => {
+			clearTimeout(handle as ReturnType<typeof setTimeout>);
+		});
+
+	let status: AgentStatus = { ...INITIAL_STATUS };
+	let disposed = false;
+	let lastNotifyAt = 0;
+	let lastDispatchProgressAt = Number.NEGATIVE_INFINITY;
+	let settleTimer: unknown = null;
+	let abortCeilingTimer: unknown = null;
+	const listeners = new Set<(status: AgentStatus) => void>();
+	const unsubscribes: Array<() => void> = [];
+
+	const currentTarget = (): { targetId: string; modelId: string } => {
+		const settings = deps.getSettings?.();
+		return {
+			targetId: settings?.orchestrator?.target ?? "",
+			modelId: settings?.orchestrator?.model ?? "",
+		};
+	};
+
+	const isLocalRuntime = (): boolean => {
+		const targetId = currentTarget().targetId;
+		if (!targetId) return false;
+		const entry = deps.providers.list().find((candidate) => candidate.target.id === targetId);
+		return entry?.runtime?.tier === "local-native";
+	};
+
+	const clearSettle = (): void => {
+		if (settleTimer === null) return;
+		clearTimeoutFn(settleTimer);
+		settleTimer = null;
+	};
+
+	const clearAbortCeiling = (): void => {
+		if (abortCeilingTimer === null) return;
+		clearTimeoutFn(abortCeilingTimer);
+		abortCeilingTimer = null;
+	};
+
+	const emitPhaseTransition = (prev: AgentStatus, next: AgentStatus, at: number): void => {
+		if (prev.phase === next.phase) return;
+		const payload: AgentStatusChangedPayload = {
+			runId: next.runId ?? deps.chat.getSessionId() ?? null,
+			phase: next.phase,
+			prevPhase: prev.phase,
+			at,
+			elapsedFromStart: next.since > 0 ? Math.max(0, at - next.since) : 0,
+			watchdogTier: next.watchdogTier,
+			metadata: statusMetadata(next),
+		};
+		deps.bus?.emit(BusChannels.AgentStatusChanged, payload);
+	};
+
+	const notify = (prev: AgentStatus, next: AgentStatus, force = false): void => {
+		const at = now();
+		emitPhaseTransition(prev, next, at);
+		const phaseChanged = prev.phase !== next.phase;
+		if (!force && !phaseChanged && at - lastNotifyAt < STATUS_EMIT_THROTTLE_MS) return;
+		lastNotifyAt = at;
+		for (const listener of listeners) listener(next);
+	};
+
+	const scheduleSettle = (): void => {
+		clearSettle();
+		settleTimer = setTimeoutFn(() => {
+			if (disposed || status.phase !== "ended") return;
+			const prev = status;
+			status = { ...INITIAL_STATUS, localRuntime: isLocalRuntime() };
+			notify(prev, status, true);
+		}, SETTLE_MS);
+	};
+
+	const scheduleAbortCeiling = (): void => {
+		clearAbortCeiling();
+		abortCeilingTimer = setTimeoutFn(() => {
+			if (disposed || status.phase === "idle" || status.phase === "ended") return;
+			apply({ type: "force_cancelled", reason: "watchdog-forced" }, true);
+		}, TIER_THRESHOLDS_MS.postAbortCeiling);
+	};
+
+	const apply = (event: StatusInputEvent, force = false): void => {
+		const at = now();
+		const target = currentTarget();
+		const prev = status;
+		const next = reduceStatus(prev, event, {
+			now: at,
+			localRuntime: isLocalRuntime(),
+			modelId: target.modelId,
+			targetId: target.targetId,
+			runId: deps.chat.getSessionId(),
+		});
+		if (next === prev) return;
+		status = next;
+		if (event.type === "agent_start") clearSettle();
+		if (status.phase === "ended") {
+			clearAbortCeiling();
+			scheduleSettle();
+		}
+		notify(prev, status, force);
+	};
+
+	unsubscribes.push(
+		deps.chat.onEvent((event: ChatLoopEvent) => {
+			if (event.type === "agent_status") return;
+			apply(event);
+		}),
+	);
+
+	if (deps.bus) {
+		unsubscribes.push(
+			deps.bus.on(BusChannels.PermissionRequested, () => apply({ type: "overlay_push", overlay: "tool_blocked" }, true)),
+			deps.bus.on(BusChannels.PermissionResolved, () => apply({ type: "overlay_pop", overlay: "tool_blocked" }, true)),
+			deps.bus.on(BusChannels.CompactionBegin, () => apply({ type: "overlay_push", overlay: "compacting" }, true)),
+			deps.bus.on(BusChannels.CompactionEnd, () => apply({ type: "overlay_pop", overlay: "compacting" }, true)),
+			deps.bus.on(BusChannels.DispatchStarted, (payload) =>
+				apply({ type: "overlay_push", overlay: "dispatching", data: payload }, true),
+			),
+			deps.bus.on(BusChannels.DispatchProgress, (payload) => {
+				if (!isWorkerStreamEvidence(payload)) return;
+				const at = now();
+				if (at - lastDispatchProgressAt < DISPATCH_PROGRESS_COALESCE_MS) return;
+				lastDispatchProgressAt = at;
+				apply({ type: "dispatch_progress" });
+			}),
+			deps.bus.on(BusChannels.DispatchCompleted, () => apply({ type: "overlay_pop", overlay: "dispatching" }, true)),
+			deps.bus.on(BusChannels.DispatchFailed, () => apply({ type: "overlay_pop", overlay: "dispatching" }, true)),
+			deps.bus.on(BusChannels.RunAborted, (payload) => {
+				scheduleAbortCeiling();
+				// Carry abort provenance into the summary; a dispatch drain and a
+				// user stream-cancel must not collapse into one hardcoded path.
+				// A malformed payload still ends the run, just without detail.
+				if (isRunAbortedPayload(payload)) {
+					apply(
+						{
+							type: "run_aborted",
+							source: payload.source,
+							...(payload.reason !== undefined ? { reason: payload.reason } : {}),
+						},
+						true,
+					);
+					return;
+				}
+				apply({ type: "run_aborted" }, true);
+			}),
+		);
+	}
+
+	const interval = setIntervalFn(() => apply({ type: "watchdog_tick" }), TICK_INTERVAL_MS);
+
+	return {
+		current: () => status,
+		subscribe(listener) {
+			listeners.add(listener);
+			listener(status);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		reset() {
+			if (disposed) return;
+			clearSettle();
+			clearAbortCeiling();
+			const prev = status;
+			status = { ...INITIAL_STATUS, localRuntime: isLocalRuntime() };
+			notify(prev, status, true);
+		},
+		dispose() {
+			disposed = true;
+			clearSettle();
+			clearAbortCeiling();
+			clearIntervalFn(interval);
+			for (const unsubscribe of unsubscribes) unsubscribe();
+			unsubscribes.length = 0;
+			listeners.clear();
+		},
+	};
+}