@mnemom/mnemom 0.17.20-next.0 → 0.17.21

package/dist/rc-state.mjs

@@ -0,0 +1,257 @@
+// rc-state — where `mnemom agent --remote-control` keeps its per-session dirs, and the sweep that
+// clears the ones a dead session left behind. Imported by rc-proxy.mjs; commands/agent.ts mirrors
+// rcStateRoot() for the launcher's log dir (tsc emits no .mjs, so it cannot import this file).
+//
+// WHY NOT THE OS TEMP DIR
+// The proxy's ephemeral CA must stay on disk for the whole session: Claude Code's
+// NODE_EXTRA_CA_CERTS points at ca.pem, and every leaf rotation re-reads ca.pem and leaf.ext.
+// OS temp dirs are cleaned behind a running process — macOS's dirhelper deletes $TMPDIR files
+// not accessed for 3 days, and systemd-tmpfiles ages out /tmp on Linux — which broke every RC
+// session older than ~3-4 days with UNABLE_TO_VERIFY_LEAF_SIGNATURE (2026-10-03). So the dirs
+// live under the CLI's per-user state dir, ~/.mnemom (the convention auth.json, config.json and
+// sessions.jsonl already follow on every platform), which nothing cleans. In exchange nothing
+// cleans up after a crashed session either: each dir records its owner's pid in OWNER_FILE, and
+// every proxy start sweeps the dirs whose owner is dead.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Every per-session dir under the root starts with one of these: the CA dir, the log dir. */
+export const RC_DIR_PREFIXES = ["mnemom-code-rc-ca-", "mnemom-code-rc."];
+/** The pid of the process that owns (and removes on exit) the dir it sits in. */
+export const OWNER_FILE = "owner.pid";
+
+/** ~/.mnemom/rc on every platform. */
+export function rcStateRoot(home = os.homedir()) {
+  return path.join(home, ".mnemom", "rc");
+}
+
+/**
+ * Create the root 0700 (and its parents) and return it. Throws when the home dir is not writable;
+ * the caller falls back to the OS temp dir, where the keep-alive in rc-proxy.mjs still applies.
+ */
+export function ensureRcStateRoot(root = rcStateRoot()) {
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  fs.chmodSync(root, 0o700); // mkdir's mode is filtered through the umask, and skips an existing dir
+  return root;
+}
+
+/** Signal 0 probes without signalling. EPERM means it exists but is someone else's: alive. */
+export function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+
+// Open flags. O_NOFOLLOW / O_DIRECTORY / O_NONBLOCK are POSIX-only; on Windows they are absent from
+// fs.constants and count as 0 (no symlink race to close there: no POSIX modes, per-user profile).
+const C = fs.constants;
+const NOFOLLOW = C.O_NOFOLLOW || 0;
+const DIRECTORY = C.O_DIRECTORY || 0;
+const NONBLOCK = C.O_NONBLOCK || 0; // a FIFO planted under a known name must not block the open
+
+/** This process's uid, or null where there is none (native Windows): no owner check there. */
+export function currentUid(proc = process) {
+  return typeof proc.getuid === "function" ? proc.getuid() : null;
+}
+
+/**
+ * Read a regular file without following a symlink at its last component (O_NOFOLLOW), checking
+ * the type on the OPEN fd. Returns null when it is missing, a symlink, or not a regular file.
+ */
+export function readNoFollow(file, { fsImpl = fs } = {}) {
+  let fd;
+  try {
+    fd = fsImpl.openSync(file, C.O_RDONLY | NOFOLLOW | NONBLOCK);
+  } catch {
+    return null;
+  }
+  try {
+    return fsImpl.fstatSync(fd).isFile() ? fsImpl.readFileSync(fd) : null;
+  } finally {
+    fsImpl.closeSync(fd);
+  }
+}
+
+/**
+ * Set atime/mtime through an fd opened without following a symlink, so a planted link never moves
+ * its target's times. Returns false (and touches nothing) when the entry is missing or a symlink.
+ */
+export function touchNoFollow(file, now, { fsImpl = fs } = {}) {
+  let fd;
+  try {
+    fd = fsImpl.openSync(file, C.O_RDONLY | NOFOLLOW | NONBLOCK);
+  } catch {
+    return false;
+  }
+  try {
+    fsImpl.futimesSync(fd, now, now);
+    return true;
+  } finally {
+    fsImpl.closeSync(fd);
+  }
+}
+
+/** Write `bytes` to `dir/name` via a fresh O_EXCL|O_NOFOLLOW temp file, then rename it in. */
+function writeAtomic(fsImpl, dir, name, bytes, mode) {
+  const tmp = path.join(
+    dir,
+    `.${name}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`,
+  );
+  // O_EXCL: the temp name must not exist, so nothing planted there (a symlink included) is followed.
+  const fd = fsImpl.openSync(tmp, C.O_WRONLY | C.O_CREAT | C.O_EXCL | NOFOLLOW, mode);
+  try {
+    let off = 0;
+    while (off < bytes.length) off += fsImpl.writeSync(fd, bytes, off, bytes.length - off);
+    fsImpl.fchmodSync(fd, mode); // the open's mode is filtered through the umask
+  } finally {
+    fsImpl.closeSync(fd);
+  }
+  // Write-then-rename, so a reader (openssl, a starting Claude Code) never sees half a file.
+  fsImpl.renameSync(tmp, path.join(dir, name));
+}
+
+const refuse = (dir) =>
+  new Error(`refusing to reuse ${dir}: not a private directory owned by this user`);
+
+/**
+ * Keep `dir` and its long-lived `files` ([name, bytes, mode] triples) present and fresh, against an
+ * OS cleaner that deletes what it has not seen accessed. Creates `dir` 0700 if it is gone, restores
+ * any file that is missing or differs (byte-identical, same path), and refreshes the atime/mtime of
+ * the dir, everything in it, and `logfile` (if any). Returns the names it restored ("dir" first if
+ * it had to recreate the dir).
+ *
+ * The dir decides what CA Claude Code trusts, so nothing here acts on a path it checked earlier:
+ *   * the dir is opened ONCE without following a symlink (O_NOFOLLOW|O_DIRECTORY) and checked on
+ *     that fd: a real directory, owned by this uid, with no group/other bits. A symlink, a file or
+ *     a foreign/non-private dir at `dir` is refused (throws), and nothing is read or written.
+ *   * every file read and every atime refresh opens the entry without following a symlink and
+ *     checks the open fd; every write goes to a fresh O_EXCL|O_NOFOLLOW temp file and is renamed in.
+ *   * Node has no openat(), so the per-file opens still resolve `dir` by path. Before returning, the
+ *     path is checked to still name the directory the held fd was validated on (dev + inode); if
+ *     anything swapped it in between, this throws. Who could swap it: the parent is ~/.mnemom/rc
+ *     (0700, ours) or, in the fallback, the OS temp dir, whose sticky bit stops another user from
+ *     replacing a dir we own; the fd check covers the case where it was deleted and re-planted.
+ */
+export function keepPrivateDir(
+  dir,
+  files,
+  {
+    logfile = "",
+    now = new Date(),
+    fsImpl = fs,
+    uid = currentUid(),
+    platform = process.platform,
+  } = {},
+) {
+  const restored = [];
+  let created = false;
+  try {
+    fsImpl.mkdirSync(path.dirname(dir), { recursive: true, mode: 0o700 });
+    fsImpl.mkdirSync(dir, { mode: 0o700 });
+    created = true;
+    restored.push("dir");
+  } catch (e) {
+    if (e.code !== "EEXIST") throw e;
+  }
+  let dfd;
+  try {
+    dfd = fsImpl.openSync(dir, C.O_RDONLY | DIRECTORY | NOFOLLOW);
+  } catch (e) {
+    // ELOOP: a symlink; ENOTDIR: a file (O_DIRECTORY). Either way not a dir we made.
+    if (e.code === "ELOOP" || e.code === "ENOTDIR") throw refuse(dir);
+    throw e;
+  }
+  try {
+    const st = fsImpl.fstatSync(dfd);
+    if (!st.isDirectory() || (uid !== null && st.uid !== uid)) throw refuse(dir);
+    if (created)
+      fsImpl.fchmodSync(dfd, 0o700); // mkdir's mode is filtered through the umask
+    else if (platform !== "win32" && (st.mode & 0o077) !== 0) throw refuse(dir); // no POSIX modes there
+    for (const [name, bytes, mode] of files) {
+      const cur = readNoFollow(path.join(dir, name), { fsImpl });
+      if (cur && cur.equals(bytes)) continue;
+      writeAtomic(fsImpl, dir, name, bytes, mode);
+      restored.push(name);
+    }
+    for (const f of fsImpl.readdirSync(dir)) {
+      // false: removed under us (e.g. ca.key between sign and rm), or a symlink: nothing to keep alive.
+      touchNoFollow(path.join(dir, f), now, { fsImpl });
+    }
+    fsImpl.futimesSync(dfd, now, now);
+    const at = fsImpl.lstatSync(dir);
+    const held = fsImpl.fstatSync(dfd);
+    if (at.dev !== held.dev || at.ino !== held.ino)
+      throw new Error(`${dir} was replaced while it was being kept alive`);
+  } finally {
+    fsImpl.closeSync(dfd);
+  }
+  // The log may live in a temp dir (a user's override). false: not created yet, or gone — log()
+  // recreates it.
+  if (logfile) touchNoFollow(logfile, now, { fsImpl });
+  return restored;
+}
+
+function ownerPid(dir, fsImpl) {
+  const b = readNoFollow(path.join(dir, OWNER_FILE), { fsImpl });
+  const n = b === null ? NaN : Number(b.toString("utf8").trim());
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+/** The name a swept dir is moved to before removal. It carries an RC prefix on purpose: if the
+ * sweep dies between the move and the removal, the next sweep finds it (its owner is dead). */
+export const SWEEP_PREFIX = "mnemom-code-rc.swept-";
+
+/**
+ * Remove the per-session dirs under `root` that no live process owns: those whose recorded owner
+ * is dead, and those with no readable owner that are older than `maxAgeMs` (a dir is only
+ * ownerless for the instant between its mkdtemp and its owner write, or after a crash in that
+ * instant). A dir whose owner is alive is never touched, however old. Returns the removed names.
+ *
+ * Race-safe removal: a candidate is first RENAMED to a fresh name under `root` (rename moves the
+ * entry itself and never follows a symlink), and only what was moved is checked (a real directory,
+ * via lstat) and removed. Nothing can be swapped in between the check and the removal, because the
+ * fresh name was never visible to anyone else. Whatever the move took that is not a directory is
+ * moved back. A dir that vanishes or changes mid-sweep (its owner's own cleanup) is skipped.
+ */
+export function sweepRcDirs(
+  root,
+  { maxAgeMs, now = Date.now(), isAlive = pidAlive, fsImpl = fs } = {},
+) {
+  const removed = [];
+  let names;
+  try {
+    names = fsImpl.readdirSync(root);
+  } catch {
+    return removed;
+  }
+  for (const name of names) {
+    if (!RC_DIR_PREFIXES.some((pre) => name.startsWith(pre))) continue;
+    const dir = path.join(root, name);
+    try {
+      const st = fsImpl.lstatSync(dir);
+      if (!st.isDirectory()) continue;
+      const pid = ownerPid(dir, fsImpl);
+      if (pid !== null) {
+        if (pid === process.pid || isAlive(pid)) continue;
+      } else if (!(now - st.mtimeMs > maxAgeMs)) {
+        continue;
+      }
+      const moved = path.join(root, SWEEP_PREFIX + crypto.randomBytes(6).toString("hex"));
+      fsImpl.renameSync(dir, moved);
+      if (!fsImpl.lstatSync(moved).isDirectory()) {
+        fsImpl.renameSync(moved, dir); // swapped for a non-dir after the check: put it back
+        continue;
+      }
+      fsImpl.rmSync(moved, { recursive: true, force: true });
+      removed.push(name);
+    } catch {
+      /* raced with its owner's own cleanup: nothing to do */
+    }
+  }
+  return removed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.20-next.0",
+  "version": "0.17.21",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {
@@ -34,6 +34,10 @@
   "files": [
     "dist",
     "!dist/__tests__",
+    "plugins",
+    "!plugins/**/*.test.tsx",
+    "!plugins/mnemom/README.md",
+    "!plugins/mnemom/tsconfig.json",
     "README.md",
     "LICENSE"
   ],

package/plugins/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "mnemom",
+  "owner": { "name": "Mnemom", "email": "hello@mnemom.ai", "url": "https://www.mnemom.ai" },
+  "metadata": {
+    "description": "Mnemom plugins for Claude Code: governance, Trust Ratings and the Mnemom gateway.",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "mnemom",
+      "source": "./mnemom",
+      "description": "Mnemom for Claude Code: the governed-agent band, /mnemom commands, the gateway guard and Mnemom attribution for a session launched by `mnemom agent`.",
+      "version": "0.1.0",
+      "author": { "name": "Mnemom", "email": "hello@mnemom.ai" },
+      "homepage": "https://docs.mnemom.ai",
+      "category": "productivity",
+      "keywords": ["mnemom", "governance", "trust", "gateway", "agent"]
+    }
+  ]
+}

package/plugins/mnemom/.claude-plugin/plugin.json

@@ -0,0 +1,47 @@
+{
+  "name": "mnemom",
+  "version": "0.1.0",
+  "description": "Mnemom for Claude Code: the governed-agent band, the goal (sealed contract or inferred, with guardrails and the gateway's verdict), /mnemom commands, the gateway guard and Mnemom attribution for a session launched by `mnemom agent`.",
+  "author": {
+    "name": "Mnemom",
+    "email": "hello@mnemom.ai",
+    "url": "https://www.mnemom.ai"
+  },
+  "homepage": "https://docs.mnemom.ai",
+  "repository": "https://github.com/mnemom/mnemom-platform",
+  "license": "Apache-2.0",
+  "keywords": ["mnemom", "governance", "trust", "gateway", "agent"],
+  "types": "./types/index.d.ts",
+  "userConfig": {
+    "showBand": {
+      "title": "Show the Mnemom band",
+      "type": "boolean",
+      "default": true,
+      "description": "Draw the Mnemom band above the prompt (agent, cell, goal and its verdict, Trust Rating). Hide it for the session with /mnemom hide."
+    },
+    "requireGovernance": {
+      "title": "Require a governed session",
+      "type": "boolean",
+      "default": false,
+      "description": "Refuse every tool call while this session is NOT routed through the Mnemom gateway (i.e. it was not launched by `mnemom agent`). Off: warn only."
+    },
+    "guardReroute": {
+      "title": "Guard the gateway routing",
+      "type": "boolean",
+      "default": true,
+      "description": "In a governed session, deny Bash commands that point ANTHROPIC_BASE_URL away from the Mnemom gateway or unset it."
+    },
+    "commitTrailer": {
+      "title": "Mnemom commit trailers",
+      "type": "boolean",
+      "default": true,
+      "description": "Append Mnemom-Agent / Mnemom-Conversation trailers to the commit attribution in a governed session."
+    },
+    "spinnerMark": {
+      "title": "Mark the spinner and turn line",
+      "type": "boolean",
+      "default": true,
+      "description": "Mark the working spinner and the turn-duration line with the Mnemom sign in a governed session."
+    }
+  }
+}

package/plugins/mnemom/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "mnemom": {
+      "type": "http",
+      "url": "https://api.mnemom.ai/mcp"
+    },
+    "mnemom-docs": {
+      "type": "http",
+      "url": "https://docs.mnemom.ai/mcp"
+    }
+  }
+}

package/plugins/mnemom/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "modules": ["./register.tsx"]
+}