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

package/dist/lib/durable/gate.js

@@ -0,0 +1,122 @@
+/**
+ * The CLI `durable` gate (BACKBONE Flags/CLI; C17-R10; amendments 26, 35).
+ *
+ * While `durable` is off every durable verb word exits 2 with `gatedMessage(…, 'durable')`, sends
+ * no HTTP, writes nothing under HOME and starts no process — `--help` and `--json` included, which
+ * is why the check runs on raw argv before commander parses it (commander answers `--help` before
+ * any preAction hook). The words are the declared allowlisted difference: a session named `lock`
+ * or `containment` is not launched by name while durable is off.
+ *
+ * `mnemom agent host run` is gated like every other word until C2 registers its handler (C2 then
+ * reads the gate from config.json only, C12-R25); ungated, it would fall through to the launcher as
+ * a session named "host". The pre-existing `mnemom agent sessions` / `show` are not gated.
+ */
+import { gatedMessage } from "../experimental.js";
+export const DURABLE_ID = "durable";
+/** `mnemom agent <word>` words that exist only with durable on. */
+export const DURABLE_VERB_WORDS = [
+    "lock",
+    "pause",
+    "resume",
+    "done",
+    "kill",
+    "amend",
+    "host",
+    "containment",
+];
+/** `mnemom agent sessions <sub>` sub-verbs that exist only with durable on. */
+export const DURABLE_SESSIONS_SUBVERBS = ["unlock", "adopt"];
+export function durableOn(enabled) {
+    return enabled.includes(DURABLE_ID);
+}
+const NO_SHAPES = { required: new Set(), optional: new Set() };
+/** The value-taking options of `commands` (commander `Command#options`), merged. */
+export function optionShapesOf(commands) {
+    const required = new Set();
+    const optional = new Set();
+    for (const c of commands) {
+        for (const raw of c.options) {
+            const o = raw;
+            if (o.negate)
+                continue;
+            const into = o.required ? required : o.optional ? optional : null;
+            if (into === null)
+                continue;
+            if (o.long)
+                into.add(o.long);
+            if (o.short)
+                into.add(o.short);
+        }
+    }
+    return { required, optional };
+}
+/**
+ * The index of the first operand at or after `i`, stepping over options (and the values the value-
+ * taking ones consume). -1 at `--` (everything after it is passthrough, never a verb).
+ */
+function firstOperand(argv, i, shapes) {
+    while (i < argv.length) {
+        const a = argv[i];
+        if (a === "--")
+            return -1;
+        if (!a.startsWith("-") || a === "-")
+            return i;
+        if (a.includes("=")) {
+            i += 1;
+            continue;
+        }
+        if (shapes.required.has(a)) {
+            i += 2;
+            continue;
+        }
+        if (shapes.optional.has(a)) {
+            const next = argv[i + 1];
+            i += next !== undefined && !next.startsWith("-") ? 2 : 1;
+            continue;
+        }
+        i += 1;
+    }
+    return i;
+}
+/**
+ * The gated use `argv` (process.argv.slice(2)) makes, as the `what` of the gate message, or null
+ * when argv names no durable verb. The verb is the first operand after `agent`, with options (and
+ * their values, per `shapes`) stepped over exactly as commander would before it dispatches the
+ * subcommand, so `agent --new lock x` is gated like `agent lock x`. A word after `--` or as a later
+ * positional is not a verb use.
+ */
+export function durableVerbUse(argv, shapes = NO_SHAPES) {
+    const at = firstOperand(argv, 0, shapes);
+    if (at < 0 || argv[at] !== "agent")
+        return null;
+    const w = firstOperand(argv, at + 1, shapes);
+    const word = w < 0 ? undefined : argv[w];
+    if (word === undefined)
+        return null;
+    if (DURABLE_VERB_WORDS.includes(word)) {
+        const sub = word === "host" || word === "containment" ? argv[w + 1] : undefined;
+        const tail = sub && !sub.startsWith("-") ? ` ${sub}` : "";
+        return `\`mnemom agent ${word}${tail}\``;
+    }
+    if (word === "sessions") {
+        const s = firstOperand(argv, w + 1, shapes);
+        const sub = s < 0 ? undefined : argv[s];
+        if (DURABLE_SESSIONS_SUBVERBS.includes(sub ?? ""))
+            return `\`mnemom agent sessions ${sub}\``;
+    }
+    return null;
+}
+/**
+ * The guard inside every durable verb's action: the pointer (exit 2) while durable is off, else
+ * null. The argv gate above runs first; this one holds for any argv shape that reaches commander.
+ */
+export function durableActionGate(what, enabled) {
+    return durableOn(enabled) ? null : gatedMessage(what, DURABLE_ID);
+}
+/** The gate decision for argv: null when allowed, else the stderr message (exit 2). */
+export function durableGate(argv, enabled, shapes = NO_SHAPES) {
+    if (durableOn(enabled))
+        return null;
+    const what = durableVerbUse(argv, shapes);
+    return what === null ? null : gatedMessage(what, DURABLE_ID);
+}

package/dist/lib/durable/handover.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The running-session handover (C02-R26 steps 2-5 and 7; BACKBONE C1 and amendment 31). Lock of a
+ * session with a live tracked claude on this machine, and adopt, follow one order:
+ *
+ *   (1) pre-commit checks run first (the caller: cwd rule, executor id, spec); a failure never
+ *       reaches here, so the original is untouched;
+ *   (2) freeze: SIGSTOP to the original claude pid only, not its descendants (under `/mnemom lock`
+ *       the lock CLI is a descendant and keeps running);
+ *   (3) commit: on any failure (non-2xx, a no-op, or a dropped response with no committed row on
+ *       re-read) SIGCONT, and the original continues with no row change;
+ *   (5) end: on the seat's hello, or at ATTACH_WAIT_S without one, SIGKILL to the frozen original's
+ *       tree, excluding this process and its own descendants. After the commit the original is never
+ *       resumed, so the conversation never has two running writers.
+ *
+ * Step 7 is the parent launcher's side: its child ended and the session is now locked, so it restores
+ * the terminal, prints the lock line and attaches to the seat.
+ *
+ * No I/O here: the live wiring (lib/durable/live.ts) injects the process table, signals and reads.
+ */
+import { type ApiAnswer, type RegistryRow } from "./api.js";
+import { DurableRefusal } from "./refusal.js";
+export interface HandoverDeps {
+    /** Step-2 discovery: the live tracked claude running this CC session here, or null. */
+    findOriginal(ccSessionId: string): number | null;
+    signal(pid: number, sig: "SIGSTOP" | "SIGCONT"): void;
+    /** The seat's hello for this session has landed (the row is locked and running). */
+    helloSeen(row: RegistryRow): Promise<boolean>;
+    /** Re-read after a dropped response: did the lock commit? */
+    committed(row: RegistryRow): Promise<boolean>;
+    /** SIGKILL the original's process tree (see processTree). */
+    killTree(pid: number): void;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+    attachWaitS: number;
+    /**
+     * This machine's launch ledger, consulted only when the registry row has no cc_session_id (the
+     * owner view does not carry it yet). Only a launch on this machine can have a live original to
+     * hand over, so its ledger can name the CC session; anything but exactly one id fails closed.
+     */
+    ledgerCcSessionId?(conversationId: string): LedgerLookup;
+    /** Why a handover was skipped (stderr; stdout keeps its one line or JSON document). */
+    log?(line: string): void;
+}
+/** The ledger's answer for one conversation: one CC session id, or why there is none to trust. */
+export type LedgerLookup = {
+    readonly ok: true;
+    readonly ccSessionId: string;
+} | {
+    readonly ok: false;
+    readonly why: "ledger_unreadable" | "no_match" | "several_matches";
+};
+/**
+ * The CC session id to hand over: the row's own when it has one, else this machine's ledger entry
+ * for its conversation. Null (with the reason logged) when the ledger cannot name exactly one, so no
+ * process is ever frozen or killed on a guess.
+ */
+export declare function ccSessionIdOf(row: RegistryRow, d: HandoverDeps | undefined): string | null;
+/**
+ * The ledger lookup over its records: the distinct CC session ids recorded for `conversationId`
+ * (a conversation launched again under the same CC session repeats one id; that is still one match).
+ */
+export declare function ledgerCcSessionIdFrom(records: readonly {
+    conversation_id: string;
+    cc_session_id?: string | null;
+}[] | null, conversationId: string): LedgerLookup;
+/**
+ * Send the lock commit for `row` under the handover order. Without handover deps, or with no live
+ * original, this is the idle source: the commit alone, zero signals.
+ */
+export declare function commitWithHandover(row: RegistryRow, d: HandoverDeps | undefined, commit: () => Promise<ApiAnswer>): Promise<ApiAnswer>;
+/**
+ * The pids to SIGKILL for `root` from a `ps -axo pid=,ppid=` listing: the root and every
+ * descendant, minus `self` and self's own descendants.
+ */
+export declare function processTree(psOutput: string, root: number, self: number): number[];
+/** The row in a GET /v1/agent/sessions/{cid} answer (bare or under `session`), or null. */
+export declare function sessionRowOf(a: ApiAnswer): RegistryRow | null;
+/** The seat's hello has landed: the row is locked and effectively running. */
+export declare function helloLanded(row: RegistryRow | null): boolean;
+/** The lock committed: the row is locked. */
+export declare function lockCommitted(row: RegistryRow | null): boolean;
+/**
+ * Whether the launcher's child exit may be a handover: a durable launch whose claude was SIGKILLed
+ * (step 5 kills the frozen tree). Any other exit is handled exactly as today.
+ */
+export declare function mayBeHandover(durable: boolean, signal: NodeJS.Signals | null): boolean;
+export interface ParentDeps {
+    /** The session row now, or null when it cannot be read. */
+    reread(row: RegistryRow): Promise<RegistryRow | null>;
+    /** Put the terminal back in the mode saved before claude started. */
+    restoreTty(): void;
+    printLockLine(row: RegistryRow, name: string): void;
+    /** attachToSeat: the attach exit, or a thrown seat_wait_timeout refusal. */
+    attach(row: RegistryRow, name: string): Promise<number>;
+    printRefusal(r: DurableRefusal): number;
+}
+/**
+ * Step 7: the launcher's tracked child ended. When the session is now locked (a handover took it),
+ * attach to its seat and return the exit status; otherwise null (exit with the child's status).
+ */
+export declare function parentAfterChildEnded(row: RegistryRow, name: string, d: ParentDeps): Promise<number | null>;

package/dist/lib/durable/handover.js

@@ -0,0 +1,175 @@
+/**
+ * The running-session handover (C02-R26 steps 2-5 and 7; BACKBONE C1 and amendment 31). Lock of a
+ * session with a live tracked claude on this machine, and adopt, follow one order:
+ *
+ *   (1) pre-commit checks run first (the caller: cwd rule, executor id, spec); a failure never
+ *       reaches here, so the original is untouched;
+ *   (2) freeze: SIGSTOP to the original claude pid only, not its descendants (under `/mnemom lock`
+ *       the lock CLI is a descendant and keeps running);
+ *   (3) commit: on any failure (non-2xx, a no-op, or a dropped response with no committed row on
+ *       re-read) SIGCONT, and the original continues with no row change;
+ *   (5) end: on the seat's hello, or at ATTACH_WAIT_S without one, SIGKILL to the frozen original's
+ *       tree, excluding this process and its own descendants. After the commit the original is never
+ *       resumed, so the conversation never has two running writers.
+ *
+ * Step 7 is the parent launcher's side: its child ended and the session is now locked, so it restores
+ * the terminal, prints the lock line and attaches to the seat.
+ *
+ * No I/O here: the live wiring (lib/durable/live.ts) injects the process table, signals and reads.
+ */
+import { RegistryUnavailable } from "./api.js";
+import { DurableRefusal } from "./refusal.js";
+import { effectiveOf, isEnded, isLocked } from "./view.js";
+import { SEAT_POLL_MS } from "./launch.js";
+const changed = (a) => a.status >= 200 &&
+    a.status < 300 &&
+    !(a.body !== null &&
+        typeof a.body === "object" &&
+        a.body.changed === false);
+async function waitHello(row, d) {
+    const deadline = d.now() + d.attachWaitS * 1000;
+    for (;;) {
+        const seen = await d.helloSeen(row).catch(() => false);
+        if (seen || d.now() >= deadline)
+            return;
+        await d.sleep(SEAT_POLL_MS);
+    }
+}
+/**
+ * The CC session id to hand over: the row's own when it has one, else this machine's ledger entry
+ * for its conversation. Null (with the reason logged) when the ledger cannot name exactly one, so no
+ * process is ever frozen or killed on a guess.
+ */
+export function ccSessionIdOf(row, d) {
+    if (typeof row.cc_session_id === "string" && row.cc_session_id)
+        return row.cc_session_id;
+    if (!d?.ledgerCcSessionId || typeof row.conversation_id !== "string")
+        return null;
+    const l = d.ledgerCcSessionId(row.conversation_id);
+    if (l.ok)
+        return l.ccSessionId;
+    d.log?.(`lock handover skipped for ${row.conversation_id}: ${l.why}`);
+    return null;
+}
+/**
+ * The ledger lookup over its records: the distinct CC session ids recorded for `conversationId`
+ * (a conversation launched again under the same CC session repeats one id; that is still one match).
+ */
+export function ledgerCcSessionIdFrom(records, conversationId) {
+    if (records === null)
+        return { ok: false, why: "ledger_unreadable" };
+    const ids = new Set();
+    for (const r of records)
+        if (r.conversation_id === conversationId &&
+            typeof r.cc_session_id === "string" &&
+            r.cc_session_id)
+            ids.add(r.cc_session_id);
+    if (ids.size === 0)
+        return { ok: false, why: "no_match" };
+    if (ids.size > 1)
+        return { ok: false, why: "several_matches" };
+    return { ok: true, ccSessionId: [...ids][0] };
+}
+/**
+ * Send the lock commit for `row` under the handover order. Without handover deps, or with no live
+ * original, this is the idle source: the commit alone, zero signals.
+ */
+export async function commitWithHandover(row, d, commit) {
+    const cc = ccSessionIdOf(row, d);
+    const original = d && cc !== null ? d.findOriginal(cc) : null;
+    if (!d || original === null)
+        return commit();
+    d.signal(original, "SIGSTOP");
+    let a;
+    try {
+        a = await commit();
+    }
+    catch (e) {
+        const done = e instanceof RegistryUnavailable && (await d.committed(row).catch(() => false));
+        if (!done) {
+            d.signal(original, "SIGCONT");
+            throw e;
+        }
+        a = { status: 200, body: {} };
+    }
+    if (!changed(a)) {
+        d.signal(original, "SIGCONT");
+        return a;
+    }
+    await waitHello(row, d);
+    d.killTree(original);
+    return a;
+}
+/**
+ * The pids to SIGKILL for `root` from a `ps -axo pid=,ppid=` listing: the root and every
+ * descendant, minus `self` and self's own descendants.
+ */
+export function processTree(psOutput, root, self) {
+    const children = new Map();
+    for (const line of psOutput.split("\n")) {
+        const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
+        if (!m)
+            continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        children.set(ppid, [...(children.get(ppid) ?? []), pid]);
+    }
+    const out = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const pid = stack.pop();
+        if (pid === self)
+            continue;
+        out.push(pid);
+        stack.push(...(children.get(pid) ?? []));
+    }
+    return out;
+}
+/** The row in a GET /v1/agent/sessions/{cid} answer (bare or under `session`), or null. */
+export function sessionRowOf(a) {
+    if (a.status !== 200 || a.body === null || typeof a.body !== "object")
+        return null;
+    const b = a.body;
+    const r = b.session !== null && typeof b.session === "object" ? b.session : b;
+    return typeof r.conversation_id === "string" ? r : null;
+}
+/** The seat's hello has landed: the row is locked and effectively running. */
+export function helloLanded(row) {
+    return row !== null && isLocked(row) && effectiveOf(row) === "running";
+}
+/** The lock committed: the row is locked. */
+export function lockCommitted(row) {
+    return row !== null && isLocked(row);
+}
+/**
+ * Whether the launcher's child exit may be a handover: a durable launch whose claude was SIGKILLed
+ * (step 5 kills the frozen tree). Any other exit is handled exactly as today.
+ */
+export function mayBeHandover(durable, signal) {
+    return durable && signal === "SIGKILL";
+}
+/**
+ * Step 7: the launcher's tracked child ended. When the session is now locked (a handover took it),
+ * attach to its seat and return the exit status; otherwise null (exit with the child's status).
+ */
+export async function parentAfterChildEnded(row, name, d) {
+    let now;
+    try {
+        now = await d.reread(row);
+    }
+    catch {
+        return null;
+    }
+    if (now === null || !isLocked(now) || isEnded(now))
+        return null;
+    d.restoreTty();
+    d.printLockLine(now, name);
+    try {
+        return await d.attach(now, name);
+    }
+    catch (e) {
+        if (e instanceof DurableRefusal)
+            return d.printRefusal(e);
+        throw e;
+    }
+}

package/dist/lib/durable/launch.d.ts

@@ -0,0 +1,182 @@
+/**
+ * The durable launcher (BACKBONE C1; C01-R01, R02, R04, R14, R15, R16, R17, R18, R19, R21, R22;
+ * C02-R20, R23, R24). Pure decisions plus one orchestrator over injected deps; the launcher in
+ * commands/agent.ts calls `planDurableLaunch` once it knows the org and the served agent, and
+ * `finishDurableLaunch` once the conversation id is fixed (registration, then lock-or-spawn).
+ *
+ * Only runs with the `durable` gate on. With it off nothing here is reached (C17).
+ */
+import { type LauncherKey, type LockRefusal } from "../../vendor/shared/durable-contract/fixlines.js";
+import { type ApiAnswer, type RegistryRow } from "./api.js";
+import { DurableRefusal } from "./refusal.js";
+import { type HomeFacts } from "./view.js";
+/** The env var a launched session carries (lib/agent.ts SESSION_NAME_ENV). */
+export declare const NESTED_ENV = "MNEMOM_AGENT_SESSION_NAME";
+export interface PreflightInput {
+    name: string | undefined;
+    env: NodeJS.ProcessEnv;
+    server: boolean;
+    launcherKey: LauncherKey;
+}
+/**
+ * Refusals the CLI decides before any registry call (C01-R15, R19; C02-R20). Null = go on.
+ *  - a nested launch (MNEMOM_AGENT_SESSION_NAME set)       -> nested_launch_refused
+ *  - --server while the launch may be durable (key not off) -> refused, naming --server
+ *  - a name outside the S1 grammar                          -> invalid_session_name
+ */
+export declare function durablePreflight(i: PreflightInput): DurableRefusal | null;
+export declare function flagValue(argv: readonly string[], flags: readonly string[]): string | null | undefined;
+/**
+ * The passthrough a continue keeps, or a refusal. `--continue` and `--resume <same>` are plain
+ * continue (dropped; the launcher adds `--resume <cc>` itself); `--resume <other>`,
+ * `--session-id` and `--fork-session` refuse with session_resume_conflict; a `--goal` refuses with
+ * session_goal_immutable.
+ */
+export declare function continuePassthrough(passthrough: readonly string[], ccSessionId: string | null, goalGiven: boolean): {
+    ok: true;
+    passthrough: string[];
+} | {
+    ok: false;
+    refusal: DurableRefusal;
+};
+export type DurableLaunchPlan = 
+/** Registry off for this caller (route absent / not entitled): launch exactly as today. */
+{
+    kind: "legacy";
+} | {
+    kind: "spawn";
+    conversationId: string;
+    /** Continue: the registered CC session to resume; new: null. */
+    resumeCcSessionId: string | null;
+    /** New: the CC session id the launch pins (registered at create). */
+    newCcSessionId: string | null;
+    passthrough: string[];
+    /** A new row is registered before the spawn. */
+    register: boolean;
+    /** The registry row continued, when continuing. */
+    row: RegistryRow | null;
+    /** Lock instead of spawning (key always, or ask answered yes); a lock refusal falls back to spawn. */
+    lock: boolean;
+    /** The agent is durable-only (C02-R24): a lock refusal never falls back to a tracked spawn. */
+    durableOnly: boolean;
+} | {
+    kind: "attach";
+    row: RegistryRow;
+    wait: boolean;
+};
+export interface PlanInput {
+    name: string;
+    newFlag: boolean;
+    launcherKey: LauncherKey;
+    passthrough: readonly string[];
+    goalGiven: boolean;
+    explicitAgentId: string | null;
+    interactive: boolean;
+    home: HomeFacts;
+    /** The registry answer already read by `registryRows` (the launcher reads it first). */
+    rows?: RegistryRow[] | "legacy";
+    /** `--conversation-id`, when given (C01-R21). */
+    explicitConversationId?: string | null;
+}
+export interface PlanDeps {
+    /** GET /v1/code/entitlement (C01-R26): read before the list; absent or untracked is legacy. */
+    entitlement(): Promise<ApiAnswer>;
+    listSessions(filter: {
+        name: string;
+    }): Promise<RegistryRow[]>;
+    failTracked(row: RegistryRow): Promise<ApiAnswer>;
+    transcriptExists(ccSessionId: string): boolean;
+    daemonLoaded(): boolean;
+    askYesNo(question: string, defaultYes: boolean): Promise<boolean>;
+    newId(): string;
+    /** agents.agent_durable_only of the served agent (C02-R24). */
+    agentDurableOnly(): Promise<boolean>;
+}
+/** A lock refusal code and its cwd_kind, as durable_only_agent's <precondition> reads it. */
+export declare function lockRefusalOf(r: DurableRefusal | null): LockRefusal | null;
+/**
+ * The durable-only refusal (C02-R24; S1 durable_only_agent, byte-equal): before any spawn, naming
+ * the lock refusal when one happened. `fixParams` fills <repo>, <toplevel>, <checkout>, <realpath>.
+ */
+export declare function durableOnlyRefusal(launcherKey: LauncherKey, name: string, lockRefusal: DurableRefusal | null, fixParams?: Record<string, string>): DurableRefusal;
+/**
+ * Whether the entitlement answer gives this caller the registry (C01-R26, R14): a 200 whose
+ * `durable.tracked` is exactly true. The field absent (API flag off or a schema mismatch) or
+ * `tracked` false (not entitled) is not.
+ */
+export declare function durableTracked(a: ApiAnswer): boolean;
+/** The registry reads `registryRows` makes, in order. */
+export type RegistryReads = Pick<PlanDeps, "entitlement" | "listSessions">;
+/**
+ * The caller's rows under `name`, or "legacy" when there is no registry for this caller: the
+ * entitlement's `durable` field absent or not tracked (C01-R26, R14: zero registry calls), the
+ * entitlement refused (403/404: the launch preamble decides access), or the list route absent (404)
+ * or refused (403). Unreachable (transport, timeout, 5xx) throws session_registry_unavailable
+ * (C01-R18). A 401 is rethrown as a RegistryAnswerError (preReadRegistry defers it). The launcher
+ * reads this FIRST, before any other API call, so a down registry refuses within
+ * REGISTRY_TIMEOUT_MS.
+ */
+export declare function registryRows(d: RegistryReads, name: string): Promise<RegistryRow[] | "legacy">;
+/**
+ * The launcher's early read (before sign-in): `registryRows`, except that a 401 (not signed in yet)
+ * defers the read to the plan, which runs after sign-in. Any other answer is final here.
+ */
+export declare function preReadRegistry(d: RegistryReads, name: string): Promise<RegistryRow[] | "legacy" | undefined>;
+/**
+ * C01-R21: `--conversation-id X` on a name live under another cid refuses (session_name_in_use, no
+ * spawn). A free name registers on X (the create route refuses another owner's cid without
+ * disclosing it), and the live row's own cid continues it.
+ */
+export declare function explicitCidRefusal(rows: RegistryRow[], explicitCid: string | null, name: string): DurableRefusal | null;
+export declare function planDurableLaunch(i: PlanInput, deps: PlanDeps): Promise<DurableLaunchPlan>;
+/**
+ * What a launcher does after its lock attempt refused: a durable-only agent gets the
+ * durable_only_agent refusal and exit 1, never a tracked spawn (C02-R24, final F02); any other
+ * agent prints the lock refusal and its fix, then spawns tracked (exit null).
+ */
+export declare function afterLockRefusal(refusal: DurableRefusal, durableOnly: boolean, launcherKey: LauncherKey, name: string): {
+    print: DurableRefusal;
+    exit: number | null;
+};
+/**
+ * A lock on a NEW Claude Code session (no transcript yet) waits for the session's first turn: the
+ * seat resumes the transcript, so a lock before it exists fails transcript_lost. The launcher
+ * spawns claude attended and locks once that turn has completed (lib/durable/first-turn.ts). A
+ * continued session already has its transcript and locks instead of spawning, as before.
+ */
+export declare function locksAfterFirstTurn(plan: Extract<DurableLaunchPlan, {
+    kind: "spawn";
+}>): boolean;
+/** The row the first-turn lock commits: the registered row, naming the CC session this launch pins. */
+export declare function firstTurnRow(row: RegistryRow, plan: Extract<DurableLaunchPlan, {
+    kind: "spawn";
+}>): RegistryRow;
+/** The create body the CLI sends (A2 owns the route; see notes-c1.md). */
+export declare function createBody(name: string, ccSessionId: string | null, cwd: string): Record<string, unknown>;
+/** A create answer: the row, or a refusal (409 session_name_in_use and the rest). */
+export declare function createOutcome(a: ApiAnswer, name: string): RegistryRow | DurableRefusal;
+export interface SeatDeps {
+    /** The live seat of a session: the tmux socket and target, or null while none. */
+    findSeat(row: RegistryRow): Promise<{
+        socket: string;
+        target: string;
+    } | null>;
+    attach(seat: {
+        socket: string;
+        target: string;
+    }): number;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+    out(line: string): void;
+    err(line: string): void;
+    interactive: boolean;
+    launcherKey: LauncherKey;
+}
+/** The poll interval of the seat wait. */
+export declare const SEAT_POLL_MS = 1000;
+/**
+ * Attach to a locked session's seat. Non-TTY: the one S1 line and exit 0, nothing attached. TTY:
+ * wait up to ATTACH_WAIT_S for the seat, attach; on timeout exit non-zero with the seat-wait fix
+ * (the session stays locked).
+ */
+export declare function attachToSeat(row: RegistryRow, name: string, droppedFlags: readonly string[], deps: SeatDeps): Promise<number>;