@wastedcode/claudemux 0.2.0

package/dist/errors.js

@@ -0,0 +1,300 @@
+/**
+ * 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 class ClaudemuxError extends Error {
+    /** The session this error pertains to. */
+    sessionName;
+    constructor(message, sessionName) {
+        super(`[claudemux:${sessionName}] ${message}`);
+        this.name = new.target.name;
+        this.sessionName = sessionName;
+    }
+}
+/**
+ * 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 class SessionExists extends ClaudemuxError {
+    constructor(sessionName) {
+        super("session already exists; refusing to silently adopt — use adopt() to reconnect to a live session", sessionName);
+    }
+}
+/**
+ * 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 class InvalidAgentSessionId extends ClaudemuxError {
+    /** The malformed value the caller passed. */
+    value;
+    constructor(value) {
+        super(`invalid agentSessionId ${JSON.stringify(value)}: must be a v4 UUID (e.g. the value crypto.randomUUID() produces)`, 
+        // No session was created — mirror InvalidSessionName's placeholder.
+        "<invalid-agentSessionId>");
+        this.value = value;
+    }
+}
+/**
+ * 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 class AgentSessionIdConflict extends ClaudemuxError {
+    constructor(sessionName) {
+        super("explicit agentSessionId conflicts with an identity flag in extraArgs " +
+            "(e.g. --session-id / --resume / --fork-session); pass the conversation id one way, not both", sessionName);
+    }
+}
+/**
+ * Thrown by the boot orchestrator when a recognized dialog matches but its
+ * response did not advance the pane within the dialog timeout.
+ */
+export class DialogStuck extends ClaudemuxError {
+    /** The matched dialog's id (e.g. `"theme-picker"`). */
+    dialogId;
+    constructor(sessionName, dialogId) {
+        super(`dialog "${dialogId}" matched but did not advance after response`, sessionName);
+        this.dialogId = dialogId;
+    }
+}
+/**
+ * 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 class ReplTimeout extends ClaudemuxError {
+    /** The timeout budget that elapsed, in milliseconds. */
+    timeoutMs;
+    constructor(sessionName, timeoutMs) {
+        super(`REPL did not settle within ${timeoutMs}ms`, sessionName);
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * 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 class LoginRequired extends ClaudemuxError {
+    constructor(sessionName) {
+        super("claude is not authenticated; the login-method dialog appeared. " +
+            "Run `claude` interactively once to sign in, then retry", sessionName);
+    }
+}
+/**
+ * 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 class WorkspaceUntrusted extends ClaudemuxError {
+    /** The cwd the agent asked to trust. */
+    cwd;
+    constructor(sessionName, cwd) {
+        super(`workspace at ${JSON.stringify(cwd)} is not trusted; the agent asked to trust it. Pass trustWorkspace:true (or --trust-workspace) to grant the agent read/edit/execute on this folder — note this writes a persistent, per-folder trust flag to the agent's config`, sessionName);
+        this.cwd = cwd;
+    }
+}
+/**
+ * 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 class PromptResponseUnsupported extends ClaudemuxError {
+    /** The agent that has no permission-prompt mapping (e.g. a future codex def). */
+    agentName;
+    constructor(sessionName, agentName) {
+        super(`agent "${agentName}" declares no permission-prompt handling; respond() has no menu mapping to answer the prompt`, sessionName);
+        this.agentName = agentName;
+    }
+}
+/**
+ * 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 class TranscriptUnlocatable extends ClaudemuxError {
+    constructor(sessionName) {
+        super("transcript cannot be located (no recoverable agentSessionId and no hook-reported path); reads are blind, not empty — persist the agentSessionId, or check `agentSessionId !== undefined` before reading", sessionName);
+    }
+}
+/**
+ * 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 class SessionGone extends ClaudemuxError {
+    constructor(sessionName) {
+        super("session is gone", sessionName);
+    }
+}
+/**
+ * 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 class AgentExitedDuringBoot extends ClaudemuxError {
+    /** The caller-chosen id the spawn used, if any — the likely collision culprit. */
+    agentSessionId;
+    constructor(sessionName, agentSessionId) {
+        const withId = agentSessionId !== undefined
+            ? ` (spawned with agentSessionId ${agentSessionId}, which is most likely already in use)`
+            : "";
+        super(`the agent exited before the session became ready${withId}; the most common cause is an agentSessionId collision (the agent refuses to resume silently and exits)`, sessionName);
+        if (agentSessionId !== undefined)
+            this.agentSessionId = agentSessionId;
+    }
+}
+/**
+ * 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 class BackendUnreachable extends ClaudemuxError {
+    /** Why the backend was unreachable — see {@link BackendUnreachableKind}. */
+    kind;
+    /** The underlying spawn / connection error, if available. */
+    underlying;
+    constructor(sessionName, kind, underlying) {
+        super(`backend unreachable [${kind}]${underlying ? ` (${underlying.message})` : ""}`, sessionName);
+        this.kind = kind;
+        if (underlying !== undefined) {
+            this.underlying = underlying;
+        }
+    }
+}
+/**
+ * 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 class InvalidSessionName extends ClaudemuxError {
+    /** Which field was invalid (`"name"` or `"namespace"`). */
+    field;
+    /** The actual value the caller passed. */
+    value;
+    /** The reason the value is rejected. */
+    reason;
+    constructor(field, value, reason) {
+        super(`invalid ${field} ${JSON.stringify(value)}: ${reason}`, 
+        // Use the offending value itself so the error has *some* identifier.
+        // The session was never created; there is no real name to use.
+        `<invalid-${field}>`);
+        this.field = field;
+        this.value = value;
+        this.reason = reason;
+    }
+}
+/**
+ * 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 class BackendError extends ClaudemuxError {
+    argv;
+    exitCode;
+    stderr;
+    constructor(sessionName, argv, exitCode, stderr) {
+        super(`backend command failed (exit ${exitCode}): ${stderr.trim() || "<empty stderr>"}`, sessionName);
+        this.argv = argv;
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * claudemux — drive long-lived Claude Code sessions from Node.
+ *
+ * Public re-exports only; the file carries no logic. Internal seams
+ * (`Backend`, `BackendEvent`, `SendPayload`, `ClassifierRules`) stay
+ * internal so the public API survives a backend swap without consumer
+ * rewrites.
+ */
+export { claude } from "./agents/index.js";
+export type { AgentDef, BootDialog, HookEdge } from "./agents/types.js";
+export { AgentExitedDuringBoot, AgentSessionIdConflict, BackendError, BackendUnreachable, ClaudemuxError, DialogStuck, InvalidAgentSessionId, InvalidSessionName, LoginRequired, PromptResponseUnsupported, ReplTimeout, SessionExists, SessionGone, TranscriptUnlocatable, WorkspaceUntrusted, } from "./errors.js";
+export { ask, recover } from "./compose.js";
+export type { AskResult, RecoverResult, RecoverStatus } from "./compose.js";
+export { DELIVERED_QUEUED, DELIVERY_UNCONFIRMED } from "./session/handle.js";
+export { adopt } from "./session/adopt.js";
+export type { AdoptOptions } from "./session/adopt.js";
+export { create } from "./session/create.js";
+export { exists, kill, list } from "./session/registry.js";
+export { resume } from "./session/resume.js";
+export type { ResumeOptions } from "./session/resume.js";
+export type { BackendCommandEvent, IdleState, Message, MessagePart, Progress, PromptChoice, ReadyOpts, SessionHandle, State, TurnOutcome, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,yBAAyB,EACzB,WAAW,EACX,aAAa,EACb,WAAW,EACX,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,YAAY,EACV,mBAAmB,EACnB,SAAS,EACT,OAAO,EACP,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,aAAa,EACb,KAAK,EACL,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * claudemux — drive long-lived Claude Code sessions from Node.
+ *
+ * Public re-exports only; the file carries no logic. Internal seams
+ * (`Backend`, `BackendEvent`, `SendPayload`, `ClassifierRules`) stay
+ * internal so the public API survives a backend swap without consumer
+ * rewrites.
+ */
+export { claude } from "./agents/index.js";
+export { AgentExitedDuringBoot, AgentSessionIdConflict, BackendError, BackendUnreachable, ClaudemuxError, DialogStuck, InvalidAgentSessionId, InvalidSessionName, LoginRequired, PromptResponseUnsupported, ReplTimeout, SessionExists, SessionGone, TranscriptUnlocatable, WorkspaceUntrusted, } from "./errors.js";
+export { ask, recover } from "./compose.js";
+export { DELIVERED_QUEUED, DELIVERY_UNCONFIRMED } from "./session/handle.js";
+export { adopt } from "./session/adopt.js";
+export { create } from "./session/create.js";
+export { exists, kill, list } from "./session/registry.js";
+export { resume } from "./session/resume.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,yBAAyB,EACzB,WAAW,EACX,aAAa,EACb,WAAW,EACX,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/io/baseline.d.ts

@@ -0,0 +1,53 @@
+import type { AgentDef } from "../agents/types.js";
+import type { Backend, SessionRef } from "../backends/types.js";
+/**
+ * The send→wait *baseline* — how a stateless `wait()` (the CLI reattaches in a
+ * fresh process each invocation) tells a turn that already completed from the
+ * previous turn's idle prompt.
+ *
+ * `wait()` is transition-aware: it will not accept `idle` as "turn complete"
+ * until it has seen the pane *leave* idle. In-process that signal is an
+ * observed `working` frame. But the CLI `send` and `wait` are separate
+ * processes; for a fast turn the agent can be back to idle before the `wait`
+ * process takes its first capture, so `wait` never observes `working` and
+ * hangs to `ReplTimeout` (bug 8a500a52).
+ *
+ * The fix: `send` records a fingerprint of the **post-submit** pane — the
+ * frame after the input box has cleared but *before* the agent's answer lands
+ * — under a session-scoped key. A later `wait` arms when the live pane
+ * *diverges* from that fingerprint. Capturing the post-submit frame (not the
+ * pre-send one) is what keeps the previous turn's idle from counting as a
+ * divergence: during the post-submit window the live pane *equals* the
+ * baseline, so `wait` correctly keeps polling instead of returning early.
+ */
+export declare const SEND_BASELINE_KEY = "send-baseline";
+/** Stable fingerprint of a bottom-N pane capture (sha256 hex — newline-safe). */
+export declare function paneFingerprint(text: string): string;
+/**
+ * After a `send`, capture the post-submit pane fingerprint: the first frame
+ * that (a) differs from the pre-send pane `pre` and (b) is a settled idle box
+ * or a working frame — i.e. the submit was accepted and the box cleared (or
+ * the agent already started working), but *before* the answer completes.
+ *
+ * Returns `undefined` when no clean frame appears within budget, or when the
+ * pre-send pane is unknown (without `pre` we cannot exclude the previous idle,
+ * and a wrong baseline would re-introduce the premature-return race). In that
+ * case `wait` falls back to arming on an observed `working` frame.
+ */
+export declare function captureSendBaseline(backend: Backend, agent: AgentDef, ref: SessionRef, pre: string | undefined): Promise<string | undefined>;
+/**
+ * Read the persisted post-submit baseline fingerprint, if any. Best-effort:
+ * returns `undefined` when unset or unreadable, so `wait` degrades to
+ * observed-working arming rather than failing.
+ */
+export declare function readSendBaseline(backend: Backend, ref: SessionRef): Promise<string | undefined>;
+/**
+ * Persist the post-submit baseline fingerprint for a later `wait`. An empty
+ * `fingerprint` clears the baseline (so `readSendBaseline` reports "unset") —
+ * `send` uses that to drop a prior turn's stale fingerprint when it couldn't
+ * establish a fresh one. Best-effort — a metadata write failure must never
+ * fail the `send` (whose contract is byte delivery); `wait` then falls back to
+ * observed-working arming.
+ */
+export declare function writeSendBaseline(backend: Backend, ref: SessionRef, fingerprint: string): Promise<void>;
+//# sourceMappingURL=baseline.d.ts.map

package/dist/io/baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../../src/io/baseline.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIhE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAOjD,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,QAAQ,EACf,GAAG,EAAE,UAAU,EACf,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAoB7B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,UAAU,EACf,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/io/baseline.js

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { CLASSIFIER_CAPTURE } from "../session/constants.js";
+import { sleep } from "../util/sleep.js";
+/**
+ * The send→wait *baseline* — how a stateless `wait()` (the CLI reattaches in a
+ * fresh process each invocation) tells a turn that already completed from the
+ * previous turn's idle prompt.
+ *
+ * `wait()` is transition-aware: it will not accept `idle` as "turn complete"
+ * until it has seen the pane *leave* idle. In-process that signal is an
+ * observed `working` frame. But the CLI `send` and `wait` are separate
+ * processes; for a fast turn the agent can be back to idle before the `wait`
+ * process takes its first capture, so `wait` never observes `working` and
+ * hangs to `ReplTimeout` (bug 8a500a52).
+ *
+ * The fix: `send` records a fingerprint of the **post-submit** pane — the
+ * frame after the input box has cleared but *before* the agent's answer lands
+ * — under a session-scoped key. A later `wait` arms when the live pane
+ * *diverges* from that fingerprint. Capturing the post-submit frame (not the
+ * pre-send one) is what keeps the previous turn's idle from counting as a
+ * divergence: during the post-submit window the live pane *equals* the
+ * baseline, so `wait` correctly keeps polling instead of returning early.
+ */
+export const SEND_BASELINE_KEY = "send-baseline";
+/** Total budget for `send` to observe the post-submit frame before giving up. */
+const BASELINE_CAPTURE_BUDGET_MS = 2_000;
+/** Capture cadence while watching for the post-submit frame. */
+const BASELINE_POLL_MS = 40;
+/** Stable fingerprint of a bottom-N pane capture (sha256 hex — newline-safe). */
+export function paneFingerprint(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/**
+ * After a `send`, capture the post-submit pane fingerprint: the first frame
+ * that (a) differs from the pre-send pane `pre` and (b) is a settled idle box
+ * or a working frame — i.e. the submit was accepted and the box cleared (or
+ * the agent already started working), but *before* the answer completes.
+ *
+ * Returns `undefined` when no clean frame appears within budget, or when the
+ * pre-send pane is unknown (without `pre` we cannot exclude the previous idle,
+ * and a wrong baseline would re-introduce the premature-return race). In that
+ * case `wait` falls back to arming on an observed `working` frame.
+ */
+export async function captureSendBaseline(backend, agent, ref, pre) {
+    if (pre === undefined)
+        return undefined;
+    const deadline = Date.now() + BASELINE_CAPTURE_BUDGET_MS;
+    while (Date.now() < deadline) {
+        let text;
+        try {
+            text = await backend.capture(ref, CLASSIFIER_CAPTURE);
+        }
+        catch {
+            return undefined; // pane unreadable — let wait fall back to working-arm
+        }
+        // The first frame that has changed from the pre-send pane AND is either an
+        // empty input box (the submit cleared it) or a working frame. This is
+        // reached before the answer lands, so it never captures the completed-turn
+        // pane (which would make a later wait see "no divergence" and hang).
+        if (text !== pre && (agent.boot.isReady(text) || agent.rules.working(text))) {
+            return paneFingerprint(text);
+        }
+        await sleep(BASELINE_POLL_MS);
+    }
+    return undefined;
+}
+/**
+ * Read the persisted post-submit baseline fingerprint, if any. Best-effort:
+ * returns `undefined` when unset or unreadable, so `wait` degrades to
+ * observed-working arming rather than failing.
+ */
+export async function readSendBaseline(backend, ref) {
+    try {
+        const v = await backend.getSessionMeta(ref, SEND_BASELINE_KEY);
+        return v && v.length > 0 ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Persist the post-submit baseline fingerprint for a later `wait`. An empty
+ * `fingerprint` clears the baseline (so `readSendBaseline` reports "unset") —
+ * `send` uses that to drop a prior turn's stale fingerprint when it couldn't
+ * establish a fresh one. Best-effort — a metadata write failure must never
+ * fail the `send` (whose contract is byte delivery); `wait` then falls back to
+ * observed-working arming.
+ */
+export async function writeSendBaseline(backend, ref, fingerprint) {
+    try {
+        await backend.setSessionMeta(ref, SEND_BASELINE_KEY, fingerprint);
+    }
+    catch {
+        /* baseline is an optimization for cross-process wait; ignore */
+    }
+}
+//# sourceMappingURL=baseline.js.map

package/dist/io/baseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../../src/io/baseline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAEjD,iFAAiF;AACjF,MAAM,0BAA0B,GAAG,KAAK,CAAC;AACzC,gEAAgE;AAChE,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAE5B,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAgB,EAChB,KAAe,EACf,GAAe,EACf,GAAuB;IAEvB,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,0BAA0B,CAAC;IACzD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC,CAAC,sDAAsD;QAC1E,CAAC;QACD,2EAA2E;QAC3E,sEAAsE;QACtE,2EAA2E;QAC3E,qEAAqE;QACrE,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAC5E,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;QACD,MAAM,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgB,EAChB,GAAe;IAEf,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;QAC/D,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAgB,EAChB,GAAe,EACf,WAAmB;IAEnB,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,iBAAiB,EAAE,WAAW,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;AACH,CAAC"}

package/dist/io/capture.d.ts

@@ -0,0 +1,15 @@
+import type { Backend, SessionRef } from "../backends/types.js";
+/**
+ * Pure pass-through to `Backend.capture`. Lives in `src/io/` because the
+ * top-level public verbs ARE the io layer; the backend is below it. Future
+ * non-tmux backends implement the same `capture` shape, so the wrapper
+ * stays trivial.
+ *
+ * @param opts.ansi  preserve escape sequences when `true`.
+ * @param opts.lines bottom-N visible lines (default: full visible region).
+ */
+export declare function captureOnce(backend: Backend, ref: SessionRef, opts?: {
+    ansi?: boolean;
+    lines?: number;
+}): Promise<string>;
+//# sourceMappingURL=capture.d.ts.map

package/dist/io/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/io/capture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,UAAU,EACf,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC,OAAO,CAAC,MAAM,CAAC,CAEjB"}

package/dist/io/capture.js

@@ -0,0 +1,13 @@
+/**
+ * Pure pass-through to `Backend.capture`. Lives in `src/io/` because the
+ * top-level public verbs ARE the io layer; the backend is below it. Future
+ * non-tmux backends implement the same `capture` shape, so the wrapper
+ * stays trivial.
+ *
+ * @param opts.ansi  preserve escape sequences when `true`.
+ * @param opts.lines bottom-N visible lines (default: full visible region).
+ */
+export function captureOnce(backend, ref, opts) {
+    return backend.capture(ref, opts);
+}
+//# sourceMappingURL=capture.js.map

package/dist/io/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../src/io/capture.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,OAAgB,EAChB,GAAe,EACf,IAAyC;IAEzC,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC"}

package/dist/io/interrupt.d.ts

@@ -0,0 +1,46 @@
+import type { Backend, SessionRef } from "../backends/types.js";
+/**
+ * Fire a single `Escape` at the pane — claude's own documented interrupt key
+ * (the classifier detects `working` by the literal `"esc to interrupt"`
+ * affordance, `agents/claude.ts`). ESC is already in `SendPayload`'s key union
+ * (`backends/types.ts`) and `sendKey` already sends it, so there is no backend
+ * change.
+ *
+ * ESC is sent **unconditionally** — no state-check guard. A guard would bake
+ * policy into the substrate and open a TOCTOU race (state read, then ESC, with
+ * the agent free to change state in between). ESC on an idle claude is harmless
+ * (it clears the input box). Gating on `state()` is the consumer's call. This
+ * is a mechanism, not a policy
+ * (`brain/decisions/0013-mechanism-not-policy-substrate-boundary.md`).
+ *
+ * That consumer-side gate is also not atomic with the ESC: a turn can finish
+ * between a `state()===working` read and the ESC landing — most easily across
+ * separate CLI processes (a short turn completes in the gap), so the ESC hits
+ * an already-idle agent. That is a harmless no-op, not a failure; a consumer
+ * that needs the interrupt to catch a turn should read `state()` and call this
+ * in one tight in-process sequence, not trust a stale prior-process reading.
+ *
+ * Blocks on **write delivery** plus a brief fixed settle ({@link
+ * INTERRUPT_SETTLE_MS}); it guarantees ESC was delivered, NOT that an in-flight
+ * abort has fully completed. This verb does exactly one named action — stop the
+ * turn — and nothing more (`brain/decisions/0013`, "a primitive does exactly the
+ * keystroke it names").
+ *
+ * **After interrupt(), claude does NOT return to a clean idle prompt.** It
+ * restores the interrupted message back into the composer, and the classifier
+ * reads that frame as `unknown` (never `idle`, never `working`). Two
+ * consequences the consumer must know:
+ *   - `wait()` after interrupt() resolves `{ kind: "aborted" }` immediately (the
+ *     handle records the interrupt authoritatively) — it does NOT hang waiting for
+ *     an idle that won't come.
+ *   - Do **not** naively `send()` a replacement after interrupt(): `send`
+ *     pastes into the *non-empty* composer (the restored message), so the
+ *     submission is the two texts concatenated. For a clean "interrupt and
+ *     replace" the composer must first be cleared to empty. claude's only
+ *     substrate-reachable composer clear is repeated ESC (its "Esc again to
+ *     clear" ladder), so the recipe is consumer-composed and claude-specific —
+ *     see the README "Interrupting a working agent" note. It is deliberately
+ *     NOT bundled into this agent-agnostic verb.
+ */
+export declare function interruptOnce(backend: Backend, ref: SessionRef): Promise<void>;
+//# sourceMappingURL=interrupt.d.ts.map

package/dist/io/interrupt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupt.d.ts","sourceRoot":"","sources":["../../src/io/interrupt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAehE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpF"}