@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/host/seat-launch.js

@@ -0,0 +1,302 @@
+/**
+ * The seat launcher: what a durable seat's tmux pane runs (BACKBONE C2 "tmux seats with pinned
+ * claude", C3 "lease key on stdin never env/disk"; C12-R16, R21, R27).
+ *
+ *   node <cli>/dist/host/seat-launch-main.js --control <daemon.sock> --session <uuid> --epoch <n>
+ *     --spawn-id <uuid> --conversation <uuid> --agent-id <uuid> --door <url> --cwd <dir>
+ *     --cli-entry <cli>/dist/index.js -- <pinned claude> --resume <cc session> …
+ *
+ * 0. Resolves the owner's provider credential exactly as `mnemom agent` does (seat-credential.ts,
+ *    dogfood B6). None resolves: the seat refuses with `mnemom agent`'s own message, before it takes
+ *    the lease key.
+ * 1. Takes the lease key ONCE from the daemon's control socket (op seat_key; the daemon clears it).
+ * 2. Starts C3's hidden `mnemom agent host seat-proxy` with the seat ids and the control socket as
+ *    its hello relay, and writes the key as one line on the proxy's stdin. The key is never in argv,
+ *    env, a file or a log line.
+ * 3. Waits for the proxy's one stdout line `READY <port> <socket path>`.
+ * 4. Starts claude (stdio inherited, so it owns the pane) against `http://127.0.0.1:<port>` with
+ *    `mnemom agent`'s own env arms (lib/subscription-login.ts launchChildEnv): the Anthropic key in
+ *    ANTHROPIC_CUSTOM_HEADERS behind a placeholder token, or its claude.ai login untouched. The
+ *    proxy passes that credential through and adds the lease key. The control socket path is never
+ *    in claude's env.
+ * 5. Mirrors exits: claude's exit is the seat's (the daemon reads it as the pane's dead status);
+ *    if the proxy exits first (dead key, C13-R7), claude is stopped and the proxy's code is the
+ *    seat's.
+ *
+ * Pure over injected deps; seat-launch-main.ts is the thin driver.
+ */
+import * as path from "node:path";
+import { buildCustomHeaders } from "../lib/agent.js";
+import { launchChildEnv } from "../lib/subscription-login.js";
+/** How long the proxy has to print READY (it reads the key, takes the conversation lock, listens). */
+export const READY_TIMEOUT_MS = 15_000;
+const FLAGS = {
+    "--control": "control",
+    "--session": "session",
+    "--epoch": "epoch",
+    "--spawn-id": "spawnId",
+    "--conversation": "conversation",
+    "--agent-id": "agentId",
+    "--door": "door",
+    "--cwd": "cwd",
+    "--cli-entry": "cliEntry",
+};
+export function parseSeatLaunchArgs(argv) {
+    const raw = {};
+    let i = 0;
+    for (; i < argv.length && argv[i] !== "--"; i += 2) {
+        const flag = argv[i];
+        const key = FLAGS[flag];
+        if (!key)
+            return { ok: false, error: `unknown argument ${flag}` };
+        const v = argv[i + 1];
+        if (v === undefined)
+            return { ok: false, error: `${flag} needs a value` };
+        raw[key] = v;
+    }
+    for (const [flag, key] of Object.entries(FLAGS)) {
+        if (raw[key] === undefined)
+            return { ok: false, error: `${flag} is required` };
+    }
+    if (!/^\d{1,9}$/.test(raw.epoch))
+        return { ok: false, error: "--epoch must be a non-negative integer" };
+    const claude = argv.slice(i + 1);
+    if (argv[i] !== "--" || claude.length === 0)
+        return { ok: false, error: "no claude command after --" };
+    return {
+        ok: true,
+        args: {
+            control: raw.control,
+            session: raw.session,
+            epoch: Number(raw.epoch),
+            spawnId: raw.spawnId,
+            conversation: raw.conversation,
+            agentId: raw.agentId,
+            door: raw.door,
+            cwd: raw.cwd,
+            cliEntry: raw.cliEntry,
+            claude,
+        },
+    };
+}
+/** C3's seat-proxy argv (after the node binary): the seat ids, and the daemon socket as the hello relay. */
+export function proxyArgv(a) {
+    return [
+        a.cliEntry,
+        "agent",
+        "host",
+        "seat-proxy",
+        "--conversation",
+        a.conversation,
+        "--agent-id",
+        a.agentId,
+        "--door",
+        a.door,
+        "--cwd",
+        a.cwd,
+        "--session",
+        a.session,
+        "--epoch",
+        String(a.epoch),
+        "--spawn-id",
+        a.spawnId,
+        "--hello-relay",
+        a.control,
+    ];
+}
+const isAnthropicCred = (k) => k === "ANTHROPIC_API_KEY" ||
+    k === "ANTHROPIC_AUTH_TOKEN" ||
+    k === "ANTHROPIC_BASE_URL" ||
+    k === "ANTHROPIC_CUSTOM_HEADERS" ||
+    k === "MNEMOM_AGENT_ANTHROPIC_KEY";
+function copyEnv(env, drop) {
+    const out = {};
+    for (const [k, v] of Object.entries(env))
+        if (v !== undefined && !drop(k))
+            out[k] = v;
+    return out;
+}
+/**
+ * The proxy reads its seat ids from argv; it gets no seat fact and no Anthropic credential from env
+ * (the provider credential reaches it only per request, from claude, and passes through).
+ */
+export const proxyEnv = (env) => copyEnv(env, (k) => k.startsWith("MNEMOM_SEAT_") || isAnthropicCred(k));
+/**
+ * claude's env: `mnemom agent`'s own env for the resolved credential (launchChildEnv over
+ * buildCustomHeaders), pointed at the loopback proxy, plus the seat socket for the plugin's hello.
+ * The headers' x-mnemom-* lines are replaced by the proxy from the lease; their x-api-key line (the
+ * api-key arm) is what reaches the door. The plugin's hello hook runs `node`, so the directory of
+ * the node running this launcher goes LAST on PATH: a node already on PATH still wins, and a PATH
+ * without one (a version-manager shim that has since gone) still finds this one. Claude Code's
+ * gateway hint headers come with launchChildEnv, as for `mnemom agent`: without x-claude-code-request-class and
+ * x-claude-code-prompt-id the proxy can only chain a turn to the newest prompt already in the
+ * transcript, which for a seat's first typed turn is the launch prompt (dogfood B8).
+ */
+export function claudeEnv(env, port, socketPath, seat, nodeDir) {
+    const headers = buildCustomHeaders({
+        anthropicKey: seat.anthropicKey,
+        agent: seat.agentId,
+        agentId: seat.agentId,
+        conversationId: seat.conversation,
+    });
+    const base = copyEnv(env, (k) => k === "MNEMOM_SEAT_SOCKET");
+    const out = copyEnv(launchChildEnv(base, `http://127.0.0.1:${port}`, headers, seat.anthropicKey), () => false);
+    if (nodeDir) {
+        const dirs = (out.PATH ?? "").split(":").filter(Boolean);
+        if (!dirs.includes(nodeDir))
+            out.PATH = [...dirs, nodeDir].join(":");
+    }
+    return { ...out, MNEMOM_SEAT_SOCKET: socketPath };
+}
+export function parseReady(line) {
+    const m = /^READY (\d{1,5}) (\/.*)$/.exec(line);
+    if (!m)
+        return null;
+    const port = Number(m[1]);
+    if (port < 1 || port > 65535)
+        return null;
+    return { port, socketPath: m[2] };
+}
+/**
+ * The seat proxy's log: its per-request lines (`seat-proxy /v1/messages -> 200 …`) and its errors.
+ * The pane belongs to claude; a proxy line written to the tty is drawn over Claude Code's input box
+ * and reads like a half-typed prompt (dogfood cosmetic finding).
+ */
+export function seatProxyLogPath(logDir, session, spawnId) {
+    return path.join(logDir, `seat-proxy-${session}-${spawnId}.log`);
+}
+/** The proxy's stdio: stdin and stdout piped (key in, READY out), stderr to the log fd or dropped. */
+export function seatProxyStdio(logFd) {
+    return ["pipe", "pipe", logFd ?? "ignore"];
+}
+/** Open the seat proxy's log (append, 0600, in the 0700 durable log dir); null when it cannot. */
+export function openProxyLog(file, f) {
+    try {
+        f.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        return f.openSync(file, "a", 0o600);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * runSeatLaunch's deps over the process's own: the proxy's stderr goes to its log fd
+ * (seatProxyStdio), claude inherits the pane, and the log is named only when it opened.
+ */
+export function seatLaunchDeps(io) {
+    return {
+        env: io.env,
+        execPath: io.execPath,
+        credential: io.credential,
+        request: io.request,
+        spawn: (cmd, args, opts) => io.spawn(cmd, [...args], {
+            env: opts.env,
+            stdio: opts.role === "proxy" ? seatProxyStdio(io.proxyLogFd) : "inherit",
+        }),
+        stderr: io.stderr,
+        ...(io.proxyLogFd !== null ? { proxyLog: io.proxyLog } : {}),
+    };
+}
+const SIGNALS = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGKILL: 9,
+    SIGTERM: 15,
+};
+const exitStatus = (code, signal) => code !== null ? code : 128 + (signal ? (SIGNALS[signal] ?? 0) : 0);
+function waitReady(proxy, timeoutMs) {
+    return new Promise((resolve) => {
+        let buf = "";
+        let done = false;
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve(r);
+        };
+        const timer = setTimeout(() => finish({ kind: "timeout" }), timeoutMs);
+        proxy.stdout?.on("data", (d) => {
+            buf += d.toString();
+            for (let i = buf.indexOf("\n"); i >= 0; i = buf.indexOf("\n")) {
+                const r = parseReady(buf.slice(0, i));
+                buf = buf.slice(i + 1);
+                if (r)
+                    return finish({ kind: "ready", ...r });
+            }
+        });
+        proxy.on("exit", (code) => finish({ kind: "exit", code }));
+    });
+}
+export async function runSeatLaunch(a, d) {
+    const say = (s) => d.stderr(`mnemom seat: ${s}\n`);
+    const cred = await d
+        .credential()
+        .catch((e) => ({ ok: false, message: e.message }));
+    if (!cred.ok) {
+        d.stderr(`${cred.message}\n`);
+        return 1;
+    }
+    const reply = await d
+        .request(a.control, { op: "seat_key", session_id: a.session, spawn_id: a.spawnId })
+        .catch(() => null);
+    const key = reply && reply.ok === true && typeof reply.lease_key === "string" ? reply.lease_key : null;
+    if (!key) {
+        say("no lease key from the host daemon");
+        return 1;
+    }
+    let proxy;
+    try {
+        proxy = d.spawn(d.execPath, proxyArgv(a), { env: proxyEnv(d.env), role: "proxy" });
+    }
+    catch (e) {
+        say(`could not start the seat proxy: ${e.message}`);
+        return 1;
+    }
+    let proxyExit = null;
+    const proxyExited = new Promise((resolve) => proxy.on("exit", (code, signal) => {
+        proxyExit = exitStatus(code, signal);
+        resolve(proxyExit);
+    }));
+    const ready = waitReady(proxy, d.readyTimeoutMs ?? READY_TIMEOUT_MS);
+    proxy.stdin?.end(`${key}\n`);
+    const r = await ready;
+    if (r.kind === "exit") {
+        say(`the seat proxy exited before it was ready (exit ${r.code ?? "signal"})${d.proxyLog ? `; see ${d.proxyLog}` : ""}`);
+        return r.code && r.code > 0 ? r.code : 1;
+    }
+    if (r.kind === "timeout") {
+        say("the seat proxy was not ready in time");
+        proxy.kill("SIGKILL");
+        return 1;
+    }
+    const [cmd, ...rest] = a.claude;
+    let claude;
+    try {
+        claude = d.spawn(cmd, rest, {
+            env: claudeEnv(d.env, r.port, r.socketPath, { agentId: a.agentId, conversation: a.conversation, anthropicKey: cred.anthropicKey }, path.dirname(d.execPath)),
+            role: "claude",
+        });
+    }
+    catch (e) {
+        say(`could not start claude: ${e.message}`);
+        proxy.kill("SIGTERM");
+        return 1;
+    }
+    let claudeDone = false;
+    const claudeExited = new Promise((resolve) => claude.on("exit", (code, signal) => {
+        claudeDone = true;
+        resolve(exitStatus(code, signal));
+    }));
+    void proxyExited.then((code) => {
+        if (claudeDone)
+            return;
+        say(`the seat proxy exited (exit ${code}); stopping claude`);
+        claude.kill("SIGTERM");
+    });
+    const claudeCode = await claudeExited;
+    if (proxyExit !== null)
+        return proxyExit;
+    proxy.kill("SIGTERM");
+    return claudeCode;
+}

package/dist/host/seat.d.ts

@@ -0,0 +1,48 @@
+import type { SessionItem } from "./client.js";
+/** The seat launcher's driver, relative to the CLI entry's directory (dist/index.js -> dist/host/…). */
+export declare const SEAT_LAUNCH_MAIN = "host/seat-launch-main.js";
+/** Env keys a seat inherits from the daemon, when set; everything else is dropped (secret scope). */
+export declare const SEAT_ENV_PASS: string[];
+export declare function seatEnv(env: Readonly<Record<string, string | undefined>>, extra: Readonly<Record<string, string>>): Record<string, string>;
+/** POSIX single-quote one token. */
+/**
+ * The door a seat's proxy forwards to: the same Anthropic door an attended launch uses
+ * (lib/agent resolveAnthropicDoor), with `cellGateway` as the gateway host when
+ * MNEMOM_AGENT_GATEWAY is unset. C3's proxy joins door path + request path, so the door carries
+ * the `/anthropic` path.
+ */
+export declare function seatDoor(env: Readonly<Record<string, string | undefined>>, cellGateway: string): string;
+export declare const shq: (s: string) => string;
+/**
+ * The owner's own default permission mode (`permissions.defaultMode` in the Claude Code user
+ * settings the seat reads), or null when it is unset or unreadable.
+ */
+export declare function seatUserDefaultMode(env: Readonly<Record<string, string | undefined>>): string | null;
+/**
+ * The pinned claude argv for a resume (C4 owns the full renderer; M1 seat flags only).
+ *
+ * When the owner's user settings set a default mode other than auto, the seat restates that same
+ * mode as a --settings source: Claude Code offers its one-time "make auto mode your default?"
+ * dialog only when no settings source but the user's sets a mode, and nobody is at a seat to
+ * answer it. The mode the seat runs in is unchanged.
+ */
+export declare function claudeArgv(claudeBin: string, item: SessionItem, pluginDir: string | null, newSession?: boolean, userDefaultMode?: string | null): string[];
+export interface SeatLaunch {
+    readonly command: string;
+    readonly env: Record<string, string>;
+    readonly specPath: string;
+    readonly specSha256: string;
+}
+export declare function buildSeatLaunch(opts: {
+    env: Readonly<Record<string, string | undefined>>;
+    cliExec: readonly string[];
+    claudeBin: string;
+    pluginDir: string | null;
+    item: SessionItem;
+    epoch: number;
+    spawnId: string;
+    newSession?: boolean;
+    specDir: string;
+    controlSocket: string;
+    door: string;
+}): SeatLaunch;

package/dist/host/seat.js

@@ -0,0 +1,149 @@
+/**
+ * How the daemon launches one seat (BACKBONE C2 "tmux seats with pinned claude"; C3 seat proxy;
+ * C12-R10, R16, R21, R23, R27, R35).
+ *
+ * The pane execs the seat launcher (seat-launch.ts): it takes the lease key once over the control
+ * socket, starts C3's hidden `mnemom agent host seat-proxy` with the key on stdin, then the pinned
+ * claude with `--resume <cc_session_id>` against the proxy's loopback port. The launch-spec file
+ * (`spec_path`, host status) is the session's committed launch spec, one file per session, so its
+ * sha256 is unchanged across respawns. Non-secret seat facts ride as plain env; the control socket
+ * path is in the launcher's argv only. No secret is in argv, env or any file here.
+ */
+import { SEAT_TEST_ENV_PASS } from "../durable/test-mode.mjs";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { canonicalJson } from "../vendor/shared/durable-contract/canonical.js";
+import { resolveAnthropicDoor } from "../lib/agent.js";
+/** The seat launcher's driver, relative to the CLI entry's directory (dist/index.js -> dist/host/…). */
+export const SEAT_LAUNCH_MAIN = "host/seat-launch-main.js";
+/** Env keys a seat inherits from the daemon, when set; everything else is dropped (secret scope). */
+export const SEAT_ENV_PASS = [
+    "PATH",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "LANG",
+    "TMPDIR",
+    "CLAUDE_CONFIG_DIR",
+    "MNEMOM_API_URL",
+    "MNEMOM_GATEWAY_URL",
+    "MNEMOM_AGENT_GATEWAY",
+    "DISABLE_AUTOUPDATER",
+    "MNEMOM_DISABLE_AUTOUPDATE",
+    "MNEMOM_UPDATE_MODE",
+    ...SEAT_TEST_ENV_PASS,
+];
+export function seatEnv(env, extra) {
+    const out = { TERM: "xterm-256color" };
+    for (const k of SEAT_ENV_PASS) {
+        const v = env[k];
+        if (v)
+            out[k] = v;
+    }
+    return { ...out, ...extra };
+}
+/** POSIX single-quote one token. */
+/**
+ * The door a seat's proxy forwards to: the same Anthropic door an attended launch uses
+ * (lib/agent resolveAnthropicDoor), with `cellGateway` as the gateway host when
+ * MNEMOM_AGENT_GATEWAY is unset. C3's proxy joins door path + request path, so the door carries
+ * the `/anthropic` path.
+ */
+export function seatDoor(env, cellGateway) {
+    const agentGateway = (env.MNEMOM_AGENT_GATEWAY ?? "").trim() || cellGateway;
+    return resolveAnthropicDoor({ ...env, MNEMOM_AGENT_GATEWAY: agentGateway });
+}
+export const shq = (s) => /^[A-Za-z0-9_./:=@%+-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+/**
+ * The owner's own default permission mode (`permissions.defaultMode` in the Claude Code user
+ * settings the seat reads), or null when it is unset or unreadable.
+ */
+export function seatUserDefaultMode(env) {
+    const dir = env.CLAUDE_CONFIG_DIR || (env.HOME ? path.join(env.HOME, ".claude") : "");
+    if (!dir)
+        return null;
+    try {
+        const mode = JSON.parse(fs.readFileSync(path.join(dir, "settings.json"), "utf8"))?.permissions
+            ?.defaultMode;
+        return typeof mode === "string" && mode ? mode : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The pinned claude argv for a resume (C4 owns the full renderer; M1 seat flags only).
+ *
+ * When the owner's user settings set a default mode other than auto, the seat restates that same
+ * mode as a --settings source: Claude Code offers its one-time "make auto mode your default?"
+ * dialog only when no settings source but the user's sets a mode, and nobody is at a seat to
+ * answer it. The mode the seat runs in is unchanged.
+ */
+export function claudeArgv(claudeBin, item, pluginDir, newSession = false, userDefaultMode = null) {
+    // B5a: a born-locked session's first spawn starts its CC session under the registered id.
+    const argv = [claudeBin, newSession ? "--session-id" : "--resume", item.cc_session_id ?? ""];
+    if (pluginDir)
+        argv.push("--plugin-dir", pluginDir);
+    const spec = item.spec ?? {};
+    if (typeof spec.model === "string")
+        argv.push("--model", spec.model);
+    if (typeof spec.effort === "string")
+        argv.push("--effort", spec.effort);
+    if (userDefaultMode && userDefaultMode !== "auto")
+        argv.push("--settings", JSON.stringify({ permissions: { defaultMode: userDefaultMode } }));
+    return argv;
+}
+export function buildSeatLaunch(opts) {
+    const { item } = opts;
+    const spec = item.spec ?? { v: 1, cwd: item.cwd, plugin: "bundled-mnemom", trim_mcp: false };
+    fs.mkdirSync(opts.specDir, { recursive: true, mode: 0o700 });
+    const specPath = path.join(opts.specDir, `${item.id}.json`);
+    const text = `${canonicalJson(spec)}\n`;
+    let cur;
+    try {
+        cur = fs.readFileSync(specPath, "utf8");
+    }
+    catch {
+        cur = null;
+    }
+    if (cur !== text)
+        fs.writeFileSync(specPath, text, { mode: 0o600 });
+    const [node, entry] = [opts.cliExec[0] ?? process.execPath, opts.cliExec[1] ?? ""];
+    const launcher = [
+        node,
+        path.join(path.dirname(entry), SEAT_LAUNCH_MAIN),
+        "--control",
+        opts.controlSocket,
+        "--session",
+        item.id,
+        "--epoch",
+        String(opts.epoch),
+        "--spawn-id",
+        opts.spawnId,
+        "--conversation",
+        item.conversation_id ?? item.id,
+        "--agent-id",
+        item.agent_id ?? "",
+        "--door",
+        opts.door,
+        "--cwd",
+        item.cwd ?? "",
+        "--cli-entry",
+        entry,
+        "--",
+        ...claudeArgv(opts.claudeBin, item, opts.pluginDir, opts.newSession === true, seatUserDefaultMode(opts.env)),
+    ];
+    const env = seatEnv(opts.env, {
+        MNEMOM_SEAT_SESSION_ID: item.id,
+        MNEMOM_SEAT_SPAWN_ID: opts.spawnId,
+        MNEMOM_SEAT_EPOCH: String(opts.epoch),
+        MNEMOM_SEAT_SPEC: specPath,
+    });
+    return {
+        command: `exec ${launcher.map(shq).join(" ")}`,
+        env,
+        specPath,
+        specSha256: createHash("sha256").update(text).digest("hex"),
+    };
+}

package/dist/host/state.d.ts

@@ -0,0 +1,33 @@
+import { type ExecutorState } from "../vendor/shared/durable-contract/executor-state.js";
+/** What a readable state file yields; boot_id null when missing or unusable. */
+export interface LoadedState {
+    readonly executor_id: string;
+    readonly executor_key: string;
+    readonly nonce: string;
+    readonly boot_id: string | null;
+}
+export type ReadResult = {
+    kind: "absent";
+} | {
+    kind: "corrupt";
+    reason: string;
+} | {
+    kind: "ok";
+    state: LoadedState;
+};
+export declare function readExecutorState(file: string): ReadResult;
+export declare function parseExecutorState(raw: unknown): ReadResult;
+/** A fresh random nonce (A1 accepts 1..128 chars). */
+export declare function newNonce(): string;
+/**
+ * C12-R06: keep the nonce only when the recorded boot id equals the OS boot id; otherwise (a
+ * reboot, a restore, a copied file, or a missing/corrupt boot id) mint a new one.
+ */
+export declare function bindNonce(loaded: LoadedState, osBootId: string, mint?: () => string): {
+    state: ExecutorState;
+    rotated: boolean;
+};
+/** True when the file on disk already holds exactly `state` in the frozen shape (no rewrite needed). */
+export declare function stateFileCurrent(file: string, state: ExecutorState): boolean;
+/** Write the frozen shape: dir 0700, file 0600, tmp+rename (the lock is elsewhere, C12-R03). */
+export declare function writeExecutorState(file: string, state: ExecutorState): void;

package/dist/host/state.js

@@ -0,0 +1,117 @@
+/**
+ * The executor state file (S1 EXECUTOR_STATE_FILE; C12-R05, R06; ruling 24.14).
+ *
+ * The file is the only home of the executor key. It is written 0600 in a 0700 directory. The
+ * single-instance lock lives on a separate file (lock.ts), so writing this file by tmp+rename
+ * never drops the lock (C12-R03).
+ *
+ * Reading is lenient about extra keys (an enrollment written by an older build, or a test
+ * fixture) but strict about the identity triple (executor_id, executor_key, nonce). A missing or
+ * corrupt boot_id is not an error: bindNonce mints a new nonce for it (C12-R06 fail safe), and
+ * the file is rewritten in the frozen S1 shape.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
+import { EXECUTOR_STATE_VERSION, executorStateOk, } from "../vendor/shared/durable-contract/executor-state.js";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function readExecutorState(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return { kind: "absent" };
+        return { kind: "corrupt", reason: `unreadable: ${e.message}` };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return { kind: "corrupt", reason: "not JSON" };
+    }
+    return parseExecutorState(raw);
+}
+export function parseExecutorState(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return { kind: "corrupt", reason: "not an object" };
+    const o = raw;
+    if (typeof o.executor_id !== "string" || !UUID_RE.test(o.executor_id))
+        return { kind: "corrupt", reason: "executor_id" };
+    if (typeof o.executor_key !== "string" || o.executor_key === "")
+        return { kind: "corrupt", reason: "executor_key" };
+    const nonce = typeof o.nonce === "string" && o.nonce.length >= 1 && o.nonce.length <= 128 ? o.nonce : "";
+    const boot = typeof o.boot_id === "string" && o.boot_id.trim() !== "" ? o.boot_id : null;
+    return {
+        kind: "ok",
+        state: {
+            executor_id: o.executor_id.toLowerCase(),
+            executor_key: o.executor_key,
+            nonce,
+            boot_id: nonce ? boot : null,
+        },
+    };
+}
+/** A fresh random nonce (A1 accepts 1..128 chars). */
+export function newNonce() {
+    return `n-${randomBytes(24).toString("hex")}`;
+}
+/**
+ * C12-R06: keep the nonce only when the recorded boot id equals the OS boot id; otherwise (a
+ * reboot, a restore, a copied file, or a missing/corrupt boot id) mint a new one.
+ */
+export function bindNonce(loaded, osBootId, mint = newNonce) {
+    const keep = loaded.boot_id !== null && loaded.nonce !== "" && loaded.boot_id === osBootId;
+    return {
+        state: {
+            version: EXECUTOR_STATE_VERSION,
+            executor_id: loaded.executor_id,
+            executor_key: loaded.executor_key,
+            nonce: keep ? loaded.nonce : mint(),
+            boot_id: osBootId,
+        },
+        rotated: !keep,
+    };
+}
+/** True when the file on disk already holds exactly `state` in the frozen shape (no rewrite needed). */
+export function stateFileCurrent(file, state) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        return (executorStateOk(raw) &&
+            raw.nonce === state.nonce &&
+            raw.boot_id === state.boot_id &&
+            raw.executor_key === state.executor_key &&
+            raw.executor_id === state.executor_id);
+    }
+    catch {
+        return false;
+    }
+}
+/** Write the frozen shape: dir 0700, file 0600, tmp+rename (the lock is elsewhere, C12-R03). */
+export function writeExecutorState(file, state) {
+    if (!executorStateOk(state))
+        throw new Error("refusing to write an executor state outside the S1 shape");
+    const dir = path.dirname(file);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(dir, 0o700);
+    const tmp = `${file}.${process.pid}.tmp`;
+    const body = `${JSON.stringify({
+        version: state.version,
+        executor_id: state.executor_id,
+        executor_key: state.executor_key,
+        nonce: state.nonce,
+        boot_id: state.boot_id,
+    }, null, 2)}\n`;
+    const fd = fs.openSync(tmp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC, 0o600);
+    try {
+        fs.fchmodSync(fd, 0o600);
+        fs.writeSync(fd, body);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, file);
+}