@wastedcode/claudemux 0.2.0

package/dist/session/handle.d.ts

@@ -0,0 +1,63 @@
+import type { AgentDef } from "../agents/types.js";
+import type { Backend } from "../backends/types.js";
+import type { SessionHandle } from "../types.js";
+/**
+ * The {@link Cursor} {@link SessionHandle.send} returns when it could **not
+ * confirm delivery** — no user record for the sent text appeared (a lost Enter,
+ * a boot-race drop). It is a detectable sentinel, NOT a positional count: a count
+ * cursor persisted and reused later would silently slice the WHOLE transcript
+ * ("everything since index 0"). `messagesSince`/`turnComplete` on this sentinel
+ * read empty/false, so an unconfirmed turn surfaces as "re-send me", never a
+ * flood. Consumers can compare `cursor === DELIVERY_UNCONFIRMED`.
+ */
+export declare const DELIVERY_UNCONFIRMED = "delivery-unconfirmed";
+/**
+ * The {@link Cursor} {@link SessionHandle.send} returns when the message was sent
+ * into a **busy** session and the agent **queued** it — accepted, and it will run
+ * after the in-flight turn finishes (claude shows "Press up to edit queued
+ * messages"). Distinct from {@link DELIVERY_UNCONFIRMED} on purpose: the message
+ * is NOT lost, so a consumer must **not** re-send (that would double-run). Its
+ * user record does not exist yet (the queued turn hasn't started), so like
+ * `DELIVERY_UNCONFIRMED` it resolves empty in `messagesSince`/`turnComplete` —
+ * the consumer `wait()`s for the current turn, lets the queued turn run, then
+ * reads with a fresh cursor. Compare `cursor === DELIVERED_QUEUED`.
+ */
+export declare const DELIVERED_QUEUED = "delivered-queued";
+interface HandleDeps {
+    backend: Backend;
+    agent: AgentDef;
+    namespace: string;
+    name: string;
+    /**
+     * The agent's conversation id, when known — surfaced as
+     * {@link SessionHandle.agentSessionId}. `undefined` for sessions with no
+     * recoverable id (older/non-claudemux, a cache-miss at adopt, or a bare
+     * `--resume`); never fabricated.
+     */
+    agentSessionId?: string;
+    /**
+     * The hook rendezvous file injected at spawn (for the observe channel). When
+     * absent (e.g. {@link attachHandle}/adopt), the handle re-derives it from
+     * {@link agentSessionId} — correct for the common (non-resume) case.
+     */
+    rendezvousPath?: string;
+}
+/**
+ * Build a {@link SessionHandle} backed by a per-handle mutex. Every public
+ * method that mutates or reads pane state goes through the mutex so
+ * concurrent consumer calls cannot interleave bytes.
+ */
+export declare function makeHandle(deps: HandleDeps): SessionHandle;
+/**
+ * Build a {@link SessionHandle} that points at an existing session, without
+ * spawning or booting — the "attach to a live session" seam.
+ *
+ * Two public consumers: the stateless CLI reattaches through this on every
+ * invocation, and the public `adopt()` primitive is built directly on it —
+ * `adopt()` asserts the session EXISTS, then calls `attachHandle` (the
+ * exists-asserting mirror of `create()`'s SessionExists guard). `create()`
+ * remains the only path that *boots*; `attachHandle` is pure attach.
+ */
+export declare function attachHandle(deps: HandleDeps): SessionHandle;
+export {};
+//# sourceMappingURL=handle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../../src/session/handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAc,MAAM,sBAAsB,CAAC;AAUhE,OAAO,KAAK,EAMV,aAAa,EAEd,MAAM,aAAa,CAAC;AAOrB;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD,UAAU,UAAU;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,CAoJ1D;AA8GD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,CAE5D"}

package/dist/session/handle.js

@@ -0,0 +1,284 @@
+import { PromptResponseUnsupported, TranscriptUnlocatable } from "../errors.js";
+import { interruptOnce } from "../io/interrupt.js";
+import { respondOnce } from "../io/respond.js";
+import { sendOnce, submitOnce } from "../io/send.js";
+import { stabilize } from "../io/stabilize.js";
+import { waitForOutcome } from "../io/wait.js";
+import { SessionObserver } from "../observe/session-observer.js";
+import { classify } from "../state/classifier.js";
+import { stripSgr } from "../util/ansi.js";
+import { sleep } from "../util/sleep.js";
+import { CLASSIFIER_CAPTURE } from "./constants.js";
+import { rendezvousPathFor } from "./hooks.js";
+import { Mutex } from "./mutex.js";
+/**
+ * The {@link Cursor} {@link SessionHandle.send} returns when it could **not
+ * confirm delivery** — no user record for the sent text appeared (a lost Enter,
+ * a boot-race drop). It is a detectable sentinel, NOT a positional count: a count
+ * cursor persisted and reused later would silently slice the WHOLE transcript
+ * ("everything since index 0"). `messagesSince`/`turnComplete` on this sentinel
+ * read empty/false, so an unconfirmed turn surfaces as "re-send me", never a
+ * flood. Consumers can compare `cursor === DELIVERY_UNCONFIRMED`.
+ */
+export const DELIVERY_UNCONFIRMED = "delivery-unconfirmed";
+/**
+ * The {@link Cursor} {@link SessionHandle.send} returns when the message was sent
+ * into a **busy** session and the agent **queued** it — accepted, and it will run
+ * after the in-flight turn finishes (claude shows "Press up to edit queued
+ * messages"). Distinct from {@link DELIVERY_UNCONFIRMED} on purpose: the message
+ * is NOT lost, so a consumer must **not** re-send (that would double-run). Its
+ * user record does not exist yet (the queued turn hasn't started), so like
+ * `DELIVERY_UNCONFIRMED` it resolves empty in `messagesSince`/`turnComplete` —
+ * the consumer `wait()`s for the current turn, lets the queued turn run, then
+ * reads with a fresh cursor. Compare `cursor === DELIVERED_QUEUED`.
+ */
+export const DELIVERED_QUEUED = "delivered-queued";
+/**
+ * Build a {@link SessionHandle} backed by a per-handle mutex. Every public
+ * method that mutates or reads pane state goes through the mutex so
+ * concurrent consumer calls cannot interleave bytes.
+ */
+export function makeHandle(deps) {
+    const ref = { namespace: deps.namespace, name: deps.name };
+    const mutex = new Mutex();
+    // Authoritative session-interaction state: 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 neither
+    // the hook nor the pane can tell aborted from working — but the handle knows.
+    let interruptPending = false;
+    // The per-handle stateful read core: incremental (bounded) reads of the hook
+    // rendezvous + transcript. state()/progress()/wait()/messagesSince all defer to
+    // it — one owner of "what's true", parsing only newly-appended bytes per poll.
+    const rv = rendezvousPath(deps);
+    const observer = new SessionObserver({
+        agent: deps.agent,
+        ...(rv === undefined ? {} : { rendezvousPath: rv }),
+        ...(deps.agentSessionId === undefined ? {} : { agentSessionId: deps.agentSessionId }),
+    });
+    /**
+     * Capture + classify the pane, fuse with the observer's belief. The capture
+     * failure is NOT swallowed: in tmux a failed capture means the session/server
+     * is gone (terminal), so `SessionGone`/`BackendUnreachable` propagates.
+     */
+    const readBelief = async (weInterrupted) => {
+        const paneText = await deps.backend.capture(ref, CLASSIFIER_CAPTURE);
+        const pane = {
+            state: classify(paneText, deps.agent.rules),
+            interrupted: deps.agent.rules.interrupted?.(paneText) ?? false,
+            // Real, non-whitespace content (SGR stripped) — gates the drift canary so a
+            // blank/gone pane is never judged as "all channels blind."
+            nonEmpty: stripSgr(paneText).trim().length > 0,
+        };
+        return { belief: observer.belief(pane, weInterrupted), paneText };
+    };
+    return {
+        name: deps.name,
+        namespace: deps.namespace,
+        ...(deps.agentSessionId === undefined ? {} : { agentSessionId: deps.agentSessionId }),
+        send: (text) => mutex.run(async () => {
+            interruptPending = false; // a new turn supersedes any pending interrupt
+            const beforeIds = new Set(observer.thread().messages.map((m) => m.id));
+            await sendOnce(deps.backend, deps.agent, ref, text);
+            // Anchor the cursor on OUR OWN user record, not a positional count.
+            // A count read here is wrong: the PRIOR turn's reply may not have flushed
+            // yet (the transcript trails the done signal by ~100ms), and a human may
+            // type an interleaved turn. Anchoring on the record this send produced is
+            // immune to both. Fall back to the sentinel only if it never appears.
+            const ownId = await anchorOwnTurn(observer, beforeIds, text);
+            if (ownId !== undefined)
+                return ownId;
+            // No user record appeared. A turn sent into a BUSY session is QUEUED by
+            // the agent (accepted, runs next — do NOT re-send); report that distinctly
+            // so the consumer doesn't double-run. The agent owns the "queued" pane
+            // vocabulary; we just ask it.
+            const pane = await deps.backend.capture(ref, CLASSIFIER_CAPTURE);
+            if (deps.agent.rules.queued?.(pane))
+                return DELIVERED_QUEUED;
+            // Lost-submit recovery — but ONLY when the pane looks like an un-submitted
+            // DRAFT: it classifies `unknown` (a `❯ <text>` composer that is neither the
+            // empty idle box nor the working spinner). That is the lost-Enter signature
+            // — the paste reached the composer but the Enter didn't register. In that
+            // one case re-fire Enter ONCE (submitOnce never re-pastes, so it cannot
+            // duplicate the body) and re-anchor; the needle-match keeps it honest
+            // (confirms a NEW record matching OUR text, never a stray draft).
+            //
+            // If the pane is `working`/`idle` instead, the submit already TOOK (or
+            // there is nothing in the composer) and we merely couldn't anchor the
+            // record — e.g. an adopted session whose transcript isn't locatable. Firing
+            // a stray Enter there would inject a spurious empty turn, so we don't: the
+            // honest answer is DELIVERY_UNCONFIRMED.
+            if (classify(pane, deps.agent.rules) === "unknown") {
+                await submitOnce(deps.backend, ref);
+                const recovered = await anchorOwnTurn(observer, beforeIds, text, RETRY_ANCHOR_POLLS);
+                if (recovered !== undefined)
+                    return recovered;
+            }
+            return DELIVERY_UNCONFIRMED;
+        }),
+        messagesSince: (cursor) => mutex.run(async () => {
+            if (!observer.transcriptLocatable())
+                throw new TranscriptUnlocatable(deps.name);
+            return messagesSince(observer, cursor);
+        }),
+        turnComplete: (cursor) => mutex.run(async () => {
+            if (!observer.transcriptLocatable())
+                throw new TranscriptUnlocatable(deps.name);
+            return messagesSince(observer, cursor).some((m) => m.role === "assistant");
+        }),
+        progress: () => mutex.run(async () => {
+            const { belief } = await readBelief(interruptPending);
+            // Project to the public Progress; the extra belief fields (interrupted /
+            // edge timings) are wait()'s concern, not progress()'s.
+            const { phase, toolInFlight, transcriptCount, hookChannelHealthy, agentChannelHealthy, state, } = belief;
+            return {
+                phase,
+                toolInFlight,
+                transcriptCount,
+                hookChannelHealthy,
+                agentChannelHealthy,
+                state,
+            };
+        }),
+        respond: (choice) => mutex.run(async () => {
+            // Compose two sub-owners; own neither's internals. The AGENT owns the
+            // menu option-order (choice→key) — no mapping ⇒ refuse rather than guess
+            // a key (a wrong guess could pick "allow all"). The OBSERVER owns "is a
+            // prompt still showing" — injected as the confirm predicate. The io
+            // primitive owns delivery + settle.
+            const key = deps.agent.permissionPrompt?.respondKey(choice);
+            if (key === undefined)
+                throw new PromptResponseUnsupported(deps.name, deps.agent.name);
+            await respondOnce(deps.backend, ref, key, async () => (await readBelief(false)).belief.state === "permission-prompt");
+        }),
+        interrupt: () => mutex.run(async () => {
+            interruptPending = true; // authoritative: we aborted; no `stop` will come
+            await interruptOnce(deps.backend, ref);
+        }),
+        wait: (opts) => mutex.run(() => {
+            // We issued an interrupt and haven't sent since — there is no turn to
+            // wait for; report the abort rather than poll a frozen spinner to budget.
+            if (interruptPending)
+                return Promise.resolve({ kind: "aborted" });
+            return waitForOutcome(deps.backend, ref, opts ?? {}, { stabilize }, () => readBelief(false));
+        }),
+        state: () => mutex.run(async () => (await readBelief(interruptPending)).belief.state),
+        capture: (opts) => mutex.run(() => deps.backend.capture(ref, opts)),
+        kill: () => mutex.run(() => deps.backend.kill(ref)),
+        onBackendCommand: (handler) => deps.backend.onCommand(handler),
+    };
+}
+/** The hook rendezvous file: the one injected at spawn, else re-derived from the id. */
+function rendezvousPath(deps) {
+    if (deps.rendezvousPath !== undefined)
+        return deps.rendezvousPath;
+    return deps.agentSessionId === undefined ? undefined : rendezvousPathFor(deps.agentSessionId);
+}
+/**
+ * The messages produced since `cursor` — the shared body of `messagesSince` and
+ * `turnComplete`, read from the observer's incremental transcript cache. Causal
+ * chain when the cursor is a real message id; clean positional slice for a legacy
+ * numeric cursor; EMPTY for an unresolvable cursor (sentinel/garbage) — never the
+ * whole transcript (F40).
+ */
+function messagesSince(observer, cursor) {
+    const { messages: all, parentOf } = observer.thread();
+    if (all.some((m) => m.id === cursor))
+        return descendantsOf(all, parentOf, cursor);
+    const n = Number.parseInt(cursor, 10);
+    return Number.isFinite(n) && n >= 0 && String(n) === cursor.trim() ? all.slice(n) : [];
+}
+/**
+ * Messages causally after `ancestorId` — those whose parent chain passes through
+ * it — in file order. Uses the thread links, not file position, so the prior
+ * turn's late-flushing reply (which descends from an EARLIER user record) is
+ * excluded even if it lands after our record in the append-only file. Records
+ * with no parent chain (e.g. an agent that omits `parentId`) fall back to a
+ * positional slice so a thread-less transcript still works.
+ *
+ * **Compaction-safe.** Verified empirically on claude 2.1.162: a compaction
+ * (`/compact` or auto) summarizes the *context window* but leaves the on-disk
+ * transcript append-only with an UNBROKEN linear `parentUuid` chain, so a
+ * post-compaction turn still descends from a pre-compaction cursor — no special
+ * handling needed for the observed case. As defense-in-depth against a future
+ * record-format change (or a partial flush) that *did* drop an intermediate
+ * record, a message whose chain hits a MISSING parent (orphaned, not a clean
+ * root) and that sits positionally after the cursor is still included — we can't
+ * prove causality through a hole, so we fall back to position. This cannot
+ * re-include the late-flush prior reply: its parent record IS present (it roots
+ * cleanly at an earlier turn), so it's never an orphan. (F43/F25.)
+ */
+function descendantsOf(all, fullParentOf, ancestorId) {
+    // Prefer the FULL ancestry graph (every record, incl. the non-message ones an
+    // agent threads between a prompt and its reply). Without it — an agent with no
+    // `parseEdge` — fall back to links between surfaced messages only.
+    const parentOf = fullParentOf.size > 0 ? fullParentOf : new Map(all.map((m) => [m.id, m.parentId]));
+    const hasLinks = [...parentOf.values()].some((p) => p !== undefined);
+    const anchorIdx = all.findIndex((m) => m.id === ancestorId);
+    if (!hasLinks)
+        return anchorIdx >= 0 ? all.slice(anchorIdx + 1) : all.slice();
+    // Classify a message's lineage relative to the cursor by walking its parent
+    // chain: reaches the cursor → `descends`; hits a referenced-but-absent parent
+    // → `orphan` (a hole, e.g. a dropped record); reaches a clean root (no parent)
+    // → `rooted` (a different lineage — an earlier turn).
+    const lineage = (id) => {
+        const seen = new Set();
+        let cur = parentOf.get(id);
+        while (cur !== undefined) {
+            if (cur === ancestorId)
+                return "descends";
+            if (seen.has(cur))
+                return "rooted"; // cycle guard
+            seen.add(cur);
+            if (!parentOf.has(cur))
+                return "orphan"; // parent referenced but its record is gone
+            cur = parentOf.get(cur);
+        }
+        return "rooted";
+    };
+    return all.filter((m, i) => {
+        const l = lineage(m.id);
+        return l === "descends" || (l === "orphan" && anchorIdx >= 0 && i > anchorIdx);
+    });
+}
+const ANCHOR_POLLS = 12;
+// The post-recovery re-anchor is shorter: a lost-Enter record appears within a
+// poll or two of the retry Enter, so a true non-delivery still reports promptly
+// rather than paying a second full anchor window.
+const RETRY_ANCHOR_POLLS = 8;
+const ANCHOR_POLL_MS = 250;
+/** Collapse whitespace so a reflowed/echoed prompt still matches. */
+const squash = (s) => s.replace(/\s+/g, " ").trim();
+/**
+ * The id of the user record THIS send produced — a NEW (not pre-existing) user
+ * message whose text matches what we sent. Polled because the record flushes
+ * shortly after delivery; `undefined` if it never appears (a delivery problem).
+ */
+async function anchorOwnTurn(observer, beforeIds, text, polls = ANCHOR_POLLS) {
+    const needle = squash(text).slice(0, 80); // prefix tolerates echo reflow / truncation
+    for (let attempt = 0; attempt < polls; attempt++) {
+        const msgs = observer.thread().messages;
+        for (let i = msgs.length - 1; i >= 0; i--) {
+            const m = msgs[i];
+            if (m === undefined || m.role !== "user" || beforeIds.has(m.id))
+                continue;
+            if (m.parts.some((p) => p.kind === "text" && squash(p.text).includes(needle)))
+                return m.id;
+        }
+        await sleep(ANCHOR_POLL_MS);
+    }
+    return undefined;
+}
+/**
+ * Build a {@link SessionHandle} that points at an existing session, without
+ * spawning or booting — the "attach to a live session" seam.
+ *
+ * Two public consumers: the stateless CLI reattaches through this on every
+ * invocation, and the public `adopt()` primitive is built directly on it —
+ * `adopt()` asserts the session EXISTS, then calls `attachHandle` (the
+ * exists-asserting mirror of `create()`'s SessionExists guard). `create()`
+ * remains the only path that *boots*; `attachHandle` is pure attach.
+ */
+export function attachHandle(deps) {
+    return makeHandle(deps);
+}
+//# sourceMappingURL=handle.js.map

package/dist/session/handle.js.map

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

package/dist/session/hooks.d.ts

@@ -0,0 +1,37 @@
+import type { AgentDef } from "../agents/types.js";
+/**
+ * Hook injection for the observe side. claudemux observes a session reliably
+ * via agent **hooks** (deterministic, harness-fired) + the transcript — never
+ * by scraping the TUI. On spawn we inject the agent's hook settings (default
+ * on) so the agent appends turn-lifecycle markers to a claudemux-owned local
+ * rendezvous file; the Observer reads them as phase edges.
+ *
+ * This module owns the claudemux-side mechanism (where the rendezvous lives,
+ * whether to inject); the agent owns the hook *vocabulary* (which events, the
+ * settings shape) behind {@link AgentDef.hooks}. No agent flag strings here.
+ */
+/**
+ * The claudemux-owned local rendezvous file for a session's hook turn-markers.
+ * Local, absolute, no network (honors the trust posture). `.ndjson` (not the
+ * agent's `.jsonl` transcript) keeps the two stores distinct.
+ */
+export declare function rendezvousPathFor(sessionId: string): string;
+/**
+ * Compute the hook injection for a spawn.
+ *
+ * @returns `args` — extra argv to prepend so the agent emits turn markers to
+ *   `rendezvousPath` (the Observer reads it). Both empty/absent when hooks are
+ *   disabled, the agent has none, or the consumer already supplied the agent's
+ *   hook flag (we don't double-inject — deep-merging the consumer's settings
+ *   with ours is a hardening follow-up).
+ */
+export declare function buildHookInjection(o: {
+    agent: AgentDef;
+    sessionId: string;
+    enabled: boolean;
+    userExtraArgs: readonly string[];
+}): {
+    args: string[];
+    rendezvousPath?: string;
+};
+//# sourceMappingURL=hooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/session/hooks.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;GAUG;AAEH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE;IACpC,KAAK,EAAE,QAAQ,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAO9C"}

package/dist/session/hooks.js

@@ -0,0 +1,42 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Hook injection for the observe side. claudemux observes a session reliably
+ * via agent **hooks** (deterministic, harness-fired) + the transcript — never
+ * by scraping the TUI. On spawn we inject the agent's hook settings (default
+ * on) so the agent appends turn-lifecycle markers to a claudemux-owned local
+ * rendezvous file; the Observer reads them as phase edges.
+ *
+ * This module owns the claudemux-side mechanism (where the rendezvous lives,
+ * whether to inject); the agent owns the hook *vocabulary* (which events, the
+ * settings shape) behind {@link AgentDef.hooks}. No agent flag strings here.
+ */
+/**
+ * The claudemux-owned local rendezvous file for a session's hook turn-markers.
+ * Local, absolute, no network (honors the trust posture). `.ndjson` (not the
+ * agent's `.jsonl` transcript) keeps the two stores distinct.
+ */
+export function rendezvousPathFor(sessionId) {
+    const stateDir = process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+    return join(stateDir, "claudemux", "turns", `${sessionId}.ndjson`);
+}
+/**
+ * Compute the hook injection for a spawn.
+ *
+ * @returns `args` — extra argv to prepend so the agent emits turn markers to
+ *   `rendezvousPath` (the Observer reads it). Both empty/absent when hooks are
+ *   disabled, the agent has none, or the consumer already supplied the agent's
+ *   hook flag (we don't double-inject — deep-merging the consumer's settings
+ *   with ours is a hardening follow-up).
+ */
+export function buildHookInjection(o) {
+    if (!o.enabled || o.agent.hooks === undefined)
+        return { args: [] };
+    const rendezvousPath = rendezvousPathFor(o.sessionId);
+    const spec = o.agent.hooks.spec({ rendezvousPath });
+    const alreadySet = o.userExtraArgs.some((a) => a === spec.flag || a.startsWith(`${spec.flag}=`));
+    if (alreadySet)
+        return { args: [] };
+    return { args: [spec.flag, spec.value], rendezvousPath };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/session/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/session/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC;;;;;;;;;;GAUG;AAEH;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAClF,OAAO,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,SAAS,SAAS,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAKlC;IACC,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IACnE,MAAM,cAAc,GAAG,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IACjG,IAAI,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IACpC,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;AAC3D,CAAC"}

package/dist/session/mutex.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tiny async mutex. Wraps an async task so calls serialize per-instance.
+ *
+ * The substrate uses one mutex per `SessionHandle` so concurrent consumer
+ * calls (e.g. `send` racing with `capture`) cannot interleave bytes.
+ */
+export declare class Mutex {
+    #private;
+    /**
+     * Run `task` with exclusive access. The mutex is released whether the
+     * task resolves or rejects.
+     */
+    run<T>(task: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=mutex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.d.ts","sourceRoot":"","sources":["../../src/session/mutex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,KAAK;;IAGhB;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAcjD"}

package/dist/session/mutex.js

@@ -0,0 +1,29 @@
+/**
+ * Tiny async mutex. Wraps an async task so calls serialize per-instance.
+ *
+ * The substrate uses one mutex per `SessionHandle` so concurrent consumer
+ * calls (e.g. `send` racing with `capture`) cannot interleave bytes.
+ */
+export class Mutex {
+    #tail = Promise.resolve();
+    /**
+     * Run `task` with exclusive access. The mutex is released whether the
+     * task resolves or rejects.
+     */
+    async run(task) {
+        const prior = this.#tail;
+        let resolveNext;
+        const next = new Promise((res) => {
+            resolveNext = res;
+        });
+        this.#tail = next;
+        try {
+            await prior;
+            return await task();
+        }
+        finally {
+            resolveNext();
+        }
+    }
+}
+//# sourceMappingURL=mutex.js.map

package/dist/session/mutex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../src/session/mutex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,KAAK;IAChB,KAAK,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAE5C;;;OAGG;IACH,KAAK,CAAC,GAAG,CAAI,IAAsB;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,WAAwB,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,GAAG,EAAE,EAAE;YACrC,WAAW,GAAG,GAAG,CAAC;QACpB,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,KAAK,CAAC;YACZ,OAAO,MAAM,IAAI,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,WAAW,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;CACF"}

package/dist/session/recover.d.ts

@@ -0,0 +1,43 @@
+import type { SessionHandle } from "../types.js";
+import { type ResumeOptions } from "./resume.js";
+/**
+ * How a session was reconnected on daemon boot — the answer to "did it survive?"
+ *   - `"attached"` — the pane was **still alive** (your process restarted, the
+ *     session didn't). Reconnected to the running session; nothing was lost.
+ *   - `"resumed"` — the pane was **gone** (it crashed, or the box lost its tmux
+ *     server). The conversation was continued in a **fresh** pane from the
+ *     persisted id. A turn may have been in flight when it died — check
+ *     `turnComplete(yourLastCursor)` and re-send if it reads `false`.
+ */
+export type RecoverStatus = "attached" | "resumed";
+/** The result of {@link recover}: the live handle + how it was recovered. */
+export interface RecoverResult {
+    readonly session: SessionHandle;
+    readonly status: RecoverStatus;
+}
+/**
+ * Reconnect to a session on boot **without the consumer hand-rolling the
+ * adopt-vs-resume decision.** This is the one verb a daemon calls for each
+ * `{ name, agentSessionId }` it persisted: it tries to {@link adopt} the running
+ * pane, and if that pane is gone (`SessionGone` — a crash, or the box lost tmux)
+ * it {@link resume}s the same conversation in a fresh pane. The returned
+ * {@link RecoverStatus} tells you which happened, so "was it crashed?" is a field,
+ * not a `try`/`catch` you write yourself.
+ *
+ * @example
+ * ```ts
+ * // On daemon boot, for each persisted { name, agentSessionId, cwd, lastCursor }:
+ * const { session, status } = await recover({ name, agentSessionId, cwd });
+ * if (status === "resumed" && !(await session.turnComplete(lastCursor))) {
+ *   await session.send(lastInFlightPrompt); // it crashed mid-turn — re-send the lost turn
+ * }
+ * // status === "attached" ⇒ the session never went down; just keep going.
+ * ```
+ *
+ * Takes the same options as {@link resume} (the crash path needs them — `cwd`,
+ * `agentSessionId`, boot knobs). Only `SessionGone` from `adopt` triggers the
+ * resume fallback; any other adopt error (e.g. `InvalidSessionName`) propagates —
+ * those are caller mistakes, not crashes.
+ */
+export declare function recover(opts: ResumeOptions): Promise<RecoverResult>;
+//# sourceMappingURL=recover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recover.d.ts","sourceRoot":"","sources":["../../src/session/recover.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAU,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEzD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC;AAEnD,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAczE"}

package/dist/session/recover.js

@@ -0,0 +1,45 @@
+import { SessionGone } from "../errors.js";
+import { adopt } from "./adopt.js";
+import { resume } from "./resume.js";
+/**
+ * Reconnect to a session on boot **without the consumer hand-rolling the
+ * adopt-vs-resume decision.** This is the one verb a daemon calls for each
+ * `{ name, agentSessionId }` it persisted: it tries to {@link adopt} the running
+ * pane, and if that pane is gone (`SessionGone` — a crash, or the box lost tmux)
+ * it {@link resume}s the same conversation in a fresh pane. The returned
+ * {@link RecoverStatus} tells you which happened, so "was it crashed?" is a field,
+ * not a `try`/`catch` you write yourself.
+ *
+ * @example
+ * ```ts
+ * // On daemon boot, for each persisted { name, agentSessionId, cwd, lastCursor }:
+ * const { session, status } = await recover({ name, agentSessionId, cwd });
+ * if (status === "resumed" && !(await session.turnComplete(lastCursor))) {
+ *   await session.send(lastInFlightPrompt); // it crashed mid-turn — re-send the lost turn
+ * }
+ * // status === "attached" ⇒ the session never went down; just keep going.
+ * ```
+ *
+ * Takes the same options as {@link resume} (the crash path needs them — `cwd`,
+ * `agentSessionId`, boot knobs). Only `SessionGone` from `adopt` triggers the
+ * resume fallback; any other adopt error (e.g. `InvalidSessionName`) propagates —
+ * those are caller mistakes, not crashes.
+ */
+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=recover.js.map

package/dist/session/recover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recover.js","sourceRoot":"","sources":["../../src/session/recover.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAsB,MAAM,aAAa,CAAC;AAmBzD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;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/session/ref.d.ts

@@ -0,0 +1,2 @@
+export { formatSessionLabel } from "../backends/types.js";
+//# sourceMappingURL=ref.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../src/session/ref.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/session/ref.js

@@ -0,0 +1,5 @@
+// formatSessionLabel moved to `src/backends/types.ts` so the backend layer
+// can use it without importing from `src/session/`. This file re-exports
+// for callers that already use the `src/session/ref` path.
+export { formatSessionLabel } from "../backends/types.js";
+//# sourceMappingURL=ref.js.map

package/dist/session/ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.js","sourceRoot":"","sources":["../../src/session/ref.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,yEAAyE;AACzE,2DAA2D;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}