pi-subagents 0.69.0 → 0.70.0

package/src/inspectors/inspector-runner.ts

@@ -1,153 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as readline from "node:readline";
-import { fileURLToPath } from "node:url";
-import { parseMissionRecord } from "../missions/store.ts";
-import type { MissionRecord } from "../missions/types.ts";
-import { requestAsyncSteer, requestAsyncStop } from "../runs/background/control-channel.ts";
-import { formatAsyncRunTranscript } from "../runs/background/fleet-view.ts";
-import { steeringReceipt } from "../runs/background/steering.ts";
-import type { AsyncStatus } from "../shared/types.ts";
-import { readStatus } from "../shared/utils.ts";
-import { decodeSessionRoots } from "./session-roots-codec.ts";
-
-export interface RunnerOptions {
-	asyncDir: string;
-	runId: string;
-	index?: number;
-	missionPath?: string;
-	refreshMs: number;
-	allowSteer?: boolean;
-	allowStop?: boolean;
-	sessionRoots: string[];
-}
-
-function readMission(filePath: string | undefined): MissionRecord | undefined {
-	if (!filePath) return undefined;
-	try { return parseMissionRecord(JSON.parse(fs.readFileSync(filePath, "utf-8")), filePath); } catch { return undefined; }
-}
-
-export function formatInspectorDashboard(input: { status: AsyncStatus; asyncDir: string; index?: number; mission?: MissionRecord; allowSteer?: boolean; allowStop?: boolean; sessionRoots?: string[] }): string {
-	const { status, asyncDir, mission } = input;
-	const lines = [
-		`pi-subagents inspector for ${status.runId}`,
-		"This inspector mirrors lifecycle artifacts; closing it does not stop the run.",
-		"",
-	];
-	if (mission) {
-		lines.push(`Mission: ${mission.title} (${mission.status})`, `Mission id: ${mission.id}`);
-		const open = mission.decisions.filter((decision) => decision.status === "open");
-		if (open.length) lines.push(`Open decisions: ${open.map((decision) => `${decision.id}: ${decision.title}`).join(" | ")}`);
-		lines.push("");
-	}
-	lines.push(formatAsyncRunTranscript(status, asyncDir, { index: input.index, lines: 60, sessionRoots: input.sessionRoots }));
-	const acceptsPlainGuidance = input.index !== undefined || status.mode === "single";
-	const controls = [input.allowSteer === false || !acceptsPlainGuidance ? undefined : "type guidance", input.allowSteer === false ? undefined : "steer <message>", input.allowStop === false ? undefined : "stop", "status"].filter(Boolean);
-	lines.push("", `Controls: ${controls.join(" | ")}`, "Supervisor replies remain in the parent Pi session (subagent_supervisor/intercom); this inspector is read-only.");
-	return lines.join("\n");
-}
-
-function parseArgs(argv: string[]): RunnerOptions {
-	const values = new Map<string, string>();
-	for (let index = 0; index < argv.length; index += 2) {
-		const key = argv[index];
-		const value = argv[index + 1];
-		if (!key?.startsWith("--") || value === undefined) throw new Error(`Invalid inspector argument '${key ?? ""}'.`);
-		values.set(key, value);
-	}
-	const asyncDir = values.get("--async-dir");
-	const runId = values.get("--run-id");
-	if (!asyncDir || !runId) throw new Error("Inspector requires --async-dir and --run-id.");
-	const indexRaw = values.get("--index");
-	const childIndex = indexRaw === undefined ? undefined : Number(indexRaw);
-	if (childIndex !== undefined && (!Number.isInteger(childIndex) || childIndex < 0)) throw new Error("--index must be a non-negative integer.");
-	const sessionRootsRaw = values.get("--session-roots");
-	const sessionRoots = sessionRootsRaw === undefined ? [] : decodeSessionRoots(sessionRootsRaw);
-	const refreshRaw = values.get("--refresh-ms");
-	const refreshMs = refreshRaw === undefined ? 1_500 : Number(refreshRaw);
-	if (!Number.isInteger(refreshMs) || refreshMs < 250) throw new Error("--refresh-ms must be an integer >= 250.");
-	return {
-		asyncDir: path.resolve(asyncDir),
-		runId,
-		...(childIndex !== undefined ? { index: childIndex } : {}),
-		...(values.get("--mission-path") ? { missionPath: path.resolve(values.get("--mission-path")!) } : {}),
-		sessionRoots,
-		refreshMs,
-		allowSteer: values.get("--allow-steer") !== "false",
-		allowStop: values.get("--allow-stop") !== "false",
-	};
-}
-
-function isTerminal(status: AsyncStatus): boolean {
-	return status.state !== "queued" && status.state !== "running";
-}
-
-function queueInspectorSteer(options: RunnerOptions, status: AsyncStatus, message: string): string {
-	if (options.allowSteer === false) throw new Error("Authority policy does not allow steer from this inspector.");
-	if (isTerminal(status)) throw new Error(`Run '${options.runId}' is ${status.state} and cannot be steered.`);
-	const runningIndexes = (status.steps ?? []).map((step, index) => step.status === "running" ? index : undefined).filter((index): index is number => index !== undefined);
-	const targetIndex = options.index ?? (status.mode === "single" ? 0 : undefined);
-	if (targetIndex === undefined && runningIndexes.length === 0) throw new Error("No running child is available to steer. Open a child-specific inspector for a pending child.");
-	requestAsyncSteer(options.asyncDir, {
-		message,
-		...(targetIndex !== undefined ? { targetIndex } : { targetIndexes: runningIndexes }),
-		source: "inspector-runner",
-	});
-	return steeringReceipt(message, `Steering queued for run ${options.runId}.`);
-}
-
-export function submitInspectorControl(options: RunnerOptions, line: string): string {
-	const command = line.trim();
-	if (!command || command === "status") return "Status refreshed.";
-	const status = readStatus(options.asyncDir);
-	if (!status || status.runId !== options.runId) throw new Error(`Lifecycle status for run '${options.runId}' is unavailable.`);
-	if (command === "stop") {
-		if (options.allowStop === false) throw new Error("Authority policy does not allow stop from this inspector.");
-		if (isTerminal(status)) throw new Error(`Run '${options.runId}' is ${status.state} and cannot be stopped.`);
-		requestAsyncStop(options.asyncDir, { source: "inspector-runner" });
-		return `Stop requested for run ${options.runId}.`;
-	}
-	if (command.startsWith("steer ")) {
-		const message = command.slice("steer ".length).trim();
-		if (!message) throw new Error("steer requires a message.");
-		return queueInspectorSteer(options, status, message);
-	}
-	if (command.startsWith("reply ")) throw new Error("Supervisor replies are owned by the parent Pi session; use subagent_supervisor/intercom there.");
-	if (options.index === undefined && status.mode !== "single") throw new Error("Plain guidance requires a child-specific inspector. Use steer <message> to target all running children from the aggregate inspector.");
-	return queueInspectorSteer(options, status, command);
-}
-
-export function runInspector(argv = process.argv.slice(2)): void {
-	const options = parseArgs(argv);
-	let notice = "";
-	let timer: ReturnType<typeof setInterval> | undefined;
-	const render = () => {
-		const status = readStatus(options.asyncDir);
-		if (!status || status.runId !== options.runId) {
-			process.stdout.write(`\x1b[2J\x1b[Hpi-subagents inspector\n\nLifecycle status for ${options.runId} is unavailable.\n`);
-			return;
-		}
-		process.stdout.write(`\x1b[2J\x1b[H${formatInspectorDashboard({ status, asyncDir: options.asyncDir, index: options.index, mission: readMission(options.missionPath), allowSteer: options.allowSteer, allowStop: options.allowStop, sessionRoots: options.sessionRoots })}${notice ? `\n\n${notice}` : ""}\n> `);
-		if (isTerminal(status) && timer) {
-			clearInterval(timer);
-			timer = undefined;
-		}
-	};
-	const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
-	rl.on("line", (line) => {
-		try { notice = submitInspectorControl(options, line); } catch (cause) { notice = `Control error: ${cause instanceof Error ? cause.message : String(cause)}`; }
-		render();
-	});
-	render();
-	if (!isTerminal(readStatus(options.asyncDir) ?? { state: "failed" } as AsyncStatus)) {
-		timer = setInterval(render, options.refreshMs);
-		timer.unref?.();
-	}
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
-	try { runInspector(); } catch (cause) {
-		process.stderr.write(`Inspector failed: ${cause instanceof Error ? cause.message : String(cause)}\n`);
-		process.exitCode = 1;
-	}
-}

package/src/inspectors/plugins.ts

@@ -1,8 +0,0 @@
-import { createHerdrInspectorPlugin } from "./herdr/plugin.ts";
-import { createGhosttyInspectorPlugin } from "./ghostty/plugin.ts";
-import type { InspectorPlugin } from "./types.ts";
-
-/** Built-in inspector plugins, ordered by host preference. */
-export function createBuiltinInspectorPlugins(): readonly InspectorPlugin[] {
-	return [createHerdrInspectorPlugin(), createGhosttyInspectorPlugin()];
-}

package/src/inspectors/session-roots-codec.ts

@@ -1,31 +0,0 @@
-/**
- * Windows PowerShell has no backslash-escape for embedded double quotes: a
- * double-quoted string literal only recognizes `` `" `` or `""` to embed a
- * literal quote, so a naively-quoted JSON array (which is full of `"` and
- * `\` characters) gets truncated or split into multiple argv tokens the
- * moment PowerShell tokenizes the `pane run` command line.
- *
- * Base64 has no quotes, backslashes, or spaces for any shell to mangle, so
- * encoding the `--session-roots` payload sidesteps quoting entirely. It is
- * also plain ASCII, so it never hits shellQuote's Windows quoting branch in
- * a way that could still fail as new characters are added upstream.
- */
-export function encodeSessionRoots(roots: readonly string[]): string {
-	return Buffer.from(JSON.stringify(roots), "utf-8").toString("base64");
-}
-
-function parseStringArray(value: unknown): string[] | undefined {
-	if (!Array.isArray(value) || value.some((root) => typeof root !== "string")) return undefined;
-	return value;
-}
-
-/** Decodes a `--session-roots` argument produced by {@link encodeSessionRoots}. */
-export function decodeSessionRoots(raw: string): string[] {
-	try {
-		const decoded = parseStringArray(JSON.parse(Buffer.from(raw, "base64").toString("utf-8")));
-		if (decoded) return decoded;
-	} catch {
-		// Report one stable validation error below.
-	}
-	throw new Error("--session-roots must be a base64-encoded JSON array of strings.");
-}

package/src/inspectors/shell-command.ts

@@ -1,16 +0,0 @@
-function shellQuote(value: string, platform: NodeJS.Platform): string {
-	if (platform === "win32") return `"${value.replaceAll('"', '\\"')}"`;
-	return `'${value.replaceAll("'", "'\\''")}'`;
-}
-
-function isBareExecutable(value: string): boolean {
-	return /^[\w./@:-]+$/.test(value);
-}
-
-export function formatShellCommand(exe: string, args: readonly string[], platform: NodeJS.Platform = process.platform): string {
-	const quotedArgs = args.map((arg) => shellQuote(arg, platform));
-	if (platform === "win32") return `& ${[shellQuote(exe, platform), ...quotedArgs].join(" ")}`;
-	// Nushell treats a leading quoted token as a string, so use a bare invoker for paths that need quoting.
-	const invocation = isBareExecutable(exe) ? exe : `sh -c 'exec "$0" "$@"' ${shellQuote(exe, platform)}`;
-	return [invocation, ...quotedArgs].join(" ");
-}

package/src/inspectors/types.ts

@@ -1,51 +0,0 @@
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { Details } from "../shared/types.ts";
-
-export const INSPECTOR_ACTIONS = ["inspector.open", "inspector.command", "inspector.status", "inspector.close"] as const;
-export type InspectorAction = typeof INSPECTOR_ACTIONS[number];
-
-export interface InspectorParams {
-	id?: string;
-	runId?: string;
-	dir?: string;
-	index?: number;
-	focus?: boolean;
-}
-
-export interface InspectorTarget {
-	runId: string;
-	asyncDir: string;
-	index?: number;
-	status: {
-		cwd?: string;
-		state: string;
-		steps?: unknown[];
-	};
-}
-
-export interface InspectorContext {
-	cwd: string;
-	signal?: AbortSignal;
-	env: NodeJS.ProcessEnv;
-	now?: () => Date;
-	target: InspectorTarget;
-}
-
-export interface InspectorLaunch {
-	executable: string;
-	argv: string[];
-	displayCommand: string;
-	mission?: { id: string; path: string };
-	allowSteer: boolean;
-	allowStop: boolean;
-	sessionRoots: string[];
-}
-
-export interface InspectorPlugin {
-	readonly name: string;
-	available(context: InspectorContext): Promise<boolean> | boolean;
-	owns(context: InspectorContext): boolean;
-	open(context: InspectorContext, launch: InspectorLaunch, params: InspectorParams): Promise<AgentToolResult<Details>>;
-	status?(context: InspectorContext): Promise<AgentToolResult<Details>>;
-	close?(context: InspectorContext): Promise<AgentToolResult<Details>>;
-}

package/src/integrations/herdr-status.ts

@@ -1,400 +0,0 @@
-import {
-	SUBAGENT_ASYNC_COMPLETE_EVENT,
-	SUBAGENT_ASYNC_STARTED_EVENT,
-	SUBAGENT_CONTROL_EVENT,
-} from "../shared/types.ts";
-import { previewDisplayText, sanitizeDisplayText } from "../shared/display-text.ts";
-
-const DEFAULT_SOURCE = "pi-subagents:herdr";
-const DEFAULT_TTL_MS = 120_000;
-const DEFAULT_REFRESH_MS = 45_000;
-const MAX_TASK_LABEL_CHARS = 80;
-const MAX_TITLE_TASK_CHARS = 42;
-const MAX_WORKFLOW_LABEL_NODES = 128;
-const MAX_WORKFLOW_LABEL_DEPTH = 8;
-
-let metadataReportSeq = Date.now() * 1000;
-
-function nextMetadataReportSeq(): number {
-	metadataReportSeq = Math.max(metadataReportSeq + 1, Date.now() * 1000);
-	return metadataReportSeq;
-}
-
-export interface HerdrStatusBridgeEvents {
-	on(event: string, handler: (data: unknown) => void): (() => void) | void;
-	emit(event: string, data: unknown): void;
-}
-
-export interface HerdrStatusRun {
-	id: string;
-	agent?: string;
-	agents?: string[];
-	/** Explicit launch/workflow label only; raw prompts never enter pane metadata. */
-	taskLabel?: string;
-	needsAttention?: boolean;
-	attentionLabel?: string;
-}
-
-export interface HerdrStatusBridgeOptions {
-	events: HerdrStatusBridgeEvents;
-	env?: Record<string, string | undefined>;
-	/** Current authoritative active-run projection, used before TTL refresh. */
-	getRuns?: () => Iterable<HerdrStatusRun>;
-	/** Current project panes opened by this Pi session. Views are excluded. */
-	getProjectPaneCount?: () => number;
-	runHerdr: (args: readonly string[]) => void | Promise<void>;
-	ttlMs?: number;
-	refreshMs?: number;
-	timers?: {
-		setInterval: typeof setInterval;
-		clearInterval: typeof clearInterval;
-	};
-}
-
-export interface HerdrStatusBridge {
-	/**
-	 * Binds the pane owner. Only the root interactive session may publish pane
-	 * metadata: headless parents (print/json), non-UI harnesses, and child
-	 * runtimes must never fight the pane's lifecycle authority over display
-	 * state. Also re-syncs runs that survived a reload/resume.
-	 */
-	sessionStarted(input: { hasUI: boolean; runs: Iterable<HerdrStatusRun> }): void;
-	syncRuns(): void;
-	agentStarted(): void;
-	flush(): Promise<void>;
-	dispose(): void;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function boundedTaskLabel(value: unknown, maxChars = MAX_TASK_LABEL_CHARS): string | undefined {
-	if (typeof value !== "string") return undefined;
-	const normalized = sanitizeDisplayText(value).trim();
-	if (!normalized) return undefined;
-	return previewDisplayText(normalized, maxChars);
-}
-
-function workflowTaskLabel(data: Record<string, unknown>): string | undefined {
-	const explicit = boundedTaskLabel(data.taskLabel);
-	if (explicit) return explicit;
-	if (!isRecord(data.workflowGraph) || !Array.isArray(data.workflowGraph.nodes)) return undefined;
-	const currentNodeId = typeof data.workflowGraph.currentNodeId === "string" ? data.workflowGraph.currentNodeId : undefined;
-	const nodes: Record<string, unknown>[] = [];
-	const collect = (values: unknown[], depth: number): void => {
-		if (depth > MAX_WORKFLOW_LABEL_DEPTH || nodes.length >= MAX_WORKFLOW_LABEL_NODES) return;
-		for (const value of values) {
-			if (nodes.length >= MAX_WORKFLOW_LABEL_NODES) return;
-			if (!isRecord(value)) continue;
-			nodes.push(value);
-			if (Array.isArray(value.children)) collect(value.children, depth + 1);
-		}
-	};
-	collect(data.workflowGraph.nodes, 0);
-	const current = currentNodeId ? nodes.find((node) => node.id === currentNodeId) : undefined;
-	const active = current ?? nodes.find((node) => node.status === "running") ?? nodes.find((node) => node.status === "pending");
-	return boundedTaskLabel(active?.label);
-}
-
-function startedRun(data: unknown): HerdrStatusRun | undefined {
-	if (!isRecord(data) || typeof data.id !== "string" || !data.id) return undefined;
-	const taskLabel = workflowTaskLabel(data);
-	return {
-		id: data.id,
-		...(typeof data.agent === "string" ? { agent: data.agent } : {}),
-		...(Array.isArray(data.agents) && data.agents.every((agent) => typeof agent === "string") ? { agents: data.agents as string[] } : {}),
-		...(taskLabel ? { taskLabel } : {}),
-	};
-}
-
-function completedRunId(data: unknown): string | undefined {
-	if (!isRecord(data)) return undefined;
-	const id = typeof data.runId === "string" ? data.runId : data.id;
-	return typeof id === "string" && id.length > 0 ? id : undefined;
-}
-
-function attentionNotice(data: unknown): { runId: string; label: string } | undefined {
-	if (!isRecord(data) || data.source !== "async" || !isRecord(data.event)) return undefined;
-	if (data.event.type !== "needs_attention" || typeof data.event.runId !== "string" || !data.event.runId) return undefined;
-	const label = typeof data.noticeText === "string" && data.noticeText
-		? data.noticeText
-		: typeof data.event.message === "string" && data.event.message
-			? data.event.message
-			: "subagent needs attention";
-	return { runId: data.event.runId, label };
-}
-
-export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): HerdrStatusBridge {
-	const env = options.env ?? process.env;
-	const paneId = env.HERDR_PANE_ID;
-	const enabled = env.HERDR_ENV === "1" && typeof paneId === "string" && paneId.length > 0;
-	const runHerdr = options.runHerdr;
-	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
-	const refreshMs = options.refreshMs ?? DEFAULT_REFRESH_MS;
-	const timers = options.timers ?? { setInterval, clearInterval };
-	const runs = new Map<string, HerdrStatusRun>();
-	const attentionLabels = new Map<string, string>();
-	const acknowledgedAttention = new Set<string>();
-	const subscriptions: Array<() => void> = [];
-	let rootSession = false;
-	let published = false;
-	let busyRaised = false;
-	let busyLabel: string | undefined;
-	let blockedRaised = false;
-	let blockedLabel: string | undefined;
-	let disposed = false;
-	let pendingReport: readonly string[] | undefined;
-	let draining = false;
-	let drainPromise = Promise.resolve();
-	let refreshTimer: ReturnType<typeof setInterval> | undefined;
-
-	const activeAgentNames = (): string[] => [...new Set([...runs.values()].flatMap((run) => run.agents?.length ? run.agents : run.agent ? [run.agent] : []))];
-	const activeSubagentCount = (): number => [...runs.values()].reduce((total, run) => total + Math.max(1, run.agents?.length ?? (run.agent ? 1 : 0)), 0);
-	const activeTaskLabel = (): string | undefined => [...runs.values()].reverse().find((run) => run.taskLabel)?.taskLabel;
-
-	const label = (includeAttention = false): string => {
-		const agents = activeAgentNames();
-		const activeCount = activeSubagentCount();
-		const who = agents.length > 0
-			? ` (${agents.slice(0, 3).join(", ")}${agents.length > 3 ? ", …" : ""})`
-			: "";
-		const panes = Math.max(0, options.getProjectPaneCount?.() ?? 0);
-		const paneText = panes > 0 ? ` · ${panes} pane${panes === 1 ? "" : "s"}` : "";
-		const task = activeTaskLabel();
-		const taskText = task ? ` · ${task}` : "";
-		const attention = includeAttention && attentionLabels.size > 0 ? " ⚠" : "";
-		return `⏳ ${activeCount} subagent${activeCount === 1 ? "" : "s"}${who}${paneText}${taskText}${attention}`;
-	};
-
-	const titleSuffix = (): string | undefined => {
-		if (runs.size === 0) return undefined;
-		const agentNames = activeAgentNames();
-		const activeCount = activeSubagentCount();
-		const task = boundedTaskLabel(activeTaskLabel(), MAX_TITLE_TASK_CHARS);
-		const target = task ?? (activeCount === 1 && agentNames.length === 1 ? agentNames[0]! : String(activeCount));
-		return `⏳${target}${attentionLabels.size > 0 ? "⚠" : ""}`;
-	};
-
-	const enqueue = (args: readonly string[]): void => {
-		pendingReport = args;
-		if (draining) return;
-		draining = true;
-		drainPromise = (async () => {
-			while (pendingReport) {
-				const next = pendingReport;
-				pendingReport = undefined;
-				try {
-					await runHerdr(next);
-				} catch {
-					// Herdr integration is best effort; a later state transition or TTL
-					// refresh retries with the newest desired snapshot.
-				}
-			}
-		})().finally(() => {
-			draining = false;
-		});
-	};
-
-	const publish = (): void => {
-		if (!enabled || !rootSession || disposed || !paneId) return;
-		if (runs.size === 0 && !published) return;
-		const seq = String(nextMetadataReportSeq());
-		if (runs.size === 0) {
-			published = false;
-			enqueue([
-				"pane", "report-metadata", paneId,
-				"--source", DEFAULT_SOURCE,
-				"--agent", "pi",
-				"--applies-to-source", "herdr:pi",
-				"--clear-state-labels",
-				"--clear-token", "summary",
-				"--clear-token", "title-suffix",
-				"--seq", seq,
-			]);
-			return;
-		}
-		const text = label(true);
-		const suffix = titleSuffix();
-		published = true;
-		enqueue([
-			"pane", "report-metadata", paneId,
-			"--source", DEFAULT_SOURCE,
-			"--agent", "pi",
-			"--applies-to-source", "herdr:pi",
-			"--state-label", `idle=${text}`,
-			"--state-label", `done=${text}`,
-			"--state-label", `working=${text}`,
-			"--token", `summary=${text}`,
-			...(suffix ? ["--token", `title-suffix=${suffix}`] : []),
-			"--ttl-ms", String(ttlMs),
-			"--seq", seq,
-		]);
-	};
-
-	const syncRefreshTimer = (): void => {
-		if (runs.size > 0 && refreshMs > 0 && !refreshTimer) {
-			refreshTimer = timers.setInterval(() => refresh(), refreshMs);
-			refreshTimer.unref?.();
-		} else if ((runs.size === 0 || refreshMs <= 0) && refreshTimer) {
-			timers.clearInterval(refreshTimer);
-			refreshTimer = undefined;
-		}
-	};
-
-	const syncBusy = (): void => {
-		if (!enabled || !rootSession || disposed) return;
-		if (runs.size > 0) {
-			const text = label();
-			if (busyRaised && busyLabel === text) return;
-			if (busyRaised) options.events.emit("herdr:busy", { active: false });
-			busyRaised = true;
-			busyLabel = text;
-			options.events.emit("herdr:busy", { active: true, label: text });
-			return;
-		}
-		if (busyRaised) {
-			busyRaised = false;
-			busyLabel = undefined;
-			options.events.emit("herdr:busy", { active: false });
-		}
-	};
-
-	const syncBlocked = (): void => {
-		if (!enabled || !rootSession || disposed) return;
-		const nextLabel = [...attentionLabels.values()].at(-1);
-		if (nextLabel !== undefined) {
-			if (blockedRaised && blockedLabel === nextLabel) return;
-			// Herdr's sibling overlay contract is counted. Lower before changing
-			// the active label so this bridge continues to own exactly one count.
-			if (blockedRaised) options.events.emit("herdr:blocked", { active: false });
-			blockedRaised = true;
-			blockedLabel = nextLabel;
-			options.events.emit("herdr:blocked", { active: true, label: nextLabel });
-			return;
-		}
-		if (blockedRaised) {
-			blockedRaised = false;
-			blockedLabel = undefined;
-			options.events.emit("herdr:blocked", { active: false });
-		}
-	};
-
-	const clearAttention = (): void => {
-		attentionLabels.clear();
-		syncBlocked();
-		publish();
-	};
-
-	const raiseAttention = (runId: string, labelText: string): void => {
-		if (!rootSession || attentionLabels.has(runId)) return;
-		acknowledgedAttention.delete(runId);
-		attentionLabels.set(runId, labelText);
-		syncBlocked();
-		publish();
-	};
-
-	const replaceRuns = (nextRuns: Iterable<HerdrStatusRun>): void => {
-		const nextAttention = new Map<string, string>();
-		const activeIds = new Set<string>();
-		runs.clear();
-		for (const run of nextRuns) {
-			if (!run || typeof run.id !== "string" || !run.id) continue;
-			activeIds.add(run.id);
-			const taskLabel = boundedTaskLabel(run.taskLabel);
-			const { taskLabel: _rawTaskLabel, ...sanitizedRun } = run;
-			runs.set(run.id, { ...sanitizedRun, ...(taskLabel ? { taskLabel } : {}) });
-			if (!run.needsAttention) {
-				acknowledgedAttention.delete(run.id);
-			} else if (!acknowledgedAttention.has(run.id)) {
-				nextAttention.set(run.id, run.attentionLabel || attentionLabels.get(run.id) || "subagent needs attention");
-			}
-		}
-		for (const id of acknowledgedAttention) {
-			if (!activeIds.has(id)) acknowledgedAttention.delete(id);
-		}
-		attentionLabels.clear();
-		for (const [id, labelText] of nextAttention) attentionLabels.set(id, labelText);
-		syncBusy();
-		syncRefreshTimer();
-		syncBlocked();
-		publish();
-	};
-
-	const refresh = (): void => {
-		if (!options.getRuns) {
-			publish();
-			return;
-		}
-		try {
-			replaceRuns(options.getRuns());
-		} catch {
-			// Keep the last known active projection and retry on the next refresh.
-			publish();
-		}
-	};
-
-	const subscribe = (event: string, handler: (data: unknown) => void): void => {
-		const unsubscribe = options.events.on(event, handler);
-		if (typeof unsubscribe === "function") subscriptions.push(unsubscribe);
-	};
-
-	if (enabled) {
-		subscribe(SUBAGENT_ASYNC_STARTED_EVENT, (data) => {
-			if (!rootSession) return;
-			const run = startedRun(data);
-			if (!run) return;
-			acknowledgedAttention.delete(run.id);
-			runs.set(run.id, run);
-			syncBusy();
-			syncRefreshTimer();
-			publish();
-		});
-		subscribe(SUBAGENT_ASYNC_COMPLETE_EVENT, (data) => {
-			if (!rootSession) return;
-			const id = completedRunId(data);
-			if (!id || !runs.delete(id)) return;
-			acknowledgedAttention.delete(id);
-			if (attentionLabels.delete(id)) syncBlocked();
-			syncBusy();
-			syncRefreshTimer();
-			publish();
-		});
-		subscribe(SUBAGENT_CONTROL_EVENT, (data) => {
-			if (!rootSession) return;
-			const notice = attentionNotice(data);
-			if (!notice || !runs.has(notice.runId)) return;
-			raiseAttention(notice.runId, notice.label);
-		});
-	}
-
-	return {
-		agentStarted() {
-			for (const id of attentionLabels.keys()) acknowledgedAttention.add(id);
-			clearAttention();
-		},
-		sessionStarted({ hasUI, runs: restoredRuns }) {
-			if (!enabled || disposed || hasUI !== true) return;
-			rootSession = true;
-			replaceRuns(restoredRuns);
-		},
-		syncRuns() {
-			if (!enabled || !rootSession || disposed) return;
-			refresh();
-		},
-		async flush() {
-			while (draining || pendingReport) await drainPromise;
-		},
-		dispose() {
-			if (disposed) return;
-			clearAttention();
-			acknowledgedAttention.clear();
-			runs.clear();
-			syncBusy();
-			syncRefreshTimer();
-			publish();
-			for (const unsubscribe of subscriptions) unsubscribe();
-			disposed = true;
-		},
-	};
-}