cyber-mux 0.3.0 → 0.4.0

package/dist/agent.d.mts

@@ -0,0 +1,66 @@
+import { t as Exec } from "./exec-B81m4yjz.mjs";
+import { d as MuxTarget, n as AgentStatus, o as MuxAdapter, r as AgentWaitOptions, t as AgentLifecycle } from "./mux-CoYDrk3v.mjs";
+//#region src/agent.d.ts
+/**
+ * An agent-lifecycle wait asked of a backend that has no native agent-state primitive (`agent wait`
+ * on tmux, wezterm or zellij). An absent `agentLifecycle` seam member is a REFUSAL, never a guess: a
+ * wait built from `read()` polling would silently disagree with herdr's own state derivation on the
+ * same question, and a wait has no truthful degrade the way a snapshot does — so a backend that cannot
+ * answer is refused rather than emulated.
+ *
+ * PORTABLE and exit-code-free by design, the exact mirror of `CaptureUnsupportedError`. The DECISION
+ * to refuse is the library's and lives in `deriveAgentWait`, the one place that sees the adapter — 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 the caller
+ * composes the message without re-deriving it; the terse `message` is a factual log line.
+ */
+declare class AgentLifecycleUnsupportedError extends Error {
+  readonly backend: string;
+  constructor(backend: string);
+}
+/**
+ * Wait for the target pane's agent to reach one of `opts.until` (or the backend's default set) through
+ * the adapter — the surface-independent orchestrator `agent wait` drives, and the single home of the
+ * agent-wait refusal. The optional `agentLifecycle` seam is where a backend says whether it has a
+ * native wait at all; a backend without it is refused HERE (`AgentLifecycleUnsupportedError`), BEFORE
+ * any exec, because `waitForState` never sees the adapter and so cannot make that call. A backend that
+ * HAS the capability delegates to it unchanged.
+ *
+ * Mirrors `deriveRegionCapture` (`template-capture.ts`) exactly: the orchestrator is the one place that
+ * sees the adapter, so it is the one place the emulate-or-refuse decision can be made.
+ */
+declare function deriveAgentWait(adapter: MuxAdapter, exec: Exec, target: MuxTarget, opts: AgentWaitOptions): AgentStatus;
+/**
+ * The `agent` subpath facade with its `Exec` and backend BOUND — the exec-bound parallel of
+ * `worktreeApi`/`templateApi`. `agentApi(env, deps?)` resolves the backend adapter from `env` ONCE
+ * (`resolveMuxAdapter`, defaulting `exec` to `nodeExec`) and exposes `supported`/`status`/`wait` with
+ * the seams already threaded, so a caller never re-plumbs an adapter or a runner into them.
+ *
+ * It ADDS no logic of its own: `supported` reads the very capability presence `deriveAgentWait` gates
+ * on, `status` reads the same `LivePane.agentStatus` the listing already carries (for one pane rather
+ * than redefining it), and `wait` routes THROUGH `deriveAgentWait` — so the emulate-or-refuse decision
+ * stays specified once and enforced once, with no second refusal path here that could drift from it.
+ */
+interface AgentApi {
+  /** Whether this backend reports agent-lifecycle state at all (herdr yes; tmux/wezterm/zellij no). */
+  supported(): boolean;
+  /** A pane's current agent state, or `undefined` when the backend has no feed (absent-not-false). */
+  status(target: MuxTarget): AgentStatus | undefined;
+  /**
+   * Block until the pane's agent reaches one of `opts.until` (or the backend's default set); throws
+   * `AgentLifecycleUnsupportedError` naming the backend on one without the capability, via
+   * `deriveAgentWait`. A bare `wait(target)` takes herdr's own defaults (`opts ?? {}`).
+   */
+  wait(target: MuxTarget, opts?: AgentWaitOptions | undefined): AgentStatus;
+}
+/**
+ * Bind the agent-lifecycle capability to an environment and runner once, returning an `AgentApi` whose
+ * methods no longer take an `Exec`. `deps.exec` defaults to `nodeExec`; `env` is bound like
+ * `resolveMux(env)` because it is what the probe resolves the backend from.
+ */
+declare function agentApi(env: NodeJS.ProcessEnv, deps?: {
+  exec?: Exec | undefined;
+} | undefined): AgentApi;
+//#endregion
+export { AgentApi, type AgentLifecycle, AgentLifecycleUnsupportedError, type AgentStatus, type AgentWaitOptions, agentApi, deriveAgentWait };
+//# sourceMappingURL=agent.d.mts.map

package/dist/agent.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.mts","names":[],"sources":["../src/agent.ts"],"mappings":";;;;;;;;;;;;;;;;cA4Ba,uCAAuC;WACvC;EAAZ,YAAY;;;;;;;;;;;;;iBAiBG,gBACf,SAAS,YACT,MAAM,MACN,QAAQ,WACR,MAAM,mBACJ;;;;;;;;;;;;UAiBc;;EAEhB;;EAEA,OAAO,QAAQ,YAAY;;;;;;EAM3B,KAAK,QAAQ,WAAW,OAAO,+BAA+B;;;;;;;iBAQ/C,SAAS,KAAK,OAAO,YAAY;EAAS,OAAO;gBAAiC"}

package/dist/agent.mjs

@@ -0,0 +1,58 @@
+import { m as nodeExec } from "./worktree-hHuFZkpW.mjs";
+import { r as resolveMuxAdapter } from "./backend-Cif257ji.mjs";
+//#region src/agent.ts
+/**
+* An agent-lifecycle wait asked of a backend that has no native agent-state primitive (`agent wait`
+* on tmux, wezterm or zellij). An absent `agentLifecycle` seam member is a REFUSAL, never a guess: a
+* wait built from `read()` polling would silently disagree with herdr's own state derivation on the
+* same question, and a wait has no truthful degrade the way a snapshot does — so a backend that cannot
+* answer is refused rather than emulated.
+*
+* PORTABLE and exit-code-free by design, the exact mirror of `CaptureUnsupportedError`. The DECISION
+* to refuse is the library's and lives in `deriveAgentWait`, the one place that sees the adapter — 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 the caller
+* composes the message without re-deriving it; the terse `message` is a factual log line.
+*/
+var AgentLifecycleUnsupportedError = class extends Error {
+	backend;
+	constructor(backend) {
+		super(`${backend} cannot report agent-lifecycle state`);
+		this.backend = backend;
+		this.name = "AgentLifecycleUnsupportedError";
+	}
+};
+/**
+* Wait for the target pane's agent to reach one of `opts.until` (or the backend's default set) through
+* the adapter — the surface-independent orchestrator `agent wait` drives, and the single home of the
+* agent-wait refusal. The optional `agentLifecycle` seam is where a backend says whether it has a
+* native wait at all; a backend without it is refused HERE (`AgentLifecycleUnsupportedError`), BEFORE
+* any exec, because `waitForState` never sees the adapter and so cannot make that call. A backend that
+* HAS the capability delegates to it unchanged.
+*
+* Mirrors `deriveRegionCapture` (`template-capture.ts`) exactly: the orchestrator is the one place that
+* sees the adapter, so it is the one place the emulate-or-refuse decision can be made.
+*/
+function deriveAgentWait(adapter, exec, target, opts) {
+	const agentLifecycle = adapter.agentLifecycle;
+	if (!agentLifecycle) throw new AgentLifecycleUnsupportedError(adapter.name);
+	return agentLifecycle.waitForState(exec, target, opts);
+}
+/**
+* Bind the agent-lifecycle capability to an environment and runner once, returning an `AgentApi` whose
+* methods no longer take an `Exec`. `deps.exec` defaults to `nodeExec`; `env` is bound like
+* `resolveMux(env)` because it is what the probe resolves the backend from.
+*/
+function agentApi(env, deps) {
+	const exec = deps?.exec ?? nodeExec;
+	const adapter = resolveMuxAdapter(env, exec);
+	return {
+		supported: () => adapter.agentLifecycle !== void 0,
+		status: (target) => adapter.listPanes(exec).find((p) => p.id === target.id)?.agentStatus,
+		wait: (target, opts) => deriveAgentWait(adapter, exec, target, opts ?? {})
+	};
+}
+//#endregion
+export { AgentLifecycleUnsupportedError, agentApi, deriveAgentWait };
+
+//# sourceMappingURL=agent.mjs.map

package/dist/agent.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.mjs","names":[],"sources":["../src/agent.ts"],"sourcesContent":["import { resolveMuxAdapter } from './backend.ts'\nimport { type Exec, nodeExec } from './exec.ts'\nimport type { AgentStatus, AgentWaitOptions, MuxAdapter, MuxTarget } from './mux.ts'\n\n/**\n * The `cyber-mux/agent` subpath — the agent-lifecycle capability's orchestrator and its refusal.\n *\n * The `AgentStatus` type rides out on the `.` barrel (it is part of `LivePane`, and `mux.ts` is\n * re-exported there); the WAIT capability — the `AgentLifecycle` seam plus the emulate-or-refuse\n * decision below — is this subpath alone, kept off the core barrel exactly as `template`'s apply\n * engine is: a capability nobody has to import to drive a pane is not on the surface everybody gets.\n */\n\nexport type { AgentLifecycle, AgentStatus, AgentWaitOptions } from './mux.ts'\n\n/**\n * An agent-lifecycle wait asked of a backend that has no native agent-state primitive (`agent wait`\n * on tmux, wezterm or zellij). An absent `agentLifecycle` seam member is a REFUSAL, never a guess: a\n * wait built from `read()` polling would silently disagree with herdr's own state derivation on the\n * same question, and a wait has no truthful degrade the way a snapshot does — so a backend that cannot\n * answer is refused rather than emulated.\n *\n * PORTABLE and exit-code-free by design, the exact mirror of `CaptureUnsupportedError`. The DECISION\n * to refuse is the library's and lives in `deriveAgentWait`, the one place that sees the adapter — how\n * the refusal SURFACES (the exit code, the fix hint, the exact sentence) is the CLI's, which catches\n * this and re-raises its own `backend-unsupported` error. `backend` names the backend so the caller\n * composes the message without re-deriving it; the terse `message` is a factual log line.\n */\nexport class AgentLifecycleUnsupportedError extends Error {\n\tconstructor(readonly backend: string) {\n\t\tsuper(`${backend} cannot report agent-lifecycle state`)\n\t\tthis.name = 'AgentLifecycleUnsupportedError'\n\t}\n}\n\n/**\n * Wait for the target pane's agent to reach one of `opts.until` (or the backend's default set) through\n * the adapter — the surface-independent orchestrator `agent wait` drives, and the single home of the\n * agent-wait refusal. The optional `agentLifecycle` seam is where a backend says whether it has a\n * native wait at all; a backend without it is refused HERE (`AgentLifecycleUnsupportedError`), BEFORE\n * any exec, because `waitForState` never sees the adapter and so cannot make that call. A backend that\n * HAS the capability delegates to it unchanged.\n *\n * Mirrors `deriveRegionCapture` (`template-capture.ts`) exactly: the orchestrator is the one place that\n * sees the adapter, so it is the one place the emulate-or-refuse decision can be made.\n */\nexport function deriveAgentWait(\n\tadapter: MuxAdapter,\n\texec: Exec,\n\ttarget: MuxTarget,\n\topts: AgentWaitOptions,\n): AgentStatus {\n\tconst agentLifecycle = adapter.agentLifecycle\n\tif (!agentLifecycle) throw new AgentLifecycleUnsupportedError(adapter.name)\n\treturn agentLifecycle.waitForState(exec, target, opts)\n}\n\n/**\n * The `agent` subpath facade with its `Exec` and backend BOUND — the exec-bound parallel of\n * `worktreeApi`/`templateApi`. `agentApi(env, deps?)` resolves the backend adapter from `env` ONCE\n * (`resolveMuxAdapter`, defaulting `exec` to `nodeExec`) and exposes `supported`/`status`/`wait` with\n * the seams already threaded, so a caller never re-plumbs an adapter or a runner into them.\n *\n * It ADDS no logic of its own: `supported` reads the very capability presence `deriveAgentWait` gates\n * on, `status` reads the same `LivePane.agentStatus` the listing already carries (for one pane rather\n * than redefining it), and `wait` routes THROUGH `deriveAgentWait` — so the emulate-or-refuse decision\n * stays specified once and enforced once, with no second refusal path here that could drift from it.\n */\nexport interface AgentApi {\n\t/** Whether this backend reports agent-lifecycle state at all (herdr yes; tmux/wezterm/zellij no). */\n\tsupported(): boolean\n\t/** A pane's current agent state, or `undefined` when the backend has no feed (absent-not-false). */\n\tstatus(target: MuxTarget): AgentStatus | undefined\n\t/**\n\t * Block until the pane's agent reaches one of `opts.until` (or the backend's default set); throws\n\t * `AgentLifecycleUnsupportedError` naming the backend on one without the capability, via\n\t * `deriveAgentWait`. A bare `wait(target)` takes herdr's own defaults (`opts ?? {}`).\n\t */\n\twait(target: MuxTarget, opts?: AgentWaitOptions | undefined): AgentStatus\n}\n\n/**\n * Bind the agent-lifecycle capability to an environment and runner once, returning an `AgentApi` whose\n * methods no longer take an `Exec`. `deps.exec` defaults to `nodeExec`; `env` is bound like\n * `resolveMux(env)` because it is what the probe resolves the backend from.\n */\nexport function agentApi(env: NodeJS.ProcessEnv, deps?: { exec?: Exec | undefined } | undefined): AgentApi {\n\tconst exec = deps?.exec ?? nodeExec\n\tconst adapter = resolveMuxAdapter(env, exec)\n\treturn {\n\t\tsupported: () => adapter.agentLifecycle !== undefined,\n\t\tstatus: (target) => adapter.listPanes(exec).find((p) => p.id === target.id)?.agentStatus,\n\t\twait: (target, opts) => deriveAgentWait(adapter, exec, target, opts ?? {}),\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA4BA,IAAa,iCAAb,cAAoD,MAAM;CACpC;CAArB,YAAY,SAA0B;EACrC,MAAM,GAAG,QAAQ,qCAAqC;EADlC,KAAA,UAAA;EAEpB,KAAK,OAAO;CACb;AACD;;;;;;;;;;;;AAaA,SAAgB,gBACf,SACA,MACA,QACA,MACc;CACd,MAAM,iBAAiB,QAAQ;CAC/B,IAAI,CAAC,gBAAgB,MAAM,IAAI,+BAA+B,QAAQ,IAAI;CAC1E,OAAO,eAAe,aAAa,MAAM,QAAQ,IAAI;AACtD;;;;;;AA+BA,SAAgB,SAAS,KAAwB,MAA0D;CAC1G,MAAM,OAAO,MAAM,QAAQ;CAC3B,MAAM,UAAU,kBAAkB,KAAK,IAAI;CAC3C,OAAO;EACN,iBAAiB,QAAQ,mBAAmB,KAAA;EAC5C,SAAS,WAAW,QAAQ,UAAU,IAAI,CAAC,CAAC,MAAM,MAAM,EAAE,OAAO,OAAO,EAAE,CAAC,EAAE;EAC7E,OAAO,QAAQ,SAAS,gBAAgB,SAAS,MAAM,QAAQ,QAAQ,CAAC,CAAC;CAC1E;AACD"}

package/dist/{backend-DnrbmL6N.mjs → backend-Cif257ji.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,130 @@ function envFallback(env, command) {
 	};
 }
 //#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/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);
+		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.herdr.ts
 /**
 * herdr backend — detected via `$HERDR_ENV`. herdr (https://herdr.dev) is an agent-aware terminal
@@ -97,7 +221,7 @@ const herdrMuxAdapter = {
 		} 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",
@@ -170,6 +294,61 @@ const herdrMuxAdapter = {
 		if (opts?.lines != null) args.push("--lines", String(opts.lines));
 		return exec("herdr", args) ?? "";
 	},
+	/**
+	* The one backend with a NATIVE wait: `pane wait-output` blocks in herdr itself (0.7.5), 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 says `recent`). 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` (verified against
+	*    0.7.5: `{"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",
+			"wait-output",
+			target.id,
+			"--source",
+			"visible",
+			"--timeout",
+			String(opts.timeoutMs)
+		];
+		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)
+			};
+		}
+		return parseWaitOutput(out);
+	},
 	focus(exec, target) {
 		const { workspaceId, tabId } = parsePaneLocation$1(exec("herdr", [
 			"pane",
@@ -230,10 +409,12 @@ 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",
 				...harness !== void 0 ? { harness } : {},
+				...agentStatus !== void 0 ? { agentStatus } : {},
 				...p.cwd !== void 0 ? { cwd: p.cwd } : {},
 				...label !== void 0 ? { label } : {}
 			};
@@ -298,9 +479,54 @@ 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 0.7.5 reports — 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
@@ -391,6 +617,16 @@ 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 +673,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.
 */
@@ -778,6 +1073,9 @@ const tmuxMuxAdapter = {
 		if (opts?.lines != null) args.push("-S", `-${opts.lines}`);
 		return exec("tmux", args) ?? "";
 	},
+	waitForOutput(exec, target, opts) {
+		return pollForOutput(tmuxMuxAdapter, exec, target, opts);
+	},
 	focus(exec, target) {
 		const { sessionName, windowId } = parsePaneLocation(exec("tmux", [
 			"list-panes",
@@ -1018,6 +1316,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)}%`;
 }
 /**
@@ -1211,6 +1510,9 @@ function createWeztermAdapter(deps) {
 			if (opts?.lines != null) args.push("--start-line", String(-opts.lines));
 			return exec("wezterm", args) ?? "";
 		},
+		waitForOutput(exec, target, opts) {
+			return pollForOutput(adapter, exec, target, opts);
+		},
 		focus(exec, target) {
 			exec("wezterm", [
 				"cli",
@@ -1326,6 +1628,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));
 }
 /**
@@ -1535,6 +1838,9 @@ function createZellijAdapter(deps) {
 				target.id
 			]) ?? "";
 		},
+		waitForOutput(exec, target, opts) {
+			return pollForOutput(adapter, exec, target, opts);
+		},
 		focus(exec, target) {
 			exec("zellij", [
 				"action",
@@ -1891,6 +2197,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;
@@ -1978,6 +2293,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 +2301,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 +2340,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 { DEFAULT_WAIT_POLL_MS as _, nudge as a, pollForOutput 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, assertWaitPattern as v, envFallback as x, matchWaitPattern as y };
 
-//# sourceMappingURL=backend-DnrbmL6N.mjs.map
+//# sourceMappingURL=backend-Cif257ji.mjs.map