cyber-mux 0.3.0 → 0.5.0

package/dist/{backend-DnrbmL6N.mjs → backend-DjX6RlAG.mjs}

@@ -1,4 +1,4 @@
-import { m as withReason, p as nodeExec, s as normalizeWorktreePath } from "./worktree-CoQdRgv1.mjs";
+import { h as withReason, m as nodeExec, s as normalizeWorktreePath } from "./worktree-hHuFZkpW.mjs";
 import { resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 //#region src/env-fallback.ts
@@ -50,6 +50,512 @@ function envFallback(env, command) {
 	};
 }
 //#endregion
+//#region src/floating.ts
+/**
+* The floating-pane refusal — the `'pane:float'` placement's answer on a backend that has no
+* floating-pane concept (wezterm, herdr).
+*
+* Its own module rather than a member of `mux.ts` for the reason every other seam type is not a
+* class: `mux.ts` is the CONTRACT and carries no runtime value, so putting the one class the
+* contract's refusal needs there would make every consumer of the types import a value too. It is
+* the core-surface parallel of `CaptureUnsupportedError` (`template-capture.ts`) and
+* `AgentLifecycleUnsupportedError` (`agent.ts`), and it rides the `.` barrel rather than a subpath
+* because the verb it refuses — `open` — is on the surface everybody gets.
+*/
+/**
+* A floating pane asked of a backend that cannot open one (`open` with `at: 'pane:float'` on wezterm
+* or herdr). A refusal, never a substitution: the nearest thing those backends could open is a tiled
+* split, which takes a share of the region and resizes its other panes — exactly the property a float
+* exists to avoid — so a caller would get back a pane whose id satisfies them and whose behavior does
+* not. There is no truthful degrade, so there is no degrade.
+*
+* PORTABLE and exit-code-free by design, the exact mirror of `AgentLifecycleUnsupportedError`. The
+* DECISION to refuse is the library's, made inside each adapter's `open` — the one place that sees
+* both the backend and the requested placement. How the refusal SURFACES (the exit code, the fix
+* hint, the exact sentence) is the CLI's, which catches this and re-raises its own
+* `backend-unsupported` error. `backend` names the backend so a caller composes the message without
+* re-deriving it; the terse `message` is a factual log line.
+*/
+var FloatingPanesUnsupportedError = class extends Error {
+	backend;
+	constructor(backend) {
+		super(`${backend} cannot open a floating pane`);
+		this.backend = backend;
+		this.name = "FloatingPanesUnsupportedError";
+	}
+};
+/**
+* Refuse a `'pane:float'` open on the backend named — the single spelling of the refusal, called by
+* every adapter that lacks the capability so the two cannot drift into two different messages.
+*
+* Takes the NAME rather than the adapter: it is called from inside `open`, where the adapter object is
+* still being constructed on some backends, and the name is the only thing the error carries anyway.
+*/
+function refuseFloatingPane(backend) {
+	throw new FloatingPanesUnsupportedError(backend);
+}
+/**
+* Whether `adapter` can open a floating pane — the declaration read, so a caller asking the question
+* before opening spells it once rather than reaching into an optional member that may be `undefined`.
+*
+* The pre-flight check, not the enforcement: `open` re-checks as its own contract (the same
+* belt-and-braces `agent wait` runs against `agentLifecycle`), so a caller that skips this is refused
+* just as loudly — one exec later.
+*/
+function canFloatPanes(adapter) {
+	return adapter.canFloatPanes === true;
+}
+//#endregion
+//#region src/wait-output.ts
+/** How long a polling backend sleeps between reads when the caller names no cadence. */
+const DEFAULT_WAIT_POLL_MS = 150;
+/**
+* The seam's own precondition on a wait pattern: EXACTLY ONE of `match`/`regex`, and a `regex` that
+* compiles.
+*
+* Enforced here, at the seam, rather than per adapter, for `assertRatioInRange`'s reason — it is a
+* universal property of what a wait pattern IS, true on every backend, not a per-backend policy. Both
+* halves matter for portability in different ways: the one-of rule is refusable by herdr's CLI and by
+* nothing at all on a polling backend, so leaving it to the backend would make the same call fail on
+* one and silently pick a winner on another; and compiling the source turns a MALFORMED pattern into
+* the same loud failure everywhere, instead of a herdr refusal on one backend and a poll that throws
+* on its first read somewhere else.
+*
+* What it deliberately does NOT check is dialect: a pattern using ECMAScript-only syntax compiles here
+* and is then herdr's own to accept or refuse (see `MuxWaitOptions.regex`). Validating against the
+* intersection of two regex engines would mean shipping a third one.
+*/
+function assertWaitPattern(opts) {
+	const hasMatch = opts.match != null;
+	const hasRegex = opts.regex != null;
+	if (hasMatch && hasRegex) throw new Error("wait pattern must be one of match or regex — got both");
+	if (!hasMatch && !hasRegex) throw new Error("wait pattern must be one of match or regex — got neither");
+	if (opts.match != null && opts.match === "") throw new Error("wait pattern match must not be empty");
+	if (opts.regex != null) try {
+		new RegExp(opts.regex);
+	} catch (err) {
+		throw new Error(`wait pattern regex is not a valid expression: ${opts.regex} — ${err.message}`);
+	}
+}
+/**
+* Whether `output` satisfies the pattern, and the single line to point at when it does.
+*
+* The match runs against the WHOLE snapshot, not line by line, so a regex that spans a newline still
+* hits — that is why `matchedLine` is derived separately and left absent when no single line carries
+* the match on its own. Pure, so the tricky half is testable with no multiplexer at all, exactly as
+* `template-capture`'s geometry derivation is.
+*/
+function matchWaitPattern(output, opts) {
+	assertWaitPattern(opts);
+	const hit = (text) => opts.match != null ? text.includes(opts.match) : new RegExp(opts.regex).test(text);
+	if (!hit(output)) return {
+		matched: false,
+		output
+	};
+	const line = output.split("\n").find(hit);
+	return {
+		matched: true,
+		output,
+		...line != null ? { matchedLine: line } : {}
+	};
+}
+/**
+* `waitForOutput` for a backend with NO native wait — poll its own `read` until the pattern matches or
+* the deadline passes. tmux, WezTerm and Zellij all route their seam method straight through here, so
+* the three share one cadence, one deadline rule and one liveness rule rather than three copies that
+* can drift; herdr overrides it with its native primitive.
+*
+* **Reads first, sleeps second.** The snapshot on screen when the call arrives is searched before any
+* sleeping, so a pattern already printed returns immediately — the seam's stated "existing output
+* counts" rule, and the same order herdr's native wait documents for itself.
+*
+* **A gone pane throws instead of timing out**, which is `nudge`'s rule for the same reason: a dead
+* pane and a quiet one both read back empty, so without the liveness probe every dead peer would be
+* reported as a timeout — a shape the caller reads as "still working" — and the real cause would be
+* buried. Probed BEFORE the first read (so a pane that was already gone fails at once rather than
+* after the full timeout) and again after the deadline (so a pane that died mid-wait is not reported as
+* one that merely stayed quiet). Never probed per poll: that would double every backend's query load
+* for a fact that only changes the verdict at the end.
+*/
+async function pollForOutput(adapter, exec, target, opts) {
+	assertWaitPattern(opts);
+	const pollMs = opts.pollMs ?? 150;
+	const now = opts.now ?? (() => Date.now());
+	const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const readOpts = opts.lines != null ? { lines: opts.lines } : void 0;
+	assertPaneLive(adapter, exec, target);
+	const deadline = now() + opts.timeoutMs;
+	let output = "";
+	for (;;) {
+		output = adapter.read(exec, target, readOpts).text;
+		const result = matchWaitPattern(output, opts);
+		if (result.matched) return result;
+		if (now() >= deadline) break;
+		await sleep(pollMs);
+	}
+	assertPaneLive(adapter, exec, target);
+	return {
+		matched: false,
+		output
+	};
+}
+/** The liveness probe both ends of a poll share, throwing `nudge`'s named failure rather than letting a
+* dead pane be reported as a quiet one. */
+function assertPaneLive(adapter, exec, target) {
+	if (!adapter.paneExists(exec, target)) throw new Error(`wait failed: pane ${target.id} no longer exists — the pane is gone, not quiet.`);
+}
+//#endregion
+//#region src/mux.cmux.ts
+/**
+* cmux backend — detected via `$CMUX_WORKSPACE_ID`. Drives cmux's CLI through `cmux <verb> …`
+* (https://cmux.com/docs/api), the same synchronous-CLI shape tmux, herdr, wezterm, and zellij
+* already give `Exec`.
+*
+* cmux is a Ghostty-based macOS terminal with vertical tabs and notifications for AI coding agents.
+* Its hierarchy is Window → Workspace → Pane → Surface. A **Surface** is the terminal unit (a tab
+* within a pane), which maps to cyber-mux's `LivePane`. The env variable `$CMUX_SURFACE_ID` carries
+* the caller's surface identity — analogous to `$TMUX_PANE` or `$WEZTERM_PANE`.
+*
+* Probed from the cmux docs and CLI reference only — cmux is not installed in this sandbox (it is
+* macOS-GUI-only), so nothing here carries the "verified against a live binary" claim
+* `mux.tmux.ts`/`mux.herdr.ts` make; it makes the same honest disclaimer `mux.wezterm.ts` and
+* `mux.zellij.ts` do.
+*
+* Real capability shape that fell out of the probe:
+*
+* - **Surface is the terminal unit, not Pane.** cmux's "pane" holds multiple "surfaces" (tabs). The
+*   terminal a command runs in is a surface, so `CMUX_SURFACE_ID` is the self-identity env var and
+*   `LivePane.id` carries a surface id. `--at tab` maps to `cmux new-surface` (a new tab in the
+*   current pane); `--at pane:*` maps to `cmux new-pane` (a split, which creates a pane with one
+*   surface).
+* - **Workspace is a real tier.** `cmux new-workspace` creates a genuinely separate workspace,
+*   reported as `OpenedPane.workspace`.
+* - **No `--env` on any route.** Like wezterm and zellij, env is native at no tier, so every open
+*   rides the `envFallback` compensation (an `env K=V` prefix on the launch command, or a stderr
+*   warning when there is no command to ride).
+* - **Splits can be sized** — `cmux new-pane --direction right --size 0.3` sizes the NEW pane, so
+*   `ratio` (fraction kept by the ORIGINAL) is inverted to `1 - ratio`. `canSizeSplits` is true.
+* - **`new-pane` has no split-TARGET flag.** It splits the focused pane (or the biggest space); the
+*   `--workspace` flag specifies which workspace, but not which pane within it. So `from` — which
+*   pane a `pane:*` split lands beside — is honored by FOCUSING that surface first, the sole way to
+*   choose the split target. That is a real focus move, and the honest cost of getting the RIGHT
+*   pane split.
+* - **No pane geometry adapter.** `cmux list-panes --json` does not report position, so `regions`
+*   (`describeRegion`/`describeWorkspace`) is not implementable. `template save` refuses on cmux by
+*   naming the backend, the same optional-absence it handles for wezterm.
+* - **No git-worktree concept in the CLI.** No `worktree` subcommand, so — like tmux, wezterm, and
+*   zellij — this backend never binds a worktree to a workspace; callers fall back to plain git plus
+*   `open()`.
+* - **Naming surfaces.** cmux surfaces can be labeled — verified against the skill docs: a label can
+*   be set after creation. No `--label` flag on `new-surface` / `new-pane`, so naming is post-birth.
+*/
+function createCmuxAdapter(deps) {
+	const adapter = {
+		name: "cmux",
+		canSizeSplits: true,
+		open(exec, opts) {
+			const at = opts.at ?? "tab";
+			if (at === "workspace") {
+				const args = ["--json", "new-workspace"];
+				if (opts.cwd) args.push("--cwd", opts.cwd);
+				const out = exec("cmux", args);
+				if (!out) throw new Error(withReason(exec, "cmux new-workspace failed"));
+				const parsed = parseCmuxOutput(out);
+				if (!parsed.workspace_ref) throw new Error("cmux new-workspace did not report the workspace ref");
+				const surfaceId = parsed.surface_ref;
+				if (!surfaceId) throw new Error("cmux new-workspace did not report the initial surface ref");
+				const opened = openedSurface(surfaceId, parsed.pane_ref, parsed.workspace_ref);
+				if (opts.label) adapter.rename(exec, opened, "tab", opts.label);
+				runLaunch$3(adapter, exec, opened, opts.env, opts.launch);
+				return opened;
+			}
+			if (at === "tab") {
+				const args = ["--json", "new-surface"];
+				if (opts.within) args.push("--pane", opts.within);
+				if (opts.cwd) args.push("--cwd", opts.cwd);
+				const out = exec("cmux", args);
+				if (!out) throw new Error(withReason(exec, "cmux new-surface failed"));
+				const parsed = parseCmuxOutput(out);
+				const surfaceId = parsed.surface_ref;
+				if (!surfaceId) throw new Error("cmux new-surface did not report the surface ref");
+				const opened = openedSurface(surfaceId, parsed.pane_ref, deps.workspace);
+				if (opts.label) adapter.rename(exec, opened, "tab", opts.label);
+				runLaunch$3(adapter, exec, opened, opts.env, opts.launch);
+				return opened;
+			}
+			if (at === "pane:float") refuseFloatingPane(adapter.name);
+			if (opts.from) adapter.focus(exec, opts.from);
+			const args = [
+				"--json",
+				"new-pane",
+				"--direction",
+				at === "pane:down" ? "down" : "right"
+			];
+			if (opts.cwd) args.push("--cwd", opts.cwd);
+			if (opts.ratio != null) args.push("--size", String(1 - opts.ratio));
+			const out = exec("cmux", args);
+			if (!out) throw new Error(withReason(exec, "cmux new-pane failed"));
+			const parsed = parseCmuxOutput(out);
+			const surfaceId = parsed.surface_ref;
+			if (!surfaceId) throw new Error("cmux new-pane did not report the surface ref");
+			const opened = openedSurface(surfaceId, parsed.pane_ref, deps.workspace);
+			if (opts.label) adapter.rename(exec, opened, "pane", opts.label);
+			runLaunch$3(adapter, exec, opened, opts.env, opts.launch);
+			return opened;
+		},
+		rename(exec, target, tier, name) {
+			if (tier === "tab") {
+				exec("cmux", [
+					"rename-surface",
+					"--surface",
+					target.id,
+					"--title",
+					name
+				]);
+				return;
+			}
+			const paneRef = surfaceToPane(exec, target.id);
+			if (paneRef) exec("cmux", [
+				"rename-pane",
+				"--pane",
+				paneRef,
+				"--title",
+				name
+			]);
+		},
+		group() {},
+		sendText(exec, target, text) {
+			exec("cmux", [
+				"send",
+				"--surface",
+				target.id,
+				text
+			]);
+		},
+		sendKeys(exec, target, keys) {
+			for (const key of keys) exec("cmux", [
+				"send-key",
+				"--surface",
+				target.id,
+				toCmuxKey(key)
+			]);
+		},
+		submit(exec, target, text) {
+			if (!text) {
+				adapter.sendKeys(exec, target, ["Enter"]);
+				return;
+			}
+			adapter.sendText(exec, target, text);
+			adapter.sendKeys(exec, target, ["Enter"]);
+		},
+		read(exec, target, opts) {
+			const args = [
+				"read-screen",
+				"--surface",
+				target.id
+			];
+			if (opts?.lines != null) args.push("--lines", String(opts.lines));
+			return { text: exec("cmux", args) ?? "" };
+		},
+		waitForOutput(exec, target, opts) {
+			return pollForOutput(adapter, exec, target, opts);
+		},
+		focus(exec, target) {
+			exec("cmux", [
+				"focus-panel",
+				"--panel",
+				target.id
+			]);
+		},
+		teardown(exec, target) {
+			exec("cmux", [
+				"close-surface",
+				"--surface",
+				target.id
+			]);
+		},
+		paneExists(exec, target) {
+			return listCmuxSurfaces(exec).some((s) => s.id === target.id);
+		},
+		isPaneFocused(exec, target) {
+			const found = listCmuxSurfaces(exec).find((s) => s.id === target.id);
+			if (!found) return void 0;
+			return found.is_focused === true;
+		},
+		listPanes(exec) {
+			return listCmuxSurfaces(exec).map((s) => {
+				const pane = {
+					id: s.id,
+					mux: "cmux",
+					floating: false
+				};
+				if (s.cwd) pane.cwd = s.cwd;
+				if (s.title) pane.label = s.title;
+				return pane;
+			});
+		}
+	};
+	return adapter;
+}
+function parseCmuxOutput(out) {
+	try {
+		return JSON.parse(out);
+	} catch {
+		return {};
+	}
+}
+function listCmuxSurfaces(exec) {
+	const out = exec("cmux", ["list-panes", "--json"]);
+	if (!out) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(out);
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(parsed)) return [];
+	const surfaces = [];
+	for (const pane of parsed) if (pane && Array.isArray(pane.surfaces)) {
+		for (const s of pane.surfaces) if (s?.surface_ref) surfaces.push({
+			id: s.surface_ref,
+			title: s.title,
+			cwd: s.cwd,
+			is_focused: s.is_focused
+		});
+	}
+	return surfaces;
+}
+function openedSurface(surfaceId, paneRef, workspace) {
+	const opened = {
+		id: surfaceId,
+		tab: paneRef ?? surfaceId
+	};
+	if (workspace) opened.workspace = workspace;
+	return opened;
+}
+function surfaceToPane(exec, surfaceId) {
+	const out = exec("cmux", ["list-panes", "--json"]);
+	if (!out) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(out);
+	} catch {
+		return;
+	}
+	if (!Array.isArray(parsed)) return void 0;
+	for (const pane of parsed) if (pane?.pane_ref && Array.isArray(pane.surfaces)) {
+		for (const s of pane.surfaces) if (s && s.surface_ref === surfaceId) return pane.pane_ref;
+	}
+}
+function runLaunch$3(adapter, exec, target, env, launch) {
+	const fallback = envFallback(env, launch);
+	if (fallback.kind === "dropped") {
+		process.stderr.write(`env (${fallback.variables.join(", ")}) could not be set on this cmux surface — cmux has no --env flag on new-pane/new-surface/new-workspace
+`);
+		return;
+	}
+	if (fallback.command !== void 0) adapter.submit(exec, target, fallback.command);
+}
+/**
+* The core key vocabulary's cmux spelling. cmux uses lowercase key names: enter, tab, escape, etc.
+*/
+const CMUX_KEY_RENAMES = {
+	Enter: "enter",
+	Tab: "tab",
+	Escape: "escape",
+	Backspace: "backspace",
+	Space: "space",
+	Up: "up",
+	Down: "down",
+	Left: "left",
+	Right: "right",
+	"C-c": "ctrl+c"
+};
+function toCmuxKey(key) {
+	return CMUX_KEY_RENAMES[key] ?? key.toLowerCase();
+}
+//#endregion
+//#region src/ratio.ts
+/**
+* The seam's own precondition on `MuxOpenOptions.ratio`: a fraction STRICTLY between 0 and 1.
+*
+* `ratio` is the fraction kept by the ORIGINAL pane. Outside `0 < ratio < 1` there is no split it can
+* name: `1 - ratio` goes negative above 1 (tmux `-l -50%` / wezterm `--percent -50`), and 0 or 1 hands
+* one side the whole region and the other nothing — a mistake, never an intent worth honoring. Left
+* unrendered these produce a silently broken split, not an error, which is the exact silent-wrong
+* output this seam's loud-over-quiet preference exists to refuse.
+*
+* Enforced HERE, at the seam, rather than left to each caller, because the invariant is a universal
+* property of what a ratio IS — true on every backend — not a per-caller policy. (The DEGRADE policy —
+* what a caller does when a backend cannot size a split at all — genuinely stays the caller's, unchanged;
+* range validity and degrade policy are different questions.) A caller cannot reach an adapter with an
+* out-of-range ratio and have it silently rendered; `template`'s schema still refuses one earlier, per
+* node, with a path-qualified message, so the two layers do different jobs and the seam is the backstop.
+*
+* The guard lives WITH the rendering: it is called by each backend's size render helper, so a backend
+* that cannot size a split (zellij) renders no ratio and so never reaches this guard — a dropped value
+* is never checked, valid or not, which is the same as the even-default degrade its callers already take.
+*/
+function assertRatioInRange(ratio) {
+	if (!Number.isFinite(ratio) || ratio <= 0 || ratio >= 1) throw new Error(`ratio must be strictly between 0 and 1 — got ${ratio}`);
+}
+//#endregion
+//#region src/read-window.ts
+/**
+* The READ WINDOW: how much of a pane a capture asks for, and whether rows sat above what came back.
+*
+* Both halves live here because they are one question. A capture is bounded — by the caller's `lines`,
+* or by the backend's own default (the viewport on all four) — and "was anything dropped" is a
+* property of that bound. Unbind the window (`lines: 'all'`) and the answer is `false` by
+* construction, with no probe to spend.
+*
+* The truncation rule itself is shared by every adapter so the four backends answer
+* `MuxReadResult.truncated` by one definition rather than four that can drift — the same reason
+* `pollForOutput` owns one poll cadence for the three polling backends.
+*
+* Pure, and deliberately so: the tricky half of the answer is a row count, testable with no
+* multiplexer at all (`template-capture`'s geometry derivation is the precedent). Each adapter owns
+* only the one thing that genuinely differs — how its backend spells "one row deeper".
+*/
+/**
+* How many terminal ROWS a capture carries.
+*
+* A trailing newline is a terminator, not an empty row: `capture-pane` and `dump-screen` both end
+* their output with one, so counting it would make every capture look one row longer than the screen
+* and — worse — would compare unequal against a probe that happened not to end with one. An empty
+* capture is zero rows, not one.
+*/
+function capturedRows(text) {
+	if (text === "") return 0;
+	return (text.endsWith("\n") ? text.slice(0, -1) : text).split("\n").length;
+}
+/**
+* Whether `capture` omitted older rows, judged against `deeper` — the SAME read taken one row further
+* back.
+*
+* More rows in the deeper read means there was output above the captured window that the caller did
+* not receive. An equal (or smaller) count means the deeper read had nothing more to give: the
+* backend clamped at the top of what it holds, so the caller has everything there is.
+*
+* Row counts, not text equality, because the two reads are not required to render the shared rows
+* identically — herdr's deeper probe reads a different `--source`, and a backend may re-wrap. What
+* both reads DO agree on is how many rows they returned, and that is the whole question.
+*/
+function isReadTruncated(capture, deeper) {
+	return capturedRows(deeper) > capturedRows(capture);
+}
+/**
+* The row count that stands in for "the whole scrollback" on a backend whose read takes a NUMBER and
+* has no all-history token of its own (WezTerm's `--start-line`, herdr's `--lines`) — tmux (`-S -`)
+* and Zellij (`--full`) say it exactly and never reach for this.
+*
+* A million rows is past any real pane's history (tmux's own `history-limit` defaults to 2000) and
+* both backends CLAMP an over-deep window to what they hold rather than failing, so this reads as
+* "everything" without pretending to be a precise number. It stays under a u32, which is what herdr's
+* CLI parses `--lines` as.
+*/
+const FULL_SCROLLBACK_LINES = 1e6;
+//#endregion
 //#region src/mux.herdr.ts
 /**
 * herdr backend — detected via `$HERDR_ENV`. herdr (https://herdr.dev) is an agent-aware terminal
@@ -60,6 +566,13 @@ function envFallback(env, command) {
 *
 * 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`.
+*
+* **Verified against 0.8.0** (protocol 19), re-probed against a live server. Everything this adapter
+* drives held: the split/read/run/send-keys lifecycle, `pane wait-output`'s success and error
+* envelopes, `pane list`/`get`/`layout`, `workspace create`/`tab create`, and the `env` and worktree
+* parameter sets below. The per-claim markers that follow name the version each was LAST established
+* against — a claim still reading 0.7.4/0.7.5 is one 0.8.0 gave no occasion to re-measure (no attached
+* client, or no live agent in the pane), not one that failed.
 */
 const herdrMuxAdapter = {
 	name: "herdr",
@@ -94,10 +607,11 @@ const herdrMuxAdapter = {
 			]);
 			if (!out) throw new Error(withReason(exec, "herdr tab create failed"));
 			opened = parseRootPaneId(out, "herdr tab create");
-		} else {
+		} else if (at === "pane:float") refuseFloatingPane(herdrMuxAdapter.name);
+		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 size = opts.ratio != null ? ["--ratio", toHerdrRatio(opts.ratio)] : [];
 			const out = exec("herdr", [
 				"pane",
 				"split",
@@ -159,16 +673,86 @@ const herdrMuxAdapter = {
 			text
 		]);
 	},
+	/**
+	* 0.8.0 added a `truncated` boolean to the read result, and it is REQUIRED in the socket schema's
+	* `PaneReadResult` — but it is not reachable from here, and that is a fact about the CLI rather than
+	* a choice: `herdr pane read` prints the pane's bare TEXT, no envelope, and its only 0.8.0 additions
+	* are `--format`/`--ansi`/`--raw`, which select the text's escaping. There is no `--json`. So the
+	* flag rides the socket API this adapter deliberately does not speak, and the one CLI surface that
+	* does hand back the envelope is `pane wait-output` (`.result.read.truncated` — seen live on 0.8.0).
+	* Surfacing truncation therefore costs a return-shape change, not a flag; see issue #100, which owns
+	* it across all four backends. Noted here so the next reader does not re-derive the dead end.
+	*/
 	read(exec, target, opts) {
+		if (opts?.lines === "all") {
+			const text = paneRead(exec, target, "recent", FULL_SCROLLBACK_LINES);
+			return opts.truncation ? {
+				text,
+				truncated: false
+			} : { text };
+		}
+		const text = paneRead(exec, target, "visible", opts?.lines);
+		if (!opts?.truncation) return { text };
+		return {
+			text,
+			truncated: isReadTruncated(text, paneRead(exec, target, "recent", capturedRows(text) + 1))
+		};
+	},
+	/**
+	* The one backend with a NATIVE wait: `pane wait-output` blocks in herdr itself (arrived in 0.7.5,
+	* still native in 0.8.0), so no poll loop is run here and no snapshot is pulled across the CLI
+	* boundary on every tick.
+	*
+	* `--source visible` is pinned rather than left to herdr's own default (`recent_unwrapped`, verified
+	* against 0.7.5 — the help still says `recent` in 0.8.0). The seam's rule is that a wait searches exactly what
+	* `read` returns, and `read` pins `visible` here; taking the default would make the same wait mean a
+	* different snapshot on this backend than on every polling one.
+	*
+	* Telling a TIMEOUT (an answer) from a broken wait (a failure) is the whole difficulty, because herdr
+	* spells both the same way: exit 1 with an error envelope on stderr, so `Exec` yields `null` for
+	* either. Two tiers answer it, in order:
+	*
+	* 1. **The envelope's `code`**, when the runner captured stderr into `lastError` (re-verified against
+	*    0.8.0: `{"error":{"code":"timeout",…}}` vs `{"error":{"code":"pane_not_found",…}}`). Exact.
+	* 2. **A live pane that actually consumed the deadline**, when it did not. `Exec.lastError` is
+	*    specified as a diagnostic and NEVER a control-flow signal — a runner that discards stderr must
+	*    still work — so the code cannot be the only answer. Liveness alone is not enough either, and the
+	*    reason is a whole released version of the backend: herdr 0.7.4 has no `pane wait-output` at all,
+	*    so it answers with clap's usage text (not an envelope) INSTANTLY, and a liveness-only rule reads
+	*    that as "timed out" — a silently wrong answer for a wait that never ran. Elapsed time is the fact
+	*    that separates them and needs no stderr: a wait that returns in a fraction of its own timeout did
+	*    not wait. Both must hold — the pane is live AND the deadline was spent — or this throws.
+	*
+	* A timeout costs ONE extra `read`, because herdr's timeout envelope carries no snapshot and the seam
+	* promises the caller the evidence its verdict was reached on. It is taken at the deadline, so it is
+	* the same "last look at the pane" a polling backend returns, one poll interval later.
+	*/
+	async waitForOutput(exec, target, opts) {
+		assertWaitPattern(opts);
+		const now = opts.now ?? (() => Date.now());
+		const pattern = opts.match != null ? ["--match", opts.match] : ["--regex", opts.regex];
 		const args = [
 			"pane",
-			"read",
+			"wait-output",
 			target.id,
 			"--source",
-			"visible"
+			"visible",
+			"--timeout",
+			String(opts.timeoutMs)
 		];
-		if (opts?.lines != null) args.push("--lines", String(opts.lines));
-		return exec("herdr", args) ?? "";
+		args.push(...pattern);
+		if (opts.lines != null) args.push("--lines", String(opts.lines));
+		const started = now();
+		const out = exec("herdr", args);
+		if (out == null) {
+			if (!isHerdrWaitTimeout(exec, target, opts.timeoutMs, now() - started)) throw new Error(withReason(exec, `herdr pane wait-output failed for pane ${target.id}`));
+			const readOpts = opts.lines != null ? { lines: opts.lines } : void 0;
+			return {
+				matched: false,
+				output: herdrMuxAdapter.read(exec, target, readOpts).text
+			};
+		}
+		return parseWaitOutput(out);
 	},
 	focus(exec, target) {
 		const { workspaceId, tabId } = parsePaneLocation$1(exec("herdr", [
@@ -230,10 +814,13 @@ const herdrMuxAdapter = {
 		return panes.filter((p) => typeof p?.pane_id === "string").map((p) => {
 			const harness = p.agent || void 0;
 			const label = p.label || void 0;
+			const agentStatus = toAgentStatus(p.agent_status);
 			return {
 				id: p.pane_id,
 				mux: "herdr",
+				floating: false,
 				...harness !== void 0 ? { harness } : {},
+				...agentStatus !== void 0 ? { agentStatus } : {},
 				...p.cwd !== void 0 ? { cwd: p.cwd } : {},
 				...label !== void 0 ? { label } : {}
 			};
@@ -256,9 +843,9 @@ const herdrMuxAdapter = {
 		* 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.
+		* `layout` is still NOT a CLI verb in 0.8.0 (its top-level help lists no such subcommand); 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", [
@@ -298,9 +885,56 @@ const herdrMuxAdapter = {
 			if (tabs.length === 0) throw new Error(`herdr reported no usable tabs in workspace ${workspaceId}: ${out.slice(0, 200)}`);
 			return tabs;
 		}
-	}
+	},
+	agentLifecycle: { waitForState(exec, target, opts) {
+		const until = opts.until ?? [];
+		const status = parseReachedAgentStatus(exec("herdr", [
+			"agent",
+			"wait",
+			target.id,
+			...until.flatMap((state) => ["--until", state]),
+			...opts.timeoutMs != null ? ["--timeout", String(opts.timeoutMs)] : []
+		]));
+		if (!status) throw new Error(withReason(exec, `herdr agent wait reported no reached agent_status for pane ${target.id}`));
+		return status;
+	} }
 };
 /**
+* The set of `agent_status` values herdr reports — unchanged through 0.8.0, whose socket schema still
+* declares `AgentStatus` as exactly this enum, and whose `agent wait --until` still lists exactly these
+* five values. The runtime witness of the `AgentStatus`
+* type, so a string read off a herdr envelope can be NARROWED to it rather than cast. A value outside
+* this set is treated as absent (the feed said something this build does not model), never forced into
+* the type.
+*/
+const AGENT_STATUSES = [
+	"idle",
+	"working",
+	"blocked",
+	"done",
+	"unknown"
+];
+/** A value narrowed to `AgentStatus`, or `undefined` for anything else (a non-string, an empty string,
+* or a status this build does not model) — the normalization both the listing and the wait share. */
+function toAgentStatus(value) {
+	return typeof value === "string" && AGENT_STATUSES.includes(value) ? value : void 0;
+}
+/**
+* The `AgentStatus` a `herdr agent wait` run reached, read defensively from its JSON envelope —
+* `{"result":{"agent":{…,"agent_status":"idle",…},"type":"agent_info"}}` (verified against 0.7.5), so
+* the reached status lives at `.result.agent.agent_status`. Every unresolvable shape — `out` is null
+* (an Exec failure), the JSON does not parse, or the field is missing/empty/unmodeled — folds to
+* `undefined`, exactly as `parsePaneRecord`/`isPaneFocused` fold, so the caller states its own failure.
+*/
+function parseReachedAgentStatus(out) {
+	if (out == null) return void 0;
+	try {
+		return toAgentStatus(JSON.parse(out)?.result?.agent?.agent_status);
+	} catch {
+		return;
+	}
+}
+/**
 * 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
@@ -384,13 +1018,25 @@ function herdrPaneDetails(exec, workspace) {
 *
 * `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
+* `[branch, cwd, focus, label, path, workspace_id]` — no `env` — and herdr rejects the flag with
 * `unknown option: --env`. A caller needing env on that route uses the command-prefix fallback.
+* Re-verified against 0.8.0: both param sets are unchanged in protocol 19's schema, and a live
+* `worktree create --env` there still answers `unknown option: --env`.
 */
 function envFlags(env) {
 	return env ? Object.entries(env).flatMap(([k, v]) => ["--env", `${k}=${v}`]) : [];
 }
 /**
+* `--ratio` takes the seam's number VERBATIM — herdr sizes the ORIGINAL pane, so no inversion, unlike
+* tmux's `-l` and wezterm's `--percent`. The guard is the same one those two render helpers call: the
+* seam refuses an out-of-range ratio here rather than pass `--ratio 5` (or `0`) through to a split herdr
+* would then size wrong.
+*/
+function toHerdrRatio(ratio) {
+	assertRatioInRange(ratio);
+	return String(ratio);
+}
+/**
 * 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
@@ -437,6 +1083,65 @@ function nonEmpty(value) {
 	return typeof value === "string" && value !== "" ? value : void 0;
 }
 /**
+* The `code` of a herdr error envelope, when the runner captured one — how a wait's TIMEOUT (an answer)
+* is told from any other failure (a throw). Read from `Exec.lastError` because that is where herdr's
+* envelope lands: it is written to stderr with exit 1, so stdout is `null` for every failure alike and
+* the code is the only thing that separates them. Defensive throughout — no reason, unparseable JSON, or
+* a missing/non-string code all answer `undefined`, which routes to the throw rather than to a silent
+* "timed out" the backend never said.
+*/
+/**
+* How much of its own timeout a wait must actually spend before a failure is believed to BE that
+* timeout. A fraction rather than the whole, because process start-up and clock granularity make an
+* exact-or-greater comparison flaky on a real runner; wide enough that the case it exists to catch — a
+* herdr with no `wait-output` subcommand, which returns in milliseconds — is nowhere near it.
+*/
+const HERDR_WAIT_ELAPSED_RATIO = .9;
+/**
+* Whether a failed `pane wait-output` was the DEADLINE passing rather than the wait breaking — the
+* two-tier rule `waitForOutput` documents, kept out of the method so the tiers read as one decision.
+*
+* The envelope's code answers when the runner captured one. Otherwise the answer needs two facts, and
+* neither alone is enough: the pane must be LIVE (a gone pane is a failure, `pollForOutput`'s rule) and
+* the call must have SPENT the deadline (a wait that returned instantly never ran — herdr 0.7.4, whose
+* usage text for an unknown subcommand is not an envelope to read a code from).
+*/
+function isHerdrWaitTimeout(exec, target, timeoutMs, elapsedMs) {
+	const code = herdrErrorCode(exec.lastError);
+	if (code != null) return code === "timeout";
+	if (elapsedMs < timeoutMs * HERDR_WAIT_ELAPSED_RATIO) return false;
+	return herdrMuxAdapter.paneExists(exec, target);
+}
+function herdrErrorCode(reason) {
+	if (!reason) return void 0;
+	try {
+		return nonEmpty(JSON.parse(reason)?.error?.code);
+	} catch {
+		return;
+	}
+}
+/**
+* A successful `pane wait-output` envelope: the snapshot it matched in, and the line it matched on.
+*
+* `matched` is `true` by construction — herdr exits 0 only on a match, so reaching here IS the match;
+* the parse only fills in the evidence. Defensive for the same reason `parsePaneRecord` is: a herdr
+* build that reshapes the envelope degrades to a match with no snapshot, never to a failed wait.
+*/
+function parseWaitOutput(out) {
+	let text;
+	let line;
+	try {
+		const result = JSON.parse(out)?.result;
+		text = nonEmpty(result?.read?.text);
+		line = nonEmpty(result?.matched_line);
+	} catch {}
+	return {
+		matched: true,
+		output: text ?? "",
+		...line != null ? { matchedLine: line } : {}
+	};
+}
+/**
 * 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.
 */
@@ -526,8 +1231,8 @@ function parseRootPaneId(out, label) {
 /**
 * 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
+* was created in), and `pane split` (the workspace the split landed in, i.e. the caller's). Re-verified
+* against herdr 0.8.0. 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.
 *
@@ -618,6 +1323,270 @@ function parseWorktreeBindings(out) {
 	}
 	return bindings;
 }
+/**
+* One spelling of `pane read`, taken by `read` for the snapshot AND for its truncation probe — so the
+* two differ only in the source and depth they are meant to differ in. `lines` omitted takes herdr's
+* own default window for the source.
+*/
+function paneRead(exec, target, source, lines) {
+	const args = [
+		"pane",
+		"read",
+		target.id,
+		"--source",
+		source
+	];
+	if (lines != null) args.push("--lines", String(lines));
+	return exec("herdr", args) ?? "";
+}
+//#endregion
+//#region src/mux.otty.ts
+/**
+* otty backend — detected via `$OTTY_PANE_ID`. Drives otty's CLI through `otty pane <verb> …`
+* (https://docs.otty.sh/reference/cli), the same synchronous-CLI shape the other backends use.
+*
+* otty is a native terminal-centric workspace app with integrated multiplexing (Windows > Tabs >
+* Splits > Panes). Its hierarchy maps onto cyber-mux's placement tiers as:
+* - **Workspace** → Window (a new window, spawned via `otty open --new-window`)
+* - **Tab** → Tab (a new tab via `otty tab new`)
+* - **Pane** → Pane (a split via `otty pane split`)
+*
+* The env variable `$OTTY_PANE_ID` carries the caller's pane identity — analogous to `$TMUX_PANE`
+* or `$WEZTERM_PANE`. `$OTTY_SOCKET` is the IPC socket path (detection hint only).
+*
+* Probed from the otty docs only — otty is a GUI-only app not installed in this sandbox, so
+* nothing here carries the "verified against a live binary" claim `mux.tmux.ts`/`mux.herdr.ts`
+* make; it makes the same honest disclaimer the other GUI-based adapters do.
+*
+* Real capability shape from the docs:
+*
+* - **Pane is the terminal unit.** `OTTY_PANE_ID` is the self-identity env var and `LivePane.id`
+*   carries a pane id. `--at tab` maps to `otty tab new`; `--at pane:*` maps to `otty pane split`.
+* - **Window is the workspace tier.** `otty open --new-window` creates a genuinely separate window,
+*   reported as `OpenedPane.workspace`.
+* - **No `--env` on any route.** Like wezterm/zellij/cmux, env is native at no tier, so every open
+*   rides the `envFallback` compensation (an `env K=V` prefix on the launch command, or a stderr
+*   warning when there is no command to ride).
+* - **Split direction is explicit.** `otty pane split --right|--bottom` maps `pane:right`/`pane:down`.
+* - **`send-keys` mixes text and key tokens.** `otty pane send-keys --pane <id> -- "text" key:Enter`
+*   can do both in one call. We implement `sendText` and `sendKeys` separately per the contract.
+* - **No pane geometry adapter.** `otty panes --json` does not report position, so `regions` is not
+*   implementable. `template save` refuses on otty by naming the backend.
+* - **No git-worktree concept in the CLI.** No `worktree` subcommand, so — like tmux, wezterm,
+*   zellij, and cmux — this backend never binds a worktree to a workspace; callers fall back to
+*   plain git plus `open()`.
+*/
+function createOttyAdapter(deps) {
+	const adapter = {
+		name: "otty",
+		canSizeSplits: false,
+		open(exec, opts) {
+			const at = opts.at ?? "tab";
+			if (at === "workspace") {
+				const args = ["open", "--new-window"];
+				if (opts.cwd) args.push(opts.cwd);
+				const out = exec("otty", args);
+				if (!out) throw new Error(withReason(exec, "otty open --new-window failed"));
+				const parsed = parseOttyOutput(out);
+				if (!parsed.window_id) throw new Error("otty open --new-window did not report the window id");
+				const paneId = parsed.pane_id;
+				if (!paneId) throw new Error("otty open --new-window did not report the initial pane id");
+				const opened = openedPane$1(paneId, parsed.tab_id, parsed.window_id);
+				if (opts.label) adapter.rename(exec, opened, "tab", opts.label);
+				runLaunch$2(adapter, exec, opened, opts.env, opts.launch);
+				return opened;
+			}
+			if (at === "tab") {
+				const args = ["tab", "new"];
+				if (opts.cwd) args.push("--cwd", opts.cwd);
+				const out = exec("otty", args);
+				if (!out) throw new Error(withReason(exec, "otty tab new failed"));
+				const parsed = parseOttyOutput(out);
+				const paneId = parsed.pane_id;
+				if (!paneId) throw new Error("otty tab new did not report the pane id");
+				const opened = openedPane$1(paneId, parsed.tab_id, deps.window);
+				if (opts.label) adapter.rename(exec, opened, "tab", opts.label);
+				runLaunch$2(adapter, exec, opened, opts.env, opts.launch);
+				return opened;
+			}
+			if (at === "pane:float") refuseFloatingPane(adapter.name);
+			if (opts.from) adapter.focus(exec, opts.from);
+			const args = [
+				"pane",
+				"split",
+				at === "pane:down" ? "--bottom" : "--right"
+			];
+			if (opts.cwd) args.push("--cwd", opts.cwd);
+			const out = exec("otty", args);
+			if (!out) throw new Error(withReason(exec, "otty pane split failed"));
+			const parsed = parseOttyOutput(out);
+			const paneId = parsed.pane_id;
+			if (!paneId) throw new Error("otty pane split did not report the pane id");
+			const opened = openedPane$1(paneId, parsed.tab_id, deps.window);
+			if (opts.label) adapter.rename(exec, opened, "pane", opts.label);
+			runLaunch$2(adapter, exec, opened, opts.env, opts.launch);
+			return opened;
+		},
+		rename(exec, target, tier, name) {
+			if (tier === "tab") {
+				exec("otty", [
+					"tab",
+					"rename",
+					"--tab",
+					target.id,
+					"--title",
+					name
+				]);
+				return;
+			}
+			exec("otty", [
+				"pane",
+				"rename",
+				"--pane",
+				target.id,
+				"--title",
+				name
+			]);
+		},
+		group() {},
+		sendText(exec, target, text) {
+			exec("otty", [
+				"pane",
+				"send-keys",
+				"--pane",
+				target.id,
+				"--",
+				text
+			]);
+		},
+		sendKeys(exec, target, keys) {
+			const keyTokens = keys.map((k) => `key:${toOttyKey(k)}`);
+			exec("otty", [
+				"pane",
+				"send-keys",
+				"--pane",
+				target.id,
+				"--",
+				...keyTokens
+			]);
+		},
+		submit(exec, target, text) {
+			if (!text) {
+				adapter.sendKeys(exec, target, ["Enter"]);
+				return;
+			}
+			exec("otty", [
+				"pane",
+				"send-keys",
+				"--pane",
+				target.id,
+				"--",
+				text,
+				"key:Enter"
+			]);
+		},
+		read(exec, target, opts) {
+			const args = [
+				"pane",
+				"capture",
+				"--pane",
+				target.id
+			];
+			if (opts?.lines != null) args.push("--lines", String(opts.lines));
+			return { text: exec("otty", args) ?? "" };
+		},
+		waitForOutput(exec, target, opts) {
+			return pollForOutput(adapter, exec, target, opts);
+		},
+		focus(exec, target) {
+			exec("otty", [
+				"pane",
+				"focus",
+				"--pane",
+				target.id
+			]);
+		},
+		teardown(exec, target) {
+			exec("otty", [
+				"pane",
+				"close",
+				"--pane",
+				target.id
+			]);
+		},
+		paneExists(exec, target) {
+			return listOttyPanes(exec).some((p) => p.id === target.id);
+		},
+		isPaneFocused(exec, target) {
+			const found = listOttyPanes(exec).find((p) => p.id === target.id);
+			if (!found) return void 0;
+			return found.is_focused === true;
+		},
+		listPanes(exec) {
+			return listOttyPanes(exec).map((p) => {
+				const pane = {
+					id: p.id,
+					mux: "otty",
+					floating: false
+				};
+				if (p.cwd) pane.cwd = p.cwd;
+				if (p.title) pane.label = p.title;
+				return pane;
+			});
+		}
+	};
+	return adapter;
+}
+function parseOttyOutput(out) {
+	try {
+		return JSON.parse(out);
+	} catch {
+		return {};
+	}
+}
+function listOttyPanes(exec) {
+	const out = exec("otty", ["panes", "--json"]);
+	if (!out) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(out);
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(parsed)) return [];
+	const panes = [];
+	for (const p of parsed) if (p?.pane_id) panes.push({
+		id: p.pane_id,
+		title: p.title,
+		cwd: p.cwd,
+		is_focused: p.is_focused
+	});
+	return panes;
+}
+function openedPane$1(paneId, tabId, window) {
+	const opened = {
+		id: paneId,
+		tab: tabId ?? paneId
+	};
+	if (window) opened.workspace = window;
+	return opened;
+}
+function runLaunch$2(adapter, exec, target, env, launch) {
+	const fallback = envFallback(env, launch);
+	if (fallback.kind === "dropped") {
+		process.stderr.write(`env (${fallback.variables.join(", ")}) could not be set on this otty pane — otty has no --env flag on pane split/tab new/open
+`);
+		return;
+	}
+	if (fallback.command !== void 0) adapter.submit(exec, target, fallback.command);
+}
+/**
+* The core key vocabulary's otty spelling. otty uses PascalCase key names: Enter, Tab, Escape, etc.
+*/
+const OTTY_KEY_RENAMES = { "C-c": "Ctrl+c" };
+function toOttyKey(key) {
+	return OTTY_KEY_RENAMES[key] ?? key;
+}
 //#endregion
 //#region src/mux.tmux.ts
 /**
@@ -651,6 +1620,25 @@ const TMUX_TAB_NAME_OPTION = "@cm_tab";
 const tmuxMuxAdapter = {
 	name: "tmux",
 	canSizeSplits: true,
+	/**
+	* `new-pane` opens a floating pane — tmux 3.7's own new command ("Add floating panes. These are
+	* panes which sit above the layout ('tiled panes') like popups but unlike popups are not modal and
+	* behave like panes", CHANGES 3.6b → 3.7), bound to `*` by default.
+	*
+	* Declared UNCONDITIONALLY rather than probed off `tmux -V`, and that is deliberate: this adapter
+	* takes no version reading anywhere (its `-l`, `-e` and `@`-option paths are all declared the same
+	* way), and a version probe would cost an exec on every resolution to pre-empt a failure tmux
+	* already reports precisely. On tmux ≤ 3.6 the command does not exist and `new-pane` fails with
+	* tmux's own `unknown command` — surfaced by the `withReason` throw in `open`, which names the
+	* command that failed. A silent wrong-pane is the failure mode worth engineering against, and this
+	* has none: there is nothing for an absent `new-pane` to be mistaken for.
+	*
+	* Both sides of this placement are now pinned against a real 3.7c binary — the read side by
+	* `#{pane_floating_flag}`, the create side by the `new-pane` rows in `mux.tmux.integration.test.ts`.
+	* The branch below was originally written off tmux's CHANGES file, because the tmux installed when
+	* it landed was 3.6b and had no `new-pane` to run it against.
+	*/
+	canFloatPanes: true,
 	open(exec, opts) {
 		const at = opts.at ?? "tab";
 		const window = at === "workspace" || at === "tab";
@@ -658,7 +1646,17 @@ const tmuxMuxAdapter = {
 		const group = window && opts.workspaceGroup != null;
 		const format = "#{pane_id}	#{window_id}";
 		let args;
-		if (window) args = [
+		if (at === "pane:float") args = [
+			"new-pane",
+			...opts.from ? ["-t", opts.from.id] : [],
+			...env,
+			"-c",
+			opts.cwd,
+			"-P",
+			"-F",
+			format
+		];
+		else if (window) args = [
 			"new-window",
 			"-d",
 			...env,
@@ -769,14 +1767,19 @@ const tmuxMuxAdapter = {
 		]);
 	},
 	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) ?? "";
+		const text = capturePane(exec, target, opts?.lines);
+		if (!opts?.truncation) return { text };
+		if (opts.lines === "all") return {
+			text,
+			truncated: false
+		};
+		return {
+			text,
+			truncated: isReadTruncated(text, capturePane(exec, target, (opts.lines ?? 0) + 1))
+		};
+	},
+	waitForOutput(exec, target, opts) {
+		return pollForOutput(tmuxMuxAdapter, exec, target, opts);
 	},
 	focus(exec, target) {
 		const { sessionName, windowId } = parsePaneLocation(exec("tmux", [
@@ -847,14 +1850,15 @@ const tmuxMuxAdapter = {
 			"list-panes",
 			"-a",
 			"-F",
-			"#{pane_id}	#{pane_current_command}	#{pane_current_path}	#{pane_title}	#{host}"
+			"#{pane_id}	#{pane_current_command}	#{pane_current_path}	#{pane_title}	#{host}	#{pane_floating_flag}"
 		]);
 		if (!out) return [];
 		return out.split("\n").filter(Boolean).map((line) => {
-			const [id, , cwd, title, host] = line.split("	");
+			const [id, , cwd, title, host, floating] = line.split("	");
 			const pane = {
 				id: id ?? "",
-				mux: "tmux"
+				mux: "tmux",
+				floating: floating === "1"
 			};
 			if (cwd) pane.cwd = cwd;
 			const label = paneLabel(title, host);
@@ -1018,6 +2022,7 @@ function splitOpenReport(out, command) {
 * the same thing without first querying the region's size.
 */
 function toTmuxSize(ratio) {
+	assertRatioInRange(ratio);
 	return `${Math.round((1 - ratio) * 100)}%`;
 }
 /**
@@ -1032,6 +2037,22 @@ function toTmuxSize(ratio) {
 * key list here would make the passthrough a second vocabulary to maintain.
 */
 const TMUX_KEY_RENAMES = { Backspace: "BSpace" };
+/**
+* One spelling of the capture, taken by `read` for the snapshot AND for the one-row-deeper truncation
+* probe — so the two differ in exactly the number they disagree about and nothing else. `lines`
+* omitted is tmux's own default window: the visible screen, with no `-S` at all.
+*/
+function capturePane(exec, target, lines) {
+	const args = [
+		"capture-pane",
+		"-p",
+		"-t",
+		target.id
+	];
+	if (lines === "all") args.push("-S", "-");
+	else if (lines != null) args.push("-S", `-${lines}`);
+	return exec("tmux", args) ?? "";
+}
 function toTmuxKey(key) {
 	return TMUX_KEY_RENAMES[key] ?? key;
 }
@@ -1139,6 +2160,7 @@ function createWeztermAdapter(deps) {
 				runLaunch$1(adapter, exec, opened, opts.env, opts.launch);
 				return opened;
 			}
+			if (at === "pane:float") refuseFloatingPane(adapter.name);
 			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)] : [];
@@ -1202,14 +2224,19 @@ function createWeztermAdapter(deps) {
 			adapter.sendKeys(exec, target, ["Enter"]);
 		},
 		read(exec, target, opts) {
-			const args = [
-				"cli",
-				"get-text",
-				"--pane-id",
-				target.id
-			];
-			if (opts?.lines != null) args.push("--start-line", String(-opts.lines));
-			return exec("wezterm", args) ?? "";
+			const text = getText(exec, target, opts?.lines);
+			if (!opts?.truncation) return { text };
+			if (opts.lines === "all") return {
+				text,
+				truncated: false
+			};
+			return {
+				text,
+				truncated: isReadTruncated(text, getText(exec, target, (opts.lines ?? 0) + 1))
+			};
+		},
+		waitForOutput(exec, target, opts) {
+			return pollForOutput(adapter, exec, target, opts);
 		},
 		focus(exec, target) {
 			exec("wezterm", [
@@ -1235,7 +2262,8 @@ function createWeztermAdapter(deps) {
 			return listWeztermPanes(exec).map((p) => {
 				const pane = {
 					id: String(p.pane_id),
-					mux: "wezterm"
+					mux: "wezterm",
+					floating: false
 				};
 				const cwd = weztermCwd(p.cwd);
 				if (cwd) pane.cwd = cwd;
@@ -1326,6 +2354,7 @@ function weztermCwd(cwd) {
 * probe note, #47) — the same inversion tmux's `-l` needs, unlike herdr's pass-through.
 */
 function toWeztermSize(ratio) {
+	assertRatioInRange(ratio);
 	return String(Math.round((1 - ratio) * 100));
 }
 /**
@@ -1370,6 +2399,26 @@ const WEZTERM_KEY_BYTES = {
 	PageUp: "\x1B[5~",
 	PageDown: "\x1B[6~"
 };
+/**
+* One spelling of the capture, taken by `read` for the snapshot AND for its one-row-deeper truncation
+* probe, so the two differ only in the number they are meant to disagree about.
+*
+* `--start-line` counts backward into scrollback from 0 (the top of the visible screen); the end
+* defaults to the bottom of the screen. Negative-N approximates "last N lines" the way tmux's `-S -N`
+* does, though the two are not guaranteed to line up cell-for-cell. `lines` omitted is WezTerm's own
+* default window — the visible screen, with no `--start-line` at all.
+*/
+function getText(exec, target, lines) {
+	const args = [
+		"cli",
+		"get-text",
+		"--pane-id",
+		target.id
+	];
+	const start = lines === "all" ? FULL_SCROLLBACK_LINES : lines;
+	if (start != null) args.push("--start-line", String(-start));
+	return exec("wezterm", args) ?? "";
+}
 //#endregion
 //#region src/mux.zellij.ts
 /**
@@ -1384,13 +2433,40 @@ const WEZTERM_KEY_BYTES = {
 * binary these commands fail and the adapter surfaces the failure rather than silently mis-targeting
 * the focused pane.
 *
-* Probed from the Zellij docs + CHANGELOG only — Zellij is not installed in this sandbox, so nothing
-* here carries the "verified against a live binary" claim `session.tmux.ts`/`session.herdr.ts` make;
-* it makes the same honest disclaimer `mux.wezterm.ts` does. Two literals in particular are worth a
-* one-line confirmation on a live 0.44.1 binary — the exact form `new-pane` prints an id in (bare `3`
-* vs `terminal_3`) and the shell value of `$ZELLIJ_PANE_ID`. Both are handled either way: ids are
-* carried verbatim and compared through `samePane`, which treats a bare `N` and its `terminal_N` twin
-* as the same pane (per the docs' own `terminal_N | plugin_N | bare N` scheme).
+* Originally probed from the Zellij docs + CHANGELOG alone; now **driven against a live 0.44.3
+* binary** by `mux.zellij.integration.test.ts`, so the command shapes below carry the same
+* verified-against-a-real-binary claim `session.tmux.ts`/`session.herdr.ts` make. What the live probe
+* changed, and what a doc probe could not have known:
+*
+* - The id forms are confirmed and asymmetric: `new-pane` prints the PREFIXED `terminal_N`, while
+*   `list-panes --json` reports `id` as a BARE integer. `samePane` is what makes those the same pane,
+*   so it is load-bearing rather than defensive.
+* - That bare integer is NOT unique: a live session reports `id: 0` for both its suppressed
+*   `zellij:link` PLUGIN pane and its first terminal pane. The number is unique only within a kind,
+*   and `is_plugin` is what says which kind — so `listZellijPanes` qualifies every bare id to
+*   `terminal_N`/`plugin_N` before anything compares or reports it. Both prefixed forms are what
+*   `--pane-id` itself accepts, and a bare `N` addresses the TERMINAL pane (verified: renaming
+*   `--pane-id 3` renames terminal 3 and leaves plugin 3 alone), which is exactly the fold
+*   `normalizePaneId` makes.
+* - Which `list-panes --json` field names are real, and what each one carries. The label guard reads
+*   `terminal_command`, not `pane_command` — a doc probe had that one backwards; see `ZellijPane`.
+*   `pane_cwd` and `pane_command` are real too, and both are present ONLY on a terminal pane: a
+*   plugin pane's record omits the keys entirely, which is how a probe that sampled one concluded
+*   the fields did not exist at all. That is the failure mode of a doc probe, and the reason this
+*   file now has a suite.
+* - `new-pane --direction` requires an attached client focused on a TERMINAL pane, and fails
+*   SILENTLY without one — it prints a plausible new pane id and exits 0 having created nothing.
+*   Re-probed against 0.44.3 with the client parked on zellij's own release-notes PLUGIN pane, which
+*   is where a fresh attach lands: the split printed `terminal_2`, exited 0, and the pane count did
+*   not move. `open()` does not propagate that phantom — see `openedForPane`, which now believes a
+*   reported id only where it names a pane that was NOT already standing.
+* - **A `zellij action` reply can be delivered to the WRONG command**, and **a session no client has
+*   ever attached to reports `list-panes --json` as an empty ARRAY** rather than as an error. Both
+*   are the reason this file retries a listing instead of reading one empty answer as the truth; see
+*   `LIST_PANES_ATTEMPTS` for the repro behind the first and `mux.zellij.integration.test.ts`'s
+*   readiness gate for the second. So the older claim that every verb but `--direction` works against
+*   a client-less session is wrong: the listing is silent there, and everything in this file that
+*   resolves an id reads the listing.
 *
 * Real capability shape that fell out of the probe:
 *
@@ -1439,6 +2515,7 @@ const WEZTERM_KEY_BYTES = {
 function createZellijAdapter(deps) {
 	const adapter = {
 		name: "zellij",
+		canFloatPanes: true,
 		open(exec, opts) {
 			const at = opts.at ?? "tab";
 			if (at === "tab" || at === "workspace") {
@@ -1449,11 +2526,10 @@ function createZellijAdapter(deps) {
 					opts.cwd
 				];
 				if (opts.label) args.push("--name", opts.label);
+				const before = paneIdSet(exec);
 				const out = exec("zellij", args);
-				if (!out) throw new Error(withReason(exec, "zellij action new-tab failed"));
-				const tabId = out.trim();
-				if (!tabId) throw new Error("zellij action new-tab did not report the new tab id");
-				const opened = openedForTab(exec, tabId, deps.session);
+				if (out === null) throw new Error(withReason(exec, "zellij action new-tab failed"));
+				const opened = openedForTab(exec, out.trim(), before, deps.session);
 				runLaunch(adapter, exec, opened, opts.env, opts.launch);
 				return opened;
 			}
@@ -1461,17 +2537,15 @@ function createZellijAdapter(deps) {
 			const args = [
 				"action",
 				"new-pane",
-				"--direction",
-				at === "pane:down" ? "down" : "right",
+				...at === "pane:float" ? ["--floating"] : ["--direction", at === "pane:down" ? "down" : "right"],
 				"--cwd",
 				opts.cwd
 			];
 			if (opts.label) args.push("--name", opts.label);
+			const before = paneIdSet(exec);
 			const out = exec("zellij", args);
-			if (!out) throw new Error(withReason(exec, "zellij action new-pane failed"));
-			const paneId = out.trim();
-			if (!paneId) throw new Error("zellij action new-pane did not report the new pane id");
-			const opened = openedForPane(exec, paneId, deps.session);
+			if (out === null) throw new Error(withReason(exec, "zellij action new-pane failed"));
+			const opened = openedForPane(exec, out.trim(), before, deps.session);
 			runLaunch(adapter, exec, opened, opts.env, opts.launch);
 			return opened;
 		},
@@ -1521,19 +2595,53 @@ function createZellijAdapter(deps) {
 			adapter.sendKeys(exec, target, ["Enter"]);
 		},
 		read(exec, target, opts) {
-			if (opts?.lines != null) return lastLines(exec("zellij", [
-				"action",
-				"dump-screen",
-				"--pane-id",
-				target.id,
-				"--full"
-			]) ?? "", opts.lines);
-			return exec("zellij", [
+			if (opts?.lines === "all") {
+				const text = exec("zellij", [
+					"action",
+					"dump-screen",
+					"--pane-id",
+					target.id,
+					"--full"
+				]) ?? "";
+				return opts.truncation ? {
+					text,
+					truncated: false
+				} : { text };
+			}
+			if (opts?.lines != null) {
+				const full = exec("zellij", [
+					"action",
+					"dump-screen",
+					"--pane-id",
+					target.id,
+					"--full"
+				]) ?? "";
+				const text = lastLines(full, opts.lines);
+				return opts.truncation ? {
+					text,
+					truncated: isReadTruncated(text, full)
+				} : { text };
+			}
+			const text = exec("zellij", [
 				"action",
 				"dump-screen",
 				"--pane-id",
 				target.id
 			]) ?? "";
+			if (!opts?.truncation) return { text };
+			return {
+				text,
+				truncated: isReadTruncated(text, exec("zellij", [
+					"action",
+					"dump-screen",
+					"--pane-id",
+					target.id,
+					"--full"
+				]) ?? "")
+			};
+		},
+		waitForOutput(exec, target, opts) {
+			return pollForOutput(adapter, exec, target, opts);
 		},
 		focus(exec, target) {
 			exec("zellij", [
@@ -1562,10 +2670,11 @@ function createZellijAdapter(deps) {
 			return listZellijPanes(exec).map((p) => {
 				const pane = {
 					id: p.id,
-					mux: "zellij"
+					mux: "zellij",
+					floating: p.is_floating === true
 				};
 				if (p.pane_cwd) pane.cwd = p.pane_cwd;
-				const label = zellijLabel(p.title, p.pane_command);
+				const label = zellijLabel(p.title, p.terminal_command);
 				if (label) pane.label = label;
 				return pane;
 			});
@@ -1575,49 +2684,158 @@ function createZellijAdapter(deps) {
 }
 const zellijMuxAdapter = createZellijAdapter({});
 /**
-* One `zellij action list-panes --json` call, parsed defensively — never throws on bad output. The id
-* is coerced to a string so a bare-integer id (`3`) and a prefixed one (`terminal_3`) are compared as
-* strings by `samePane` rather than one being a number.
+* How many times a listing is re-asked before it is reported as empty, and how many times an open
+* re-looks for the pane it just made.
+*
+* Both exist for ONE verified defect in zellij 0.44.3's CLI, which no amount of adapter care can
+* prevent and every verb here rides on: **a `zellij action` reply can be delivered to the wrong
+* command.** Driven under CPU contention, a command exits 0 having printed NOTHING, and the reply it
+* should have received arrives on the stdout of the command issued after it. Reproduced by
+* alternating `new-tab` and `list-panes --json` 40 times on a loaded 2-core box — twice in 40, the
+* `new-tab` printed an empty string and the `list-panes` that followed it printed `27`. Two hundred
+* back-to-back `list-panes --json` calls with no mutating verb between them lost nothing, so it is
+* the mutating verbs that open the window.
+*
+* The consequences land squarely here. An empty reply to `list-panes --json` is not an empty session
+* — a live zellij session always has at least one pane — so reading it as one made every id
+* resolution in this file fail at once. And an id printed by `new-pane`/`new-tab` may belong to the
+* PREVIOUS command, so it can name a pane that has been standing all along.
+*
+* A retry is the honest remedy because the loss is per-call and independent: the same read reissued
+* answers. These are ceilings on a wedged server, not a wait that decides a pass.
+*
+* What a retry CANNOT reach, stated so a caller knows the edge: a misdelivered reply may also be a
+* valid pane array — an older one, which simply does not carry a pane opened since. Nothing in the
+* shape of that answer marks it stale, so `listPanes` cannot reject it and a single negative read
+* (`paneExists`, `isPaneFocused`) can be wrong. A caller that needs certainty on this backend re-asks;
+* `mux.zellij.integration.test.ts` does exactly that.
+*/
+const LIST_PANES_ATTEMPTS = 3;
+const OPEN_RESOLVE_ATTEMPTS = 10;
+/**
+* One `zellij action list-panes --json` read, parsed defensively — `undefined` for output that is not
+* a pane array, so a caller can tell "zellij did not answer" from "zellij answered, with no panes".
+* Every id is QUALIFIED on the way out (see `zellijPaneId`), so what this returns — and therefore
+* what `LivePane.id` carries and what `samePane` compares — names exactly one live pane.
 */
-function listZellijPanes(exec) {
+function readZellijPanes(exec) {
 	const out = exec("zellij", [
 		"action",
 		"list-panes",
 		"--json"
 	]);
-	if (!out) return [];
+	if (!out) return void 0;
 	let parsed;
 	try {
 		parsed = JSON.parse(out);
 	} catch {
-		return [];
+		return;
 	}
-	if (!Array.isArray(parsed)) return [];
+	if (!Array.isArray(parsed)) return void 0;
 	return parsed.filter((p) => p != null && p.id != null).map((p) => ({
 		...p,
-		id: String(p.id)
+		id: zellijPaneId(p.id, p.is_plugin)
 	}));
 }
 /**
-* The `OpenedPane` for a pane `new-pane` just reported — its tab resolved from the one `list-panes`
-* record carrying that pane id, and the workspace filled from the ambient session name. Throws rather
-* than guessing a tab: `OpenedPane.tab` is required (every multiplexer has the Tab level), and a wrong
-* tab is worse than a loud failure.
+* The id a listing record is reported under — qualified by KIND, because zellij's bare number is not
+* unique. Plugin panes and terminal panes are numbered in separate spaces, so a live session reports
+* `id: 0` for both its suppressed `zellij:link` plugin pane and its first terminal pane; reporting
+* both as `'0'` collapsed two genuinely different panes onto one `LivePane.id`, and every resolution
+* by id — `paneExists`, `isPaneFocused`, and `openedForPane`'s guard against a phantom `new-pane`
+* result — could then land on the wrong one.
+*
+* A bare integer therefore takes the `terminal_`/`plugin_` prefix its `is_plugin` names, which is the
+* form `new-pane` already prints and the form `--pane-id` accepts for BOTH kinds (verified against a
+* live 0.44.3). An id that already carries a prefix is left exactly as it is — this qualifies what
+* zellij left ambiguous, it does not rewrite what zellij spelled out.
+*
+* A record with no `is_plugin` at all is read as a terminal pane: that is the same answer
+* `normalizePaneId` gives a bare id, and the kind zellij's own bare-id addressing resolves to.
 */
-function openedForPane(exec, paneId, session) {
-	const found = listZellijPanes(exec).find((p) => samePane(p.id, paneId));
-	if (!found || found.tab_id == null) throw new Error(`zellij did not report a tab for the new pane ${paneId}`);
-	return openedPane(paneId, String(found.tab_id), session);
+function zellijPaneId(id, isPlugin) {
+	const raw = String(id);
+	if (!/^\d+$/.test(raw)) return raw;
+	return isPlugin === true ? `plugin_${raw}` : `terminal_${raw}`;
 }
 /**
-* The `OpenedPane` for a tab `new-tab` just reported — its initial pane resolved as the single
-* `list-panes` record carrying that tab id. Throws rather than guessing: a new tab must have a pane,
-* and a caller handed a tab with no pane could neither drive nor name it.
+* The session's panes — never throws on bad output, and never reports a LOST reply as an empty
+* session. A read that did not come back as a pane array is simply re-asked (`LIST_PANES_ATTEMPTS`);
+* only a session that refuses every time answers `[]`, which is then a real answer rather than a
+* dropped one. See `LIST_PANES_ATTEMPTS` for the defect this stands in front of.
 */
-function openedForTab(exec, tabId, session) {
-	const pane = listZellijPanes(exec).find((p) => p.tab_id != null && String(p.tab_id) === tabId);
-	if (!pane) throw new Error(`zellij did not report a pane in the new tab ${tabId}`);
-	return openedPane(pane.id, tabId, session);
+function listZellijPanes(exec) {
+	for (let attempt = 1; attempt <= LIST_PANES_ATTEMPTS; attempt++) {
+		const panes = readZellijPanes(exec);
+		if (panes) return panes;
+	}
+	return [];
+}
+/**
+* The panes standing right now, keyed the way `samePane` compares them — an open's BEFORE side. A
+* pane already in this set cannot be the one the open just made, which is the whole check.
+*/
+function paneIdSet(exec) {
+	return new Set(listZellijPanes(exec).map((p) => normalizePaneId(p.id)));
+}
+/**
+* The TERMINAL panes that appeared since `before` — the only candidates an open can have made.
+*
+* Plugin panes are excluded because zellij loads them on its own schedule, not the caller's: a tab
+* opened by `new-tab` can be carrying a plugin pane in the same listing as its own initial pane, and
+* that plugin record can sort FIRST. Resolving an open to it hands the caller a `plugin_N` — an id
+* that exists, so nothing downstream refuses it, and that then answers nothing a pane is asked. Seen
+* at the real boundary: an `open()` at `tab` returned `plugin_15`, and the `rename()` that followed
+* renamed a pane the caller never opened. `new-tab` and `new-pane` both create a TERMINAL pane, so
+* the kind is the discriminator, and `is_plugin` is the field that carries it.
+*/
+function appearedTerminals(exec, before) {
+	return listZellijPanes(exec).filter((p) => p.is_plugin !== true && !before.has(normalizePaneId(p.id)));
+}
+/**
+* The `OpenedPane` for a pane `new-pane` just made — resolved against the listing rather than taken
+* on the word of the id zellij printed, because that word is not reliable (see
+* `LIST_PANES_ATTEMPTS`): the reply may be empty, or may be the PREVIOUS command's, in which case
+* `paneId` names a pane that has been standing all along.
+*
+* So the id is believed only where it names a pane ABSENT from `before` — the phantom guard this file
+* has always meant to be, now closed. Where it cannot be believed, the session itself answers: a
+* single pane that appeared over this open is unambiguous, and adopting it recovers a reply zellij
+* lost instead of failing an open that genuinely happened. That fallback waits one round, so a
+* printed id that is merely SLOW to appear still wins over a guess.
+*
+* Throws rather than guessing a tab: `OpenedPane.tab` is required (every multiplexer has the Tab
+* level), and a wrong tab is worse than a loud failure.
+*/
+function openedForPane(exec, paneId, before, session) {
+	for (let attempt = 1; attempt <= OPEN_RESOLVE_ATTEMPTS; attempt++) {
+		const appeared = appearedTerminals(exec, before);
+		const claimed = paneId ? appeared.find((p) => samePane(p.id, paneId)) : void 0;
+		if (claimed?.tab_id != null) return openedPane(paneId, String(claimed.tab_id), session);
+		const only = appeared.length === 1 ? appeared[0] : void 0;
+		if ((attempt > 1 || !paneId) && only?.tab_id != null) return openedPane(only.id, String(only.tab_id), session);
+	}
+	throw new Error(paneId ? `zellij did not report a tab for the new pane ${paneId}` : "zellij action new-pane did not report the new pane id, and no new pane appeared");
+}
+/**
+* The `OpenedPane` for a tab `new-tab` just made — its initial pane resolved as the `list-panes`
+* record that carries that tab id AND was not already standing. Same reply-delivery defect, same
+* shape of answer as `openedForPane`: a `tabId` that names a tab whose panes all predate the open is
+* a stale reply, not this tab, and a single pane that appeared over the open answers when the id
+* cannot.
+*
+* Throws rather than guessing: a new tab must have a pane, and a caller handed a tab with no pane
+* could neither drive nor name it.
+*/
+function openedForTab(exec, tabId, before, session) {
+	for (let attempt = 1; attempt <= OPEN_RESOLVE_ATTEMPTS; attempt++) {
+		const appeared = appearedTerminals(exec, before);
+		const claimed = tabId ? appeared.find((p) => p.tab_id != null && String(p.tab_id) === tabId) : void 0;
+		if (claimed) return openedPane(claimed.id, tabId, session);
+		const only = appeared.length === 1 ? appeared[0] : void 0;
+		if ((attempt > 1 || !tabId) && only?.tab_id != null) return openedPane(only.id, String(only.tab_id), session);
+	}
+	throw new Error(tabId ? `zellij did not report a pane in the new tab ${tabId}` : "zellij action new-tab did not report the new tab id, and no new pane appeared");
 }
 /**
 * Assemble an `OpenedPane`, attaching `workspace` only when the ambient session name is known — the
@@ -1668,7 +2886,7 @@ function toZellijKey(key) {
 }
 /**
 * A Zellij pane's label — its title, unless that title is the running command Zellij handed an unnamed
-* pane. Zellij defaults an unnamed pane's title to its `pane_command`, so a title equal to it is
+* pane. Zellij defaults an unnamed pane's title to its `terminal_command`, so a title equal to it is
 * ambient rather than chosen; exporting it would put the same manufactured name on every shell pane,
 * exactly the collision tmux's hostname guard exists to prevent. A title that differs from the command
 * is one someone set (`new-pane --name`/`rename-pane`), so it is the author's and survives.
@@ -1701,6 +2919,8 @@ const KNOWN_MUX = [
 	"herdr",
 	"wezterm",
 	"zellij",
+	"cmux",
+	"otty",
 	"screen",
 	"none"
 ];
@@ -1713,25 +2933,29 @@ function isKnownMux(v) {
 * every pane (its own bare-integer id) — per the issue that requested that backend (#47), the same
 * fast-path extension `$TMUX_PANE`/`$HERDR_PANE_ID` already get; Zellij exports `$ZELLIJ_PANE_ID` in
 * every terminal pane (its own `terminal_N`/bare-`N` id) — per the issue that requested this backend
-* (#46). screen carries no per-pane env var. Both the ancestry probe and the `currentPane`
-* self-identity helper read the pane through this table so the two never diverge on which env var a
-* given mux uses.
+* (#46); cmux exports `$CMUX_SURFACE_ID` in every terminal (its surface ref, e.g. `surface:7`) — per
+* the issue that requested this backend (#48). screen carries no per-pane env var. Both the ancestry
+* probe and the `currentPane` self-identity helper read the pane through this table so the two never
+* diverge on which env var a given mux uses.
 */
 const PANE_ENV = {
 	tmux: (env) => env["TMUX_PANE"],
 	herdr: (env) => env["HERDR_PANE_ID"],
 	wezterm: (env) => env["WEZTERM_PANE"],
-	zellij: (env) => env["ZELLIJ_PANE_ID"]
+	zellij: (env) => env["ZELLIJ_PANE_ID"],
+	cmux: (env) => env["CMUX_SURFACE_ID"],
+	otty: (env) => env["OTTY_PANE_ID"]
 };
 /**
 * Resolve THIS session's own pane from env alone (no `ps` walk): the `$CYBER_MUX_PANE` fast-path a
 * spawn propagates → `$TMUX_PANE` (tmux) → `$HERDR_PANE_ID` (herdr) → `$WEZTERM_PANE` (wezterm) →
-* `$ZELLIJ_PANE_ID` (zellij). Returns the pane tagged with its multiplexer, or undefined when the
-* session is in no pane-carrying multiplexer. This is the mux-agnostic self-identity key.
+* `$ZELLIJ_PANE_ID` (zellij) → `$CMUX_SURFACE_ID` (cmux) → `$OTTY_PANE_ID` (otty). Returns the pane
+* tagged with its multiplexer, or undefined when the session is in no pane-carrying multiplexer.
+* This is the mux-agnostic self-identity key.
 */
 function currentPane(env) {
 	if (env["CYBER_MUX_PANE"]) return {
-		mux: env["CYBER_MUX"] === "herdr" ? "herdr" : env["CYBER_MUX"] === "wezterm" ? "wezterm" : env["CYBER_MUX"] === "zellij" ? "zellij" : "tmux",
+		mux: env["CYBER_MUX"] === "herdr" ? "herdr" : env["CYBER_MUX"] === "wezterm" ? "wezterm" : env["CYBER_MUX"] === "zellij" ? "zellij" : env["CYBER_MUX"] === "cmux" ? "cmux" : env["CYBER_MUX"] === "otty" ? "otty" : "tmux",
 		pane: env["CYBER_MUX_PANE"]
 	};
 	const tmux = PANE_ENV.tmux(env);
@@ -1754,6 +2978,16 @@ function currentPane(env) {
 		mux: "zellij",
 		pane: zellij
 	};
+	const cmux = PANE_ENV.cmux(env);
+	if (cmux) return {
+		mux: "cmux",
+		pane: cmux
+	};
+	const otty = PANE_ENV.otty(env);
+	if (otty) return {
+		mux: "otty",
+		pane: otty
+	};
 }
 /**
 * Two-mode multiplexer detection.
@@ -1809,7 +3043,7 @@ const MUX_COMM = [
 ];
 /** The per-pane env var for a mux, via the shared `PANE_ENV` table; undefined for screen/none. */
 function paneFor(mux, env) {
-	return mux === "tmux" || mux === "herdr" || mux === "wezterm" || mux === "zellij" ? PANE_ENV[mux](env) : void 0;
+	return mux === "tmux" || mux === "herdr" || mux === "wezterm" || mux === "zellij" || mux === "cmux" ? PANE_ENV[mux](env) : void 0;
 }
 /**
 * An ancestry-discovered probe, OMITTING `pane` when the mux carries none — never carrying it as an
@@ -1855,6 +3089,8 @@ function discoverByAncestry(exec, env) {
 	if (env["HERDR_ENV"]) return ancestryProbe("herdr", env);
 	if (env["WEZTERM_PANE"]) return ancestryProbe("wezterm", env);
 	if (env["ZELLIJ"]) return ancestryProbe("zellij", env);
+	if (env["CMUX_WORKSPACE_ID"]) return ancestryProbe("cmux", env);
+	if (env["OTTY_PANE_ID"]) return ancestryProbe("otty", env);
 	return {
 		mux: "none",
 		via: "ancestry"
@@ -1891,6 +3127,15 @@ function isStaged(visible, message) {
 * A pane that no longer exists is rejected up front rather than retried: a gone pane and a booting
 * one both read back empty, so without the liveness probe the retry loop reports a dead peer as
 * "never took the turn" — a boot-race shape — and buries the real cause.
+*
+* **Not built on `waitForOutput`, deliberately.** The two look alike and wait on opposite conditions:
+* `waitForOutput` returns when a pattern APPEARS anywhere in the snapshot, while nudge returns when the
+* message DISAPPEARS from the input box at the bottom (`isStaged`) — a negative, position-sensitive
+* condition the wait primitive cannot express, and one that must not be satisfied by the same text
+* sitting up in the transcript, which is exactly where a submitted message ends up. Nor is the loop body
+* the same: nudge does not merely observe between polls, it re-submits, so its "poll" is a corrective
+* action with its own attempt budget rather than a read. What the two DO share is the liveness rule —
+* a gone pane throws instead of being reported as a quiet one — and `pollForOutput` adopts it from here.
 */
 async function nudge(adapter, exec, target, message, opts = {}) {
 	const attempts = opts.attempts ?? DEFAULT_ATTEMPTS;
@@ -1899,14 +3144,14 @@ async function nudge(adapter, exec, target, message, opts = {}) {
 	if (!adapter.paneExists(exec, target)) throw new Error(`nudge failed: pane ${target.id} no longer exists — the peer's session is gone, not busy.`);
 	adapter.submit(exec, target, message);
 	await sleep(settleMs);
-	if (!isStaged(adapter.read(exec, target), message)) return {
+	if (!isStaged(adapter.read(exec, target).text, message)) return {
 		taken: true,
 		resubmits: 0
 	};
 	for (let attempt = 1; attempt <= attempts; attempt++) {
 		adapter.submit(exec, target);
 		await sleep(settleMs);
-		if (!isStaged(adapter.read(exec, target), message)) return {
+		if (!isStaged(adapter.read(exec, target).text, message)) return {
 			taken: true,
 			resubmits: attempt
 		};
@@ -1918,14 +3163,15 @@ async function nudge(adapter, exec, target, message, opts = {}) {
 /**
 * Resolve the raw backend for the multiplexer this process is inside, via the two-mode mux probe
 * (`$CYBER_MUX` fast-path/override, else ancestry discovery from `$$` falling back to the
-* `$TMUX`/`$HERDR_ENV`/`$WEZTERM_PANE`/`$ZELLIJ` hint when the walk is inconclusive) —
-* tmux/herdr/wezterm/zellij map to their adapters; anything else throws, because a caller asking to
-* drive panes with no multiplexer has an unmet precondition, and a loud, actionable failure beats a
-* silent no-op.
+* `$TMUX`/`$HERDR_ENV`/`$WEZTERM_PANE`/`$ZELLIJ`/`$CMUX_WORKSPACE_ID` hint when the walk is
+* inconclusive) — tmux/herdr/wezterm/zellij/cmux map to their adapters; anything else throws,
+* because a caller asking to drive panes with no multiplexer has an unmet precondition, and a loud,
+* actionable failure beats a silent no-op.
 *
 * The zellij adapter is bound to the ambient session name (`$ZELLIJ_SESSION_NAME`) at resolution — it
 * reports that as `OpenedPane.workspace`, so the session name has to come from the SAME `env` the
-* probe reads. A missing name simply omits `workspace`; see `createZellijAdapter`.
+* probe reads. A missing name simply omits `workspace`; see `createZellijAdapter`. The cmux adapter
+* is similarly bound to the ambient workspace id (`$CMUX_WORKSPACE_ID`).
 *
 * `screen` is a KNOWN mux — the probe detects it (ancestry) and honors it as an override (fast-path)
 * — but it is NOT a drivable backend, so it throws its OWN message naming the reason rather than the
@@ -1951,8 +3197,10 @@ function resolveMuxAdapter(env, exec = nodeExec) {
 	if (probe.mux === "herdr") return herdrMuxAdapter;
 	if (probe.mux === "wezterm") return weztermMuxAdapter;
 	if (probe.mux === "zellij") return createZellijAdapter({ session: env["ZELLIJ_SESSION_NAME"] });
-	if (probe.mux === "screen") throw new Error("cyber-mux detected GNU Screen, which it cannot drive: Screen addresses its split regions positionally (no per-pane id) and leaves $WINDOW unset in panes opened via `screen -X`, so a pane has no stable identity to send to, read from, or self-identify by. Run inside tmux ($TMUX), herdr ($HERDR_ENV=1), wezterm ($WEZTERM_PANE set), or zellij ($ZELLIJ set) instead.");
-	throw new Error("cyber-mux requires a session backend — run inside tmux ($TMUX), herdr ($HERDR_ENV=1), wezterm ($WEZTERM_PANE set), or zellij ($ZELLIJ set)");
+	if (probe.mux === "cmux") return createCmuxAdapter({ workspace: env["CMUX_WORKSPACE_ID"] });
+	if (probe.mux === "otty") return createOttyAdapter({ window: void 0 });
+	if (probe.mux === "screen") throw new Error("cyber-mux detected GNU Screen, which it cannot drive: Screen addresses its split regions positionally (no per-pane id) and leaves $WINDOW unset in panes opened via `screen -X`, so a pane has no stable identity to send to, read from, or self-identify by. Run inside tmux ($TMUX), herdr ($HERDR_ENV=1), wezterm ($WEZTERM_PANE set), zellij ($ZELLIJ set), or cmux ($CMUX_WORKSPACE_ID set) instead.");
+	throw new Error("cyber-mux requires a session backend — run inside tmux ($TMUX), herdr ($HERDR_ENV=1), wezterm ($WEZTERM_PANE set), zellij ($ZELLIJ set), cmux ($CMUX_WORKSPACE_ID set), or otty ($OTTY_PANE_ID set)");
 }
 /**
 * Resolve the multiplexer this process is inside and return it as a `MuxSession` with `exec` BOUND —
@@ -1978,6 +3226,7 @@ function resolveMux(env, deps) {
 		sendKeys: (target, keys, d) => raw.sendKeys(pick(d), target, keys),
 		submit: (target, text, d) => raw.submit(pick(d), target, text),
 		read: (target, opts, d) => raw.read(pick(d), target, opts),
+		waitForOutput: (target, opts, d) => raw.waitForOutput(pick(d), target, opts),
 		focus: (target, d) => raw.focus(pick(d), target),
 		teardown: (target, d) => raw.teardown(pick(d), target),
 		paneExists: (target, d) => raw.paneExists(pick(d), target),
@@ -1985,9 +3234,13 @@ function resolveMux(env, deps) {
 		listPanes: (d) => raw.listPanes(pick(d)),
 		nudge: (target, message, opts, d) => nudge(raw, pick(d), target, message, opts),
 		...raw.worktree ? { worktree: bindWorktree(raw.worktree, pick) } : {},
-		...raw.regions ? { regions: bindRegions(raw.regions, pick) } : {}
+		...raw.regions ? { regions: bindRegions(raw.regions, pick) } : {},
+		...raw.agentLifecycle ? { agentLifecycle: bindAgentLifecycle(raw.agentLifecycle, pick) } : {}
 	};
 }
+function bindAgentLifecycle(agent, pick) {
+	return { waitForState: (target, opts, d) => agent.waitForState(pick(d), target, opts) };
+}
 function bindWorktree(wt, pick) {
 	return {
 		createInWorkspace: (opts, d) => wt.createInWorkspace(pick(d), opts),
@@ -2020,6 +3273,6 @@ function callerPane(adapter, env) {
 	return self && self.mux === adapter.name ? { id: self.pane } : void 0;
 }
 //#endregion
-export { envFallback as _, nudge as a, createZellijAdapter as c, weztermMuxAdapter as d, nodeNewId as f, herdrMuxAdapter as g, tmuxMuxAdapter as h, isStaged as i, zellijMuxAdapter as l, TMUX_WORKSPACE_GROUP_OPTION as m, resolveMux as n, currentPane as o, TMUX_TAB_NAME_OPTION as p, resolveMuxAdapter as r, probeMultiplexer as s, callerPane as t, createWeztermAdapter as u };
+export { pollForOutput as C, envFallback as D, refuseFloatingPane as E, matchWaitPattern as S, canFloatPanes as T, FULL_SCROLLBACK_LINES as _, nudge as a, DEFAULT_WAIT_POLL_MS as b, createZellijAdapter as c, weztermMuxAdapter as d, nodeNewId as f, herdrMuxAdapter as g, tmuxMuxAdapter as h, isStaged as i, zellijMuxAdapter as l, TMUX_WORKSPACE_GROUP_OPTION as m, resolveMux as n, currentPane as o, TMUX_TAB_NAME_OPTION as p, resolveMuxAdapter as r, probeMultiplexer as s, callerPane as t, createWeztermAdapter as u, capturedRows as v, FloatingPanesUnsupportedError as w, assertWaitPattern as x, isReadTruncated as y };
 
-//# sourceMappingURL=backend-DnrbmL6N.mjs.map
+//# sourceMappingURL=backend-DjX6RlAG.mjs.map