@mnemom/mnemom 0.17.34-next.1 → 0.17.34-next.2

package/dist/durable/seat-socket.js

@@ -0,0 +1,179 @@
+// The per-seat socket of the durable seat proxy (C13-R10, C13-R14; BACKBONE C3 "per-seat 0600
+// socket serving only hello").
+//
+// Framing (the plugin SessionStart hook's and the eval's): one JSON object per line,
+// {op, session_id, ...payload}, answered by exactly one JSON line, then the server closes.
+//
+// In M1 it serves exactly one op: `hello` naming the seat's own session id and its registered spawn
+// id (and, when given, the seat's epoch). That hello is relayed to the host daemon, which holds the
+// executor key and nonce the API hello route needs, and the daemon's one-line answer goes back to
+// the hook unchanged; a repeat hello is relayed like the first. Every other op, and any op naming
+// another session id or spawn id, gets the one fixed refusal line below, with no relay and no API
+// call. The refusal echoes nothing from the request.
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+/** The one fixed refusal line (bytes before the newline). A local literal: S1 freezes no seat-socket refusal line yet (gap c3-seat-proxy-enums-not-in-s1). */
+export const SEAT_SOCKET_REFUSAL = '{"ok":false,"error":"seat_op_refused"}';
+/** Our own hello cannot reach the daemon (no relay configured, or the relay failed). */
+export const SEAT_SOCKET_UNAVAILABLE = '{"ok":false,"error":"seat_hello_unavailable"}';
+/** A frame (the bytes before the newline) longer than this many bytes is refused without parsing. */
+export const SEAT_SOCKET_MAX_FRAME = 64 * 1024;
+/** macOS sun_path is 104 bytes including the NUL. */
+export const SOCKET_PATH_MAX = 103;
+/** Whether a parsed frame is the seat's own hello. Everything else is refused. */
+export function isOwnHello(frame, seat) {
+    if (!seat || !frame || typeof frame !== "object" || Array.isArray(frame))
+        return false;
+    const f = frame;
+    if (f.op !== "hello")
+        return false;
+    if (f.session_id !== seat.sessionId)
+        return false;
+    if (f.spawn_id !== seat.spawnId)
+        return false;
+    // Strict: a given epoch must be the seat's own number, same type and value ("3", [3], true: refused).
+    if (f.epoch !== undefined && f.epoch !== seat.epoch)
+        return false;
+    return true;
+}
+/** The reply line (without newline) for one request line. Never throws. */
+export async function answerFrame(line, seat, relay) {
+    let frame;
+    try {
+        frame = JSON.parse(line);
+    }
+    catch {
+        return { reply: SEAT_SOCKET_REFUSAL, outcome: "refused" };
+    }
+    if (!isOwnHello(frame, seat) || !seat)
+        return { reply: SEAT_SOCKET_REFUSAL, outcome: "refused" };
+    if (!relay)
+        return { reply: SEAT_SOCKET_UNAVAILABLE, outcome: "unavailable" };
+    try {
+        const out = await relay({
+            op: "hello",
+            session_id: seat.sessionId,
+            epoch: seat.epoch,
+            spawn_id: seat.spawnId,
+        });
+        const first = String(out).split("\n")[0];
+        return first
+            ? { reply: first, outcome: "relayed" }
+            : { reply: SEAT_SOCKET_UNAVAILABLE, outcome: "unavailable" };
+    }
+    catch {
+        return { reply: SEAT_SOCKET_UNAVAILABLE, outcome: "unavailable" };
+    }
+}
+/**
+ * The socket path for a conversation: under ~/.mnemom/durable/seats when it fits sun_path, else a
+ * short path under /tmp/mnm-seat-<uid>/ (a 0700 directory the seat uid owns), named by a hash of
+ * HOME and the conversation id.
+ */
+export function seatSocketPath(home, conversationId, uid = os.userInfo().uid) {
+    const preferred = path.join(home, ".mnemom", "durable", "seats", `${conversationId}.sock`);
+    if (Buffer.byteLength(preferred) <= SOCKET_PATH_MAX)
+        return preferred;
+    const h = createHash("sha256").update(`${home}\0${conversationId}`).digest("hex").slice(0, 24);
+    return path.join("/tmp", `mnm-seat-${uid}`, `${h}.sock`);
+}
+/** Create (or check) the socket's directory: 0700 and owned by this uid. Throws when it is not. */
+export function ensureSocketDir(dir, uid = os.userInfo().uid) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = fs.lstatSync(dir);
+    if (!st.isDirectory())
+        throw new Error("socket dir is not a directory");
+    if (st.uid !== uid)
+        throw new Error("socket dir is owned by another user");
+    if ((st.mode & 0o777) !== 0o700)
+        fs.chmodSync(dir, 0o700);
+}
+/** Relay a hello to the daemon's control socket: one JSON line out, one line back. */
+export function unixLineRelay(socketPath, timeoutMs = 10_000) {
+    return (frame) => new Promise((resolve, reject) => {
+        const sock = net.createConnection({ path: socketPath });
+        let buf = "";
+        const timer = setTimeout(() => {
+            sock.destroy();
+            reject(new Error("relay timeout"));
+        }, timeoutMs);
+        sock.on("connect", () => sock.write(`${JSON.stringify(frame)}\n`));
+        sock.on("data", (d) => {
+            buf += d.toString("utf8");
+            const i = buf.indexOf("\n");
+            if (i >= 0) {
+                clearTimeout(timer);
+                sock.end();
+                resolve(buf.slice(0, i));
+            }
+        });
+        sock.on("error", (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+        sock.on("close", () => {
+            clearTimeout(timer);
+            if (buf.indexOf("\n") < 0)
+                reject(new Error("relay closed without a reply"));
+        });
+    });
+}
+/** Listen on the seat socket (file mode 0600). Resolves once listening. */
+export function startSeatSocket(opts) {
+    ensureSocketDir(path.dirname(opts.socketPath));
+    try {
+        fs.unlinkSync(opts.socketPath); // a stale socket from a dead proxy; we hold the conversation lock
+    }
+    catch {
+        /* none */
+    }
+    const server = net.createServer((sock) => {
+        // Raw bytes, decoded once a whole line is in: the cap counts bytes (a multibyte character is
+        // not one unit), and a character split across chunks is not mangled.
+        let buf = Buffer.alloc(0);
+        sock.on("error", () => sock.destroy());
+        const onData = (d) => {
+            buf = Buffer.concat([buf, d]);
+            const i = buf.indexOf(0x0a);
+            if ((i < 0 ? buf.length : i) > SEAT_SOCKET_MAX_FRAME) {
+                sock.removeListener("data", onData);
+                opts.log("socket op refused (frame too long)");
+                sock.end(`${SEAT_SOCKET_REFUSAL}\n`);
+                return;
+            }
+            if (i < 0)
+                return;
+            sock.removeListener("data", onData);
+            void answerFrame(buf.subarray(0, i).toString("utf8"), opts.seat, opts.relay).then((a) => {
+                opts.log(`socket op ${a.outcome}`);
+                sock.end(`${a.reply}\n`);
+            });
+        };
+        sock.on("data", onData);
+    });
+    const prev = process.umask(0o177);
+    return new Promise((resolve, reject) => {
+        const onStartError = (e) => {
+            process.umask(prev);
+            reject(e);
+        };
+        server.once("error", onStartError);
+        server.listen(opts.socketPath, () => {
+            process.umask(prev);
+            // The start-up listener only answers listen(): once listening, a later server error must not
+            // reset the umask or vanish into a settled promise, and must not go unhandled either.
+            server.removeListener("error", onStartError);
+            server.on("error", (e) => opts.log(`seat socket error: ${e.message}`));
+            try {
+                fs.chmodSync(opts.socketPath, 0o600);
+            }
+            catch {
+                /* best effort: umask already gave 0600 */
+            }
+            resolve(server);
+        });
+    });
+}

package/dist/durable/seat-spec-validator.d.ts

@@ -0,0 +1,28 @@
+import { type LaunchSpec, type LauncherKey } from "../vendor/durable-contract/index.js";
+export interface SeatSpecInput {
+    raw_spec: unknown;
+    name: string;
+    launcher_key: LauncherKey;
+}
+export interface SeatSpecRefusal {
+    code: "durable_unsupported";
+    feature: "remote_control";
+    names: string[];
+    fix: string;
+}
+export interface SeatSpecResult {
+    seat_spec_built: boolean;
+    spawn_requested: boolean;
+    refusal: SeatSpecRefusal | null;
+    /** The parsed spec when built (not part of the S1 output contract; for the daemon). */
+    spec?: LaunchSpec;
+}
+/** The spec's user flags for the fix line, in the seat order: --model, then --effort. */
+export declare function specFlags(raw: unknown): string[];
+/**
+ * The launch_spec_change fix for `name`: exactly the S1 render with <flags> the spec's flags. S1
+ * does not say how an empty <flags> renders (gap c3-rc-fix-empty-flags), so it is not
+ * post-processed here.
+ */
+export declare function remoteControlFix(name: string, flags: readonly string[], launcherKey: LauncherKey): string;
+export declare function validateSeatSpec(input: SeatSpecInput): SeatSpecResult;

package/dist/durable/seat-spec-validator.js

@@ -0,0 +1,59 @@
+// The daemon's seat-spec validator: defence in depth against a durable launch spec carrying
+// remote control (C13-R13; BACKBONE line 153; S1 PURE_FN_M1_PENDING validateSeatSpec, ruling 33.01).
+//
+// Order (BACKBONE line 84): hasRemoteControl on the raw spec first, then the closed-schema parse.
+// A remote-control carrier is refused with S1 durable_unsupported{feature: remote_control}, and the
+// fix is the S1 launch_spec_change render for the session name (the done clause, since the locked
+// session holds its name; then `--new` with the spec's model/effort flags; the S1 launcher suffix
+// unless the launcher key is always). The validator builds nothing and spawns nothing itself: the
+// daemon (C2) builds the seat from `spec` and spawns only when seat_spec_built is true.
+import { hasRemoteControl, parseLaunchSpec, renderFixLine, LAUNCHER_KEYS, } from "../vendor/durable-contract/index.js";
+/** The spec's user flags for the fix line, in the seat order: --model, then --effort. */
+export function specFlags(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return [];
+    const r = raw;
+    const out = [];
+    if (typeof r.model === "string" && r.model)
+        out.push("--model", r.model);
+    if (typeof r.effort === "string" && r.effort)
+        out.push("--effort", r.effort);
+    return out;
+}
+/**
+ * The launch_spec_change fix for `name`: exactly the S1 render with <flags> the spec's flags. S1
+ * does not say how an empty <flags> renders (gap c3-rc-fix-empty-flags), so it is not
+ * post-processed here.
+ */
+export function remoteControlFix(name, flags, launcherKey) {
+    return renderFixLine("launch_spec_change", {
+        launcherKey,
+        nameHeld: true,
+        params: { name, flags: flags.join(" ") },
+    });
+}
+export function validateSeatSpec(input) {
+    if (!input || typeof input !== "object")
+        throw new TypeError("validateSeatSpec needs {raw_spec, name, launcher_key}");
+    const { raw_spec: raw, name, launcher_key: launcherKey } = input;
+    if (typeof name !== "string" || name === "")
+        throw new TypeError("name must be a non-empty string");
+    if (!LAUNCHER_KEYS.includes(launcherKey))
+        throw new TypeError("launcher_key must be off, ask or always");
+    if (hasRemoteControl(raw)) {
+        return {
+            seat_spec_built: false,
+            spawn_requested: false,
+            refusal: {
+                code: "durable_unsupported",
+                feature: "remote_control",
+                names: ["--remote-control"],
+                fix: remoteControlFix(name, specFlags(raw), launcherKey),
+            },
+        };
+    }
+    const spec = parseLaunchSpec(raw);
+    if (spec === null)
+        return { seat_spec_built: false, spawn_requested: false, refusal: null };
+    return { seat_spec_built: true, spawn_requested: true, refusal: null, spec };
+}

package/dist/durable/test-mode.mjs

@@ -0,0 +1,81 @@
+// The CLI's one TEST_MODE module (S1 TEST_MODE_MODULE.cli; C17-R16, C12-R26, C12-R29).
+//
+// Every CLI seam getter lives here and nowhere else reads DURABLE_SESSIONS_TEST_MODE: the static
+// seam_module check fails the build on any other read. A seam is honoured only when
+// DURABLE_SESSIONS_TEST_MODE is exactly "1" and every URL on the CLI guard list (S1 GUARD_LISTS.cli)
+// is a loopback literal; an unset URL counts as non-loopback. Otherwise a seam env is ignored.
+//
+// The CLI seams (closed list): T1 DURABLE_BOOT_ID_FILE, T2 DURABLE_HOST_TEST_PAUSE_AT, T3 the
+// credential proxy's http door on a loopback host.
+
+const TEST_MODE = "DURABLE_SESSIONS_TEST_MODE";
+/** S1 GUARD_LISTS.cli, in order. */
+export const CLI_GUARD = Object.freeze(["MNEMOM_API_URL", "MNEMOM_GATEWAY_URL"]);
+const LOOPBACK = new Set(["127.0.0.1", "[::1]", "localhost"]);
+
+/** A URL whose host is exactly a loopback literal (S1 isLoopbackUrl). */
+export function isLoopbackUrl(value) {
+  if (typeof value !== "string" || value === "") return false;
+  try {
+    return LOOPBACK.has(new URL(value).hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** The seam guard: test mode exactly "1" and every guard URL a loopback literal. */
+export function testSeamsHonoured(env = process.env) {
+  if (env[TEST_MODE] !== "1") return false;
+  return CLI_GUARD.every((k) => isLoopbackUrl(env[k]));
+}
+
+/**
+ * T1: the boot id override file, or null. `warned` says the override was set but ignored (the
+ * caller logs a warning before any network call, C12-R26).
+ */
+export function bootIdFileOverride(env = process.env) {
+  const file = env.DURABLE_BOOT_ID_FILE;
+  if (typeof file !== "string" || file === "") return { file: null, ignored: false };
+  if (!testSeamsHonoured(env)) return { file: null, ignored: true };
+  return { file, ignored: false };
+}
+
+/** S1 T2_PAUSE_POINTS. */
+export const PAUSE_POINTS = Object.freeze([
+  "after_claim_before_spawn",
+  "after_spawn_before_register",
+  "after_register_before_hello",
+  "after_first_batch",
+  "after_verify_before_exec",
+]);
+
+/** T2: the host daemon pause point, or null (unknown values are ignored). */
+export function hostTestPauseAt(env = process.env) {
+  const v = env.DURABLE_HOST_TEST_PAUSE_AT;
+  if (typeof v !== "string" || !PAUSE_POINTS.includes(v)) return null;
+  return testSeamsHonoured(env) ? v : null;
+}
+
+/** T3: whether the credential proxy may use `door` (an http URL on a loopback host). https is always allowed. */
+export function httpDoorAllowed(door, env = process.env) {
+  let u;
+  try {
+    u = new URL(door);
+  } catch {
+    return false;
+  }
+  if (u.protocol === "https:") return true;
+  if (u.protocol !== "http:") return false;
+  return isLoopbackUrl(door) && testSeamsHonoured(env);
+}
+
+/**
+ * Seam env the host daemon's LaunchAgent and its seats carry over, so a test-mode lane stays in test
+ * mode across launchd and tmux. Named here so no other module spells the test-mode variable.
+ */
+export const DAEMON_TEST_ENV_PASS = Object.freeze([
+  TEST_MODE,
+  "DURABLE_BOOT_ID_FILE",
+  "DURABLE_HOST_TEST_PAUSE_AT",
+]);
+export const SEAT_TEST_ENV_PASS = Object.freeze([TEST_MODE]);

package/dist/durable/turn-chain.d.ts

@@ -0,0 +1,55 @@
+import { type TranscriptEntry, type TurnOrigins } from "../turn-origin.mjs";
+import { type RequestClass } from "../vendor/durable-contract/index.js";
+export type DurableTurn = 
+/** Forward with this `x-mnemom-turn` value (it starts with `chain=`). */
+{
+    kind: "chained";
+    value: string;
+    chain: string;
+    cls: RequestClass;
+    note: string;
+}
+/** Forward with no turn header (pre-first-prompt count_tokens). */
+ | {
+    kind: "unchained";
+    cls: RequestClass;
+    note: string;
+}
+/** Answer the request locally; nothing is forwarded. */
+ | {
+    kind: "local";
+    cls: RequestClass | "no_session";
+    reason: "turn_wait_timeout" | "pre_first_prompt" | "no_session";
+    note: string;
+};
+/** The S1 request class of a request, from its path and (lower-cased) Claude Code hint headers. */
+export declare function requestClassOf(pathname: string, headers: Record<string, unknown>): RequestClass;
+/**
+ * The entry as the durable variant states it. Every prompt entry is stated, so the newest stated
+ * entry is always the real newest one: an entry whose origin turn-origin cannot name reads as the
+ * user's prompt when it records no source either, and as meta (with its source) when its source is
+ * system or sdk. Nothing Claude Code recorded as non-human is ever promoted.
+ */
+export declare function statedEntry(e: TranscriptEntry): TranscriptEntry;
+/**
+ * The producer Claude Code recorded for a task notification (`origin.producer`), stated on
+ * origin=task entries only (S1 amendment 56); undefined otherwise or when not a TURN_PRODUCER_RE token.
+ */
+export declare function entryProducer(e: TranscriptEntry): string | undefined;
+/** The header value: the leading chain element, then the stated entries up to and including the root. */
+export declare function durableHeaderValue(entries: readonly TranscriptEntry[], chain: string): string;
+/** Entries up to and including the last one whose promptId is `promptId`; none when it is absent. */
+export declare function upTo(entries: readonly TranscriptEntry[], promptId: string): TranscriptEntry[];
+export interface DurableTurnOptions {
+    /** Must be exactly true: the explicit opt-in only the durable seat proxy passes. */
+    durable: boolean;
+    /** Overrides S1 TURN_WAIT_MS (tests only). */
+    waitMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The durable turn decision for one request. Without `{ durable: true }` it throws: there is no
+ * implicit path to a `chain=` header.
+ */
+export declare function durableTurnHeaderFor(turns: TurnOrigins, pathname: string, headers: Record<string, unknown>, opts: DurableTurnOptions): Promise<DurableTurn>;

package/dist/durable/turn-chain.js

@@ -0,0 +1,178 @@
+// The opt-in durable variant of the turn-origin builder (BACKBONE C3 and amendment 38; C13-R8).
+//
+// A sibling of turn-origin.mjs `turnHeaderFor`: it reads the same transcript through the same
+// TurnOrigins / TranscriptIndex and states entries with the same `buildTurnHeader`, and adds the
+// leading `chain=<64 hex>` element under the S1 chain derivation. It emits `chain=` only when the
+// caller passes `{ durable: true }`, and only the durable seat proxy does. MNEMOM_AGENT_TURN_HEADER
+// is never read here. rc-proxy.mjs and base-url-proxy.mjs do not import this module, so their
+// output is byte-identical with durable on or off.
+//
+// S1 chain derivation (shared/durable-contract turn.ts chainHandling):
+//   main with a prompt id      wait up to TURN_WAIT_MS for that prompt; chain = sha256(promptId),
+//                              newest stated entry = that prompt entry; timeout = drop
+//   main without a prompt id,  no wait; the session's current root chain: sha256 of the promptId of
+//   compaction, auxiliary      the newest prompt entry (a compact-summary line never counts)
+//   count_tokens               no wait; the current root chain when there is one, else forwarded
+//                              with no turn header at all (the one named exception, ruling 22)
+//   no prompt entry yet        generation requests are answered locally by the proxy
+//
+// A prompt entry that records no origin fact at all (no turnOrigin, origin.kind, promptSource, meta
+// or summary flag) is stated as `origin=human`, with no source: it is the user's own prompt line.
+// Every non-human fact Claude Code records still wins, by entryOrigin's precedence.
+//
+// S1 amendment 56: an origin=task entry also states `producer=<token>` (Claude Code's own
+// origin.producer, e.g. session-task), here only. turn-origin.mjs is main's, so the plain proxies'
+// header bytes never carry it.
+import { createHash } from "node:crypto";
+import { buildTurnHeader, entryOrigin, entrySource, TURN_PARTS_MAX, } from "../turn-origin.mjs";
+import { TURN_WAIT_MS, isCountTokensPath, } from "../vendor/durable-contract/index.js";
+import { TURN_PRODUCER_RE } from "../vendor/shared/durable-contract/turn.js";
+const ID_RE = /^[A-Za-z0-9-]{8,64}$/;
+const POLL_MS = 20;
+const one = (v) => String((Array.isArray(v) ? v[0] : v) ?? "").trim();
+const sha256Hex = (s) => createHash("sha256").update(s, "utf8").digest("hex");
+/** The S1 request class of a request, from its path and (lower-cased) Claude Code hint headers. */
+export function requestClassOf(pathname, headers) {
+    const cls = one(headers["x-claude-code-request-class"]).toLowerCase();
+    const promptId = one(headers["x-claude-code-prompt-id"]);
+    if (isCountTokensPath(pathname))
+        return "count_tokens_pre_first_prompt";
+    if (cls === "main")
+        return ID_RE.test(promptId) ? "main_synced" : "main_no_prompt_id";
+    if (cls === "compaction")
+        return "compaction";
+    return "auxiliary";
+}
+/** A transcript entry that may be the root of a turn: a prompt entry with a promptId, never a summary. */
+function isRootCandidate(e) {
+    return typeof e.promptId === "string" && e.promptId !== "" && e.isCompactSummary !== true;
+}
+/**
+ * entryOrigin as S1 pinned it (turn-origin.mjs@b37bfbf1), before main's SDK rule (#2849: an SDK
+ * prompt reads as the user's turn). In a durable session the host daemon's seat drives Claude Code
+ * through the SDK, so an SDK prompt is not the owner speaking: an entry whose only origin fact is
+ * `sdk` names no origin here, and statedEntry states it as meta with its source, as before.
+ */
+function originWithoutSdkRule(e) {
+    return entryOrigin({
+        ...e,
+        promptSource: e.promptSource === "sdk" ? undefined : e.promptSource,
+        turnOrigin: e.turnOrigin === "sdk" ? undefined : e.turnOrigin,
+    });
+}
+/**
+ * The entry as the durable variant states it. Every prompt entry is stated, so the newest stated
+ * entry is always the real newest one: an entry whose origin turn-origin cannot name reads as the
+ * user's prompt when it records no source either, and as meta (with its source) when its source is
+ * system or sdk. Nothing Claude Code recorded as non-human is ever promoted.
+ */
+export function statedEntry(e) {
+    if (originWithoutSdkRule(e) !== null)
+        return e;
+    const source = entrySource(e);
+    if (source === "system" || source === "sdk")
+        return { ...e, isMeta: true };
+    return { ...e, turnOrigin: "human" };
+}
+/**
+ * The producer Claude Code recorded for a task notification (`origin.producer`), stated on
+ * origin=task entries only (S1 amendment 56); undefined otherwise or when not a TURN_PRODUCER_RE token.
+ */
+export function entryProducer(e) {
+    if (entryOrigin(e) !== "task")
+        return undefined;
+    const p = e.origin?.producer;
+    return typeof p === "string" && TURN_PRODUCER_RE.test(p) ? p : undefined;
+}
+/**
+ * main's buildTurnHeader, entry by entry, with `producer=<p>; ` before `pastes=` on an entry that
+ * states one; the same newest TURN_PARTS_MAX parts.
+ */
+function statedParts(stated) {
+    const parts = [];
+    for (const e of stated) {
+        const own = buildTurnHeader([e], Number.MAX_SAFE_INTEGER);
+        if (!own)
+            continue;
+        const producer = entryProducer(e);
+        for (const part of own.split(", "))
+            parts.push(producer ? part.replace("; pastes=", `; producer=${producer}; pastes=`) : part);
+    }
+    return parts.slice(-TURN_PARTS_MAX).join(", ");
+}
+/** The header value: the leading chain element, then the stated entries up to and including the root. */
+export function durableHeaderValue(entries, chain) {
+    const stated = entries.filter((e) => e.isCompactSummary !== true).map(statedEntry);
+    const parts = statedParts(stated);
+    return parts ? `chain=${chain}, ${parts}` : `chain=${chain}`;
+}
+/** Entries up to and including the last one whose promptId is `promptId`; none when it is absent. */
+export function upTo(entries, promptId) {
+    for (let i = entries.length - 1; i >= 0; i--)
+        if (entries[i].promptId === promptId)
+            return entries.slice(0, i + 1);
+    return [];
+}
+/** The newest root candidate, or null before the first prompt. */
+function newestRoot(entries) {
+    for (let i = entries.length - 1; i >= 0; i--)
+        if (isRootCandidate(entries[i]))
+            return entries[i];
+    return null;
+}
+/**
+ * The durable turn decision for one request. Without `{ durable: true }` it throws: there is no
+ * implicit path to a `chain=` header.
+ */
+export async function durableTurnHeaderFor(turns, pathname, headers, opts) {
+    if (!opts || opts.durable !== true)
+        throw new Error("durableTurnHeaderFor needs { durable: true }");
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const sessionId = one(headers["x-claude-code-session-id"]);
+    const cls = requestClassOf(pathname, headers);
+    const isCount = cls === "count_tokens_pre_first_prompt";
+    if (!ID_RE.test(sessionId)) {
+        if (isCount)
+            return { kind: "unchained", cls, note: "no_session" };
+        return { kind: "local", cls: "no_session", reason: "no_session", note: "no_session" };
+    }
+    if (cls === "main_synced") {
+        const promptId = one(headers["x-claude-code-prompt-id"]);
+        const deadline = now() + (opts.waitMs ?? TURN_WAIT_MS);
+        for (;;) {
+            const ix = turns.index(sessionId);
+            if (ix && ix.refresh() && ix.has(promptId)) {
+                const entries = upTo(ix.entries, promptId);
+                const chain = sha256Hex(promptId);
+                return {
+                    kind: "chained",
+                    value: durableHeaderValue(entries, chain),
+                    chain,
+                    cls,
+                    note: "synced",
+                };
+            }
+            if (now() >= deadline)
+                return { kind: "local", cls, reason: "turn_wait_timeout", note: "turn_wait_timeout" };
+            await sleep(POLL_MS);
+        }
+    }
+    const ix = turns.index(sessionId);
+    const ok = ix ? ix.refresh() : false;
+    const root = ok && ix ? newestRoot(ix.entries) : null;
+    if (!root || !ix) {
+        if (isCount)
+            return { kind: "unchained", cls, note: "pre_first_prompt" };
+        return { kind: "local", cls, reason: "pre_first_prompt", note: "pre_first_prompt" };
+    }
+    const promptId = root.promptId;
+    const chain = sha256Hex(promptId);
+    return {
+        kind: "chained",
+        value: durableHeaderValue(upTo(ix.entries, promptId), chain),
+        chain,
+        cls,
+        note: "current_root",
+    };
+}

package/dist/host/auto-continue.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The seat's automatic "continue" (lead rulings, 2026-10-28: "auto-continue an interrupted turn once
+ * on takeover"): a lock that lands mid-turn leaves the resumed conversation's last turn interrupted,
+ * and `claude --resume` then idles at "What should Claude do instead?". On the seat's first accepted
+ * hello, if the transcript's last turn (as it was before the seat started) was interrupted and that
+ * turn was never continued, the daemon types one "continue" into the pane and logs it. The marker is
+ * keyed on the session and the interrupted turn's record uuid, written before the keys are sent and
+ * kept across respawns: each interrupted turn is continued at most once, so a later mid-turn lock in
+ * the same session is continued too, and a respawn never continues the same turn twice.
+ *
+ * The continue is also journaled: S1's executor.turn_continued (refs {spawn_id}, lead ruling
+ * 2026-10-28) is appended under the seat's epoch after the marker and before the keys. A refused or
+ * failed append sends nothing; the marker stays, so no restart retries that turn unjournaled. The
+ * marker remains the per-turn guard: the event's refs name the spawn, not the turn.
+ *
+ * Pure over injected deps; host/run.ts wires tmux, the marker directory and the daemon log.
+ */
+import type { ExecutorApi } from "./client.js";
+export declare const CONTINUE_TEXT = "continue";
+/** How long to wait for claude's input prompt in the pane before giving up. */
+export declare const PANE_READY_TIMEOUT_MS = 30000;
+export declare const PANE_READY_POLL_MS = 500;
+/**
+ * The interrupted turn of a CC transcript: the uuid of its last conversation record when the turn was
+ * cut off, else null. The last record decides: the assistant's tool call (no result yet) or any user
+ * record (a prompt no reply followed, a tool result the model never answered, or CC's "[Request
+ * interrupted by user]") is cut off, as is an assistant record with only thinking; the assistant's own
+ * text finished the turn. Meta records and lines that are not JSON are skipped. A cut-off record with
+ * no uuid also gives null: without a turn id there is no marker to guard the continue with.
+ */
+export declare function interruptedTurnId(transcript: string): string | null;
+/** The seat a continue is for: its session, pane, and the claim it was spawned under. */
+export interface ContinueSeat {
+    readonly sessionId: string;
+    readonly tmuxSession: string;
+    readonly epoch: number;
+    readonly spawnId: string;
+}
+/** The turn_continued idempotency key: one continue per spawn of a session under one epoch. */
+export declare const continueIdempotencyKey: (seat: ContinueSeat) => string;
+/**
+ * The journal dep over the executor API: POST executor.turn_continued for the seat under its claim
+ * epoch and the boot-bound nonce. A 2xx is journaled (null); anything else answers its code.
+ */
+export declare function turnContinuedJournal(api: Pick<ExecutorApi, "append">, nonce: () => string): (seat: ContinueSeat) => Promise<string | null>;
+export interface AutoContinueDeps {
+    /** This turn of this session was already continued (by any spawn). */
+    continued(sessionId: string, turnId: string): boolean;
+    /** Record the turn's one continue; throws when it cannot be recorded (then nothing is sent). */
+    markContinued(sessionId: string, turnId: string): void;
+    /** Append executor.turn_continued for `seat`; null when the API took it, else why it did not. */
+    journal(seat: ContinueSeat): Promise<string | null>;
+    /** The pane's visible text, or null when the pane is gone. */
+    capture(tmuxSession: string): Promise<string | null>;
+    /** Type `text` and press Enter in the pane. */
+    send(tmuxSession: string, text: string): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+    log(line: string): void;
+    readyTimeoutMs?: number;
+}
+export type AutoContinueOutcome = "not_interrupted" | "already_continued" | "pane_not_ready" | "marker_unwritable" | "journal_refused" | "sent";
+/**
+ * Run once per seat after its first accepted hello. `turnId` is interruptedTurnId of the transcript
+ * as it was at spawn (null: nothing to continue).
+ */
+export declare function autoContinue(seat: ContinueSeat, turnId: string | null, d: AutoContinueDeps): Promise<AutoContinueOutcome>;