@wastedcode/claudemux 0.2.0

package/dist/observe/observer.d.ts

@@ -0,0 +1,86 @@
+import type { AgentDef, HookEdge } from "../agents/types.js";
+import type { Progress, State } from "../types.js";
+/**
+ * Derive a {@link Progress} from the ordered hook edges + a transcript count.
+ * Pure — the testable heart of the Observer.
+ *
+ * `phase`: `stop` ⇒ `done`; else a tool in flight ⇒ `tool`; else the last edge
+ * being `tool-end` ⇒ `composing`; else ⇒ `prompt`; no edges ⇒ `unknown`.
+ * `toolInFlight`: net-open tools (`tool-start` count minus `tool-end` count).
+ */
+export declare function deriveProgress(o: {
+    edges: readonly HookEdge[];
+    transcriptCount: number;
+}): Progress;
+/**
+ * The single fused belief about a session **right now** — the one owner of
+ * "what's true." Extends {@link Progress} with the pane-only facts hooks can't
+ * see (`interrupted`) and the edge timings `wait()` composes into a
+ * {@link import('../types.js').TurnOutcome} (`lastStopAt` = the turn-end trigger,
+ * `lastActivityAt` = a progress heartbeat). Pure: the caller supplies the
+ * already-classified pane (classification is the agent's job, fusion is ours).
+ */
+export interface Belief extends Progress {
+    /** The pane shows an interrupted (ESC'd) turn — `wait()` maps this to `aborted`. */
+    readonly interrupted: boolean;
+    /** ms of the most recent turn-end (`stop`) edge, if any. */
+    readonly lastStopAt?: number;
+    /** ms of the most recent lifecycle edge of any kind — a liveness heartbeat. */
+    readonly lastActivityAt?: number;
+}
+/**
+ * Edges from the **current** session lifecycle only: everything from the latest
+ * `session-start` onward. The rendezvous is keyed by conversation id and *reused
+ * across resume*, so a crashed prior life leaves an unclosed `prompt-submit` (and
+ * a stale `session-start`) in the same file. Computing the belief over those
+ * poisons it (the false-`working`-after-resume bug). Resetting at the last
+ * `session-start` boundary is the one fix for that whole family. Edges are sorted
+ * by time, so the last `session-start` in the array is the most recent; with no
+ * `session-start` at all (a bare progress sequence) everything is kept.
+ */
+export declare function currentLifeEdges(edges: readonly HookEdge[]): readonly HookEdge[];
+/**
+ * Fuse the reliable signals + the pre-classified pane into one {@link Belief}.
+ * `state` precedence: pane-only modals (dialog/permission) → hook lifecycle
+ * (when the channel is live and a turn has happened) → pane (hooks silent/off).
+ * The hook-lifecycle branch carries one pane cross-check for its blind spot: a
+ * denied/abandoned tool leaves a dangling `tool-start` (no `tool-end`), so a
+ * settled idle pane overrides a stuck hook `working`. Only {@link currentLifeEdges}
+ * feed the belief, so a resumed session is never judged by its prior life's edges.
+ */
+export declare function believe(o: {
+    edges: readonly HookEdge[];
+    transcriptCount: number;
+    /**
+     * The pre-classified pane. `nonEmpty` (does the captured frame carry any real,
+     * non-whitespace content) feeds the {@link Belief.agentChannelHealthy} drift
+     * canary — we only judge "all channels blind" against a pane that actually has
+     * content. Optional: absent ⇒ treated as empty (no drift judgment).
+     */
+    pane: {
+        state: State;
+        interrupted: boolean;
+        nonEmpty?: boolean;
+    };
+    /**
+     * Authoritative "this handle issued an interrupt not yet superseded by a send."
+     * An interrupt fires NO `stop` edge AND leaves the spinner's `esc to interrupt`
+     * frozen in scrollback (so the pane mis-classifies as `working`) — neither
+     * channel can tell a frozen spinner from a live one. The handle KNOWS, so this
+     * flag overrides both. The pane's "Interrupted" text is only a best-effort
+     * fallback for a *human* interrupt we didn't issue.
+     */
+    weInterrupted?: boolean;
+}): Belief;
+/**
+ * Read the hook rendezvous into ordered {@link HookEdge}s (chronological).
+ * Empty when hooks are off, the agent has no hook spec, or the file is absent
+ * — degrades, never throws. A FULL read: used by `bootSession` (a one-shot, not
+ * a hot path); the per-poll session path is the incremental
+ * {@link import('./session-observer.js').SessionObserver}.
+ */
+export declare function readHookEdges(o: {
+    agent: AgentDef;
+    rendezvousPath: string;
+}): HookEdge[];
+//# sourceMappingURL=observer.d.ts.map

package/dist/observe/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../src/observe/observer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAwBnD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE;IAChC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,QAAQ,CAyCX;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,MAAO,SAAQ,QAAQ;IACtC,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,QAAQ,EAAE,CAMhF;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE;IACzB,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,IAAI,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACjE;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,MAAM,CA6CT;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,EAAE,CAUxF"}

package/dist/observe/observer.js

@@ -0,0 +1,167 @@
+import { readFileSync } from "node:fs";
+/**
+ * The Observer — **agent-agnostic** fusion of the reliable observe signals into
+ * one belief. It knows nothing of any agent's transcript schema or hook
+ * vocabulary: it reads files by path and delegates every agent-specific bit to
+ * {@link AgentDef.transcript} / {@link AgentDef.hooks}, and takes the pane only
+ * as a pre-classified verdict. (grep-enforced: no jsonl/claude vocabulary here.)
+ *
+ * **Single owner of "what's true."** `state()` and `progress()` both defer to
+ * {@link believe}; `wait()` composes that belief with the patience policy. No
+ * caller forms its own belief from raw signals. Fusion precedence: pane-only
+ * modal states (dialog/permission) win (hooks can't see them) → else the hook
+ * lifecycle (the reliable channel) → else the pane (hooks silent/off).
+ */
+function readLines(path) {
+    try {
+        return readFileSync(path, "utf8").split("\n");
+    }
+    catch {
+        return []; // absent/unreadable file → no signal (degrades, never throws)
+    }
+}
+/**
+ * Derive a {@link Progress} from the ordered hook edges + a transcript count.
+ * Pure — the testable heart of the Observer.
+ *
+ * `phase`: `stop` ⇒ `done`; else a tool in flight ⇒ `tool`; else the last edge
+ * being `tool-end` ⇒ `composing`; else ⇒ `prompt`; no edges ⇒ `unknown`.
+ * `toolInFlight`: net-open tools (`tool-start` count minus `tool-end` count).
+ */
+export function deriveProgress(o) {
+    let open = 0;
+    for (const e of o.edges) {
+        if (e.event === "tool-start")
+            open += 1;
+        else if (e.event === "tool-end")
+            open = Math.max(0, open - 1);
+    }
+    const toolInFlight = open > 0;
+    const lifecycle = o.edges.filter((e) => e.event === "prompt-submit" ||
+        e.event === "tool-start" ||
+        e.event === "tool-end" ||
+        e.event === "stop");
+    const last = lifecycle[lifecycle.length - 1];
+    let phase;
+    if (last === undefined)
+        phase = "unknown";
+    else if (last.event === "stop")
+        phase = "done";
+    else if (toolInFlight)
+        phase = "tool";
+    else if (last.event === "tool-end")
+        phase = "composing";
+    else
+        phase = "prompt";
+    const hookChannelHealthy = o.edges.length > 0;
+    // Hook-derived state. The pane fallback (dialog / permission-prompt) is fused
+    // in by the state/wait consolidation; here state reflects only the reliable
+    // hook signal: working unless the turn has ended (or no signal at all).
+    const state = phase === "done" ? "idle" : phase === "unknown" ? "unknown" : "working";
+    // `agentChannelHealthy` is a FUSED (pane-aware) judgment — `believe()` computes
+    // the real value; from hooks/transcript alone there is no drift evidence, so the
+    // base is `true`. (deriveProgress is hook-only; the canary needs the pane.)
+    return {
+        phase,
+        toolInFlight,
+        transcriptCount: o.transcriptCount,
+        hookChannelHealthy,
+        agentChannelHealthy: true,
+        state,
+    };
+}
+/**
+ * Edges from the **current** session lifecycle only: everything from the latest
+ * `session-start` onward. The rendezvous is keyed by conversation id and *reused
+ * across resume*, so a crashed prior life leaves an unclosed `prompt-submit` (and
+ * a stale `session-start`) in the same file. Computing the belief over those
+ * poisons it (the false-`working`-after-resume bug). Resetting at the last
+ * `session-start` boundary is the one fix for that whole family. Edges are sorted
+ * by time, so the last `session-start` in the array is the most recent; with no
+ * `session-start` at all (a bare progress sequence) everything is kept.
+ */
+export function currentLifeEdges(edges) {
+    let lastStart = -1;
+    for (let i = 0; i < edges.length; i++) {
+        if (edges[i]?.event === "session-start")
+            lastStart = i;
+    }
+    return lastStart < 0 ? edges : edges.slice(lastStart);
+}
+/**
+ * Fuse the reliable signals + the pre-classified pane into one {@link Belief}.
+ * `state` precedence: pane-only modals (dialog/permission) → hook lifecycle
+ * (when the channel is live and a turn has happened) → pane (hooks silent/off).
+ * The hook-lifecycle branch carries one pane cross-check for its blind spot: a
+ * denied/abandoned tool leaves a dangling `tool-start` (no `tool-end`), so a
+ * settled idle pane overrides a stuck hook `working`. Only {@link currentLifeEdges}
+ * feed the belief, so a resumed session is never judged by its prior life's edges.
+ */
+export function believe(o) {
+    const edges = currentLifeEdges(o.edges);
+    const prog = deriveProgress({ edges, transcriptCount: o.transcriptCount });
+    // `weInterrupted` is authoritative; else the human-interrupt heuristic: the
+    // pane shows "Interrupted" AND is the post-interrupt draft (`unknown`), not a
+    // working/idle box (a new turn, or a resume replaying old "Interrupted" text).
+    const interrupted = o.weInterrupted === true || (o.pane.interrupted && o.pane.state === "unknown");
+    let state;
+    if (o.pane.state === "dialog" || o.pane.state === "permission-prompt") {
+        state = o.pane.state; // only the pane sees modals — they win
+    }
+    else if (interrupted) {
+        state = "unknown"; // aborted: hook phase is stale, pane is a draft (not idle)
+    }
+    else if (prog.hookChannelHealthy && prog.phase !== "unknown") {
+        // The reliable hook lifecycle (working / idle) — with ONE pane cross-check
+        // for its blind spot. A tool the consumer DENIES (or claude abandons) fires
+        // `tool-start` but never `tool-end`, so the hook phase stays `tool` → working
+        // forever though the turn is over. When the hooks say working but the pane
+        // has settled to a clean idle box, the turn actually ended — trust the pane.
+        // A genuinely in-flight tool never renders the idle box (it shows the
+        // "esc to interrupt" spinner), so this only ever fires on the dangling-tool
+        // case; any transient idle frame is filtered by wait()'s idle stabilization.
+        state = prog.state === "working" && o.pane.state === "idle" ? "idle" : prog.state;
+    }
+    else {
+        state = o.pane.state; // hooks silent (off, or no turn yet) → trust the pane
+    }
+    const lastStop = [...edges].reverse().find((e) => e.event === "stop");
+    const lastEdge = edges[edges.length - 1];
+    // Drift canary: against a non-empty pane, at least ONE channel must extract
+    // signal — a recognized pane state, a known interrupt, hook edges, or a parsed
+    // message. All blind at once ⇒ the agent's output format likely drifted.
+    const recognizedSomething = o.pane.state !== "unknown" ||
+        interrupted ||
+        prog.hookChannelHealthy ||
+        prog.transcriptCount > 0;
+    const agentChannelHealthy = o.pane.nonEmpty !== true || recognizedSomething;
+    return {
+        ...prog,
+        state,
+        interrupted,
+        agentChannelHealthy,
+        ...(lastStop === undefined ? {} : { lastStopAt: lastStop.at }),
+        ...(lastEdge === undefined ? {} : { lastActivityAt: lastEdge.at }),
+    };
+}
+/**
+ * Read the hook rendezvous into ordered {@link HookEdge}s (chronological).
+ * Empty when hooks are off, the agent has no hook spec, or the file is absent
+ * — degrades, never throws. A FULL read: used by `bootSession` (a one-shot, not
+ * a hot path); the per-poll session path is the incremental
+ * {@link import('./session-observer.js').SessionObserver}.
+ */
+export function readHookEdges(o) {
+    const hooks = o.agent.hooks;
+    if (hooks === undefined)
+        return [];
+    const edges = [];
+    for (const line of readLines(o.rendezvousPath)) {
+        const edge = hooks.parseMarker(line);
+        if (edge !== null)
+            edges.push(edge);
+    }
+    edges.sort((a, b) => a.at - b.at);
+    return edges;
+}
+//# sourceMappingURL=observer.js.map

package/dist/observe/observer.js.map

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

package/dist/observe/session-observer.d.ts

@@ -0,0 +1,49 @@
+import type { AgentDef } from "../agents/types.js";
+import type { Message, State } from "../types.js";
+import { type Belief } from "./observer.js";
+/**
+ * The per-session stateful read core — the single owner of "what's true" with
+ * **bounded** reads. It holds incremental {@link TailReader}s over the hook
+ * rendezvous and the transcript, so each `state()`/`progress()`/`wait()` poll
+ * parses only the bytes appended since the last one (O(delta), not O(file)) — the
+ * fix for a long-lived session re-parsing its whole transcript every 150ms (F39).
+ *
+ * It accumulates the parsed edges + messages + ancestry graph across polls, and
+ * resolves the transcript path from the hook's own report (free — it's already
+ * in the edges) before falling back to the agent's locate. One per handle; every
+ * method that reads session state defers to it. (Boot still does a one-shot full
+ * read — it isn't a hot path.)
+ */
+export declare class SessionObserver {
+    #private;
+    constructor(o: {
+        agent: AgentDef;
+        rendezvousPath?: string;
+        agentSessionId?: string;
+    });
+    /**
+     * The one fused {@link Belief}, given the caller's pre-classified pane and the
+     * handle's authoritative interrupt flag. Refreshes both channels first.
+     */
+    belief(pane: {
+        state: State;
+        interrupted: boolean;
+        nonEmpty?: boolean;
+    }, weInterrupted: boolean): Belief;
+    /**
+     * Is the transcript **addressable** — do we hold an `agentSessionId` to locate
+     * it by, or has a hook edge reported its path? This is addressability, NOT file
+     * existence: a fresh session with an id (transcript not flushed yet) is
+     * locatable and reads empty legitimately. `false` means we have NO handle on
+     * where the transcript lives (an adopt-miss, a non-claudemux session, or a fork
+     * before its first hook edge) — reads are blind, and the handle throws
+     * `TranscriptUnlocatable` rather than returning a deceptive empty.
+     */
+    transcriptLocatable(): boolean;
+    /** The accumulated messages + ancestry graph (for `messagesSince`/`turnComplete`). */
+    thread(): {
+        messages: readonly Message[];
+        parentOf: Map<string, string | undefined>;
+    };
+}
+//# sourceMappingURL=session-observer.d.ts.map

package/dist/observe/session-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-observer.d.ts","sourceRoot":"","sources":["../../src/observe/session-observer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAY,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,eAAe,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAe;;gBAYd,CAAC,EAAE;QAAE,KAAK,EAAE,QAAQ,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE;IA0DpF;;;OAGG;IACH,MAAM,CACJ,IAAI,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,EAChE,aAAa,EAAE,OAAO,GACrB,MAAM;IAWT;;;;;;;;OAQG;IACH,mBAAmB,IAAI,OAAO;IAM9B,sFAAsF;IACtF,MAAM,IAAI;QAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;QAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;KAAE;CAKtF"}

package/dist/observe/session-observer.js

@@ -0,0 +1,123 @@
+import { TailReader } from "./incremental.js";
+import { believe } from "./observer.js";
+/**
+ * The per-session stateful read core — the single owner of "what's true" with
+ * **bounded** reads. It holds incremental {@link TailReader}s over the hook
+ * rendezvous and the transcript, so each `state()`/`progress()`/`wait()` poll
+ * parses only the bytes appended since the last one (O(delta), not O(file)) — the
+ * fix for a long-lived session re-parsing its whole transcript every 150ms (F39).
+ *
+ * It accumulates the parsed edges + messages + ancestry graph across polls, and
+ * resolves the transcript path from the hook's own report (free — it's already
+ * in the edges) before falling back to the agent's locate. One per handle; every
+ * method that reads session state defers to it. (Boot still does a one-shot full
+ * read — it isn't a hot path.)
+ */
+export class SessionObserver {
+    #agent;
+    #rendezvousPath;
+    #agentSessionId;
+    #rvReader = new TailReader();
+    #txReader = new TailReader();
+    #edges = [];
+    #messages = [];
+    #parentOf = new Map();
+    #txPath; // memoized once resolved
+    constructor(o) {
+        this.#agent = o.agent;
+        this.#rendezvousPath = o.rendezvousPath;
+        this.#agentSessionId = o.agentSessionId;
+    }
+    /** Incrementally fold new rendezvous lines into the cached edges. */
+    #refreshEdges() {
+        const path = this.#rendezvousPath;
+        const hooks = this.#agent.hooks;
+        if (path === undefined || hooks === undefined)
+            return;
+        const { reset, lines } = this.#rvReader.poll(path);
+        if (reset)
+            this.#edges = [];
+        for (const line of lines) {
+            const edge = hooks.parseMarker(line);
+            if (edge !== null)
+                this.#edges.push(edge);
+        }
+    }
+    /**
+     * The transcript path: the hook-reported one (from the edges we already hold —
+     * authoritative, no extra read) preferred over the agent's fragile locate.
+     * Memoized once non-undefined (it is stable for a session's lifetime).
+     */
+    #resolveTxPath() {
+        if (this.#txPath !== undefined)
+            return this.#txPath;
+        for (let i = this.#edges.length - 1; i >= 0; i--) {
+            const p = this.#edges[i]?.transcriptPath;
+            if (p !== undefined) {
+                this.#txPath = p;
+                return p;
+            }
+        }
+        const transcript = this.#agent.transcript;
+        if (transcript !== undefined && this.#agentSessionId !== undefined) {
+            this.#txPath = transcript.locate({ agentSessionId: this.#agentSessionId }) ?? undefined;
+        }
+        return this.#txPath;
+    }
+    /** Incrementally fold new transcript lines into the cached messages + graph. */
+    #refreshTranscript() {
+        const transcript = this.#agent.transcript;
+        const path = this.#resolveTxPath();
+        if (path === undefined || transcript === undefined)
+            return;
+        const { reset, lines } = this.#txReader.poll(path);
+        if (reset) {
+            this.#messages = [];
+            this.#parentOf = new Map();
+        }
+        for (const line of lines) {
+            const m = transcript.parseLine(line);
+            if (m !== null)
+                this.#messages.push(m);
+            const e = transcript.parseEdge?.(line);
+            if (e !== null && e !== undefined)
+                this.#parentOf.set(e.id, e.parentId);
+        }
+    }
+    /**
+     * The one fused {@link Belief}, given the caller's pre-classified pane and the
+     * handle's authoritative interrupt flag. Refreshes both channels first.
+     */
+    belief(pane, weInterrupted) {
+        this.#refreshEdges();
+        this.#refreshTranscript();
+        return believe({
+            edges: this.#edges,
+            transcriptCount: this.#messages.length,
+            pane,
+            weInterrupted,
+        });
+    }
+    /**
+     * Is the transcript **addressable** — do we hold an `agentSessionId` to locate
+     * it by, or has a hook edge reported its path? This is addressability, NOT file
+     * existence: a fresh session with an id (transcript not flushed yet) is
+     * locatable and reads empty legitimately. `false` means we have NO handle on
+     * where the transcript lives (an adopt-miss, a non-claudemux session, or a fork
+     * before its first hook edge) — reads are blind, and the handle throws
+     * `TranscriptUnlocatable` rather than returning a deceptive empty.
+     */
+    transcriptLocatable() {
+        if (this.#agentSessionId !== undefined)
+            return true;
+        this.#refreshEdges();
+        return this.#edges.some((e) => e.transcriptPath !== undefined);
+    }
+    /** The accumulated messages + ancestry graph (for `messagesSince`/`turnComplete`). */
+    thread() {
+        this.#refreshEdges(); // so the hook transcript-path is preferred on a first read
+        this.#refreshTranscript();
+        return { messages: this.#messages, parentOf: this.#parentOf };
+    }
+}
+//# sourceMappingURL=session-observer.js.map

package/dist/observe/session-observer.js.map

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

package/dist/session/adopt.d.ts

@@ -0,0 +1,52 @@
+import type { AgentDef } from "../agents/types.js";
+import type { Backend } from "../backends/types.js";
+import type { SessionHandle } from "../types.js";
+/**
+ * Options for {@link adopt}. Mirrors {@link CreateOptions} minus the spawn-only
+ * fields (`cwd`, `extraArgs`, `env`, `bootTimeoutMs`, `trustWorkspace`) — adopt
+ * neither spawns nor boots.
+ */
+export interface AdoptOptions {
+    /** Name of the session to re-adopt; must match the live session's name. */
+    name: string;
+    /** Namespace prefix (default: `"claudemux"`). Must match the live session's namespace. */
+    namespace?: string;
+    /**
+     * Agent definition controlling state/idle classification (default: claude).
+     * MUST be the same agent the original `create()` used — the classifier reads
+     * THIS agent's `rules`, not the session's. Passing the wrong agent silently
+     * misclassifies `state()`/`wait()`. See README §adopt.
+     */
+    agent?: AgentDef;
+    /** Backend the live session runs in (default: the process-wide shared default — stable socket). */
+    backend?: Backend;
+}
+/**
+ * Re-adopt a session that is already live but was created by another process —
+ * the mirror of {@link create}. Pure attach: no spawn, no boot, no dialog dismissal.
+ *
+ * After a successful adopt the consumer MUST call `state()` before driving the
+ * pane (covers wedged / mid-dialog). See README §adopt for the A/B/C recovery
+ * taxonomy and the single-writer invariant.
+ *
+ * @throws `InvalidSessionName` if `name`/`namespace` contain reserved characters
+ *   (thrown before the exists-check).
+ * @throws `SessionGone` if no such session exists — incl. the whole backend
+ *   server being down, which `exists()` reports as absence.
+ *
+ * @example
+ * ```ts
+ * import { adopt, SessionGone } from "claudemux";
+ * try {
+ *   const session = await adopt({ name: "job" });
+ *   await session.state(); // ALWAYS call state() before driving the pane
+ * } catch (err) {
+ *   if (err instanceof SessionGone) {
+ *     // the pane is gone — continue the conversation in a fresh one:
+ *     // await resume({ name: "job-2", cwd, agentSessionId });
+ *   }
+ * }
+ * ```
+ */
+export declare function adopt(opts: AdoptOptions): Promise<SessionHandle>;
+//# sourceMappingURL=adopt.d.ts.map

package/dist/session/adopt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.d.ts","sourceRoot":"","sources":["../../src/session/adopt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMjD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,mGAAmG;IACnG,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CA0BtE"}

package/dist/session/adopt.js

@@ -0,0 +1,57 @@
+import { SessionGone } from "../errors.js";
+import { AGENT_SESSION_ID_META_KEY } from "./constants.js";
+import { attachHandle } from "./handle.js";
+import { formatSessionLabel } from "./ref.js";
+import { resolveSessionContext } from "./resolve.js";
+/**
+ * Re-adopt a session that is already live but was created by another process —
+ * the mirror of {@link create}. Pure attach: no spawn, no boot, no dialog dismissal.
+ *
+ * After a successful adopt the consumer MUST call `state()` before driving the
+ * pane (covers wedged / mid-dialog). See README §adopt for the A/B/C recovery
+ * taxonomy and the single-writer invariant.
+ *
+ * @throws `InvalidSessionName` if `name`/`namespace` contain reserved characters
+ *   (thrown before the exists-check).
+ * @throws `SessionGone` if no such session exists — incl. the whole backend
+ *   server being down, which `exists()` reports as absence.
+ *
+ * @example
+ * ```ts
+ * import { adopt, SessionGone } from "claudemux";
+ * try {
+ *   const session = await adopt({ name: "job" });
+ *   await session.state(); // ALWAYS call state() before driving the pane
+ * } catch (err) {
+ *   if (err instanceof SessionGone) {
+ *     // the pane is gone — continue the conversation in a fresh one:
+ *     // await resume({ name: "job-2", cwd, agentSessionId });
+ *   }
+ * }
+ * ```
+ */
+export async function adopt(opts) {
+    const { ref, agent, backend } = resolveSessionContext(opts);
+    // Mirror of create()'s exists-check, inverted. adopt REQUIRES the session to
+    // be present; absence (including whole-server-down, which exists() collapses
+    // to false) is SessionGone — the symmetric counterpart to SessionExists.
+    if (!(await backend.exists(ref))) {
+        throw new SessionGone(formatSessionLabel(ref));
+    }
+    // Best-effort: recover the agent's conversation id from the session-meta the
+    // creating process cached. `undefined` on a miss (older/non-claudemux session,
+    // a creator that never wrote it, or a store read failure) — adopt never
+    // fabricates an id, it tells the truth and lets the consumer fall back to its
+    // own store. getSessionMeta already collapses "unreadable" to `undefined`.
+    const agentSessionId = await backend.getSessionMeta(ref, AGENT_SESSION_ID_META_KEY);
+    // Pure attach — no spawn, no boot, no dialog dismissal. The consumer MUST call
+    // state() after adopt to learn where the live pane stands.
+    return attachHandle({
+        backend,
+        agent,
+        namespace: ref.namespace,
+        name: ref.name,
+        ...(agentSessionId === undefined ? {} : { agentSessionId }),
+    });
+}
+//# sourceMappingURL=adopt.js.map

package/dist/session/adopt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.js","sourceRoot":"","sources":["../../src/session/adopt.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAuBrD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAkB;IAC5C,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAE5D,6EAA6E;IAC7E,6EAA6E;IAC7E,yEAAyE;IACzE,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,WAAW,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,6EAA6E;IAC7E,+EAA+E;IAC/E,wEAAwE;IACxE,8EAA8E;IAC9E,2EAA2E;IAC3E,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC;IAEpF,+EAA+E;IAC/E,2DAA2D;IAC3D,OAAO,YAAY,CAAC;QAClB,OAAO;QACP,KAAK;QACL,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC;KAC5D,CAAC,CAAC;AACL,CAAC"}

package/dist/session/boot.d.ts

@@ -0,0 +1,66 @@
+import type { AgentDef } from "../agents/types.js";
+import type { Backend, SessionRef } from "../backends/types.js";
+/** Boot options threaded from `create`. */
+export interface BootOptions {
+    /** Total boot budget (default 60s). */
+    timeoutMs?: number;
+    /**
+     * Opt in to auto-dismissing the agent's workspace-trust dialog. Default
+     * **false** — trusting a folder is an authority grant the substrate does
+     * not make for the caller. Without it, an untrusted-cwd trust dialog
+     * throws `WorkspaceUntrusted` before any keystroke is sent. See that
+     * error's TSDoc for the persistent/global-trust caveats.
+     */
+    trustWorkspace?: boolean;
+    /** The cwd being booted into — carried on `WorkspaceUntrusted` for the caller. */
+    cwd?: string;
+    /**
+     * The caller-chosen `agentSessionId` for this spawn, if any. Carried onto
+     * {@link AgentExitedDuringBoot} when the agent exits before ready, so the
+     * (overwhelmingly likely) collision case stays actionable. Omitted for a
+     * minted id — a v4 mint collides with ~zero probability, so attributing a
+     * minted-id boot-death to "id in use" would mislead.
+     */
+    agentSessionId?: string;
+    /**
+     * Path to the session's hook rendezvous file, when hooks were injected
+     * (default-on). When set, boot **gates** readiness on the agent's
+     * `SessionStart` hook edge appearing here: a ready-looking pane alone never
+     * declares ready until the edge fires. Verified against claude 2.1.162:
+     * `SessionStart` fires only *after* any boot dialog is dismissed, once input
+     * is interactive — so an edge can never signal ready while a dialog is up.
+     * After the edge, boot still waits for a *stable* `isReady` pane (the first
+     * send otherwise races the welcome/MCP render storm and is lost). Omitted
+     * under `create({ hooks: false })`, where the pane is the only ready signal.
+     */
+    rendezvousPath?: string;
+}
+/**
+ * Boot the session: dismiss any matching dialogs in order, then wait for ready.
+ *
+ * **Ready signal:** a hook *gate* plus a pane *settle*.
+ *   1. **`session-start` hook edge — the authoritative "started" gate.** With
+ *      hooks on (the default, `opts.rendezvousPath` set), boot will not declare
+ *      ready until this edge fires — a ready-*looking* pane is NOT trusted on
+ *      its own (the founder's "hooks, not screen-scraping" north star). The edge
+ *      lands only once input is interactive and post-dialog. With hooks off
+ *      there is no edge, so the pane is the only signal.
+ *   2. **Stable ready box — the delivery-safety settle.** Even after "started,"
+ *      a fresh REPL is still painting its welcome/MCP render, and the *first*
+ *      send pasted into that render storm is silently lost (verified). So boot
+ *      returns only once the ready box has held *stable*, guaranteeing the input
+ *      is paintable. Dialogs are handled before either check each iteration.
+ *
+ * Throws on the documented failures.
+ *
+ * @throws `WorkspaceUntrusted` if the workspace-trust dialog fires and
+ *   `trustWorkspace` was not set — thrown *before* any keystroke, so no
+ *   persistent trust flag is written.
+ * @throws `LoginRequired` if the login-method dialog fires.
+ * @throws `DialogStuck` if a recognized dialog persists after its response.
+ * @throws `AgentExitedDuringBoot` if the agent process exits (its session is
+ *   reaped) before becoming ready — most often an `agentSessionId` collision.
+ * @throws `ReplTimeout` if the total budget elapses before a stable ready.
+ */
+export declare function bootSession(backend: Backend, agent: AgentDef, ref: SessionRef, opts?: BootOptions): Promise<void>;
+//# sourceMappingURL=boot.d.ts.map

package/dist/session/boot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../src/session/boot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AA6ChE,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,QAAQ,EACf,GAAG,EAAE,UAAU,EACf,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,IAAI,CAAC,CAmEf"}