@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/host/transcript.js

@@ -0,0 +1,130 @@
+/**
+ * The transcript guard (C12-R16, R38; BACKBONE C2 "Transcript guard"). For every locked,
+ * non-terminal session homed here the daemon keeps a hard link to the Claude Code transcript at
+ * the S1 guard path, so Claude Code's own cleanup cannot lose it. On EXDEV it keeps a copy.
+ * Before every `--resume` a missing original is restored from the guard. It never writes any
+ * Claude settings file.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { transcriptGuardPath } from "../vendor/shared/durable-contract/paths.js";
+export function ccProjectsDir(env, home = os.homedir()) {
+    return path.join((env.CLAUDE_CONFIG_DIR ?? "").trim() || path.join(home, ".claude"), "projects");
+}
+/** Claude Code's project folder name for a cwd: every non-alphanumeric character becomes '-'. */
+export const projectSlug = (cwd) => cwd.replace(/[^a-zA-Z0-9]/g, "-");
+export function expectedTranscriptPath(projectsDir, cwd, ccSessionId) {
+    return path.join(projectsDir, projectSlug(cwd), `${ccSessionId}.jsonl`);
+}
+/** The transcript as it is on disk now: the cwd's project folder first, then any project folder. */
+export function findTranscript(projectsDir, cwd, ccSessionId) {
+    if (cwd) {
+        const p = expectedTranscriptPath(projectsDir, cwd, ccSessionId);
+        if (fs.existsSync(p))
+            return p;
+    }
+    try {
+        for (const d of fs.readdirSync(projectsDir)) {
+            const p = path.join(projectsDir, d, `${ccSessionId}.jsonl`);
+            if (fs.existsSync(p))
+                return p;
+        }
+    }
+    catch {
+        /* no projects dir */
+    }
+    return null;
+}
+/** Create or refresh the guard for one session. Returns the mode now held (null when there is nothing to guard). */
+export function refreshGuard(home, sessionId, original) {
+    const guard = transcriptGuardPath(home, sessionId);
+    if (!original || !fs.existsSync(original)) {
+        return { mode: fs.existsSync(guard) ? currentMode(guard) : null, guardPath: guard };
+    }
+    fs.mkdirSync(path.dirname(guard), { recursive: true, mode: 0o700 });
+    const o = fs.statSync(original);
+    let g;
+    try {
+        g = fs.statSync(guard);
+    }
+    catch {
+        g = null;
+    }
+    if (g && g.ino === o.ino && g.dev === o.dev)
+        return { mode: "link", guardPath: guard };
+    // A copy is current while size and mtime match (EXDEV mode).
+    if (g &&
+        g.nlink === 1 &&
+        o.dev !== g.dev &&
+        g.size === o.size &&
+        Math.trunc(g.mtimeMs) === Math.trunc(o.mtimeMs)) {
+        return { mode: "copy", guardPath: guard };
+    }
+    const tmp = `${guard}.${process.pid}.tmp`;
+    try {
+        fs.rmSync(tmp, { force: true });
+        fs.linkSync(original, tmp);
+        fs.renameSync(tmp, guard);
+        return { mode: "link", guardPath: guard };
+    }
+    catch (e) {
+        fs.rmSync(tmp, { force: true });
+        if (e.code !== "EXDEV")
+            throw e;
+    }
+    fs.copyFileSync(original, tmp);
+    fs.chmodSync(tmp, 0o600);
+    fs.utimesSync(tmp, o.atime, o.mtime);
+    fs.renameSync(tmp, guard);
+    return { mode: "copy", guardPath: guard };
+}
+function currentMode(guard) {
+    try {
+        return fs.statSync(guard).nlink > 1 ? "link" : "copy";
+    }
+    catch {
+        return "link";
+    }
+}
+/**
+ * Before a `--resume`: the original exists, or it is restored from the guard (a new hard link,
+ * or a copy across volumes), or both are missing (transcript_lost).
+ */
+export function ensureTranscript(home, sessionId, projectsDir, cwd, ccSessionId, lastKnown) {
+    const found = findTranscript(projectsDir, cwd, ccSessionId);
+    if (found)
+        return { kind: "present", path: found };
+    const guard = transcriptGuardPath(home, sessionId);
+    if (!fs.existsSync(guard))
+        return { kind: "lost" };
+    const target = lastKnown ?? (cwd ? expectedTranscriptPath(projectsDir, cwd, ccSessionId) : null);
+    if (!target)
+        return { kind: "lost" };
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    try {
+        fs.linkSync(guard, target);
+    }
+    catch (e) {
+        if (e.code !== "EXDEV")
+            throw e;
+        fs.copyFileSync(guard, target);
+    }
+    return { kind: "restored", path: target };
+}
+export function removeGuard(home, sessionId) {
+    fs.rmSync(transcriptGuardPath(home, sessionId), { force: true });
+}
+/** Session ids that have a guard file. */
+export function guardedSessionIds(home) {
+    const dir = path.dirname(transcriptGuardPath(home, "00000000-0000-0000-0000-000000000000"));
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith(".jsonl"))
+            .map((f) => f.slice(0, -6));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/host/verbs.d.ts

@@ -0,0 +1,50 @@
+import { type LockResult } from "./lock.js";
+import { type Launchctl } from "./launchd.js";
+import { type OwnerApi, type ExecutorRow } from "./owner.js";
+export declare const INSTALL_FIX = "`mnemom agent host install`";
+export declare const UNINSTALL_SESSION_LINE: (name: string) => string;
+export interface VerbIo {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly home: string;
+    readonly uid: number;
+    readonly json: boolean;
+    readonly out: (line: string) => void;
+    readonly err: (line: string) => void;
+    readonly owner: OwnerApi;
+    readonly launchctl: Launchctl;
+    readonly now: () => number;
+    readonly bootId: () => string;
+    /** The daemon's ProgramArguments (absolute node + CLI entry + agent host run). */
+    readonly programArguments: () => string[];
+    readonly claudeBin: () => string | null;
+    readonly pollSleep?: (ms: number) => Promise<void>;
+    /** Takes the enrollment lock; acquireHostLock (macOS flock) when absent. */
+    readonly acquireLock?: (lockFile: string) => LockResult;
+}
+/** Fresh-invocation gate for every host verb (C12-R25): exit 2 with the gated text, nothing else. */
+export declare function freshGate(io: VerbIo): number | null;
+export type Liveness = {
+    kind: "live";
+    row: ExecutorRow;
+} | {
+    kind: "lapsed";
+    row: ExecutorRow;
+} | {
+    kind: "gone";
+} | {
+    kind: "unknown";
+    why: string;
+};
+export declare function executorLiveness(io: VerbIo, executorId: string): Promise<Liveness>;
+/** The S1 risk line (BACKBONE amendment 27): human text, or a JSON event in --json mode. Recorded nowhere. */
+export declare function printRiskLine(io: VerbIo): void;
+/** The device step: start, show the code, poll, write the state file. Returns an exit code. */
+export declare function enrollDevice(io: VerbIo, opts?: {
+    label?: string;
+}): Promise<number>;
+/** Write the plist and (re)load the job. */
+export declare function writeAndLoad(io: VerbIo): Promise<number>;
+export declare function hostInstall(io: VerbIo): Promise<number>;
+export declare function hostEnroll(io: VerbIo): Promise<number>;
+export declare function hostRenew(io: VerbIo): Promise<number>;
+export declare function hostUninstall(io: VerbIo): Promise<number>;

package/dist/host/verbs.js

@@ -0,0 +1,271 @@
+/**
+ * `mnemom agent host install | enroll | renew | uninstall` (C04, C12-R22, R24, R40; BACKBONE C2).
+ *
+ * install: gate (config.json only, R40) -> a live enrollment in the state file reloads the job
+ * (no device step, C04-R19); a lapsed grant prints the renew fix and stops; a missing state file
+ * or a revoked executor enrolls through the device step. Then the plist is written and the job
+ * (re)loaded. The S1 risk line is printed and recorded nowhere locally.
+ * enroll: the device step alone (writes the state file), under its own lock so a second
+ * concurrent enroll starts nothing (C04-CH-FLOCK).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { RISK_LINE_TEXT } from "../vendor/shared/durable-contract/fixlines.js";
+import { EXECUTOR_STATE_VERSION } from "../vendor/shared/durable-contract/executor-state.js";
+import { TERMINAL_STATES } from "../vendor/shared/durable-contract/states.js";
+import { RISK_LINE_VERSION } from "../vendor/shared/durable-contract/constants.js";
+import { resolveInstance, hostPaths } from "./instance.js";
+import { installGate, durableOnFresh, GATED_TEXT } from "./gate.js";
+import { readExecutorState, writeExecutorState, newNonce } from "./state.js";
+import { acquireHostLock } from "./lock.js";
+import { renderPlist } from "./plist.js";
+import { loadJob, unloadJob } from "./launchd.js";
+import { classifyPoll, parseEnrollStart, parseExecutorList, EXECUTOR_CONTRACT, } from "./owner.js";
+import { readRuntime } from "./runtime.js";
+import { RENEW_FIX, GRANT_EXPIRED_LINE } from "./grant.js";
+export const INSTALL_FIX = "`mnemom agent host install`";
+export const UNINSTALL_SESSION_LINE = (name) => `${name}: they stop restarting until ${INSTALL_FIX}`;
+const ctx = (io) => {
+    const instance = resolveInstance(io.env);
+    return { instance, paths: hostPaths(io.home, instance) };
+};
+/** Fresh-invocation gate for every host verb (C12-R25): exit 2 with the gated text, nothing else. */
+export function freshGate(io) {
+    const { paths } = ctx(io);
+    if (durableOnFresh(paths.configFile, io.env))
+        return null;
+    io.err(GATED_TEXT);
+    return 2;
+}
+export async function executorLiveness(io, executorId) {
+    const r = await io.owner.list();
+    if (r.status !== 200)
+        return { kind: "unknown", why: r.networkError ?? `http ${r.status}` };
+    const rows = parseExecutorList(r.body);
+    if (!rows)
+        return { kind: "unknown", why: "unreadable executor list" };
+    const row = rows.find((x) => x.id === executorId.toLowerCase());
+    if (!row || row.revoked)
+        return { kind: "gone" };
+    if (row.grantExpiresAt !== null && row.grantExpiresAt <= io.now())
+        return { kind: "lapsed", row };
+    return { kind: "live", row };
+}
+/** The S1 risk line (BACKBONE amendment 27): human text, or a JSON event in --json mode. Recorded nowhere. */
+export function printRiskLine(io) {
+    if (io.json)
+        io.out(JSON.stringify({ event: "risk_line", text: RISK_LINE_TEXT, version: RISK_LINE_VERSION }));
+    else
+        io.out(RISK_LINE_TEXT);
+}
+/** The device step: start, show the code, poll, write the state file. Returns an exit code. */
+export async function enrollDevice(io, opts = {}) {
+    const { paths } = ctx(io);
+    const lock = (io.acquireLock ?? acquireHostLock)(path.join(paths.durableDir, "enroll.lock"));
+    if (!lock.ok) {
+        io.err(`mnemom agent host: an enrollment is already in progress here (${lock.reason}): wait for it, then ${INSTALL_FIX}`);
+        return 1;
+    }
+    try {
+        const st = await io.owner.enrollStart({
+            kind: "host",
+            runtime: "node",
+            contract_version: EXECUTOR_CONTRACT,
+            ...(opts.label ? { machine_label: opts.label } : {}),
+        });
+        const start = st.status === 202 || st.status === 200 || st.status === 201
+            ? parseEnrollStart(st.body)
+            : null;
+        if (!start) {
+            const code = st.body && typeof st.body === "object"
+                ? JSON.stringify(st.body).slice(0, 300)
+                : String(st.status);
+            io.err(`could not start the enrollment (${st.networkError ?? code}). Sign in with \`mnemom login\`, then ${INSTALL_FIX}`);
+            return 1;
+        }
+        printRiskLine(io);
+        if (io.json)
+            io.out(JSON.stringify({
+                event: "enroll_started",
+                user_code: start.userCode,
+                verification_uri_complete: start.verificationUri,
+                expires_in: start.expiresIn,
+            }));
+        else {
+            io.out(`Approve this machine in your browser: ${start.verificationUri}`);
+            io.out(`Code: ${start.userCode}`);
+        }
+        const nap = io.pollSleep ?? ((ms) => sleep(ms));
+        let interval = start.interval * 1000;
+        const until = io.now() + start.expiresIn * 1000 + 5000;
+        while (io.now() < until) {
+            await nap(interval);
+            const p = classifyPoll(await io.owner.enrollPoll(start.pollSecret, start.approvalId));
+            if (p.kind === "pending")
+                continue;
+            if (p.kind === "slow_down") {
+                interval += 5000;
+                continue;
+            }
+            if (p.kind === "terminal") {
+                io.err(`enrollment ${p.error.replace(/_/g, " ")}: run ${INSTALL_FIX} again`);
+                return 1;
+            }
+            writeExecutorState(paths.stateFile, {
+                version: EXECUTOR_STATE_VERSION,
+                executor_id: p.executorId,
+                executor_key: p.executorKey,
+                nonce: newNonce(),
+                boot_id: io.bootId(),
+            });
+            if (io.json)
+                io.out(JSON.stringify({ event: "enrolled", executor_id: p.executorId }));
+            else
+                io.out(`Enrolled this machine (executor ${p.executorId.slice(0, 8)}).`);
+            return 0;
+        }
+        io.err(`enrollment expired_token: run ${INSTALL_FIX} again`);
+        return 1;
+    }
+    finally {
+        fs.closeSync(lock.fd);
+    }
+}
+/** Write the plist and (re)load the job. */
+export async function writeAndLoad(io) {
+    const { instance, paths } = ctx(io);
+    const claude = io.claudeBin();
+    if (!claude) {
+        io.err("claude was not found on PATH: install Claude Code, or set MNEMOM_AGENT_CLI to its absolute path");
+        return 1;
+    }
+    fs.mkdirSync(paths.logDir, { recursive: true, mode: 0o700 });
+    fs.mkdirSync(path.dirname(paths.plistFile), { recursive: true });
+    const text = renderPlist({
+        label: instance.label,
+        programArguments: io.programArguments(),
+        home: io.home,
+        path: io.env.PATH ?? "/usr/bin:/bin:/usr/sbin:/sbin",
+        claudeBin: claude,
+        logFile: path.join(paths.logDir, "daemon.log"),
+        env: io.env,
+    });
+    const tmp = `${paths.plistFile}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, text, { mode: 0o644 });
+    fs.renameSync(tmp, paths.plistFile);
+    const r = await loadJob(io.launchctl, io.uid, instance.label, paths.plistFile);
+    if (r.code !== 0) {
+        io.err(`launchctl bootstrap failed (${r.code}): ${r.stderr.trim()}`);
+        return 1;
+    }
+    return 0;
+}
+export async function hostInstall(io) {
+    const { paths } = ctx(io);
+    const g = installGate(paths.configFile, io.env);
+    if (!g.ok) {
+        io.err(g.message);
+        return g.exit;
+    }
+    const st = readExecutorState(paths.stateFile);
+    let reload = false;
+    if (st.kind === "ok") {
+        const l = await executorLiveness(io, st.state.executor_id);
+        if (l.kind === "lapsed") {
+            io.err(GRANT_EXPIRED_LINE);
+            return 1;
+        }
+        if (l.kind === "live")
+            reload = true;
+        else if (l.kind === "unknown") {
+            // Cannot ask the server: keep the enrollment; the daemon's claims answer for it.
+            io.err(`could not check this machine's enrollment (${l.why}); reloading on the existing enrollment`);
+            reload = true;
+        }
+    }
+    if (!reload) {
+        const e = await enrollDevice(io);
+        if (e !== 0)
+            return e;
+    }
+    else
+        printRiskLine(io);
+    const loaded = await writeAndLoad(io);
+    if (loaded !== 0)
+        return loaded;
+    if (io.json)
+        io.out(JSON.stringify({ event: "installed", reloaded: reload, plist: paths.plistFile }));
+    else
+        io.out(reload ? "Host daemon reloaded on this machine's enrollment." : "Host daemon installed.");
+    return 0;
+}
+export async function hostEnroll(io) {
+    return enrollDevice(io);
+}
+export async function hostRenew(io) {
+    const { paths } = ctx(io);
+    const st = readExecutorState(paths.stateFile);
+    if (st.kind !== "ok") {
+        io.err(`this machine is not enrolled: ${INSTALL_FIX}`);
+        return 1;
+    }
+    const r = await io.owner.renew(st.state.executor_id);
+    const start = r.status === 202 || r.status === 200 ? parseEnrollStart(r.body) : null;
+    if (!start) {
+        io.err(`renewal refused (${r.networkError ?? `http ${r.status}`})`);
+        return 1;
+    }
+    if (io.json)
+        io.out(JSON.stringify({
+            event: "renew_started",
+            user_code: start.userCode,
+            verification_uri_complete: start.verificationUri,
+            expires_in: start.expiresIn,
+        }));
+    else {
+        io.out(`Approve the renewal in your browser: ${start.verificationUri}`);
+        io.out(`Code: ${start.userCode}`);
+    }
+    const nap = io.pollSleep ?? ((ms) => sleep(ms));
+    const until = io.now() + start.expiresIn * 1000 + 5000;
+    while (io.now() < until) {
+        await nap(start.interval * 1000);
+        const l = await executorLiveness(io, st.state.executor_id);
+        if (l.kind === "live" && l.row.grantExpiresAt !== null && l.row.grantExpiresAt > io.now()) {
+            if (io.json)
+                io.out(JSON.stringify({
+                    event: "renewed",
+                    grant_expires_at: new Date(l.row.grantExpiresAt).toISOString(),
+                }));
+            else
+                io.out(`Grant renewed until ${new Date(l.row.grantExpiresAt).toISOString()}.`);
+            return 0;
+        }
+        if (l.kind === "gone") {
+            io.err(`this machine's executor was revoked: ${INSTALL_FIX}`);
+            return 1;
+        }
+    }
+    io.err(`renewal not approved in time: ${RENEW_FIX}`);
+    return 1;
+}
+export async function hostUninstall(io) {
+    const { instance, paths } = ctx(io);
+    const had = fs.existsSync(paths.plistFile);
+    const wasLoaded = await unloadJob(io.launchctl, io.uid, instance.label);
+    fs.rmSync(paths.plistFile, { force: true });
+    if (!had && !wasLoaded) {
+        io.out("The host daemon is not installed here.");
+        return 0;
+    }
+    io.out("Host daemon uninstalled. Seats keep running; this machine stays enrolled.");
+    const rt = readRuntime(paths.runtimeFile);
+    const terminal = new Set(TERMINAL_STATES);
+    for (const s of rt?.sessions ?? []) {
+        if (s.state && terminal.has(s.state))
+            continue;
+        io.out(UNINSTALL_SESSION_LINE(s.name ?? s.id));
+    }
+    return 0;
+}

package/dist/index.d.ts

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 import "./lib/retired-env-guard.js";
-import { program, type Command } from "commander";
-/**
- * The durable-gated commands (BACKBONE Flags/CLI: off lists no durable verb). The committed
- * command-tree.json leaves them out whatever the generating machine's experimental state
- * (scripts/gen-command-tree.mjs); a piece that registers another durable verb adds it here.
- */
+import { program, Option, type Command } from "commander";
+import { type OptionShapes } from "./lib/durable/gate.js";
 export declare const DURABLE_GATED_COMMANDS: ReadonlySet<Command>;
+export declare const DURABLE_GATED_OPTIONS: ReadonlySet<Option>;
 export { program };
+/**
+ * The value-taking options of the program, `agent` and `agent sessions`: the durable gate steps over
+ * them (and their values) to find the verb word, as commander does before it dispatches.
+ */
+export declare function agentOptionShapes(): OptionShapes;
 /**
  * The entrypoint dispatch. `mnemom agent slack …` owns its own flags (--thread,
  * --channel, …), which the `agent` launcher options would otherwise reject as