cyber-mux 0.1.0 → 0.3.0

package/dist/backend-DnrbmL6N.mjs

@@ -0,0 +1,2025 @@
+import { m as withReason, p as nodeExec, s as normalizeWorktreePath } from "./worktree-CoQdRgv1.mjs";
+import { resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/env-fallback.ts
+/**
+* The env-prefix fallback — the one compensation for a route that could not set env at birth.
+*
+* env is native at every tier on both backends EXCEPT herdr's worktree `create`/`open`, which take
+* no env parameter (0.7.4 answers `--env` with `unknown option`). A route that hit that wall carries
+* env the only way left: as an `env KEY=VALUE` prefix on the command the pane runs. It is a LAST
+* resort — the values land in `ps` output and the pane's shell history — and it only works when there
+* IS a command to ride; with none, the honest outcome is to warn, never to drop silently.
+*
+* This lives in one module, called by both routes that can lose env (the CLI worktree verbs and the
+* template walk's root pane), so the rule cannot be wired on one and forgotten on the other. Only a
+* route that lost env may call it: prefixing over a natively-set env would push the values into `ps`
+* and shell history on every route, the exact cost the prefix exists to pay only when it must.
+*/
+/**
+* Single-quote a value for a shell command line. Everything is literal inside single quotes, so the
+* only escape needed is for a single quote itself: end the quoting, emit an escaped `'`, reopen.
+* Without this a value carrying a space or a quote would split into extra words, or unbalance the
+* line outright.
+*/
+function shellQuote(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** `env K=V …` with a trailing space, ready to prepend to a command line. Values are shell-quoted. */
+function envPrefix(env) {
+	return `env ${Object.entries(env).map(([key, value]) => `${key}=${shellQuote(value)}`).join(" ")} `;
+}
+/**
+* Given the env a route could not carry and the command (if any) that would run in the opened pane,
+* decide how env rides in. With a command, env is prefixed onto it and the pane carries the value;
+* with none, env is dropped and the caller warns. No env (or an empty map) is `carried` unchanged, so
+* a caller on the losing route can call this unconditionally and get the right command back.
+*/
+function envFallback(env, command) {
+	if (env === void 0 || Object.keys(env).length === 0) return {
+		kind: "carried",
+		command
+	};
+	if (command === void 0) return {
+		kind: "dropped",
+		variables: Object.keys(env)
+	};
+	return {
+		kind: "carried",
+		command: `${envPrefix(env)}${command}`
+	};
+}
+//#endregion
+//#region src/mux.herdr.ts
+/**
+* herdr backend — detected via `$HERDR_ENV`. herdr (https://herdr.dev) is an agent-aware terminal
+* multiplexer that also reports real busy-state (working / idle / blocked / done); this adapter
+* only drives its pane lifecycle, not the state feed. Talks to herdr's own CLI (`herdr pane ...`)
+* rather than its Unix-socket API, so it composes with this codebase's synchronous `Exec`
+* convention exactly like the tmux adapter — no new client/transport needed.
+*
+* The pane lifecycle (split/run/read/close) is verified against a live herdr binary; `pane split`
+* returns a JSON `pane_info` envelope whose id is extracted in `parsePaneId`.
+*/
+const herdrMuxAdapter = {
+	name: "herdr",
+	canSizeSplits: true,
+	open(exec, opts) {
+		const at = opts.at ?? "tab";
+		const label = opts.label ? ["--label", opts.label] : [];
+		const env = envFlags(opts.env);
+		let opened;
+		if (at === "workspace") {
+			const out = exec("herdr", [
+				"workspace",
+				"create",
+				"--cwd",
+				opts.cwd,
+				...label,
+				...env,
+				"--no-focus"
+			]);
+			if (!out) throw new Error(withReason(exec, "herdr workspace create failed"));
+			opened = parseRootPaneId(out, "herdr workspace create");
+		} else if (at === "tab") {
+			const out = exec("herdr", [
+				"tab",
+				"create",
+				...opts.within ? ["--workspace", opts.within] : [],
+				"--cwd",
+				opts.cwd,
+				...label,
+				...env,
+				"--no-focus"
+			]);
+			if (!out) throw new Error(withReason(exec, "herdr tab create failed"));
+			opened = parseRootPaneId(out, "herdr tab create");
+		} else {
+			const direction = at === "pane:down" ? "down" : "right";
+			const from = opts.from ? [opts.from.id] : ["--current"];
+			const size = opts.ratio != null ? ["--ratio", String(opts.ratio)] : [];
+			const out = exec("herdr", [
+				"pane",
+				"split",
+				...from,
+				"--direction",
+				direction,
+				"--cwd",
+				opts.cwd,
+				...size,
+				...env
+			]);
+			if (!out) throw new Error(withReason(exec, "herdr pane split failed"));
+			opened = parsePaneId(out);
+			if (opts.label) herdrMuxAdapter.rename(exec, opened, "pane", opts.label);
+		}
+		if (opts.launch) herdrMuxAdapter.submit(exec, opened, opts.launch);
+		return opened;
+	},
+	rename(exec, target, tier, name) {
+		exec("herdr", [
+			tier,
+			"rename",
+			target.id,
+			name
+		]);
+	},
+	group() {},
+	worktree: herdrWorktreeCapability(),
+	sendText(exec, target, text) {
+		exec("herdr", [
+			"pane",
+			"send-text",
+			target.id,
+			text
+		]);
+	},
+	sendKeys(exec, target, keys) {
+		exec("herdr", [
+			"pane",
+			"send-keys",
+			target.id,
+			...keys
+		]);
+	},
+	submit(exec, target, text) {
+		if (!text) {
+			exec("herdr", [
+				"pane",
+				"send-keys",
+				target.id,
+				"Enter"
+			]);
+			return;
+		}
+		exec("herdr", [
+			"pane",
+			"run",
+			target.id,
+			text
+		]);
+	},
+	read(exec, target, opts) {
+		const args = [
+			"pane",
+			"read",
+			target.id,
+			"--source",
+			"visible"
+		];
+		if (opts?.lines != null) args.push("--lines", String(opts.lines));
+		return exec("herdr", args) ?? "";
+	},
+	focus(exec, target) {
+		const { workspaceId, tabId } = parsePaneLocation$1(exec("herdr", [
+			"pane",
+			"get",
+			target.id
+		]), target.id);
+		exec("herdr", [
+			"workspace",
+			"focus",
+			workspaceId
+		]);
+		exec("herdr", [
+			"tab",
+			"focus",
+			tabId
+		]);
+	},
+	teardown(exec, target) {
+		exec("herdr", [
+			"pane",
+			"close",
+			target.id
+		]);
+	},
+	paneExists(exec, target) {
+		return exec("herdr", [
+			"pane",
+			"read",
+			target.id,
+			"--source",
+			"visible"
+		]) !== null;
+	},
+	isPaneFocused(exec, target) {
+		const out = exec("herdr", [
+			"pane",
+			"get",
+			target.id
+		]);
+		if (out == null) return void 0;
+		try {
+			const focused = JSON.parse(out)?.result?.pane?.focused;
+			return typeof focused === "boolean" ? focused : void 0;
+		} catch {
+			return;
+		}
+	},
+	listPanes(exec) {
+		const out = exec("herdr", ["pane", "list"]);
+		if (!out) return [];
+		let panes;
+		try {
+			panes = JSON.parse(out)?.result?.panes;
+		} catch {
+			return [];
+		}
+		if (!Array.isArray(panes)) return [];
+		return panes.filter((p) => typeof p?.pane_id === "string").map((p) => {
+			const harness = p.agent || void 0;
+			const label = p.label || void 0;
+			return {
+				id: p.pane_id,
+				mux: "herdr",
+				...harness !== void 0 ? { harness } : {},
+				...p.cwd !== void 0 ? { cwd: p.cwd } : {},
+				...label !== void 0 ? { label } : {}
+			};
+		});
+	},
+	regions: {
+		describeRegion(exec, target) {
+			return herdrRegionPanes(exec, target.id, herdrPaneDetails(exec));
+		},
+		/**
+		* herdr HAS a workspace tier, so the workspace is a fact the backend holds rather than one
+		* cyber-mux has to reconstruct: the caller's pane names its `workspace_id`, `tab list --workspace`
+		* enumerates that workspace's tabs, and `pane list --workspace` hands back every pane already
+		* stamped with the tab it sits in. No grouping tag is read here and none is written — the tier IS
+		* the group, which is exactly why `open` ignores `workspaceGroup` on this backend.
+		*
+		* The one indirection: geometry is per-PANE (`pane layout --pane`), never per-tab, so each tab's
+		* rects are fetched through any one pane that sits in it. That is safe and race-free, and both
+		* halves were established against 0.7.4: `pane layout` reports live geometry for an UNFOCUSED tab
+		* in a DIFFERENT workspace, so nothing has to be focused first and nothing moves while this runs.
+		*
+		* herdr's own native per-tab layout export would be the obvious road — it takes a `tab_id` — but
+		* `layout` is NOT a CLI verb in 0.7.4; it is socket-API-only, and this adapter speaks the CLI by
+		* design (so it composes with the synchronous `Exec` seam). The road is closed, hence the pane
+		* indirection.
+		*/
+		describeWorkspace(exec, target) {
+			const { workspaceId } = parsePaneRecord(exec("herdr", [
+				"pane",
+				"get",
+				target.id
+			]));
+			if (!workspaceId) throw new Error(withReason(exec, `herdr could not resolve the workspace around pane ${target.id}`));
+			const out = exec("herdr", [
+				"tab",
+				"list",
+				"--workspace",
+				workspaceId
+			]);
+			if (!out) throw new Error(withReason(exec, `herdr could not enumerate the tabs of workspace ${workspaceId}`));
+			let reported;
+			try {
+				reported = JSON.parse(out)?.result?.tabs;
+			} catch {
+				throw new Error(`herdr tab list returned unparseable output: ${out.slice(0, 200)}`);
+			}
+			if (!Array.isArray(reported) || reported.length === 0) throw new Error(`herdr reported no tabs in workspace ${workspaceId}: ${out.slice(0, 200)}`);
+			const details = herdrPaneDetails(exec, workspaceId);
+			const tabs = [];
+			for (const reportedTab of reported) {
+				if (typeof reportedTab?.tab_id !== "string") continue;
+				const tabId = reportedTab.tab_id;
+				const anchor = [...details].find(([, detail]) => detail.tab === tabId)?.[0];
+				if (!anchor) throw new Error(`herdr reported no panes in tab ${tabId} of workspace ${workspaceId}`);
+				const tab = {
+					id: tabId,
+					panes: herdrRegionPanes(exec, anchor, details)
+				};
+				if (typeof reportedTab.label === "string" && reportedTab.label !== "") tab.label = reportedTab.label;
+				tabs.push(tab);
+			}
+			if (tabs.length === 0) throw new Error(`herdr reported no usable tabs in workspace ${workspaceId}: ${out.slice(0, 200)}`);
+			return tabs;
+		}
+	}
+};
+/**
+* The rects of the region `paneId` sits in, joined with the cwd/label half.
+*
+* Two sources, because herdr splits the answer across two verbs: `pane layout` reports the region's
+* rects (`layout.panes[].rect`) but carries no cwd and no label, while `pane list` carries both and
+* no geometry. Neither alone can build a template — hence `details` is passed IN, so a caller reading
+* many tabs pays for that list once rather than once per tab.
+*
+* `layout.splits[]` is deliberately ignored even though it reports `direction` and `ratio` outright.
+* It is FLAT — `[{id:"split_0_root",...},{id:"split_1_0",...}]` — so the tree is recoverable only by
+* parsing the parent out of that id string, a convention herdr's CLI help never documents and could
+* respell without warning. The rects say the same thing in a fact herdr does promise, so the
+* derivation runs off those; see `RegionInspector.describeRegion` in `mux.ts`.
+*/
+function herdrRegionPanes(exec, paneId, details) {
+	const out = exec("herdr", [
+		"pane",
+		"layout",
+		"--pane",
+		paneId
+	]);
+	if (!out) throw new Error(withReason(exec, `herdr could not describe the region around pane ${paneId}`));
+	let reported;
+	try {
+		reported = JSON.parse(out)?.result?.layout?.panes;
+	} catch {
+		throw new Error(`herdr pane layout returned unparseable output: ${out.slice(0, 200)}`);
+	}
+	if (!Array.isArray(reported) || reported.length === 0) throw new Error(`herdr pane layout reported no panes for ${paneId}: ${out.slice(0, 200)}`);
+	return reported.filter((p) => typeof p?.pane_id === "string").map((p) => {
+		const detail = details.get(p.pane_id);
+		const pane = {
+			id: p.pane_id,
+			rect: {
+				x: p.rect?.["x"] ?? 0,
+				y: p.rect?.["y"] ?? 0,
+				width: p.rect?.["width"] ?? 0,
+				height: p.rect?.["height"] ?? 0
+			}
+		};
+		if (detail?.cwd) pane.cwd = detail.cwd;
+		if (detail?.label) pane.label = detail.label;
+		return pane;
+	});
+}
+/**
+* Each pane's cwd, label and tab, keyed by pane id — the half `pane layout` does not report.
+*
+* `workspace` scopes the list to one workspace when the caller has one to scope by; omitting it lists
+* every pane herdr can see, which is what a single-region read wants (it keys by pane id and never
+* cares which workspace a pane came from).
+*/
+function herdrPaneDetails(exec, workspace) {
+	const details = /* @__PURE__ */ new Map();
+	const out = exec("herdr", [
+		"pane",
+		"list",
+		...workspace ? ["--workspace", workspace] : []
+	]);
+	if (!out) return details;
+	let panes;
+	try {
+		panes = JSON.parse(out)?.result?.panes;
+	} catch {
+		return details;
+	}
+	if (!Array.isArray(panes)) return details;
+	for (const pane of panes) {
+		if (typeof pane?.pane_id !== "string") continue;
+		details.set(pane.pane_id, {
+			cwd: pane.cwd,
+			label: pane.label,
+			tab: pane.tab_id
+		});
+	}
+	return details;
+}
+/**
+* herdr's repeatable `--env KEY=VALUE` — spelled the same way by exactly three verbs: `pane split`,
+* `workspace create` and `tab create`, each backed by a native `env` Record in the socket schema
+* (protocol 16).
+*
+* `worktree create`/`worktree open` are deliberately NOT in that list: their params are
+* `[base, branch, cwd, focus, label, path, workspace_id]` and
+* `[branch, cwd, focus, label, path, workspace_id]` — no `env` — and 0.7.4 rejects the flag with
+* `unknown option: --env`. A caller needing env on that route uses the command-prefix fallback.
+*/
+function envFlags(env) {
+	return env ? Object.entries(env).flatMap(([k, v]) => ["--env", `${k}=${v}`]) : [];
+}
+/**
+* Launch a command in a worktree's root pane, carrying env the worktree verb could not set at birth.
+* The prefix-or-warn rule is the seam's (`env-fallback.ts`); this is the one route that invokes it,
+* because it is the one route that loses env. With a command, env rides in as a prefix; with none and
+* env asked for, it warns to stderr (stdout stays machine-readable) rather than dropping in silence.
+*/
+function carryLaunch(exec, target, env, launch) {
+	const fallback = envFallback(env, launch);
+	if (fallback.kind === "dropped") {
+		process.stderr.write(`env (${fallback.variables.join(", ")}) could not be set on this worktree's workspace and no command was given to carry it — herdr worktree create/open take no env parameter
+`);
+		return;
+	}
+	if (fallback.command !== void 0) herdrMuxAdapter.submit(exec, target, fallback.command);
+}
+/**
+* `herdr pane split` emits a JSON envelope, not a bare id:
+* `{"id":"cli:pane:split","result":{"pane":{"pane_id":"w3:pB", ...},"type":"pane_info"}}`.
+* The pane id herdr's other `pane` subcommands accept lives at `.result.pane.pane_id`. Extract it —
+* passing the whole blob downstream lands it in a filename and blows the path length limit.
+*/
+function parsePaneId(out) {
+	return parseOpenedPane(out, "herdr pane split", "pane");
+}
+/**
+* `herdr pane get <id>` emits `{"result":{"pane":{"workspace_id":...,"tab_id":...,...}}}`, or an
+* error envelope when the id no longer names a live pane. Every unresolvable shape — `out` is null
+* (an Exec failure), the JSON does not parse, or a field is missing/empty/not a string — folds to the
+* field simply being absent, so each caller states its OWN failure rather than inheriting one
+* phrased for somebody else's verb.
+*/
+function parsePaneRecord(out) {
+	if (out == null) return {};
+	try {
+		const pane = JSON.parse(out)?.result?.pane;
+		return {
+			workspaceId: nonEmpty(pane?.workspace_id),
+			tabId: nonEmpty(pane?.tab_id)
+		};
+	} catch {
+		return {};
+	}
+}
+function nonEmpty(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+/**
+* The pane's workspace and tab, or a throw — so `focus` never issues a workspace/tab switch against a
+* pane it couldn't actually resolve.
+*/
+function parsePaneLocation$1(out, id) {
+	const { workspaceId, tabId } = parsePaneRecord(out);
+	if (!workspaceId || !tabId) throw new Error(`peer's pane ${id} could not be resolved to beam to`);
+	return {
+		workspaceId,
+		tabId
+	};
+}
+/**
+* herdr binds a git worktree to a workspace as a first-class record, and that binding is what its UI
+* groups a repo's checkouts by. Only `worktree create`/`worktree open` produce it: `git worktree add`
+* followed by `workspace create --cwd <checkout>` yields a workspace herdr does not know is a
+* worktree at all, left out of the group. Hence this capability — see `WorktreeWorkspaceCapability`
+* for what it deliberately does not own.
+*
+* Every call pins the source repo with `--cwd <primaryRoot>` rather than relying on the caller's
+* ambient process cwd (matching how the git adapter always passes `-C <primaryRoot>`), and opens
+* with `--no-focus` so spawning never steals the caller's attention.
+*/
+function herdrWorktreeCapability() {
+	return {
+		createInWorkspace(exec, opts) {
+			const args = [
+				"worktree",
+				"create",
+				"--cwd",
+				opts.primaryRoot,
+				"--branch",
+				opts.branch,
+				"--path",
+				opts.path
+			];
+			if (opts.base) args.push("--base", opts.base);
+			if (opts.label) args.push("--label", opts.label);
+			args.push("--no-focus");
+			const out = exec("herdr", args);
+			if (!out) throw new Error(withReason(exec, "herdr worktree create failed"));
+			const created = parseWorktreeWorkspace(out, "herdr worktree create");
+			carryLaunch(exec, created.target, opts.env, opts.launch);
+			return created;
+		},
+		openInWorkspace(exec, opts) {
+			const args = [
+				"worktree",
+				"open",
+				"--cwd",
+				opts.primaryRoot,
+				"--path",
+				opts.path
+			];
+			if (opts.label) args.push("--label", opts.label);
+			args.push("--no-focus");
+			const out = exec("herdr", args);
+			if (!out) throw new Error(withReason(exec, "herdr worktree open failed"));
+			const opened = parseWorktreeWorkspace(out, "herdr worktree open");
+			carryLaunch(exec, opened.target, opts.env, opts.launch);
+			return opened;
+		},
+		bindings(exec, opts) {
+			return parseWorktreeBindings(exec("herdr", [
+				"worktree",
+				"list",
+				"--cwd",
+				opts.primaryRoot
+			]));
+		},
+		releaseWorkspace(exec, workspace) {
+			exec("herdr", [
+				"workspace",
+				"close",
+				workspace
+			]);
+		}
+	};
+}
+/**
+* `herdr workspace create` and `herdr tab create` both emit their new root pane at
+* `.result.root_pane.pane_id` (a different path than `pane split`'s `.result.pane.pane_id`).
+* `label` names the command in error messages (e.g. "herdr workspace create").
+*/
+function parseRootPaneId(out, label) {
+	return parseOpenedPane(out, label, "root_pane");
+}
+/**
+* Every pane herdr emits carries its own `workspace_id` alongside its `pane_id`, on EVERY route —
+* `workspace create` (which reports the workspace it just made), `tab create` (the workspace the tab
+* was created in), and `pane split` (the workspace the split landed in, i.e. the caller's). Verified
+* against herdr 0.7.4. That is why the workspace costs no extra call: it rides in on the same output
+* the pane id is already read from, so probing for it separately would buy nothing and cost a round
+* trip per open.
+*
+* The pane id is required — a route that cannot name its pane has failed. The workspace is NOT: it
+* is read opportunistically and left absent when missing rather than throwing, so a herdr build that
+* stops emitting it degrades to "cannot say" instead of breaking `open` outright. Absent is a
+* meaning this seam already has (`OpenedPane.workspace`); a hard failure here would be inventing a
+* new one for a field no caller is required to use.
+*/
+function parseOpenedPane(out, label, key) {
+	let pane;
+	try {
+		pane = JSON.parse(out)?.result?.[key];
+	} catch {
+		throw new Error(`${label} returned unparseable output: ${out.slice(0, 200)}`);
+	}
+	const paneId = pane?.pane_id;
+	if (typeof paneId !== "string" || paneId === "") throw new Error(`${label} output had no result.${key}.pane_id: ${out.slice(0, 200)}`);
+	const tab = pane?.tab_id;
+	if (typeof tab !== "string" || tab === "") throw new Error(`${label} output had no result.${key}.tab_id: ${out.slice(0, 200)}`);
+	const workspace = pane?.workspace_id;
+	return typeof workspace === "string" && workspace !== "" ? {
+		id: paneId,
+		tab,
+		workspace
+	} : {
+		id: paneId,
+		tab
+	};
+}
+/**
+* `herdr worktree create` and `herdr worktree open` emit the same envelope: the root pane at
+* `.result.root_pane.pane_id` (as `workspace create` does), the checkout at
+* `.result.worktree.{path,branch}`, and the bound workspace at `.result.workspace.workspace_id`.
+* That workspace id IS the binding — the whole reason to route through these instead of plain git.
+* `label` names the command in error messages (e.g. "herdr worktree create").
+*
+* The root pane is read through `parseOpenedPane`, NOT re-parsed here: `root_pane` is the same record
+* `workspace create` emits, so it carries the same `tab_id`, and one spelling is what keeps the two
+* routes from disagreeing about a field both report. That tab is the region's root tab — what lets a
+* caller handed this workspace group or rename it without reaching for the pane id, which would be
+* green on tmux and silently broken on herdr.
+*/
+function parseWorktreeWorkspace(out, label) {
+	let parsed;
+	try {
+		parsed = JSON.parse(out);
+	} catch {
+		throw new Error(`${label} returned unparseable output: ${out.slice(0, 200)}`);
+	}
+	const result = parsed?.result;
+	const target = parseOpenedPane(out, label, "root_pane");
+	const workspace = result?.workspace?.workspace_id;
+	const path = result?.worktree?.path;
+	const branch = result?.worktree?.branch;
+	if (typeof path !== "string" || path === "" || typeof branch !== "string" || branch === "") throw new Error(`${label} output had no result.worktree.{path,branch}: ${out.slice(0, 200)}`);
+	if (typeof workspace !== "string" || workspace === "") throw new Error(`${label} output had no result.workspace.workspace_id: ${out.slice(0, 200)}`);
+	return {
+		target,
+		worktree: {
+			root: resolve(path),
+			branch
+		},
+		workspace
+	};
+}
+/**
+* `herdr worktree list` reports every worktree of the repo, each carrying `open_workspace_id` ONLY
+* while a workspace is currently open on it. Everything else it reports (branch, linked, prunable)
+* is herdr re-reading git — deliberately ignored here; git answers those for every backend.
+* Defensive like `listPanes`: a query that cannot be read reports nothing rather than throwing.
+*/
+function parseWorktreeBindings(out) {
+	const bindings = /* @__PURE__ */ new Map();
+	if (!out) return bindings;
+	let parsed;
+	try {
+		parsed = JSON.parse(out);
+	} catch {
+		return bindings;
+	}
+	const worktrees = parsed?.result?.worktrees ?? [];
+	if (!Array.isArray(worktrees)) return bindings;
+	for (const entry of worktrees) {
+		const path = entry?.path;
+		const workspace = entry?.open_workspace_id;
+		if (typeof path === "string" && path !== "" && typeof workspace === "string" && workspace !== "") bindings.set(normalizeWorktreePath(path), workspace);
+	}
+	return bindings;
+}
+//#endregion
+//#region src/mux.tmux.ts
+/**
+* The tmux window user option `MuxOpenOptions.workspaceGroup` is stored in. A user option (the
+* `@` prefix) is tmux's own mechanism for a value it stores but never interprets, so tmux carries
+* the tag without cyber-mux teaching it anything: it survives a window rename, and `list-windows`
+* both reads it back (`#{@cm_ws}`) and filters on it server-side (`-f '#{==:#{@cm_ws},<id>}'`).
+*
+* Named here rather than spelled at each use so the write side and every read side cannot drift.
+* Server-lifetime, like every window: it dies with the tmux server, along with the windows it tags.
+*/
+const TMUX_WORKSPACE_GROUP_OPTION = "@cm_ws";
+/**
+* The tmux window user option a grouped window's OWN name is stored in — the name the caller gave the
+* tab, beside the group id, because tmux's single `window_name` field no longer holds it.
+*
+* tmux has ONE name field per space. A caller that composes a display name out of a tab's name
+* (`pool - editor`) has destroyed `editor`, and there is no sound way back: splitting on the separator
+* is ambiguous (`acme - beta - main` reads two legal ways), and reading the display name verbatim
+* re-prefixes it on every round trip (`pool - pool - editor`). So the original is stored here and read
+* back from here — the same rule the group id follows, one tier down. The display name is a human's to
+* read; this is what a machine reads.
+*
+* A user option (the `@` prefix) for `TMUX_WORKSPACE_GROUP_OPTION`'s reasons exactly: tmux stores it
+* without interpreting it, it survives a window rename, and `list-windows` reads it back
+* (`#{@cm_tab}`). Named here rather than spelled at each use so the write side and every read side
+* cannot drift.
+*/
+const TMUX_TAB_NAME_OPTION = "@cm_tab";
+/** tmux backend — detected via `$TMUX`. */
+const tmuxMuxAdapter = {
+	name: "tmux",
+	canSizeSplits: true,
+	open(exec, opts) {
+		const at = opts.at ?? "tab";
+		const window = at === "workspace" || at === "tab";
+		const env = opts.env ? Object.entries(opts.env).flatMap(([k, v]) => ["-e", `${k}=${v}`]) : [];
+		const group = window && opts.workspaceGroup != null;
+		const format = "#{pane_id}	#{window_id}";
+		let args;
+		if (window) args = [
+			"new-window",
+			"-d",
+			...env,
+			"-c",
+			opts.cwd,
+			"-P",
+			"-F",
+			format
+		];
+		else {
+			const from = opts.from ? ["-t", opts.from.id] : [];
+			const size = opts.ratio != null ? ["-l", toTmuxSize(opts.ratio)] : [];
+			args = [
+				"split-window",
+				at === "pane:down" ? "-v" : "-h",
+				...from,
+				...size,
+				...env,
+				"-c",
+				opts.cwd,
+				"-P",
+				"-F",
+				format
+			];
+		}
+		if (window && opts.label) args.splice(1, 0, "-n", opts.label);
+		const out = exec("tmux", args);
+		if (!out) throw new Error(withReason(exec, `tmux ${args[0]} failed`));
+		const [pane, windowId] = splitOpenReport(out, args[0]);
+		const target = {
+			id: pane,
+			tab: windowId
+		};
+		if (group && windowId) tmuxMuxAdapter.group(exec, { id: windowId }, opts.workspaceGroup);
+		if (!window && opts.label) tmuxMuxAdapter.rename(exec, target, "pane", opts.label);
+		if (opts.launch) tmuxMuxAdapter.submit(exec, target, opts.launch);
+		return target;
+	},
+	rename(exec, target, tier, name) {
+		if (tier === "tab") {
+			exec("tmux", [
+				"rename-window",
+				"-t",
+				target.id,
+				name
+			]);
+			return;
+		}
+		exec("tmux", [
+			"select-pane",
+			"-t",
+			target.id,
+			"-T",
+			name
+		]);
+	},
+	group(exec, target, group, name) {
+		exec("tmux", [
+			"set-option",
+			"-w",
+			"-t",
+			target.id,
+			TMUX_WORKSPACE_GROUP_OPTION,
+			group
+		]);
+		if (name !== void 0) exec("tmux", [
+			"set-option",
+			"-w",
+			"-t",
+			target.id,
+			TMUX_TAB_NAME_OPTION,
+			name
+		]);
+	},
+	sendText(exec, target, text) {
+		exec("tmux", [
+			"send-keys",
+			"-t",
+			target.id,
+			"-l",
+			text
+		]);
+	},
+	sendKeys(exec, target, keys) {
+		exec("tmux", [
+			"send-keys",
+			"-t",
+			target.id,
+			...keys.map(toTmuxKey)
+		]);
+	},
+	submit(exec, target, text) {
+		if (!text) {
+			exec("tmux", [
+				"send-keys",
+				"-t",
+				target.id,
+				"Enter"
+			]);
+			return;
+		}
+		tmuxMuxAdapter.sendText(exec, target, text);
+		exec("tmux", [
+			"send-keys",
+			"-t",
+			target.id,
+			"Enter"
+		]);
+	},
+	read(exec, target, opts) {
+		const args = [
+			"capture-pane",
+			"-p",
+			"-t",
+			target.id
+		];
+		if (opts?.lines != null) args.push("-S", `-${opts.lines}`);
+		return exec("tmux", args) ?? "";
+	},
+	focus(exec, target) {
+		const { sessionName, windowId } = parsePaneLocation(exec("tmux", [
+			"list-panes",
+			"-a",
+			"-F",
+			"#{pane_id} #{session_name} #{window_id}"
+		]), target.id);
+		exec("tmux", [
+			"switch-client",
+			"-t",
+			sessionName
+		]);
+		exec("tmux", [
+			"select-window",
+			"-t",
+			windowId
+		]);
+		exec("tmux", [
+			"select-pane",
+			"-t",
+			target.id
+		]);
+	},
+	teardown(exec, target) {
+		exec("tmux", [
+			"kill-pane",
+			"-t",
+			target.id
+		]);
+	},
+	paneExists(exec, target) {
+		if (exec("tmux", [
+			"has-session",
+			"-t",
+			target.id
+		]) !== null) return true;
+		return (exec("tmux", [
+			"list-panes",
+			"-a",
+			"-F",
+			"#{pane_id}"
+		]) ?? "").split("\n").includes(target.id);
+	},
+	isPaneFocused(exec, target) {
+		const out = exec("tmux", [
+			"list-panes",
+			"-a",
+			"-F",
+			"#{pane_id} #{pane_active} #{window_active} #{session_attached}"
+		]);
+		if (!out) return void 0;
+		const line = out.split("\n").find((l) => l.split(" ")[0] === target.id);
+		if (!line) return void 0;
+		const [, paneActive, windowActive, sessionAttached] = line.split(" ");
+		return paneActive === "1" && windowActive === "1" && sessionAttached !== "0" && sessionAttached !== void 0;
+	},
+	/**
+	* Tab-separated, not space — the same rule `describeTmuxRegion` follows, and for the same reason:
+	* `pane_current_path` and `pane_title` can both contain spaces. The old space-separated format
+	* recovered the cwd by rejoining everything after the command, which works only while the cwd is
+	* the LAST field. A label is a human's and may hold anything, so appending one to that format would
+	* make both fields unrecoverable — `my worker` and `/repo/my dir` cannot be told apart by a space.
+	* A tab can appear in neither id nor command, and the two free-text fields are separated by one.
+	*/
+	listPanes(exec) {
+		const out = exec("tmux", [
+			"list-panes",
+			"-a",
+			"-F",
+			"#{pane_id}	#{pane_current_command}	#{pane_current_path}	#{pane_title}	#{host}"
+		]);
+		if (!out) return [];
+		return out.split("\n").filter(Boolean).map((line) => {
+			const [id, , cwd, title, host] = line.split("	");
+			const pane = {
+				id: id ?? "",
+				mux: "tmux"
+			};
+			if (cwd) pane.cwd = cwd;
+			const label = paneLabel(title, host);
+			if (label) pane.label = label;
+			return pane;
+		}).filter((p) => p.id !== "");
+	},
+	regions: {
+		describeRegion(exec, target) {
+			return describeTmuxRegion(exec, target.id);
+		},
+		/**
+		* tmux has NO workspace tier — `workspace` and `tab` both collapse onto a Window — so a workspace
+		* is not a fact this backend holds. What it holds is the grouping TAG the walk wrote
+		* (`MuxOpenOptions.workspaceGroup`, stored in a window user option), so the read here is
+		* literally *"which windows carry this group id"*.
+		*
+		* The tag, never the label. `list-windows -a` spans SESSIONS, so a bare name match would
+		* over-collect a same-named window from another session, and taking the workspace off a
+		* `<workspace> - <tab>` label is unsound in the first place (`acme - beta - main` splits two ways,
+		* both legal). `-f '#{==:#{@cm_ws},<id>}'` keys on what actually identifies the group, filtered
+		* server-side — the tag survives a window rename, which a name-encoded grouping does not.
+		*
+		* A window with NO tag is a workspace of ONE: the honest answer for a window nobody grouped, and
+		* it costs no further call — the caller's own window is the whole workspace.
+		*/
+		describeWorkspace(exec, target) {
+			const out = exec("tmux", [
+				"display-message",
+				"-p",
+				"-t",
+				target.id,
+				`#{window_id}\t#{${TMUX_WORKSPACE_GROUP_OPTION}}\t#{${TMUX_TAB_NAME_OPTION}}\t#{window_name}`
+			]);
+			if (!out) throw new Error(withReason(exec, `tmux could not resolve the workspace around pane ${target.id}`));
+			const [windowId, group, ownName, ...nameParts] = out.split("\n")[0].split("	");
+			if (!windowId) throw new Error(`tmux did not report the window around pane ${target.id}`);
+			if (!group) return [tmuxTab(exec, windowId, ownName, nameParts.join("	"))];
+			const listed = exec("tmux", [
+				"list-windows",
+				"-a",
+				"-F",
+				`#{window_id}\t#{${TMUX_TAB_NAME_OPTION}}\t#{window_name}`,
+				"-f",
+				`#{==:#{${TMUX_WORKSPACE_GROUP_OPTION}},${group}}`
+			]);
+			if (!listed) throw new Error(withReason(exec, `tmux could not enumerate the windows grouped as ${group}`));
+			const tabs = listed.split("\n").filter(Boolean).map((line) => line.split("	")).filter(([id]) => Boolean(id)).map(([id, own, ...rest]) => tmuxTab(exec, id, own, rest.join("	")));
+			if (tabs.length === 0) throw new Error(`tmux reported no windows grouped as ${group}`);
+			return tabs;
+		}
+	}
+};
+/**
+* One window, read as a tab: its id, the tab's OWN name, and its region's geometry.
+*
+* `ownName` is what `group` stored (`TMUX_TAB_NAME_OPTION`) and it WINS, because `windowName` is the
+* display name — on a grouped window that is the composed `pool - editor`, whose `editor` tmux's
+* single name field no longer holds. Reporting the display name instead would compound the prefix on
+* every capture/apply round trip (`pool - pool - editor`), and splitting it back apart is the unsound
+* parse the option exists to refuse.
+*
+* The window name is the FALLBACK, not a second guess: a window carrying no stored name is one nobody
+* composed a display name for, so its name already IS its own name. That covers the untagged window —
+* a workspace of one — and any window a caller grouped without naming.
+*/
+function tmuxTab(exec, windowId, ownName, windowName) {
+	const tab = {
+		id: windowId,
+		panes: describeTmuxRegion(exec, windowId)
+	};
+	const label = ownName || windowName;
+	if (label) tab.label = label;
+	return tab;
+}
+/**
+* Every pane of the region `id` names, with its rectangle. `id` is a pane id (that pane's own window)
+* or a window id (that window) — `list-panes -t` resolves both, which is what lets the region read and
+* the workspace read share one query instead of two that could drift apart.
+*
+* `-t` scopes `list-panes` to ONE window — the region tier, which is what capture captures. Without
+* `-a`, so this never reaches the panes of some other window.
+*
+* `#{pane_left}`/`#{pane_top}` are window-relative, and the widths exclude the divider column tmux
+* draws between panes (a 200-wide window split side by side reports 119 + 80, not 200) — both are
+* exactly what `RegionPane.rect` documents, so nothing is adjusted here.
+*
+* Tab-separated, not space: `pane_current_path` and `pane_title` can both contain spaces, and
+* splitting a path on spaces is how a directory with one in it silently becomes the wrong pane.
+*/
+function describeTmuxRegion(exec, id) {
+	const out = exec("tmux", [
+		"list-panes",
+		"-t",
+		id,
+		"-F",
+		"#{pane_id}	#{pane_left}	#{pane_top}	#{pane_width}	#{pane_height}	#{pane_current_path}	#{pane_title}	#{host}"
+	]);
+	if (!out) throw new Error(withReason(exec, `tmux could not describe the region around pane ${id}`));
+	const panes = [];
+	for (const line of out.split("\n").filter(Boolean)) {
+		const [paneId, left, top, width, height, cwd, title, host] = line.split("	");
+		if (!paneId) continue;
+		const pane = {
+			id: paneId,
+			rect: {
+				x: Number(left),
+				y: Number(top),
+				width: Number(width),
+				height: Number(height)
+			}
+		};
+		if (cwd) pane.cwd = cwd;
+		const label = paneLabel(title, host);
+		if (label) pane.label = label;
+		panes.push(pane);
+	}
+	if (panes.length === 0) throw new Error(`tmux reported no panes in the region around pane ${id}`);
+	return panes;
+}
+/**
+* A tmux pane's label — its title, unless that title is the hostname tmux handed it.
+*
+* **tmux has no "unset title"**: it defaults `pane_title` to the hostname, so a pane nobody ever named
+* reports a name nobody chose, and every pane in an untouched session reports the SAME one. Exporting
+* that would label them all `zeta`, and `zeta` would then resolve to every pane in the session —
+* ambiguity manufactured out of nothing. A title that differs from the host is one someone set
+* (cyber-mux's own `select-pane -T` among them), so it is the author's and survives.
+*
+* One home for the rule, called by BOTH reads — `listPanes` (which a name resolves against) and
+* `describeTmuxRegion` (which a capture exports). Two spellings of a heuristic this load-bearing is
+* how the listing and the capture come to disagree about which panes are named.
+*
+* The comparison is the workaround, not the shape of the thing: herdr has the honest primitive and
+* omits the key outright until a pane is renamed, so it needs no rule at all.
+*/
+function paneLabel(title, host) {
+	return title && title !== host ? title : void 0;
+}
+/**
+* The `-P -F '#{pane_id}\t#{window_id}'` report EVERY open asks for, split back into its two ids.
+* Tab-separated because neither id can contain a tab.
+*
+* A report that does not carry both throws rather than returning half an answer: the window is the
+* pane's tab, which `OpenedPane.tab` promises is always present, and it is also what a grouping open
+* tags. Guessing either would be worse than failing — a caller would name or group nothing and never
+* learn it.
+*/
+function splitOpenReport(out, command) {
+	const [pane, windowId] = out.split("	");
+	if (!pane || !windowId) throw new Error(`tmux ${command} did not report the new pane's id and window id`);
+	return [pane, windowId];
+}
+/**
+* `ratio` is the fraction kept by the ORIGINAL pane; tmux's `-l` sizes the NEW one. So this INVERTS
+* — `1 - ratio` — where herdr's `--ratio` passes the same number through untouched. The two backends
+* genuinely convert in opposite directions, and applying the inversion to both (or to neither) is
+* the way this gets silently backwards: a 0.333 template would size the original pane at 67%.
+*
+* Percent rather than cells: tmux takes `-l` as either, and a percentage is the only form that means
+* the same thing without first querying the region's size.
+*/
+function toTmuxSize(ratio) {
+	return `${Math.round((1 - ratio) * 100)}%`;
+}
+/**
+* The core vocabulary's tmux spelling. Exactly one member differs — probed, not read off tmux(1):
+* tmux has no `Backspace` key name, so it would *type* the word (its unrecognized-token fallback);
+* its name for that key is `BSpace` (tmux(1): "the following special key names are accepted: Up,
+* Down, Left, Right, BSpace, BTab, DC ..."). Every other core key — `Up` `Down` `Left` `Right`
+* `Enter` `Escape` `Tab` `Space` `C-c` `F1`-`F12` — is already tmux's own name for it.
+*
+* Deliberately a rename table, NOT a validation table: a token outside the core is forwarded
+* verbatim (the contract), so this must not reject what it does not recognize. Keeping a full tmux
+* key list here would make the passthrough a second vocabulary to maintain.
+*/
+const TMUX_KEY_RENAMES = { Backspace: "BSpace" };
+function toTmuxKey(key) {
+	return TMUX_KEY_RENAMES[key] ?? key;
+}
+/**
+* `tmux list-panes -a -F '#{pane_id} #{session_name} #{window_id}'` lists every pane server-wide.
+* Resolving fails — no line's pane id matches `id` — when the pane no longer exists in the backend,
+* and that must throw so `focus` never issues a switch-client/select-window against a pane it
+* couldn't actually resolve.
+*/
+function parsePaneLocation(out, id) {
+	const line = (out ?? "").split("\n").find((l) => l.split(" ")[0] === id);
+	if (!line) throw new Error(`peer's pane ${id} could not be resolved to beam to`);
+	const [, sessionName, windowId] = line.split(" ");
+	return {
+		sessionName,
+		windowId
+	};
+}
+//#endregion
+//#region src/new-id.ts
+/** The real id source — a v4 UUID. The shell binds this; core takes `NewId` as a parameter. */
+const nodeNewId = () => randomUUID();
+//#endregion
+//#region src/mux.wezterm.ts
+/**
+* WezTerm backend — detected via `$WEZTERM_PANE`. Drives WezTerm's built-in multiplexer through
+* `wezterm cli …` (https://wezterm.org/cli/general.html), the same synchronous-CLI shape tmux and
+* herdr already give `Exec`.
+*
+* Probed from `wezterm cli --help`/the CLI reference docs only — there is no live WezTerm GUI in
+* this sandbox, so nothing here carries the "verified against a live binary" claim `session.tmux.ts`
+* and `session.herdr.ts` make. Several real capability gaps fell out of that probe, not just missing
+* polish:
+*
+* - **No `--env` on `spawn`/`split-pane` at all.** Unlike herdr (native everywhere except one
+*   worktree route), WezTerm's CLI has no env flag on ANY space-creating command — every route is
+*   the exception, so `open`'s env always rides the `envFallback` compensation (a `env K=V` prefix
+*   on the launch command, or a stderr warning with none to ride), never a native flag.
+* - **No way to title a PANE**, at birth or after — `set-tab-title`/`set-window-title` exist, there
+*   is no pane equivalent. `rename(..., 'pane', …)` throws; `open`'s pane-tier `label` degrades to a
+*   stderr warning rather than silently dropping it or failing the whole open.
+* - **No focus-query primitive** — `list --format json`'s documented fields carry no active/focused
+*   indicator for a pane, tab, or window. `isPaneFocused` always answers `undefined`, which is the
+*   seam's own honest answer for "no primitive to report focus", not a workaround.
+* - **No per-key press primitive** — there is no `send-keys`-shaped verb, only `send-text`. The core
+*   vocabulary is instead realized by encoding each key as its raw terminal byte sequence and typing
+*   it via `send-text --no-paste`; see `WEZTERM_KEY_BYTES`.
+* - **No pane geometry** — `list --format json` reports a pane's `size` (rows/cols) but no position,
+*   so there is nothing to build a `PaneRect` from. `describeRegion`/`describeWorkspace` are omitted
+*   entirely, the same optional-omission `template save` already handles for a backend that cannot.
+* - **No git-worktree concept in the CLI at all** — no `worktree` subcommand, so like tmux this
+*   backend never binds one to a workspace; `worktree` is omitted.
+*
+* `spawn`/`split-pane` report only the new pane's bare id — unlike tmux/herdr, which embed the tab
+* (and workspace) in the same `-F`/JSON envelope the pane id rides out on. So `OpenedPane.tab` costs
+* a follow-up `wezterm cli list --format json` lookup here, not a free read of output already held.
+*/
+/**
+* Build the WezTerm adapter over its injected effects. The only effect it takes is `newId` — the id
+* source for the fresh workspace name minted when the caller opens a `workspace` without a `label`.
+* Exported as a factory (with `weztermMuxAdapter` binding the real one below) so a test can inject a
+* deterministic id instead of a UUID, exactly the seam `Exec`/`TemplateStore` already are.
+*/
+function createWeztermAdapter(deps) {
+	const adapter = {
+		name: "wezterm",
+		canSizeSplits: true,
+		open(exec, opts) {
+			const at = opts.at ?? "tab";
+			if (at === "workspace") {
+				const workspace = opts.label ?? `cyber-mux-${deps.newId().slice(0, 8)}`;
+				const out = exec("wezterm", [
+					"cli",
+					"spawn",
+					"--new-window",
+					"--workspace",
+					workspace,
+					"--cwd",
+					opts.cwd
+				]);
+				if (!out) throw new Error(withReason(exec, "wezterm cli spawn --new-window failed"));
+				const pane = out.trim();
+				if (!pane) throw new Error("wezterm cli spawn --new-window did not report the new pane id");
+				const opened = {
+					id: pane,
+					tab: resolveTab(exec, pane),
+					workspace
+				};
+				runLaunch$1(adapter, exec, opened, opts.env, opts.launch);
+				return opened;
+			}
+			if (at === "tab") {
+				const out = exec("wezterm", [
+					"cli",
+					"spawn",
+					...opts.within ? ["--window-id", resolveWorkspaceWindow(exec, opts.within)] : [],
+					"--cwd",
+					opts.cwd
+				]);
+				if (!out) throw new Error(withReason(exec, "wezterm cli spawn failed"));
+				const pane = out.trim();
+				if (!pane) throw new Error("wezterm cli spawn did not report the new pane id");
+				const opened = withTabAndWorkspace(exec, pane);
+				if (opts.label) adapter.rename(exec, { id: opened.tab }, "tab", opts.label);
+				runLaunch$1(adapter, exec, opened, opts.env, opts.launch);
+				return opened;
+			}
+			const direction = at === "pane:down" ? ["--bottom"] : ["--right"];
+			const from = opts.from ? ["--pane-id", opts.from.id] : [];
+			const size = opts.ratio != null ? ["--percent", toWeztermSize(opts.ratio)] : [];
+			const out = exec("wezterm", [
+				"cli",
+				"split-pane",
+				...direction,
+				...from,
+				...size,
+				"--cwd",
+				opts.cwd
+			]);
+			if (!out) throw new Error(withReason(exec, "wezterm cli split-pane failed"));
+			const pane = out.trim();
+			if (!pane) throw new Error("wezterm cli split-pane did not report the new pane id");
+			const opened = withTabAndWorkspace(exec, pane);
+			if (opts.label) process.stderr.write(`wezterm cannot name a pane — "${opts.label}" was not set on pane ${opened.id}\n`);
+			runLaunch$1(adapter, exec, opened, opts.env, opts.launch);
+			return opened;
+		},
+		rename(exec, target, tier, name) {
+			if (tier === "tab") {
+				exec("wezterm", [
+					"cli",
+					"set-tab-title",
+					"--tab-id",
+					target.id,
+					name
+				]);
+				return;
+			}
+			throw new Error(`wezterm cannot name a pane (only a tab or window) — asked to rename ${target.id}`);
+		},
+		group() {},
+		sendText(exec, target, text) {
+			exec("wezterm", [
+				"cli",
+				"send-text",
+				"--pane-id",
+				target.id,
+				text
+			]);
+		},
+		sendKeys(exec, target, keys) {
+			const bytes = keys.map((k) => WEZTERM_KEY_BYTES[k] ?? k).join("");
+			exec("wezterm", [
+				"cli",
+				"send-text",
+				"--pane-id",
+				target.id,
+				"--no-paste",
+				bytes
+			]);
+		},
+		submit(exec, target, text) {
+			if (!text) {
+				adapter.sendKeys(exec, target, ["Enter"]);
+				return;
+			}
+			adapter.sendText(exec, target, text);
+			adapter.sendKeys(exec, target, ["Enter"]);
+		},
+		read(exec, target, opts) {
+			const args = [
+				"cli",
+				"get-text",
+				"--pane-id",
+				target.id
+			];
+			if (opts?.lines != null) args.push("--start-line", String(-opts.lines));
+			return exec("wezterm", args) ?? "";
+		},
+		focus(exec, target) {
+			exec("wezterm", [
+				"cli",
+				"activate-pane",
+				"--pane-id",
+				target.id
+			]);
+		},
+		teardown(exec, target) {
+			exec("wezterm", [
+				"cli",
+				"kill-pane",
+				"--pane-id",
+				target.id
+			]);
+		},
+		paneExists(exec, target) {
+			return listWeztermPanes(exec).some((p) => String(p.pane_id) === target.id);
+		},
+		isPaneFocused() {},
+		listPanes(exec) {
+			return listWeztermPanes(exec).map((p) => {
+				const pane = {
+					id: String(p.pane_id),
+					mux: "wezterm"
+				};
+				const cwd = weztermCwd(p.cwd);
+				if (cwd) pane.cwd = cwd;
+				return pane;
+			});
+		}
+	};
+	return adapter;
+}
+const weztermMuxAdapter = createWeztermAdapter({ newId: nodeNewId });
+/**
+* `wezterm cli spawn`/`split-pane` report ONLY the new pane's bare id on stdout — unlike tmux/herdr,
+* neither embeds the tab (or workspace) in that same output. So the tab this pane landed in is a
+* follow-up `list --format json` lookup rather than a free read of an envelope already held.
+* `OpenedPane.tab` is still required — every multiplexer has the Tab level — it simply costs more
+* here than the "no extra call" property tmux/herdr get to claim.
+*/
+function resolveTab(exec, pane) {
+	const found = listWeztermPanes(exec).find((p) => String(p.pane_id) === pane);
+	if (!found) throw new Error(`wezterm did not report a tab for the new pane ${pane}`);
+	return String(found.tab_id);
+}
+/**
+* A window of the named workspace — what `spawn --window-id` needs to place a tab in a workspace
+* WezTerm's CLI cannot target directly (`--workspace` only names the space a `--new-window` spawn
+* creates, so it cannot place a tab in an existing one).
+*
+* Throws rather than falling back to an untargeted spawn: an unresolvable anchor means the workspace
+* is gone, and the untargeted spawn is exactly the wrong-space bug `within` was added to close.
+*/
+function resolveWorkspaceWindow(exec, workspace) {
+	const found = listWeztermPanes(exec).find((p) => p.workspace === workspace);
+	if (!found) throw new Error(`wezterm reported no window in workspace ${workspace} to open a tab in`);
+	return String(found.window_id);
+}
+/** `resolveTab` plus the workspace the same lookup already answers — one call serves both facts. */
+function withTabAndWorkspace(exec, pane) {
+	const found = listWeztermPanes(exec).find((p) => String(p.pane_id) === pane);
+	if (!found) throw new Error(`wezterm did not report a tab for the new pane ${pane}`);
+	return {
+		id: pane,
+		tab: String(found.tab_id),
+		workspace: found.workspace
+	};
+}
+/**
+* Env is native at NO tier on this backend — `spawn`/`split-pane` take no `--env` at all, unlike
+* herdr (native everywhere but one worktree route). So every `open` funnels through the same
+* fallback herdr's worktree route uses: with a launch command, env rides in as an `env K=V` prefix;
+* with none, a warning names what did not land. `envFallback` is a no-op when there is no env to
+* carry, so this is safe to call unconditionally.
+*/
+function runLaunch$1(adapter, exec, target, env, launch) {
+	const fallback = envFallback(env, launch);
+	if (fallback.kind === "dropped") {
+		process.stderr.write(`env (${fallback.variables.join(", ")}) could not be set on this wezterm pane — wezterm has no --env flag on any space-creating command
+`);
+		return;
+	}
+	if (fallback.command !== void 0) adapter.submit(exec, target, fallback.command);
+}
+/** One `wezterm cli list --format json` call, parsed defensively — never throws on bad output. */
+function listWeztermPanes(exec) {
+	const out = exec("wezterm", [
+		"cli",
+		"list",
+		"--format",
+		"json"
+	]);
+	if (!out) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(out);
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(parsed)) return [];
+	return parsed.filter((p) => p != null && p.pane_id != null && p.tab_id != null && p.window_id != null);
+}
+/** `cwd` is reported as a `file://` URI; strip the scheme and host down to the bare path. */
+function weztermCwd(cwd) {
+	if (!cwd) return void 0;
+	const match = /^file:\/\/[^/]*(\/.*)$/.exec(cwd);
+	return match ? decodeURIComponent(match[1]) : cwd;
+}
+/**
+* `ratio` is the fraction kept by the ORIGINAL pane; `--percent` sizes the NEW one (the issue's own
+* probe note, #47) — the same inversion tmux's `-l` needs, unlike herdr's pass-through.
+*/
+function toWeztermSize(ratio) {
+	return String(Math.round((1 - ratio) * 100));
+}
+/**
+* The core vocabulary, realized as raw terminal bytes rather than a backend key NAME — there is no
+* send-keys-shaped verb to name a key TO, only `send-text`. Escape sequences are the ANSI/VT100
+* "cursor key mode" forms every common shell/program already parses; `Backspace` sends DEL (`\x7f`),
+* what most terminals emit for that key today (probed, not read off any wezterm spec — wezterm ships
+* no such table because it has no key-name CLI surface to spec).
+*
+* `Home`/`End`/`Delete`/`Insert`/`PageUp`/`PageDown` are extras beyond the core, included for the
+* same reason tmux "knows" `Home` even though the core vocabulary does not name it: these are
+* standard-enough ANSI keys that encoding them costs nothing extra and a caller reaching for one
+* should not silently get the literal word typed instead.
+*/
+const WEZTERM_KEY_BYTES = {
+	Up: "\x1B[A",
+	Down: "\x1B[B",
+	Right: "\x1B[C",
+	Left: "\x1B[D",
+	Enter: "\r",
+	Escape: "\x1B",
+	Tab: "	",
+	Space: " ",
+	Backspace: "",
+	"C-c": "",
+	F1: "\x1BOP",
+	F2: "\x1BOQ",
+	F3: "\x1BOR",
+	F4: "\x1BOS",
+	F5: "\x1B[15~",
+	F6: "\x1B[17~",
+	F7: "\x1B[18~",
+	F8: "\x1B[19~",
+	F9: "\x1B[20~",
+	F10: "\x1B[21~",
+	F11: "\x1B[23~",
+	F12: "\x1B[24~",
+	Home: "\x1B[H",
+	End: "\x1B[F",
+	Delete: "\x1B[3~",
+	Insert: "\x1B[2~",
+	PageUp: "\x1B[5~",
+	PageDown: "\x1B[6~"
+};
+//#endregion
+//#region src/mux.zellij.ts
+/**
+* Zellij backend — detected via `$ZELLIJ`. Drives Zellij's built-in multiplexer through `zellij
+* action …` (https://zellij.dev/documentation/cli-actions), the same synchronous-CLI shape tmux,
+* herdr and wezterm already give `Exec`.
+*
+* Requires **Zellij ≥ 0.44.1**. The whole per-pane-addressable surface this adapter stands on landed
+* in 0.44.0 (2026-03-23): `--pane-id` across the action verbs, `list-panes --json`, ids returned from
+* `new-pane`/`new-tab`, and `focus-pane-id`. Before that release Zellij's CLI was almost entirely
+* FOCUS-relative — no stable per-pane handle — and no faithful adapter was possible. On an older
+* binary these commands fail and the adapter surfaces the failure rather than silently mis-targeting
+* the focused pane.
+*
+* Probed from the Zellij docs + CHANGELOG only — Zellij is not installed in this sandbox, so nothing
+* here carries the "verified against a live binary" claim `session.tmux.ts`/`session.herdr.ts` make;
+* it makes the same honest disclaimer `mux.wezterm.ts` does. Two literals in particular are worth a
+* one-line confirmation on a live 0.44.1 binary — the exact form `new-pane` prints an id in (bare `3`
+* vs `terminal_3`) and the shell value of `$ZELLIJ_PANE_ID`. Both are handled either way: ids are
+* carried verbatim and compared through `samePane`, which treats a bare `N` and its `terminal_N` twin
+* as the same pane (per the docs' own `terminal_N | plugin_N | bare N` scheme).
+*
+* Real capability shape that fell out of the probe:
+*
+* - **The session is the workspace tier, but a SEPARATE session's panes are un-addressable through
+*   this seam.** Zellij's native tiers are Session › Tab › Pane, so a `workspace` placement would
+*   naturally open a new session (`zellij attach --create-background`). But Zellij pane ids are
+*   SESSION-SCOPED — driving another session's pane requires `zellij --session <name> action …` — and
+*   `MuxTarget` carries only an opaque pane id, no session. A pane returned from a freshly-created
+*   session would therefore fail on the next `write`/`read`/`focus`, which is a trap, not a feature.
+*   So this adapter operates within the AMBIENT session: `workspace` collapses to a new **tab**, the
+*   same collapse tmux makes for a Window. Unlike tmux, the occupied workspace IS reported —
+*   `OpenedPane.workspace` carries the ambient session name (`deps.session`), because every pane
+*   genuinely lives in that session. (Lifting the collapse needs a seam change: a session qualifier
+*   on `MuxTarget`. Recorded in the ADR log.)
+* - **No `--env` on `new-pane`/`new-tab`.** Like wezterm, env is native at no tier, so every open
+*   rides the `envFallback` compensation (an `env K=V` prefix on the launch command, or a stderr
+*   warning when there is no command to ride).
+* - **Tiled splits cannot be sized.** `new-pane`'s `-x/-y/--width/--height` all require `--floating`;
+*   a tiled `pane:*` split is always even. So `canSizeSplits` is omitted and a `ratio` is dropped —
+*   callers degrade to the even default, the same path the flag's absence already documents.
+* - **`new-pane` has no split-TARGET flag.** It splits the focused pane (or the biggest space); the
+*   only flag is `--tab-id`. So `from` — which pane a `pane:*` split lands beside — is honored by
+*   FOCUSING that pane first, the sole way to choose the split target. That is a real focus move, and
+*   the honest cost of getting the RIGHT pane split.
+* - **No pane geometry adapter.** `list-panes --json` does report `pane_x`/`pane_y`, so `regions`
+*   (`describeRegion`/`describeWorkspace`) is IMPLEMENTABLE here — unlike wezterm, which lacks
+*   position entirely — but the cell-vs-divider semantics of Zellij's rects need a live binary to pin,
+*   so it is deliberately left as a follow-up rather than guessed. `template save` refuses on zellij
+*   by naming the backend, the same optional-absence it already handles for wezterm.
+* - **No git-worktree concept in the CLI.** No `worktree` subcommand, so — like tmux and wezterm —
+*   this backend never binds one to a workspace; callers fall back to plain git plus `open()`.
+*
+* Wins Zellij has that wezterm does not: it CAN name a pane (`new-pane --name` / `rename-pane`), and
+* it CAN report which pane is focused (`list-panes --json`'s `is_focused`), so `isPaneFocused`
+* answers a real value rather than always `unknown`.
+*/
+/**
+* Build the Zellij adapter over its injected effects. The only effect it takes is `session` — the
+* ambient Zellij session name (`$ZELLIJ_SESSION_NAME`), reported as `OpenedPane.workspace` so a
+* caller learns which workspace a new pane landed in. Undefined when unknown (the exported singleton),
+* in which case `workspace` is simply omitted — the same absent-not-false convention the seam uses
+* elsewhere. Exported as a factory (with `zellijMuxAdapter` binding the effect-less one) so
+* `backend.ts` can bind the real session name off `env` at resolution, exactly the seam `Exec` and
+* wezterm's `newId` already are.
+*/
+function createZellijAdapter(deps) {
+	const adapter = {
+		name: "zellij",
+		open(exec, opts) {
+			const at = opts.at ?? "tab";
+			if (at === "tab" || at === "workspace") {
+				const args = [
+					"action",
+					"new-tab",
+					"--cwd",
+					opts.cwd
+				];
+				if (opts.label) args.push("--name", opts.label);
+				const out = exec("zellij", args);
+				if (!out) throw new Error(withReason(exec, "zellij action new-tab failed"));
+				const tabId = out.trim();
+				if (!tabId) throw new Error("zellij action new-tab did not report the new tab id");
+				const opened = openedForTab(exec, tabId, deps.session);
+				runLaunch(adapter, exec, opened, opts.env, opts.launch);
+				return opened;
+			}
+			if (opts.from) adapter.focus(exec, opts.from);
+			const args = [
+				"action",
+				"new-pane",
+				"--direction",
+				at === "pane:down" ? "down" : "right",
+				"--cwd",
+				opts.cwd
+			];
+			if (opts.label) args.push("--name", opts.label);
+			const out = exec("zellij", args);
+			if (!out) throw new Error(withReason(exec, "zellij action new-pane failed"));
+			const paneId = out.trim();
+			if (!paneId) throw new Error("zellij action new-pane did not report the new pane id");
+			const opened = openedForPane(exec, paneId, deps.session);
+			runLaunch(adapter, exec, opened, opts.env, opts.launch);
+			return opened;
+		},
+		rename(exec, target, tier, name) {
+			if (tier === "tab") {
+				exec("zellij", [
+					"action",
+					"rename-tab-by-id",
+					target.id,
+					name
+				]);
+				return;
+			}
+			exec("zellij", [
+				"action",
+				"rename-pane",
+				"--pane-id",
+				target.id,
+				name
+			]);
+		},
+		group() {},
+		sendText(exec, target, text) {
+			exec("zellij", [
+				"action",
+				"write-chars",
+				"--pane-id",
+				target.id,
+				text
+			]);
+		},
+		sendKeys(exec, target, keys) {
+			exec("zellij", [
+				"action",
+				"send-keys",
+				"--pane-id",
+				target.id,
+				...keys.map(toZellijKey)
+			]);
+		},
+		submit(exec, target, text) {
+			if (!text) {
+				adapter.sendKeys(exec, target, ["Enter"]);
+				return;
+			}
+			adapter.sendText(exec, target, text);
+			adapter.sendKeys(exec, target, ["Enter"]);
+		},
+		read(exec, target, opts) {
+			if (opts?.lines != null) return lastLines(exec("zellij", [
+				"action",
+				"dump-screen",
+				"--pane-id",
+				target.id,
+				"--full"
+			]) ?? "", opts.lines);
+			return exec("zellij", [
+				"action",
+				"dump-screen",
+				"--pane-id",
+				target.id
+			]) ?? "";
+		},
+		focus(exec, target) {
+			exec("zellij", [
+				"action",
+				"focus-pane-id",
+				target.id
+			]);
+		},
+		teardown(exec, target) {
+			exec("zellij", [
+				"action",
+				"close-pane",
+				"--pane-id",
+				target.id
+			]);
+		},
+		paneExists(exec, target) {
+			return listZellijPanes(exec).some((p) => samePane(p.id, target.id));
+		},
+		isPaneFocused(exec, target) {
+			const found = listZellijPanes(exec).find((p) => samePane(p.id, target.id));
+			if (!found) return void 0;
+			return found.is_focused === true;
+		},
+		listPanes(exec) {
+			return listZellijPanes(exec).map((p) => {
+				const pane = {
+					id: p.id,
+					mux: "zellij"
+				};
+				if (p.pane_cwd) pane.cwd = p.pane_cwd;
+				const label = zellijLabel(p.title, p.pane_command);
+				if (label) pane.label = label;
+				return pane;
+			});
+		}
+	};
+	return adapter;
+}
+const zellijMuxAdapter = createZellijAdapter({});
+/**
+* One `zellij action list-panes --json` call, parsed defensively — never throws on bad output. The id
+* is coerced to a string so a bare-integer id (`3`) and a prefixed one (`terminal_3`) are compared as
+* strings by `samePane` rather than one being a number.
+*/
+function listZellijPanes(exec) {
+	const out = exec("zellij", [
+		"action",
+		"list-panes",
+		"--json"
+	]);
+	if (!out) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(out);
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(parsed)) return [];
+	return parsed.filter((p) => p != null && p.id != null).map((p) => ({
+		...p,
+		id: String(p.id)
+	}));
+}
+/**
+* The `OpenedPane` for a pane `new-pane` just reported — its tab resolved from the one `list-panes`
+* record carrying that pane id, and the workspace filled from the ambient session name. Throws rather
+* than guessing a tab: `OpenedPane.tab` is required (every multiplexer has the Tab level), and a wrong
+* tab is worse than a loud failure.
+*/
+function openedForPane(exec, paneId, session) {
+	const found = listZellijPanes(exec).find((p) => samePane(p.id, paneId));
+	if (!found || found.tab_id == null) throw new Error(`zellij did not report a tab for the new pane ${paneId}`);
+	return openedPane(paneId, String(found.tab_id), session);
+}
+/**
+* The `OpenedPane` for a tab `new-tab` just reported — its initial pane resolved as the single
+* `list-panes` record carrying that tab id. Throws rather than guessing: a new tab must have a pane,
+* and a caller handed a tab with no pane could neither drive nor name it.
+*/
+function openedForTab(exec, tabId, session) {
+	const pane = listZellijPanes(exec).find((p) => p.tab_id != null && String(p.tab_id) === tabId);
+	if (!pane) throw new Error(`zellij did not report a pane in the new tab ${tabId}`);
+	return openedPane(pane.id, tabId, session);
+}
+/**
+* Assemble an `OpenedPane`, attaching `workspace` only when the ambient session name is known — the
+* absent-not-false convention. Every Zellij pane genuinely lives in a session, so where the name IS
+* known this is never absent, on every placement including `pane:*`; where it is not (the effect-less
+* singleton), it is omitted rather than reported as a false "none".
+*/
+function openedPane(id, tab, session) {
+	const opened = {
+		id,
+		tab
+	};
+	if (session) opened.workspace = session;
+	return opened;
+}
+/**
+* Env is native at NO tier on this backend — `new-pane`/`new-tab` take no `--env`, like wezterm. So
+* every `open` funnels through the same fallback herdr's worktree route uses: with a launch command,
+* env rides in as an `env K=V` prefix; with none, a warning names what did not land. `envFallback` is
+* a no-op when there is no env to carry, so this is safe to call unconditionally.
+*/
+function runLaunch(adapter, exec, target, env, launch) {
+	const fallback = envFallback(env, launch);
+	if (fallback.kind === "dropped") {
+		process.stderr.write(`env (${fallback.variables.join(", ")}) could not be set on this zellij pane — zellij has no --env flag on new-pane/new-tab
+`);
+		return;
+	}
+	if (fallback.command !== void 0) adapter.submit(exec, target, fallback.command);
+}
+/**
+* The core key vocabulary's Zellij spelling — a rename table, NOT a validation table: a token outside
+* the core is forwarded verbatim (the seam's passthrough), so this must not reject what it does not
+* recognize. Only the two members that differ from the core name are listed; `Up` `Down` `Left`
+* `Right` `Enter` `Tab` `Space` `Backspace` `F1`–`F12` are already Zellij's own names. Probed from
+* Zellij's key-binding vocabulary in the docs, not verified against a live `send-keys`:
+*
+* - `Escape` → `Esc`: Zellij's key name for that key is `Esc`.
+* - `C-c` → `Ctrl c`: Zellij writes a modified key as space-separated words (`"Ctrl a"`, `"Alt Shift
+*   b"`), so the whole `Ctrl c` is one argument — the modifier and key are not two keys.
+*/
+const ZELLIJ_KEY_RENAMES = {
+	Escape: "Esc",
+	"C-c": "Ctrl c"
+};
+function toZellijKey(key) {
+	return ZELLIJ_KEY_RENAMES[key] ?? key;
+}
+/**
+* A Zellij pane's label — its title, unless that title is the running command Zellij handed an unnamed
+* pane. Zellij defaults an unnamed pane's title to its `pane_command`, so a title equal to it is
+* ambient rather than chosen; exporting it would put the same manufactured name on every shell pane,
+* exactly the collision tmux's hostname guard exists to prevent. A title that differs from the command
+* is one someone set (`new-pane --name`/`rename-pane`), so it is the author's and survives.
+*/
+function zellijLabel(title, command) {
+	return title && title !== command ? title : void 0;
+}
+/**
+* Normalize a pane id to a single canonical form for comparison. Per the Zellij docs a bare integer
+* `N` is the same terminal pane as `terminal_N`; `plugin_N` is a distinct space. So a bare id is
+* folded to its `terminal_` form and everything else is left as-is — a comparison-only transform,
+* never stored (`MuxTarget.id` stays whatever the backend reported).
+*/
+function normalizePaneId(id) {
+	return /^\d+$/.test(id) ? `terminal_${id}` : id;
+}
+/** Whether two pane ids name the same pane, treating a bare `N` and its `terminal_N` twin as equal. */
+function samePane(a, b) {
+	return normalizePaneId(a) === normalizePaneId(b);
+}
+/** The last `n` lines of `text` — `read`'s client-side approximation of a trailing-lines capture. */
+function lastLines(text, n) {
+	const lines = text.split("\n");
+	return lines.slice(Math.max(0, lines.length - n)).join("\n");
+}
+//#endregion
+//#region src/mux-probe.ts
+const KNOWN_MUX = [
+	"tmux",
+	"herdr",
+	"wezterm",
+	"zellij",
+	"screen",
+	"none"
+];
+function isKnownMux(v) {
+	return v != null && KNOWN_MUX.includes(v);
+}
+/**
+* The single source of the mux → per-pane-env-var mapping. tmux exports `$TMUX_PANE`; herdr exports
+* `$HERDR_PANE_ID` (both in the same `wX:pY`-style namespace); WezTerm exports `$WEZTERM_PANE` in
+* every pane (its own bare-integer id) — per the issue that requested that backend (#47), the same
+* fast-path extension `$TMUX_PANE`/`$HERDR_PANE_ID` already get; Zellij exports `$ZELLIJ_PANE_ID` in
+* every terminal pane (its own `terminal_N`/bare-`N` id) — per the issue that requested this backend
+* (#46). screen carries no per-pane env var. Both the ancestry probe and the `currentPane`
+* self-identity helper read the pane through this table so the two never diverge on which env var a
+* given mux uses.
+*/
+const PANE_ENV = {
+	tmux: (env) => env["TMUX_PANE"],
+	herdr: (env) => env["HERDR_PANE_ID"],
+	wezterm: (env) => env["WEZTERM_PANE"],
+	zellij: (env) => env["ZELLIJ_PANE_ID"]
+};
+/**
+* Resolve THIS session's own pane from env alone (no `ps` walk): the `$CYBER_MUX_PANE` fast-path a
+* spawn propagates → `$TMUX_PANE` (tmux) → `$HERDR_PANE_ID` (herdr) → `$WEZTERM_PANE` (wezterm) →
+* `$ZELLIJ_PANE_ID` (zellij). Returns the pane tagged with its multiplexer, or undefined when the
+* session is in no pane-carrying multiplexer. This is the mux-agnostic self-identity key.
+*/
+function currentPane(env) {
+	if (env["CYBER_MUX_PANE"]) return {
+		mux: env["CYBER_MUX"] === "herdr" ? "herdr" : env["CYBER_MUX"] === "wezterm" ? "wezterm" : env["CYBER_MUX"] === "zellij" ? "zellij" : "tmux",
+		pane: env["CYBER_MUX_PANE"]
+	};
+	const tmux = PANE_ENV.tmux(env);
+	if (tmux) return {
+		mux: "tmux",
+		pane: tmux
+	};
+	const herdr = PANE_ENV.herdr(env);
+	if (herdr) return {
+		mux: "herdr",
+		pane: herdr
+	};
+	const wezterm = PANE_ENV.wezterm(env);
+	if (wezterm) return {
+		mux: "wezterm",
+		pane: wezterm
+	};
+	const zellij = PANE_ENV.zellij(env);
+	if (zellij) return {
+		mux: "zellij",
+		pane: zellij
+	};
+}
+/**
+* Two-mode multiplexer detection.
+*
+* Fast-path: `$CYBER_MUX` (tmux | herdr | wezterm | zellij | screen | none) is trusted outright —
+* this also serves as an OVERRIDE (`=none` forces no-mux even inside a real multiplexer).
+* `$CYBER_MUX_PANE` carries the pane id alongside it. Detection RECOGNIZES `screen` (so an override
+* pinning it, or a real screen ancestor, is reported truthfully rather than silently ignored), but
+* `screen` is not a drivable backend — `resolveMuxAdapter` rejects it with a reason. Recognition is
+* not support.
+*
+* Discovery (else): walk the process ancestry from `$$` via `ps -o ppid=,comm= -p <pid>`, since the
+* tool's own shell may not be the human's pane. `$TMUX`/`$HERDR_ENV` are NOT trusted alone — they
+* are used only as a fast-positive hint the ancestry walk falls back to when the walk itself is
+* inconclusive (e.g. `ps` unavailable), never as a substitute for it.
+*/
+function probeMultiplexer(exec, env, opts = {}) {
+	const prefix = opts.envPrefix ?? "CYBER_MUX";
+	const override = env[prefix];
+	const pane = env[`${prefix}_PANE`];
+	if (isKnownMux(override)) return {
+		mux: override,
+		...pane ? { pane } : {},
+		via: "env"
+	};
+	if (opts.discover === false) return {
+		mux: "none",
+		via: "ancestry"
+	};
+	return discoverByAncestry(exec, env);
+}
+const MUX_COMM = [
+	{
+		re: /^tmux(:|$)/,
+		mux: "tmux"
+	},
+	{
+		re: /^herdr(:|$)/,
+		mux: "herdr"
+	},
+	{
+		re: /^wezterm(-gui|-mux-server)?(:|$)/,
+		mux: "wezterm"
+	},
+	{
+		re: /^zellij(:|$)/,
+		mux: "zellij"
+	},
+	{
+		re: /^screen(:|$)/,
+		mux: "screen"
+	}
+];
+/** The per-pane env var for a mux, via the shared `PANE_ENV` table; undefined for screen/none. */
+function paneFor(mux, env) {
+	return mux === "tmux" || mux === "herdr" || mux === "wezterm" || mux === "zellij" ? PANE_ENV[mux](env) : void 0;
+}
+/**
+* An ancestry-discovered probe, OMITTING `pane` when the mux carries none — never carrying it as an
+* explicit `undefined`, so `MuxProbe.pane` stays an absent-or-present field (the same conditional
+* shape the `$CYBER_MUX_PANE` fast-path uses above).
+*/
+function ancestryProbe(mux, env) {
+	const pane = paneFor(mux, env);
+	return {
+		mux,
+		...pane !== void 0 ? { pane } : {},
+		via: "ancestry"
+	};
+}
+const MAX_ANCESTORS = 32;
+function walkAncestry(exec, env) {
+	let pid = process.pid;
+	const seen = /* @__PURE__ */ new Set();
+	for (let i = 0; i < MAX_ANCESTORS; i++) {
+		if (seen.has(pid)) break;
+		seen.add(pid);
+		const line = exec("ps", [
+			"-o",
+			"ppid=,comm=",
+			"-p",
+			String(pid)
+		]);
+		if (!line) break;
+		const trimmed = line.trim();
+		const spaceIdx = trimmed.indexOf(" ");
+		const ppidStr = spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx);
+		const comm = spaceIdx === -1 ? "" : trimmed.slice(spaceIdx + 1).trim();
+		const ppid = Number.parseInt(ppidStr, 10);
+		for (const entry of MUX_COMM) if (entry.re.test(comm)) return ancestryProbe(entry.mux, env);
+		if (!Number.isFinite(ppid) || ppid <= 1) break;
+		pid = ppid;
+	}
+}
+function discoverByAncestry(exec, env) {
+	const found = walkAncestry(exec, env);
+	if (found) return found;
+	if (env["TMUX"]) return ancestryProbe("tmux", env);
+	if (env["HERDR_ENV"]) return ancestryProbe("herdr", env);
+	if (env["WEZTERM_PANE"]) return ancestryProbe("wezterm", env);
+	if (env["ZELLIJ"]) return ancestryProbe("zellij", env);
+	return {
+		mux: "none",
+		via: "ancestry"
+	};
+}
+//#endregion
+//#region src/nudge.ts
+/** Max flush re-submits after the initial submit, before nudge fails loud. */
+const DEFAULT_ATTEMPTS = 10;
+/** Wait after a submit before reading the pane back, in ms. */
+const DEFAULT_SETTLE_MS = 400;
+/** Length of the message prefix used as the staged-text needle. */
+const NEEDLE_LEN = 40;
+/**
+* Whether `message` is still sitting staged in `visible`'s input box (not yet submitted). A real
+* submit scrolls the message into the transcript, leaving the bottom input box empty, so the
+* needle is absent from the tail; while staged it sits in the bottom input box, so the needle is
+* present. `visible` being null/empty means the turn can't be confirmed — treated as still staged
+* so callers keep retrying rather than falsely reporting success.
+*/
+function isStaged(visible, message) {
+	if (!visible) return true;
+	const needle = message.replace(/\s+/g, " ").trim().slice(0, NEEDLE_LEN);
+	if (needle === "") return true;
+	return visible.split("\n").filter((l) => l.trim() !== "").slice(-5).join(" ").replace(/\s+/g, " ").trim().includes(needle);
+}
+/**
+* Submit `message` to `target` and verify the peer actually took the turn — a booting harness can
+* swallow the Enter of the initial `submit`, leaving the text staged unsent while nudge would
+* otherwise report false success. Types the message exactly once; a swallowed Enter is recovered by
+* flushing the staged buffer (`adapter.submit` with no text, a bare Enter) — never re-typing the
+* message — up to a bounded number of attempts. Throws if the turn is never taken within the cap.
+*
+* A pane that no longer exists is rejected up front rather than retried: a gone pane and a booting
+* one both read back empty, so without the liveness probe the retry loop reports a dead peer as
+* "never took the turn" — a boot-race shape — and buries the real cause.
+*/
+async function nudge(adapter, exec, target, message, opts = {}) {
+	const attempts = opts.attempts ?? DEFAULT_ATTEMPTS;
+	const settleMs = opts.settleMs ?? DEFAULT_SETTLE_MS;
+	const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	if (!adapter.paneExists(exec, target)) throw new Error(`nudge failed: pane ${target.id} no longer exists — the peer's session is gone, not busy.`);
+	adapter.submit(exec, target, message);
+	await sleep(settleMs);
+	if (!isStaged(adapter.read(exec, target), message)) return {
+		taken: true,
+		resubmits: 0
+	};
+	for (let attempt = 1; attempt <= attempts; attempt++) {
+		adapter.submit(exec, target);
+		await sleep(settleMs);
+		if (!isStaged(adapter.read(exec, target), message)) return {
+			taken: true,
+			resubmits: attempt
+		};
+	}
+	throw new Error(`nudge failed: peer at pane ${target.id} never took the turn — input still staged after ${attempts} re-submit attempts`);
+}
+//#endregion
+//#region src/backend.ts
+/**
+* Resolve the raw backend for the multiplexer this process is inside, via the two-mode mux probe
+* (`$CYBER_MUX` fast-path/override, else ancestry discovery from `$$` falling back to the
+* `$TMUX`/`$HERDR_ENV`/`$WEZTERM_PANE`/`$ZELLIJ` hint when the walk is inconclusive) —
+* tmux/herdr/wezterm/zellij map to their adapters; anything else throws, because a caller asking to
+* drive panes with no multiplexer has an unmet precondition, and a loud, actionable failure beats a
+* silent no-op.
+*
+* The zellij adapter is bound to the ambient session name (`$ZELLIJ_SESSION_NAME`) at resolution — it
+* reports that as `OpenedPane.workspace`, so the session name has to come from the SAME `env` the
+* probe reads. A missing name simply omits `workspace`; see `createZellijAdapter`.
+*
+* `screen` is a KNOWN mux — the probe detects it (ancestry) and honors it as an override (fast-path)
+* — but it is NOT a drivable backend, so it throws its OWN message naming the reason rather than the
+* generic "no multiplexer" one. That distinction is the whole point of issue #45: a caller who
+* pinned `CYBER_MUX=screen` declared a real multiplexer, and telling them "run inside a multiplexer"
+* would be a lie. The empirical probe behind the rejection is recorded in the ADR log
+* (`.agents/spec/design/decisions`): GNU Screen addresses its split regions POSITIONALLY (no
+* per-pane id), and `$WINDOW` is left unset in panes opened via `screen -X`, so a driver-created
+* pane has no stable identity to send to, read from, self-identify by, or enumerate — the exact
+* affordance `SessionTarget.id`/`currentPane`/`LivePane.id` are load-bearing on, and the exact one
+* wezterm (#47) had and screen lacks. Keeping the value KNOWN-but-rejected honors the override's
+* whole reason to exist: pinning it tells the caller the truth immediately instead of silently
+* discovering something else.
+*
+* Returns the PURE, exec-injected `MuxAdapter` seam — the one whose methods each take an `Exec`.
+* `resolveMux` binds one of these into a `MuxSession`; this is the lower layer, exported for a caller
+* that wants to thread its own runner per call rather than bind one. Not in a multiplexer? Gate on
+* `probeMultiplexer(env).mux !== 'none'` first — that answer never throws.
+*/
+function resolveMuxAdapter(env, exec = nodeExec) {
+	const probe = probeMultiplexer(exec, env);
+	if (probe.mux === "tmux") return tmuxMuxAdapter;
+	if (probe.mux === "herdr") return herdrMuxAdapter;
+	if (probe.mux === "wezterm") return weztermMuxAdapter;
+	if (probe.mux === "zellij") return createZellijAdapter({ session: env["ZELLIJ_SESSION_NAME"] });
+	if (probe.mux === "screen") throw new Error("cyber-mux detected GNU Screen, which it cannot drive: Screen addresses its split regions positionally (no per-pane id) and leaves $WINDOW unset in panes opened via `screen -X`, so a pane has no stable identity to send to, read from, or self-identify by. Run inside tmux ($TMUX), herdr ($HERDR_ENV=1), wezterm ($WEZTERM_PANE set), or zellij ($ZELLIJ set) instead.");
+	throw new Error("cyber-mux requires a session backend — run inside tmux ($TMUX), herdr ($HERDR_ENV=1), wezterm ($WEZTERM_PANE set), or zellij ($ZELLIJ set)");
+}
+/**
+* Resolve the multiplexer this process is inside and return it as a `MuxSession` with `exec` BOUND —
+* the ergonomic entry point. `deps.exec` (default `nodeExec`) runs the detection probe AND is the
+* default runner every method binds; a per-call `deps` overrides it.
+*
+* Throws when no supported multiplexer is detected (see `resolveMuxAdapter`); gate on
+* `probeMultiplexer(env).mux !== 'none'` first if a caller runs with-or-without one. For the pure
+* exec-injected seam, reach for `resolveMuxAdapter` instead.
+*/
+function resolveMux(env, deps) {
+	const boundExec = deps?.exec ?? nodeExec;
+	const raw = resolveMuxAdapter(env, boundExec);
+	const pick = (d) => d?.exec ?? boundExec;
+	return {
+		name: raw.name,
+		...raw.canSizeSplits !== void 0 ? { canSizeSplits: raw.canSizeSplits } : {},
+		callerPane: () => callerPane(raw, env),
+		open: (opts, d) => raw.open(pick(d), opts),
+		rename: (target, tier, name, d) => raw.rename(pick(d), target, tier, name),
+		group: (target, group, name, d) => raw.group(pick(d), target, group, name),
+		sendText: (target, text, d) => raw.sendText(pick(d), target, text),
+		sendKeys: (target, keys, d) => raw.sendKeys(pick(d), target, keys),
+		submit: (target, text, d) => raw.submit(pick(d), target, text),
+		read: (target, opts, d) => raw.read(pick(d), target, opts),
+		focus: (target, d) => raw.focus(pick(d), target),
+		teardown: (target, d) => raw.teardown(pick(d), target),
+		paneExists: (target, d) => raw.paneExists(pick(d), target),
+		isPaneFocused: (target, d) => raw.isPaneFocused(pick(d), target),
+		listPanes: (d) => raw.listPanes(pick(d)),
+		nudge: (target, message, opts, d) => nudge(raw, pick(d), target, message, opts),
+		...raw.worktree ? { worktree: bindWorktree(raw.worktree, pick) } : {},
+		...raw.regions ? { regions: bindRegions(raw.regions, pick) } : {}
+	};
+}
+function bindWorktree(wt, pick) {
+	return {
+		createInWorkspace: (opts, d) => wt.createInWorkspace(pick(d), opts),
+		openInWorkspace: (opts, d) => wt.openInWorkspace(pick(d), opts),
+		bindings: (opts, d) => wt.bindings(pick(d), opts),
+		releaseWorkspace: (workspace, d) => wt.releaseWorkspace(pick(d), workspace)
+	};
+}
+function bindRegions(regions, pick) {
+	return {
+		describeRegion: (target, d) => regions.describeRegion(pick(d), target),
+		describeWorkspace: (target, d) => regions.describeWorkspace(pick(d), target)
+	};
+}
+/**
+* This process's own pane, as something `adapter` can address — `MuxOpenOptions.from`'s intended
+* argument for a `pane:*` open, so a split lands on the caller rather than on whichever pane the
+* user is looking at (see `from`'s note for why each backend's default gets that wrong).
+*
+* `undefined` when this session is in no pane, or in a pane belonging to a *different* multiplexer
+* than `adapter` drives — that mismatch is reachable (a `$TMUX_PANE` inherited into a herdr pane,
+* `$CYBER_MUX` overridden to the other backend), and handing one backend the other's pane id would
+* turn a self-identity mixup into a split of some unrelated pane. Falling back to the backend's own
+* default is the conservative answer: still possibly the wrong pane, but never a foreign id.
+*
+* A `MuxSession` exposes this bound as `mux.callerPane()`; this free form is for the raw seam.
+*/
+function callerPane(adapter, env) {
+	const self = currentPane(env);
+	return self && self.mux === adapter.name ? { id: self.pane } : void 0;
+}
+//#endregion
+export { envFallback as _, nudge as a, createZellijAdapter as c, weztermMuxAdapter as d, nodeNewId as f, herdrMuxAdapter as g, tmuxMuxAdapter as h, isStaged as i, zellijMuxAdapter as l, TMUX_WORKSPACE_GROUP_OPTION as m, resolveMux as n, currentPane as o, TMUX_TAB_NAME_OPTION as p, resolveMuxAdapter as r, probeMultiplexer as s, callerPane as t, createWeztermAdapter as u };
+
+//# sourceMappingURL=backend-DnrbmL6N.mjs.map