cyber-mux 0.6.0 → 0.8.0

package/README.md

@@ -0,0 +1,73 @@
+# cyber-mux
+
+[![npm version](https://img.shields.io/npm/v/cyber-mux.svg)](https://www.npmjs.com/package/cyber-mux)
+[![npm downloads](https://img.shields.io/npm/dm/cyber-mux.svg)](https://www.npmjs.com/package/cyber-mux)
+[![release](https://github.com/cyberuni/cyber-mux/actions/workflows/release.yml/badge.svg)](https://github.com/cyberuni/cyber-mux/actions/workflows/release.yml)
+[![docs](https://img.shields.io/badge/docs-cyberuni.github.io-blue)](https://cyberuni.github.io/cyber-mux/)
+[![license](https://img.shields.io/npm/l/cyber-mux.svg)](https://www.npmjs.com/package/cyber-mux)
+
+Cross-multiplexer pane control for AI-agent tooling. One contract over terminal multiplexers — open,
+send, read, focus, and close panes without caring which multiplexer you are inside.
+
+`cyber-mux` is the mux seam used by [`cyberlegion`](https://github.com/cyberuni/cyberplace), kept
+deliberately narrow: it drives panes and nothing else.
+
+## Install
+
+```bash
+npx cyber-mux mode
+```
+
+## What it does
+
+- **Detects** the multiplexer you are running under — env fast-path (`CYBER_MUX` / `CYBER_MUX_PANE`),
+  otherwise a process-ancestry walk falling back to the multiplexer's own env hints.
+- **Drives panes** through one `MuxAdapter` contract: `open`, `send`, `submit`, `read`, `wait`,
+  `focus`, `close`, `list`, `exists`.
+- **Nudges** a peer pane and verifies the turn was actually taken (recovers a submit swallowed by a
+  booting harness).
+- **Worktrees**: create a git worktree and open it in a new workspace/session in one step.
+
+## Backends
+
+Drivable: **tmux**, **rmux**, **herdr**, **wezterm**, **zellij**, **cmux**, **otty**.
+
+GNU **screen** is recognized and reported truthfully, then rejected with a named error rather than
+driven — it addresses panes positionally, so a driver-created pane has no stable identity to send to,
+read from, or self-identify by.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `cyber-mux doctor` | Probe the multiplexer, self pane, and backend; print fast-path pins |
+| `cyber-mux mode` | Report the detected session backend |
+| `cyber-mux open` | Open a new pane/tab/workspace, optionally launching a command in it |
+| `cyber-mux send` | Drive a pane without taking its turn (text or keys) |
+| `cyber-mux submit` | Take a pane's turn: type the text if given, then press Enter |
+| `cyber-mux read` | Capture a pane's output |
+| `cyber-mux wait` | Block until a pane's output matches (exit 0), or the timeout elapses (exit 1) |
+| `cyber-mux focus` | Beam the attached client to a pane |
+| `cyber-mux close` | Close a pane |
+| `cyber-mux list` / `exists` | Enumerate live panes / probe whether one is still live |
+| `cyber-mux worktree` | Git worktree helpers for spawning and tearing down a session |
+| `cyber-mux template` | Manage named templates (apply one with `open`/`worktree --template`) |
+| `cyber-mux agent` | Inspect and wait on a pane's agent-lifecycle state |
+
+Full reference: <https://cyberuni.github.io/cyber-mux/>
+
+## Development
+
+Node and pnpm are pinned in `mise.toml` and managed by [mise](https://mise.jdx.dev):
+
+```bash
+mise install  # node + pnpm at the pinned versions
+pnpm install
+pnpm verify   # build + typecheck + lint + test
+```
+
+The CLI lives in `packages/cyber-mux`; the docs site in `apps/website` (Astro + Starlight).
+
+## License
+
+MIT

package/dist/agent.d.mts

@@ -1,12 +1,70 @@
 import { t as Exec } from "./exec-B81m4yjz.mjs";
-import { f as MuxTarget, n as AgentStatus, o as MuxAdapter, r as AgentWaitOptions, t as AgentLifecycle } from "./mux-DBpfXsdE.mjs";
+import { m as MuxTarget, n as AgentStatus, o as MuxAdapter, r as AgentWaitOptions, t as AgentLifecycle } from "./mux-CDrZQglk.mjs";
+//#region src/agent-states.d.ts
+/**
+ * The agent-wait STATE-SET refusal — what an `AgentLifecycle` backend answers when it has the native
+ * wait but cannot express the state set the caller asked for.
+ *
+ * Its own module rather than a member of `agent.ts` for the reason `floating.ts`/`zoom.ts`/`resize.ts`
+ * are their own modules: the adapters throw it, and `agent.ts` imports `backend.ts`, which imports
+ * every adapter — so an adapter reaching into `agent.ts` for the class would close a cycle. The class
+ * lives here and RIDES OUT on the `cyber-mux/agent` subpath (re-exported by `agent.ts`), because the
+ * capability it belongs to is that subpath's and deliberately not on the core barrel.
+ */
+/**
+ * A wait asked for states the backend's native wait cannot name. Distinct from
+ * `AgentLifecycleUnsupportedError`, and the distinction is the whole point: that one says *this
+ * backend has no agent wait at all*; this one says *it has one, and its vocabulary is narrower than
+ * what you asked for*. Collapsing them would tell a caller on otty to "run it on herdr" when the fix
+ * is to drop one state from `until`.
+ *
+ * **Refused by NAME rather than silently narrowed**, which is the only honest answer available. A
+ * backend that waits on `idle` alone, handed `until: ['idle', 'blocked']`, has exactly three options:
+ * wait for `idle` only and return it (a wait that ends on a state the caller did not ask for — the
+ * plausible-wrong-answer shape), wait for all of them (impossible, there is no flag), or say so. It
+ * says so.
+ *
+ * PORTABLE and exit-code-free by design, the same shape every other seam refusal takes. `backend`
+ * names the backend, `requested` the set that was asked for, and `supported` the set the backend can
+ * actually end a wait on — so a caller composes the fix without re-deriving any of it.
+ */
+declare class AgentWaitStatesUnsupportedError extends Error {
+  readonly backend: string;
+  readonly requested: readonly AgentStatus[];
+  readonly supported: readonly AgentStatus[];
+  constructor(backend: string, requested: readonly AgentStatus[], supported: readonly AgentStatus[]);
+}
+/**
+ * Refuse an `until` set a backend's native wait cannot express — the single spelling of the refusal,
+ * so a second backend with a narrow vocabulary cannot drift into a second message.
+ *
+ * Takes the backend NAME rather than the adapter, for `refuseFloatingPane`/`refusePaneZoom`'s reason:
+ * it is called from inside an adapter method while the adapter object is still being constructed, and
+ * the name is the only thing the error carries anyway.
+ */
+declare function refuseAgentWaitStates(backend: string, requested: readonly AgentStatus[], supported: readonly AgentStatus[]): never;
+/**
+ * Whether `until` is satisfiable by a backend whose native wait ends on exactly `supported`.
+ *
+ * An EMPTY or omitted `until` is satisfiable by construction: the seam defines it as *take the
+ * backend's own default*, and a backend never restates that default in the command it runs — so there
+ * is nothing to check. A non-empty set is satisfiable only when every state in it is one the backend
+ * can end on; a set that names a state the backend cannot reach would otherwise end the wait on a
+ * state nobody asked for.
+ */
+declare function agentWaitStatesSatisfiable(until: readonly AgentStatus[] | undefined, supported: readonly AgentStatus[]): boolean;
+//#endregion
 //#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.
+ * An agent-lifecycle wait asked of a backend that has no native agent-state primitive (`agent wait` on
+ * tmux, rmux, wezterm, zellij or cmux). An absent `agentLifecycle` seam member is a REFUSAL, never a
+ * guess: a wait built from `read()` polling would silently disagree with the backend'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.
+ *
+ * Distinct from `AgentWaitStatesUnsupportedError` (`agent-states.ts`), which a backend that HAS the
+ * wait throws when its vocabulary is narrower than the `until` it was handed. This one says *no wait
+ * here*; that one says *this wait, not those states*.
  *
  * 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
@@ -42,14 +100,22 @@ declare function deriveAgentWait(adapter: MuxAdapter, exec: Exec, target: MuxTar
  * 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). */
+  /** Whether this backend can WAIT on agent-lifecycle state (herdr and otty yes; the rest no). */
   supported(): boolean;
-  /** A pane's current agent state, or `undefined` when the backend has no feed (absent-not-false). */
+  /**
+   * A pane's current agent state, or `undefined` when the backend has no feed (absent-not-false).
+   *
+   * Deliberately NOT the question `supported()` answers, and otty is the backend that proves the two
+   * are independent: otty can BLOCK on its own agent state but exposes no documented CLI read of it,
+   * so `supported()` is `true` there while this stays `undefined`. Until otty they happened to agree
+   * on every backend.
+   */
   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 ?? {}`).
+   * `deriveAgentWait`, or `AgentWaitStatesUnsupportedError` on one whose native wait cannot name every
+   * requested state. A bare `wait(target)` takes the backend's own defaults (`opts ?? {}`).
    */
   wait(target: MuxTarget, opts?: AgentWaitOptions | undefined): AgentStatus;
 }
@@ -62,5 +128,5 @@ declare function agentApi(env: NodeJS.ProcessEnv, deps?: {
   exec?: Exec | undefined;
 } | undefined): AgentApi;
 //#endregion
-export { AgentApi, type AgentLifecycle, AgentLifecycleUnsupportedError, type AgentStatus, type AgentWaitOptions, agentApi, deriveAgentWait };
+export { AgentApi, type AgentLifecycle, AgentLifecycleUnsupportedError, type AgentStatus, type AgentWaitOptions, AgentWaitStatesUnsupportedError, agentApi, agentWaitStatesSatisfiable, deriveAgentWait, refuseAgentWaitStates };
 //# sourceMappingURL=agent.d.mts.map

package/dist/agent.d.mts.map

@@ -1 +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"}
+{"version":3,"file":"agent.d.mts","names":[],"sources":["../src/agent-states.ts","../src/agent.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA8Ba,wCAAwC;WAEnD;WACA,oBAA6B;WAC7B,oBAA6B;EAH9B,YACC,iBACA,oBAA6B,eAC7B,oBAA6B;;;;;;;;;;iBAef,sBACf,iBACA,oBAAoB,eACpB,oBAAoB;;;;;;;;;;iBAcL,2BACf,gBAAgB,2BAChB,oBAAoB;;;;;;;;;;;;;;;;;;;;cC/BR,uCAAuC;WACvC;EAAZ,YAAY;;;;;;;;;;;;;iBAiBG,gBACf,SAAS,YACT,MAAM,MACN,QAAQ,WACR,MAAM,mBACJ;;;;;;;;;;;;UAiBc;;EAEhB;;;;;;;;;EASA,OAAO,QAAQ,YAAY;;;;;;;EAO3B,KAAK,QAAQ,WAAW,OAAO,+BAA+B;;;;;;;iBAQ/C,SAAS,KAAK,OAAO,YAAY;EAAS,OAAO;gBAAiC"}

package/dist/agent.mjs

@@ -1,12 +1,16 @@
-import { m as nodeExec } from "./worktree-hHuFZkpW.mjs";
-import { r as resolveMuxAdapter } from "./backend-AErdtLRB.mjs";
+import { h as nodeExec } from "./worktree-Bj6IgHv7.mjs";
+import { b as agentWaitStatesSatisfiable, r as resolveMuxAdapter, x as refuseAgentWaitStates, y as AgentWaitStatesUnsupportedError } from "./backend-Dg5JGbd3.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.
+* An agent-lifecycle wait asked of a backend that has no native agent-state primitive (`agent wait` on
+* tmux, rmux, wezterm, zellij or cmux). An absent `agentLifecycle` seam member is a REFUSAL, never a
+* guess: a wait built from `read()` polling would silently disagree with the backend'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.
+*
+* Distinct from `AgentWaitStatesUnsupportedError` (`agent-states.ts`), which a backend that HAS the
+* wait throws when its vocabulary is narrower than the `until` it was handed. This one says *no wait
+* here*; that one says *this wait, not those states*.
 *
 * 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
@@ -53,6 +57,6 @@ function agentApi(env, deps) {
 	};
 }
 //#endregion
-export { AgentLifecycleUnsupportedError, agentApi, deriveAgentWait };
+export { AgentLifecycleUnsupportedError, AgentWaitStatesUnsupportedError, agentApi, agentWaitStatesSatisfiable, deriveAgentWait, refuseAgentWaitStates };
 
 //# sourceMappingURL=agent.mjs.map

package/dist/agent.mjs.map

@@ -1 +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"}
+{"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 {\n\tAgentWaitStatesUnsupportedError,\n\tagentWaitStatesSatisfiable,\n\trefuseAgentWaitStates,\n} from './agent-states.ts'\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` on\n * tmux, rmux, wezterm, zellij or cmux). An absent `agentLifecycle` seam member is a REFUSAL, never a\n * guess: a wait built from `read()` polling would silently disagree with the backend's own state\n * derivation on the same question, and a wait has no truthful degrade the way a snapshot does — so a\n * backend that cannot answer is refused rather than emulated.\n *\n * Distinct from `AgentWaitStatesUnsupportedError` (`agent-states.ts`), which a backend that HAS the\n * wait throws when its vocabulary is narrower than the `until` it was handed. This one says *no wait\n * here*; that one says *this wait, not those states*.\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 can WAIT on agent-lifecycle state (herdr and otty yes; the rest no). */\n\tsupported(): boolean\n\t/**\n\t * A pane's current agent state, or `undefined` when the backend has no feed (absent-not-false).\n\t *\n\t * Deliberately NOT the question `supported()` answers, and otty is the backend that proves the two\n\t * are independent: otty can BLOCK on its own agent state but exposes no documented CLI read of it,\n\t * so `supported()` is `true` there while this stays `undefined`. Until otty they happened to agree\n\t * on every backend.\n\t */\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`, or `AgentWaitStatesUnsupportedError` on one whose native wait cannot name every\n\t * requested state. A bare `wait(target)` takes the backend'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":";;;;;;;;;;;;;;;;;;;;AAqCA,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;;;;;;AAuCA,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"}