@wastedcode/claudemux 0.2.0

package/dist/cli/state.js

@@ -0,0 +1,11 @@
+import { handleFor } from "./context.js";
+/**
+ * `claudemux state <name>` — print the current pane state
+ * (`working` / `idle` / `permission-prompt` / `dialog` / `unknown`).
+ */
+export async function stateCli(name, opts = {}) {
+    const handle = await handleFor({ ...opts, name });
+    const state = await handle.state();
+    process.stdout.write(`${state}\n`);
+}
+//# sourceMappingURL=state.js.map

package/dist/cli/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/cli/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE1D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,OAAmB,EAAE;IAChE,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACnC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/dist/cli/turn-complete.d.ts

@@ -0,0 +1,8 @@
+import { type CommonOpts } from "./context.js";
+/**
+ * `claudemux turn-complete <name> <cursor>` — print `true`/`false` and exit 0/1
+ * for "did the turn at <cursor> produce a reply?". The crash-recovery face: after
+ * a `resume`, exit 1 (false) on your last-sent cursor means re-send that prompt.
+ */
+export declare function turnCompleteCli(name: string, cursor: string, opts?: CommonOpts): Promise<void>;
+//# sourceMappingURL=turn-complete.d.ts.map

package/dist/cli/turn-complete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-complete.d.ts","sourceRoot":"","sources":["../../src/cli/turn-complete.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAa,MAAM,cAAc,CAAC;AAE1D;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/cli/turn-complete.js

@@ -0,0 +1,14 @@
+import { handleFor } from "./context.js";
+/**
+ * `claudemux turn-complete <name> <cursor>` — print `true`/`false` and exit 0/1
+ * for "did the turn at <cursor> produce a reply?". The crash-recovery face: after
+ * a `resume`, exit 1 (false) on your last-sent cursor means re-send that prompt.
+ */
+export async function turnCompleteCli(name, cursor, opts = {}) {
+    const handle = await handleFor({ ...opts, name });
+    const done = await handle.turnComplete(cursor);
+    process.stdout.write(`${done}\n`);
+    if (!done)
+        process.exitCode = 1;
+}
+//# sourceMappingURL=turn-complete.js.map

package/dist/cli/turn-complete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-complete.js","sourceRoot":"","sources":["../../src/cli/turn-complete.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE1D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAY,EACZ,MAAc,EACd,OAAmB,EAAE;IAErB,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AAClC,CAAC"}

package/dist/cli/wait.d.ts

@@ -0,0 +1,13 @@
+import { type CommonOpts, type PatienceCliOpts } from "./context.js";
+export interface WaitCliOpts extends CommonOpts, PatienceCliOpts {
+}
+/**
+ * `claudemux wait <name>` — block until the turn reaches a terminal
+ * {@link TurnOutcome}. Prints the outcome as JSON (the `kind` plus any nested
+ * `on`/`reason`) so a scripting consumer can branch on it. Exit code is 0 for
+ * `completed`, non-zero otherwise, so shell callers can gate without parsing.
+ * Patience is the consumer's: `--timeout-ms`/`--idle-ms`, else the CLI's own
+ * wall-clock default (the library imposes none).
+ */
+export declare function waitCli(name: string, opts?: WaitCliOpts): Promise<void>;
+//# sourceMappingURL=wait.d.ts.map

package/dist/cli/wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../src/cli/wait.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAA2B,MAAM,cAAc,CAAC;AAE9F,MAAM,WAAW,WAAY,SAAQ,UAAU,EAAE,eAAe;CAAG;AAEnE;;;;;;;GAOG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKjF"}

package/dist/cli/wait.js

@@ -0,0 +1,17 @@
+import { handleFor, patienceOpts } from "./context.js";
+/**
+ * `claudemux wait <name>` — block until the turn reaches a terminal
+ * {@link TurnOutcome}. Prints the outcome as JSON (the `kind` plus any nested
+ * `on`/`reason`) so a scripting consumer can branch on it. Exit code is 0 for
+ * `completed`, non-zero otherwise, so shell callers can gate without parsing.
+ * Patience is the consumer's: `--timeout-ms`/`--idle-ms`, else the CLI's own
+ * wall-clock default (the library imposes none).
+ */
+export async function waitCli(name, opts = {}) {
+    const handle = await handleFor({ ...opts, name });
+    const outcome = await handle.wait(patienceOpts(opts));
+    process.stdout.write(`${JSON.stringify(outcome)}\n`);
+    if (outcome.kind !== "completed")
+        process.exitCode = 1;
+}
+//# sourceMappingURL=wait.js.map

package/dist/cli/wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../../src/cli/wait.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyC,SAAS,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAI9F;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY,EAAE,OAAoB,EAAE;IAChE,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACzD,CAAC"}

package/dist/compose.d.ts

@@ -0,0 +1,81 @@
+import { type ResumeOptions } from "./session/resume.js";
+import type { Cursor, Message, ReadyOpts, SessionHandle, TurnOutcome } from "./types.js";
+/**
+ * The composition seam — the **single owner** of multi-primitive workflows over
+ * a {@link SessionHandle}. It holds no belief and no content of its own: it only
+ * sequences the primitives, each of which stays the sole owner of its decision.
+ * Both the CLI (`claudemux ask`) and programmatic consumers (e.g. Posse) call
+ * THIS, so the round-trip has one owner rather than one per interface face.
+ */
+/** What {@link ask} returns: the full outcome, the messages, and the cursor. */
+export interface AskResult {
+    /**
+     * The terminal {@link TurnOutcome}, surfaced in full — never swallowed.
+     * `completed` is the happy path; `awaiting`/`aborted`/`budget-exceeded` are
+     * first-class and the caller must branch on them.
+     */
+    readonly outcome: TurnOutcome;
+    /**
+     * The messages produced since this turn's `send`, read via the one content
+     * owner ({@link SessionHandle.messagesSince}). On `completed` they are the
+     * full, flushed reply (race-free); on a non-`completed` outcome they are
+     * whatever has landed so far (possibly partial) — interpret with `outcome`.
+     */
+    readonly messages: readonly Message[];
+    /** The cursor this turn's `send` produced — re-read content later with it. */
+    readonly cursor: Cursor;
+}
+/**
+ * Do one Q&A round-trip: **send** the prompt, **wait** for the turn to reach a
+ * terminal {@link TurnOutcome}, then read the **messages** since it. Pure
+ * composition of the three primitives — `ask` is sugar, not a third source of
+ * truth: content still flows only through `messagesSince`, the outcome only
+ * through `wait`.
+ *
+ * @example
+ * ```ts
+ * import { create, ask } from "claudemux";
+ * const session = await create({ name: "job", cwd: process.cwd() });
+ * const { outcome, messages } = await ask(session, "What's 2+2?");
+ * if (outcome.kind === "completed") console.log(messages.at(-1));
+ * else handleAbnormal(outcome); // awaiting / aborted / budget-exceeded
+ * ```
+ */
+export declare function ask(session: SessionHandle, text: string, opts?: ReadyOpts): Promise<AskResult>;
+/**
+ * How a session was reconnected on daemon boot — see {@link recover}.
+ *   - `"attached"` — the pane was **still alive** (your process restarted, the
+ *     session didn't); reconnected, nothing lost.
+ *   - `"resumed"` — the pane was **gone** (it crashed, or the box lost its tmux
+ *     server); the conversation was continued in a **fresh** pane. A turn may
+ *     have been in flight when it died — check `turnComplete(yourLastCursor)`.
+ */
+export type RecoverStatus = "attached" | "resumed";
+/** What {@link recover} returns: the live handle + how it was recovered. */
+export interface RecoverResult {
+    readonly session: SessionHandle;
+    readonly status: RecoverStatus;
+}
+/**
+ * Reconnect to a session on boot — the **reconnect compound**, one decision
+ * (attach the live pane vs resume the dead one) composed from two atomic
+ * sub-owners ({@link adopt} and {@link resume}). It owns no policy beyond that:
+ * the re-send decision stays the consumer's (via `turnComplete`). A daemon calls
+ * THIS for each `{ name, agentSessionId }` it persisted, instead of hand-rolling
+ * a `try`/catch-`SessionGone`/resume dance — and the returned {@link RecoverStatus}
+ * makes "did it crash?" a field, not control flow you write yourself. Only
+ * `SessionGone` from `adopt` (uniform across both crash modes) triggers the
+ * resume fallback; any other adopt error propagates — those are caller mistakes,
+ * not crashes.
+ *
+ * @example
+ * ```ts
+ * // daemon boot, per persisted { name, agentSessionId, cwd, lastCursor, lastPrompt }:
+ * const { session, status } = await recover({ name, agentSessionId, cwd });
+ * if (status === "resumed" && !(await session.turnComplete(lastCursor)))
+ *   await session.send(lastPrompt);   // it crashed mid-turn — re-send the one lost turn
+ * // status === "attached" ⇒ the session never went down; just keep going.
+ * ```
+ */
+export declare function recover(opts: ResumeOptions): Promise<RecoverResult>;
+//# sourceMappingURL=compose.d.ts.map

package/dist/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,aAAa,EAAU,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzF;;;;;;GAMG;AAEH,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,GAAG,CACvB,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,SAAS,GACf,OAAO,CAAC,SAAS,CAAC,CAKpB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC;AAEnD,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAczE"}

package/dist/compose.js

@@ -0,0 +1,64 @@
+import { SessionGone } from "./errors.js";
+import { adopt } from "./session/adopt.js";
+import { resume } from "./session/resume.js";
+/**
+ * Do one Q&A round-trip: **send** the prompt, **wait** for the turn to reach a
+ * terminal {@link TurnOutcome}, then read the **messages** since it. Pure
+ * composition of the three primitives — `ask` is sugar, not a third source of
+ * truth: content still flows only through `messagesSince`, the outcome only
+ * through `wait`.
+ *
+ * @example
+ * ```ts
+ * import { create, ask } from "claudemux";
+ * const session = await create({ name: "job", cwd: process.cwd() });
+ * const { outcome, messages } = await ask(session, "What's 2+2?");
+ * if (outcome.kind === "completed") console.log(messages.at(-1));
+ * else handleAbnormal(outcome); // awaiting / aborted / budget-exceeded
+ * ```
+ */
+export async function ask(session, text, opts) {
+    const cursor = await session.send(text);
+    const outcome = await session.wait(opts);
+    const messages = await session.messagesSince(cursor);
+    return { outcome, messages, cursor };
+}
+/**
+ * Reconnect to a session on boot — the **reconnect compound**, one decision
+ * (attach the live pane vs resume the dead one) composed from two atomic
+ * sub-owners ({@link adopt} and {@link resume}). It owns no policy beyond that:
+ * the re-send decision stays the consumer's (via `turnComplete`). A daemon calls
+ * THIS for each `{ name, agentSessionId }` it persisted, instead of hand-rolling
+ * a `try`/catch-`SessionGone`/resume dance — and the returned {@link RecoverStatus}
+ * makes "did it crash?" a field, not control flow you write yourself. Only
+ * `SessionGone` from `adopt` (uniform across both crash modes) triggers the
+ * resume fallback; any other adopt error propagates — those are caller mistakes,
+ * not crashes.
+ *
+ * @example
+ * ```ts
+ * // daemon boot, per persisted { name, agentSessionId, cwd, lastCursor, lastPrompt }:
+ * const { session, status } = await recover({ name, agentSessionId, cwd });
+ * if (status === "resumed" && !(await session.turnComplete(lastCursor)))
+ *   await session.send(lastPrompt);   // it crashed mid-turn — re-send the one lost turn
+ * // status === "attached" ⇒ the session never went down; just keep going.
+ * ```
+ */
+export async function recover(opts) {
+    try {
+        const session = await adopt({
+            name: opts.name,
+            ...(opts.namespace === undefined ? {} : { namespace: opts.namespace }),
+            ...(opts.agent === undefined ? {} : { agent: opts.agent }),
+            ...(opts.backend === undefined ? {} : { backend: opts.backend }),
+        });
+        return { session, status: "attached" };
+    }
+    catch (e) {
+        if (!(e instanceof SessionGone))
+            throw e; // a real adopt error, not a crash
+        const session = await resume(opts);
+        return { session, status: "resumed" };
+    }
+}
+//# sourceMappingURL=compose.js.map

package/dist/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAsB,MAAM,EAAE,MAAM,qBAAqB,CAAC;AA8BjE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CACvB,OAAsB,EACtB,IAAY,EACZ,IAAgB;IAEhB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACrD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AACvC,CAAC;AAkBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAmB;IAC/C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC;YAC1B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;YACtE,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;YAC1D,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;SACjE,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,CAAC,CAAC,YAAY,WAAW,CAAC;YAAE,MAAM,CAAC,CAAC,CAAC,kCAAkC;QAC5E,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACxC,CAAC;AACH,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Typed errors thrown by the claudemux substrate. Every error carries the
+ * session name in its message so a consumer logging an unknown failure
+ * still has the context they need.
+ *
+ * No bare `Error` is ever thrown from the library. The classes here are
+ * exhaustive for the current public surface.
+ */
+/** Base class — consumers can `catch (e: ClaudemuxError)` for the union. */
+export declare class ClaudemuxError extends Error {
+    /** The session this error pertains to. */
+    readonly sessionName: string;
+    constructor(message: string, sessionName: string);
+}
+/**
+ * Thrown by {@link create} when a session with the requested name already
+ * exists. The substrate never silently adopts an existing session — reconnect
+ * to the live session with {@link adopt} instead.
+ */
+export declare class SessionExists extends ClaudemuxError {
+    constructor(sessionName: string);
+}
+/**
+ * Thrown by {@link create} when a caller-supplied `agentSessionId` is not a
+ * well-formed v4 UUID. Thrown *before spawn*, at the substrate boundary.
+ *
+ * @remarks
+ * This is a **security boundary**, not just input hygiene. The id flows into
+ * the agent's argv next to its identity flag, and into the backend's per-session
+ * store and command grammar — where, in some backends, a bare `;` element can be
+ * a command separator. A v4 UUID is hex + hyphens only, so it can never be `;`,
+ * a path, or any token a backend would re-interpret; rejecting non-UUIDs here is
+ * what keeps the always-two-argv-elements injection safe. Do not "simplify" this
+ * to a loose check.
+ */
+export declare class InvalidAgentSessionId extends ClaudemuxError {
+    /** The malformed value the caller passed. */
+    readonly value: string;
+    constructor(value: string);
+}
+/**
+ * Thrown by {@link create} when the caller passes an explicit
+ * `agentSessionId` **and** an identity flag in `extraArgs` that also selects a
+ * conversation id (claude: `--session-id`, `-r`/`--resume`, `--fork-session`).
+ * The two would fight over which id the agent runs under, so the substrate
+ * fails fast *before spawn* rather than silently dropping one. Pass the id one
+ * way or the other, not both.
+ *
+ * @remarks
+ * Which `extraArgs` flags count as identity flags is agent-specific knowledge,
+ * so the conflict is detected inside the agent's `buildArgv` (claude owns the
+ * flag vocabulary per the layering grep) and surfaced as this neutral error.
+ */
+export declare class AgentSessionIdConflict extends ClaudemuxError {
+    constructor(sessionName: string);
+}
+/**
+ * Thrown by the boot orchestrator when a recognized dialog matches but its
+ * response did not advance the pane within the dialog timeout.
+ */
+export declare class DialogStuck extends ClaudemuxError {
+    /** The matched dialog's id (e.g. `"theme-picker"`). */
+    readonly dialogId: string;
+    constructor(sessionName: string, dialogId: string);
+}
+/**
+ * Thrown by **boot** ({@link create}/{@link resume}/{@link adopt}) when the REPL
+ * did not reach a stable ready state within `bootTimeoutMs`. NOT thrown by
+ * `wait()` — turn patience is the consumer's, so a turn that outlasts your budget
+ * is a returned `budget-exceeded` {@link TurnOutcome}, never an exception.
+ */
+export declare class ReplTimeout extends ClaudemuxError {
+    /** The timeout budget that elapsed, in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(sessionName: string, timeoutMs: number);
+}
+/**
+ * Thrown by boot when the login-method dialog fires — claudemux assumes the
+ * founder is already authenticated, so this dialog firing under claudemux is
+ * a setup error, not an auto-answerable dialog.
+ */
+export declare class LoginRequired extends ClaudemuxError {
+    constructor(sessionName: string);
+}
+/**
+ * Thrown by boot when the agent presents a workspace-trust dialog for a
+ * `cwd` the substrate has not been told to trust. Trusting a folder is an
+ * **authority grant** (the agent gains read/edit/execute on those files),
+ * so the substrate fails closed: it does **not** auto-answer the dialog —
+ * it throws this *before sending any keystroke* and leaves the decision to
+ * the consumer. Pass `trustWorkspace: true` to `create` (or `--trust-workspace`
+ * on the CLI) to opt in.
+ *
+ * @remarks
+ * Opting in writes a **persistent, global, per-cwd** trust flag to the
+ * agent's config (`~/.claude.json` → `projects[<abs-cwd>]`), NOT a
+ * session-scoped one: it outlives the claudemux process and applies to
+ * every future `claude` run in that path, including the user's own
+ * interactive sessions. Trust is sticky per `(HOME × cwd-path)` — fail-closed
+ * only protects the *first* run in an untrusted path; a reused checkout path
+ * a prior run (or the user) already trusted inherits trust silently. For
+ * untrusted-fork workloads (PR bots / CI), use an ephemeral unique checkout
+ * path or an ephemeral HOME per run.
+ */
+export declare class WorkspaceUntrusted extends ClaudemuxError {
+    /** The cwd the agent asked to trust. */
+    readonly cwd: string;
+    constructor(sessionName: string, cwd: string);
+}
+/**
+ * Thrown by {@link SessionHandle.respond} when the agent declares no
+ * permission-prompt handling — there is no menu mapping to translate a
+ * {@link PromptChoice} into a keystroke, so the substrate refuses to guess a
+ * digit (a wrong guess could pick the broadest "allow all" option). An agent
+ * grows prompt handling by adding the mapping to its `AgentDef`; until then a
+ * consumer that hits an `awaiting{permission-prompt}` must answer the agent
+ * out-of-band (or run it in a non-interactive permission mode).
+ */
+export declare class PromptResponseUnsupported extends ClaudemuxError {
+    /** The agent that has no permission-prompt mapping (e.g. a future codex def). */
+    readonly agentName: string;
+    constructor(sessionName: string, agentName: string);
+}
+/**
+ * Thrown by {@link SessionHandle.messagesSince} / {@link SessionHandle.turnComplete}
+ * when the session's transcript **cannot be located at all** — there is no
+ * recoverable `agentSessionId` to locate it by AND no hook edge has reported its
+ * path (an {@link adopt} whose recovery cache missed, a non-claudemux session, or
+ * a fork before its first hook edge). Reads are *blind*, not "nothing new."
+ *
+ * This is a **loud** failure on purpose: an empty read silently conflated with
+ * "no reply yet" sits exactly in the crash-recovery re-send path, where the wrong
+ * answer double-runs work. Throwing forces the consumer to handle "I can't see
+ * this conversation" distinctly. A genuinely empty (but *locatable*) transcript,
+ * or an unresolvable cursor (a sentinel/garbage value), still returns empty —
+ * only true unlocatability throws.
+ */
+export declare class TranscriptUnlocatable extends ClaudemuxError {
+    constructor(sessionName: string);
+}
+/**
+ * Thrown when the backend cannot find the named session — it has been reaped
+ * (a crash, a `kill`, or the box lost its backend server). The canonical "this
+ * session is gone" for **every** per-session op (read or write); `kill()` never
+ * throws it (killing a gone session is success).
+ */
+export declare class SessionGone extends ClaudemuxError {
+    constructor(sessionName: string);
+}
+/**
+ * Thrown by {@link create} when the agent process **exits before the session
+ * becomes ready** — claudemux spawned it, but it was gone (its backend session
+ * reaped) before boot could reach an interactive prompt.
+ *
+ * @remarks
+ * **The most common cause is an `agentSessionId` collision:** claude refuses to
+ * silently resume or clobber an in-use conversation id — it prints
+ * "Session ID … is already in use" and exits. But a malformed `extraArgs` flag,
+ * an auth edge, or any startup crash produce the *identical* shape, and
+ * claudemux **cannot read which** — the substrate runs panes with
+ * `remain-on-exit off`, so claude's stderr is reaped before boot can capture
+ * it. That is the same deliberate property that lets {@link adopt} hand back a
+ * clean {@link SessionGone} for a crashed agent instead of a corpse handle, so
+ * we do not flip it to recover a diagnostic string.
+ *
+ * This is a distinct class on purpose (errors.ts reuses before adding):
+ * {@link SessionGone} reads as *external* reaping of a session that should
+ * exist, which does not carry the meaning the create path needs — *"the agent I
+ * just spawned rejected its own launch"* (self-inflicted exit vs external
+ * interference) — which is exactly what the consumer must act on.
+ *
+ * When the spawn used a caller-chosen id, it is carried on
+ * {@link agentSessionId} so the collision case stays actionable as structured
+ * data (pick another id, or resume that conversation) without scraping text.
+ *
+ * **Deferred precision:** once a `transcriptPath` helper lands (owning claude's
+ * cwd-slug rule in `claude.ts` per the layering grep), a pre-spawn transcript
+ * probe can upgrade the collision case to a precise `AgentSessionInUse` and
+ * fall back to this error for the other death causes — a non-breaking addition.
+ */
+export declare class AgentExitedDuringBoot extends ClaudemuxError {
+    /** The caller-chosen id the spawn used, if any — the likely collision culprit. */
+    readonly agentSessionId?: string;
+    constructor(sessionName: string, agentSessionId?: string);
+}
+/**
+ * Discriminates *why* the backend is unreachable. Recovery code branches on
+ * this: `no-server` is a legitimate "nothing is running yet" (query verbs
+ * treat it as absence), whereas `spawn-failed` (binary missing) and
+ * `timeout` (wedged backend) are real faults that must surface loudly — a
+ * missing dependency or a hung process must never masquerade as "no
+ * sessions exist."
+ */
+export type BackendUnreachableKind = "no-server" | "spawn-failed" | "timeout";
+/**
+ * Thrown when the underlying backend (the agent's I/O substrate) is
+ * unreachable — the backend process failed to spawn (`spawn-failed`), its
+ * server was not running on the requested connection (`no-server`), or a
+ * backend invocation hung past its budget (`timeout`).
+ */
+export declare class BackendUnreachable extends ClaudemuxError {
+    /** Why the backend was unreachable — see {@link BackendUnreachableKind}. */
+    readonly kind: BackendUnreachableKind;
+    /** The underlying spawn / connection error, if available. */
+    readonly underlying?: Error;
+    constructor(sessionName: string, kind: BackendUnreachableKind, underlying?: Error);
+}
+/**
+ * Thrown by `create` / `spawn` when the session name or namespace contains
+ * characters that the substrate cannot encode safely for the backend's
+ * target grammar. The substrate fails fast at the boundary instead of
+ * silently renaming and producing an un-addressable handle.
+ *
+ * @remarks
+ * Reserved set: `.`, `:`, `*`, `?`, leading `-`, any whitespace, `/`,
+ * `\n`, `\r`, `\\`, and the empty string.
+ */
+export declare class InvalidSessionName extends ClaudemuxError {
+    /** Which field was invalid (`"name"` or `"namespace"`). */
+    readonly field: "name" | "namespace";
+    /** The actual value the caller passed. */
+    readonly value: string;
+    /** The reason the value is rejected. */
+    readonly reason: string;
+    constructor(field: "name" | "namespace", value: string, reason: string);
+}
+/**
+ * Wrapper for an unexpected backend failure that isn't one of the typed
+ * cases above (non-zero exit + unrecognized stderr).
+ *
+ * @remarks
+ * The `.message` deliberately **excludes the backend argv** — the argv is
+ * pure backend vocabulary (the backend's own subcommand names) and leaking
+ * it into the user-facing message violates the substrate's "zero references
+ * to the backend in error messages" promise. The argv lives on `.argv` (and
+ * flows through `onBackendCommand`) for programmatic diagnosis; the
+ * human-readable message carries the exit code and the backend's own stderr
+ * text, which is the diagnostic value without the command vocabulary.
+ *
+ * This is the structural backstop behind the backend classifier's
+ * routine-case promotion: even a backend failure shape we haven't classified
+ * yet cannot leak the backend's command names into user-facing text.
+ */
+export declare class BackendError extends ClaudemuxError {
+    readonly argv: readonly string[];
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(sessionName: string, argv: readonly string[], exitCode: number, stderr: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}