@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/interactive/watch-pane.ts

@@ -0,0 +1,152 @@
+/**
+ * The workers-view watch pane: one pane, beside Clio's own, rendering whatever
+ * run the operator points at.
+ *
+ * The pane hosts `clio-coder fleet view --watch <selection-file>` (see
+ * src/cli/fleet-view.ts), a durable-state viewer that re-reads the selection
+ * file on every poll. Retargeting is therefore one small atomic file write:
+ * arrow keys in the Alt+W board follow the cursor with zero socket traffic and
+ * zero pane churn, which is what makes the navigation feel like part of the
+ * board rather than like driving a terminal multiplexer.
+ *
+ * Pane creation is deliberately lazy, but reclamation is eager. A surviving
+ * pane is adopted as soon as the controller starts so the relaunched session's
+ * inventory owns it before the next watch command. A new pane still opens only
+ * on the first watch (operator Enter, `/panes show`, or the panes tool), and is
+ * never closed by navigation: leaving the workers view parks it on the last
+ * selection, and it goes away when the operator quits the viewer (`q`), closes
+ * the pane, or runs `/panes close watch`.
+ */
+
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { type ClioDirs, clioCacheDir, clioConfigDir, clioDataDir, clioStateDir } from "../core/xdg.js";
+import type { MuxContract } from "../domains/mux/index.js";
+import type { PanesWatchController, PanesWatchResult } from "../domains/mux/operations.js";
+import { watchViewerCommand } from "../domains/mux/viewer-command.js";
+
+/**
+ * One selection file per state root, deliberately not per session: every
+ * session over a state root shares one run ledger, so a surviving watch pane
+ * from a crashed session keeps working the moment a new session writes the
+ * same file.
+ */
+function watchSelectionPath(stateDir: string = clioStateDir()): string {
+	return join(stateDir, "watch-selection");
+}
+
+export interface WatchPaneDeps {
+	mux: MuxContract;
+	getCwd: () => string;
+	/** Selection-file override for tests. */
+	selectionPath?: string;
+	/** Resolved-layout override for tests. Production pins this process's four cached roots. */
+	dirs?: Readonly<ClioDirs>;
+	/** Command override for tests; production runs this install's own CLI. */
+	command?: (selectionPath: string, dirs: Readonly<ClioDirs>) => ReadonlyArray<string>;
+	writeFile?: (path: string, content: string) => void;
+}
+
+/** Replace-by-rename so the viewer's poll never reads a torn line. */
+function atomicWrite(path: string, content: string): void {
+	mkdirSync(dirname(path), { recursive: true });
+	const tmp = `${path}.tmp`;
+	writeFileSync(tmp, content, "utf8");
+	renameSync(tmp, path);
+}
+
+export function createWatchPaneController(deps: WatchPaneDeps): PanesWatchController {
+	const selectionPath = deps.selectionPath ?? watchSelectionPath();
+	const dirs =
+		deps.dirs ??
+		Object.freeze({
+			config: clioConfigDir(),
+			data: clioDataDir(),
+			state: clioStateDir(),
+			cache: clioCacheDir(),
+		});
+	const command = deps.command ?? ((path, layout) => watchViewerCommand(path, { dirs: layout }));
+	const write = deps.writeFile ?? atomicWrite;
+
+	let paneId: string | null = null;
+	let disposed = false;
+	let adoptionInFlight: Promise<boolean> | null = null;
+	const unsubscribe = deps.mux.onPaneGone((record) => {
+		if (record.ref.paneId === paneId) paneId = null;
+	});
+	const adoptExistingPane = (): Promise<boolean> => {
+		if (disposed || paneId !== null) return Promise.resolve(true);
+		if (adoptionInFlight !== null) return adoptionInFlight;
+		const attempt = Promise.resolve()
+			.then(() => deps.mux.adoptPane({ purpose: "watch", label: "watch" }))
+			.then((adopted) => {
+				if (!disposed && paneId === null && adopted !== null) paneId = adopted.paneId;
+				return true;
+			})
+			.catch(() => {
+				// Startup reclamation is best effort. An explicit watch retries the
+				// scan before it opens a replacement pane.
+				return false;
+			})
+			.finally(() => {
+				if (adoptionInFlight === attempt) adoptionInFlight = null;
+			});
+		adoptionInFlight = attempt;
+		return attempt;
+	};
+
+	const writeSelection = (runId: string): boolean => {
+		try {
+			write(selectionPath, `${runId}\n`);
+			return true;
+		} catch {
+			return false;
+		}
+	};
+
+	// Reclaim durable ownership for inventory and navigation immediately. The
+	// scan remains best effort and never opens a replacement pane on its own.
+	void adoptExistingPane();
+
+	return {
+		async watch(runId: string): Promise<PanesWatchResult> {
+			if (!writeSelection(runId)) {
+				return { status: "unavailable", reason: `cannot write the watch selection at ${selectionPath}` };
+			}
+			if (paneId !== null) return { status: "watching", runId, paneId, opened: false };
+			const scanned = await adoptExistingPane();
+			if (!scanned) await adoptExistingPane();
+			if (paneId !== null) return { status: "watching", runId, paneId, opened: false };
+			const opened = await deps.mux.openUtilityPane({
+				argv: command(selectionPath, dirs),
+				cwd: deps.getCwd(),
+				label: "watch",
+				title: "clio watch",
+				purpose: "watch",
+				direction: "right",
+			});
+			if (opened === null) {
+				return { status: "unavailable", reason: "the pane host refused to open the watch pane" };
+			}
+			paneId = opened.paneId;
+			return { status: "watching", runId, paneId, opened: true };
+		},
+
+		follow(runId: string): boolean {
+			// Navigation never opens anything; a closed watch pane stays closed
+			// until the operator asks again with Enter.
+			if (paneId === null) return false;
+			return writeSelection(runId);
+		},
+
+		isOpen(): boolean {
+			return paneId !== null;
+		},
+
+		dispose(): void {
+			// The pane parks; only the subscription goes.
+			disposed = true;
+			unsubscribe();
+		},
+	};
+}

package/src/interactive/worker-progress.ts

@@ -261,6 +261,8 @@ export function createWorkerProgressFold(): WorkerProgressFold {
 	const toolNames: string[] = [];
 	let settled = false;
 	let durable = "";
+	/** True after one assistant message ended and before the next message emits prose. */
+	let betweenAssistantMessages = false;
 	/** Starts still awaiting a finish, oldest first. */
 	const pendingActions: WorkerAction[] = [];
 	/** New streams resolve exact starts through this index. */
@@ -340,7 +342,9 @@ export function createWorkerProgressFold(): WorkerProgressFold {
 
 			const delta = workerTextDelta(event);
 			if (delta.length > 0) {
-				changed = appendTail(admitDelta(delta, nowMs)) || changed;
+				const separator = betweenAssistantMessages && tailText.length > 0 && !tailText.endsWith("\n") ? "\n\n" : "";
+				betweenAssistantMessages = false;
+				changed = appendTail(admitDelta(`${separator}${delta}`, nowMs)) || changed;
 				changed = setPhase("writing") || changed;
 			} else if (isThinkingEvent(event)) {
 				// The phase moves and nothing else: reasoning content is never kept.
@@ -355,6 +359,7 @@ export function createWorkerProgressFold(): WorkerProgressFold {
 				if (delta.length === 0 && tailText.trim().length === 0) {
 					changed = appendTail(durableText) || changed;
 				}
+				betweenAssistantMessages = true;
 			}
 
 			const action = toolEventAction(event);
@@ -412,6 +417,7 @@ export function createWorkerProgressFold(): WorkerProgressFold {
 			pendingActions.length = 0;
 			pendingActionsById.clear();
 			durable = "";
+			betweenAssistantMessages = false;
 			settled = false;
 			phase = "starting";
 			touch();

package/src/interactive/worker-receipts.ts

@@ -19,7 +19,7 @@ import { clioStateDir } from "../core/xdg.js";
 import type { RunEnvelope, RunReceipt } from "../domains/dispatch/types.js";
 import { inspectRunReceiptTrustStatus } from "../domains/evidence/trust-status.js";
 import { receiptFilePath } from "./view/artifacts.js";
-import type { WorkerReceiptFacts, WorkerResultContract } from "./worker-stream.js";
+import type { WorkerPresentedResultContract, WorkerReceiptFacts, WorkerResultContract } from "./worker-stream.js";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -55,6 +55,22 @@ function contractFrom(receipt: Record<string, unknown>): WorkerResultContract |
 	return conformance === "pass" || conformance === "fail" || conformance === "not-reached" ? conformance : undefined;
 }
 
+const PRESENTED_RESULT_CONTRACTS: ReadonlyArray<WorkerPresentedResultContract> = [
+	"debugger-report",
+	"verifier-report",
+	"research-report",
+	"scout-report",
+];
+
+/** The kind is integrity-covered inside the validator source id on current receipts. */
+function contractKindFrom(receipt: Record<string, unknown>): WorkerPresentedResultContract | undefined {
+	const quality = isRecord(receipt.quality) ? receipt.quality : null;
+	const fact = quality !== null && isRecord(quality.resultContract) ? quality.resultContract : null;
+	const sourceId = optionalString(fact?.sourceId);
+	if (sourceId === undefined) return undefined;
+	return PRESENTED_RESULT_CONTRACTS.find((kind) => sourceId.startsWith(`agent-result-contract:${kind}:`));
+}
+
 /**
  * Project a parsed receipt onto the facts a worker block renders. The input is
  * whatever JSON the file held, not a typed {@link RunReceipt}: receipts written
@@ -66,6 +82,7 @@ export function workerReceiptFacts(receipt: Record<string, unknown>): WorkerRece
 	if (outcome === undefined) return null;
 	const output = isRecord(receipt.output) ? receipt.output : null;
 	const contract = contractFrom(receipt);
+	const contractKind = contractKindFrom(receipt);
 	const text = optionalString(output?.text);
 	const failureMessage = optionalString(receipt.failureMessage);
 	const outcomeCode = optionalString(receipt.outcomeCode);
@@ -82,6 +99,7 @@ export function workerReceiptFacts(receipt: Record<string, unknown>): WorkerRece
 		...(durationMs !== undefined ? { durationMs } : {}),
 		...(toolCalls !== undefined ? { toolCalls } : {}),
 		...(contract !== undefined ? { contract } : {}),
+		...(contractKind !== undefined ? { contractKind } : {}),
 		...(text !== undefined ? { text } : {}),
 	};
 }

package/src/interactive/worker-stream.ts

@@ -61,6 +61,9 @@ export interface WorkerAttempt {
 
 export type WorkerResultContract = "pass" | "fail" | "not-reached" | "unmeasured";
 
+/** Result kinds whose parsed envelopes have a dedicated transcript presentation. */
+export type WorkerPresentedResultContract = "debugger-report" | "verifier-report" | "research-report" | "scout-report";
+
 /**
  * Terminal facts a worker block reports. Sealed by the receipt when it can be
  * read, carried by the terminal event otherwise. Every unit is optional and
@@ -76,6 +79,8 @@ export interface WorkerReceiptSummary {
 	durationMs?: number;
 	toolCalls?: number;
 	contract?: WorkerResultContract;
+	/** Parsed from the receipt's result-contract source id; absent on legacy and untyped receipts. */
+	contractKind?: WorkerPresentedResultContract;
 	/** From an abort marker rather than a sealed terminal event; a later DispatchCompleted/DispatchFailed replaces it. */
 	provisional?: boolean;
 	/** The run is over, but no receipt could be read for it, and the ledger row could not explain why either. */

package/src/interactive/yazi-bridge.ts

@@ -0,0 +1,444 @@
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { clioCacheDir } from "../core/xdg.js";
+import type { MuxContract } from "../domains/mux/index.js";
+import type { YaziEvent } from "../domains/mux/yazi/event-stream.js";
+import { ensureYaziProfile, yaziProfileDir } from "../domains/mux/yazi/profile.js";
+import {
+	createYaziSession,
+	resolveYaziBinaries,
+	type YaziProfileMode,
+	type YaziResolvedBinaries,
+	type YaziSession,
+	type YaziSessionMode,
+	type YaziSessionOpenResult,
+	type YaziSessionOptions,
+} from "../domains/mux/yazi/session.js";
+
+export const YAZI_PICK_MAX_PATHS = 32;
+export const YAZI_PICK_MAX_CHARS = 4096;
+export const YAZI_LIVENESS_MS = 5000;
+
+export interface YaziBridgeSettings {
+	mode: YaziSessionMode;
+	profile: YaziProfileMode;
+	followCwd: boolean;
+}
+
+export interface YaziMentionBatch {
+	text: string;
+	inserted: number;
+	mentions: number;
+	plainPaths: number;
+	duplicates: number;
+	truncated: number;
+}
+
+export interface YaziBridgeStatus {
+	mode: YaziSessionMode | "closed";
+	paneId: string | null;
+	paneCwd: string | null;
+	lastLineAt: number | null;
+	droppedLines: number;
+}
+
+export type YaziBridgeOpenResult =
+	| { status: "opened"; mode: YaziSessionMode; paneId: string | null; existing: boolean }
+	| Exclude<YaziSessionOpenResult, { status: "opened" }>;
+
+export interface YaziBridge {
+	open(options?: { once?: boolean }): Promise<YaziBridgeOpenResult>;
+	status(): Readonly<YaziBridgeStatus>;
+	dispose(): void;
+}
+
+export interface YaziBridgeDeps {
+	mux?: MuxContract;
+	getDraft: () => string;
+	setDraft: (text: string) => void;
+	requestRender: () => void;
+	notice: (level: "info" | "warning", text: string) => void;
+	getCwd: () => string;
+	getSettings?: () => Readonly<YaziBridgeSettings>;
+	openSession?: (options: YaziSessionOptions) => Promise<YaziSessionOpenResult>;
+	/** TUI lease used only by the no-mux, in-terminal chooser. */
+	stopUi?: () => void;
+	startUi?: () => void;
+	runTerminalChooser?: (options: { cwd: string; profileMode: YaziProfileMode }) => Promise<YaziTerminalChooserResult>;
+	statPath?: (path: string) => "file" | "directory" | "other";
+	livenessMs?: number;
+	pickToken?: () => string;
+}
+
+export type YaziTerminalChooserResult =
+	| { status: "chosen"; choice: { paths: ReadonlyArray<string>; cwd: string } }
+	| { status: "cancelled" }
+	| { status: "missing-binary"; binary: "yazi" | "ya"; detail: string }
+	| { status: "profile-error"; reason: string }
+	| { status: "unavailable"; reason: string };
+
+export interface YaziTerminalChooserOptions {
+	cwd: string;
+	profileMode: YaziProfileMode;
+	stopUi: () => void;
+	startUi: () => void;
+	requestRender: () => void;
+	cacheDir?: string;
+	sessionId?: string;
+	resolveBinaries?: () => YaziResolvedBinaries;
+	ensureProfile?: typeof ensureYaziProfile;
+	spawnYazi?: (
+		file: string,
+		args: ReadonlyArray<string>,
+		options: { cwd: string; env: Readonly<NodeJS.ProcessEnv> },
+	) => { error?: Error };
+}
+
+function readOptional(path: string): string {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * Run Yazi as a full-screen chooser when no pane host is usable.
+ *
+ * Resolution, profile generation, and chooser-file truncation all happen
+ * before the TUI lease is released. A missing or below-floor binary therefore
+ * leaves the screen intact and returns the shared doctor sentence verbatim.
+ */
+export async function runYaziTerminalChooser(options: YaziTerminalChooserOptions): Promise<YaziTerminalChooserResult> {
+	const binaries = (options.resolveBinaries ?? resolveYaziBinaries)();
+	if (!binaries.yaziPath) {
+		return { status: "missing-binary", binary: "yazi", detail: binaries.missingYaziDetail };
+	}
+	if (options.profileMode === "managed" && !binaries.yaPath) {
+		return {
+			status: "missing-binary",
+			binary: "ya",
+			detail: "the Yazi helper `ya` is not available; install the complete pinned Yazi tool",
+		};
+	}
+
+	const cacheDir = options.cacheDir ?? clioCacheDir();
+	const sessionsDir = join(cacheDir, "yazi", "sessions");
+	mkdirSync(sessionsDir, { recursive: true });
+	const sessionId = options.sessionId ?? randomUUID();
+	const chooserPath = join(sessionsDir, `${sessionId}.chooser`);
+	const cwdPath = join(sessionsDir, `${sessionId}.cwd`);
+	const profile =
+		options.profileMode === "managed"
+			? (options.ensureProfile ?? ensureYaziProfile)({
+					yaPath: binaries.yaPath as string,
+					yaziPath: binaries.yaziPath,
+					profileDir: yaziProfileDir(cacheDir),
+				})
+			: null;
+	if (options.profileMode === "managed" && !profile) {
+		return { status: "profile-error", reason: "Clio could not generate a valid managed Yazi profile" };
+	}
+	writeFileSync(chooserPath, "");
+	writeFileSync(cwdPath, "");
+
+	const args = [options.cwd, "--chooser-file", chooserPath, "--cwd-file", cwdPath] as const;
+	const env = { ...process.env, ...(profile ? { YAZI_CONFIG_HOME: profile.dir } : {}) };
+	let processError: Error | undefined;
+	options.stopUi();
+	try {
+		const result = options.spawnYazi
+			? options.spawnYazi(binaries.yaziPath, args, { cwd: options.cwd, env })
+			: spawnSync(binaries.yaziPath, args, { cwd: options.cwd, env, stdio: "inherit" });
+		processError = result.error;
+	} catch (error) {
+		processError = error instanceof Error ? error : new Error(String(error));
+	} finally {
+		options.startUi();
+		options.requestRender();
+	}
+	if (processError) return { status: "unavailable", reason: `yazi chooser failed: ${processError.message}` };
+
+	const paths = readOptional(chooserPath)
+		.split("\n")
+		.filter((path) => path.length > 0);
+	if (paths.length === 0) return { status: "cancelled" };
+	return {
+		status: "chosen",
+		choice: { paths, cwd: readOptional(cwdPath).trim() || options.cwd },
+	};
+}
+
+function containsAsciiWhitespace(value: string): boolean {
+	for (const character of value) {
+		const code = character.charCodeAt(0);
+		if (code === 32 || (code >= 9 && code <= 13)) return true;
+	}
+	return false;
+}
+
+function relativeWhenInside(path: string, cwd: string): string {
+	const candidate = relative(cwd, path);
+	if (
+		candidate.length > 0 &&
+		candidate !== ".." &&
+		!candidate.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) &&
+		!isAbsolute(candidate)
+	) {
+		return candidate;
+	}
+	return path;
+}
+
+function draftContains(draft: string, item: string): boolean {
+	let from = 0;
+	while (from <= draft.length) {
+		const at = draft.indexOf(item, from);
+		if (at < 0) return false;
+		const before = at === 0 ? "" : (draft[at - 1] ?? "");
+		const after = draft[at + item.length] ?? "";
+		if ((before === "" || /\s/u.test(before)) && (after === "" || /\s/u.test(after))) return true;
+		from = at + item.length;
+	}
+	return false;
+}
+
+function pathKind(path: string): "file" | "directory" | "other" {
+	try {
+		const stat = statSync(path);
+		if (stat.isFile()) return "file";
+		if (stat.isDirectory()) return "directory";
+		return "other";
+	} catch {
+		return "other";
+	}
+}
+
+/** Format one DDS or chooser batch for the composer without ever submitting it. */
+export function formatYaziMentions(
+	paths: ReadonlyArray<string>,
+	options: {
+		cwd: string;
+		draft: string;
+		statPath?: (path: string) => "file" | "directory" | "other";
+		maxPaths?: number;
+		maxChars?: number;
+	},
+): YaziMentionBatch {
+	const maxPaths = options.maxPaths ?? YAZI_PICK_MAX_PATHS;
+	const maxChars = options.maxChars ?? YAZI_PICK_MAX_CHARS;
+	const inspect = options.statPath ?? pathKind;
+	const rendered: string[] = [];
+	const seen = new Set<string>();
+	let mentions = 0;
+	let plainPaths = 0;
+	let duplicates = 0;
+	let truncated = Math.max(0, paths.length - maxPaths);
+
+	const candidates = paths.slice(0, maxPaths);
+	for (const [index, rawPath] of candidates.entries()) {
+		const absolute = isAbsolute(rawPath) ? rawPath : resolve(options.cwd, rawPath);
+		if (seen.has(absolute)) {
+			duplicates += 1;
+			continue;
+		}
+		seen.add(absolute);
+		const kind = inspect(absolute);
+		let display = relativeWhenInside(absolute, options.cwd);
+		if (kind === "directory" && display !== "/" && !display.endsWith("/")) display = `${display}/`;
+		const mention = kind === "file" && !containsAsciiWhitespace(display);
+		const item = mention ? `@${display}` : `\`${display.replaceAll("`", "\\`")}\``;
+		if (draftContains(options.draft, item)) {
+			duplicates += 1;
+			continue;
+		}
+		const nextLength = rendered.length === 0 ? item.length : rendered.join(" ").length + 1 + item.length;
+		if (nextLength > maxChars) {
+			truncated += candidates.length - index;
+			break;
+		}
+		rendered.push(item);
+		if (mention) mentions += 1;
+		else plainPaths += 1;
+	}
+
+	return {
+		text: rendered.join(" "),
+		inserted: rendered.length,
+		mentions,
+		plainPaths,
+		duplicates,
+		truncated,
+	};
+}
+
+function appendDraft(draft: string, addition: string): string {
+	if (addition.length === 0) return draft;
+	if (draft.length === 0) return addition;
+	return `${draft.replace(/\s+$/u, "")} ${addition}`;
+}
+
+/** Own the only path from a Yazi decision into the interactive composer. */
+export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
+	const openSession = deps.openSession ?? createYaziSession;
+	let active: YaziSession | null = null;
+	let paneCwd: string | null = null;
+	let droppedLines = 0;
+	let disposed = false;
+	let generation = 0;
+	let livenessTimer: NodeJS.Timeout | null = null;
+	let sawLine = false;
+
+	const clearLiveness = (): void => {
+		if (livenessTimer) clearTimeout(livenessTimer);
+		livenessTimer = null;
+	};
+
+	const insert = (paths: ReadonlyArray<string>, cwd: string): void => {
+		const draft = deps.getDraft();
+		const batch = formatYaziMentions(paths, { cwd, draft, ...(deps.statPath ? { statPath: deps.statPath } : {}) });
+		if (batch.inserted === 0) {
+			if (batch.truncated > 0) {
+				deps.notice(
+					"warning",
+					`${batch.truncated} file-pane path${batch.truncated === 1 ? " was" : "s were"} omitted by the pick limits`,
+				);
+			}
+			return;
+		}
+		deps.setDraft(appendDraft(draft, batch.text));
+		deps.requestRender();
+		deps.notice(
+			"info",
+			`${batch.inserted} ${batch.inserted === 1 ? "path" : "paths"} from the file pane added to the draft`,
+		);
+		if (batch.plainPaths > 0) {
+			deps.notice(
+				"info",
+				`${batch.plainPaths} ${batch.plainPaths === 1 ? "path was" : "paths were"} inserted as plain text because directories and spaced paths cannot be file mentions`,
+			);
+		}
+		if (batch.truncated > 0) {
+			deps.notice(
+				"warning",
+				`${batch.truncated} file-pane path${batch.truncated === 1 ? " was" : "s were"} omitted by the pick limits`,
+			);
+		}
+	};
+
+	const start = async (mode: YaziSessionMode, profileMode: YaziProfileMode): Promise<YaziBridgeOpenResult> => {
+		const mux = deps.mux;
+		if (!mux?.available()) return { status: "unavailable", reason: "the pane layer is not available" };
+		generation += 1;
+		const ownGeneration = generation;
+		const token = (deps.pickToken ?? randomUUID)();
+		sawLine = false;
+		paneCwd = deps.getCwd();
+		const result = await openSession({
+			mux,
+			mode,
+			profileMode,
+			cwd: deps.getCwd(),
+			pickToken: token,
+			onEvent: (event: YaziEvent) => {
+				if (disposed || ownGeneration !== generation) return;
+				sawLine = true;
+				if (event.kind === "cd") {
+					paneCwd = event.cwd;
+					return;
+				}
+				if (event.values[0] !== token) {
+					droppedLines += 1;
+					return;
+				}
+				insert(event.values.slice(1), paneCwd ?? deps.getCwd());
+			},
+			onChooser: (choice) => {
+				if (disposed || ownGeneration !== generation) return;
+				paneCwd = choice.cwd;
+				if (choice.paths.length > 0) insert(choice.paths, choice.cwd);
+			},
+			onStopped: () => {
+				if (ownGeneration !== generation) return;
+				clearLiveness();
+				active = null;
+			},
+		});
+		if (result.status !== "opened") return result;
+		if (disposed || ownGeneration !== generation) {
+			await result.session.close();
+			return { status: "unavailable", reason: "the file pane was closed while it was opening" };
+		}
+		active = result.session;
+		if (mode === "companion") {
+			livenessTimer = setTimeout(() => {
+				if (disposed || ownGeneration !== generation || sawLine || active === null) return;
+				const stale = active;
+				active = null;
+				deps.notice("warning", "the file-pane event stream did not start; reopening yazi in chooser mode");
+				void stale.close().finally(() => {
+					if (!disposed && ownGeneration === generation) void start("chooser", profileMode);
+				});
+			}, deps.livenessMs ?? YAZI_LIVENESS_MS);
+			livenessTimer.unref();
+		}
+		return { status: "opened", mode, paneId: result.session.pane.paneId, existing: false };
+	};
+
+	return {
+		async open(options = {}): Promise<YaziBridgeOpenResult> {
+			if (disposed) return { status: "unavailable", reason: "the file-pane bridge is closed" };
+			const settings = deps.getSettings?.() ?? { mode: "companion", profile: "managed", followCwd: true };
+			if (active) {
+				if (settings.followCwd) {
+					const cwd = deps.getCwd();
+					if (await active.pushCwd(cwd)) paneCwd = cwd;
+				}
+				return { status: "opened", mode: active.mode, paneId: active.pane.paneId, existing: true };
+			}
+			const mode = options.once || settings.profile === "user" ? "chooser" : settings.mode;
+			if (!deps.mux?.available()) {
+				const result = await (
+					deps.runTerminalChooser ??
+					((choiceOptions) =>
+						runYaziTerminalChooser({
+							...choiceOptions,
+							stopUi: deps.stopUi ?? (() => {}),
+							startUi: deps.startUi ?? (() => {}),
+							requestRender: deps.requestRender,
+						}))
+				)({ cwd: deps.getCwd(), profileMode: settings.profile });
+				if (result.status === "chosen") {
+					paneCwd = result.choice.cwd;
+					insert(result.choice.paths, result.choice.cwd);
+				}
+				if (result.status === "chosen" || result.status === "cancelled") {
+					return { status: "opened", mode: "chooser", paneId: null, existing: false };
+				}
+				return result;
+			}
+			return await start(mode, settings.profile);
+		},
+		status(): Readonly<YaziBridgeStatus> {
+			const snapshot = active?.snapshot();
+			return {
+				mode: active?.mode ?? "closed",
+				paneId: active?.pane.paneId ?? null,
+				paneCwd: paneCwd ?? snapshot?.paneCwd ?? null,
+				lastLineAt: snapshot?.lastLineAt ?? null,
+				droppedLines,
+			};
+		},
+		dispose(): void {
+			if (disposed) return;
+			disposed = true;
+			generation += 1;
+			clearLiveness();
+			const closing = active;
+			active = null;
+			if (closing) void closing.close();
+		},
+	};
+}