@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/interactive/interactive-slash-runtime.ts

@@ -0,0 +1,554 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { ClioSettings } from "../core/config.js";
+import type { SafeEventBus } from "../core/event-bus.js";
+import type { PendingSkillRequest } from "../core/skill-activation.js";
+import { clioConfigDir } from "../core/xdg.js";
+import type { AgentsContract } from "../domains/agents/contract.js";
+import type { DispatchContract } from "../domains/dispatch/contract.js";
+import { agentRoleFactsResolver } from "../domains/dispatch/execution-role.js";
+import type { ExtensionsContract } from "../domains/extensions/index.js";
+import {
+	type ProvidersContract,
+	type ResolvedThinkingCapability,
+	resolveModelRuntimeCapabilitiesForProviders,
+	type ThinkingLevel,
+	thinkingLevelChoiceLabel,
+} from "../domains/providers/index.js";
+import type { ResourcesContract } from "../domains/resources/index.js";
+import { installSkill } from "../domains/resources/skills/marketplace.js";
+import type { SessionContract, SessionEntry } from "../domains/session/index.js";
+import type { ShareContract } from "../domains/share/index.js";
+import type { UserTasksStore } from "../domains/user-tasks/store.js";
+import { stripTerminalSequences } from "../engine/tui.js";
+import type { ImageContent } from "../engine/types.js";
+import type { AskUserHandler } from "../tools/ask-user.js";
+import type { ChatLoop } from "./chat-loop.js";
+import { type ChatPanel, createChatPanel } from "./chat-panel.js";
+import { rehydrateChatPanelFromTurns } from "./chat-renderer.js";
+import { runCompactWithNotice } from "./command-fallbacks.js";
+import { appendNotice, appendOperatorCommand } from "./command-output.js";
+import { renderSessionHtml } from "./export-html/index.js";
+import { dateLocal } from "./format-time.js";
+import type { SettingsCenterRowId, SettingsSectionId } from "./overlays/settings.js";
+import {
+	type ContextClearCommandOptions,
+	dispatchSlashCommand,
+	type InitCommandOptions,
+	parseSlashCommand,
+	type RunIo,
+	type SlashCommandContext,
+	type SlashCommandDispatchResult,
+	type TaskMemorySeedCommandResult,
+} from "./slash-commands.js";
+import { verifyReceiptFile } from "./view/artifacts.js";
+import type { WorkerEntryState } from "./worker-stream.js";
+
+const EXPORT_RENDER_WIDTH = 100;
+
+export interface InteractiveSlashSubmitExpansion {
+	text: string;
+	images: ImageContent[];
+	workingContextPaths: string[];
+	pendingSkillRequests: PendingSkillRequest[];
+}
+
+type SlashChat = Pick<ChatLoop, "getSessionId" | "isStreaming" | "submit">;
+type SlashChatPanel = Pick<ChatPanel, "appendReplayBlock" | "appendUser">;
+type SlashResources = Pick<ResourcesContract, "prompts" | "expandPromptTemplate" | "reload">;
+type SlashExtensions = Pick<ExtensionsContract, "list">;
+type SlashAgents = Pick<AgentsContract, "getSpec" | "listSpecs">;
+type SlashShare = Pick<ShareContract, "writeArchive" | "planImport" | "importArchive">;
+
+export interface InteractiveSlashRuntimeDeps {
+	io: RunIo;
+	bus: SafeEventBus;
+	dispatch: DispatchContract;
+	providers: ProvidersContract;
+	chat: SlashChat;
+	chatPanel: SlashChatPanel;
+	resources?: SlashResources;
+	extensions?: SlashExtensions;
+	interop?: SlashCommandContext["interop"];
+	agents?: SlashAgents;
+	share?: SlashShare;
+	userTasks?: UserTasksStore;
+	getSettings?: () => Readonly<ClioSettings>;
+	writeSettings?: (next: ClioSettings) => void;
+	/**
+	 * Scoped commit of one settings leaf, the same path /settings edits take.
+	 * Slash commands use scope "session": they change the running session, and
+	 * making a value permanent stays the Settings overlay's explicit choice.
+	 */
+	commitSetting?: (id: string, next: ClioSettings, scope: "session" | "global") => void;
+	onSelectModel?: (ref: { target: string; model: string }) => void;
+	onSetThinkingLevel?: (level: ThinkingLevel) => void;
+	onCompact?: (instructions: string | undefined) => Promise<void>;
+	onInit?: (options: InitCommandOptions, io?: RunIo) => Promise<void>;
+	onContextClear?: (options: ContextClearCommandOptions) => Promise<void>;
+	onContextRefresh?: () => Promise<void>;
+	stateDir: string;
+	shutdown: () => void | Promise<void>;
+	requestRender: () => void;
+	beforeSemanticSubmit?: () => void;
+	settleVisibleFrame?: (reason: string) => Promise<void>;
+	refreshFooter: () => void;
+	dismissContextBootstrapNotices: () => void;
+	recordSubmittedTurn: () => void;
+	readStructuredEntries: (sessionId: string) => ReadonlyArray<SessionEntry>;
+	/**
+	 * Leaf lookup for `/export`, so the export follows the branch the session
+	 * is actually on. current.jsonl still holds the abandoned turns after a
+	 * `/tree` pin, and an unscoped rehydrate reproduced them (issue #109).
+	 */
+	session?: Pick<SessionContract, "tree">;
+	expandSubmit: (text: string) => Promise<InteractiveSlashSubmitExpansion>;
+	openAskUser: AskUserHandler;
+	openSkillsHub: () => void;
+	openCost: () => void;
+	openContextView: () => void;
+	openTasks: () => void;
+	openDecisions: () => void;
+	openMemory: () => void;
+	seedTaskMemory?: () => TaskMemorySeedCommandResult;
+	openView: (filter?: string) => void;
+	openModel: () => void;
+	openSettings: (section?: SettingsSectionId, rowId?: SettingsCenterRowId) => void;
+	openResume: () => void;
+	startNewSession: () => void;
+	openTree: () => void;
+	openMessagePicker: () => void;
+	openHelp: (query?: string) => void;
+	openAgents: () => void;
+	openPrompts: () => void;
+	openExtensions: () => void;
+	openInterop?: () => void;
+	openContextReset: () => void;
+	setEditorText: (text: string) => void;
+	/** Worker blocks this session folded, oldest first; `/share` picks a finished one. */
+	listWorkerRuns?: () => ReadonlyArray<WorkerEntryState>;
+	getCwd?: () => string;
+	getConfigDir?: () => string;
+	installSkill?: typeof installSkill;
+	now?: () => Date;
+}
+
+export interface InteractiveSlashRuntime {
+	context: SlashCommandContext;
+	notice: SlashCommandContext["notice"];
+	dispatchCommand(text: string): SlashCommandDispatchResult;
+	/** Admit captured Stage 0 input without waiting for the model turn to finish. */
+	admitCommand(text: string, signal?: AbortSignal): Promise<void>;
+}
+
+/** Owns slash-command context construction and its asynchronous command state. */
+const OUTPUT_VERBOSITIES: ReadonlyArray<ClioSettings["terminal"]["outputVerbosity"]> = [
+	"minimal",
+	"default",
+	"verbose",
+];
+
+/** Thinking capability of the active orchestrator target and model, or null when unresolved. */
+export function resolveThinkingCapability(
+	providers: ProvidersContract,
+	settings: Readonly<ClioSettings>,
+): ResolvedThinkingCapability | null {
+	const resolved = resolveModelRuntimeCapabilitiesForProviders(
+		providers,
+		settings.orchestrator.target,
+		settings.orchestrator.model,
+		settings.orchestrator.thinkingLevel ?? "off",
+	);
+	return resolved?.thinking ?? null;
+}
+
+/**
+ * Thinking levels permitted for the active orchestrator target. This is the
+ * same resolved surface used by the runtime payload builders and dashboard.
+ * Unknown or unconfigured targets return `["off"]`.
+ */
+export function resolveAvailableThinkingLevels(
+	providers: ProvidersContract,
+	settings: Readonly<ClioSettings>,
+): ReadonlyArray<ThinkingLevel> {
+	return resolveThinkingCapability(providers, settings)?.supportedLevels ?? ["off"];
+}
+
+export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps): InteractiveSlashRuntime {
+	let activeContextInit = false;
+	let latestAdmission: Promise<void> = Promise.resolve();
+	let activeAdmissionSignal: AbortSignal | undefined;
+	const cwd = (): string => deps.getCwd?.() ?? process.cwd();
+	const resources = deps.resources;
+	const userTasks = deps.userTasks;
+
+	const appendCommandNotice: SlashCommandContext["notice"] = (level, text) => {
+		appendNotice(level, text, {
+			appendReplayBlock: (renderBlock) => deps.chatPanel.appendReplayBlock(renderBlock),
+			requestRender: deps.requestRender,
+		});
+	};
+
+	/** One expanded operator turn into the chat loop: record it, paint it, submit it. */
+	const submitExpanded = (sub: InteractiveSlashSubmitExpansion, awaitAdmission = false): Promise<void> => {
+		try {
+			// Enter while streaming becomes a steer inside chat.submit. The
+			// queue panel shows it until the engine injects it, and the
+			// injection emits queued_user_turn, which is when the transcript
+			// renders it. Appending here too showed the text twice and at
+			// the wrong point in the turn's order.
+			const willQueue = deps.chat.isStreaming();
+			deps.recordSubmittedTurn();
+			deps.refreshFooter();
+			if (!willQueue) deps.chatPanel.appendUser(sub.text);
+			deps.requestRender();
+			deps.beforeSemanticSubmit?.();
+			let acknowledgeAdmission = (): void => {};
+			const admitted = new Promise<void>((resolve) => {
+				acknowledgeAdmission = resolve;
+			});
+			const turn = deps.chat.submit(sub.text, {
+				...(sub.images.length > 0 ? { images: sub.images } : {}),
+				...(sub.workingContextPaths.length > 0 ? { workingContextPaths: sub.workingContextPaths } : {}),
+				...(sub.pendingSkillRequests.length > 0 ? { pendingSkillRequests: sub.pendingSkillRequests } : {}),
+				...(awaitAdmission && willQueue ? { steering: "end-of-turn" as const } : {}),
+				...(awaitAdmission ? { onAdmitted: acknowledgeAdmission } : {}),
+			});
+			const settlement = turn
+				.then(() => deps.settleVisibleFrame?.("submit-return"))
+				.catch((err) => {
+					const msg = err instanceof Error ? err.message : String(err);
+					deps.io.stderr(`[interactive] chat failed: ${msg}\n`);
+				})
+				.finally(deps.requestRender);
+			return awaitAdmission ? Promise.race([admitted, settlement]) : settlement;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			deps.io.stderr(`[interactive] chat failed: ${msg}\n`);
+			deps.requestRender();
+			return Promise.resolve();
+		}
+	};
+
+	const admitChat = async (text: string, signal?: AbortSignal): Promise<void> => {
+		try {
+			signal?.throwIfAborted();
+			const submitted = await deps.expandSubmit(text);
+			signal?.throwIfAborted();
+			const uninstalled = submitted.pendingSkillRequests.find((request) => !request.installed);
+			if (uninstalled && !uninstalled.marketplaceRef) {
+				deps.io.stderr(`Skill "${uninstalled.name}" is not installed and no local marketplace entry is available.\n`);
+				return;
+			}
+			if (uninstalled) {
+				void deps
+					.openAskUser([
+						{
+							question: `Skill "${uninstalled.name}" is not installed. Would you like to install it?`,
+							options: [
+								{ label: "Install and run", description: `Install from ${uninstalled.marketplaceRef}` },
+								{ label: "Cancel", description: "Do not install." },
+							],
+						},
+					])
+					.then((res) => {
+						if (res.cancelled || res.answers[0]?.answer !== "Install and run") {
+							deps.io.stderr("Installation cancelled.\n");
+							return;
+						}
+						void (async () => {
+							try {
+								deps.io.stdout(`Installing skill "${uninstalled.name}"...\n`);
+								let configDir: string | undefined;
+								try {
+									configDir = (deps.getConfigDir ?? clioConfigDir)();
+								} catch (configErr) {
+									deps.io.stderr(
+										`Skill install: config dir unavailable (${configErr instanceof Error ? configErr.message : String(configErr)}); continuing without it.\n`,
+									);
+								}
+								(deps.installSkill ?? installSkill)({
+									source: uninstalled.name,
+									cwd: cwd(),
+									...(configDir ? { configDir } : {}),
+								});
+								deps.io.stdout(`Successfully installed "${uninstalled.name}"!\n`);
+								await deps.resources?.reload();
+								const postInstallSubmitted = await deps.expandSubmit(text);
+								submitExpanded(postInstallSubmitted);
+							} catch (err) {
+								deps.io.stderr(
+									`Failed to install skill "${uninstalled.name}": ${err instanceof Error ? err.message : String(err)}\n`,
+								);
+							}
+						})();
+					});
+				return;
+			}
+			await submitExpanded(submitted, true);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			deps.io.stderr(`[interactive] chat failed: ${msg}\n`);
+			deps.requestRender();
+		}
+	};
+	const context: SlashCommandContext = {
+		io: deps.io,
+		notice: appendCommandNotice,
+		echoOperatorCommand: (text) => {
+			appendOperatorCommand(text, {
+				appendReplayBlock: (renderBlock) => deps.chatPanel.appendReplayBlock(renderBlock),
+				requestRender: deps.requestRender,
+			});
+		},
+		dispatch: deps.dispatch,
+		bus: deps.bus,
+		...(deps.agents
+			? { getAgentRoleFacts: agentRoleFactsResolver((agentId: string) => deps.agents?.getSpec(agentId) ?? null) }
+			: {}),
+		shutdown: () => {
+			void deps.shutdown();
+		},
+		listPrompts: () => deps.resources?.prompts(cwd()) ?? { items: [], diagnostics: [] },
+		...(resources ? { expandPromptTemplate: (text: string) => resources.expandPromptTemplate(text, cwd()) } : {}),
+		openSkillsHub: deps.openSkillsHub,
+		listExtensions: () => deps.extensions?.list(cwd(), { all: true }) ?? [],
+		listAgents: () => deps.agents?.listSpecs().filter((spec) => spec.audience !== "internal") ?? [],
+		listDelegationAgents: () => deps.getSettings?.().delegation.agents ?? [],
+		exportShareArchive: (outPath) => {
+			if (!deps.share) throw new Error("share domain is not loaded");
+			const path = resolve(outPath);
+			const archive = deps.share.writeArchive(path, { scope: "project" });
+			return { fileCount: archive.files.length, path };
+		},
+		importShareArchive: (archivePath, options) => {
+			if (!deps.share) {
+				return {
+					archive: null,
+					actions: [],
+					diagnostics: [{ type: "error", message: "share domain is not loaded" }],
+				};
+			}
+			const importOptions = {
+				...(options.dryRun ? { dryRun: true } : {}),
+				...(options.force ? { force: true } : {}),
+			};
+			return options.dryRun
+				? deps.share.planImport(resolve(archivePath), importOptions)
+				: deps.share.importArchive(resolve(archivePath), importOptions);
+		},
+		openCost: deps.openCost,
+		openContextView: deps.openContextView,
+		openTasks: deps.openTasks,
+		openDecisions: deps.openDecisions,
+		...(userTasks
+			? {
+					userTasks: {
+						add: (title: string) => userTasks.add(title),
+						hand: (id: string) => userTasks.hand(id, deps.chat.getSessionId() ?? undefined),
+						done: (id: string) => userTasks.done(id),
+						drop: (id: string) => userTasks.drop(id),
+					},
+				}
+			: {}),
+		openMemory: deps.openMemory,
+		seedTaskMemory: () => {
+			const result = deps.seedTaskMemory?.() ?? { status: "not-found" as const };
+			deps.refreshFooter();
+			deps.requestRender();
+			return result;
+		},
+		openView: deps.openView,
+		setThinkingLevel: (level) => {
+			const settings = deps.getSettings?.();
+			if (!settings || !deps.onSetThinkingLevel) return { status: "unavailable" };
+			const thinking = resolveThinkingCapability(deps.providers, settings);
+			// The target's own supported set is the authority, and its labels are
+			// what the settings row and footer already show, so `/thinking on` works
+			// on an on-off model exactly as picking `on` in settings does.
+			const supported = thinking?.supportedLevels ?? (["off"] as ReadonlyArray<ThinkingLevel>);
+			const labelFor = (candidate: ThinkingLevel): string =>
+				thinkingLevelChoiceLabel(thinking?.mechanism ?? null, candidate);
+			const requested = level.trim().toLowerCase();
+			const match = supported.find((candidate) => candidate === requested || labelFor(candidate) === requested);
+			if (!match) {
+				return { status: "unsupported", level, supported: supported.map(labelFor) };
+			}
+			// Session scope, like /output: onSetThinkingLevel writes the level
+			// through to settings.yaml as the new default, which a slash command
+			// has no mandate to do.
+			if (deps.commitSetting) {
+				const next = structuredClone(settings) as ClioSettings;
+				next.orchestrator.thinkingLevel = match;
+				deps.commitSetting("orchestrator.thinkingLevel", next, "session");
+			} else {
+				deps.onSetThinkingLevel(match);
+			}
+			deps.refreshFooter();
+			return { status: "applied", level: match, display: labelFor(match) };
+		},
+		setOutputVerbosity: (verbosity) => {
+			if (!deps.getSettings || !(deps.commitSetting || deps.writeSettings)) return { status: "unavailable" };
+			const requested = verbosity.trim().toLowerCase();
+			const match = OUTPUT_VERBOSITIES.find((candidate) => candidate === requested);
+			if (!match) return { status: "unsupported", verbosity, supported: OUTPUT_VERBOSITIES };
+			const next = structuredClone(deps.getSettings()) as ClioSettings;
+			next.terminal.outputVerbosity = match;
+			// Session scope: /output changes this session and leaves settings.yaml
+			// alone. Saving it as the default is what Settings → Terminal is for.
+			if (deps.commitSetting) deps.commitSetting("terminal.outputVerbosity", next, "session");
+			else deps.writeSettings?.(next);
+			return { status: "applied", verbosity: match };
+		},
+		openModel: deps.openModel,
+		providers: deps.providers,
+		applyModelRef: (ref) => {
+			deps.onSelectModel?.({ target: ref.target, model: ref.model });
+			if (ref.thinkingLevel) deps.onSetThinkingLevel?.(ref.thinkingLevel);
+			deps.requestRender();
+		},
+		openSettings: deps.openSettings,
+		openResume: deps.openResume,
+		startNewSession: deps.startNewSession,
+		openTree: deps.openTree,
+		openMessagePicker: deps.openMessagePicker,
+		openHelp: deps.openHelp,
+		openAgents: deps.openAgents,
+		openPrompts: deps.openPrompts,
+		openExtensions: deps.openExtensions,
+		...(deps.openInterop ? { openInterop: deps.openInterop } : {}),
+		...(deps.interop ? { interop: deps.interop } : {}),
+		setEditorText: (text) => {
+			deps.setEditorText(text);
+			deps.requestRender();
+		},
+		runCompact: (instructions) => {
+			runCompactWithNotice(deps.onCompact, appendCommandNotice, instructions);
+		},
+		exportTranscript: (pathArg) => {
+			const sessionId = deps.chat.getSessionId();
+			if (!sessionId) {
+				appendCommandNotice("error", "[/export] no active session to export");
+				return;
+			}
+			try {
+				const turns = deps.readStructuredEntries(sessionId);
+				// Same pure render pipeline as the live panel and /resume replay: a
+				// throwaway panel is rehydrated from the ledger, every tool segment is
+				// expanded, and the transcript is rendered at a stable width. HTML
+				// converts the resulting ANSI presentation to inline styles; Markdown
+				// keeps the prior plain-text fenced transcript.
+				const exportPanel = createChatPanel({ unboundedToolBodies: true });
+				// Scoped to the leaf the session is on, the same way /resume replays
+				// (issue #107): with a /tree pin persisted and not yet extended, the
+				// file still holds the abandoned branch after the pin, and an unscoped
+				// rehydrate exported it as ordinary history (issue #109). No session
+				// contract means no pin can exist for this reader, so the file replays whole.
+				const leafTurnId = deps.session?.tree(sessionId).leafId ?? null;
+				rehydrateChatPanelFromTurns(exportPanel, turns, {
+					unboundedToolBodies: true,
+					...(leafTurnId ? { activeLeafTurnId: leafTurnId } : {}),
+				});
+				exportPanel.toggleAllToolsExpanded();
+				const ansiLines = exportPanel.render(EXPORT_RENDER_WIDTH);
+				// The operator names this file by the day they ran the export, so the
+				// date in it is their calendar date. The header below keeps the ISO
+				// instant, which is the machine-readable half of the same fact.
+				const exportedAt = deps.now?.() ?? new Date();
+				const date = dateLocal(exportedAt);
+				const requestedPath = pathArg?.trim() ?? "";
+				const markdown = requestedPath.toLowerCase().endsWith(".md");
+				const target = resolve(
+					requestedPath.length > 0 ? requestedPath : join(".clio-coder", "exports", `${sessionId}-${date}.html`),
+				);
+				mkdirSync(resolve(target, ".."), { recursive: true });
+				if (markdown) {
+					const lines = ansiLines.map(stripTerminalSequences);
+					const header = [`# Clio session ${sessionId}`, "", `Exported ${exportedAt.toISOString()}`, "", "```text"];
+					writeFileSync(target, `${[...header, ...lines, "```", ""].join("\n")}`, "utf8");
+				} else {
+					writeFileSync(target, renderSessionHtml({ sessionId, exportedAt: exportedAt.toISOString(), ansiLines }), "utf8");
+				}
+				appendCommandNotice("success", `[/export] wrote ${ansiLines.length} lines to ${target}`);
+			} catch (err) {
+				appendCommandNotice("error", `[/export] ${err instanceof Error ? err.message : String(err)}`);
+			}
+		},
+		runInit: (options) => {
+			const onInit = deps.onInit;
+			if (!onInit) {
+				deps.io.stderr("[/context init] context init not wired; pass onInit to startInteractive\n");
+				return;
+			}
+			if (activeContextInit) {
+				deps.io.stderr("[/context init] bootstrap already running\n");
+				return;
+			}
+			activeContextInit = true;
+			void Promise.resolve()
+				.then(() => onInit(options, deps.io))
+				.then(() => {
+					deps.dismissContextBootstrapNotices();
+					deps.refreshFooter();
+				})
+				.catch((err) => {
+					const msg = err instanceof Error ? err.message : String(err);
+					deps.io.stderr(`[/context init] ${msg}\n`);
+				})
+				.finally(() => {
+					activeContextInit = false;
+					deps.requestRender();
+				});
+		},
+		runContextClear: () => {
+			if (!deps.onContextClear) {
+				deps.io.stderr("[/context reset] context reset not wired; pass onContextClear to startInteractive\n");
+				return;
+			}
+			deps.openContextReset();
+		},
+		runContextRefresh: () => {
+			if (!deps.onContextRefresh) {
+				deps.io.stderr("[/context refresh] context refresh not wired; pass onContextRefresh to startInteractive\n");
+				return;
+			}
+			void deps
+				.onContextRefresh()
+				.catch((err) => {
+					const msg = err instanceof Error ? err.message : String(err);
+					deps.io.stderr(`[/context refresh] ${msg}\n`);
+				})
+				.finally(deps.requestRender);
+		},
+		verifyReceipt: (runId) => verifyReceiptFile(deps.stateDir, runId),
+		...(deps.listWorkerRuns ? { listWorkerRuns: deps.listWorkerRuns } : {}),
+		// The user-turn path, minus expansion. A worker's answer is literal text:
+		// running it through the prompt, skill, and @file expanders would let a
+		// worker's output name a file the operator never mentioned.
+		submitOperatorNote: (text) => submitExpanded({ text, images: [], workingContextPaths: [], pendingSkillRequests: [] }),
+		submitChat: (text) => {
+			latestAdmission = admitChat(text, activeAdmissionSignal);
+			void latestAdmission;
+		},
+		render: deps.requestRender,
+	};
+
+	return {
+		context,
+		notice: appendCommandNotice,
+		dispatchCommand: (text) => dispatchSlashCommand(parseSlashCommand(text), context),
+		admitCommand: async (text, signal) => {
+			signal?.throwIfAborted();
+			const command = parseSlashCommand(text);
+			const before = latestAdmission;
+			const previousSignal = activeAdmissionSignal;
+			activeAdmissionSignal = signal;
+			try {
+				dispatchSlashCommand(command, context);
+			} finally {
+				activeAdmissionSignal = previousSignal;
+			}
+			if (latestAdmission !== before) await latestAdmission;
+		},
+	};
+}

package/src/interactive/interactive-subscriptions.ts

@@ -0,0 +1,111 @@
+import { BusChannels } from "../core/bus-events.js";
+import type { SafeEventBus } from "../core/event-bus.js";
+import { readWorkerReceiptFacts } from "./worker-receipts.js";
+import { type WorkerRunEntryFields, workerRunEntryFields } from "./worker-replay.js";
+import {
+	createWorkerStream,
+	type WorkerEntryState,
+	type WorkerReceiptReader,
+	type WorkerStream,
+	type WorkerStreamChange,
+} from "./worker-stream.js";
+
+export type InteractiveNoticeLevel = "info" | "success" | "warning" | "error";
+
+export interface InteractiveSubscriptionsDeps {
+	bus: SafeEventBus;
+	refreshFooter: () => void;
+	renderTaskIsland: () => void;
+	renderContextIsland: () => void;
+	requestRender: () => void;
+	notify: (level: InteractiveNoticeLevel, text: string, key?: string) => void;
+	/**
+	 * Place or refresh a worker's transcript block. Optional only so a host
+	 * without a chat panel still gets the footer and island repaints. Without it
+	 * no block is placed and nothing is shareable, because `/share` reads
+	 * `chatPanel.workerStates()`. Tests rely on the contract staying optional.
+	 */
+	applyWorkerState?: (state: WorkerEntryState) => void;
+	/**
+	 * Record one attempt of a transcript-bound run in the session ledger, so a
+	 * resumed session can redraw the block from the entry plus its receipt.
+	 * Called where the block opens and once per failover; absent hosts simply
+	 * do not persist, which costs replay and nothing else. The argument is a
+	 * snapshot, not the live block, so a host that defers the write records the
+	 * attempt it was handed.
+	 */
+	recordWorkerRun?: (fields: WorkerRunEntryFields) => void;
+	/** Sealed-receipt reader, injected by tests. Defaults to `<state>/receipts/<runId>.json`. */
+	readWorkerReceipt?: WorkerReceiptReader;
+}
+
+export interface InteractiveSubscriptions {
+	/** Live worker blocks folded from the dispatch lifecycle, keyed by assignment. */
+	workers: WorkerStream;
+	dispose(): void;
+}
+
+/**
+ * Own the non-modal dispatch and context repaint subscriptions. Bus delivery
+ * is synchronous, so each handler deliberately preserves the existing order:
+ * fold the worker block, refresh data-backed footer state, refresh islands,
+ * then request one render. The worker fold runs first because the render it
+ * asks for has to show the delta that arrived with the event.
+ */
+export function createInteractiveSubscriptions(deps: InteractiveSubscriptionsDeps): InteractiveSubscriptions {
+	const workers = createWorkerStream({ readReceipt: deps.readWorkerReceipt ?? readWorkerReceiptFacts });
+	const repaint = (): void => {
+		deps.refreshFooter();
+		deps.renderTaskIsland();
+		deps.requestRender();
+	};
+	/** Fold one lifecycle payload into its worker block, place the block, then repaint. */
+	const folded =
+		<P>(reduce: (payload: P) => WorkerStreamChange | null, after?: (change: WorkerStreamChange) => void) =>
+		(payload: P): void => {
+			const change = reduce(payload);
+			if (change !== null) {
+				deps.applyWorkerState?.(change.entry);
+				after?.(change);
+			}
+			repaint();
+		};
+	const unsubscribers = [
+		deps.bus.on(BusChannels.DispatchEnqueued, repaint),
+		// Every attempt writes its own session entry: a failover is history, and
+		// the attempt trail a resumed block shows is that history read back.
+		deps.bus.on(
+			BusChannels.DispatchStarted,
+			folded(workers.started, (change) => deps.recordWorkerRun?.(workerRunEntryFields(change.entry))),
+		),
+		deps.bus.on(
+			BusChannels.DispatchProgress,
+			folded((payload) => {
+				const workerEvent = payload.event as { type?: unknown } | null | undefined;
+				if (workerEvent?.type === "clio_steer_received") {
+					deps.notify("success", `steer received by ${payload.agentId} (${payload.runId})`, `steer:${payload.runId}`);
+				}
+				return workers.progress(payload);
+			}),
+		),
+		deps.bus.on(BusChannels.RunAborted, folded(workers.aborted)),
+		deps.bus.on(BusChannels.DispatchCompleted, folded(workers.completed)),
+		deps.bus.on(BusChannels.DispatchFailed, folded(workers.failed)),
+		deps.bus.on(BusChannels.ContextActivity, () => {
+			deps.refreshFooter();
+			deps.renderContextIsland();
+			deps.renderTaskIsland();
+			deps.requestRender();
+		}),
+	];
+
+	let disposed = false;
+	return {
+		workers,
+		dispose(): void {
+			if (disposed) return;
+			disposed = true;
+			for (const unsubscribe of unsubscribers) unsubscribe();
+		},
+	};
+}