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

package/dist/lib/durable/live.js

@@ -0,0 +1,635 @@
+/**
+ * The live wiring of the durable verbs: real fetch, the stored login (JWT) or the personal org
+ * MNEMOM_API_KEY, the active org, launcher.toml's `durable` key, the process table. Thin by design:
+ * every decision lives in the injected modules and is unit-tested there.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { getAccessToken, resolveAuth } from "../auth.js";
+import { getActiveOrg } from "../cli-config.js";
+import { getCodeEntitlement, listOrgAgents } from "../api.js";
+import { getApiUrl, MNEMOM_DIR } from "../config.js";
+import { applyConfigToEnv, loadLauncherConfig } from "../launcher-config.js";
+import { launchPreferenceExplicit, remoteControlAllowed, resolveLaunchShape } from "../agent.js";
+import { checkRcCapability, resolveCliBin } from "../../commands/agent.js";
+import { conversationOf, envRecord, launcherPassthrough } from "../../durable/discover.js";
+import { liveProcDeps, processTable, readProcArgs } from "../../durable/proc.js";
+import { ledgerPath, readSessionRecords } from "../agent-ledger.js";
+import { launchingNow, liveLaunchingDeps } from "./launching.js";
+import { ATTACH_WAIT_S } from "../../vendor/shared/durable-contract/constants.js";
+import { durableDoctorLines } from "../../commands/durable-doctor.js";
+import { liveCwdProbe, liveTranscriptDirs, liveTrustProbe, lockFactsOf, lockResolvedRow, lockSpecDefaults, printLocked, rcWouldBeNamed, readLocalExecutorId, } from "../../commands/durable-lock.js";
+import { DurableApi, RegistryUnavailable, } from "./api.js";
+import { afterLockRefusal, attachToSeat, createBody, createOutcome, flagValue, } from "./launch.js";
+import { helloLanded, ledgerCcSessionIdFrom, lockCommitted, parentAfterChildEnded, processTree, sessionRowOf, } from "./handover.js";
+import { ccProjectsDir } from "../../host/transcript.js";
+import { resolveInstance } from "../../host/instance.js";
+import { ownerApi, parseExecutorList } from "../../host/owner.js";
+import { seatTmuxSession } from "../../host/tmux.js";
+import { lockAfterFirstTurn, transcriptReader } from "./first-turn.js";
+import { DurableRefusal, printDurableRefusal } from "./refusal.js";
+export function liveDurableApi() {
+    return new DurableApi({
+        fetch: (...a) => fetch(...a),
+        apiBase: () => getApiUrl(),
+        credential: async () => {
+            const c = await resolveAuth();
+            if (c.type === "jwt")
+                return { type: "jwt", token: c.token };
+            if (c.type === "api-key")
+                return { type: "api-key", key: c.key };
+            return { type: "none" };
+        },
+        activeOrgId: () => getActiveOrg()?.org_id,
+        agentsByName: async (name) => (await listOrgAgents())
+            .filter((a) => a.name === name)
+            .map((a) => ({ id: a.id, org_id: a.org_id })),
+    });
+}
+/** launcher.toml `durable`, defaulting to off (only read while the gate is on); unreadable is off. */
+export function liveLauncherKey(load = loadLauncherConfig) {
+    try {
+        return load().durable ?? "off";
+    }
+    catch {
+        return "off";
+    }
+}
+/** PIDs of local claude processes whose argv names `ccSessionId` (pure over a `ps` listing). */
+export function claudePidsFor(psOutput, ccSessionId, selfPid) {
+    const out = [];
+    for (const line of psOutput.split("\n")) {
+        const m = /^\s*(\d+)\s+(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const pid = Number(m[1]);
+        const args = m[2];
+        if (pid === selfPid || !/(^|\/)claude(\s|$)/.test(args.split(" ")[0] ?? ""))
+            continue;
+        if (args.split(/\s+/).includes(ccSessionId))
+            out.push(pid);
+    }
+    return out;
+}
+/** done/kill on a tracked session: SIGTERM its local claude, SIGKILL after the grace (final F04). */
+async function stopTrackedClaude(row, graceS) {
+    const cc = typeof row.cc_session_id === "string" ? row.cc_session_id : null;
+    if (cc === null)
+        return;
+    const ps = spawnSync("ps", ["-axo", "pid=,args="], { encoding: "utf8" });
+    if (ps.status !== 0)
+        return;
+    const pids = claudePidsFor(ps.stdout, cc, process.pid);
+    const alive = (pid) => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    for (const pid of pids) {
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    const deadline = Date.now() + graceS * 1000;
+    while (pids.some(alive) && Date.now() < deadline)
+        await new Promise((r) => setTimeout(r, 200));
+    for (const pid of pids.filter(alive)) {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+export function liveVerbDeps() {
+    return {
+        api: liveDurableApi(),
+        launcherKey: () => liveLauncherKey(),
+        out: (l) => process.stdout.write(`${l}\n`),
+        err: (l) => console.error(l),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        now: () => Date.now(),
+        stopTrackedClaude,
+    };
+}
+export function liveSessionsReadDeps() {
+    return {
+        api: liveDurableApi(),
+        launcherKey: () => liveLauncherKey(),
+        home: liveHomeFacts,
+        out: (l) => process.stdout.write(`${l}\n`),
+        err: (l) => console.error(l),
+    };
+}
+export function liveLockDeps() {
+    const base = liveVerbDeps();
+    return {
+        ...base,
+        api: base.api,
+        home: homedir(),
+        cwd: () => process.cwd(),
+        probe: liveCwdProbe,
+        trust: liveTrustProbe(process.env),
+        readExecutorId: (h) => readLocalExecutorId(h),
+        executorOrg: (id) => {
+            const owner = ownerApi({
+                apiUrl: getApiUrl(),
+                jwt: getAccessToken,
+                fetch: globalThis.fetch,
+            });
+            return readExecutorOrg(id, () => owner.list());
+        },
+        launching: (name) => launchingNow(name, liveLaunchingDeps(MNEMOM_DIR)),
+        specDefaults: (row) => {
+            let launcher = {};
+            try {
+                const c = loadLauncherConfig();
+                launcher = { model: c.model, effort: c.effort };
+            }
+            catch {
+                /* no launcher.toml: the launch's own record alone */
+            }
+            return lockSpecDefaults(row.conversation_id, readSessionRecords({ dir: MNEMOM_DIR }), launcher);
+        },
+        readOriginal: (pid) => liveReadOriginal(pid),
+        rcNamed: () => liveRcNamed(),
+    };
+}
+/** The live original's exact argv, its parent launcher's passthrough and its shape (C14-R13). */
+export function liveReadOriginal(pid, deps = liveProcDeps) {
+    const a = readProcArgs(pid, deps);
+    if (a === null || a.argv.length === 0)
+        return null;
+    const row = processTable(deps).find((r) => r.pid === pid);
+    const parent = row ? readProcArgs(row.ppid, deps) : null;
+    return {
+        argv: a.argv,
+        passthroughHint: launcherPassthrough(parent?.argv),
+        remoteControl: conversationOf(envRecord(a.env))?.rc === true,
+    };
+}
+export const liveRcNamingIo = () => ({
+    env: process.env,
+    loadConfig: () => loadLauncherConfig(),
+    entitlement: () => getCodeEntitlement(getActiveOrg()?.org_id),
+    capable: (env) => checkRcCapability(resolveCliBin(undefined, env)).ok,
+});
+/** The idle source's RC naming, as `mnemom agent <name>` would resolve it (fail-closed: false). */
+export async function liveRcNamed(io = liveRcNamingIo()) {
+    const env = { ...io.env };
+    try {
+        applyConfigToEnv(io.loadConfig(), env);
+        const shape = resolveLaunchShape({}, env);
+        return rcWouldBeNamed({
+            shape,
+            shapeExplicit: launchPreferenceExplicit({}, env),
+            rcAllowed: remoteControlAllowed(await io.entitlement()),
+            rcCapable: () => io.capable(env),
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/** `mnemom agent doctor`'s durable lines (C02-R19), read through the live registry client. */
+export function liveDoctorDurableLines() {
+    return durableDoctorLines(liveDurableApi());
+}
+/** This machine's launch-ledger records, or null when the ledger is missing or unreadable. */
+export function readLedgerRecords(exists, read) {
+    try {
+        return exists() ? read() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The live C02-R26 handover: the process table, real signals, and the registry row. */
+export function liveHandoverDeps(api) {
+    const reread = async (row) => sessionRowOf(await api.getSession(row.conversation_id, row.agent_id));
+    return {
+        ledgerCcSessionId: (cid) => ledgerCcSessionIdFrom(readLedgerRecords(() => existsSync(ledgerPath(MNEMOM_DIR)), () => readSessionRecords({ dir: MNEMOM_DIR })), cid),
+        log: (line) => console.error(line),
+        findOriginal: (cc) => {
+            const ps = spawnSync("ps", ["-axo", "pid=,args="], { encoding: "utf8" });
+            if (ps.status !== 0)
+                return null;
+            const pids = claudePidsFor(ps.stdout, cc, process.pid);
+            return pids.length === 0 ? null : Math.min(...pids);
+        },
+        signal: (pid, sig) => {
+            try {
+                process.kill(pid, sig);
+            }
+            catch {
+                /* already gone */
+            }
+        },
+        helloSeen: async (row) => helloLanded(await reread(row)),
+        committed: async (row) => lockCommitted(await reread(row)),
+        killTree: (pid) => {
+            const ps = spawnSync("ps", ["-axo", "pid=,ppid="], { encoding: "utf8" });
+            const pids = processTree(ps.status === 0 ? ps.stdout : "", pid, process.pid);
+            for (const p of pids) {
+                try {
+                    process.kill(p, "SIGKILL");
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        },
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        now: () => Date.now(),
+        attachWaitS: ATTACH_WAIT_S,
+    };
+}
+/**
+ * The lock verb's deps: the handover on, and EPIPE on stdout ignored (under `/mnemom lock` the
+ * parent may be gone by the time the lock line prints; C02-R26 step 7).
+ */
+export function liveLockVerbDeps() {
+    process.stdout.on("error", (e) => {
+        if (e.code !== "EPIPE")
+            throw e;
+    });
+    const base = liveLockDeps();
+    return {
+        ...base,
+        handover: liveHandoverDeps(liveDurableApi()),
+        transcriptDirs: liveTranscriptDirs(process.env),
+    };
+}
+/**
+ * C02-R26 step 7 for the launcher: its tracked child ended. When a handover locked the session,
+ * restore the terminal mode saved before the spawn (`stty -g`), print the lock line and attach;
+ * the exit status, or null to exit with the child's status as today.
+ */
+export async function liveParentAfterChildEnded(row, name, launcherKey, savedTty) {
+    const api = liveDurableApi();
+    const seat = liveSeatDeps(launcherKey);
+    return parentAfterChildEnded(row, name, {
+        reread: async (r) => sessionRowOf(await api.getSession(r.conversation_id, r.agent_id)),
+        restoreTty: () => {
+            if (savedTty)
+                spawnSync("stty", [savedTty], { stdio: ["inherit", "ignore", "ignore"] });
+        },
+        printLockLine: (r, n) => printLocked({ body: {}, changed: true }, r, n, seat.out),
+        attach: (r, n) => attachToSeat(r, n, [], seat),
+        printRefusal: (r) => printDurableRefusal(r, false, seat),
+    });
+}
+/** The terminal mode (`stty -g`) before claude starts, or null off a TTY. */
+export function saveTtyMode() {
+    if (!process.stdin.isTTY)
+        return null;
+    const r = spawnSync("stty", ["-g"], { stdio: ["inherit", "pipe", "ignore"], encoding: "utf8" });
+    return r.status === 0 && typeof r.stdout === "string" ? r.stdout.trim() || null : null;
+}
+const runThisCli = (bin, args) => spawnSync(process.execPath, [bin, ...args], {
+    encoding: "utf8",
+    timeout: 10_000,
+    env: { ...process.env, MNEMOM_NO_UPDATE_CHECK: "1" },
+});
+/** `mnemom agent host status --json` (C2), or null when it is not available. */
+export function readHostStatus(bin = process.argv[1], run = runThisCli) {
+    if (!bin)
+        return null;
+    const r = run(bin, ["agent", "host", "status", "--json"]);
+    if (r.status !== 0 || typeof r.stdout !== "string")
+        return null;
+    try {
+        const v = JSON.parse(r.stdout);
+        return v !== null && typeof v === "object" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * agents.agent_durable_only from an agent record (bare or under `agent`); null when the record
+ * carries no boolean flag. Absent is never read as false: the api once never served the field
+ * (a PostgREST computed field missed by `select=*`, mnemom-api #4263), and false skipped C02-R24.
+ */
+export function agentDurableOnlyOf(body) {
+    if (body === null || typeof body !== "object")
+        return null;
+    const b = body;
+    const rec = b.agent !== null && typeof b.agent === "object" ? b.agent : b;
+    return typeof rec.agent_durable_only === "boolean" ? rec.agent_durable_only : null;
+}
+/**
+ * agents.agent_durable_only of an agent (A2 serves it on the agent record). It fails closed
+ * (C02-R24): a record that cannot be read (transport, timeout, 5xx, any non-200) refuses with
+ * session_registry_unavailable before any spawn, so a durable-only agent never gets a tracked
+ * claude on an unreadable flag. A 200 without the field refuses the same way: absent is not false.
+ */
+export async function readAgentDurableOnly(api, agentId) {
+    const unreadable = (detail) => new DurableRefusal({
+        code: "session_registry_unavailable",
+        message: `mnemom agent: agent ${agentId}'s durable-only setting could not be read (${detail}); nothing was started`,
+        fix: null,
+    });
+    let a;
+    try {
+        a = await api.getAgent(agentId);
+    }
+    catch (e) {
+        if (e instanceof RegistryUnavailable)
+            throw unreadable(e.message);
+        throw e;
+    }
+    if (a.status !== 200)
+        throw unreadable(`HTTP ${a.status}`);
+    const flag = agentDurableOnlyOf(a.body);
+    if (flag === null)
+        throw unreadable("the agent record carries no agent_durable_only");
+    return flag;
+}
+/**
+ * This machine's label: the machine_label of its current executor in the owner executor list
+ * (exec_list), matched by the state file's executor id. Never the hostname: enrollment takes any
+ * --label. Null when not enrolled here, when the list can't be read, or when the row has no
+ * label; the unreachable-home rule then never applies (the home reads elsewhere).
+ */
+export async function readLocalMachineLabel(localExecutorId, list) {
+    if (localExecutorId === null)
+        return null;
+    let r;
+    try {
+        r = await list();
+    }
+    catch {
+        return null;
+    }
+    if (r.status !== 200)
+        return null;
+    const id = localExecutorId.toLowerCase();
+    return parseExecutorList(r.body)?.find((x) => x.id === id)?.label ?? null;
+}
+/**
+ * The org this machine's executor is enrolled in (exec_list, matched by id), or null when the list
+ * can't be read or names no org for it. Read only to explain a durable_no_executor lock refusal.
+ */
+export async function readExecutorOrg(executorId, list) {
+    let r;
+    try {
+        r = await list();
+    }
+    catch {
+        return null;
+    }
+    if (r.status !== 200)
+        return null;
+    const id = executorId.toLowerCase();
+    return parseExecutorList(r.body)?.find((x) => x.id === id)?.orgId ?? null;
+}
+export async function liveHomeFacts() {
+    const localExecutorId = readLocalExecutorId(homedir());
+    const owner = ownerApi({
+        apiUrl: getApiUrl(),
+        jwt: getAccessToken,
+        fetch: globalThis.fetch,
+    });
+    return {
+        localExecutorId,
+        localMachineLabel: await readLocalMachineLabel(localExecutorId, () => owner.list()),
+        nowMs: Date.now(),
+    };
+}
+/** The launcher's registry reads (entitlement, then the list by name) over one client. */
+export function liveRegistryReads(api) {
+    return {
+        entitlement: () => api.entitlement(),
+        listSessions: (f) => api.listSessions({ name: f.name, agentId: undefined }),
+    };
+}
+export function livePlanDeps(servedAgentId, transcriptExists, askYesNo) {
+    const api = liveDurableApi();
+    return {
+        ...liveRegistryReads(api),
+        failTracked: (row) => api.ownerVerb("own_fail", row.conversation_id, row.agent_id || servedAgentId, {
+            reason: "transcript_lost",
+        }),
+        transcriptExists,
+        daemonLoaded: () => daemonPresent(readHostStatus()),
+        askYesNo,
+        newId: () => randomUUID(),
+        agentDurableOnly: () => readAgentDurableOnly(api, servedAgentId),
+    };
+}
+/**
+ * A host daemon serves this machine when launchd has it loaded, or when one is running here
+ * outside launchd (`mnemom agent host run` in the foreground): status reports its pid only while
+ * that pid holds host.lock and wrote the runtime file.
+ */
+export function daemonPresent(status) {
+    if (!status)
+        return false;
+    return status.loaded === true || typeof status.daemon_pid === "number";
+}
+/**
+ * The seat of a session from host status (C2). Status names its host by the launchd label
+ * (`instance`); a status for another host is never attached to. The socket is this host's tmux
+ * socket, resolved from the environment as the daemon resolves it (host/instance.ts), never the
+ * label: the two differ on every host. The target is the seat's tmux session, named as the daemon
+ * names it from the session and spawn ids (host/tmux.ts seatTmuxSession).
+ */
+export function seatOf(status, row, instance) {
+    if (status === null || status.instance !== instance.label)
+        return null;
+    const seats = Array.isArray(status.seats) ? status.seats : [];
+    const id = row.id ?? null;
+    const seat = seats.find((s) => s !== null &&
+        typeof s === "object" &&
+        s.session_id === id &&
+        s.claude_pid !== null);
+    if (!seat || id === null || typeof seat.spawn_id !== "string")
+        return null;
+    return { socket: instance.tmuxSocket, target: `=${seatTmuxSession(id, seat.spawn_id)}` };
+}
+/** tmux's argv to attach a seat. */
+export function seatAttachArgv(seat) {
+    return ["-L", seat.socket, "attach", "-t", seat.target];
+}
+/** The host instance this CLI talks to, or null when its env names an invalid one. */
+export function envInstance(env = process.env) {
+    try {
+        return resolveInstance(env);
+    }
+    catch {
+        return null;
+    }
+}
+/** The seat to attach to: none when the env names no valid instance (status is then never read). */
+export function seatIn(row, instance, status) {
+    return instance ? seatOf(status(), row, instance) : null;
+}
+/**
+ * Attach the terminal to a seat with tmux and return tmux's exit status; a tmux ended by a signal
+ * (no status) is a failed attach, 1.
+ */
+export function attachSeat(seat, run) {
+    return run("tmux", seatAttachArgv(seat), { stdio: "inherit" }).status ?? 1;
+}
+export function liveSeatDeps(launcherKey) {
+    return {
+        findSeat: async (row) => seatIn(row, envInstance(), () => readHostStatus()),
+        attach: (seat) => attachSeat(seat, spawnSync),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        now: () => Date.now(),
+        out: (l) => process.stdout.write(`${l}\n`),
+        err: (l) => console.error(l),
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        launcherKey,
+    };
+}
+/** Register a new session (POST create) or return the continued row; a refusal is thrown. */
+export async function registerDurableSession(plan, name, agentId, deps = { api: liveDurableApi(), cwd: () => process.cwd() }) {
+    if (!plan.register && plan.row !== null)
+        return plan.row;
+    let a;
+    try {
+        a = await deps.api.createSession(plan.conversationId, agentId, createBody(name, plan.newCcSessionId, deps.cwd()));
+    }
+    catch (e) {
+        if (e instanceof RegistryUnavailable) {
+            throw new DurableRefusal({
+                code: "session_registry_unavailable",
+                message: `mnemom agent: the session registry is unreachable (${e.message}); nothing was started`,
+                fix: null,
+            });
+        }
+        throw e;
+    }
+    const out = createOutcome(a, name);
+    if (out instanceof DurableRefusal)
+        throw out;
+    return {
+        ...out,
+        conversation_id: out.conversation_id ?? plan.conversationId,
+        agent_id: out.agent_id ?? agentId,
+        name: out.name ?? name,
+        cwd: out.cwd ?? deps.cwd(),
+    };
+}
+function liveLockInsteadDeps(launcherKey) {
+    return {
+        lockRow: (row, name, deps) => lockResolvedRow(row, name, {}, deps),
+        lockDeps: liveLockDeps(),
+        seat: liveSeatDeps(launcherKey),
+    };
+}
+export async function lockInsteadOfSpawn(row, name, launcherKey, durableOnly, d = liveLockInsteadDeps(launcherKey)) {
+    const deps = d.lockDeps;
+    const o = await d.lockRow(row, name, deps);
+    if (!o.ok) {
+        const next = afterLockRefusal(o.refusal, durableOnly, launcherKey, name);
+        printDurableRefusal(next.print, false, deps);
+        return next.exit;
+    }
+    const seat = d.seat;
+    if (seat.interactive)
+        printLocked(o, row, name, deps.out);
+    const dropped = lockFactsOf(o.body, row, name, o.dropped).droppedFlags;
+    try {
+        return await attachToSeat(row, name, dropped, seat);
+    }
+    catch (e) {
+        if (e instanceof DurableRefusal)
+            return printDurableRefusal(e, false, deps);
+        throw e;
+    }
+}
+// ---- create-and-lock (ruling B5a as amended) ----------------------------------------------------
+/** The row a create-and-lock is about to make: what the idle-source lock reads (cwd, cc id). */
+export function bornRow(plan, name, agentId, cwd) {
+    return {
+        conversation_id: plan.conversationId,
+        name,
+        agent_id: agentId,
+        durable_mode: "tracked",
+        state: "running",
+        cc_session_id: plan.newCcSessionId,
+        cwd,
+    };
+}
+/**
+ * B5a (as amended): `--new` under `always` on a durable-only agent creates the session locked in
+ * one request (the create route with the lock verb's body; the api commits both in one
+ * transaction), then attaches to the seat like any lock instead of spawning. No tracked row, no
+ * attended claude, so no turn ever runs on a plain key. The lock is the lock verb's own
+ * (lockResolvedRow: cwd rule, executor id, spec); only its POST goes to the create route. A
+ * refusal is the durable_only_agent refusal and exit 1 (C02-R24), never a tracked spawn.
+ *
+ * No claude runs before the lock, so the spec cannot be read from a live original as the lock after
+ * the first turn does: the launch's own `--model` / `--effort` stand in for it (a passthrough
+ * `-- --model` / `--effort` first, as it comes last on claude's argv; else the flag, else
+ * launcher.toml), with its `--trim-mcp`, so the seat runs as the launch chose, never the default.
+ */
+export async function createLockedInsteadOfSpawn(plan, name, agentId, launcherKey, launch, d = {
+    ...liveLockInsteadDeps(launcherKey),
+    api: liveDurableApi(),
+}) {
+    const cwd = d.lockDeps.cwd();
+    const row = bornRow(plan, name, agentId, cwd);
+    const model = flagValue(plan.passthrough, ["--model"]) || launch.model;
+    const effort = flagValue(plan.passthrough, ["--effort"]) || launch.effort;
+    const lockRow = async (r, n, deps) => {
+        const o = await d.lockRow(r, n, {
+            ...deps,
+            specDefaults: (row) => ({
+                ...deps.specDefaults(row),
+                ...(model ? { model } : {}),
+                ...(effort ? { effort } : {}),
+                ...(launch.trimMcp === true ? { trimMcp: true } : {}),
+            }),
+            api: {
+                ...deps.api,
+                lock: (cid, aid, body) => d.api.createSession(cid, aid, {
+                    ...createBody(n, plan.newCcSessionId, cwd),
+                    lock: body,
+                }),
+            },
+        });
+        // the seat is found by the new row's id, which only the answer names
+        const sid = o.ok ? o.body?.session_id : undefined;
+        if (typeof sid === "string")
+            r.id = sid;
+        return o;
+    };
+    return lockInsteadOfSpawn(row, name, launcherKey, true, { ...d, lockRow });
+}
+/**
+ * Dogfood B5: the live lock after the first turn of a new session (lib/durable/first-turn.ts). The
+ * transcript is read under `${CLAUDE_CONFIG_DIR:-~/.claude}/projects`; the lock is the lock verb's
+ * (cwd rule, transcript slug check, executor id) under the running-session handover, so a commit
+ * freezes the attended claude, waits for the seat's hello and ends it, and the launcher's exit path
+ * attaches to the seat (C02-R26 step 7). A refusal is printed with its fix line; claude goes on.
+ */
+export function liveLockAfterFirstTurn(row, name, launcherKey, childAlive) {
+    const dirs = liveTranscriptDirs(process.env);
+    const seat = liveSeatDeps(launcherKey);
+    return lockAfterFirstTurn({
+        name,
+        readTranscript: transcriptReader(ccProjectsDir(process.env), dirs, row.cc_session_id, (p) => readFileSync(p, "utf8")),
+        childAlive,
+        lock: () => lockResolvedRow(row, name, {}, {
+            ...liveLockDeps(),
+            handover: liveHandoverDeps(liveDurableApi()),
+            transcriptDirs: dirs,
+        }),
+        printRefusal: (r) => printDurableRefusal(r, false, seat),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    });
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Durable refusals on the CLI (wave-0 fix ruling 19; S1 cli-output.ts). One shape for every refused
+ * durable verb, with or without --json:
+ *
+ *   stderr  <refusal line>
+ *           fix: <S1 catalogue line, rendered under the fix-line rule>   (when there is one)
+ *           code: <machine code>
+ *   stdout  with --json only: exactly one JSON document, the ruling-14 error envelope. An API or
+ *           gateway refusal body is passed through unchanged; a refusal the CLI decides itself is
+ *           built with S1 `cliRefusalJson` (details.fix carries the rendered line).
+ *   exit    CLI_REFUSAL_EXIT (1).
+ *
+ * The refusal line never contains "code:"/"error:" text, so the first machine-readable stderr token
+ * is always the code line.
+ */
+import { type FixKey, type LauncherKey } from "../../vendor/shared/durable-contract/fixlines.js";
+export interface DurableRefusalInit {
+    /** The machine code (an S1 durable code, or an existing API code such as agent_not_found). */
+    code: string;
+    /** The human refusal line. */
+    message: string;
+    /** The rendered fix line, when the refusal has one. */
+    fix?: string | null;
+    /** Extra closed details for a CLI-built --json document (the code's CodeSpec.fields). */
+    details?: Record<string, unknown>;
+    /** The API or gateway body to pass through unchanged on --json. */
+    apiBody?: unknown;
+    /** Exit status; CLI_REFUSAL_EXIT unless a caller has a reason (claude's own status, say). */
+    exit?: number;
+    /** Fix-line params a later renderer reuses (<repo>, <toplevel>, …); never printed or serialized. */
+    fixParams?: Record<string, string>;
+}
+/** A refused durable verb. Commands throw it; `printDurableRefusal` renders it. */
+export declare class DurableRefusal extends Error {
+    readonly code: string;
+    readonly fix: string | null;
+    readonly details: Record<string, unknown>;
+    readonly apiBody: unknown;
+    readonly exit: number;
+    readonly fixParams: Record<string, string>;
+    constructor(init: DurableRefusalInit);
+}
+/** Render one catalogue line (thin wrapper so callers never restate a fix text). */
+export declare function fixLine(key: FixKey, launcherKey: LauncherKey, nameHeld: boolean, params: Record<string, string>): string;
+/** The --json stdout document for a refusal. */
+export declare function refusalJson(r: DurableRefusal): unknown;
+export interface RefusalSink {
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+/** Print a refusal (stderr always; stdout JSON only with --json) and return its exit status. */
+export declare function printDurableRefusal(r: DurableRefusal, json: boolean, sink: RefusalSink): number;
+/**
+ * The agent action's catch (index.ts): a DurableRefusal is printed (refusal line, fix, code) and its
+ * exit status returned; anything else is null and goes to the generic CLI error report.
+ */
+export declare function durableRefusalExit(error: unknown, sink: RefusalSink): number | null;