@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/domains/mux/yazi/event-stream.ts

@@ -0,0 +1,180 @@
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+
+export const YAZI_STREAM_POLL_MS = 250;
+export const YAZI_STREAM_MAX_BYTES = 1024 * 1024;
+
+export interface YaziCdEvent {
+	kind: "cd";
+	receiver: string;
+	sender: string;
+	tab: string;
+	cwd: string;
+}
+
+export interface YaziPickEvent {
+	kind: "clio-pick";
+	receiver: string;
+	sender: string;
+	values: ReadonlyArray<string>;
+}
+
+export type YaziEvent = YaziCdEvent | YaziPickEvent;
+export type YaziEventStreamStopReason = "stopped" | "pane-gone" | "file-missing" | "size-cap";
+
+export interface YaziEventStreamStats {
+	bytesRead: number;
+	linesRead: number;
+	malformedLines: number;
+	lastLineAt: number | null;
+	stopReason: YaziEventStreamStopReason | null;
+}
+
+export type YaziStreamLog = (level: "debug" | "warning", message: string) => void;
+
+export interface YaziEventStreamOptions {
+	path: string;
+	onEvent: (event: YaziEvent) => void;
+	isAlive: () => boolean | Promise<boolean>;
+	log?: YaziStreamLog;
+	now?: () => number;
+	pollMs?: number;
+	maxBytes?: number;
+	autoStart?: boolean;
+}
+
+export interface YaziEventStream {
+	poll(): Promise<void>;
+	stop(reason?: YaziEventStreamStopReason): void;
+	stats(): Readonly<YaziEventStreamStats>;
+	done: Promise<YaziEventStreamStopReason>;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Parse the four DDS fields with the same three-comma split Yazi uses. */
+export function parseYaziEventLine(line: string): YaziEvent | null {
+	const first = line.indexOf(",");
+	const second = first < 0 ? -1 : line.indexOf(",", first + 1);
+	const third = second < 0 ? -1 : line.indexOf(",", second + 1);
+	if (first <= 0 || second <= first + 1 || third <= second + 1) return null;
+	const kind = line.slice(0, first);
+	if (kind !== "cd" && kind !== "clio-pick") return null;
+	const receiver = line.slice(first + 1, second);
+	const sender = line.slice(second + 1, third);
+	try {
+		const body: unknown = JSON.parse(line.slice(third + 1));
+		if (kind === "cd") {
+			if (!record(body) || typeof body.url !== "string") return null;
+			const tab = body.tab;
+			if (typeof tab !== "number" && typeof tab !== "string") return null;
+			return { kind, receiver, sender, tab: String(tab), cwd: body.url };
+		}
+		if (!Array.isArray(body) || !body.every((value) => typeof value === "string")) return null;
+		return { kind, receiver, sender, values: body };
+	} catch {
+		return null;
+	}
+}
+
+/** Poll-tail one bounded DDS stdout file without knowing anything about panes or composers. */
+export function createYaziEventStream(options: YaziEventStreamOptions): YaziEventStream {
+	const log = options.log ?? ((): void => undefined);
+	const now = options.now ?? Date.now;
+	const maxBytes = options.maxBytes ?? YAZI_STREAM_MAX_BYTES;
+	let offset = 0;
+	let carry = "";
+	let decoder = new StringDecoder("utf8");
+	let stopped = false;
+	let polling = false;
+	let interval: NodeJS.Timeout | null = null;
+	let settleDone: (reason: YaziEventStreamStopReason) => void = () => {};
+	const done = new Promise<YaziEventStreamStopReason>((resolve) => {
+		settleDone = resolve;
+	});
+	const state: YaziEventStreamStats = {
+		bytesRead: 0,
+		linesRead: 0,
+		malformedLines: 0,
+		lastLineAt: null,
+		stopReason: null,
+	};
+
+	const stop = (reason: YaziEventStreamStopReason = "stopped"): void => {
+		if (stopped) return;
+		stopped = true;
+		state.stopReason = reason;
+		if (interval) clearInterval(interval);
+		interval = null;
+		log(reason === "size-cap" ? "warning" : "debug", `yazi event stream stopped (${reason}): ${options.path}`);
+		settleDone(reason);
+	};
+
+	const poll = async (): Promise<void> => {
+		if (stopped || polling) return;
+		polling = true;
+		try {
+			if (!(await options.isAlive())) {
+				stop("pane-gone");
+				return;
+			}
+			const stat = statSync(options.path, { throwIfNoEntry: false });
+			if (!stat?.isFile()) {
+				stop("file-missing");
+				return;
+			}
+			if (stat.size > maxBytes) {
+				stop("size-cap");
+				return;
+			}
+			if (stat.size < offset) {
+				offset = 0;
+				carry = "";
+				decoder = new StringDecoder("utf8");
+			}
+			const remaining = stat.size - offset;
+			if (remaining <= 0) return;
+			const bytes = Buffer.allocUnsafe(remaining);
+			const fd = openSync(options.path, "r");
+			let read = 0;
+			try {
+				read = readSync(fd, bytes, 0, remaining, offset);
+			} finally {
+				closeSync(fd);
+			}
+			offset += read;
+			state.bytesRead += read;
+			const complete = `${carry}${decoder.write(bytes.subarray(0, read))}`.split("\n");
+			carry = complete.pop() ?? "";
+			for (const raw of complete) {
+				const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+				if (line.length === 0) continue;
+				const kind = line.slice(0, line.indexOf(","));
+				if (kind !== "cd" && kind !== "clio-pick") continue;
+				const event = parseYaziEventLine(line);
+				if (!event) {
+					state.malformedLines += 1;
+					continue;
+				}
+				state.linesRead += 1;
+				state.lastLineAt = now();
+				try {
+					options.onEvent(event);
+				} catch (error) {
+					log("warning", `yazi event consumer failed: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			}
+		} finally {
+			polling = false;
+		}
+	};
+
+	if (options.autoStart !== false) {
+		interval = setInterval(() => void poll(), options.pollMs ?? YAZI_STREAM_POLL_MS);
+		interval.unref();
+		void poll();
+	}
+	return { poll, stop, stats: () => ({ ...state }), done };
+}

package/src/domains/mux/yazi/profile.ts

@@ -0,0 +1,299 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+	cpSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { readClioVersion, resolvePackageRoot } from "../../../core/package-root.js";
+import { parseTomlDocument } from "../../../core/toml.js";
+import { clioCacheDir, resolveClioDirs } from "../../../core/xdg.js";
+import { findPinnedTool } from "../../toolchain/registry.js";
+import { resolveToolBinary } from "../../toolchain/resolve.js";
+import { renderYaziTheme } from "./theme.js";
+
+const PROFILE_FILES = ["yazi.toml", "keymap.toml", "theme.toml", "init.lua"] as const;
+const PROFILE_PLUGIN_FILES = ["main.lua", "types.lua", "LICENSE", "README.md"] as const;
+const STAMP_FILE = "stamp.json";
+
+export interface YaziProfileStamp {
+	yaziVersion: string;
+	clioVersion: string;
+	yaPath: string;
+	assetSha256: string;
+	themeSha256: string;
+}
+
+export interface YaziProfile {
+	dir: string;
+	stamp: Readonly<YaziProfileStamp>;
+}
+
+export type YaziProfileState = "current" | "stale" | "missing";
+
+export interface YaziProfileInspection {
+	dir: string;
+	userConfigDir: string;
+	state: YaziProfileState;
+	stamp: Readonly<YaziProfileStamp>;
+}
+
+export interface YaziProfileOptions {
+	yaPath: string;
+	profileDir?: string;
+	assetDir?: string;
+	yaziVersion?: string;
+	clioVersion?: string;
+	themeToml?: string;
+	yaziToml?: string;
+	keymapToml?: string;
+}
+
+export interface EnsureYaziProfileOptions extends YaziProfileOptions {
+	yaziPath: string;
+}
+
+/** The managed profile location without creating the cache root. */
+export function yaziProfileDir(cacheDir: string = resolveClioDirs().cache): string {
+	return join(cacheDir, "yazi", "profile");
+}
+
+/** The config path Yazi itself would use when Clio does not set its override. */
+export function userYaziConfigDir(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string {
+	const xdg = env.XDG_CONFIG_HOME;
+	return xdg && isAbsolute(xdg) ? join(xdg, "yazi") : join(home, ".config", "yazi");
+}
+
+/** Remove only Clio's reproducible profile. The user's Yazi config is never addressed. */
+export function resetYaziProfile(profileDir: string = yaziProfileDir()): void {
+	rmSync(profileDir, { recursive: true, force: true });
+}
+
+function defaultAssetDir(): string {
+	return join(resolvePackageRoot(), "src", "domains", "mux", "yazi", "assets");
+}
+
+function yaziPin(): string {
+	return findPinnedTool("yazi")?.version ?? "unknown";
+}
+
+function sha256(input: string | Buffer): string {
+	return createHash("sha256").update(input).digest("hex");
+}
+
+function filesBelow(root: string, current: string = root): string[] {
+	const files: string[] = [];
+	for (const entry of readdirSync(current, { withFileTypes: true }).sort((left, right) =>
+		left.name.localeCompare(right.name),
+	)) {
+		const path = join(current, entry.name);
+		if (entry.isDirectory()) files.push(...filesBelow(root, path));
+		else if (entry.isFile()) files.push(relative(root, path).replaceAll("\\", "/"));
+	}
+	return files;
+}
+
+/** Hash file names and bytes in a stable order, so any vendored-asset change invalidates the profile. */
+export function hashYaziAssetTree(assetDir: string): string {
+	const hash = createHash("sha256");
+	for (const file of filesBelow(assetDir)) {
+		hash.update(file);
+		hash.update("\0");
+		hash.update(readFileSync(join(assetDir, file)));
+		hash.update("\0");
+	}
+	return hash.digest("hex");
+}
+
+function shellQuote(value: string): string {
+	return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/** Render the one Clio key chord, with an absolute `ya` path for vendored installs. */
+export function renderYaziKeymap(yaPath: string): string {
+	const command = `shell -- ${shellQuote(yaPath)} pub-to "$YAZI_ID" clio-pick --list "$CLIO_YAZI_PICK_TOKEN" %s`;
+	return `# Generated by Clio Coder. Changes are replaced when the managed profile regenerates.
+
+[[mgr.prepend_keymap]]
+on   = "<C-y>"
+run  = ${JSON.stringify(command)}
+desc = "Send the selection to Clio"
+`;
+}
+
+function expected(options: YaziProfileOptions): {
+	dir: string;
+	assetDir: string;
+	yaziToml: string;
+	keymapToml: string;
+	themeToml: string;
+	stamp: YaziProfileStamp;
+} {
+	const assetDir = options.assetDir ?? defaultAssetDir();
+	const themeToml = options.themeToml ?? renderYaziTheme();
+	const yaziToml = options.yaziToml ?? readFileSync(join(assetDir, "yazi.toml"), "utf8");
+	const keymapToml = options.keymapToml ?? renderYaziKeymap(options.yaPath);
+	return {
+		dir: options.profileDir ?? yaziProfileDir(),
+		assetDir,
+		yaziToml,
+		keymapToml,
+		themeToml,
+		stamp: {
+			yaziVersion: options.yaziVersion ?? yaziPin(),
+			clioVersion: options.clioVersion ?? readClioVersion(),
+			yaPath: options.yaPath,
+			assetSha256: hashYaziAssetTree(assetDir),
+			themeSha256: sha256(themeToml),
+		},
+	};
+}
+
+function readStamp(dir: string): YaziProfileStamp | null {
+	try {
+		const value = JSON.parse(readFileSync(join(dir, STAMP_FILE), "utf8")) as Partial<YaziProfileStamp>;
+		if (
+			typeof value.yaziVersion !== "string" ||
+			typeof value.clioVersion !== "string" ||
+			typeof value.yaPath !== "string" ||
+			typeof value.assetSha256 !== "string" ||
+			typeof value.themeSha256 !== "string"
+		) {
+			return null;
+		}
+		return value as YaziProfileStamp;
+	} catch {
+		return null;
+	}
+}
+
+function sameStamp(left: Readonly<YaziProfileStamp> | null, right: Readonly<YaziProfileStamp>): boolean {
+	return (
+		left !== null &&
+		left.yaziVersion === right.yaziVersion &&
+		left.clioVersion === right.clioVersion &&
+		left.yaPath === right.yaPath &&
+		left.assetSha256 === right.assetSha256 &&
+		left.themeSha256 === right.themeSha256
+	);
+}
+
+function profileFilesExist(dir: string): boolean {
+	return (
+		PROFILE_FILES.every((file) => statSync(join(dir, file), { throwIfNoEntry: false })?.isFile()) &&
+		PROFILE_PLUGIN_FILES.every(
+			(file) => statSync(join(dir, "plugins", "git.yazi", file), { throwIfNoEntry: false })?.isFile() === true,
+		)
+	);
+}
+
+/** Read whether the cached profile matches current inputs without creating or rewriting it. */
+export function inspectYaziProfile(options: YaziProfileOptions): YaziProfileInspection {
+	const inputs = expected(options);
+	const present = statSync(inputs.dir, { throwIfNoEntry: false })?.isDirectory() === true;
+	const current = present && profileFilesExist(inputs.dir) && sameStamp(readStamp(inputs.dir), inputs.stamp);
+	return {
+		dir: inputs.dir,
+		userConfigDir: userYaziConfigDir(),
+		state: current ? "current" : present ? "stale" : "missing",
+		stamp: inputs.stamp,
+	};
+}
+
+/** Inspect the profile against the `ya` path the shared resolution ladder currently chooses. */
+export function inspectCurrentYaziProfile(): YaziProfileInspection {
+	return inspectYaziProfile({ yaPath: resolveToolBinary("ya").binaryPath ?? "(unresolved)" });
+}
+
+/** One shared sentence for `tools status yazi` and the doctor profile row. */
+export function describeYaziProfile(inspection: Readonly<YaziProfileInspection>): string {
+	return `${inspection.dir} (${inspection.state}); user config ${inspection.userConfigDir} is separate and untouched`;
+}
+
+function parseGenerated(dir: string): boolean {
+	return ["yazi.toml", "keymap.toml", "theme.toml"].every((file) => {
+		try {
+			return parseTomlDocument(readFileSync(join(dir, file), "utf8")) !== null;
+		} catch {
+			return false;
+		}
+	});
+}
+
+const YAZI_CONFIG_ERROR_MARKERS = ["Failed to parse config", "Press <Enter> to continue with preset settings"];
+
+/** Ask the resolved Yazi binary to load the staged profile before it can become current. */
+function validatesWithYazi(dir: string, yaziPath: string): boolean {
+	const scratchHome = mkdtempSync(join(dirname(dir), ".yazi-validation-"));
+	try {
+		const result = spawnSync(yaziPath, ["--debug"], {
+			cwd: scratchHome,
+			env: {
+				...process.env,
+				HOME: scratchHome,
+				XDG_CACHE_HOME: join(scratchHome, "cache"),
+				XDG_CONFIG_HOME: join(scratchHome, "config"),
+				YAZI_CONFIG_HOME: dir,
+			},
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+		return (
+			result.error === undefined &&
+			result.status === 0 &&
+			YAZI_CONFIG_ERROR_MARKERS.every((marker) => !output.includes(marker))
+		);
+	} catch {
+		return false;
+	} finally {
+		rmSync(scratchHome, { recursive: true, force: true });
+	}
+}
+
+/**
+ * Materialize Clio's deterministic Yazi profile, replacing it only when its
+ * recorded inputs differ. No path outside `<cache>/yazi/` is read or written.
+ */
+export function ensureYaziProfile(options: EnsureYaziProfileOptions): YaziProfile | null {
+	let inputs: ReturnType<typeof expected>;
+	try {
+		inputs = expected({ ...options, profileDir: options.profileDir ?? yaziProfileDir(clioCacheDir()) });
+	} catch {
+		return null;
+	}
+	if (profileFilesExist(inputs.dir) && sameStamp(readStamp(inputs.dir), inputs.stamp)) {
+		return { dir: inputs.dir, stamp: inputs.stamp };
+	}
+
+	mkdirSync(dirname(inputs.dir), { recursive: true });
+	const staging = mkdtempSync(join(dirname(inputs.dir), ".profile-"));
+	try {
+		cpSync(join(inputs.assetDir, "init.lua"), join(staging, "init.lua"));
+		cpSync(join(inputs.assetDir, "plugins"), join(staging, "plugins"), { recursive: true });
+		writeFileSync(join(staging, "yazi.toml"), inputs.yaziToml);
+		writeFileSync(join(staging, "keymap.toml"), inputs.keymapToml);
+		writeFileSync(join(staging, "theme.toml"), inputs.themeToml);
+		writeFileSync(join(staging, STAMP_FILE), `${JSON.stringify(inputs.stamp, null, 2)}\n`);
+		if (!parseGenerated(staging) || !validatesWithYazi(staging, options.yaziPath)) {
+			rmSync(inputs.dir, { recursive: true, force: true });
+			return null;
+		}
+		rmSync(inputs.dir, { recursive: true, force: true });
+		renameSync(staging, inputs.dir);
+		return { dir: inputs.dir, stamp: inputs.stamp };
+	} catch {
+		rmSync(inputs.dir, { recursive: true, force: true });
+		return null;
+	} finally {
+		rmSync(staging, { recursive: true, force: true });
+	}
+}

package/src/domains/mux/yazi/session.ts

@@ -0,0 +1,228 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { clioCacheDir } from "../../../core/xdg.js";
+import { findPinnedTool } from "../../toolchain/registry.js";
+import { describeResolution, resolveToolBinary, toolStatus } from "../../toolchain/resolve.js";
+import type { MuxContract } from "../contract.js";
+import type { MuxPaneRef } from "../types.js";
+import { createYaziEventStream, YAZI_STREAM_POLL_MS, type YaziEvent, type YaziEventStream } from "./event-stream.js";
+import { ensureYaziProfile, type YaziProfile, yaziProfileDir } from "./profile.js";
+
+export type YaziSessionMode = "companion" | "chooser";
+export type YaziProfileMode = "managed" | "user";
+
+export interface YaziResolvedBinaries {
+	yaziPath: string | null;
+	yaPath: string | null;
+	missingYaziDetail: string;
+}
+
+export interface YaziChooserResult {
+	paths: ReadonlyArray<string>;
+	cwd: string;
+}
+
+export interface YaziSessionSnapshot {
+	mode: YaziSessionMode;
+	paneId: string;
+	paneCwd: string;
+	instanceId: string | null;
+	lastLineAt: number | null;
+	streamPath: string | null;
+	chooserPath: string | null;
+}
+
+export interface YaziSession {
+	readonly mode: YaziSessionMode;
+	readonly pane: Readonly<MuxPaneRef>;
+	readonly token: string | null;
+	readonly profile: Readonly<YaziProfile> | null;
+	snapshot(): Readonly<YaziSessionSnapshot>;
+	pushCwd(cwd: string): Promise<boolean>;
+	close(): Promise<void>;
+}
+
+export type YaziSessionOpenResult =
+	| { status: "opened"; session: YaziSession }
+	| { status: "missing-binary"; binary: "yazi" | "ya"; detail: string }
+	| { status: "profile-error"; reason: string }
+	| { status: "unavailable"; reason: string };
+
+export interface YaziSessionOptions {
+	mux: MuxContract;
+	mode: YaziSessionMode;
+	profileMode: YaziProfileMode;
+	cwd: string;
+	onEvent: (event: YaziEvent) => void;
+	onChooser: (result: YaziChooserResult) => void;
+	onStopped?: (reason: string) => void;
+	log?: (level: "debug" | "warning", message: string) => void;
+	cacheDir?: string;
+	sessionId?: string;
+	pickToken?: string;
+	pollMs?: number;
+	resolveBinaries?: () => YaziResolvedBinaries;
+	ensureProfile?: typeof ensureYaziProfile;
+	runYa?: (file: string, args: ReadonlyArray<string>, env: Readonly<NodeJS.ProcessEnv>) => Promise<boolean>;
+}
+
+export function resolveYaziBinaries(): YaziResolvedBinaries {
+	const entry = findPinnedTool("yazi");
+	const status = entry ? toolStatus(entry) : null;
+	return {
+		yaziPath: status?.resolution.binaryPath ?? null,
+		yaPath: resolveToolBinary("ya").binaryPath,
+		missingYaziDetail: status ? describeResolution(status) : "yazi is not in the pinned tool registry",
+	};
+}
+
+function runYa(file: string, args: ReadonlyArray<string>, env: Readonly<NodeJS.ProcessEnv>): Promise<boolean> {
+	return new Promise((resolve) => {
+		const child = spawn(file, args, { env: { ...env }, stdio: "ignore" });
+		child.once("error", () => resolve(false));
+		child.once("exit", (code) => resolve(code === 0));
+	});
+}
+
+function readOptional(path: string): string {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+/** Open one mux-hosted Yazi process and own its DDS or chooser-file transport. */
+export async function createYaziSession(options: YaziSessionOptions): Promise<YaziSessionOpenResult> {
+	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 sessionId = options.sessionId ?? randomUUID();
+	const sessionsDir = join(cacheDir, "yazi", "sessions");
+	mkdirSync(sessionsDir, { recursive: true });
+	const managedProfile =
+		options.profileMode === "managed"
+			? (options.ensureProfile ?? ensureYaziProfile)({
+					yaPath: binaries.yaPath as string,
+					yaziPath: binaries.yaziPath,
+					profileDir: yaziProfileDir(cacheDir),
+				})
+			: null;
+	if (options.profileMode === "managed" && !managedProfile) {
+		return { status: "profile-error", reason: "Clio could not generate a valid managed Yazi profile" };
+	}
+
+	const streamPath = join(sessionsDir, `${sessionId}.stream`);
+	const chooserPath = join(sessionsDir, `${sessionId}.chooser`);
+	const cwdPath = join(sessionsDir, `${sessionId}.cwd`);
+	const token = options.mode === "companion" ? (options.pickToken ?? randomUUID()) : null;
+	const env: Record<string, string> = {
+		...(managedProfile ? { YAZI_CONFIG_HOME: managedProfile.dir } : {}),
+		...(token ? { CLIO_YAZI_PICK_TOKEN: token } : {}),
+	};
+	let argv: ReadonlyArray<string>;
+	let stdoutPath: string | undefined;
+	if (options.mode === "companion") {
+		writeFileSync(streamPath, "");
+		argv = [binaries.yaziPath, "--local-events", "cd,clio-pick", "--remote-events", "clio-pick"];
+		stdoutPath = streamPath;
+	} else {
+		writeFileSync(chooserPath, "");
+		writeFileSync(cwdPath, "");
+		argv = [binaries.yaziPath, options.cwd, "--chooser-file", chooserPath, "--cwd-file", cwdPath];
+	}
+
+	const pane = await options.mux.openUtilityPane({
+		argv,
+		cwd: options.cwd,
+		label: "yazi",
+		...(Object.keys(env).length > 0 ? { env } : {}),
+		...(stdoutPath ? { stdoutPath } : {}),
+	});
+	if (!pane) return { status: "unavailable", reason: "pane host refused to open yazi" };
+
+	let paneCwd = options.cwd;
+	let instanceId: string | null = null;
+	let stream: YaziEventStream | null = null;
+	let chooserTimer: NodeJS.Timeout | null = null;
+	let stopped = false;
+	const alive = (): boolean => options.mux.list().some((record) => record.ref.paneId === pane.paneId);
+	const stop = (reason: string): void => {
+		if (stopped) return;
+		stopped = true;
+		if (chooserTimer) clearInterval(chooserTimer);
+		chooserTimer = null;
+		options.onStopped?.(reason);
+	};
+
+	if (options.mode === "companion") {
+		stream = createYaziEventStream({
+			path: streamPath,
+			isAlive: alive,
+			...(options.pollMs !== undefined ? { pollMs: options.pollMs } : {}),
+			...(options.log ? { log: options.log } : {}),
+			onEvent: (event) => {
+				if (event.kind === "cd") {
+					paneCwd = event.cwd;
+					instanceId = event.sender;
+				}
+				options.onEvent(event);
+			},
+		});
+		void stream.done.then((reason) => stop(reason));
+	} else {
+		const pollChooser = (): void => {
+			if (stopped || alive()) return;
+			const raw = readOptional(chooserPath);
+			const cwd = readOptional(cwdPath).trim() || paneCwd;
+			paneCwd = cwd;
+			const paths = raw.length === 0 ? [] : raw.split("\n").filter((path) => path.length > 0);
+			options.onChooser({ paths, cwd });
+			stop("pane-gone");
+		};
+		chooserTimer = setInterval(pollChooser, options.pollMs ?? YAZI_STREAM_POLL_MS);
+		chooserTimer.unref();
+	}
+
+	const session: YaziSession = {
+		mode: options.mode,
+		pane,
+		token,
+		profile: managedProfile,
+		snapshot: () => ({
+			mode: options.mode,
+			paneId: pane.paneId,
+			paneCwd,
+			instanceId,
+			lastLineAt: stream?.stats().lastLineAt ?? null,
+			streamPath: options.mode === "companion" ? streamPath : null,
+			chooserPath: options.mode === "chooser" ? chooserPath : null,
+		}),
+		async pushCwd(cwd: string): Promise<boolean> {
+			if (!instanceId || !binaries.yaPath) return false;
+			const pushed = await (options.runYa ?? runYa)(binaries.yaPath, ["emit-to", instanceId, "cd", cwd], {
+				...process.env,
+				...(managedProfile ? { YAZI_CONFIG_HOME: managedProfile.dir } : {}),
+			});
+			return pushed;
+		},
+		async close(): Promise<void> {
+			stream?.stop();
+			stop("stopped");
+			await options.mux.closePane(pane.paneId);
+		},
+	};
+	return { status: "opened", session };
+}