@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/lib/durable/launch.js

@@ -0,0 +1,443 @@
+/**
+ * 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 { ATTACH_WAIT_S } from "../../vendor/shared/durable-contract/constants.js";
+import { DURABLE_ONLY_PRECONDITION, LOCK_REFUSAL_FIX, lockRefusalFixKey, renderDurableOnly, renderNonTtyLocked, } from "../../vendor/shared/durable-contract/fixlines.js";
+import { sessionNameRefusal } from "../../vendor/shared/durable-contract/names.js";
+import { errorCodeOf, RegistryAnswerError, RegistryUnavailable, } from "./api.js";
+import { shellWord } from "../../commands/durable-lock.js";
+import { DurableRefusal, fixLine } from "./refusal.js";
+import { continueDecision, effectiveOf, liveRow } from "./view.js";
+import { CODE } from "./codes.js";
+/** The env var a launched session carries (lib/agent.ts SESSION_NAME_ENV). */
+export const NESTED_ENV = "MNEMOM_AGENT_SESSION_NAME";
+/**
+ * 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 function durablePreflight(i) {
+    const nested = i.env[NESTED_ENV];
+    if (typeof nested === "string" && nested !== "") {
+        return new DurableRefusal({
+            code: "nested_launch_refused",
+            message: `mnemom agent: a launch from inside a session ('${sanitize(nested)}') is refused; run it from a terminal outside that session`,
+            fix: null,
+        });
+    }
+    if (i.server && i.launcherKey !== "off") {
+        return new DurableRefusal({
+            code: "server_launch_refused",
+            message: "mnemom agent: --server is not available for durable sessions; launch without --server (or set `mnemom agent config set durable off`)",
+            fix: null,
+        });
+    }
+    if (i.name !== undefined) {
+        const why = sessionNameRefusal(i.name);
+        if (why !== null) {
+            return new DurableRefusal({
+                code: "invalid_session_name",
+                message: `mnemom agent: '${sanitize(i.name)}' cannot be a session name (${why})`,
+                fix: null,
+            });
+        }
+    }
+    return null;
+}
+function sanitize(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\u0000-\u001f\u007f‪-‮⁦-⁩]/g, "?").slice(0, 80);
+}
+// ---- passthrough on a registry hit (C01-R22) ---------------------------------------------------
+export function flagValue(argv, flags) {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        for (const f of flags) {
+            if (a === f) {
+                const v = argv[i + 1];
+                return v !== undefined && !v.startsWith("-") ? v : null;
+            }
+            if (a.startsWith(`${f}=`))
+                return a.slice(f.length + 1) || null;
+        }
+    }
+    return 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 function continuePassthrough(passthrough, ccSessionId, goalGiven) {
+    const conflict = (what) => ({
+        ok: false,
+        refusal: new DurableRefusal({
+            code: "session_resume_conflict",
+            message: `mnemom agent: ${what} would move this session to another Claude Code session; continue it without it, or start fresh with --new`,
+            fix: null,
+        }),
+    });
+    if (goalGiven) {
+        return {
+            ok: false,
+            refusal: new DurableRefusal({
+                code: "session_goal_immutable",
+                message: "mnemom agent: a continued session keeps its goal; drop --goal, or start fresh with --new",
+                fix: null,
+            }),
+        };
+    }
+    if (flagValue(passthrough, ["--session-id"]) !== undefined)
+        return conflict("--session-id");
+    if (passthrough.includes("--fork-session"))
+        return conflict("--fork-session");
+    const resumed = flagValue(passthrough, ["--resume", "-r"]);
+    if (typeof resumed === "string" && resumed !== ccSessionId)
+        return conflict("--resume <other id>");
+    const out = [];
+    for (let i = 0; i < passthrough.length; i++) {
+        const a = passthrough[i];
+        if (a === "--continue" || a === "-c")
+            continue;
+        if (a === "--resume" || a === "-r") {
+            if (passthrough[i + 1] === resumed)
+                i++;
+            continue;
+        }
+        if (a.startsWith("--resume="))
+            continue;
+        out.push(a);
+    }
+    return { ok: true, passthrough: out };
+}
+/** A lock refusal code and its cwd_kind, as durable_only_agent's <precondition> reads it. */
+export function lockRefusalOf(r) {
+    if (r === null || !(r.code in LOCK_REFUSAL_FIX))
+        return null;
+    const kind = r.details.cwd_kind;
+    // durable_cwd_not_root picks its clause by cwd_kind; without one there is no clause to print.
+    if (r.code === CODE.durable_cwd_not_root && typeof kind !== "string")
+        return null;
+    const refusal = {
+        code: r.code,
+        ...(typeof kind === "string" ? { cwd_kind: kind } : {}),
+    };
+    // A clause whose path the refusal does not carry (not_git: no checkout) is not printed: every
+    // printed fix line is a working command (C11-R27), never a placeholder.
+    const key = lockRefusalFixKey(refusal);
+    const clause = key === null ? "" : DURABLE_ONLY_PRECONDITION[key];
+    const needs = [...clause.matchAll(/<([a-z_]+)>/g)].map((m) => m[1]);
+    return needs.every((p) => p === "name" || r.fixParams[p] !== undefined) ? refusal : 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 function durableOnlyRefusal(launcherKey, name, lockRefusal, fixParams = {}) {
+    const refusal = lockRefusalOf(lockRefusal);
+    const reason = lockRefusal ? ` (lock refused: ${lockRefusal.code})` : "";
+    return new DurableRefusal({
+        code: CODE.durable_only_agent,
+        message: `mnemom agent: this agent runs durable sessions only, and '${name}' would not end locked${reason}; nothing was started`,
+        fix: renderDurableOnly(launcherKey, { name, refusal, fixParams }),
+    });
+}
+const registryDown = (detail) => new DurableRefusal({
+    code: "session_registry_unavailable",
+    message: `mnemom agent: the session registry is unreachable (${detail}); nothing was started`,
+    fix: null,
+});
+async function wantsLock(i, deps, name) {
+    if (i.launcherKey === "always")
+        return true;
+    if (i.launcherKey === "ask" && i.interactive)
+        return deps.askYesNo(`Make ${name} durable? [y/N]`, false);
+    return false;
+}
+/**
+ * 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 function durableTracked(a) {
+    if (a.status !== 200 || a.body === null || typeof a.body !== "object")
+        return false;
+    const d = a.body.durable;
+    return d !== null && typeof d === "object" && d.tracked === true;
+}
+/**
+ * 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 async function registryRows(d, name) {
+    let ent;
+    try {
+        ent = await d.entitlement();
+    }
+    catch (e) {
+        if (e instanceof RegistryUnavailable)
+            throw registryDown(e.message);
+        throw e;
+    }
+    if (ent.status === 401)
+        throw new RegistryAnswerError(ent);
+    if (ent.status >= 500)
+        throw registryDown(`HTTP ${ent.status}`);
+    if (!durableTracked(ent))
+        return "legacy";
+    try {
+        return await d.listSessions({ name });
+    }
+    catch (e) {
+        if (e instanceof RegistryUnavailable)
+            throw registryDown(e.message);
+        if (e instanceof RegistryAnswerError) {
+            if (e.answer.status === 403 || e.answer.status === 404)
+                return "legacy";
+            if (e.answer.status >= 500)
+                throw registryDown(`HTTP ${e.answer.status}`);
+        }
+        throw e;
+    }
+}
+/**
+ * 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 async function preReadRegistry(d, name) {
+    try {
+        return await registryRows(d, name);
+    }
+    catch (e) {
+        if (e instanceof RegistryAnswerError && e.answer.status === 401)
+            return undefined;
+        throw e;
+    }
+}
+/**
+ * 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 function explicitCidRefusal(rows, explicitCid, name) {
+    if (explicitCid === null)
+        return null;
+    const live = liveRow(rows);
+    if (live === null || live.conversation_id === explicitCid)
+        return null;
+    return new DurableRefusal({
+        code: "session_name_in_use",
+        message: `mnemom agent: '${name}' is already a session on another conversation (${effectiveOf(live)}); drop --conversation-id to continue it, or pick another name`,
+        fix: null,
+        details: {},
+    });
+}
+export async function planDurableLaunch(i, deps) {
+    const rows = i.rows ?? (await registryRows(deps, i.name));
+    if (rows === "legacy")
+        return { kind: "legacy" };
+    const explicitCid = i.explicitConversationId ?? null;
+    const cidRefusal = explicitCidRefusal(rows, explicitCid, i.name);
+    if (cidRefusal !== null)
+        throw cidRefusal;
+    // C02-R24: a launch that would not end locked on a durable-only agent is refused before spawn.
+    const spawnPlan = async (p) => {
+        const durableOnly = await deps.agentDurableOnly();
+        if (durableOnly && !p.lock)
+            throw durableOnlyRefusal(i.launcherKey, i.name, null);
+        return { ...p, durableOnly };
+    };
+    const fresh = async () => {
+        const cc = deps.newId();
+        return spawnPlan({
+            kind: "spawn",
+            conversationId: explicitCid ?? deps.newId(),
+            resumeCcSessionId: null,
+            newCcSessionId: cc,
+            passthrough: [...i.passthrough],
+            register: true,
+            row: null,
+            lock: await wantsLock(i, deps, i.name),
+        });
+    };
+    if (i.newFlag) {
+        const live = liveRow(rows);
+        if (live !== null) {
+            throw new DurableRefusal({
+                code: "session_name_in_use",
+                message: `mnemom agent: '${i.name}' is already a session (${effectiveOf(live)}); end it with \`mnemom agent done ${i.name}\` or \`mnemom agent kill ${i.name}\`, or pick another name`,
+                fix: null,
+                details: {},
+            });
+        }
+        return fresh();
+    }
+    const d = continueDecision({
+        rows,
+        launcherKey: i.launcherKey,
+        home: i.home,
+        daemonLoaded: deps.daemonLoaded(),
+        agentKilled: false,
+        explicitAgentId: i.explicitAgentId,
+    });
+    switch (d.kind) {
+        case "fresh":
+            return fresh();
+        case "refuse":
+            throw new DurableRefusal({
+                code: d.code,
+                message: d.message,
+                fix: d.fix,
+                details: d.details,
+            });
+        case "attach":
+            return { kind: "attach", row: d.row, wait: d.wait };
+        case "tracked_continue": {
+            const row = d.row;
+            const cc = typeof row.cc_session_id === "string" ? row.cc_session_id : null;
+            const pt = continuePassthrough(i.passthrough, cc, i.goalGiven);
+            if (!pt.ok)
+                throw pt.refusal;
+            if (cc === null || !deps.transcriptExists(cc)) {
+                // C01-R02: mark it failed (owner route), then refuse with the --new line (name now free).
+                await deps.failTracked(row);
+                throw new DurableRefusal({
+                    code: "session_transcript_missing",
+                    message: `mnemom agent: Claude Code no longer has the transcript of '${i.name}'; the session is marked failed`,
+                    fix: fixLine("session_transcript_missing", i.launcherKey, false, { name: i.name }),
+                });
+            }
+            return spawnPlan({
+                kind: "spawn",
+                conversationId: row.conversation_id,
+                resumeCcSessionId: cc,
+                newCcSessionId: null,
+                passthrough: pt.passthrough,
+                register: false,
+                row,
+                lock: i.launcherKey === "always",
+            });
+        }
+    }
+}
+// ---- lock refused on the launcher path (C02-R23 c, e; C02-R24) ---------------------------------
+/**
+ * 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 function afterLockRefusal(refusal, durableOnly, launcherKey, name) {
+    if (!durableOnly)
+        return { print: refusal, exit: null };
+    // cwd_untrusted is CLI-local (no S1 precondition clause): a durable-only launch prints it as itself,
+    // its fix shaped for the launch (rerun it), not for `mnemom agent lock`.
+    const root = refusal.details.cwd;
+    if (refusal.code === "cwd_untrusted" && typeof root === "string") {
+        const r = new DurableRefusal({
+            code: "cwd_untrusted",
+            message: `${name}: Claude Code has not been trusted in ${root}, so the durable seat would stop at its trust dialog; nothing was started`,
+            fix: `run \`cd ${shellWord(root)} && claude\` once, accept the trust dialog, then rerun \`mnemom agent ${name} --new\``,
+            details: { cwd: root },
+        });
+        return { print: r, exit: r.exit };
+    }
+    const r = durableOnlyRefusal(launcherKey, name, refusal, refusal.fixParams);
+    return { print: r, exit: r.exit };
+}
+// ---- lock after the first turn (dogfood B5) -----------------------------------------------------
+/**
+ * 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 function locksAfterFirstTurn(plan) {
+    return plan.lock && plan.newCcSessionId !== null;
+}
+/** The row the first-turn lock commits: the registered row, naming the CC session this launch pins. */
+export function firstTurnRow(row, plan) {
+    return typeof row.cc_session_id === "string"
+        ? row
+        : { ...row, cc_session_id: plan.newCcSessionId };
+}
+// ---- registration (C01-R05) ---------------------------------------------------------------------
+/** The create body the CLI sends (A2 owns the route; see notes-c1.md). */
+export function createBody(name, ccSessionId, cwd) {
+    return { name, cc_session_id: ccSessionId, cwd };
+}
+/** A create answer: the row, or a refusal (409 session_name_in_use and the rest). */
+export function createOutcome(a, name) {
+    if (a.status === 200 || a.status === 201) {
+        const b = (a.body ?? {});
+        const row = (b.session ?? b);
+        return row;
+    }
+    const code = errorCodeOf(a.body) ?? `http_${a.status}`;
+    if (code === "session_name_in_use") {
+        return new DurableRefusal({
+            code,
+            message: `mnemom agent: '${name}' is already a session; end it with \`mnemom agent done ${name}\` or \`mnemom agent kill ${name}\`, or pick another name`,
+            fix: null,
+            apiBody: a.body,
+        });
+    }
+    if (code === CODE.durable_only_agent) {
+        // Another session is locked on this agent (walk5): say what to do with it, not just "refused".
+        return new DurableRefusal({
+            code,
+            message: `mnemom agent: this agent already has a locked session, so '${name}' was not started; finish that one with \`mnemom agent done <name>\` or carry on in it with \`mnemom agent <name>\` (\`mnemom agent sessions\` lists it), or start '${name}' on another agent with \`--agent\``,
+            fix: null,
+            apiBody: a.body,
+        });
+    }
+    return new DurableRefusal({
+        code,
+        message: `mnemom agent: the session registry refused '${name}' (${a.status})`,
+        fix: null,
+        apiBody: a.body,
+    });
+}
+/** The poll interval of the seat wait. */
+export 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 async function attachToSeat(row, name, droppedFlags, deps) {
+    if (!deps.interactive) {
+        deps.out(renderNonTtyLocked(name, droppedFlags));
+        return 0;
+    }
+    const deadline = deps.now() + ATTACH_WAIT_S * 1000;
+    for (;;) {
+        const seat = await deps.findSeat(row);
+        if (seat !== null) {
+            const status = deps.attach(seat);
+            // tmux attach exits non-zero only when it could not attach (a detach exits 0); say how back in.
+            if (status !== 0)
+                deps.err(`couldn't attach to ${name}; to get back to it run: mnemom agent ${name}`);
+            return status;
+        }
+        if (deps.now() >= deadline)
+            break;
+        await deps.sleep(SEAT_POLL_MS);
+    }
+    throw new DurableRefusal({
+        code: "seat_wait_timeout",
+        message: `${name} is locked; the host daemon will start it`,
+        fix: fixLine("seat_wait_timeout", deps.launcherKey, true, { name }),
+    });
+}

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

@@ -0,0 +1,15 @@
+/** A mark older than this is a launch that died without clearing it. */
+export declare const LAUNCHING_MAX_AGE_MS: number;
+export interface LaunchingDeps {
+    readonly dir: string;
+    read(path: string): string | null;
+    write(path: string, body: string): void;
+    remove(path: string): void;
+    alive(pid: number): boolean;
+    now(): number;
+}
+export declare function markLaunching(name: string, pid: number, d: LaunchingDeps): void;
+export declare function clearLaunching(name: string, d: LaunchingDeps): void;
+/** True while a live launch of `name` started under LAUNCHING_MAX_AGE_MS ago holds the mark. */
+export declare function launchingNow(name: string, d: LaunchingDeps): boolean;
+export declare const liveLaunchingDeps: (mnemomDir: string) => LaunchingDeps;

package/dist/lib/durable/launching.js

@@ -0,0 +1,70 @@
+/**
+ * The launch-start marker (dogfood walk5 leg A): a durable `mnemom agent <name>` launch marks the
+ * name as starting before it registers its session, and clears the mark once the session is
+ * registered or the launch exits. A lock that finds no session by that name while the mark is
+ * live answers "start a first turn, then lock" instead of agent_not_found, which reads like a
+ * typo in the name. The launch ledger cannot do this: its record is written after registration.
+ *
+ * Pure over injected deps; liveLaunchingDeps wires the real filesystem and process table.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** A mark older than this is a launch that died without clearing it. */
+export const LAUNCHING_MAX_AGE_MS = 10 * 60 * 1000;
+const markPath = (dir, name) => join(dir, `${encodeURIComponent(name)}.json`);
+export function markLaunching(name, pid, d) {
+    d.write(markPath(d.dir, name), JSON.stringify({ pid, started_at: d.now() }));
+}
+export function clearLaunching(name, d) {
+    d.remove(markPath(d.dir, name));
+}
+/** True while a live launch of `name` started under LAUNCHING_MAX_AGE_MS ago holds the mark. */
+export function launchingNow(name, d) {
+    const raw = d.read(markPath(d.dir, name));
+    if (raw === null)
+        return false;
+    let m;
+    try {
+        m = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (typeof m !== "object" || m === null)
+        return false;
+    const { pid, started_at } = m;
+    if (typeof pid !== "number" || typeof started_at !== "number")
+        return false;
+    if (d.now() - started_at > LAUNCHING_MAX_AGE_MS)
+        return false;
+    return d.alive(pid);
+}
+export const liveLaunchingDeps = (mnemomDir) => {
+    const dir = join(mnemomDir, "durable", "launching");
+    return {
+        dir,
+        read: (p) => {
+            try {
+                return readFileSync(p, "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+        write: (p, body) => {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            writeFileSync(p, body, { mode: 0o600 });
+        },
+        remove: (p) => rmSync(p, { force: true }),
+        alive: (pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (e) {
+                return e.code === "EPERM";
+            }
+        },
+        now: () => Date.now(),
+    };
+};