@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/interactive/modal-marker.ts

@@ -0,0 +1,170 @@
+/**
+ * The outward signal that a modal overlay owns the keyboard.
+ *
+ * Every framed Clio overlay captures input for as long as it is up, and until
+ * now it announced that only by being on screen. An external driver feeding
+ * keys into the pane, and herdr deciding whether the pane is idle, working, or
+ * blocked, had to infer modality from whatever the overlay happened to draw:
+ * its box title, its hint row, a footer pill. Those are per-overlay strings
+ * that move on every reskin, and the tall modals cover the very rows a screen
+ * scraper reads, so the signal is weakest exactly when a modal is largest.
+ *
+ * The marker publishes the fact out of band instead, as an OSC 0 terminal
+ * title. Three properties make the title the reliable channel here:
+ *
+ *   1. It is not screen content. No overlay can composite over it, no
+ *      transcript line can counterfeit it, and no terminal height changes
+ *      whether it is readable.
+ *   2. herdr already consumes it. `region = "osc_title"` is a first-class
+ *      detection region (herdr `src/detect/manifest.rs`), fed from the pane's
+ *      own emulator, and its rules outrank every screen rule.
+ *   3. Clio has never written a title, so the channel carries exactly one
+ *      meaning and nothing else contends for it.
+ *
+ * The grammar is fixed and machine-first:
+ *
+ *   clio                                 no modal owns the keys
+ *   clio [modal:permission-confirm]      one modal, named
+ *   clio [modal:library-install+2]       top modal named, two more beneath it
+ *
+ * Nothing is written until the first modal opens, so a Clio that never opens
+ * an overlay leaves the pane's inherited title alone. From the first modal
+ * onward the title toggles between the marker and the bare base, which is what
+ * makes the absence of a marker a positive statement rather than an unknown.
+ */
+
+/** The write side of a terminal title. `ProcessTerminal` satisfies it structurally. */
+export interface ModalMarkerSink {
+	setTitle(title: string): void;
+}
+
+/** What the title reads when nothing modal owns the keyboard. */
+export const MODAL_MARKER_BASE_TITLE = "clio";
+
+/**
+ * The one regular expression an external reader needs. Exported so Clio's own
+ * contract test and herdr's manifest rule are written against the same shape
+ * rather than two hand-copied spellings of it.
+ */
+export const MODAL_MARKER_TITLE_PATTERN = /^clio \[modal:([a-z0-9][a-z0-9-]*)(?:\+([1-9]\d*))?\]$/u;
+
+/** Render the title for a modal stack, outermost first. */
+export function formatModalMarkerTitle(stack: readonly string[]): string {
+	const top = stack.at(-1);
+	if (top === undefined) return MODAL_MARKER_BASE_TITLE;
+	const beneath = stack.length - 1;
+	return `${MODAL_MARKER_BASE_TITLE} [modal:${top}${beneath > 0 ? `+${beneath}` : ""}]`;
+}
+
+/** Read a marker title back. Returns null for the base title and for anything else. */
+export function parseModalMarkerTitle(title: string): { id: string; depth: number } | null {
+	const match = MODAL_MARKER_TITLE_PATTERN.exec(title);
+	const id = match?.[1];
+	if (id === undefined) return null;
+	const beneath = match?.[2];
+	return { id, depth: beneath === undefined ? 1 : 1 + Number.parseInt(beneath, 10) };
+}
+
+/** One modal's claim on the keyboard, released when the overlay goes away. */
+export interface ModalMarkerHandle {
+	/** Drop this modal from the stack. Idempotent; a second call is inert. */
+	release(): void;
+	/**
+	 * Whether this modal currently owns keys. The engine's `setHidden` takes a
+	 * visible overlay out of the focus order without destroying it, which is how
+	 * a surface that shells out to a child process gets off the screen, so a
+	 * hidden modal must stop claiming the keyboard without leaving the stack.
+	 */
+	setActive(active: boolean): void;
+	/** Bring this modal back to the top of the stack, as `handle.focus()` does on screen. */
+	raise(): void;
+}
+
+interface ModalMarkerRegistry {
+	/**
+	 * Push a modal. The sink is taken from the caller rather than installed at
+	 * startup so the marker has no lifecycle of its own: it exists exactly when
+	 * an overlay exists, and a stub terminal with no `setTitle` makes the whole
+	 * mechanism inert instead of throwing.
+	 */
+	enter(id: string, sink?: ModalMarkerSink | null): ModalMarkerHandle;
+	/** The ids that currently own keys, outermost first. */
+	stack(): readonly string[];
+}
+
+interface ModalMarkerEntry {
+	readonly id: string;
+	active: boolean;
+}
+
+function createModalMarkerRegistry(): ModalMarkerRegistry {
+	const entries: ModalMarkerEntry[] = [];
+	let sink: ModalMarkerSink | null = null;
+	let published: string | null = null;
+
+	function activeIds(): string[] {
+		return entries.filter((entry) => entry.active).map((entry) => entry.id);
+	}
+
+	function publish(): void {
+		if (sink === null) return;
+		const title = formatModalMarkerTitle(activeIds());
+		// Before the first marker there is no stale claim to clear, so the pane
+		// keeps whatever title the shell or the multiplexer gave it.
+		if (published === null && title === MODAL_MARKER_BASE_TITLE) return;
+		if (title === published) return;
+		published = title;
+		sink.setTitle(title);
+	}
+
+	function enter(id: string, nextSink?: ModalMarkerSink | null): ModalMarkerHandle {
+		if (nextSink) sink = nextSink;
+		const entry: ModalMarkerEntry = { id, active: true };
+		entries.push(entry);
+		publish();
+		let released = false;
+		return {
+			release(): void {
+				if (released) return;
+				released = true;
+				const index = entries.indexOf(entry);
+				if (index !== -1) entries.splice(index, 1);
+				publish();
+			},
+			setActive(active: boolean): void {
+				if (released || entry.active === active) return;
+				entry.active = active;
+				publish();
+			},
+			raise(): void {
+				if (released) return;
+				entry.active = true;
+				const index = entries.indexOf(entry);
+				if (index !== -1 && index !== entries.length - 1) {
+					entries.splice(index, 1);
+					entries.push(entry);
+				}
+				publish();
+			},
+		};
+	}
+
+	return { enter, stack: (): readonly string[] => activeIds() };
+}
+
+let registry = createModalMarkerRegistry();
+
+/** Push a modal onto the process-wide stack. See {@link ModalMarkerRegistry.enter}. */
+export function enterModal(id: string, sink?: ModalMarkerSink | null): ModalMarkerHandle {
+	return registry.enter(id, sink);
+}
+
+/** The ids that currently own keys, outermost first. */
+export function modalMarkerStack(): readonly string[] {
+	return registry.stack();
+}
+
+/** Drop every claim and forget the sink. Tests use it to isolate; nothing in the app does. */
+export function resetModalMarker(): void {
+	registry = createModalMarkerRegistry();
+}

package/src/interactive/mutation-preview.ts

@@ -0,0 +1,295 @@
+/**
+ * Local inspection of the exact mutation a parked `write` or `edit` would make.
+ *
+ * The approval card describes an unlisted argument by type and size, so a
+ * parked write read `content=<string 482 bytes>` and a parked edit read
+ * `edits=<array 3 items>`: the operator authorized bytes they had never seen,
+ * and the only way to read them was the external session ledger (issue #254).
+ *
+ * Two rules shape everything here. The preview is derived from the same
+ * arguments object the decision resumes, and it carries a digest of those
+ * arguments so the bytes on screen are verifiably the bytes being approved.
+ * And the mutation text is process-local: it is built lazily when the operator
+ * asks for it, it is handed only to the overlay body, and it is never placed on
+ * {@link import("./permission-overlay.js").ApprovalRequestView}, which is what
+ * crosses into the transcript, the notices, and the worker seam.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { ToolNames } from "../core/tool-names.js";
+import { sanitizeCallTargetText, sanitizeMultilineDisplayText } from "../domains/safety/call-target.js";
+import {
+	applyEditsToNormalizedContent,
+	type Edit,
+	generateDiffString,
+	normalizeToLF,
+	stripBom,
+} from "../tools/edit-diff.js";
+import { resolveToCwd } from "../tools/path-utils.js";
+
+export { MUTATION_PREVIEW_KEY } from "./permission-hint.js";
+
+/** Rows of mutation shown at once. Anything longer scrolls, as `/handoff` review does. */
+export const MUTATION_PREVIEW_VISIBLE_ROWS = 16;
+
+/**
+ * Characters of proposed content the preview renders. The diff builder has its
+ * own byte backstop; this bounds the write path, whose payload is a whole file.
+ * Reaching it prints an explicit line naming what was withheld.
+ */
+export const MUTATION_PREVIEW_MAX_CHARS = 262_144;
+
+/**
+ * Facts about a parked mutation that may cross every process boundary: what
+ * kind it is, how big it is, and the digest that binds a preview to it. No part
+ * of the mutation text appears here, which is why this is the shape the
+ * approval view, the transcript row, and any notice may carry.
+ */
+export interface MutationFacts {
+	kind: "write" | "edit";
+	/** Bytes of proposed content (write), or of the replacement text across every edit. */
+	bytes: number;
+	/** Replacements in the edit list. One for a write. */
+	replacements: number;
+	/** Truncated SHA-256 over the exact call arguments this decision applies to. */
+	digest: string;
+}
+
+export interface MutationPreview {
+	facts: MutationFacts;
+	/** What the body is, named honestly on the overlay's first line. */
+	heading: string;
+	/** The complete rendered mutation, already sanitized and one entry per display row. */
+	body: ReadonlyArray<string>;
+	/** A control byte or escape sequence in the payload was neutralized for display. */
+	neutralized: boolean;
+	/** A tab was expanded, so columns are display columns. */
+	tabsExpanded: boolean;
+}
+
+/**
+ * Build the complete preview for the parked call, or explain why it cannot be
+ * built. Never throws: an unreadable file or an edit list that will not apply
+ * is itself something the operator needs to read before deciding.
+ */
+export type MutationInspector = () => MutationPreview;
+
+function canonicalJson(value: unknown): string {
+	if (value === null || value === undefined) return "null";
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (typeof value === "object") {
+		const entries = Object.entries(value as Record<string, unknown>)
+			.filter(([, entry]) => entry !== undefined)
+			.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+		return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+	}
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number") return Number.isFinite(value) ? JSON.stringify(value) : "null";
+	if (typeof value === "boolean") return value ? "true" : "false";
+	return "null";
+}
+
+/**
+ * The identity a decision is bound to. Key order and absent optional fields do
+ * not change it, so the same call digests the same way wherever it is read;
+ * anything else about the arguments does, which is the point: a call that
+ * differs from the previewed one cannot inherit its preview.
+ */
+export function callArgumentsDigest(args: Record<string, unknown> | undefined): string {
+	return createHash("sha256")
+		.update(canonicalJson(args ?? {}), "utf8")
+		.digest("hex")
+		.slice(0, 16);
+}
+
+function readEdits(value: unknown): Edit[] | null {
+	if (!Array.isArray(value)) return null;
+	const edits: Edit[] = [];
+	for (const entry of value) {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+		const record = entry as Record<string, unknown>;
+		if (typeof record.oldText !== "string" || typeof record.newText !== "string") return null;
+		edits.push({ oldText: record.oldText, newText: record.newText });
+	}
+	return edits;
+}
+
+/**
+ * The size-and-digest facts for a parked call, or null when the tool is not a
+ * file mutation or its arguments are not the shape this can describe. The card
+ * keeps rendering its allowlisted target either way.
+ */
+export function mutationFacts(tool: string, args: Record<string, unknown> | undefined): MutationFacts | null {
+	if (!args || typeof args.path !== "string" || args.path.length === 0) return null;
+	if (tool === ToolNames.Write) {
+		if (typeof args.content !== "string") return null;
+		return {
+			kind: "write",
+			bytes: Buffer.byteLength(args.content, "utf8"),
+			replacements: 1,
+			digest: callArgumentsDigest(args),
+		};
+	}
+	if (tool === ToolNames.Edit) {
+		const edits = readEdits(args.edits);
+		if (edits === null || edits.length === 0) return null;
+		const bytes = edits.reduce((total, edit) => total + Buffer.byteLength(edit.newText, "utf8"), 0);
+		return { kind: "edit", bytes, replacements: edits.length, digest: callArgumentsDigest(args) };
+	}
+	return null;
+}
+
+/** `write · 482 B · sha256 3f9a1c22ee04b7d1`, the collapsed card's whole mutation line. */
+export function mutationFactsLine(facts: MutationFacts): string {
+	const shape =
+		facts.kind === "write"
+			? `write ${facts.bytes} B`
+			: `edit ${facts.replacements} replacement${facts.replacements === 1 ? "" : "s"} · ${facts.bytes} B`;
+	return `${shape} · sha256 ${facts.digest}`;
+}
+
+function numberedLines(text: string): string[] {
+	const raw = text.split("\n");
+	const width = String(raw.length).length;
+	return raw.map((line, index) => `${String(index + 1).padStart(width, " ")} ${line}`);
+}
+
+function boundedContent(content: string): { text: string; withheld: number } {
+	if (content.length <= MUTATION_PREVIEW_MAX_CHARS) return { text: content, withheld: 0 };
+	return {
+		text: content.slice(0, MUTATION_PREVIEW_MAX_CHARS),
+		withheld: content.length - MUTATION_PREVIEW_MAX_CHARS,
+	};
+}
+
+function previewFrom(
+	facts: MutationFacts,
+	heading: string,
+	text: string,
+	options: { numbered?: boolean; trailer?: string } = {},
+): MutationPreview {
+	const clean = sanitizeMultilineDisplayText(text);
+	const body = options.numbered ? numberedLines(clean.text) : clean.text.split("\n");
+	if (options.trailer !== undefined) body.push(options.trailer);
+	return {
+		facts,
+		heading,
+		body,
+		neutralized: clean.neutralized,
+		tabsExpanded: clean.tabsExpanded,
+	};
+}
+
+function refusal(facts: MutationFacts, heading: string, reason: string): MutationPreview {
+	return { facts, heading, body: [reason], neutralized: false, tabsExpanded: false };
+}
+
+/**
+ * The requested replacements, rendered as a diff would render them, for the
+ * case where the effective diff cannot be computed. The operator still needs to
+ * read what the model asked for; the heading says this is the request rather
+ * than the effect.
+ */
+function replacementListing(edits: ReadonlyArray<Edit>): string {
+	const blocks: string[] = [];
+	for (const [index, edit] of edits.entries()) {
+		blocks.push(`@@ replacement ${index + 1} of ${edits.length}`);
+		for (const line of normalizeToLF(edit.oldText).split("\n")) blocks.push(`- ${line}`);
+		for (const line of normalizeToLF(edit.newText).split("\n")) blocks.push(`+ ${line}`);
+	}
+	return blocks.join("\n");
+}
+
+function editPreview(facts: MutationFacts, path: string, edits: ReadonlyArray<Edit>, read: (path: string) => string) {
+	let current: string;
+	try {
+		current = read(resolveToCwd(path));
+	} catch (error) {
+		const message = sanitizeCallTargetText(error instanceof Error ? error.message : String(error));
+		return previewFrom(
+			facts,
+			`Requested replacements for ${sanitizeCallTargetText(path)} (the file could not be read: ${message})`,
+			replacementListing(edits),
+		);
+	}
+	try {
+		const { text } = stripBom(current);
+		const applied = applyEditsToNormalizedContent(normalizeToLF(text), edits, path);
+		const diff = generateDiffString(applied.baseContent, applied.newContent);
+		return previewFrom(facts, `Effective diff for ${sanitizeCallTargetText(path)}`, diff.diff);
+	} catch (error) {
+		const message = sanitizeCallTargetText(error instanceof Error ? error.message : String(error));
+		return previewFrom(
+			facts,
+			`Requested replacements for ${sanitizeCallTargetText(path)} (they do not apply: ${message})`,
+			replacementListing(edits),
+		);
+	}
+}
+
+export interface MutationInspectorOptions {
+	/** Reads the current file bytes for an edit's effective diff. Injected so the contract test owns the filesystem. */
+	readFile?: (path: string) => string;
+}
+
+/**
+ * Bind an inspector to one parked call. The returned closure reads the file and
+ * computes the diff only when the operator presses the inspect key, and it
+ * re-derives the digest from the same arguments it renders: a mismatch means
+ * the arguments changed under the decision and the preview refuses rather than
+ * showing bytes that are no longer the ones being approved.
+ */
+export function createMutationInspector(
+	tool: string,
+	args: Record<string, unknown> | undefined,
+	facts: MutationFacts,
+	options: MutationInspectorOptions = {},
+): MutationInspector {
+	const read = options.readFile ?? ((path: string) => readFileSync(path, "utf8"));
+	return () => {
+		const current = mutationFacts(tool, args);
+		if (current === null || current.digest !== facts.digest) {
+			return refusal(
+				facts,
+				"Preview unavailable",
+				`These arguments no longer digest to sha256 ${facts.digest}. Deny this call rather than approving bytes that cannot be shown.`,
+			);
+		}
+		const path = typeof args?.path === "string" ? args.path : "";
+		if (facts.kind === "write") {
+			const content = typeof args?.content === "string" ? args.content : "";
+			const bounded = boundedContent(content);
+			return previewFrom(facts, `Proposed content for ${sanitizeCallTargetText(path)}`, bounded.text, {
+				numbered: true,
+				...(bounded.withheld > 0
+					? { trailer: `… ${bounded.withheld} more characters not shown (preview capped at ${MUTATION_PREVIEW_MAX_CHARS})` }
+					: {}),
+			});
+		}
+		const edits = readEdits(args?.edits) ?? [];
+		return editPreview(facts, path, edits, read);
+	};
+}
+
+/**
+ * The scrolled window of a preview, plus the position line that makes the cut
+ * visible. Mirrors the `/handoff` review overlay so both scrollable inspection
+ * surfaces read the same way.
+ */
+export function mutationPreviewWindow(
+	lines: ReadonlyArray<string>,
+	scroll: number,
+	rows = MUTATION_PREVIEW_VISIBLE_ROWS,
+): { window: ReadonlyArray<string>; position: string | null; maxScroll: number } {
+	const visible = Math.max(1, rows);
+	const maxScroll = Math.max(0, lines.length - visible);
+	const start = Math.max(0, Math.min(scroll, maxScroll));
+	const window = lines.slice(start, start + visible);
+	if (lines.length <= visible) return { window, position: null, maxScroll };
+	return {
+		window,
+		position: `(${start + 1}-${start + window.length} of ${lines.length} lines)`,
+		maxScroll,
+	};
+}

package/src/interactive/mux-bridge.ts

@@ -0,0 +1,214 @@
+/**
+ * The dispatch-to-pane-host bridge.
+ *
+ * Two responsibilities, both projections of state the session already owns:
+ *
+ * - **Terminal-run notifications.** A finished dispatch raises a pane-host
+ *   toast per the `panes.notifications` policy, and a failure additionally
+ *   leaves a persistent transcript notice, which unlike a toast remains
+ *   auditable in the TUI and does not depend on the pane host being alive.
+ *
+ * - **Self-report (SA-3).** Clio's own hosting pane, in guest mode, carries
+ *   the interactive status machine's phase as a semantic agent state, on a
+ *   trailing-edge throttle: herdr answers one request per connection, and an
+ *   operator turn passes through several phases inside one window, of which
+ *   only the last is worth a wire call.
+ *
+ * What this bridge deliberately no longer does is open panes. The phase 3/4
+ * integration projected every dispatch onto a viewer pane in a hidden Fleet
+ * tab (an `agents` policy knob, a keep-failed close policy, resume adoption,
+ * role-vocabulary sidebar labels). All of it duplicated the native fleet
+ * surfaces into panes the operator had not asked for; the one pane that
+ * renders runs is now the operator-pulled watch pane (`watch-pane.ts`), and
+ * the policy line lives in `pane-policy.ts`.
+ */
+
+import { type AgentStatusChangedPayload, BusChannels, type DispatchRunIdentity } from "../core/bus-events.js";
+import type { SafeEventBus } from "../core/event-bus.js";
+import type { MuxContract, MuxLog } from "../domains/mux/index.js";
+import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
+
+/** Trailing-edge window for the self-report; matches `WAIT_POLL_MS`. */
+export const MUX_BRIDGE_THROTTLE_MS = 250;
+
+/**
+ * A success worth a sound. Below it a finished run is one of many and a chime
+ * per run is noise; above it the operator has moved on and wants telling.
+ */
+const LONG_RUN_MS = 60_000;
+
+/** How much terminal detail may reach a toast body or a notice line. */
+const DETAIL_MAX_CHARS = 96;
+
+export type PanesNotificationsPolicy = "failures" | "all" | "off";
+
+/** Terminal outcomes that read as failure for the notification policy. */
+type BridgeRunOutcome = "succeeded" | "failed" | "canceled" | "timed_out";
+
+export interface MuxBridgeDeps {
+	bus: SafeEventBus;
+	mux: MuxContract;
+	/** Read live so a `/settings` change takes effect on the next terminal run. */
+	notificationsPolicy: () => PanesNotificationsPolicy;
+	/** Persistent transcript notice; unlike a herdr toast, this remains auditable in the TUI. */
+	notice?: (level: "error", text: string) => void;
+	log?: MuxLog;
+	now?: () => number;
+	throttleMs?: number;
+	setTimeoutFn?: typeof setTimeout;
+	clearTimeoutFn?: typeof clearTimeout;
+}
+
+export interface MuxBridge {
+	/** Settle every in-flight notification and self-report. Tests await it. */
+	flush(): Promise<void>;
+	dispose(): void;
+}
+
+function isFailure(outcome: BridgeRunOutcome): boolean {
+	return outcome === "failed" || outcome === "timed_out";
+}
+
+/** Clio's own pane state (SA-3), mapped from the interactive status machine. */
+function selfStateFor(phase: AgentStatusChangedPayload["phase"]): "working" | "blocked" | "idle" {
+	if (phase === "tool_blocked") return "blocked";
+	// `ended` is the settle step on the way back to idle, so both read idle.
+	return phase === "idle" || phase === "ended" ? "idle" : "working";
+}
+
+/**
+ * Clio's seven-member run outcome taxonomy narrowed to the four states the
+ * notification policy distinguishes. `stalled`, `denied_by_policy`,
+ * `spawn_failed`, and the synthetic `retry_denied` all read as failure, which
+ * is the safe direction: an unrecognized terminal state must not silently
+ * skip the failure notice.
+ */
+function terminalOutcome(outcome: string): BridgeRunOutcome {
+	if (outcome === "succeeded") return "succeeded";
+	if (outcome === "canceled") return "canceled";
+	if (outcome === "timed_out") return "timed_out";
+	return "failed";
+}
+
+export function createMuxBridge(deps: MuxBridgeDeps): MuxBridge {
+	const log = deps.log ?? ((): void => undefined);
+	const now = deps.now ?? Date.now;
+	const throttleMs = deps.throttleMs ?? MUX_BRIDGE_THROTTLE_MS;
+	const setTimeoutFn = deps.setTimeoutFn ?? setTimeout;
+	const clearTimeoutFn = deps.clearTimeoutFn ?? clearTimeout;
+
+	/** Start stamps, so a terminal event without a duration still gets one. */
+	const startedAt = new Map<string, number>();
+	let disposed = false;
+	let timer: ReturnType<typeof setTimeout> | null = null;
+	/** Serializes wire work: notifies and self-reports must not interleave. */
+	let draining: Promise<void> = Promise.resolve();
+	/** Pending self-report state, or null when nothing changed since the last flush. */
+	let pendingSelf: "working" | "blocked" | "idle" | null = null;
+	/** The last state actually reported, so a repeated phase costs no wire call. */
+	let reportedSelf: "working" | "blocked" | "idle" | null = null;
+
+	const schedule = (): void => {
+		if (disposed || timer !== null) return;
+		timer = setTimeoutFn(() => {
+			timer = null;
+			void drainSelf();
+		}, throttleMs);
+		timer.unref?.();
+	};
+
+	const drainSelf = (): Promise<void> => {
+		draining = draining.then(async () => {
+			if (disposed) return;
+			const self = pendingSelf;
+			pendingSelf = null;
+			if (self !== null && self !== reportedSelf) {
+				reportedSelf = self;
+				await deps.mux.reportSelf({ state: self }).catch(() => false);
+			}
+		});
+		return draining;
+	};
+
+	const boundedDetail = (value: string | null | undefined): string | null => {
+		if (typeof value !== "string" || value.length === 0) return null;
+		return sanitizeCallTargetText(value).slice(0, DETAIL_MAX_CHARS);
+	};
+
+	const onTerminal = (
+		identity: DispatchRunIdentity,
+		rawOutcome: string,
+		fields: { durationMs?: number | undefined; detail?: string | null | undefined },
+	): void => {
+		const outcome = terminalOutcome(rawOutcome);
+		const begun = startedAt.get(identity.runId);
+		startedAt.delete(identity.runId);
+		const policy = deps.notificationsPolicy();
+		const failed = isFailure(outcome);
+		const qualifies = policy === "all" || (policy === "failures" && failed);
+		if (!qualifies) return;
+		const detail = boundedDetail(fields.detail);
+		const durationMs =
+			typeof fields.durationMs === "number" ? fields.durationMs : begun === undefined ? null : now() - begun;
+		if (failed) {
+			deps.notice?.("error", `${identity.agentId} ${outcome} (${identity.runId})${detail ? `: ${detail}` : ""}`);
+		}
+		if (!deps.mux.available()) return;
+		draining = draining.then(async () => {
+			if (disposed) return;
+			try {
+				await deps.mux.notify({
+					title: `${identity.agentId} ${outcome}`,
+					...(detail ? { body: detail } : {}),
+					// A failure interrupts; a long success announces. A short success
+					// in `all` mode gets the toast without the chime.
+					sound: failed ? "request" : durationMs !== null && durationMs >= LONG_RUN_MS ? "done" : "none",
+				});
+			} catch (error) {
+				// The contract swallows its own failures; anything arriving here is a
+				// bug rather than a dead socket, and must still not kill the chain.
+				log("debug", `mux bridge notify failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+	};
+
+	const unsubscribers = [
+		deps.bus.on(BusChannels.DispatchStarted, (payload) => {
+			startedAt.set(payload.runId, now());
+		}),
+		deps.bus.on(BusChannels.DispatchCompleted, (payload) => {
+			onTerminal(payload, payload.outcome, { durationMs: payload.durationMs, detail: payload.outcomeDetail });
+		}),
+		deps.bus.on(BusChannels.DispatchFailed, (payload) => {
+			onTerminal(payload, payload.reason, { durationMs: payload.durationMs, detail: payload.outcomeDetail });
+		}),
+		// SA-3. The interactive status machine is the one surface that already
+		// knows when a turn starts, when it ends, and when a tool call is parked
+		// on an approval, so the self-report rides its transitions rather than
+		// growing a second turn-lifecycle listener.
+		deps.bus.on(BusChannels.AgentStatusChanged, (payload) => {
+			const state = selfStateFor(payload.phase);
+			if (state === reportedSelf && pendingSelf === null) return;
+			pendingSelf = state;
+			schedule();
+		}),
+	];
+
+	return {
+		flush(): Promise<void> {
+			if (timer !== null) {
+				clearTimeoutFn(timer);
+				timer = null;
+			}
+			return drainSelf();
+		},
+		dispose(): void {
+			if (disposed) return;
+			disposed = true;
+			if (timer !== null) clearTimeoutFn(timer);
+			timer = null;
+			for (const unsubscribe of unsubscribers) unsubscribe();
+			startedAt.clear();
+		},
+	};
+}