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

package/dist/commands/durable-lock.js

@@ -0,0 +1,595 @@
+/**
+ * `mnemom agent lock <name> [--own-agent] [--json]` (BACKBONE C1, design PR 6; C02-R01, R05, R17,
+ * R20, R26, R27; S1 lock.ts, spec.ts, fixlines.ts).
+ *
+ * The idle-source lock (no live tracked claude): resolve the name through the registry, apply the
+ * R27 cwd rule to the session's registered cwd BEFORE any lock request (a failing cwd sends none),
+ * read this machine's executor id, build the launch spec, POST ROUTES.own_lock, and print the one
+ * quiet lock line plus the S1 laptop risk sentence. The API runs the S1 LOCK_STEPS in order; the CLI
+ * only renders its answer.
+ *
+ * Boundaries (cross-piece, see notes-c1.md):
+ *  - The spec comes from C4's `buildDurableLaunchSpec` by the builder input table (`lockSpecOf`):
+ *    a live original is read exactly (C14-R13), else the launcher's resolved continue flags; what
+ *    it dropped is named on the lock line (C14-R12).
+ *  - The executor id is read from S1 EXECUTOR_STATE_FILE (C2 writes it); only `executor_id` is kept.
+ *  - A live tracked claude for the session on this machine (the verb from another terminal, or
+ *    `/mnemom lock` inside the session) takes the C02-R26 handover order (lib/durable/handover.ts)
+ *    around the commit when `handover` is injected; the launcher's own lock (idle source) injects
+ *    none and sends zero signals. The verb takes no passthrough.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { executorStateOk } from "../vendor/shared/durable-contract/executor-state.js";
+import { APPROVALS_TEXT_M1, lockRefusalFixKey, RISK_LINE_TEXT, } from "../vendor/shared/durable-contract/fixlines.js";
+import { EXECUTOR_STATE_FILE } from "../vendor/shared/durable-contract/paths.js";
+import { parseLaunchSpec, PLUGIN_TOKEN, SPEC_VERSION, } from "../vendor/shared/durable-contract/spec.js";
+import { errorCodeOf, errorDetailsOf } from "../lib/durable/api.js";
+import { ccSessionIdOf, commitWithHandover } from "../lib/durable/handover.js";
+import { DurableRefusal, fixLine } from "../lib/durable/refusal.js";
+import { effectiveOf, isEnded } from "../lib/durable/view.js";
+import { handleVerbError, refusalFromAnswer, resolveTarget, } from "./durable-verbs.js";
+import { CODE } from "../lib/durable/codes.js";
+import { buildDurableLaunchSpec, launchSpecChangeFixLines, runningSourceInput, specUserArgv, } from "../durable/launch-spec.js";
+/**
+ * C02-R27: the registered root is realpath(D) when git's toplevel equals it. not_git knows no
+ * checkout, so it carries no <checkout> and prints no fix line (C11-R27, as the C4 rule).
+ */
+export function cwdRule(dir, probe) {
+    const real = probe.realpath(dir);
+    if (real === null)
+        return { ok: false, kind: "not_git", params: {} };
+    const top = probe.toplevel(real);
+    if (top === null)
+        return { ok: false, kind: "not_git", params: {} };
+    const topReal = probe.realpath(top) ?? top;
+    if (topReal !== real)
+        return { ok: false, kind: "subdirectory", params: { toplevel: topReal } };
+    return { ok: true, root: real };
+}
+/** The live probe: node realpath and git with hooks/fsmonitor off and every GIT_* var cleared. */
+export const liveCwdProbe = {
+    realpath: (dir) => {
+        try {
+            return realpathSync(dir);
+        }
+        catch {
+            return null;
+        }
+    },
+    toplevel: (dir) => {
+        const env = {};
+        for (const [k, v] of Object.entries(process.env))
+            if (!k.startsWith("GIT_"))
+                env[k] = v;
+        const r = spawnSync("git", [
+            "-c",
+            "core.hooksPath=/dev/null",
+            "-c",
+            "core.fsmonitor=false",
+            "rev-parse",
+            "--show-toplevel",
+        ], { cwd: dir, env, encoding: "utf8", timeout: 10_000 });
+        if (r.status !== 0 || typeof r.stdout !== "string")
+            return null;
+        const out = r.stdout.trim();
+        return out === "" ? null : out;
+    },
+};
+// ---- the transcript slug check (symlink_transcript) ---------------------------------------------
+/** Claude Code's project directory name for a cwd: every non-alphanumeric character becomes '-'. */
+export const claudeSlug = (cwd) => cwd.replace(/[^A-Za-z0-9]/g, "-");
+const CC_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The live lookup under `${CLAUDE_CONFIG_DIR:-~/.claude}/projects`. */
+export function liveTranscriptDirs(env) {
+    const projects = join((env.CLAUDE_CONFIG_DIR ?? "").trim() || join(homedir(), ".claude"), "projects");
+    return (cc) => {
+        if (!CC_ID_RE.test(cc))
+            return [];
+        try {
+            return readdirSync(projects).filter((d) => existsSync(join(projects, d, `${cc}.jsonl`)));
+        }
+        catch (e) {
+            // No projects dir: Claude Code has written no transcript here, so there is nothing to check.
+            // Any other failure (EACCES, EIO, ENOTDIR, ...) means the check cannot be made: fail closed.
+            return e.code === "ENOENT" ? [] : null;
+        }
+    };
+}
+/**
+ * BACKBONE C1 lock-time cwd check: the realpath `root` is committed only if the session's transcript
+ * (found by cc_session_id) sits under the project dir slugged from it; a transcript found only under
+ * another slug (the symlink path's) is symlink_transcript. No transcript found: nothing to check.
+ */
+export function transcriptSlugRule(root, ccSessionId, dirs) {
+    if (!dirs || ccSessionId === null)
+        return { ok: true, root };
+    const found = dirs(ccSessionId);
+    if (found === null)
+        return { ok: false, kind: "transcript_unverifiable" };
+    if (found.length === 0 || found.includes(claudeSlug(root)))
+        return { ok: true, root };
+    return { ok: false, kind: "symlink_transcript", params: { realpath: root } };
+}
+/**
+ * claude's order for a root (the cwd rule already made it a realpath'd toplevel): the canonical key
+ * (the main checkout for a linked worktree) first, then the bounded walk, which at a toplevel is the
+ * root itself. A parent above the root never counts; the keys are realpaths, never symlink paths.
+ */
+export function rootTrusted(root, probe) {
+    const projects = probe.projects();
+    if (projects === null)
+        return false;
+    const trusted = (k) => rec(projects[k]).hasTrustDialogAccepted === true;
+    const main = probe.mainRoot(root);
+    return (main !== null && trusted(main)) || trusted(root);
+}
+/** A path as one POSIX shell word: bare when it is plainly safe, else single-quoted. */
+export const shellWord = (p) => /^[A-Za-z0-9_./@%+=:,-]+$/.test(p) ? p : `'${p.replace(/'/g, "'\\''")}'`;
+/** The live probe: the config file Claude Code reads, and git with hooks/fsmonitor off and GIT_* cleared. */
+export function liveTrustProbe(env) {
+    const dir = (env.CLAUDE_CONFIG_DIR ?? "").trim();
+    const file = dir ? join(dir, ".claude.json") : join(homedir(), ".claude.json");
+    return {
+        projects: () => {
+            try {
+                const p = rec(JSON.parse(readFileSync(file, "utf8"))).projects;
+                return rec(p);
+            }
+            catch {
+                return null;
+            }
+        },
+        mainRoot: (d) => {
+            const genv = {};
+            for (const [k, v] of Object.entries(env))
+                if (!k.startsWith("GIT_"))
+                    genv[k] = v;
+            const r = spawnSync("git", [
+                "-c",
+                "core.hooksPath=/dev/null",
+                "-c",
+                "core.fsmonitor=false",
+                "rev-parse",
+                "--path-format=absolute",
+                "--git-common-dir",
+            ], { cwd: d, env: genv, encoding: "utf8", timeout: 10_000 });
+            const out = r.status === 0 && typeof r.stdout === "string" ? r.stdout.trim() : "";
+            return out === "" ? null : liveCwdProbe.realpath(dirname(out));
+        },
+    };
+}
+// ---- executor id ------------------------------------------------------------------------------
+/** This machine's executor id from S1 EXECUTOR_STATE_FILE, or null (not enrolled here). */
+export function readLocalExecutorId(home, read = (p) => readFileSync(p, "utf8")) {
+    let raw;
+    try {
+        raw = JSON.parse(read(join(home, EXECUTOR_STATE_FILE)));
+    }
+    catch {
+        return null;
+    }
+    return executorStateOk(raw) ? raw.executor_id : null;
+}
+/**
+ * The idle-source spec in the S1 closed schema; fields the schema refuses are dropped, not sent.
+ * Null when even the required core does not parse (e.g. a root the schema refuses).
+ */
+export function idleLaunchSpec(i) {
+    const spec = {
+        v: SPEC_VERSION,
+        cwd: i.root,
+        plugin: PLUGIN_TOKEN,
+        trim_mcp: i.trimMcp === true,
+    };
+    if (i.model)
+        spec.model = i.model;
+    if (i.effort)
+        spec.effort = i.effort;
+    const parsed = parseLaunchSpec(spec);
+    if (parsed !== null)
+        return parsed;
+    // A model or effort outside the schema: keep the required core only.
+    return parseLaunchSpec({
+        v: SPEC_VERSION,
+        cwd: i.root,
+        plugin: PLUGIN_TOKEN,
+        trim_mcp: i.trimMcp === true,
+    });
+}
+/**
+ * The lock spec's model/effort: the locked conversation's own launch (its newest ledger record)
+ * wins over the launcher defaults, so a session launched with `--model` keeps that model in its
+ * seat instead of resuming on launcher.toml's (or Claude Code's default) model.
+ */
+export function lockSpecDefaults(conversationId, records, launcher) {
+    const own = [...records].reverse().find((r) => r.conversation_id === conversationId);
+    const out = { ...launcher };
+    if (own?.model)
+        out.model = own.model;
+    if (own?.effort)
+        out.effort = own.effort;
+    return out;
+}
+const fmtUsd = (n) => `$${Number.isInteger(n) ? n : n.toFixed(2)}`;
+export function lockLine(f) {
+    const parts = [
+        `${f.name} is durable`,
+        `rules: ${f.rules ?? "default"}`,
+        `approvals → ${APPROVALS_TEXT_M1}`,
+        `budget ${f.budgetUsd === null ? "-" : fmtUsd(f.budgetUsd)}`,
+    ];
+    if (f.ownAgent)
+        parts.push(`moved to its own agent ${f.agent}`);
+    if (f.durableOnly)
+        parts.push(`agent ${f.agent} durable-only: its plain keys stop`);
+    if (f.sharedWith >= 1)
+        parts.push(`shares it with ${f.sharedWith} sessions (pausing pauses all)`);
+    parts.push(`mnemom agent show ${f.name}`);
+    // R17: one line. Every M1 lock homes on a host executor, so the current S1 laptop risk sentence
+    // always rides on it, before the dropped-flags fragment that ends the line.
+    parts.push(RISK_LINE_TEXT);
+    const line = parts.join(" · ");
+    return f.droppedFlags.length === 0
+        ? line
+        : `${line}; flags dropped: ${f.droppedFlags.join(", ")}`;
+}
+function rec(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v)
+        ? v
+        : {};
+}
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+/** Lock facts from the lock answer, falling back to the row (A2 owns the body; read defensively). */
+export function lockFactsOf(body, row, name, built = []) {
+    const b = rec(body);
+    const s = rec(b.session ?? b);
+    const charter = rec(b.charter ?? s.charter);
+    const limits = rec(charter.limits ?? charter);
+    const shared = b.shared_sessions ?? b.locked_sessions ?? b.shares_with;
+    // --own-agent: the api answers the new agent as {agent: {id, name}} (mnemom-test #881).
+    const moved = rec(b.agent).name;
+    return {
+        name,
+        rules: typeof charter.profile === "string"
+            ? charter.profile
+            : typeof b.rules === "string"
+                ? b.rules
+                : null,
+        budgetUsd: num(limits.budget_usd) ?? num(b.budget_usd) ?? num(row.guard_state?.budget_usd ?? null),
+        agent: (typeof moved === "string" ? moved : null) ??
+            (typeof b.agent_name === "string" ? b.agent_name : null) ??
+            row.agent_name ??
+            row.agent_id,
+        ownAgent: typeof moved === "string",
+        durableOnly: b.durable_only === true || b.agent_durable_only === true,
+        sharedWith: Array.isArray(shared) ? shared.length : (num(shared) ?? 0),
+        // The builder's names first (C14-R12), then any the answer adds, each once.
+        droppedFlags: [
+            ...new Set([
+                ...built,
+                ...(Array.isArray(b.flags_dropped)
+                    ? b.flags_dropped.filter((x) => typeof x === "string")
+                    : []),
+            ]),
+        ],
+    };
+}
+/**
+ * Would the launcher's continue have been Remote Control? An explicit shape counts only when it is
+ * RC on an entitled account (a non-entitled one is degraded to terminal by the launcher, nothing
+ * is dropped); an unpinned one only by the auto-upgrade (entitled and capable). The capability
+ * probe runs only when it decides.
+ */
+export function rcWouldBeNamed(i) {
+    if (!i.rcAllowed)
+        return false;
+    if (i.shapeExplicit)
+        return i.shape === "remote-control";
+    return i.shape === "terminal" && i.rcCapable();
+}
+/**
+ * The spec by the builder input table (BACKBONE C4, final F01): a live tracked claude for the
+ * session on this machine is the running source, read exactly; otherwise the idle source, the
+ * launcher's resolved continue flags. `unreadable` when the original is live but its argv cannot be
+ * read (re-resolving the launcher config for a running session is C02-M53); null when the spec does
+ * not fit the closed schema.
+ */
+export async function lockSpecOf(row, root, deps) {
+    const cc = typeof row.cc_session_id === "string" ? row.cc_session_id : null;
+    const pid = cc !== null && deps.handover ? deps.handover.findOriginal(cc) : null;
+    try {
+        if (pid !== null) {
+            const o = deps.readOriginal ? deps.readOriginal(pid) : null;
+            if (o === null)
+                return "unreadable";
+            return await buildDurableLaunchSpec(runningSourceInput(o.argv.slice(1), root, {
+                passthroughHint: o.passthroughHint,
+                remoteControl: o.remoteControl,
+            }));
+        }
+        const d = deps.specDefaults(row);
+        const argv = [
+            ...(d.model ? ["--model", d.model] : []),
+            ...(d.effort ? ["--effort", d.effort] : []),
+            ...(d.trimMcp === true ? ["--trim-mcp"] : []),
+        ];
+        return await buildDurableLaunchSpec({
+            source: "idle",
+            argv,
+            // The launcher's own flags: one outside the schema is dropped from the spec, not named.
+            userArgv: [],
+            remoteControl: deps.rcNamed ? await deps.rcNamed() : false,
+            cwd: root,
+        });
+    }
+    catch (e) {
+        if (e instanceof RangeError)
+            return null;
+        throw e;
+    }
+}
+/** The refusal for a session that has not run its first turn, registered or not yet. */
+export function firstTurnPending(name) {
+    return new DurableRefusal({
+        code: "first_turn_pending",
+        message: `${name} hasn't started its first turn yet: start a first turn, then lock; nothing was locked`,
+        fix: null,
+    });
+}
+/**
+ * A lock refusal's fix line from the S1 lock catalogue, its params (<repo>, <toplevel>, <checkout>,
+ * <realpath>) from the API details. A param the answer does not carry leaves no fix line: an
+ * unfilled placeholder is never printed.
+ */
+export function lockRefusalFix(code, details, name, launcherKey, nameHeld) {
+    if (!(code in LOCK_CODES))
+        return null;
+    const refusals = Array.isArray(details.refusals) ? details.refusals : [];
+    const params = { name };
+    const repo = rec(refusals[0]).repo;
+    if (typeof repo === "string")
+        params.repo = repo;
+    for (const k of ["toplevel", "checkout", "realpath"]) {
+        const v = details[k];
+        if (typeof v === "string" && v !== "")
+            params[k] = v;
+    }
+    const key = lockRefusalFixKey({
+        code: code,
+        cwd_kind: details.cwd_kind ?? undefined,
+    });
+    if (key === null)
+        return null;
+    try {
+        return fixLine(key, launcherKey, nameHeld, params);
+    }
+    catch (e) {
+        if (e instanceof RangeError)
+            return null;
+        throw e;
+    }
+}
+const LOCK_CODES = {
+    durable_cwd_not_root: true,
+    durable_lock_not_entitled: true,
+    durable_lock_mfa_required: true,
+    durable_lock_branch_unprotected: true,
+    durable_lock_agent_shared: true,
+    durable_no_executor: true,
+    durable_precondition_unavailable: true,
+};
+const CWD_REFUSAL_TEXT = {
+    subdirectory: "the session's directory is not the repo root",
+    not_git: "the session's directory is not a git checkout",
+    symlink_transcript: "the session's transcript sits under a symlinked path, not the repo's realpath",
+};
+/**
+ * Lock one resolved row (the idle source): the R27 cwd rule, this machine's executor id, the spec,
+ * POST own_lock. Never prints; the lock verb and the launcher (C02-R23 c, e) render the outcome.
+ */
+export async function lockResolvedRow(row, name, opts, deps) {
+    // The CC session id from the row, else the launch ledger (a --new session's row can lack it).
+    const cc = ccSessionIdOf(row, deps.handover);
+    // A running tracked session with no CC session id from either: its live original (if any) can't
+    // be found, so the idle path would leave it running beside the seat. Fail closed, before any
+    // signal or request.
+    if (row.durable_mode === "tracked" && effectiveOf(row) === "running" && cc === null) {
+        return {
+            ok: false,
+            refusal: new DurableRefusal({
+                code: "session_registry_unavailable",
+                message: `${name}: the session registry did not return this session's Claude Code session id, so its running claude can't be handed over; nothing was signalled and nothing was locked`,
+                fix: null,
+            }),
+        };
+    }
+    const launcherKey = deps.launcherKey();
+    const held = !isEnded(row);
+    const ruled = cwdRule(row.cwd ?? deps.cwd(), deps.probe);
+    const cwd = ruled.ok ? transcriptSlugRule(ruled.root, cc, deps.transcriptDirs) : ruled;
+    if (!cwd.ok && cwd.kind === "transcript_unverifiable") {
+        return {
+            ok: false,
+            refusal: new DurableRefusal({
+                code: "transcript_unverifiable",
+                message: `${name}: can't verify where the session's transcript sits (the Claude Code projects directory is unreadable); nothing was locked`,
+                fix: null,
+            }),
+        };
+    }
+    if (!cwd.ok) {
+        const key = cwd.kind === "subdirectory"
+            ? "cwd_subdirectory"
+            : cwd.kind === "not_git"
+                ? "cwd_not_git"
+                : "cwd_symlink_transcript";
+        return {
+            ok: false,
+            refusal: new DurableRefusal({
+                code: CODE.durable_cwd_not_root,
+                message: `${name}: ${CWD_REFUSAL_TEXT[cwd.kind]} (cwd_kind: ${cwd.kind}); nothing was locked`,
+                fix: cwd.kind === "not_git" ? null : fixLine(key, launcherKey, held, { name, ...cwd.params }),
+                details: { cwd_kind: cwd.kind },
+                fixParams: cwd.params,
+            }),
+        };
+    }
+    if (deps.trust && !rootTrusted(cwd.root, deps.trust)) {
+        return {
+            ok: false,
+            refusal: new DurableRefusal({
+                code: "cwd_untrusted",
+                message: `${name}: Claude Code has not been trusted in ${cwd.root}, so the durable seat would stop at its trust dialog; nothing was locked`,
+                fix: `run \`cd ${shellWord(cwd.root)} && claude\` once, accept the trust dialog, then \`mnemom agent lock ${name}\``,
+                details: { cwd: cwd.root },
+            }),
+        };
+    }
+    // A running session that has not run its first turn has no transcript for the seat to resume
+    // (it would fail transcript_lost): refuse, and leave the attended session as it is.
+    if (deps.handover && deps.transcriptDirs) {
+        if (cc !== null && deps.transcriptDirs(cc)?.length === 0)
+            return { ok: false, refusal: firstTurnPending(name) };
+    }
+    const executorId = deps.readExecutorId(deps.home);
+    if (executorId === null) {
+        return {
+            ok: false,
+            refusal: new DurableRefusal({
+                code: CODE.durable_no_executor,
+                message: `${name}: this machine has no host daemon enrolled; nothing was locked`,
+                fix: fixLine("no_executor", launcherKey, held, { name }),
+            }),
+        };
+    }
+    const built = await lockSpecOf(row, cwd.root, deps);
+    if (built === "unreadable") {
+        return {
+            ok: false,
+            refusal: new DurableRefusal({
+                code: "original_unreadable",
+                message: `${name}: can't read the running session's command line on this machine; nothing was locked`,
+                fix: null,
+            }),
+        };
+    }
+    if (built === null) {
+        return {
+            ok: false,
+            refusal: new DurableRefusal({
+                code: "launch_spec_invalid",
+                message: `${name}: the session's launch spec does not fit the durable schema; nothing was locked`,
+                fix: null,
+            }),
+        };
+    }
+    const body = { spec: built.spec, executor_id: executorId };
+    if (opts.ownAgent)
+        body.own_agent = true;
+    const a = await commitWithHandover(row, deps.handover, () => deps.api.lock(row.conversation_id, row.agent_id, body));
+    if (a.status >= 200 && a.status < 300)
+        return {
+            ok: true,
+            body: a.body,
+            changed: rec(a.body).changed !== false,
+            dropped: built.dropped,
+        };
+    const code = errorCodeOf(a.body);
+    const details = errorDetailsOf(a.body);
+    if (code === CODE.durable_unsupported && details.feature === "launch_spec_change")
+        return { ok: false, refusal: specChangeRefusal(name, built, launcherKey, a.body) };
+    if (code === CODE.durable_no_executor) {
+        const mismatch = await orgMismatchRefusal(row, name, executorId, deps, a.body);
+        if (mismatch !== null)
+            return { ok: false, refusal: mismatch };
+    }
+    const r = refusalFromAnswer(a, name, launcherKey, row);
+    const firstRepo = rec(Array.isArray(details.refusals) ? details.refusals[0] : null).repo;
+    const fixParams = typeof firstRepo === "string" ? { repo: firstRepo } : {};
+    const fix = r.fix === null && code !== null
+        ? lockRefusalFix(code, details, name, launcherKey, held)
+        : r.fix;
+    return {
+        ok: false,
+        refusal: new DurableRefusal({
+            code: r.code,
+            message: r.message,
+            fix,
+            apiBody: a.body,
+            fixParams,
+            ...(typeof details.cwd_kind === "string" ? { details: { cwd_kind: details.cwd_kind } } : {}),
+        }),
+    };
+}
+/**
+ * durable_no_executor because this machine's executor is enrolled in another org than the
+ * session's: say so, with no fix line (installing a host here would not change the org). Null when
+ * the orgs match or either is unknown; the refusal then renders as the API answered.
+ */
+export async function orgMismatchRefusal(row, name, executorId, deps, apiBody) {
+    if (!deps.executorOrg || typeof row.org_id !== "string")
+        return null;
+    const hostOrg = await deps.executorOrg(executorId).catch(() => null);
+    if (hostOrg === null || hostOrg === row.org_id)
+        return null;
+    return new DurableRefusal({
+        code: CODE.durable_no_executor,
+        message: `${name}: the session is in org ${row.org_id}, but this machine's host is enrolled in org ${hostOrg}; nothing was locked`,
+        fix: null,
+        apiBody,
+    });
+}
+/**
+ * 422 durable_unsupported {feature: launch_spec_change} on a re-lock (BACKBONE l.57, final F09): the
+ * S1 `launch_spec_change` entry with <flags> filled from the spec this lock built, so the printed
+ * line is a command that works (C11-R27). The locked row holds the name: the done clause applies.
+ */
+export function specChangeRefusal(name, built, launcherKey, apiBody) {
+    const flags = specUserArgv(built.spec).join(" ");
+    const [line] = launchSpecChangeFixLines({
+        name,
+        flags,
+        launcherKey,
+        soleLockedSession: false,
+    });
+    return new DurableRefusal({
+        code: CODE.durable_unsupported,
+        message: `${name}: the launch spec differs from the committed one (launch_spec_change); a locked session's flags can't change in M1, nothing was changed`,
+        // No flags to pass: `--new` alone, never a dangling space.
+        fix: flags === "" ? line.replace(" --new `", " --new`") : line,
+        details: { feature: "launch_spec_change" },
+        apiBody,
+    });
+}
+/** Print a successful lock: the one quiet line and the S1 laptop risk sentence (C02-R17). */
+export function printLocked(o, row, name, out) {
+    if (!o.changed) {
+        out(`${name} is already durable · mnemom agent show ${name}`);
+        return;
+    }
+    out(lockLine(lockFactsOf(o.body, row, name, o.dropped)));
+}
+export async function lockCommand(name, opts, deps) {
+    try {
+        const row = await resolveTarget(deps.api, name).catch((e) => {
+            // Seconds after `agent <name> --new` the launch may not have registered yet: not a typo.
+            if (e instanceof DurableRefusal && e.code === "agent_not_found" && deps.launching?.(name))
+                throw firstTurnPending(name);
+            throw e;
+        });
+        const o = await lockResolvedRow(row, name, opts, deps);
+        if (!o.ok)
+            throw o.refusal;
+        // --json: stdout carries the one JSON document; the human line goes to stderr.
+        printLocked(o, row, name, opts.json ? deps.err : deps.out);
+        if (opts.json)
+            deps.out(JSON.stringify(o.body ?? {}));
+        return 0;
+    }
+    catch (e) {
+        return handleVerbError(e, opts.json === true, deps);
+    }
+}

package/dist/commands/durable-sessions.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `mnemom agent sessions` and `mnemom agent show <name>` with the `durable` gate on (BACKBONE C1;
+ * C01-R12, R24, R25, R27, R28; C11-R27): read from the server registry, never from the local
+ * ledger. With the gate off these are not reached and the ledger commands run exactly as today.
+ *
+ *   sessions  one row per session: name, user-facing state (of the EFFECTIVE state), agent,
+ *             machine, spend (guard_state.spend_usd to cents for locked rows, `-` for tracked) and
+ *             last activity; under a row, its fix line and the grant warning when they apply.
+ *   show      the S1 SHOW_KEYS sections in order (the --json keys are the same strings, same
+ *             order); keys that do not apply to a tracked session print NA_TEXT (null in --json).
+ *
+ * A registry that is absent for this caller (route 404, not entitled 403) falls back to the ledger
+ * command (`fallback`); an unreachable one refuses with session_registry_unavailable.
+ */
+import { SHOW_KEYS, type LauncherKey } from "../vendor/shared/durable-contract/fixlines.js";
+import { type ApiAnswer, type RegistryRow } from "../lib/durable/api.js";
+import { type HomeFacts } from "../lib/durable/view.js";
+/** The slice of DurableApi these read verbs use (a fake in tests). */
+export interface ReadApi {
+    listSessions(filter: {
+        name?: string;
+        agentId?: string;
+    }): Promise<RegistryRow[]>;
+    getSession(cid: string, agentId: string, include?: "goal"): Promise<ApiAnswer>;
+    getAgent(agentId: string): Promise<ApiAnswer>;
+}
+export interface SessionsReadDeps {
+    api: ReadApi;
+    launcherKey: () => LauncherKey;
+    home: () => Promise<HomeFacts>;
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+/** The ledger command to run when the registry is absent for this caller. */
+export type Fallback = () => Promise<number>;
+/** Rows from the registry, or "absent" (route 404 / not entitled 403). Down -> a refusal is thrown. */
+export declare function readRows(api: ReadApi, filter: {
+    name?: string;
+    agentId?: string;
+}): Promise<RegistryRow[] | "absent">;
+/** Newest first by last activity (rows without one last, input order kept among equals). */
+export declare function newestFirst(rows: readonly RegistryRow[]): RegistryRow[];
+export interface SessionJson {
+    name: string | null;
+    conversation_id: string;
+    state: string;
+    internal_state: string;
+    effective_state: string;
+    state_reason: string | null;
+    durable_mode: "tracked" | "locked";
+    agent: string;
+    machine: string | null;
+    spend: string | null;
+    last_activity: string | null;
+    fix: string | null;
+    grant_warning: string | null;
+}
+/** One row's --json document and its fix / grant lines (the human table prints the same). */
+export declare function sessionJson(row: RegistryRow, launcherKey: LauncherKey, home: HomeFacts): SessionJson;
+export declare function durableSessionsCommand(opts: {
+    all?: boolean;
+    json?: boolean;
+}, deps: SessionsReadDeps, fallback: Fallback): Promise<number>;
+export type ShowKey = (typeof SHOW_KEYS)[number];
+export interface ShowInput {
+    row: RegistryRow;
+    /** GET /{cid}?include=goal body (owner only), or null when unreadable. */
+    detail: Record<string, unknown> | null;
+    /** The caller's other non-terminal sessions on the same agent; null when the registry could not be read. */
+    others: RegistryRow[] | null;
+    /**
+     * agents.agent_durable_only; null when unread (transport, non-200), "protocol_error" when a 200
+     * agent record carries no boolean agent_durable_only (never read as false).
+     */
+    durableOnly: boolean | null | "protocol_error";
+    launcherKey: LauncherKey;
+    home: HomeFacts;
+}
+/** The show document: SHOW_KEYS in order; locked-only keys are null on a tracked session. */
+export declare function showDocument(i: ShowInput): Record<ShowKey, unknown>;
+/** The human lines of a show document, one section per SHOW_KEYS entry, in order. */
+export declare function showLines(name: string, doc: Record<ShowKey, unknown>): string[];
+/** A 200 agent record's agent_durable_only: a boolean, or a protocol error when it is missing. */
+export declare function durableOnlyOf(body: unknown): boolean | "protocol_error";
+export declare function durableShowCommand(ref: string | undefined, opts: {
+    json?: boolean;
+}, deps: SessionsReadDeps, fallback: Fallback): Promise<number>;