cyber-mux 0.1.0

package/dist/cli.mjs

@@ -0,0 +1,3716 @@
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+//#region src/exec.ts
+const realExec = (cmd, args) => {
+	try {
+		const out = execFileSync(cmd, args, {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		}).trim();
+		realExec.lastError = void 0;
+		return out;
+	} catch (err) {
+		const stderr = err.stderr;
+		realExec.lastError = String(stderr ?? "").trim() || void 0;
+		return null;
+	}
+};
+/**
+* A failure message carrying the runner's reason for it, when there is one. The backend's own words
+* verbatim — never a paraphrase, and never a guess: a refused split may be a region too small, or a
+* server that is simply gone, and only the backend knows which.
+*/
+function withReason(exec, message) {
+	return exec.lastError ? `${message} — ${exec.lastError}` : message;
+}
+//#endregion
+//#region src/mux-probe.ts
+const KNOWN_MUX = [
+	"tmux",
+	"herdr",
+	"wezterm",
+	"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 this backend (#47), the same
+* fast-path extension `$TMUX_PANE`/`$HERDR_PANE_ID` already get. 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
+};
+/**
+* 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).
+* 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" : "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
+	};
+}
+/**
+* Two-mode multiplexer detection.
+*
+* Fast-path: `$CYBER_MUX` (tmux | herdr | 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.
+*
+* 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 = {}) {
+	if (isKnownMux(env.CYBER_MUX)) return {
+		mux: env.CYBER_MUX,
+		...env.CYBER_MUX_PANE ? { pane: env.CYBER_MUX_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: /^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" ? PANE_ENV[mux](env) : void 0;
+}
+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 {
+			mux: entry.mux,
+			pane: paneFor(entry.mux, env),
+			via: "ancestry"
+		};
+		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 {
+		mux: "tmux",
+		pane: paneFor("tmux", env),
+		via: "ancestry"
+	};
+	if (env.HERDR_ENV) return {
+		mux: "herdr",
+		pane: paneFor("herdr", env),
+		via: "ancestry"
+	};
+	if (env.WEZTERM_PANE) return {
+		mux: "wezterm",
+		pane: paneFor("wezterm", env),
+		via: "ancestry"
+	};
+	return {
+		mux: "none",
+		via: "ancestry"
+	};
+}
+//#endregion
+//#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/worktree.ts
+/**
+* This module's own refusals and failures — plain cyber-mux prose, never a dependency's raw words.
+* `reportWorktreeFailure` (`cli.ts`) forwards a `WorktreeGitError`'s message onto stdout verbatim
+* because it is safe to: everything thrown here is this CLI's own text. Anything else that reaches
+* that catch-all (a `session.tmux.ts`/`session.herdr.ts` throw, which embeds the backend's own name
+* and its raw stderr via `withReason`) is a different case and is translated, not forwarded.
+*/
+var WorktreeGitError = class extends Error {};
+/** The only worktree backend at MVP — plain `git worktree`. */
+const gitWorktreeAdapter = {
+	add(exec, opts) {
+		const args = [
+			"-C",
+			opts.primaryRoot,
+			"worktree",
+			"add",
+			"-b",
+			opts.branch,
+			opts.path
+		];
+		if (opts.base) args.push(opts.base);
+		if (exec("git", args) === null) throw new WorktreeGitError(`git worktree add failed for ${opts.path}`);
+		return {
+			root: resolve(opts.path),
+			branch: opts.branch
+		};
+	},
+	remove(exec, path, opts) {
+		if (exec("git", [
+			"-C",
+			opts.primaryRoot,
+			"worktree",
+			"remove",
+			path,
+			"--force"
+		]) === null) throw new WorktreeGitError(`git worktree remove failed for ${path}`);
+	}
+};
+/**
+* Resolve the primary checkout's root regardless of whether the caller's cwd is the primary
+* checkout or a linked worktree — `--git-common-dir` always points at the main repo's `.git`.
+*/
+function resolvePrimaryRoot(exec) {
+	const commonDir = exec("git", [
+		"rev-parse",
+		"--path-format=absolute",
+		"--git-common-dir"
+	]);
+	if (!commonDir) throw new WorktreeGitError("cannot resolve the primary checkout — not inside a git repository");
+	return dirname(commonDir);
+}
+/**
+* The single normalization point for every path that gets MATCHED against another — a multiplexer
+* reports its own checkout paths, and those only line up with git's if both sides are resolved the
+* same way (a symlinked repo, or macOS's `/tmp` → `/private/tmp`, otherwise silently fails to
+* match). Falls back to `resolve` for a path that isn't on disk, where there is no link to follow.
+*/
+function normalizeWorktreePath(path) {
+	try {
+		return realpathSync.native(path);
+	} catch {
+		return resolve(path);
+	}
+}
+/**
+* Every worktree of the repo, straight from git. These are the facts — path, branch, linked,
+* prunable — on EVERY backend: a multiplexer that also happens to enumerate worktrees is only
+* re-reading git, so reading them here is what keeps two backends from ever disagreeing about the
+* same worktree. The one fact git cannot answer — which workspace a worktree is open in — is joined
+* in by the caller.
+*/
+function listWorktreesFromGit(exec, primaryRoot) {
+	const out = exec("git", [
+		"-C",
+		primaryRoot,
+		"worktree",
+		"list",
+		"--porcelain"
+	]);
+	if (!out) return [];
+	const normalizedPrimary = normalizeWorktreePath(primaryRoot);
+	return out.split("\n\n").map((record) => record.trim()).filter((record) => record.startsWith("worktree ")).map((record) => {
+		const lines = record.split("\n");
+		const root = normalizeWorktreePath(lines[0].slice(9));
+		return {
+			root,
+			branch: lines.find((line) => line.startsWith("branch "))?.slice(7).replace(/^refs\/heads\//, ""),
+			linked: root !== normalizedPrimary,
+			prunable: lines.some((line) => line === "prunable" || line.startsWith("prunable "))
+		};
+	});
+}
+/**
+* Refuse the primary checkout: a spawned session's resolved worktree root must never be the primary
+* checkout itself.
+*/
+function assertDistinctFromPrimary(worktreeRoot, primaryRoot) {
+	if (resolve(worktreeRoot) === resolve(primaryRoot)) throw new WorktreeGitError("refusing to run in the primary checkout — spawn a worktree distinct from the primary checkout");
+}
+/**
+* Default worktree location — a sibling of the primary checkout (`<parent>/<repo>.worktrees/<name>`),
+* never nested inside the primary's own working tree (an untracked-but-present nested worktree
+* pollutes `git status` in the primary and confuses tools that walk the tree expecting only the
+* primary's own files).
+*/
+function resolveWorktreePath(primaryRoot, name) {
+	return join(dirname(primaryRoot), `${basename(primaryRoot)}.worktrees`, name);
+}
+/** Whether a worktree has uncommitted changes — gates a safe remove unless the caller forces it. */
+function isDirty(exec, worktreeRoot) {
+	return !!exec("git", [
+		"-C",
+		worktreeRoot,
+		"status",
+		"--porcelain"
+	]);
+}
+/**
+* Remove a worktree the safe way: refuse the primary checkout (absolute — `force` never overrides
+* it), tolerate a worktree already gone from disk, and refuse to discard uncommitted changes unless
+* `force` is set.
+*
+* `releaseBinding` detaches whatever a multiplexer has bound to this checkout (a herdr workspace).
+* It stays an opaque callback so this module owes nothing to the session seam. Its ORDER is a
+* specified property, not an incidental one:
+*
+*  - every gate runs BEFORE it, so a REFUSED removal has no side effect — a dirty worktree that
+*    fails the check must not lose its workspace on the way out;
+*  - it runs BEFORE git removes the checkout, so no workspace is ever left pointing at a deleted
+*    directory (and a held cwd can block the removal outright).
+*/
+function removeWorktreeSafely(exec, path, opts) {
+	assertDistinctFromPrimary(path, opts.primaryRoot);
+	if (!existsSync(path)) {
+		opts.releaseBinding?.();
+		return;
+	}
+	if (!opts.force && isDirty(exec, path)) throw new WorktreeGitError(`worktree "${path}" has uncommitted changes — pass --force to discard them`);
+	opts.releaseBinding?.();
+	gitWorktreeAdapter.remove(exec, path, { primaryRoot: opts.primaryRoot });
+}
+//#endregion
+//#region src/session.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 herdrSessionAdapter = {
+	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",
+				"--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) herdrSessionAdapter.rename(exec, opened, "pane", opts.label);
+		}
+		if (opts.launch) herdrSessionAdapter.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) => ({
+			id: p.pane_id,
+			mux: "herdr",
+			harness: p.agent || void 0,
+			cwd: p.cwd,
+			label: p.label || void 0
+		}));
+	},
+	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 `describeRegion` in `session.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) herdrSessionAdapter.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/session.tmux.ts
+/**
+* The tmux window user option `SessionOpenOptions.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 tmuxSessionAdapter = {
+	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) tmuxSessionAdapter.group(exec, { id: windowId }, opts.workspaceGroup);
+		if (!window && opts.label) tmuxSessionAdapter.rename(exec, target, "pane", opts.label);
+		if (opts.launch) tmuxSessionAdapter.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;
+		}
+		tmuxSessionAdapter.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 !== "");
+	},
+	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
+	* (`SessionOpenOptions.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/session.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.
+*/
+const weztermSessionAdapter = {
+	name: "wezterm",
+	canSizeSplits: true,
+	open(exec, opts) {
+		const at = opts.at ?? "tab";
+		if (at === "workspace") {
+			const workspace = opts.label ?? `cyber-mux-${randomUUID().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(exec, opened, opts.env, opts.launch);
+			return opened;
+		}
+		if (at === "tab") {
+			const out = exec("wezterm", [
+				"cli",
+				"spawn",
+				"--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) weztermSessionAdapter.rename(exec, { id: opened.tab }, "tab", opts.label);
+			runLaunch(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(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) {
+			weztermSessionAdapter.sendKeys(exec, target, ["Enter"]);
+			return;
+		}
+		weztermSessionAdapter.sendText(exec, target, text);
+		weztermSessionAdapter.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;
+		});
+	}
+};
+/**
+* `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);
+}
+/** `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(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) weztermSessionAdapter.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/backend.ts
+/**
+* Backend selection via the two-mode mux probe (`$CYBER_MUX` fast-path/override, else ancestry
+* discovery from `$$` falling back to the `$TMUX`/`$HERDR_ENV`/`$WEZTERM_PANE` hint when the walk is
+* inconclusive) — tmux/herdr/wezterm map to their existing adapters; anything else is a clear error.
+*/
+function selectSessionAdapter(env, exec = realExec) {
+	const probe = probeMultiplexer(exec, env);
+	if (probe.mux === "tmux") return tmuxSessionAdapter;
+	if (probe.mux === "herdr") return herdrSessionAdapter;
+	if (probe.mux === "wezterm") return weztermSessionAdapter;
+	throw new Error("cyber-mux requires a session backend — run inside tmux ($TMUX), herdr ($HERDR_ENV=1), or wezterm ($WEZTERM_PANE set)");
+}
+/**
+* This process's own pane, as something `adapter` can address — `SessionOpenOptions.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.
+*/
+function callerPane(adapter, env) {
+	const self = currentPane(env);
+	return self && self.mux === adapter.name ? { id: self.pane } : void 0;
+}
+//#endregion
+//#region src/output.ts
+function printJson(data) {
+	console.log(JSON.stringify(data, null, 2));
+}
+function printFields(fields) {
+	const entries = Object.entries(fields).filter(([, v]) => v != null);
+	if (entries.length === 0) return;
+	const width = Math.max(...entries.map(([k]) => k.length));
+	for (const [key, val] of entries) console.log(`${key.padEnd(width)}  ${val}`);
+}
+/**
+* Render #9 suggestions as a `help[N]:` block on stdout — inside the structured payload, the stream an
+* agent reads, not stderr it never does. Each entry is a message line and its command, indented under
+* it. Prints NOTHING for an empty list: a self-contained result owes no suggestion (#9's
+* omit-when-self-contained rule), so the block never appears as noise.
+*/
+function printHelp(entries) {
+	entries.forEach((entry, i) => {
+		console.log(`help[${i}]: ${entry.message}`);
+		console.log(`  -> ${entry.command}`);
+	});
+}
+function printTable(items, cols) {
+	if (items.length === 0) {
+		console.log("(none)");
+		return;
+	}
+	const widths = cols.map((c) => Math.max(c.label.length, ...items.map((i) => c.get(i).length)));
+	console.log(cols.map((c, i) => c.label.toUpperCase().padEnd(widths[i])).join("  "));
+	console.log(widths.map((w) => "-".repeat(w)).join("  "));
+	for (const item of items) console.log(cols.map((c, i) => c.get(item).padEnd(widths[i])).join("  "));
+}
+function getFormat() {
+	const argv = process.argv;
+	const fmtIdx = argv.indexOf("--format");
+	if (fmtIdx !== -1) return argv[fmtIdx + 1];
+	if (argv.includes("--json")) return "json";
+}
+/**
+* Whether the caller asked for machine-readable output. Exported because `output()` is not the only
+* writer that owes it: a structured ERROR is rendered by `reportError` (`cli-error.ts`) rather than
+* through `output()`, and it has to honor `--format json` exactly as the success path does. Both write
+* stdout — AXI's stream for everything the agent consumes, errors included.
+*/
+function isJsonOutput() {
+	return getFormat() === "json";
+}
+function output(data, readable) {
+	if (isJsonOutput()) printJson(data);
+	else readable();
+}
+//#endregion
+//#region src/cli-error.ts
+/**
+* The error surface — AXI's #6, made concrete.
+*
+* Every failure is a STRUCTURED, CODED error on **stdout**, because stdout is the stream AXI reserves
+* for what the agent consumes — data, errors and suggestions alike — while stderr is defined as debug
+* the agent does not read. A report whose whole purpose is telling a caller what went wrong and how to
+* fix it is the last thing that belongs on the ignored stream. This does not muddy the payload: a verb
+* either succeeds and writes its result or fails and writes its error, never both, so the exit code
+* tells the two apart before anything is parsed.
+*
+* Three things every error carries, and they are not decoration:
+* - a **stable `code`** a script matches on, so one failure mode is told from another without parsing
+*   prose (`no-mux` is not `pane-not-found` is not `ambiguous-pane`);
+* - a **`help`** line naming THIS CLI's command that fixes it — never "see --help", and never a
+*   dependency's own name: an agent handed a raw tmux/herdr diagnostic cannot act on it through
+*   cyber-mux, so a backend's text is TRANSLATED here rather than forwarded;
+* - an **`exit`** code that separates a usage error (2 — a missing or malformed argument, whose fix is
+*   a different invocation) from a genuine operation failure (1).
+*/
+var CliError = class extends Error {
+	code;
+	help;
+	exit;
+	extra;
+	constructor(code, message, help, exit, extra) {
+		super(message);
+		this.code = code;
+		this.help = help;
+		this.exit = exit;
+		this.extra = extra;
+		this.name = "CliError";
+	}
+};
+/** The stable code the ambiguity error carries, in both formats — what a caller matches on. */
+const AMBIGUOUS_CODE = "ambiguous-pane";
+/**
+* An ambiguous locator — a `CliError` like any other, so the one renderer and the one verb-boundary
+* catch handle it with no special case, and so a caller sees the same `{ code, help, exit }` shape it
+* sees for every other failure.
+*
+* It is THROWN rather than reported where it is found: reporting in place would mean exiting from
+* inside `resolveTarget`, and a verb's own catch-all could then flatten an exit-2 ambiguity into an
+* exit-1 generic failure behind its back. A typed error is what makes the ambiguity visible to every
+* catch it passes through, so each one rethrows it deliberately instead of swallowing it by accident.
+*
+* Each candidate carries its id, its label and its cwd: the id is the RETRY — paste it back and the
+* ambiguity is gone, since an id outranks every name — and the cwd is what actually tells three panes
+* all labeled `worker` apart.
+*/
+var AmbiguousPaneError = class extends CliError {
+	locator;
+	candidates;
+	constructor(locator, candidates) {
+		super(AMBIGUOUS_CODE, `"${locator}" matches ${candidates.length} panes — an id resolves it`, `retry with one of the ids: ${candidates.map((c) => c.id).join(" ")}`, 2, { candidates });
+		this.locator = locator;
+		this.candidates = candidates;
+		this.name = "AmbiguousPaneError";
+	}
+};
+/**
+* The ONE renderer — every coded failure reaches stdout through here, and exits.
+*
+* `--format json` emits the machine form: a single `{ error: { code, message, help, ...extra } }`
+* object, the stable code first, no free-text prose beside it. The readable form leads its human line
+* with the same `code` token a script branches on — so a person scanning the terminal sees exactly
+* what a `--format json` consumer matches on — then the `help` line, then (for an ambiguity) one line
+* per candidate: `<id>  <label>  <cwd>`, the id-first shape whose first column is the retry.
+*/
+function reportError(e) {
+	if (isJsonOutput()) console.log(JSON.stringify({ error: {
+		code: e.code,
+		message: e.message,
+		help: e.help,
+		...e.extra
+	} }, null, 2));
+	else {
+		console.log(`error: ${e.code}: ${e.message}`);
+		console.log(`help: ${e.help}`);
+		const candidates = e.extra?.candidates;
+		if (candidates) for (const c of candidates) console.log(`  ${c.id}  ${c.label ?? ""}  ${c.cwd ?? ""}`);
+	}
+	process.exit(e.exit);
+}
+//#endregion
+//#region src/cli-options.ts
+/** Output format shared by every command: `text` (human), `json`, or `agent`. */
+const FORMAT_OPTION = new Option("--format <format>", "Output format").choices([
+	"text",
+	"json",
+	"agent"
+]);
+/**
+* Accumulate one `--env KEY=VALUE` into the running map. Repeatable: commander calls this once per
+* flag, threading the previous map through, so `--env A=1 --env B=2` collects both. Rejecting a
+* malformed pair from HERE — the parser, before the action runs — is what makes "rejected before any
+* side effect" hold on every verb, worktree-creating ones included. The KEY is everything before the
+* first `=`, the VALUE everything after it: a value may contain `=` (a URL query, a base64 pad) and a
+* KEY may not, so the first `=` is the only unambiguous split. A missing `=` is malformed; a present
+* `=` with nothing after it is a deliberate empty value, not an error.
+*/
+function collectEnv(pair, previous = {}) {
+	const eq = pair.indexOf("=");
+	if (eq <= 0) throw new InvalidArgumentError(`expected KEY=VALUE, got "${pair}"`);
+	return {
+		...previous,
+		[pair.slice(0, eq)]: pair.slice(eq + 1)
+	};
+}
+/**
+* `--env KEY=VALUE`, repeatable — the CLI door to the seam's env option, on every verb that opens a
+* pane. One shared Option so the collector, the split rule, and the rejection are defined once and
+* every verb inherits them, the way `AT_OPTION`/`LABEL_OPTION` are shared. Conflicts with `--template`,
+* whose template owns its own panes' env; the two verbs that carry `--template` refuse the pair.
+*/
+const ENV_OPTION = new Option("--env <pair>", "Environment variable KEY=VALUE (repeatable)").argParser(collectEnv).conflicts("template");
+/** Placement for a newly opened pane, matching `SessionPlacement`. */
+const AT_OPTION = new Option("--at <placement>", "Where to place the new pane").choices([
+	"pane:right",
+	"pane:down",
+	"tab",
+	"workspace"
+]);
+/**
+* Name for whatever `--at` opens. Host-neutral because every backend names every tier: on herdr a
+* workspace/tab/pane label, on tmux a window name (where `workspace` and `tab` both collapse to a
+* Window) or a pane title.
+*/
+const LABEL_OPTION = new Option("--label <label>", "Name for the opened workspace/tab/pane");
+//#endregion
+//#region src/template.ts
+const ARRANGES = [
+	"tiled",
+	"even-horizontal",
+	"even-vertical"
+];
+/**
+* A template name is `[a-z0-9][a-z0-9-]*` and must equal its file's stem, so a name can never
+* traverse out of the templates directory. Checked BEFORE any file is read — a name is a lookup key,
+* not a path, and treating it as one is how `../../../etc/pwd` becomes a read.
+*/
+const TEMPLATE_NAME = /^[a-z0-9][a-z0-9-]*$/;
+function isValidTemplateName(name) {
+	return TEMPLATE_NAME.test(name);
+}
+/** Parse a template's bytes. Throws on malformed JSON; SCHEMA validity is `validateTemplate`'s job. */
+function parseTemplate(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`template is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/**
+* Every validation error, not the first — CI's whole reason to run this is to be told everything
+* wrong at once. Each error names its own JSON path (`root.second.first.cwd`), so an error points at
+* a place in the file rather than describing one. An empty array means valid.
+*
+* `stem` is the filename's stem when there is a file to compare against; the `name` field must equal
+* it. The redundancy is the point: a copied template that kept its old name fails loudly.
+*/
+function validateTemplate(template, stem) {
+	const errors = [];
+	if (typeof template !== "object" || template === null || Array.isArray(template)) return ["template: must be a JSON object"];
+	const t = template;
+	if (t.name === void 0) errors.push("name: required — it must equal the template filename's stem");
+	else if (typeof t.name !== "string") errors.push("name: must be a string");
+	else if (stem !== void 0 && t.name !== stem) errors.push(`name: filename stem is "${stem}" but the name field is "${t.name}" — they must match`);
+	if (t.description !== void 0 && typeof t.description !== "string") errors.push("description: must be a string");
+	const hasRoot = t.root !== void 0;
+	const hasPanes = t.panes !== void 0;
+	const hasTabs = t.tabs !== void 0;
+	const declared = [
+		hasRoot && "root",
+		hasPanes && "panes",
+		hasTabs && "tabs"
+	].filter((d) => Boolean(d));
+	if (declared.length > 1) errors.push(`root/panes/tabs: exactly one of "root", "panes" or "tabs" may be set — this template sets ${declared.map((d) => `"${d}"`).join(" and ")}`);
+	else if (declared.length === 0) errors.push("root/panes/tabs: exactly one of \"root\", \"panes\" or \"tabs\" must be set — this template sets none");
+	validateTree(t, "", errors);
+	if (hasTabs) if (!Array.isArray(t.tabs)) errors.push("tabs: must be an array of tab objects");
+	else if (t.tabs.length === 0) errors.push("tabs: must name at least one tab — a workspace of no tabs is not one");
+	else t.tabs.forEach((tab, i) => {
+		validateTab(tab, `tabs[${i}]`, errors);
+	});
+	return errors;
+}
+/**
+* One tab: the same `root`/`panes` tree a top-level template declares, plus its own label. Every rule
+* the template tier holds holds here for the identical reason — hence the shared `validateTree`
+* rather than a parallel set of checks that could drift.
+*/
+function validateTab(tab, path, errors) {
+	if (typeof tab !== "object" || tab === null || Array.isArray(tab)) {
+		errors.push(`${path}: must be an object`);
+		return;
+	}
+	const n = tab;
+	if (n.cwd !== void 0) errors.push(`${path}.cwd: a template must never set cwd — pass --cwd at apply time, or use "dir" for a subdirectory under it`);
+	if (n.label !== void 0 && (typeof n.label !== "string" || n.label === "")) errors.push(`${path}.label: must be a non-empty string`);
+	const hasRoot = n.root !== void 0;
+	const hasPanes = n.panes !== void 0;
+	if (hasRoot && hasPanes) errors.push(`${path}: exactly one of "root" or "panes" may be set — this tab sets both`);
+	else if (!hasRoot && !hasPanes) errors.push(`${path}: exactly one of "root" or "panes" must be set — this tab sets neither`);
+	validateTree(n, path, errors);
+}
+/**
+* The `root` / `panes` / `arrange` triple, wherever it sits. `path` is `''` at the template tier and
+* `tabs[i]` inside a tab, so an error points at a place in the file either way. Whether exactly one of
+* the two spellings is present is the CALLER's check — the template tier weighs `tabs` in that choice
+* and a tab does not.
+*/
+function validateTree(t, path, errors) {
+	const at = (key) => path === "" ? key : `${path}.${key}`;
+	if (t.arrange !== void 0 && (typeof t.arrange !== "string" || !ARRANGES.includes(t.arrange))) errors.push(`${at("arrange")}: must be one of ${ARRANGES.join(", ")}`);
+	if (t.root !== void 0) validateNode(t.root, at("root"), errors);
+	if (t.panes !== void 0) if (!Array.isArray(t.panes)) errors.push(`${at("panes")}: must be an array of pane objects`);
+	else if (t.panes.length === 0) errors.push(`${at("panes")}: must name at least one pane`);
+	else t.panes.forEach((pane, i) => {
+		validatePaneFields(pane, `${at("panes")}[${i}]`, errors);
+	});
+}
+function validateNode(node, path, errors) {
+	if (typeof node !== "object" || node === null || Array.isArray(node)) {
+		errors.push(`${path}: must be an object with a "type" of "pane" or "split"`);
+		return;
+	}
+	const n = node;
+	if (n.type === "pane") {
+		validatePaneFields(n, path, errors);
+		return;
+	}
+	if (n.type !== "split") {
+		errors.push(`${path}.type: must be "pane" or "split"`);
+		return;
+	}
+	if (n.direction !== "right" && n.direction !== "down") errors.push(`${path}.direction: must be "right" or "down"`);
+	if (n.ratio !== void 0) {
+		if (typeof n.ratio !== "number" || !Number.isFinite(n.ratio) || n.ratio <= 0 || n.ratio >= 1) errors.push(`${path}.ratio: must be a number strictly between 0 and 1 — got ${JSON.stringify(n.ratio)}`);
+	}
+	if (n.first === void 0) errors.push(`${path}.first: required`);
+	else validateNode(n.first, `${path}.first`, errors);
+	if (n.second === void 0) errors.push(`${path}.second: required`);
+	else validateNode(n.second, `${path}.second`, errors);
+}
+function validatePaneFields(pane, path, errors) {
+	if (typeof pane !== "object" || pane === null || Array.isArray(pane)) {
+		errors.push(`${path}: must be an object`);
+		return;
+	}
+	const p = pane;
+	if (p.cwd !== void 0) errors.push(`${path}.cwd: a template must never set cwd — pass --cwd at apply time, or use "dir" for a subdirectory under it`);
+	if (p.label !== void 0 && (typeof p.label !== "string" || p.label === "")) errors.push(`${path}.label: must be a non-empty string`);
+	if (p.command !== void 0 && typeof p.command !== "string") errors.push(`${path}.command: must be a string`);
+	if (p.env !== void 0) {
+		if (typeof p.env !== "object" || p.env === null || Array.isArray(p.env)) errors.push(`${path}.env: must be an object of string values`);
+		else for (const [key, value] of Object.entries(p.env)) if (typeof value !== "string") errors.push(`${path}.env.${key}: must be a string`);
+	}
+	if (p.dir !== void 0) {
+		if (typeof p.dir !== "string" || p.dir === "") errors.push(`${path}.dir: must be a non-empty string`);
+		else if (dirEscapes(p.dir)) errors.push(`${path}.dir: must be a relative subdirectory under the apply-time target — "${p.dir}" escapes it`);
+	}
+}
+/**
+* Whether a `dir` can reach outside the apply-time target. Absolute is rejected because a
+* machine-specific path must never reach a template by any road; `..` is rejected because it is the
+* other road to the same place. Checked on the RAW string as well as the normalized one — a `..` that
+* cancels out (`packages/../../outside` normalizes past the root, but `a/../b` does not) is still an
+* author saying something they did not mean.
+*/
+function dirEscapes(dir) {
+	if (isAbsolute(dir)) return true;
+	if (dir.split(/[/\\]+/).includes("..")) return true;
+	return normalize(dir).startsWith("..");
+}
+/**
+* The tree a `TemplateTree` describes, whichever form it was written in — the ONE place `panes`/`arrange`
+* becomes a tree, so `template show --desugar` and the apply walk can never disagree about what a flat
+* template means.
+*
+* It takes either carrier of a `TemplateTree`, so a `TabNode` and a single-tab `Template` resolve
+* through THIS function rather than through two that happen to agree today: the sugar is a property of
+* a pane pool, not of where the pool sits, so a tab of 3 panes means what a top-level pool of 3 panes
+* means. One desugarer, one answer.
+*/
+function resolveTree(tree) {
+	if (tree.root) return tree.root;
+	return desugar(tree.panes ?? [], tree.arrange ?? "tiled");
+}
+/**
+* Expand the flat sugar into the canonical tree. A pure function of `panes.length` and `arrange`
+* ALONE — no backend, no region size — which is exactly what lets `show --desugar` print the tree
+* apply will build, and what makes one template mean one geometry everywhere.
+*
+* tmux's native `select-template tiled` is deliberately NOT used even though it exists and would be one
+* call: it implements tmux's own grid algorithm, herdr has no equivalent, and reaching for it would
+* mean the same template producing a visibly different geometry per backend — and a third on
+* whatever backend comes next. Owning the desugaring is what makes a backend-agnostic schema worth
+* having, and it costs exactly one saved call.
+*/
+function desugar(panes, arrange) {
+	if (panes.length === 0) throw new Error("a flat template must name at least one pane");
+	const leaves = panes.map(toPaneNode$1);
+	if (arrange === "even-horizontal") return comb(leaves, "right");
+	if (arrange === "even-vertical") return comb(leaves, "down");
+	return tiled(leaves);
+}
+function toPaneNode$1(pane) {
+	const node = { type: "pane" };
+	if (pane.label !== void 0) node.label = pane.label;
+	if (pane.command !== void 0) node.command = pane.command;
+	if (pane.env !== void 0) node.env = pane.env;
+	if (pane.dir !== void 0) node.dir = pane.dir;
+	return node;
+}
+/**
+* The even comb: split at `1/n`, then `1/(n-1)`, … so all `n` regions end EQUAL.
+*
+* The ratios are the whole point and the easy thing to get wrong. Splitting evenly at `0.5` each time
+* would yield 1/2, 1/4, 1/4 — a comb that looks like a row and is not one. Peeling `1/n` off the
+* front leaves `(n-1)/n` for the rest, which the next `1/(n-1)` divides into another exact `1/n`.
+*/
+function comb(nodes, direction) {
+	const [head, ...rest] = nodes;
+	if (rest.length === 0) return head;
+	return {
+		type: "split",
+		direction,
+		ratio: 1 / nodes.length,
+		first: head,
+		second: comb(rest, direction)
+	};
+}
+/**
+* A balanced grid: `ceil(sqrt(n))` columns laid left-to-right, each column an even stack. Both axes
+* are the same even comb, so the geometry is exact rather than approximate at every `n`.
+*
+* For `n = 4` this is one `right` at `0.5` with a `down` at `0.5` in each half — a true 2x2. `n = 1`
+* falls out as the bare pane with no split at all, rather than being special-cased.
+*/
+function tiled(leaves) {
+	if (leaves.length === 1) return leaves[0];
+	return comb(distribute(leaves, Math.ceil(Math.sqrt(leaves.length))).map((column) => comb(column, "down")), "right");
+}
+/** Split `items` into `groups` contiguous chunks as evenly as possible, remainder to the front. */
+function distribute(items, groups) {
+	const out = [];
+	const base = Math.floor(items.length / groups);
+	let remainder = items.length % groups;
+	let index = 0;
+	for (let g = 0; g < groups; g++) {
+		const size = base + (remainder > 0 ? 1 : 0);
+		if (remainder > 0) remainder--;
+		out.push(items.slice(index, index + size));
+		index += size;
+	}
+	return out;
+}
+/** Every pane in the tree, in template order — a depth-first walk taking `first` before `second`. */
+function collectPanes(node, acc = []) {
+	if (node.type === "pane") acc.push(node);
+	else {
+		collectPanes(node.first, acc);
+		collectPanes(node.second, acc);
+	}
+	return acc;
+}
+/**
+* The pane that ends up on a subtree's EXISTING region pane — follow `first` down, since `first`
+* always inherits the pane a split was made from. This is what tells the walk whose `env` and `dir`
+* a split must carry: the new pane a split creates is the region for `second`, and the leaf that
+* ultimately sits on it is `firstPane(second)`.
+*/
+function firstPane(node) {
+	return node.type === "pane" ? node : firstPane(node.first);
+}
+//#endregion
+//#region src/template-capture.ts
+const right = (rect) => rect.x + rect.width;
+const bottom = (rect) => rect.y + rect.height;
+const HORIZONTAL = {
+	direction: "right",
+	start: (r) => r.x,
+	end: right
+};
+const VERTICAL = {
+	direction: "down",
+	start: (r) => r.y,
+	end: bottom
+};
+/**
+* The lowest cut on this axis that separates the panes cleanly, or `undefined` if none does.
+*
+* Taking the LOWEST rather than any is what produces a right-comb for an n-ary row: three panes side
+* by side cut first into `[a][b c]`, then `[b][c]` — the exact tree `desugar`'s `comb` emits for
+* `arrange: even-horizontal`, reached from the opposite direction.
+*
+* A candidate is any pane's start edge. It separates cleanly when every pane lies wholly before it
+* or wholly after it, and both sides have something in them.
+*/
+function findCut(panes, axis) {
+	const candidates = [...new Set(panes.map((p) => axis.start(p.rect)))].sort((a, b) => a - b);
+	for (const at of candidates) {
+		const first = panes.filter((p) => axis.end(p.rect) <= at);
+		const second = panes.filter((p) => axis.start(p.rect) >= at);
+		if (first.length === 0 || second.length === 0) continue;
+		if (first.length + second.length !== panes.length) continue;
+		return {
+			direction: axis.direction,
+			ratio: ratioOf(panes, second, axis),
+			first,
+			second
+		};
+	}
+}
+/**
+* The fraction of the split region kept by `first` — the schema's `ratio`.
+*
+* Measured as the COMPLEMENT of what `second` occupies, over the whole region: `1 - second/total`.
+* The obvious `first / (first + second)` is subtly wrong on any backend that draws a divider, and
+* the arithmetic says why — tmux splitting a 50-row region reports 34 + 15, with the 51st row eaten
+* by the divider. `first / (first + second)` reads 34/49 = 0.69; the true split was 0.7, and the
+* divider row belongs to neither pane's height while still costing the region a row.
+*
+* Taking the complement puts that row back where the backend's own arithmetic puts it: tmux's `-l`
+* sizes the NEW pane, so `second` is exactly the fraction asked for and `first` keeps the rest,
+* divider included. That reads 1 - 15/50 = 0.7 — the number the split was actually made with. On a
+* backend with no divider (herdr) the two formulas agree, so nothing is traded for the fix.
+*
+* Both checked against live binaries: this recovers tmux's `-l 40%`/`-l 30%` splits as 0.6/0.7
+* exactly, and reproduces herdr's to within the cell it rounds to.
+*/
+function ratioOf(all, second, axis) {
+	const total = extent(all, axis);
+	if (total <= 0) return .5;
+	return 1 - extent(second, axis) / total;
+}
+/** How far a group of panes reaches along an axis — its bounding box on that axis. */
+function extent(panes, axis) {
+	const starts = panes.map((p) => axis.start(p.rect));
+	const ends = panes.map((p) => axis.end(p.rect));
+	return Math.max(...ends) - Math.min(...starts);
+}
+/**
+* Cut the region into a binary tree, recursively.
+*
+* **`right` is tried before `down`, and the order is load-bearing on a grid.** A 2x2 is genuinely
+* ambiguous — cutting it vertically first and horizontally first both describe the same screen, and
+* neither is more true. Columns-then-rows is the tie-break because that is what `desugar`'s `tiled`
+* emits, so a tiled pool exports back as the tree it was built from rather than its transpose.
+*
+* A region no cut separates cannot come out of a multiplexer: both backends build regions BY
+* splitting, so every region they can report is guillotine-cuttable by construction. Reaching the
+* throw means the geometry did not come from where we think it did — which is worth saying loudly
+* rather than papering over with a tree that misplaces the user's panes.
+*/
+function partition(panes) {
+	if (panes.length === 1) return {
+		type: "pane",
+		pane: panes[0]
+	};
+	const cut = findCut(panes, HORIZONTAL) ?? findCut(panes, VERTICAL);
+	if (!cut) throw new Error(`this region's panes do not form a splittable tree (${panes.length} panes: ${panes.map((p) => p.id).join(", ")}) — export can only capture a region built by splitting`);
+	const node = {
+		type: "split",
+		direction: cut.direction,
+		first: partition(cut.first),
+		second: partition(cut.second)
+	};
+	const ratio = roundRatio(cut.ratio);
+	if (ratio !== .5) node.ratio = ratio;
+	return node;
+}
+/**
+* Two decimals, and clamped strictly inside `(0, 1)`.
+*
+* Two because the emitted template is meant to be READ and edited: a 3-pane row wants `0.33`, not
+* `0.33167`, and the cell it costs is invisible. The clamp is the guard on a degenerate capture — a
+* pane one cell wide in a wide region rounds to `0`, which `validateTemplate` rejects outright, so an
+* export of a real screen would emit a template that fails its own validator.
+*/
+function roundRatio(ratio) {
+	const rounded = Math.round(ratio * 100) / 100;
+	return Math.min(.99, Math.max(.01, rounded));
+}
+/**
+* The `dir` a pane's cwd becomes: relative to the root, or `undefined` when it IS the root or sits
+* outside it. Apply's injection run backwards — apply joins `cwd + dir`, so export subtracts.
+*
+* The schema forbids `cwd` outright, so a pane outside the root has nowhere to put its location and
+* genuinely loses it. That is reported as a warning rather than dropped in silence, and never
+* emitted as a `..` path: `dir` must stay under the apply-time target, so a template that escaped it
+* would fail validation on the way back in.
+*/
+function toDir(paneCwd, rootCwd) {
+	if (!paneCwd || !rootCwd) return { outside: false };
+	const rel = relative(rootCwd, paneCwd);
+	if (rel === "") return { outside: false };
+	if (rel.startsWith("..") || rel.split(sep).includes("..")) return { outside: true };
+	return {
+		dir: rel,
+		outside: false
+	};
+}
+/** The pane sitting on the region's own root — follow `first` down, exactly as `firstPane` does. */
+function rootOf(tree) {
+	return tree.type === "pane" ? tree.pane : rootOf(tree.first);
+}
+/**
+* Capture a region into a template.
+*
+* The root pane's cwd becomes the template's implicit target — every other pane's `dir` is measured
+* from it — because that is precisely what apply injects `--cwd` as. A pane elsewhere on the disk
+* cannot be expressed and says so in `warnings`.
+*/
+function captureTemplate(panes, opts) {
+	if (panes.length === 0) throw new Error("a capture needs at least one pane — this region reported none");
+	const tree = partition(panes);
+	const ctx = context(rootOf(tree).cwd);
+	const template = shell(opts);
+	template.root = convert(tree, ctx);
+	return {
+		template,
+		warnings: ctx.warnings
+	};
+}
+/**
+* Capture a whole workspace into a `tabs` template — the exact inverse of the tabs walk, and
+* `captureTemplate` one level up rather than a second derivation: each tab's tree comes off the SAME
+* `partition`, because a tab is a region and the geometry rules cannot depend on how many of them
+* there are.
+*
+* One thing is workspace-WIDE rather than per-tab, and it follows from what the schema already says:
+* the target is the FIRST tab's root pane, because that is the pane apply's `--cwd` opens the
+* workspace at, so every tab's `dir` is measured from that one root.
+*/
+function captureWorkspaceTemplate(tabs, opts) {
+	if (tabs.length === 0) throw new Error("a workspace capture needs at least one tab — this workspace reported none");
+	const trees = tabs.map((tab) => {
+		if (tab.panes.length === 0) throw new Error(`a capture needs at least one pane — tab ${tab.id} reported none`);
+		return partition(tab.panes);
+	});
+	const ctx = context(rootOf(trees[0]).cwd);
+	const template = shell(opts);
+	template.tabs = tabs.map((tab, index) => {
+		const node = {};
+		if (tab.label) node.label = tab.label;
+		node.root = convert(trees[index], ctx);
+		return node;
+	});
+	return {
+		template,
+		warnings: ctx.warnings
+	};
+}
+/** The template every capture starts from — the fields that owe nothing to the geometry. */
+function shell(opts) {
+	const template = { name: opts.name };
+	if (opts.description) template.description = opts.description;
+	return template;
+}
+function context(rootCwd) {
+	return {
+		rootCwd,
+		warnings: []
+	};
+}
+function toPaneNode(pane, ctx) {
+	const node = { type: "pane" };
+	if (pane.label) node.label = pane.label;
+	const { dir, outside } = toDir(pane.cwd, ctx.rootCwd);
+	if (dir) node.dir = dir;
+	if (outside) ctx.warnings.push(`pane ${pane.id}${pane.label ? ` ("${pane.label}")` : ""} runs in ${pane.cwd}, which is not under the captured root ${ctx.rootCwd} — a template cannot pin a directory, so this pane is captured without one`);
+	return node;
+}
+/**
+* A partition into schema nodes. `command` is never emitted and there is no branch here that could
+* emit one: no multiplexer reports the command a pane was launched with, so a capture at any tier is
+* a DRAFT with `command` left for the author.
+*/
+function convert(node, ctx) {
+	if (node.type === "pane") return toPaneNode(node.pane, ctx);
+	const split = {
+		type: "split",
+		direction: node.direction,
+		first: convert(node.first, ctx),
+		second: convert(node.second, ctx)
+	};
+	if (node.ratio !== void 0) split.ratio = node.ratio;
+	return split;
+}
+//#endregion
+//#region src/template-session.ts
+/**
+* A walk that threw partway. Carries the manifest of what WAS built, because apply does not roll
+* back: rolling back would mean killing panes, and a kill is not obviously safer than a half-built
+* template the caller can see and finish. This is the price of owning the engine rather than
+* delegating to an atomic tree-apply, and it is paid uniformly — a guarantee only herdr could make
+* is not a guarantee cyber-mux can offer.
+*/
+var TemplateApplyError = class extends Error {
+	manifest;
+	constructor(message, manifest) {
+		super(message);
+		this.manifest = manifest;
+		this.name = "TemplateApplyError";
+	}
+};
+/** A tab's bookkeeping, with its root pane already open and its root leaf pinned to that pane. */
+function tabState(tree, index, root, rootDir, rootEnvHonored) {
+	const rootLeaf = firstPane(tree);
+	return {
+		tree,
+		index,
+		root,
+		rootDir,
+		rootEnvHonored,
+		ordered: collectPanes(tree),
+		rootLeaf,
+		paneOf: /* @__PURE__ */ new Map([[rootLeaf, root.id]])
+	};
+}
+/** A pane's resolved cwd: the apply-time target, joined with the node's relative `dir`. */
+function resolveDir(cwd, dir) {
+	return dir ? join(cwd, dir) : cwd;
+}
+/**
+* Every `dir` the template names, checked against the REAL target before anything is opened. A
+* branch that predates a directory is a real case, so the error names the pane and the resolved path
+* rather than just failing a mkdir somewhere.
+*
+* Up front, not per-pane-at-birth: a predictable error should not cost a half-built pool.
+*/
+function assertTemplateDirs(tree, cwd, dirExists) {
+	for (const pane of collectPanes(tree)) {
+		if (pane.dir === void 0) continue;
+		const resolved = resolveDir(cwd, pane.dir);
+		if (!dirExists(resolved)) throw new Error(`template pane "${pane.label ?? "(unlabeled)"}": directory does not exist — ${resolved}`);
+	}
+}
+/**
+* Open a region and build the template inside it — `open --template`.
+*
+* The region opens BLANK (no `launch`) and its pane becomes the tree's root region: not a wasted
+* pane to close, but the pane the walk splits INTO. That is why nothing is launched here — the
+* template owns what runs.
+*
+* The manifest's `workspace` is whatever the region's own `open` landed in — the workspace it
+* created at the default `workspace` placement, or the one it landed inside at a `tab`/`pane:*`
+* placement. `null` only when the backend has no workspace tier (tmux) and so had nothing to report.
+* This is occupancy, not a worktree binding: `open` groups no repo, and a caller must not read a
+* workspace here as evidence that it did.
+*/
+function openTemplate(exec, adapter, template, opts) {
+	if (template.tabs) return openTabsTemplate(exec, adapter, template, template.tabs, opts);
+	const tree = resolveTree(template);
+	assertTemplateDirs(tree, opts.cwd, opts.dirExists);
+	const rootLeaf = firstPane(tree);
+	const rootDir = resolveDir(opts.cwd, rootLeaf.dir);
+	const root = adapter.open(exec, {
+		cwd: rootDir,
+		at: opts.at ?? "workspace",
+		label: opts.label,
+		env: rootLeaf.env,
+		from: opts.from
+	});
+	return walk(tabState(tree, null, root, rootDir, true), {
+		exec,
+		adapter,
+		cwd: opts.cwd,
+		name: template.name,
+		workspace: root.workspace ?? null,
+		dirExists: opts.dirExists,
+		warnedRatio: false
+	});
+}
+/**
+* The workspace label a tabs apply groups under: what the caller asked for, or the template's own
+* name. Never shortened, anywhere — it is the label the caller already chose, so the caller owns its
+* length, and not shortening is what makes a collision between two workspaces that shorten alike
+* impossible rather than merely handled.
+*/
+function workspaceLabelOf(template, label) {
+	return label ?? template.name;
+}
+/**
+* A workspace of N tabs — the single-tab walk, wrapped, with the inner walk unchanged and run once
+* per tab. Every later tab opens INSIDE the workspace at the `tab` placement; no tab is ever a split
+* of another tab's pane, which is the whole difference between a workspace of tabs and one tab of
+* panes.
+*
+* `firstTab` is the ONE thing the two routes differ in, and the reason they share this walk rather
+* than owning two that could drift: `open --template` opens the workspace and hands back its region,
+* while `worktree add --template` already HAS one — the worktree's own workspace, which that route
+* forced the placement for — so the first tab builds into it rather than opening a second.
+*
+* Every tab is opened and every split built BEFORE the first command is submitted — the single-tab
+* ordering, scaled: a split lands mid-render if it targets a pane already running an interactive
+* agent, and a tab is opened blank for exactly the reason a region is.
+*/
+function walkTabs(ctx, tabs, trees, workspaceLabel, group, firstTab) {
+	const built = [];
+	try {
+		trees.forEach((tree, index) => {
+			let opened;
+			if (index === 0) {
+				const first = firstTab();
+				opened = first.root;
+				built.push(tabState(tree, 0, first.root, first.rootDir, first.rootEnvHonored));
+				const name = tabLabelFor(ctx, tabs[0], workspaceLabel);
+				if (name !== void 0) ctx.adapter.rename(ctx.exec, { id: opened.tab }, "tab", name);
+			} else {
+				const rootLeaf = firstPane(tree);
+				const rootDir = resolveDir(ctx.cwd, rootLeaf.dir);
+				opened = ctx.adapter.open(ctx.exec, {
+					cwd: rootDir,
+					at: "tab",
+					label: tabLabelFor(ctx, tabs[index], workspaceLabel),
+					env: rootLeaf.env
+				});
+				built.push(tabState(tree, index, opened, rootDir, true));
+			}
+			ctx.adapter.group(ctx.exec, { id: opened.tab }, group, tabs[index].label);
+			buildGeometry(built[index], ctx);
+		});
+	} catch (err) {
+		throw new TemplateApplyError(err instanceof Error ? err.message : String(err), report(ctx, built));
+	}
+	submitCommands(built, ctx);
+	return report(ctx, built);
+}
+/** `open --template` with a tabs template: the first tab opens the workspace the rest live in. */
+function openTabsTemplate(exec, adapter, template, tabs, opts) {
+	const trees = tabs.map((tab) => resolveTree(tab));
+	for (const tree of trees) assertTemplateDirs(tree, opts.cwd, opts.dirExists);
+	const group = randomUUID();
+	const workspaceLabel = workspaceLabelOf(template, opts.label);
+	const ctx = {
+		exec,
+		adapter,
+		cwd: opts.cwd,
+		name: template.name,
+		workspace: null,
+		dirExists: opts.dirExists,
+		warnedRatio: false
+	};
+	return walkTabs(ctx, tabs, trees, workspaceLabel, group, () => {
+		const rootLeaf = firstPane(trees[0]);
+		const rootDir = resolveDir(opts.cwd, rootLeaf.dir);
+		const opened = adapter.open(exec, {
+			cwd: rootDir,
+			at: opts.at ?? "workspace",
+			label: workspaceLabel,
+			env: rootLeaf.env,
+			from: opts.from
+		});
+		ctx.workspace = opened.workspace ?? null;
+		return {
+			root: opened,
+			rootDir,
+			rootEnvHonored: true
+		};
+	});
+}
+/**
+* A tab's label, as a human reads it.
+*
+* Where the backend has no workspace tier (tmux, which collapses workspace and tab onto one Window),
+* the workspace is carried into the label — `<workspace> - <tab>` — because the template's tabs would
+* otherwise land as an unlabeled pile with nothing marking them as one pool. Where the backend HAS the
+* tier (herdr), its UI already groups by the real workspace label, so a prefix would be redundant
+* noise and the tab carries its own label alone. The concept maps onto what the backend actually has.
+*
+* The workspace label goes in whole — never shortened. It is the label the caller already chose, so
+* the caller owns its length, and not shortening is what makes a collision between two workspaces that
+* shorten alike impossible rather than merely handled.
+*
+* This is the human's carrier only. The machine reads `workspaceGroup`, never this — the label is
+* ambiguous under every split rule ("acme - beta - main"), so it is written and never parsed back.
+*/
+function tabLabelFor(ctx, tab, workspaceLabel) {
+	if (tab.label === void 0) return void 0;
+	if (ctx.workspace !== null) return tab.label;
+	return `${workspaceLabel} - ${tab.label}`;
+}
+/**
+* The pane that will sit on a region's own root pane — whoever opens that region must carry this
+* pane's `env` (and, where it can, its `dir`), because no split ever births it.
+*
+* For a tabs template that is the FIRST tab's root leaf: the first tab is the one built into the
+* region the caller opens, and every later tab opens its own space (carrying its own root leaf's env
+* at that open). Resolving the template itself here would desugar a `panes` list a tabs template does
+* not have.
+*/
+function templateRootPane(template) {
+	return firstPane(resolveTree(template.tabs ? template.tabs[0] : template));
+}
+/**
+* Build a template inside a region someone else already opened — `worktree add --template`, where the
+* worktree's own workspace IS the region and its root pane is the tree's root.
+*/
+function applyTemplateToRegion(exec, adapter, template, opts) {
+	if (template.tabs) return applyTabsToRegion(exec, adapter, template, template.tabs, opts);
+	const tree = resolveTree(template);
+	assertTemplateDirs(tree, opts.cwd, opts.dirExists);
+	const rootLeaf = firstPane(tree);
+	if (rootLeaf.dir !== void 0) process.stderr.write(`the template's root pane "${rootLeaf.label ?? "(unlabeled)"}" cannot start in "${rootLeaf.dir}" — the region opens at ${opts.cwd}\n`);
+	return walk(tabState(tree, null, opts.root, opts.cwd, opts.rootEnvHonored), {
+		exec,
+		adapter,
+		cwd: opts.cwd,
+		name: template.name,
+		workspace: opts.workspace,
+		dirExists: opts.dirExists,
+		warnedRatio: false
+	});
+}
+/**
+* `worktree add --template` with a tabs template: the workspace already EXISTS — that route forces the
+* `workspace` placement and opened one for the worktree — so a set of tabs has somewhere to live and
+* needs no second workspace. The first tab is built INTO that region; every later tab opens as a tab
+* in it. That one difference is the whole of what separates this route from `open --template`.
+*/
+function applyTabsToRegion(exec, adapter, template, tabs, opts) {
+	const trees = tabs.map((tab) => resolveTree(tab));
+	for (const tree of trees) assertTemplateDirs(tree, opts.cwd, opts.dirExists);
+	const ctx = {
+		exec,
+		adapter,
+		cwd: opts.cwd,
+		name: template.name,
+		workspace: opts.workspace,
+		dirExists: opts.dirExists,
+		warnedRatio: false
+	};
+	const rootLeaf = firstPane(trees[0]);
+	if (rootLeaf.dir !== void 0) process.stderr.write(`the template's root pane "${rootLeaf.label ?? "(unlabeled)"}" cannot start in "${rootLeaf.dir}" — the region opens at ${opts.cwd}\n`);
+	return walkTabs(ctx, tabs, trees, workspaceLabelOf(template, opts.label), randomUUID(), () => ({
+		root: opts.root,
+		rootDir: opts.cwd,
+		rootEnvHonored: opts.rootEnvHonored
+	}));
+}
+/**
+* The walk: geometry depth-first against NAMED panes, then every command, last.
+*
+* **Geometry before commands is deliberate ordering, not incidental.** `open`'s `launch` couples
+* creation to launching, so reusing it would mean splitting a pane already running an interactive
+* agent — the split lands mid-render, and the ratio is computed against a pane whose child is
+* reflowing. Opening every pane blank first makes the whole geometry phase side-effect-free from the
+* agent's point of view.
+*/
+function walk(tab, ctx) {
+	const tabs = [tab];
+	try {
+		buildGeometry(tab, ctx);
+	} catch (err) {
+		throw new TemplateApplyError(err instanceof Error ? err.message : String(err), report(ctx, tabs));
+	}
+	submitCommands(tabs, ctx);
+	return report(ctx, tabs);
+}
+/**
+* One tab's geometry: depth-first against NAMED panes, opening every pane blank. Submits nothing —
+* the caller does that once EVERY tab is built, which is what lets the multi-tab walk hold the same
+* "no split ever lands on a pane mid-render" guarantee the single-tab walk holds.
+*/
+function buildGeometry(tab, ctx) {
+	const sizeSplit = (ratio) => {
+		if (ratio == null) return void 0;
+		if (ctx.adapter.canSizeSplits) return ratio;
+		if (!ctx.warnedRatio) {
+			ctx.warnedRatio = true;
+			process.stderr.write(`${ctx.adapter.name} cannot size a split — every ratio in this template takes its default\n`);
+		}
+	};
+	const build = (node, paneId) => {
+		if (node.type === "pane") return;
+		const born = firstPane(node.second);
+		const created = ctx.adapter.open(ctx.exec, {
+			cwd: resolveDir(ctx.cwd, born.dir),
+			at: node.direction === "down" ? "pane:down" : "pane:right",
+			from: { id: paneId },
+			ratio: sizeSplit(node.ratio),
+			env: born.env,
+			label: born.label
+		});
+		tab.paneOf.set(born, created.id);
+		build(node.first, paneId);
+		build(node.second, created.id);
+	};
+	build(tab.tree, tab.root.id);
+}
+/**
+* The manifest, across every tab built so far. ONE FLAT pane list — the tab is a field on each pane
+* rather than a second nesting a consumer has to walk. The unique handle is the pane `id`; `label` is
+* a name two panes may share, and the tab is reported by INDEX rather than by either.
+*/
+function report(ctx, tabs) {
+	return {
+		template: ctx.name,
+		cwd: ctx.cwd,
+		workspace: ctx.workspace,
+		panes: tabs.flatMap((tab) => tab.ordered.filter((pane) => tab.paneOf.has(pane)).map((pane) => ({
+			label: pane.label ?? null,
+			pane: tab.paneOf.get(pane),
+			dir: pane === tab.rootLeaf ? tab.rootDir : resolveDir(ctx.cwd, pane.dir),
+			command: pane.command ?? null,
+			tab: tab.index
+		})))
+	};
+}
+/**
+* Every command, last — and across every tab, in template order, tab by tab. Only reachable once all
+* geometry is built: a split lands mid-render if it targets a pane already running an interactive
+* agent, and that reason does not weaken because the pane sits in another tab.
+*/
+function submitCommands(tabs, ctx) {
+	for (const tab of tabs) {
+		const rootFallback = tab.rootEnvHonored ? void 0 : envFallback(tab.rootLeaf.env, tab.rootLeaf.command);
+		if (rootFallback?.kind === "dropped") process.stderr.write(`the template's root pane "${tab.rootLeaf.label ?? "(unlabeled)"}" has env (${rootFallback.variables.join(", ")}) but no command to carry it — this backend cannot set env on the region it opens
+`);
+		for (const pane of tab.ordered) {
+			const command = pane === tab.rootLeaf && rootFallback?.kind === "carried" ? rootFallback.command : pane.command;
+			if (!command) continue;
+			ctx.adapter.submit(ctx.exec, { id: tab.paneOf.get(pane) }, command);
+		}
+	}
+}
+//#endregion
+//#region src/template-store.ts
+const realTemplateStore = {
+	list(dir) {
+		try {
+			return readdirSync(dir).filter((file) => file.endsWith(".json")).map((file) => basename(file, ".json")).sort();
+		} catch {
+			return [];
+		}
+	},
+	read(path) {
+		try {
+			return readFileSync(path, "utf8");
+		} catch {
+			return null;
+		}
+	},
+	dirExists(path) {
+		return existsSync(path);
+	},
+	write(path, contents) {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, contents, "utf8");
+	}
+};
+/**
+* The two searched directories.
+*
+* The repo location resolves through `resolvePrimaryRoot`, NOT `./.cyber-mux` relative to the
+* caller's cwd, and that is load-bearing rather than incidental: cyber-mux is used across many
+* worktrees of one project, and a worktree branched from a commit that predates a template would
+* otherwise silently see a stale template, or none at all. Resolving through the primary checkout
+* gives one canonical answer from every worktree.
+*/
+function templateDirs(exec, env) {
+	const configHome = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+	return {
+		repo: join(resolvePrimaryRoot(exec), ".cyber-mux", "templates"),
+		user: join(configHome, "cyber-mux", "templates")
+	};
+}
+/**
+* Resolve a template to its bytes: `--file` (explicit), then the repo, then the user.
+*
+* **Repo beats user, deliberately.** A project that ships a template is making a statement about how
+* the project is worked on, and a personal template of the same name should not silently shadow it —
+* so `template list` reports each name's source and marks the user template a repo one shadows.
+*
+* Throws when nothing resolves, naming BOTH directories searched — a name that resolves nowhere is a
+* typo, and the answer to a typo is where it looked.
+*/
+function resolveTemplate$1(opts) {
+	if (opts.file) {
+		const raw = opts.store.read(opts.file);
+		if (raw === null) throw new Error(`cannot read template: ${opts.file}`);
+		return {
+			stem: basename(opts.file, ".json"),
+			path: opts.file,
+			source: "file",
+			raw
+		};
+	}
+	const name = opts.name ?? "";
+	assertTemplateName(name);
+	const dirs = templateDirs(opts.exec, opts.env);
+	for (const source of ["repo", "user"]) {
+		const path = join(dirs[source], `${name}.json`);
+		const raw = opts.store.read(path);
+		if (raw !== null) return {
+			stem: name,
+			path,
+			source,
+			raw
+		};
+	}
+	throw new Error(`template "${name}" not found — searched ${dirs.repo} and ${dirs.user}`);
+}
+function assertTemplateName(name) {
+	if (!isValidTemplateName(name)) throw new Error(`invalid template name "${name}" — a name must match [a-z0-9][a-z0-9-]* and be a plain filename stem`);
+}
+/**
+* Every template resolvable from here, repo first.
+*
+* A shadowed user template is REPORTED rather than omitted: the whole reason repo wins is that a
+* personal template should not silently displace the project's, and "silently" cuts both ways — a
+* user whose `pool-4` stopped being used deserves to be told why, not left to wonder.
+*/
+function listTemplates(store, dirs) {
+	const repo = store.list(dirs.repo);
+	const repoNames = new Set(repo);
+	return [...repo.map((name) => ({
+		name,
+		source: "repo",
+		path: join(dirs.repo, `${name}.json`),
+		shadowed: false
+	})), ...store.list(dirs.user).map((name) => ({
+		name,
+		source: "user",
+		path: join(dirs.user, `${name}.json`),
+		shadowed: repoNames.has(name)
+	}))];
+}
+//#endregion
+//#region src/worktree-session.ts
+/**
+* Grouping is possible only where the backend binds AND the caller asked for a workspace — herdr's
+* `worktree create` ALWAYS opens a workspace, so it cannot serve a pane or tab placement.
+*/
+function canBind(adapter, at) {
+	return Boolean(adapter.worktree) && at === "workspace";
+}
+/** True only where a group was on offer and the placement is what cost us it. */
+function isDegraded(adapter, at) {
+	return Boolean(adapter.worktree) && !canBind(adapter, at);
+}
+/**
+* Create a worktree and open it.
+*
+* Routes through the backend's own primitive when it can bind (grouped), and otherwise falls back to
+* `git worktree add` plus a plain `open()`. The fallback is a complete, useful outcome — a worktree
+* open in a split pane — just not a grouped one, so it is REPORTED (`degraded`), never refused.
+* Refusing would make identical flags succeed on tmux and fail on herdr, which is exactly the
+* backend leak this seam exists to prevent.
+*/
+function addAndOpenWorktree(exec, adapter, opts) {
+	if (canBind(adapter, opts.at)) return {
+		...adapter.worktree.createInWorkspace(exec, {
+			primaryRoot: opts.primaryRoot,
+			branch: opts.branch,
+			path: opts.path,
+			base: opts.base,
+			launch: opts.launch,
+			env: opts.env,
+			label: opts.label
+		}),
+		degraded: false,
+		envHonored: !opts.env
+	};
+	const worktree = gitWorktreeAdapter.add(exec, {
+		primaryRoot: opts.primaryRoot,
+		path: opts.path,
+		branch: opts.branch,
+		base: opts.base
+	});
+	return {
+		worktree,
+		target: adapter.open(exec, {
+			cwd: worktree.root,
+			launch: opts.launch,
+			env: opts.env,
+			at: opts.at,
+			label: opts.label,
+			from: opts.from
+		}),
+		degraded: isDegraded(adapter, opts.at),
+		envHonored: true
+	};
+}
+/**
+* Open an EXISTING worktree — the remedy that groups one a bare `worktree add` created earlier, so
+* "add now, group later" is a real story rather than a dead end.
+*/
+function openExistingWorktree(exec, adapter, opts) {
+	const at = opts.at ?? "workspace";
+	if (canBind(adapter, at)) return {
+		...adapter.worktree.openInWorkspace(exec, {
+			primaryRoot: opts.primaryRoot,
+			path: opts.path,
+			launch: opts.launch,
+			env: opts.env,
+			label: opts.label
+		}),
+		degraded: false,
+		envHonored: !opts.env
+	};
+	const root = normalizeWorktreePath(opts.path);
+	const target = adapter.open(exec, {
+		cwd: root,
+		launch: opts.launch,
+		env: opts.env,
+		at,
+		label: opts.label,
+		from: opts.from
+	});
+	return {
+		worktree: {
+			root,
+			branch: listWorktreesFromGit(exec, opts.primaryRoot).find((entry) => entry.root === root)?.branch ?? ""
+		},
+		target,
+		degraded: isDegraded(adapter, at),
+		envHonored: true
+	};
+}
+/**
+* Every worktree of the repo, with the workspace each is open in.
+*
+* The facts come from git on EVERY backend and the backend contributes only the binding, joined by
+* normalized path. A backend that also enumerates worktrees is merely re-reading git, so letting it
+* answer would let two backends report a different branch for the same worktree — this is
+* structurally incapable of that.
+*/
+function listWorktrees(exec, adapter, opts) {
+	const bindings = adapter?.worktree?.bindings(exec, { primaryRoot: opts.primaryRoot });
+	return listWorktreesFromGit(exec, opts.primaryRoot).map((entry) => {
+		const workspace = bindings?.get(entry.root);
+		return workspace ? {
+			...entry,
+			workspace
+		} : entry;
+	});
+}
+/**
+* Remove a worktree, with identical gates on every backend: refuse the primary checkout (absolute),
+* tolerate one already gone from disk, refuse uncommitted changes unless `force`.
+*
+* Removal is never handed to the backend — only the binding's release is. See
+* `WorktreeWorkspaceCapability` for why, and `removeWorktreeSafely` for why the ordering of that
+* release is a specified property rather than an incidental one.
+*/
+function removeWorktree(exec, adapter, path, opts) {
+	const capability = adapter?.worktree;
+	const workspace = capability?.bindings(exec, { primaryRoot: opts.primaryRoot }).get(normalizeWorktreePath(path));
+	removeWorktreeSafely(exec, path, {
+		primaryRoot: opts.primaryRoot,
+		force: opts.force,
+		releaseBinding: capability && workspace ? () => capability.releaseWorkspace(exec, workspace) : void 0
+	});
+}
+//#endregion
+//#region src/cli.ts
+const REAL_DEPS = {
+	env: process.env,
+	exec: realExec,
+	store: realTemplateStore
+};
+/**
+* Resolve the adapter for the multiplexer this process is inside, failing with a coded `no-mux` error
+* when there is none. The underlying throw is TRANSLATED, never forwarded — `selectSessionAdapter`
+* names `$TMUX`/`$HERDR_ENV`, which is backend plumbing an agent driving cyber-mux cannot act on; the
+* help names how to get a backend through this CLI instead.
+*/
+function adapter(deps) {
+	try {
+		return selectSessionAdapter(deps.env, deps.exec);
+	} catch {
+		throw noMux();
+	}
+}
+/** No multiplexer around this process — an operation failure (exit 1), not a usage error. */
+function noMux() {
+	return new CliError("no-mux", "no multiplexer detected around this process", "run cyber-mux inside tmux or herdr, or set CYBER_MUX to name one", 1);
+}
+/** A locator that resolved to no live pane — a pane verb's not-found. Exit 1: a real operation
+* failure, distinct from a malformed argument. */
+function paneNotFound(locator) {
+	return new CliError("pane-not-found", `pane "${locator}" matched no live pane`, "list the live panes with: cyber-mux list", 1);
+}
+/** A malformed template name — a usage error (exit 2): the fix is a different name, nothing was
+* attempted. The same family a missing required argument is in. */
+function invalidTemplateName(name) {
+	return new CliError("invalid-template-name", `invalid template name "${name}" — a name must match [a-z0-9][a-z0-9-]* and be a plain filename stem`, "use a lowercase stem like pool-4", 2);
+}
+/**
+* A git/worktree operation that refused or failed — exit 1. A coded surface already on its way out (a
+* `no-mux`, a resolved-template error, an apply failure) passes through untouched rather than being
+* flattened into this generic one. A `WorktreeGitError` is this CLI's own worktree text (a refusal
+* naming `--force`, a primary-checkout guard), which is kept because the frozen worktree refusals are
+* asserted on it. Anything else reaching here comes from the session adapter opening/binding the
+* worktree's pane (`session.tmux.ts`/`session.herdr.ts`) and embeds the backend's own name plus its raw
+* stderr (`withReason`, `exec.lastError`) — AXI #6 forbids leaking a dependency's name or text, so that
+* detail is not load-bearing for the agent and goes to stderr as a diagnostic only; stdout carries this
+* CLI's own coded, translated error.
+*/
+function reportWorktreeFailure(err) {
+	if (err instanceof CliError) reportError(err);
+	if (err instanceof WorktreeGitError) reportError(new CliError("worktree-failed", err.message, "check the worktree path and its state, then re-run", 1));
+	if (err instanceof Error && err.message) process.stderr.write(`${err.message}\n`);
+	reportError(new CliError("worktree-failed", "the worktree operation failed", "check the worktree path and its state, then re-run", 1));
+}
+/**
+* Resolve a locator — a pane id or a human label — to the one pane it names.
+*
+* **Id first, then name.** An id can never be made to mean something else by a person renaming an
+* unrelated pane, so every caller that passes ids today keeps working no matter what anyone labels.
+* That also makes ambiguity a fuzzy-tier condition only: an id hit and a label hit are not peers, so
+* they are not candidates to choose between — the same ladder git, Docker and tmux resolve targets by.
+*
+* **An id is recognized by EXISTENCE, never by syntax.** The question asked is "does a live pane carry
+* this id?", not "does this string look like an id?". Docker sniffs shape (`sg-` → an id) and it is
+* the cheaper rule, refused here: encoding a backend's id format in the CLI is exactly the backend
+* leak this seam exists to prevent, and every new backend would owe a new syntax rule. It is also
+* wrong on a real case — `%9` is id-SHAPED, but if no pane carries it as an id and one carries it as a
+* label, a sniffer reports a missing pane while the live list finds the label.
+*
+* One `listPanes` read answers both halves, so name support costs the id path a single query and no
+* behavior. The SEAM is untouched: adapters keep receiving concrete ids, and never learn that a name
+* was ever involved.
+*
+* A locator matching NOTHING resolves to itself, deliberately — it is handed to the backend as an id
+* and takes the verb's existing not-found path (exit 1). Failing here instead would make every verb's
+* "no such pane" message this function's to write.
+*/
+function resolveTarget(deps, a, locator) {
+	let panes;
+	try {
+		panes = a.listPanes(deps.exec);
+	} catch {
+		return { id: locator };
+	}
+	if (panes.some((p) => p.id === locator)) return { id: locator };
+	const named = panes.filter((p) => p.label === locator);
+	if (named.length === 1) return { id: named[0].id };
+	if (named.length > 1) throw new AmbiguousPaneError(locator, named.map((p) => ({
+		id: p.id,
+		label: p.label ?? null,
+		cwd: p.cwd ?? null
+	})));
+	return { id: locator };
+}
+/**
+* Wrap a verb's action so ANY coded failure reports itself on stdout and exits — the one place that
+* turns a `CliError` (an ambiguity, a `no-mux`, a `pane-not-found`, a template refusal) into output, for
+* every verb.
+*
+* Here rather than deeper so the report is the OUTERMOST thing a verb does: by the time it runs, every
+* inner catch-all has already had its chance to rethrow, and nothing can convert an exit-2 usage error
+* into an exit-1 generic failure behind its back. A non-`CliError` is a bug, not a surface — it is
+* rethrown to the top-level handler rather than dressed up as a coded failure.
+*/
+function guarded(action) {
+	return (...args) => {
+		try {
+			action(...args);
+		} catch (err) {
+			if (err instanceof CliError) reportError(err);
+			throw err;
+		}
+	};
+}
+/**
+* Run a pane verb's body, translating a backend throw into a `pane-not-found` on the way out.
+*
+* `resolveTarget` hands an unmatched locator to the backend as an id, so a bad target surfaces as the
+* backend's OWN diagnostic — which must never reach the caller: an agent handed a tmux/herdr error
+* cannot act on it through cyber-mux. A `CliError` already on its way out (a `no-mux` from `adapter`,
+* an ambiguity from `resolveTarget`) is a coded surface and passes through untouched; anything else is
+* the multiplexer's raw failure and becomes this CLI's own code and help instead.
+*/
+function paneVerb(locator, body) {
+	try {
+		body();
+	} catch (err) {
+		if (err instanceof CliError) throw err;
+		throw paneNotFound(locator);
+	}
+}
+/**
+* The backend when there is one, `undefined` when there is not — unlike `adapter`, which fails. For
+* verbs whose subject is git (`worktree list`/`remove`): a multiplexer can only ever add to the
+* answer, so its absence must not deny one.
+*/
+function optionalAdapter(deps) {
+	try {
+		return selectSessionAdapter(deps.env, deps.exec);
+	} catch {
+		return;
+	}
+}
+/**
+* One shape for every verb that opens a worktree. `printFields` drops nullish entries, so a bare
+* `worktree add` — which opens nothing — prints exactly what it always did.
+*
+* When the chosen placement cost the workspace grouping, the backend could have grouped this worktree
+* and did not — worth saying out loud. Per axi/'s #9 that next move rides in the payload on STDOUT as
+* a `help[N]:` block, not on stderr the agent never reads; `workspace: null` is the machine-readable
+* half of the same report. `regroupCommand` is the caller's own verb re-stated with `--at workspace`,
+* so the flag that would have grouped it is named as a concrete command. Emitted only when a grouping
+* was actually lost (#9's omit-when-self-contained rule), so `help` never rides along otherwise.
+*/
+function reportOpenedWorktree(opened, regroupCommand) {
+	const help = opened.degraded ? [{
+		message: "opened ungrouped — pass --at workspace to group it with the repo",
+		command: regroupCommand
+	}] : [];
+	output({
+		root: opened.worktree.root,
+		branch: opened.worktree.branch,
+		pane: opened.target.id,
+		workspace: opened.workspace ?? null,
+		...help.length ? { help } : {}
+	}, () => {
+		printFields({
+			root: opened.worktree.root,
+			branch: opened.worktree.branch,
+			pane: opened.target.id,
+			workspace: opened.workspace
+		});
+		printHelp(help);
+	});
+}
+/**
+* `--template`, the exact sibling of `--launch`: both answer "what runs in the space you are opening",
+* one for a single pane and one for a pool. Mutually exclusive by construction — commander rejects
+* the pair rather than picking a winner.
+*/
+function templateOption() {
+	return new Option("--template <name>", "Named template to build in the opened space").conflicts(["launch", "env"]);
+}
+/**
+* Resolve, parse and validate a template — the whole answer BEFORE any side effect. A typo in a
+* template name must never leave a worktree behind, and an invalid template must not either, so every
+* caller runs this before it opens or creates anything.
+*/
+function resolveTemplate(deps, opts) {
+	if (opts.name !== void 0 && opts.file === void 0 && !isValidTemplateName(opts.name)) throw invalidTemplateName(opts.name);
+	let resolved;
+	try {
+		resolved = resolveTemplate$1({
+			name: opts.name,
+			file: opts.file,
+			store: deps.store,
+			exec: deps.exec,
+			env: deps.env
+		});
+	} catch (err) {
+		throw new CliError("template-not-found", err instanceof Error ? err.message : String(err), "list the templates resolvable from here with: cyber-mux template list", 1);
+	}
+	let parsed;
+	try {
+		parsed = parseTemplate(resolved.raw);
+	} catch (err) {
+		throw new CliError("invalid-template", `${resolved.path}: ${err instanceof Error ? err.message : String(err)}`, "fix the template JSON, then re-run", 1);
+	}
+	const errors = validateTemplate(parsed, resolved.stem);
+	if (errors.length > 0) throw new CliError("invalid-template", errors.join("\n"), "fix the fields named above, then re-run", 1);
+	return {
+		...resolved,
+		template: parsed
+	};
+}
+/** The apply manifest — the handoff. `printFields`/`printTable` for humans, the raw object for json. */
+function reportManifest(manifest, extra = {}) {
+	output({
+		...extra,
+		...manifest
+	}, () => {
+		printFields({
+			...extra,
+			template: manifest.template,
+			cwd: manifest.cwd,
+			workspace: manifest.workspace
+		});
+		printTable(manifest.panes, [
+			{
+				label: "label",
+				get: (p) => p.label ?? ""
+			},
+			{
+				label: "pane",
+				get: (p) => p.pane
+			},
+			{
+				label: "dir",
+				get: (p) => p.dir
+			},
+			{
+				label: "command",
+				get: (p) => p.command ?? ""
+			}
+		]);
+	});
+}
+/**
+* A walk that threw reports what it BUILT and exits 1, killing nothing. Rolling back would mean
+* killing panes, and a kill is not obviously safer than a half-built template the caller can see and
+* finish.
+*/
+function reportApplyFailure(err, extra = {}) {
+	if (err instanceof TemplateApplyError) {
+		reportManifest(err.manifest, extra);
+		process.stderr.write(`${err.message}\n`);
+		process.exit(1);
+	}
+	throw new CliError("template-apply-failed", err instanceof Error ? err.message : String(err), "check the template and the target directory, then re-run", 1);
+}
+function templateListCommand(deps) {
+	return new Command("list").description("Every template resolvable from here, with its source and pane count").addOption(FORMAT_OPTION).action(guarded(() => {
+		const dirs = templateDirs(deps.exec, deps.env);
+		const templates = listTemplates(deps.store, dirs).map((entry) => {
+			let panes = 0;
+			try {
+				const raw = deps.store.read(entry.path);
+				if (raw) panes = collectPanes(resolveTree(parseTemplate(raw))).length;
+			} catch {
+				panes = 0;
+			}
+			return {
+				...entry,
+				panes
+			};
+		});
+		output({ templates }, () => printTable(templates, [
+			{
+				label: "name",
+				get: (l) => l.name
+			},
+			{
+				label: "source",
+				get: (l) => l.source
+			},
+			{
+				label: "panes",
+				get: (l) => String(l.panes)
+			},
+			{
+				label: "shadowed",
+				get: (l) => l.shadowed ? "yes" : ""
+			}
+		]));
+	}));
+}
+function templateShowCommand(deps) {
+	return new Command("show").description("Print a resolved template as JSON").argument("[name]", "Template name").option("--file <path>", "Read this path instead, skipping resolution entirely").option("--desugar", "Print the canonical tree panes/arrange expands to — exactly what apply builds").action(guarded((name, opts) => {
+		if (!name && !opts.file) throw new CliError("missing-argument", "template show needs a template name or --file <path>", "pass a template name, or --file <path>", 2);
+		const { template } = resolveTemplate(deps, {
+			name,
+			file: opts.file
+		});
+		console.log(JSON.stringify(opts.desugar ? resolveTree(template) : template, null, 2));
+	}));
+}
+function templateValidateCommand(deps) {
+	return new Command("validate").description("Validate a template — exit 0 valid, 1 invalid, every error at once with a JSON path").argument("[name]", "Template name").option("--file <path>", "Validate this path instead, skipping resolution entirely").action(guarded((name, opts) => {
+		if (!name && !opts.file) throw new CliError("missing-argument", "template validate needs a template name or --file <path>", "pass a template name, or --file <path>", 2);
+		resolveTemplate(deps, {
+			name,
+			file: opts.file
+		});
+	}));
+}
+/**
+* `save` is the one verb here that reads a multiplexer rather than a file, and the only one that
+* WRITES: it captures a live region into a named template, so a pool built by hand once can be named
+* rather than hand-written. That is the schema's one real authoring cost — a 4+ pane grid needs
+* nested `split` nodes nobody wants to type.
+*
+* **What it saves is a draft, and the file says so.** A capture recovers geometry, labels and dirs;
+* it can never recover commands, because no multiplexer reports the command a pane was launched with
+* (`template-capture.ts` has the why). A saved template therefore lands with no `command` on any pane
+* and is immediately listed by `template list` alongside finished ones, so the draft has to announce
+* itself IN the file — hence the `description` default. Saying it only on stderr would put the
+* warning everywhere except where the reader is.
+*
+* `--to` defaults to `repo`, matching resolution's own precedence: a template is a statement about
+* how the PROJECT is worked on, and that is the copy worth having by default.
+*
+* **`save`'s subject is a REGION and stays one.** `--workspace` widens it to every tab of the
+* workspace the caller's region sits in — one captured tab per live tab, each with its own derived
+* tree, the exact inverse of the tabs walk. It is opt-in rather than the default because widening the
+* default silently would rewrite what `save` has always meant for every caller already relying on it.
+* The bare form does not stay quiet about the narrowing, though: capturing one tab of three notes on
+* stderr what it left out, rather than letting a caller believe a 3-tab workspace round-trips from a
+* 1-tab template.
+*/
+function templateSaveCommand(deps) {
+	return new Command("save").description("Capture the live region around a pane into a named template").argument("<name>", "Name for the captured template").option("--from <pane>", "Pane whose region to capture; defaults to this process's own pane").option("--workspace", "Capture every tab of the caller's workspace, as a tabs template").option("--description <text>", "Description to record in the template").addOption(new Option("--to <source>", "Which templates directory to write to").choices(["repo", "user"]).default("repo")).option("--force", "Overwrite an existing template of this name").addOption(FORMAT_OPTION).addHelpText("after", "\nA capture recovers geometry, labels and dirs — NOT commands: no multiplexer can report the\ncommand a pane was launched with, so every pane is saved without one. Fill them in before\nthe template is worth applying.").action(guarded((name, opts) => {
+		if (!isValidTemplateName(name)) throw invalidTemplateName(name);
+		try {
+			const path = join(templateDirs(deps.exec, deps.env)[opts.to], `${name}.json`);
+			if (!opts.force && deps.store.read(path) !== null) throw new CliError("template-exists", `template "${name}" already exists at ${path} — pass --force to overwrite it`, "re-run with --force to replace it", 1);
+			const a = adapter(deps);
+			const describeRegion = a.describeRegion;
+			if (!opts.workspace && !describeRegion) throw new CliError("backend-unsupported", `${a.name} cannot report a region's geometry — template save needs a backend that can`, "run template save on a backend that reports geometry (tmux or herdr)", 1);
+			const describeWorkspace = a.describeWorkspace;
+			if (opts.workspace && !describeWorkspace) throw new CliError("backend-unsupported", `${a.name} cannot enumerate a workspace's tabs — template save --workspace needs a backend that can`, "run template save --workspace on a backend that enumerates tabs (tmux or herdr)", 1);
+			const target = opts.from ? resolveTarget(deps, a, opts.from) : callerPane(a, deps.env);
+			if (!target) throw new CliError("missing-pane", "template save needs a pane to capture the region around — pass --from <pane>, or run it inside one", "pass --from <pane>, or run template save inside a pane", 2);
+			const captureOpts = {
+				name,
+				description: opts.description ?? CAPTURED_DESCRIPTION
+			};
+			const { template, warnings } = opts.workspace ? captureWorkspaceTemplate(describeWorkspace(deps.exec, target), captureOpts) : captureTemplate(describeRegion(deps.exec, target), captureOpts);
+			deps.store.write(path, `${JSON.stringify(template, null, 2)}\n`);
+			for (const warning of warnings) process.stderr.write(`${warning}\n`);
+			const entry = opts.workspace ? null : noteTabsLeftOut(deps, a, target, name);
+			const help = entry ? [entry] : [];
+			output({
+				path,
+				...help.length ? { help } : {}
+			}, () => {
+				printFields({ path });
+				printHelp(help);
+			});
+		} catch (err) {
+			if (err instanceof CliError) throw err;
+			throw new CliError("unsplittable-region", "this region could not be captured — it is not a tree any sequence of splits could have produced", "template save can only capture a region built by splitting", 1);
+		}
+	}));
+}
+/**
+* What a bare `save` left behind: a `help` entry when the caller's workspace holds tabs this capture
+* did not take, so the capture is honest about its own scope rather than letting a caller believe a
+* 3-tab workspace round-trips from a 1-tab template.
+*
+* Per axi/'s #9 this reveal rides in `save`'s stdout payload as a `help[N]:` block, not on stderr the
+* agent never reads — programmatic composition reads the path from `--format json`, not bare stdout.
+* It is a NOTE rather than a refusal: the template the caller asked for is correct and is already
+* written. Which is also why this is best-effort — a workspace read that fails or that the backend
+* cannot do at all returns `null` (no entry), costing the caller a courtesy, not their capture. An
+* untagged window on a backend with no workspace tier reports one tab and yields nothing, which is
+* right — a window nobody grouped is a workspace of one, and nothing was left out. The `command`
+* re-states the caller's own `name` with `--workspace`, the flag that captures every tab.
+*/
+function noteTabsLeftOut(deps, adapter, target, name) {
+	if (!adapter.describeWorkspace) return null;
+	let tabs;
+	try {
+		tabs = adapter.describeWorkspace(deps.exec, target).length;
+	} catch {
+		return null;
+	}
+	if (tabs <= 1) return null;
+	return {
+		message: `this pane's workspace holds ${tabs} tabs — only the caller's own region was captured. Pass --workspace to capture every tab of it`,
+		command: `cyber-mux template save ${name} --workspace`
+	};
+}
+/**
+* The default `description` on a captured template — the draft warning, written where the reader
+* actually is. A saved capture is listed by `template list` next to finished templates and shows up in
+* `template show`, so a note that only ever reached the terminal that ran `save` would be gone by the
+* time anyone reads the file. Overridden by `--description`, since an author who names the template's
+* purpose has said something more useful than this.
+*/
+const CAPTURED_DESCRIPTION = "Captured from a live region — geometry only; add a command to each pane.";
+/**
+* The `template` group manages templates — there is deliberately no `template apply`. Applying is what
+* `open` and `worktree add` already do, told to build N panes instead of one, so it is `--template` on
+* those verbs.
+*
+* `list` / `show` / `validate` take a FILE as their subject and touch no multiplexer. `save` is the
+* exception in both respects — it reads a live region and writes a file — and it belongs here anyway:
+* it AUTHORS a template, which is what this group is for.
+*/
+function templateCommand(deps) {
+	const cmd = new Command("template").description("Manage named templates (apply one with open/worktree --template)");
+	cmd.addCommand(templateListCommand(deps));
+	cmd.addCommand(templateShowCommand(deps));
+	cmd.addCommand(templateValidateCommand(deps));
+	cmd.addCommand(templateSaveCommand(deps));
+	return cmd;
+}
+function doctorCommand(deps) {
+	return new Command("doctor").description("Probe the multiplexer, self pane, and backend; print fast-path pins").addOption(FORMAT_OPTION).action(() => {
+		const probe = probeMultiplexer(deps.exec, deps.env);
+		const self = currentPane(deps.env);
+		let backend = "none";
+		try {
+			backend = selectSessionAdapter(deps.env, deps.exec).name;
+		} catch {}
+		const data = {
+			mux: probe.mux,
+			via: probe.via,
+			pane: self?.pane ?? probe.pane ?? null,
+			backend
+		};
+		output(data, () => {
+			printFields({
+				multiplexer: data.mux,
+				"detected via": data.via,
+				pane: data.pane ?? "(none)",
+				backend: data.backend
+			});
+			if (self) {
+				console.log("");
+				console.log("Pin the fast-path to skip detection:");
+				console.log(`  export CYBER_MUX=${self.mux} CYBER_MUX_PANE=${self.pane}`);
+			}
+		});
+	});
+}
+function modeCommand(deps) {
+	return new Command("mode").description("Report the detected session backend (tmux / herdr / none)").addOption(FORMAT_OPTION).action(() => {
+		let name = "none";
+		try {
+			name = selectSessionAdapter(deps.env, deps.exec).name;
+		} catch {}
+		output({ backend: name }, () => console.log(name));
+	});
+}
+function openCommand(deps) {
+	return new Command("open").description("Open a new pane/tab/workspace, optionally launching a command in it").option("--launch <command>", "Command line to run in the new pane").addOption(templateOption()).option("--cwd <path>", "Working directory for the new pane", process.cwd()).addOption(AT_OPTION).addOption(ENV_OPTION).addOption(LABEL_OPTION).addOption(FORMAT_OPTION).action(guarded((opts) => {
+		if (opts.template) {
+			const { template } = resolveTemplate(deps, { name: opts.template });
+			const a = adapter(deps);
+			try {
+				reportManifest(openTemplate(deps.exec, a, template, {
+					cwd: opts.cwd,
+					at: opts.at ?? "workspace",
+					label: opts.label ?? template.name,
+					dirExists: deps.store.dirExists,
+					from: callerPane(a, deps.env)
+				}));
+			} catch (err) {
+				reportApplyFailure(err);
+			}
+			return;
+		}
+		const a = adapter(deps);
+		const t = a.open(deps.exec, {
+			cwd: opts.cwd,
+			launch: opts.launch,
+			at: opts.at,
+			env: opts.env,
+			label: opts.label,
+			from: callerPane(a, deps.env)
+		});
+		output({
+			pane: t.id,
+			workspace: t.workspace ?? null
+		}, () => printFields({
+			pane: t.id,
+			workspace: t.workspace
+		}));
+	}));
+}
+/** The `send` group: drive a pane's input WITHOUT taking its turn. Neither subcommand presses an
+* Enter the caller did not write — supplying one is `submit`'s job. Bare `cyber-mux send` is
+* incomplete input, not a content request: it is answered with help on stdout and exit 2 (a usage
+* error — a missing required parameter; see the AXI note in `.agents/spec/axi/README.md`). */
+function sendCommand(deps) {
+	const send = new Command("send").description("Drive a pane without taking its turn (text | keys)");
+	send.addCommand(new Command("text").description("Type literal text into a pane, pressing no Enter (a key-named word is typed, not pressed)").argument("<pane>", "Target pane id").argument("<text>", "Literal text to type").addOption(FORMAT_OPTION).action(guarded((pane, text) => {
+		paneVerb(pane, () => {
+			const a = adapter(deps);
+			a.sendText(deps.exec, resolveTarget(deps, a, pane), text);
+		});
+	})));
+	send.addCommand(new Command("keys").description("Press named keys in a pane, typing nothing (Up, Enter, Escape, C-c, F1 …)").argument("<pane>", "Target pane id").argument("<keys...>", "Key names, in order — core vocabulary is portable, anything else is passed to the backend as-is").addOption(FORMAT_OPTION).action(guarded((pane, keys) => {
+		paneVerb(pane, () => {
+			const a = adapter(deps);
+			a.sendKeys(deps.exec, resolveTarget(deps, a, pane), keys);
+		});
+	})));
+	return send;
+}
+function submitCommand(deps) {
+	return new Command("submit").description("Take a pane's turn: type the text if given, then always press Enter (no text = bare-Enter flush)").argument("<pane>", "Target pane id").argument("[text]", "Text to type before Enter; omit to flush an already-staged buffer without retyping it").addOption(FORMAT_OPTION).action(guarded((pane, text) => {
+		paneVerb(pane, () => {
+			const a = adapter(deps);
+			a.submit(deps.exec, resolveTarget(deps, a, pane), text);
+		});
+	}));
+}
+function readCommand(deps) {
+	return new Command("read").description("Capture a pane's output").argument("<pane>", "Target pane id").option("--lines <n>", "Trailing lines to capture", (v) => Number.parseInt(v, 10)).addOption(FORMAT_OPTION).action(guarded((pane, opts) => {
+		paneVerb(pane, () => {
+			const a = adapter(deps);
+			const t = resolveTarget(deps, a, pane);
+			const out = a.read(deps.exec, t, opts.lines != null ? { lines: opts.lines } : void 0);
+			process.stdout.write(out.endsWith("\n") ? out : `${out}\n`);
+		});
+	}));
+}
+function focusCommand(deps) {
+	return new Command("focus").description("Beam the attached client to a pane").argument("<pane>", "Target pane id").addOption(FORMAT_OPTION).action(guarded((pane) => {
+		paneVerb(pane, () => {
+			const a = adapter(deps);
+			a.focus(deps.exec, resolveTarget(deps, a, pane));
+		});
+	}));
+}
+function closeCommand(deps) {
+	return new Command("close").description("Close a pane").argument("<pane>", "Target pane id").addOption(FORMAT_OPTION).action(guarded((pane) => {
+		paneVerb(pane, () => {
+			const a = adapter(deps);
+			a.teardown(deps.exec, resolveTarget(deps, a, pane));
+		});
+	}));
+}
+function listCommand(deps) {
+	return new Command("list").description("Enumerate every live pane the current backend can see").addOption(FORMAT_OPTION).action(guarded(() => {
+		const panes = adapter(deps).listPanes(deps.exec);
+		output({ panes }, () => printTable(panes, [
+			{
+				label: "pane",
+				get: (p) => p.id
+			},
+			{
+				label: "label",
+				get: (p) => p.label ?? ""
+			},
+			{
+				label: "harness",
+				get: (p) => p.harness ?? ""
+			},
+			{
+				label: "cwd",
+				get: (p) => p.cwd ?? ""
+			}
+		]));
+	}));
+}
+function existsCommand(deps) {
+	return new Command("exists").description("Probe whether a single pane is still live (exit 0 = live, 1 = gone)").argument("<pane>", "Target pane id").addOption(FORMAT_OPTION).action(guarded((pane) => {
+		const a = adapter(deps);
+		const t = resolveTarget(deps, a, pane);
+		const live = a.paneExists(deps.exec, t);
+		output({
+			pane,
+			live
+		}, () => console.log(live ? "live" : "gone"));
+		if (!live) process.exit(1);
+	}));
+}
+function worktreeAddCommand(deps) {
+	return new Command("add").description("Create a git worktree, and open it when given a placement — grouped where the backend can").requiredOption("--branch <branch>", "Branch to create the worktree on").option("--path <path>", "Where to check out the worktree (default: a sibling of the primary checkout)").option("--base <ref>", "Start point for the new branch (default: the current HEAD)").option("--launch <command>", "Command to run in the opened pane; implies --at workspace").addOption(templateOption()).addOption(AT_OPTION).addOption(ENV_OPTION).addOption(LABEL_OPTION).addOption(FORMAT_OPTION).action((opts) => {
+		try {
+			const primaryRoot = resolvePrimaryRoot(deps.exec);
+			if (opts.template) {
+				const { template } = resolveTemplate(deps, { name: opts.template });
+				const path = opts.path ?? resolveWorktreePath(primaryRoot, opts.branch);
+				const a = adapter(deps);
+				const opened = addAndOpenWorktree(deps.exec, a, {
+					primaryRoot,
+					branch: opts.branch,
+					path,
+					base: opts.base,
+					env: templateRootPane(template).env,
+					at: "workspace",
+					label: opts.label ?? template.name,
+					from: callerPane(a, deps.env)
+				});
+				const extra = {
+					root: opened.worktree.root,
+					branch: opened.worktree.branch
+				};
+				try {
+					reportManifest(applyTemplateToRegion(deps.exec, a, template, {
+						root: opened.target,
+						cwd: opened.worktree.root,
+						workspace: opened.workspace ?? null,
+						label: opts.label ?? template.name,
+						rootEnvHonored: opened.envHonored,
+						dirExists: deps.store.dirExists
+					}), extra);
+				} catch (err) {
+					reportApplyFailure(err, extra);
+				}
+				return;
+			}
+			const path = opts.path ?? resolveWorktreePath(primaryRoot, opts.branch);
+			if (!opts.at && !opts.launch && !opts.env) {
+				const wt = gitWorktreeAdapter.add(deps.exec, {
+					primaryRoot,
+					path,
+					branch: opts.branch,
+					base: opts.base
+				});
+				output({
+					root: wt.root,
+					branch: wt.branch,
+					pane: null,
+					workspace: null
+				}, () => printFields({
+					root: wt.root,
+					branch: wt.branch
+				}));
+				return;
+			}
+			const at = opts.at ?? "workspace";
+			const a = adapter(deps);
+			reportOpenedWorktree(addAndOpenWorktree(deps.exec, a, {
+				primaryRoot,
+				branch: opts.branch,
+				path,
+				base: opts.base,
+				launch: opts.launch,
+				env: opts.env,
+				at,
+				label: opts.label,
+				from: callerPane(a, deps.env)
+			}), `cyber-mux worktree add --branch ${opts.branch} --at workspace`);
+		} catch (err) {
+			reportWorktreeFailure(err);
+		}
+	});
+}
+function worktreeOpenCommand(deps) {
+	return new Command("open").description("Open an existing git worktree — groups it with the repo where the backend can bind").argument("<path>", "Worktree path to open").option("--launch <command>", "Command to run in the opened pane").addOption(AT_OPTION).addOption(ENV_OPTION).addOption(LABEL_OPTION).addOption(FORMAT_OPTION).action((path, opts) => {
+		try {
+			const primaryRoot = resolvePrimaryRoot(deps.exec);
+			const a = adapter(deps);
+			reportOpenedWorktree(openExistingWorktree(deps.exec, a, {
+				primaryRoot,
+				path,
+				launch: opts.launch,
+				env: opts.env,
+				at: opts.at,
+				label: opts.label,
+				from: callerPane(a, deps.env)
+			}), `cyber-mux worktree open ${path} --at workspace`);
+		} catch (err) {
+			reportWorktreeFailure(err);
+		}
+	});
+}
+function worktreeListCommand(deps) {
+	return new Command("list").description("Every worktree of the repo, and the workspace each is open in").addOption(FORMAT_OPTION).action(() => {
+		try {
+			const primaryRoot = resolvePrimaryRoot(deps.exec);
+			const worktrees = listWorktrees(deps.exec, optionalAdapter(deps), { primaryRoot });
+			output({ worktrees }, () => printTable(worktrees, [
+				{
+					label: "branch",
+					get: (w) => w.branch ?? "(detached)"
+				},
+				{
+					label: "root",
+					get: (w) => w.root
+				},
+				{
+					label: "linked",
+					get: (w) => String(w.linked)
+				},
+				{
+					label: "workspace",
+					get: (w) => w.workspace ?? ""
+				}
+			]));
+		} catch (err) {
+			reportWorktreeFailure(err);
+		}
+	});
+}
+function worktreeRemoveCommand(deps) {
+	return new Command("remove").description("Remove a git worktree — refuses the primary checkout and uncommitted changes unless --force").argument("<path>", "Worktree path to remove").option("--force", "Discard uncommitted changes in the worktree").action((path, opts) => {
+		try {
+			const primaryRoot = resolvePrimaryRoot(deps.exec);
+			removeWorktree(deps.exec, optionalAdapter(deps), path, {
+				primaryRoot,
+				force: opts.force
+			});
+		} catch (err) {
+			reportWorktreeFailure(err);
+		}
+	});
+}
+function worktreeCommand(deps) {
+	const cmd = new Command("worktree").description("Git worktree helpers for spawning/tearing down a session");
+	cmd.addCommand(worktreeAddCommand(deps));
+	cmd.addCommand(worktreeOpenCommand(deps));
+	cmd.addCommand(worktreeListCommand(deps));
+	cmd.addCommand(worktreeRemoveCommand(deps));
+	return cmd;
+}
+/**
+* Translate a commander-level rejection into the SAME coded error surface every verb uses. commander's
+* own failures — a flag the command does not define, a required argument the parser never received, two
+* mutually-exclusive flags — are USAGE errors: the fix is a different invocation, not a retry, so they
+* exit 2, and they belong on stdout under a stable code exactly as an operation failure does.
+*
+* The callback is attached per command, so `command` is the SUBCOMMAND actually invoked — which is what
+* lets an unknown flag be rejected against that subcommand's own flags (`template list` does not share
+* `template save`'s), and the offending flag be named beside them so the agent self-corrects in one turn
+* rather than a second `--help` round trip.
+*/
+function handleCommanderError(command, err) {
+	if (err.code === "commander.helpDisplayed" || err.code === "commander.version") process.exit(err.exitCode);
+	if (err.code === "commander.help") {
+		process.stdout.write(command.helpInformation());
+		process.exit(2);
+	}
+	if (err.code === "commander.unknownOption") reportError(unknownFlagError(command, err));
+	if (err.code === "commander.missingArgument") reportError(missingArgumentError(command, err));
+	if (err.code === "commander.conflictingOption" || err.code === "commander.excessArguments") reportError(new CliError("usage-error", usageMessage(err), "pass only one of the conflicting flags, then re-run", 2));
+	throw err;
+}
+/** commander's raw message minus its own `error: ` prefix — its own CLI's text, safe to surface. */
+function usageMessage(err) {
+	return (err.message ?? "").replace(/^error:\s*/, "");
+}
+/** An unknown flag, named beside the command's OWN valid flags, so the agent self-corrects in one turn. */
+function unknownFlagError(command, err) {
+	const flag = err.message.match(/'([^']+)'/)?.[1] ?? "the flag";
+	const valid = command.options.map((o) => o.long ?? o.short).filter((f) => Boolean(f));
+	return new CliError("unknown-flag", `unknown flag ${flag} for ${command.name()}`, valid.length > 0 ? `valid flags for ${command.name()}: ${valid.join(" ")}` : `${command.name()} takes no flags`, 2);
+}
+/** A required argument the parser never received — a usage error naming the missing argument. */
+function missingArgumentError(command, err) {
+	const arg = err.message.match(/'([^']+)'/)?.[1] ?? "an argument";
+	return new CliError("missing-argument", `missing required argument: ${arg}`, `provide ${arg}: cyber-mux ${command.name()} <${arg}>`, 2);
+}
+/**
+* Every command in the tree gets a translating `exitOverride` — NOT inherited by subcommands, so it is
+* walked. Without it `cyber-mux send` with no subcommand would `process.exit` straight from the group
+* and kill the caller's process (in tests, the runner itself); with the plain default it would throw a
+* bare `CommanderError`. This routes commander's own rejections through the coded error surface, so a
+* missing argument or unknown flag reaches the caller as an exit-2 structured error on stdout, exactly
+* as an ambiguity or a `no-mux` does.
+*/
+function exitOverrideTree(command) {
+	command.exitOverride((err) => handleCommanderError(command, err));
+	for (const sub of command.commands) exitOverrideTree(sub);
+	return command;
+}
+/** Assembles the full command tree against the given deps (real env/exec in production, fakes in
+* tests). Every command in the tree gets `exitOverride()`, so commander throws a `CommanderError`
+* instead of calling `process.exit` directly and a rejection (an invalid `--at` choice, a missing
+* argument, a bare `send`) is catchable both here and in tests, rather than killing the test
+* runner's own process. */
+function buildProgram(cliDeps = REAL_DEPS) {
+	const deps = {
+		env: cliDeps.env,
+		exec: cliDeps.exec,
+		store: cliDeps.store ?? realTemplateStore
+	};
+	const program = new Command().name("cyber-mux").description("Cross-multiplexer pane control — one contract over tmux and herdr").version("0.0.0");
+	program.addCommand(doctorCommand(deps));
+	program.addCommand(modeCommand(deps));
+	program.addCommand(openCommand(deps));
+	program.addCommand(sendCommand(deps));
+	program.addCommand(submitCommand(deps));
+	program.addCommand(readCommand(deps));
+	program.addCommand(focusCommand(deps));
+	program.addCommand(closeCommand(deps));
+	program.addCommand(listCommand(deps));
+	program.addCommand(existsCommand(deps));
+	program.addCommand(worktreeCommand(deps));
+	program.addCommand(templateCommand(deps));
+	return exitOverrideTree(program);
+}
+/** The real CLI entry point — called explicitly by `bin/cyber-mux.mjs`, never as an import-time
+* side effect, so importing this module (e.g. from tests) never runs the real CLI. */
+async function main() {
+	try {
+		await buildProgram().parseAsync(process.argv);
+	} catch (err) {
+		if (err instanceof CliError) reportError(err);
+		if (err instanceof CommanderError) process.exit(err.exitCode);
+		process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+		process.exit(1);
+	}
+}
+//#endregion
+export { buildProgram, main };