cyber-mux 0.3.0 → 0.4.0

package/dist/cli.mjs

@@ -1,5 +1,6 @@
-import { a as listWorktreesFromGit, c as pruneWorktrees, d as resolveWorktreePath, i as isWorktreeRemovable, l as removeWorktreeSafely, p as nodeExec, r as gitWorktreeAdapter, s as normalizeWorktreePath, t as WorktreeGitError, u as resolvePrimaryRoot } from "./worktree-CoQdRgv1.mjs";
-import { _ as envFallback, f as nodeNewId, o as currentPane, r as resolveMuxAdapter, s as probeMultiplexer, t as callerPane } from "./backend-DnrbmL6N.mjs";
+import { a as listWorktreesFromGit, c as provisionWorktree, d as resolvePrimaryRoot, f as resolveWorktreePath, i as isWorktreeRemovable, l as pruneWorktrees, m as nodeExec, r as gitWorktreeAdapter, s as normalizeWorktreePath, t as WorktreeGitError, u as removeWorktreeSafely } from "./worktree-hHuFZkpW.mjs";
+import { f as nodeNewId, o as currentPane, r as resolveMuxAdapter, s as probeMultiplexer, t as callerPane, x as envFallback } from "./backend-Cif257ji.mjs";
+import { AgentLifecycleUnsupportedError, deriveAgentWait } from "./agent.mjs";
 import { collectPanes, firstPane, isValidTemplateName, listTemplates, nodeTemplateStore, parseTemplate, resolveTemplate as resolveTemplate$1, resolveTree, templateDirs, validateTemplate } from "./template.mjs";
 import { join, relative, sep } from "node:path";
 import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
@@ -136,6 +137,29 @@ var AmbiguousPaneError = class extends CliError {
 		this.name = "AmbiguousPaneError";
 	}
 };
+/** The stable code a missing-pane usage error carries — the same code FAMILY as the ambiguity: both
+* are exit-2 usage errors whose fix is a different pane argument, and both hand the caller the live
+* panes to retry with rather than sending them on a second round trip. */
+const MISSING_PANE_CODE = "missing-pane";
+/**
+* A pane verb invoked with no `<pane>` at all — a usage error (exit 2), the same shape the ambiguity
+* uses. The old "having called no backend" guarantee is deliberately gone (CR 95): the backend IS
+* queried so the live panes can be listed as candidates, since the caller's deterministic next move
+* after "missing pane" is `cyber-mux list`. Folding that answer into the error collapses a two-turn
+* correction into one, exactly as the ambiguity report already does.
+*
+* Carries its `candidates` in `extra` under the same key `AmbiguousPaneError` uses, so the one
+* renderer prints them `<id>  <label>  <cwd>` with no special case. When the backend could NOT be
+* enumerated the list is empty and the help points at `cyber-mux list` instead of the ids.
+*/
+var MissingPaneError = class extends CliError {
+	candidates;
+	constructor(candidates) {
+		super(MISSING_PANE_CODE, "no pane given — this command needs a target pane", candidates.length > 0 ? `pass one of the ids below: ${candidates.map((c) => c.id).join(" ")}` : "list the live panes with: cyber-mux list", 2, { candidates });
+		this.candidates = candidates;
+		this.name = "MissingPaneError";
+	}
+};
 /**
 * The ONE renderer — every coded failure reaches stdout through here, and exits.
 *
@@ -452,6 +476,54 @@ function convert(node, ctx) {
 	if (node.ratio !== void 0) split.ratio = node.ratio;
 	return split;
 }
+/**
+* A capture asked of a backend that lacks the optional geometry seam it needs — no `describeRegion`
+* for a region capture, no `describeWorkspace` for a `--workspace` one. An absent optional seam member
+* is a refusal, never a guess: a backend that cannot answer cannot be captured and there is nothing to
+* degrade to.
+*
+* PORTABLE and exit-code-free by design. The DECISION to refuse is the library's and lives here, at
+* the one place that sees the adapter — the pure `captureTemplate` above takes rectangles already read
+* and could never make it. 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. `capability`
+* names which seam was missing so the caller composes the right message without re-deriving it, and
+* the terse `message` is a factual log line, not the user-facing copy.
+*/
+var CaptureUnsupportedError = class extends Error {
+	backend;
+	capability;
+	constructor(backend, capability) {
+		super(capability === "region" ? `${backend} cannot report a region's geometry` : `${backend} cannot enumerate a workspace's tabs`);
+		this.backend = backend;
+		this.capability = capability;
+		this.name = "CaptureUnsupportedError";
+	}
+};
+/**
+* Read the live region around `target` through the adapter and derive its template — the
+* surface-independent orchestrator `template save` drives, and the single home of the region-capture
+* refusal. The optional `regions` seam is where a backend says whether it can report geometry at all;
+* a backend without `describeRegion` is refused HERE (`CaptureUnsupportedError`), before any read,
+* because the pure `captureTemplate` it would feed cannot see the adapter and so cannot make that
+* call. A backend that CAN report reads its region and hands the rectangles to the pure capture
+* unchanged.
+*/
+function deriveRegionCapture(adapter, exec, target, opts) {
+	const describeRegion = adapter.regions?.describeRegion;
+	if (!describeRegion) throw new CaptureUnsupportedError(adapter.name, "region");
+	return captureTemplate(describeRegion(exec, target), opts);
+}
+/**
+* Read every tab of the workspace `target` sits in through the adapter and derive a `tabs` template —
+* the `--workspace` orchestrator, and the single home of the workspace-capture refusal. Same shape as
+* `deriveRegionCapture`, one member over: a backend without `describeWorkspace` cannot enumerate a
+* workspace's tabs and is refused HERE (`CaptureUnsupportedError`), before any read.
+*/
+function deriveWorkspaceCapture(adapter, exec, target, opts) {
+	const describeWorkspace = adapter.regions?.describeWorkspace;
+	if (!describeWorkspace) throw new CaptureUnsupportedError(adapter.name, "workspace");
+	return captureWorkspaceTemplate(describeWorkspace(exec, target), opts);
+}
 //#endregion
 //#region src/template-edit.ts
 /**
@@ -1224,6 +1296,16 @@ function noMux() {
 function paneNotFound(locator) {
 	return new CliError("pane-not-found", `pane "${locator}" matched no live pane`, "list the live panes with: cyber-mux list", 1);
 }
+/**
+* `send text`/`send keys` given a pane but no payload — a usage error (exit 2), the fix is to add the
+* payload. The payload argument is optional at the parser (`[text]`/`[keys...]`) only so a bare
+* `send text` resolves its MISSING pane through `resolveTarget` and lists candidates rather than
+* tripping commander's own payload-missing error first; once a pane is resolved, an absent payload is
+* caught here so the operation never runs on nothing.
+*/
+function missingSendPayload(verb) {
+	return verb === "text" ? new CliError("missing-argument", "send text needs the text to type", "pass the text: cyber-mux send text <pane> <text>", 2) : new CliError("missing-argument", "send keys needs at least one key to press", "pass one or more keys: cyber-mux send keys <pane> <keys...>", 2);
+}
 /** 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) {
@@ -1270,6 +1352,17 @@ function reportWorktreeFailure(err) {
 * "no such pane" message this function's to write.
 */
 function resolveTarget(deps, a, locator) {
+	if (!locator) {
+		let listed = [];
+		try {
+			listed = a.listPanes(deps.exec);
+		} catch {}
+		throw new MissingPaneError(listed.map((p) => ({
+			id: p.id,
+			label: p.label ?? null,
+			cwd: p.cwd ?? null
+		})));
+	}
 	let panes;
 	try {
 		panes = a.listPanes(deps.exec);
@@ -1338,7 +1431,7 @@ function paneVerb(locator, body) {
 		body();
 	} catch (err) {
 		if (err instanceof CliError) throw err;
-		throw paneNotFound(locator);
+		throw paneNotFound(locator ?? "");
 	}
 }
 /**
@@ -1557,17 +1650,14 @@ function templateSaveCommand(deps) {
 			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.regions?.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.regions?.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);
+			if (!(opts.workspace ? a.regions?.describeWorkspace : a.regions?.describeRegion)) throw new CaptureUnsupportedError(a.name, opts.workspace ? "workspace" : "region");
 			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);
+			const { template, warnings } = opts.workspace ? deriveWorkspaceCapture(a, deps.exec, target, captureOpts) : deriveRegionCapture(a, 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);
@@ -1581,6 +1671,7 @@ function templateSaveCommand(deps) {
 			});
 		} catch (err) {
 			if (err instanceof CliError) throw err;
+			if (err instanceof CaptureUnsupportedError) throw backendUnsupported(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);
 		}
 	}));
@@ -1599,6 +1690,15 @@ function templateSaveCommand(deps) {
 * 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.
 */
+/**
+* The CLI surface of the library's geometry-capability refusal: exit 1 (a genuine operation failure,
+* not a usage error), naming the backend, with the flag-specific fix hint. The DECISION to refuse is
+* the orchestrator's (`CaptureUnsupportedError`); this composes only the presentation from the two
+* structured fields the error carries, so the sentence lives in one place per surface.
+*/
+function backendUnsupported(err) {
+	return err.capability === "region" ? new CliError("backend-unsupported", `${err.backend} 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) : new CliError("backend-unsupported", `${err.backend} 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);
+}
 function noteTabsLeftOut(deps, adapter, target, name) {
 	const describeWorkspace = adapter.regions?.describeWorkspace;
 	if (!describeWorkspace) return null;
@@ -1928,22 +2028,26 @@ function openCommand(deps) {
 * 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) => {
+	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);
+			const target = resolveTarget(deps, a, pane);
+			if (text === void 0) throw missingSendPayload("text");
+			a.sendText(deps.exec, target, 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) => {
+	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);
+			const target = resolveTarget(deps, a, pane);
+			if (keys.length === 0) throw missingSendPayload("keys");
+			a.sendKeys(deps.exec, target, 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) => {
+	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);
@@ -1951,7 +2055,7 @@ function submitCommand(deps) {
 	}));
 }
 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) => {
+	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);
@@ -1960,8 +2064,78 @@ function readCommand(deps) {
 		});
 	}));
 }
+/** The default deadline a bare `wait` takes. Named, not spelled inline, so the help text and the value
+* cannot drift. Chosen to be long enough for a harness to boot and print, short enough that an agent
+* that guessed the wrong pattern gets its answer back inside one turn. */
+const DEFAULT_WAIT_TIMEOUT_MS = 3e4;
+/**
+* The `wait` verb: block until a pane PRINTS something, or the deadline passes.
+*
+* Agent-first in the two ways that matter here. First, the verdict is in the EXIT CODE — 0 matched, 1
+* timed out — so a shell caller branches without parsing anything, exactly as `exists` separates live
+* from gone. Second, a timeout is a normal answer and prints the same `{matched, output}` payload a
+* match does, so an agent that guessed wrong sees what the pane actually said instead of an error with
+* the evidence thrown away.
+*
+* It is its own verb rather than `read --wait <pattern>` because the two answer different questions —
+* `read` reports a snapshot and always succeeds; this one asserts a condition and can fail — and folding
+* them would make `read`'s exit code depend on a flag.
+*
+* The PATTERN is validated before the pane is resolved, which is the one place this verb orders its two
+* usage errors: a missing pattern is answered without a `listPanes` round trip, and candidate panes are
+* no use to a caller that has not said what it is waiting for. A missing PANE then takes the same
+* `MissingPaneError` (candidates listed) every other pane verb takes, from the one chokepoint that owns
+* it — which is why `[pane]` is optional at the parser and required in fact.
+*/
+function waitCommand(deps) {
+	return new Command("wait").description("Block until a pane's output matches, or the timeout elapses (exit 0 = matched, 1 = timed out)").argument("[pane]", "Target pane id").option("--match <text>", "Literal substring to wait for").option("--regex <pattern>", "Regular expression to wait for (backend dialect; prefer --match)").option("--timeout <ms>", `Give up after this many ms (default ${DEFAULT_WAIT_TIMEOUT_MS})`, (v) => Number.parseInt(v, 10), DEFAULT_WAIT_TIMEOUT_MS).option("--lines <n>", "Restrict the searched snapshot to this many trailing lines", (v) => Number.parseInt(v, 10)).addOption(FORMAT_OPTION).action(guardedAsync(async (pane, opts) => {
+		const pattern = waitPattern(opts);
+		if (!Number.isFinite(opts.timeout) || opts.timeout < 0) throw invalidWaitTimeout(opts.timeout);
+		const a = adapter(deps);
+		const t = resolveTarget(deps, a, pane);
+		const result = await a.waitForOutput(deps.exec, t, {
+			...pattern,
+			timeoutMs: opts.timeout,
+			...opts.lines != null ? { lines: opts.lines } : {}
+		}).catch((err) => {
+			if (err instanceof CliError) throw err;
+			throw paneNotFound(pane ?? "");
+		});
+		output({
+			pane: t.id,
+			...result
+		}, () => {
+			printFields({
+				pane: t.id,
+				matched: String(result.matched),
+				line: result.matchedLine ?? null
+			});
+		});
+		if (!result.matched) process.exit(1);
+	}));
+}
+/** Exactly one of `--match`/`--regex`, as the seam requires — refused HERE so the caller gets this CLI's
+* coded usage error (exit 2, the fix is a different invocation) rather than the seam's bare throw. */
+function waitPattern(opts) {
+	if (opts.match != null && opts.regex != null) throw new CliError("usage-error", "--match and --regex are mutually exclusive", "pass one pattern: cyber-mux wait <pane> --match <text>", 2);
+	if (opts.match != null) return { match: opts.match };
+	if (opts.regex != null) {
+		try {
+			new RegExp(opts.regex);
+		} catch {
+			throw new CliError("usage-error", `--regex is not a valid expression: ${opts.regex}`, "pass a valid pattern, or a literal with --match instead", 2);
+		}
+		return { regex: opts.regex };
+	}
+	throw new CliError("usage-error", "wait needs a pattern — pass --match or --regex", "wait for a literal: cyber-mux wait <pane> --match <text>", 2);
+}
+/** A `--timeout` that is not a non-negative number — a usage error: nothing was attempted, and the fix
+* is a different invocation. */
+function invalidWaitTimeout(timeout) {
+	return new CliError("usage-error", `--timeout must be a non-negative number of milliseconds — got ${timeout}`, "pass milliseconds: cyber-mux wait <pane> --match <text> --timeout 30000", 2);
+}
 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) => {
+	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));
@@ -1969,7 +2143,7 @@ function focusCommand(deps) {
 	}));
 }
 function closeCommand(deps) {
-	return new Command("close").description("Close a pane").argument("<pane>", "Target pane id").addOption(FORMAT_OPTION).action(guarded((pane) => {
+	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));
@@ -1979,7 +2153,8 @@ function closeCommand(deps) {
 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, [
+		const hasAgent = panes.some((p) => p.agentStatus !== void 0);
+		const cols = [
 			{
 				label: "pane",
 				get: (p) => p.id
@@ -1996,11 +2171,16 @@ function listCommand(deps) {
 				label: "cwd",
 				get: (p) => p.cwd ?? ""
 			}
-		]));
+		];
+		if (hasAgent) cols.push({
+			label: "agent",
+			get: (p) => p.agentStatus ?? ""
+		});
+		output({ panes }, () => printTable(panes, cols));
 	}));
 }
 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) => {
+	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);
@@ -2011,6 +2191,87 @@ function existsCommand(deps) {
 		if (!live) process.exit(1);
 	}));
 }
+/**
+* The CLI surface of the library's agent-wait refusal: exit 1 (a genuine operation failure, not a
+* usage error), naming the backend, with a fix hint pointing at the herdr-only constraint. The
+* DECISION to refuse is the orchestrator's (`AgentLifecycleUnsupportedError`); this composes only the
+* presentation, so the sentence lives in one place — the exact mirror of how `backendUnsupported`
+* surfaces `CaptureUnsupportedError` for `template save`.
+*/
+function agentUnsupported(err) {
+	return new CliError("backend-unsupported", `${err.backend} cannot wait on agent-lifecycle state — agent wait needs a backend with a native per-pane agent-state feed (herdr)`, "run agent wait on herdr, the only backend with a native agent-state feed", 1);
+}
+/**
+* `agent status <pane>` — a SNAPSHOT that degrades, never refuses. It resolves a pane through the
+* shared ladder and prints its `agentStatus`, a fact independent of whether the backend can WAIT on it
+* (that is `agent wait`'s herdr-only capability). A backend with no agent-state feed still answers
+* truthfully — the pane, with no status — and exits 0: refusing here would turn a caller away from a
+* fact the backend CAN answer (which pane this is) because of one it can't (what its agent is doing),
+* and the two are independent.
+*/
+function agentStatusCommand(deps) {
+	return new Command("status").description("Print a pane's agent-lifecycle status (herdr); degrades to no status on a backend with no feed").argument("[pane]", "Target pane id or label").addOption(FORMAT_OPTION).action(guarded((pane) => {
+		const a = adapter(deps);
+		const target = resolveTarget(deps, a, pane);
+		let agentStatus;
+		try {
+			agentStatus = a.listPanes(deps.exec).find((p) => p.id === target.id)?.agentStatus;
+		} catch {
+			agentStatus = void 0;
+		}
+		output({
+			pane: target.id,
+			agentStatus: agentStatus ?? null
+		}, () => printFields({
+			pane: target.id,
+			agentStatus
+		}));
+	}));
+}
+/**
+* `agent wait <pane>` — a blocking DRIVE of herdr's native `agent wait`, or a refusal naming the
+* backend on one without the capability. Unlike `agent status`, waiting has no truthful degrade, so a
+* backend with no agent-lifecycle primitive is refused (`backend-unsupported`, exit 1) rather than
+* answered with a guess — the exact mirror of how `template save` refuses a geometry-incapable backend.
+*
+* The refusal is checked BEFORE the pane is resolved so a name that resolves nowhere never masks the
+* herdr-only refusal; the orchestrator (`deriveAgentWait`) re-checks the same seam member, that check
+* being its own library contract. `--until` is repeatable (omit to take herdr's default set) and
+* `--timeout` is optional (omit for an indefinite wait).
+*/
+function agentWaitCommand(deps) {
+	return new Command("wait").description("Block until a pane's agent reaches a state (herdr); refused on a backend with no agent-state feed").argument("[pane]", "Target pane id or label").option("--until <status...>", "Agent states any of which ends the wait (idle, working, blocked, done, unknown); omit for herdr’s default").option("--timeout <ms>", "Milliseconds before the wait gives up; omit to wait indefinitely", (v) => Number.parseInt(v, 10)).addOption(FORMAT_OPTION).addHelpText("after", "\nagent wait drives a native per-pane agent-state feed, which only herdr has — tmux, wezterm and\nzellij are refused with backend-unsupported. Use agent status for a snapshot that works everywhere.").action(guarded((pane, opts) => {
+		const a = adapter(deps);
+		if (!a.agentLifecycle) throw agentUnsupported(new AgentLifecycleUnsupportedError(a.name));
+		const target = resolveTarget(deps, a, pane);
+		let reached;
+		try {
+			reached = deriveAgentWait(a, deps.exec, target, {
+				until: opts.until,
+				timeoutMs: opts.timeout
+			});
+		} catch (err) {
+			if (err instanceof CliError) throw err;
+			if (err instanceof AgentLifecycleUnsupportedError) throw agentUnsupported(err);
+			throw new CliError("agent-wait-failed", err instanceof Error ? err.message : String(err), "check the pane still exists with: cyber-mux exists <pane>", 1);
+		}
+		output({
+			pane: target.id,
+			agentStatus: reached
+		}, () => console.log(reached));
+	}));
+}
+/**
+* The `agent` group reaches the herdr agent-lifecycle capability: `status` (a snapshot that degrades
+* truthfully) and `wait` (a blocking drive of herdr's native wait, refused on every backend without
+* it). The state feed itself is herdr's; this group is how the CLI reads and blocks on it.
+*/
+function agentCommand(deps) {
+	const cmd = new Command("agent").description("Inspect and wait on a pane's agent-lifecycle state (herdr)");
+	cmd.addCommand(agentStatusCommand(deps));
+	cmd.addCommand(agentWaitCommand(deps));
+	return cmd;
+}
 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 {
@@ -2085,6 +2346,47 @@ function worktreeAddCommand(deps) {
 		}
 	});
 }
+/**
+* `worktree provision` — reuse a free worktree or create a fresh one, the CLI wiring of the
+* `provisionWorktree` seam. The verb uses the DEFAULT availability gate (`isWorktreeRemovable`, the
+* exact set `worktree list` marks `(removable)` and `prune` removes) and offers NO flag to inject a
+* host predicate — that is the surface divergence from the library seam, which takes one. A host that
+* must exclude a live-session worktree calls `WorktreeApi.provision` directly. It reports what it did
+* (`reused` | `created`), the worktree, and on reuse the recycled entry — its prior branch and the
+* workspace it was open in; `printFields` drops the nullish reuse fields on a create.
+*/
+function worktreeProvisionCommand(deps) {
+	return new Command("provision").description("Reuse a free worktree or create a fresh one — the default-gate wiring of the provision seam (a worktree `list` marks \"(removable)\"). Reports whether it reused or created").requiredOption("--branch <branch>", "Branch the provisioned worktree ends up on").option("--base <ref>", "Start point for the fresh branch (default: the resolved default branch, then HEAD)").option("--path <path>", "Where a fresh checkout goes when none is free to reuse (default: a sibling of the primary checkout)").addOption(FORMAT_OPTION).action((opts) => {
+		try {
+			const primaryRoot = resolvePrimaryRoot(deps.exec);
+			const path = opts.path ?? resolveWorktreePath(primaryRoot, opts.branch);
+			const result = provisionWorktree(deps.exec, primaryRoot, { create: {
+				path,
+				branch: opts.branch,
+				base: opts.base
+			} });
+			const reused = result.reused ? {
+				root: result.reused.root,
+				branch: result.reused.branch ?? null,
+				workspace: result.reused.workspace ?? null
+			} : null;
+			output({
+				action: result.action,
+				root: result.worktree.root,
+				branch: result.worktree.branch,
+				reused
+			}, () => printFields({
+				action: result.action,
+				root: result.worktree.root,
+				branch: result.worktree.branch,
+				"reused-from": reused ? reused.branch ?? "(detached)" : void 0,
+				"reused-workspace": reused?.workspace ?? void 0
+			}));
+		} 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 {
@@ -2198,6 +2500,7 @@ function worktreePruneCommand(deps) {
 function worktreeCommand(deps) {
 	const cmd = new Command("worktree").description("Git worktree helpers for spawning/tearing down a session");
 	cmd.addCommand(worktreeAddCommand(deps));
+	cmd.addCommand(worktreeProvisionCommand(deps));
 	cmd.addCommand(worktreeOpenCommand(deps));
 	cmd.addCommand(worktreeListCommand(deps));
 	cmd.addCommand(worktreeRemoveCommand(deps));
@@ -2273,12 +2576,14 @@ function buildProgram(cliDeps = DEFAULT_DEPS) {
 	program.addCommand(sendCommand(deps));
 	program.addCommand(submitCommand(deps));
 	program.addCommand(readCommand(deps));
+	program.addCommand(waitCommand(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));
+	program.addCommand(agentCommand(deps));
 	return exitOverrideTree(program);
 }
 /** The real CLI entry point — called explicitly by `bin/cyber-mux.mjs`, never as an import-time