@mnemom/mnemom 0.17.20-next.0 → 0.17.21

package/dist/lib/claude-plugin.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The bundled "Mnemom for Claude Code" plugin (`cli/plugins/mnemom`): a Claude Code
+ * mod + skill + MCP config that `mnemom agent` loads into the Claude Code it launches, so the
+ * session SHOWS it is governed — the Mnemom band above the prompt, `/mnemom` commands, the ◆ sign
+ * on the spinner, Mnemom trailers in commit attribution, and a guard that keeps the routing in
+ * place.
+ *
+ * The launcher tells the mod about the launch through NON-SECRET env vars. They carry a distinct
+ * `MNEMOM_CC_*` prefix so they can never be confused with the launcher's own `MNEMOM_AGENT_*`
+ * inputs, and none of them is a key, a header value or anything derived from one: the mod reads
+ * them by literal name (`claude plugin validate` lists every name), and a stray `env` dump of the
+ * child shows nothing it should not.
+ *
+ * Only Claude Code proper (`cli.name === "claude"`) understands `--plugin-dir`; every other
+ * adapter launches without the plugin.
+ *
+ * OFF BY DEFAULT. The folder ships in the npm tarball (`package.json` `files`, minus its tests
+ * and checkout-only files) but no launch loads it unless asked: `--plugin` or
+ * MNEMOM_AGENT_PLUGIN=1|true|yes|on opts in (`--no-plugin` or 0|false|off|no wins over the env),
+ * and the flags stay out of `--help`. An install missing the folder says so and launches without
+ * it. Turning it on for everyone is one edit: `pluginEnabled`'s default to true. It never blocks
+ * the launch.
+ */
+/** The plugin's `name` in its plugin.json, and its folder under `cli/plugins/`. */
+export declare const CLAUDE_PLUGIN_NAME = "mnemom";
+/** The env Claude Code reads a path list of extra plugin folders from (where no flag can be given). */
+export declare const CLAUDE_PLUGIN_DIRS_ENV = "CLAUDE_CODE_PLUGIN_DIRS";
+/** The env vars the launcher exports for the mod. Every value is non-secret. */
+export declare const PLUGIN_ENV: {
+    /** `https://gateway.mnemom.ai` (no path): presence = the session is governed. */
+    readonly gatewayHost: "MNEMOM_CC_GATEWAY_HOST";
+    /** The public API origin the Trust Rating is read from (`https://api.mnemom.ai`). */
+    readonly apiUrl: "MNEMOM_CC_API_URL";
+    /** The governed agent's name (the `x-mnemom-agent` header's value). */
+    readonly agent: "MNEMOM_CC_AGENT";
+    readonly conversationId: "MNEMOM_CC_CONVERSATION_ID";
+    /** The cell note the launch log prints (`us-2/prod`, or `custom (<host>)`). */
+    readonly cell: "MNEMOM_CC_CELL";
+    /** `terminal` | `remote-control` | `server`. */
+    readonly shape: "MNEMOM_CC_SHAPE";
+    /** `sealed` (a contract rides in the header) | `implicit` | `off`. */
+    readonly goalMode: "MNEMOM_CC_GOAL_MODE";
+    /** The sealed contract's sha256[0:16]; empty unless sealed. */
+    readonly contractSha: "MNEMOM_CC_CONTRACT_SHA";
+    /**
+     * The sealed contract itself — the canonical JSON the gateway hashes (statement, requirements,
+     * allowed/forbidden paths, ceilings). Empty unless sealed. It is what `--goal`/`--requirement`/…
+     * said on the command line: the person's own words, no secret in it.
+     */
+    readonly contract: "MNEMOM_CC_CONTRACT";
+    /**
+     * The implicit mode's guardrail ceilings, `max_turns=N; budget_usd=X; stall_turns=N` (the
+     * `x-mnemom-goal-mode` header minus its leading `implicit`). Empty unless implicit with ceilings.
+     */
+    readonly guardrails: "MNEMOM_CC_GUARDRAILS";
+    /**
+     * How to run this very `mnemom` again, as a JSON argv (`[node, ...execArgv, script]`): the mod
+     * runs `mnemom agent show <conversation> --json` / `mnemom agent goal show …` through it to read
+     * the live goal state (the sealed verdict, the inferred goal, guardrail usage). The CLI
+     * authenticates with the launch key from its own ledger; the mod never holds the key.
+     */
+    readonly launcherExec: "MNEMOM_CC_LAUNCHER_EXEC";
+    /** The `mnemom agent <session>` scenario name. */
+    readonly session: "MNEMOM_CC_SESSION";
+    readonly launcherVersion: "MNEMOM_CC_LAUNCHER_VERSION";
+};
+export type PluginEnvName = (typeof PLUGIN_ENV)[keyof typeof PLUGIN_ENV];
+/**
+ * Whether this launch loads the plugin: `--plugin` / `--no-plugin` (an explicit boolean) wins,
+ * then MNEMOM_AGENT_PLUGIN (1/true/yes/on ⇒ on), else OFF: the plugin lands dark.
+ */
+export declare function pluginEnabled(optionPlugin: boolean | undefined, env: NodeJS.ProcessEnv): boolean;
+/**
+ * The bundled plugin's folder (the one holding `.claude-plugin/plugin.json`), or null when it is
+ * missing. Lives at `<package>/plugins/mnemom`, next to `dist/` and `src/`, so it is
+ * found from a built `dist/lib/` and from `src/lib/` under tsx alike.
+ */
+export declare function resolvePluginDir(baseDirOverride?: string): string | null;
+/** What the launcher knows about a launch that the mod shows. */
+export interface PluginLaunch {
+    gatewayHost: string;
+    apiUrl: string;
+    agent: string;
+    conversationId: string;
+    cellNote: string;
+    shape: "terminal" | "remote-control" | "server";
+    /** The sealed contract's sha (envelope.sha) when one rides along. */
+    contractSha?: string;
+    /** The sealed contract's canonical JSON (envelope.canonical) when one rides along. */
+    contract?: string;
+    /**
+     * The launcher's goal-mode header when no contract is sealed (`implicit[; max_turns=N; …]`),
+     * or null.
+     */
+    goalMode?: string | null;
+    /** The argv that runs this `mnemom` again (`[process.execPath, ...process.execArgv, process.argv[1]]`). */
+    launcherExec?: readonly string[];
+    scenario: string;
+    launcherVersion: string;
+}
+/**
+ * The `MNEMOM_CC_*` block for the child env. Pure: no key, no header, nothing the gateway
+ * authenticates with — just what the launch log already prints to stderr.
+ */
+export declare function buildPluginEnv(launch: PluginLaunch): Record<PluginEnvName, string>;
+/** Writes the block onto a child env in place (the launch shapes all build their env first). */
+export declare function applyPluginEnv(childEnv: NodeJS.ProcessEnv, launch: PluginLaunch): void;
+/**
+ * Appends the plugin folder to CLAUDE_CODE_PLUGIN_DIRS (for the headless `remote-control` server,
+ * which takes no `--plugin-dir`): a user's own list is kept, the folder is added once.
+ */
+export declare function appendPluginDirsEnv(childEnv: NodeJS.ProcessEnv, pluginDir: string): void;
+/** The line the launch log and the dry-run plan print for the plugin. */
+export declare function pluginPlanLine(pluginDir: string | null | undefined, enabled: boolean): string;

package/dist/lib/claude-plugin.js

@@ -0,0 +1,148 @@
+/**
+ * The bundled "Mnemom for Claude Code" plugin (`cli/plugins/mnemom`): a Claude Code
+ * mod + skill + MCP config that `mnemom agent` loads into the Claude Code it launches, so the
+ * session SHOWS it is governed — the Mnemom band above the prompt, `/mnemom` commands, the ◆ sign
+ * on the spinner, Mnemom trailers in commit attribution, and a guard that keeps the routing in
+ * place.
+ *
+ * The launcher tells the mod about the launch through NON-SECRET env vars. They carry a distinct
+ * `MNEMOM_CC_*` prefix so they can never be confused with the launcher's own `MNEMOM_AGENT_*`
+ * inputs, and none of them is a key, a header value or anything derived from one: the mod reads
+ * them by literal name (`claude plugin validate` lists every name), and a stray `env` dump of the
+ * child shows nothing it should not.
+ *
+ * Only Claude Code proper (`cli.name === "claude"`) understands `--plugin-dir`; every other
+ * adapter launches without the plugin.
+ *
+ * OFF BY DEFAULT. The folder ships in the npm tarball (`package.json` `files`, minus its tests
+ * and checkout-only files) but no launch loads it unless asked: `--plugin` or
+ * MNEMOM_AGENT_PLUGIN=1|true|yes|on opts in (`--no-plugin` or 0|false|off|no wins over the env),
+ * and the flags stay out of `--help`. An install missing the folder says so and launches without
+ * it. Turning it on for everyone is one edit: `pluginEnabled`'s default to true. It never blocks
+ * the launch.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The plugin's `name` in its plugin.json, and its folder under `cli/plugins/`. */
+export const CLAUDE_PLUGIN_NAME = "mnemom";
+/** The env Claude Code reads a path list of extra plugin folders from (where no flag can be given). */
+export const CLAUDE_PLUGIN_DIRS_ENV = "CLAUDE_CODE_PLUGIN_DIRS";
+/** The env vars the launcher exports for the mod. Every value is non-secret. */
+export const PLUGIN_ENV = {
+    /** `https://gateway.mnemom.ai` (no path): presence = the session is governed. */
+    gatewayHost: "MNEMOM_CC_GATEWAY_HOST",
+    /** The public API origin the Trust Rating is read from (`https://api.mnemom.ai`). */
+    apiUrl: "MNEMOM_CC_API_URL",
+    /** The governed agent's name (the `x-mnemom-agent` header's value). */
+    agent: "MNEMOM_CC_AGENT",
+    conversationId: "MNEMOM_CC_CONVERSATION_ID",
+    /** The cell note the launch log prints (`us-2/prod`, or `custom (<host>)`). */
+    cell: "MNEMOM_CC_CELL",
+    /** `terminal` | `remote-control` | `server`. */
+    shape: "MNEMOM_CC_SHAPE",
+    /** `sealed` (a contract rides in the header) | `implicit` | `off`. */
+    goalMode: "MNEMOM_CC_GOAL_MODE",
+    /** The sealed contract's sha256[0:16]; empty unless sealed. */
+    contractSha: "MNEMOM_CC_CONTRACT_SHA",
+    /**
+     * The sealed contract itself — the canonical JSON the gateway hashes (statement, requirements,
+     * allowed/forbidden paths, ceilings). Empty unless sealed. It is what `--goal`/`--requirement`/…
+     * said on the command line: the person's own words, no secret in it.
+     */
+    contract: "MNEMOM_CC_CONTRACT",
+    /**
+     * The implicit mode's guardrail ceilings, `max_turns=N; budget_usd=X; stall_turns=N` (the
+     * `x-mnemom-goal-mode` header minus its leading `implicit`). Empty unless implicit with ceilings.
+     */
+    guardrails: "MNEMOM_CC_GUARDRAILS",
+    /**
+     * How to run this very `mnemom` again, as a JSON argv (`[node, ...execArgv, script]`): the mod
+     * runs `mnemom agent show <conversation> --json` / `mnemom agent goal show …` through it to read
+     * the live goal state (the sealed verdict, the inferred goal, guardrail usage). The CLI
+     * authenticates with the launch key from its own ledger; the mod never holds the key.
+     */
+    launcherExec: "MNEMOM_CC_LAUNCHER_EXEC",
+    /** The `mnemom agent <session>` scenario name. */
+    session: "MNEMOM_CC_SESSION",
+    launcherVersion: "MNEMOM_CC_LAUNCHER_VERSION",
+};
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+/**
+ * Whether this launch loads the plugin: `--plugin` / `--no-plugin` (an explicit boolean) wins,
+ * then MNEMOM_AGENT_PLUGIN (1/true/yes/on ⇒ on), else OFF: the plugin lands dark.
+ */
+export function pluginEnabled(optionPlugin, env) {
+    if (optionPlugin !== undefined)
+        return optionPlugin;
+    const raw = (env.MNEMOM_AGENT_PLUGIN ?? "").trim().toLowerCase();
+    return TRUTHY.has(raw);
+}
+/**
+ * The bundled plugin's folder (the one holding `.claude-plugin/plugin.json`), or null when it is
+ * missing. Lives at `<package>/plugins/mnemom`, next to `dist/` and `src/`, so it is
+ * found from a built `dist/lib/` and from `src/lib/` under tsx alike.
+ */
+export function resolvePluginDir(baseDirOverride) {
+    const here = baseDirOverride ?? dirname(fileURLToPath(import.meta.url));
+    const dir = join(here, "..", "..", "plugins", CLAUDE_PLUGIN_NAME);
+    return existsSync(join(dir, ".claude-plugin", "plugin.json")) ? dir : null;
+}
+/** Header-free, newline-free: a value that ends up in a child env and, later, on a band. */
+function clean(v) {
+    return v.replace(/[\r\n]+/g, " ").trim();
+}
+/**
+ * The `MNEMOM_CC_*` block for the child env. Pure: no key, no header, nothing the gateway
+ * authenticates with — just what the launch log already prints to stderr.
+ */
+export function buildPluginEnv(launch) {
+    const sealed = Boolean(launch.contractSha);
+    const implicit = !sealed && /^implicit(\s*;|$)/.test((launch.goalMode ?? "").trim());
+    const goalMode = sealed ? "sealed" : implicit ? "implicit" : "off";
+    // `implicit; max_turns=40; budget_usd=5` → `max_turns=40; budget_usd=5`.
+    const guardrails = implicit
+        ? clean(launch.goalMode ?? "")
+            .replace(/^implicit\s*;?\s*/, "")
+            .trim()
+        : "";
+    const exec = (launch.launcherExec ?? []).map(clean).filter(Boolean);
+    return {
+        [PLUGIN_ENV.gatewayHost]: clean(launch.gatewayHost).replace(/\/+$/, ""),
+        [PLUGIN_ENV.apiUrl]: clean(launch.apiUrl).replace(/\/+$/, ""),
+        [PLUGIN_ENV.agent]: clean(launch.agent),
+        [PLUGIN_ENV.conversationId]: clean(launch.conversationId),
+        [PLUGIN_ENV.cell]: clean(launch.cellNote),
+        [PLUGIN_ENV.shape]: launch.shape,
+        [PLUGIN_ENV.goalMode]: goalMode,
+        [PLUGIN_ENV.contractSha]: clean(launch.contractSha ?? ""),
+        [PLUGIN_ENV.contract]: sealed ? clean(launch.contract ?? "") : "",
+        [PLUGIN_ENV.guardrails]: guardrails,
+        [PLUGIN_ENV.launcherExec]: exec.length > 0 ? JSON.stringify(exec) : "",
+        [PLUGIN_ENV.session]: clean(launch.scenario),
+        [PLUGIN_ENV.launcherVersion]: clean(launch.launcherVersion),
+    };
+}
+/** Writes the block onto a child env in place (the launch shapes all build their env first). */
+export function applyPluginEnv(childEnv, launch) {
+    for (const [k, v] of Object.entries(buildPluginEnv(launch)))
+        childEnv[k] = v;
+}
+/**
+ * Appends the plugin folder to CLAUDE_CODE_PLUGIN_DIRS (for the headless `remote-control` server,
+ * which takes no `--plugin-dir`): a user's own list is kept, the folder is added once.
+ */
+export function appendPluginDirsEnv(childEnv, pluginDir) {
+    const have = (childEnv[CLAUDE_PLUGIN_DIRS_ENV] ?? "").split(delimiter).filter(Boolean);
+    if (have.includes(pluginDir))
+        return;
+    childEnv[CLAUDE_PLUGIN_DIRS_ENV] = [...have, pluginDir].join(delimiter);
+}
+/** The line the launch log and the dry-run plan print for the plugin. */
+export function pluginPlanLine(pluginDir, enabled) {
+    if (!enabled)
+        return "off";
+    if (!pluginDir)
+        return "off (the plugin folder is not in this install)";
+    return `${CLAUDE_PLUGIN_NAME} (${pluginDir})`;
+}

package/dist/lib/config.d.ts

@@ -7,10 +7,21 @@
  */
 /** Base directory for mnemom CLI state (auth tokens, caches). */
 export declare const MNEMOM_DIR: string;
-export type Environment = "production" | "staging" | "local";
+export type Environment = "production" | "local";
+/**
+ * Thrown for `MNEMOM_ENV=staging`: the value used to be accepted, and the ring
+ * it named is gone (MNE-7968). Failing loud is deliberate — the two silent
+ * alternatives are both wrong: resolving to the dead staging hostnames makes
+ * every call fail with a DNS/connection error that does not say why, and
+ * falling through to production would send a caller who asked for a non-prod
+ * ring at real customer data.
+ */
+export declare class RetiredEnvironmentError extends Error {
+    constructor();
+}
 /**
  * Resolve the active environment from MNEMOM_ENV.
- * Defaults to production.
+ * Defaults to production. `staging` throws (see RetiredEnvironmentError).
  */
 export declare function getEnvironment(): Environment;
 export type CellRing = "us-1";

package/dist/lib/config.js

@@ -11,27 +11,43 @@ import * as os from "node:os";
 export const MNEMOM_DIR = path.join(os.homedir(), ".mnemom");
 const API_URLS = {
     production: "https://api.mnemom.ai",
-    staging: "https://api-staging.mnemom.ai",
     local: "http://localhost:8787",
 };
 const GATEWAY_URLS = {
     production: "https://gateway.mnemom.ai",
-    staging: "https://gateway-staging.mnemom.ai",
     local: "http://localhost:8787",
 };
 const WEBSITE_URLS = {
     production: "https://www.mnemom.ai",
-    staging: "https://staging.mnemom.ai",
     local: "http://localhost:5173",
 };
+/**
+ * Thrown for `MNEMOM_ENV=staging`: the value used to be accepted, and the ring
+ * it named is gone (MNE-7968). Failing loud is deliberate — the two silent
+ * alternatives are both wrong: resolving to the dead staging hostnames makes
+ * every call fail with a DNS/connection error that does not say why, and
+ * falling through to production would send a caller who asked for a non-prod
+ * ring at real customer data.
+ */
+export class RetiredEnvironmentError extends Error {
+    constructor() {
+        super("MNEMOM_ENV=staging is no longer supported: the staging ring was retired (MNE-7968) " +
+            "and nothing serves api-staging / gateway-staging.mnemom.ai. " +
+            "Use MNEMOM_RING=us-1 for the preview cell, MNEMOM_ENV=local for a local stack, " +
+            "or set MNEMOM_API_URL / MNEMOM_GATEWAY_URL / MNEMOM_WEBSITE_URL to target another cell.");
+        this.name = "RetiredEnvironmentError";
+    }
+}
 /**
  * Resolve the active environment from MNEMOM_ENV.
- * Defaults to production.
+ * Defaults to production. `staging` throws (see RetiredEnvironmentError).
  */
 export function getEnvironment() {
     const env = process.env.MNEMOM_ENV;
-    if (env === "staging" || env === "local")
+    if (env === "local")
         return env;
+    if (env === "staging")
+        throw new RetiredEnvironmentError();
     return "production";
 }
 const RING_URLS = {
@@ -61,7 +77,7 @@ export function getRing() {
     const env = process.env.MNEMOM_RING?.trim();
     return env && isCellRing(env) ? env : undefined;
 }
-// Process-level base overrides. MNEMOM_ENV only selects prod/staging/local;
+// Process-level base overrides. MNEMOM_ENV only selects prod/local;
 // to target an arbitrary ring (preview/us-1, test) a command can set an
 // explicit override (e.g. `try-me --api <ring>`) or the operator can export
 // MNEMOM_API_URL / MNEMOM_GATEWAY_URL / MNEMOM_WEBSITE_URL. Crucially these

package/dist/lib/first-run/governed.js

@@ -123,11 +123,14 @@ export class Governance {
             if (!r.cc_session_id && t !== null)
                 this.windows.push(["registry_window", t]);
         }
-        // Remote Control proxy logs: $TMPDIR/mnemom-code-rc.*/proxy.log, ~/.mnemom/*rc-proxy*.log
+        // Remote Control proxy logs: ~/.mnemom/rc/mnemom-code-rc.*/proxy.log (the launcher's dir),
+        // $TMPDIR/mnemom-code-rc.*/proxy.log (where older CLIs put it), ~/.mnemom/*rc-proxy*.log
         const logs = [];
-        for (const d of safeList(tmp)) {
-            if (d.startsWith("mnemom-code-rc."))
-                logs.push(join(tmp, d, "proxy.log"));
+        for (const base of [join(mnemomDir, "rc"), tmp]) {
+            for (const d of safeList(base)) {
+                if (d.startsWith("mnemom-code-rc."))
+                    logs.push(join(base, d, "proxy.log"));
+            }
         }
         for (const f of safeList(mnemomDir)) {
             if (f.includes("rc-proxy") && f.endsWith(".log"))

package/dist/lib/oauth.d.ts

@@ -83,7 +83,9 @@ export interface LoopbackResult {
  * for refresh). `openUrl` is injectable so tests can drive the flow without
  * spawning a real browser.
  */
-export declare function loginWithLoopback(openUrl?: (url: string) => void): Promise<LoopbackResult>;
+export declare function loginWithLoopback(openUrl?: (url: string) => void, opts?: {
+    inviteToken?: string;
+}): Promise<LoopbackResult>;
 export interface DeviceResult {
     tokens: OAuthTokens;
     clientId: string;

package/dist/lib/oauth.js

@@ -146,7 +146,7 @@ function tokensFromResponse(data) {
  * for refresh). `openUrl` is injectable so tests can drive the flow without
  * spawning a real browser.
  */
-export async function loginWithLoopback(openUrl = openBrowser) {
+export async function loginWithLoopback(openUrl = openBrowser, opts = {}) {
     const meta = await discover();
     const pkce = generatePkce();
     const state = crypto.randomBytes(16).toString("hex");
@@ -164,6 +164,12 @@ export async function loginWithLoopback(openUrl = openBrowser) {
     authUrl.searchParams.set("state", state);
     authUrl.searchParams.set("code_challenge", pkce.challenge);
     authUrl.searchParams.set("code_challenge_method", pkce.method);
+    // A Mnemom Agent invitation (`mnemom agent --invite`) rides along so a NEW
+    // invitee who signs up in this browser round-trip skips the confirmation
+    // email: the AS ignores the param but bounces a signed-out browser to /login
+    // with this exact URL as return_to, and sign-up forwards the token to the api.
+    if (opts.inviteToken)
+        authUrl.searchParams.set("invite_token", opts.inviteToken);
     console.log("Opening browser to authenticate...");
     console.log(`If the browser doesn't open, visit:\n  ${authUrl.toString()}\n`);
     openUrl(authUrl.toString());
@@ -234,6 +240,12 @@ function startLoopbackServer(expectedState) {
                 close: () => {
                     clearTimeout(timeout);
                     server.close();
+                    // The browser keeps idle keep-alive sockets (incl. Chrome's spare
+                    // preconnect) open while the tab stays up; server.close() alone waits
+                    // on them, so `mnemom login` printed success and then sat there until
+                    // the tab was closed. Drop them — the callback response is already sent.
+                    // Optional call: closeAllConnections() landed in Node 18.2 (engines allow 18.0).
+                    server.closeAllConnections?.();
                 },
             });
         });

package/dist/lib/retired-env-guard.d.ts

@@ -0,0 +1,7 @@
+export declare const RETIRED_ENV_EXIT_CODE = 2;
+/**
+ * The startup error line when any CLI base URL would resolve via the retired
+ * `MNEMOM_ENV=staging`, else undefined. Exported for the unit test; the module
+ * body below is what the CLI relies on.
+ */
+export declare function retiredEnvMessage(): string | undefined;

package/dist/lib/retired-env-guard.js

@@ -0,0 +1,46 @@
+/**
+ * Startup guard for `MNEMOM_ENV=staging` (MNE-7968).
+ *
+ * `getEnvironment()` throws `RetiredEnvironmentError` for that value, and three
+ * modules resolve the API base at MODULE-EVAL time (`lib/api.ts`,
+ * `lib/webhooks-api.ts`, `commands/listen.ts` — see the note at the top of
+ * `__tests__/cli-api-integration.test.ts`). Those modules are statically
+ * imported by `index.ts`, so without this guard the throw surfaces during ESM
+ * linking — before `runEntrypoint()`, before commander, before any try/catch —
+ * and every invocation, `mnemom --help` included, dies with a raw Node stack
+ * trace. This module is the FIRST import of `index.ts`, so it evaluates before
+ * any of them: it prints the same message on one line and exits 2 (the CLI's
+ * usage-error code).
+ *
+ * The guard decides by running config.ts's own resolvers rather than reading
+ * MNEMOM_ENV, so it follows their precedence exactly (raw MNEMOM_*_URL > ring >
+ * MNEMOM_ENV): when a valid MNEMOM_RING, or all three MNEMOM_*_URL overrides,
+ * answer every base URL, MNEMOM_ENV is never consulted and a stale
+ * `MNEMOM_ENV=staging` beside them is harmless. Importing this module has no
+ * effect unless some base URL would resolve via the retired environment.
+ */
+import { getApiUrl, getGatewayUrl, getWebsiteUrl, RetiredEnvironmentError } from "./config.js";
+export const RETIRED_ENV_EXIT_CODE = 2;
+/**
+ * The startup error line when any CLI base URL would resolve via the retired
+ * `MNEMOM_ENV=staging`, else undefined. Exported for the unit test; the module
+ * body below is what the CLI relies on.
+ */
+export function retiredEnvMessage() {
+    try {
+        getApiUrl();
+        getGatewayUrl();
+        getWebsiteUrl();
+        return undefined;
+    }
+    catch (err) {
+        if (err instanceof RetiredEnvironmentError)
+            return `error: ${err.message}`;
+        throw err;
+    }
+}
+const message = retiredEnvMessage();
+if (message !== undefined) {
+    console.error(message);
+    process.exit(RETIRED_ENV_EXIT_CODE);
+}

package/dist/rc-proxy.mjs

@@ -14,9 +14,10 @@
 // WHAT IT DOES
 //   * Listens on 127.0.0.1 (ephemeral port) as an HTTP CONNECT proxy.
 //   * Terminates TLS for api.anthropic.com ONLY, with an ephemeral CA (397 days, key held in
-//     memory only) minted at startup into a private 0700 tmpdir (removed on exit), and a 7-day
-//     leaf re-minted every 24 h and hot-swapped (see below). Every other host is tunnelled
-//     byte-for-byte (telemetry, Datadog, MCP servers…).
+//     memory only) minted at startup into a private 0700 dir under ~/.mnemom/rc (removed on
+//     exit; see rc-state.mjs for why not the OS temp dir), and a 7-day leaf re-minted every 24 h
+//     and hot-swapped (see below). Every other host is tunnelled byte-for-byte (telemetry, Datadog,
+//     MCP servers…).
 //   * Inside api.anthropic.com, only `POST /v1/messages[?…]` is rewritten to the Mnemom
 //     gateway door: the real Anthropic key rides as `x-api-key` (API-key billing), plus
 //     `x-mnemom-agent`, `x-mnemom-conversation-id`, and optionally `x-mnemom-api-key`,
@@ -90,6 +91,7 @@ import path from "node:path";
 import crypto from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { TURN_HEADER, TurnOrigins, turnHeaderEnabled, turnHeaderFor } from "./turn-origin.mjs";
+import { OWNER_FILE, ensureRcStateRoot, keepPrivateDir, sweepRcDirs } from "./rc-state.mjs";
 
 const MITM_HOST = "api.anthropic.com";
 const env = process.env;
@@ -125,7 +127,19 @@ const PORT = Number(env.MNEMOM_AGENT_RC_PORT || 0);
 // transcript. Implicit goal mode only — a sealed contract does not infer a goal from the user.
 const TURNS = GOAL_MODE && turnHeaderEnabled(env) ? new TurnOrigins() : null;
 
-const log = (line) => {
+// If something deleted the log's dir, recreate it (once per line) rather than spill log lines onto
+// the terminal Claude Code is drawing on (the launcher's stderr). True when the retry may go ahead.
+const remakeLogDir = (e) => {
+  if (e.code !== "ENOENT") return false;
+  try {
+    fs.mkdirSync(path.dirname(LOGFILE), { recursive: true, mode: 0o700 });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const log = (line, retry = true) => {
   // One record per line: gateway header values and error bodies are spliced into log lines, so a
   // CR/LF inside them must not fabricate extra records (log injection).
   const s = `${new Date().toISOString()} ${String(line).replace(/[\r\n]+/g, " ")}\n`;
@@ -133,8 +147,9 @@ const log = (line) => {
     try {
       fs.appendFileSync(LOGFILE, s);
       return;
-    } catch {
-      /* fall through */
+    } catch (e) {
+      // The retry goes through the one append above: there is a single write sink for log lines.
+      if (retry && remakeLogDir(e)) return log(line, false);
     }
   }
   process.stderr.write(s);
@@ -157,7 +172,7 @@ if (SUBSCRIPTION) {
 } else if (!secrets.anthropic) die("the Anthropic key (stdin line 1) is empty");
 
 // --- ephemeral CA + rotating leaf for api.anthropic.com ---------------------------------
-// Private 0700 dir under the OS tmpdir, removed on exit. Claude Code reads NODE_EXTRA_CA_CERTS
+// Private 0700 dir under ~/.mnemom/rc (rc-state.mjs), removed on exit. Claude Code reads NODE_EXTRA_CA_CERTS
 // once at process start, so the CA it trusts can never change mid-session: the CA is valid for
 // CA_DAYS and its private key lives in memory only (read into a Buffer, then deleted from disk).
 // The leaf is short-lived and re-minted from that key every LEAF_ROTATE_MS — and on demand when
@@ -166,17 +181,42 @@ if (SUBSCRIPTION) {
 // startup broke every session older than 48 h with "SSL certificate has expired".) openssl only
 // takes the CA key from a file, so each signing writes it 0600 into caDir and deletes it right
 // after. Works with macOS's system LibreSSL (3.3+) and OpenSSL 1.1.1+ (`-addext`).
-// MNEMOM_RC_LEAF_ROTATE_MS / MNEMOM_RC_LEAF_DAYS exist for tests only.
+//
+// Nothing may take the CA files mid-session. In the OS temp dir, macOS's dirhelper deleted
+// ca.pem / leaf.ext from sessions older than ~3-4 days (files not accessed for 3 days; openssl
+// reading them at each rotation does not move their atime), every later rotation failed, and
+// Claude Code reported UNABLE_TO_VERIFY_LEAF_SIGNATURE until relaunch (2026-10-03). The dir now
+// lives under ~/.mnemom/rc, which no cleaner touches (the OS temp dir only if home is not
+// writable). Belt and braces: the CA PEM, the leaf.ext text and the owner pid live in memory too,
+// and keepCaDir() — every CA_KEEPALIVE_MS and before every mint — recreates caDir if it is gone,
+// restores any of the three that is missing or differs (ca.pem byte-identical at the same path:
+// NODE_EXTRA_CA_CERTS points at it), and refreshes the atime/mtime of the dir and everything in
+// it. At startup, sibling dirs left by dead sessions are swept (rc-state.mjs).
+// MNEMOM_RC_LEAF_ROTATE_MS / MNEMOM_RC_LEAF_DAYS / MNEMOM_RC_CA_KEEPALIVE_MS exist for tests only.
 const CA_DAYS = 397;
 const LEAF_DAYS = Number(env.MNEMOM_RC_LEAF_DAYS || 7);
 const LEAF_ROTATE_MS = Number(env.MNEMOM_RC_LEAF_ROTATE_MS || 24 * 60 * 60 * 1000);
 const LEAF_MIN_LEFT_MS = 24 * 60 * 60 * 1000;
-const caDir = fs.mkdtempSync(path.join(os.tmpdir(), "mnemom-code-rc-ca-"));
+const CA_KEEPALIVE_MS = Number(env.MNEMOM_RC_CA_KEEPALIVE_MS || 6 * 60 * 60 * 1000);
+let rcRoot;
+try {
+  rcRoot = ensureRcStateRoot();
+  const swept = sweepRcDirs(rcRoot, { maxAgeMs: CA_DAYS * 24 * 60 * 60 * 1000 });
+  if (swept.length) log(`swept ${swept.length} dir(s) left by dead sessions under ${rcRoot}`);
+} catch (e) {
+  rcRoot = os.tmpdir();
+  log(`cannot use ~/.mnemom/rc (${e.code || e.message}); CA dir falls back to ${rcRoot}`);
+}
+const caDir = fs.mkdtempSync(path.join(rcRoot, "mnemom-code-rc-ca-"));
 fs.chmodSync(caDir, 0o700);
 const p = (f) => path.join(caDir, f);
+const OWNER = `${process.pid}\n`;
+fs.writeFileSync(p(OWNER_FILE), OWNER, { mode: 0o600 });
 let rotateTimer = null;
+let keepAliveTimer = null;
 const cleanup = () => {
   clearInterval(rotateTimer); // a no-op while still null
+  clearInterval(keepAliveTimer);
   try {
     fs.rmSync(caDir, { recursive: true, force: true });
   } catch {
@@ -190,6 +230,8 @@ const ossl = (...a) => execFileSync("openssl", a, { stdio: ["ignore", "ignore",
 const osslErr = (e) => (e.stderr && e.stderr.length ? e.stderr.toString().trim() : e.message);
 
 let caKey; // Buffer — never on disk outside mintLeaf()'s signing call
+let caPem; // Buffer — the exact bytes of ca.pem, restored from here if the file goes missing
+const LEAF_EXT = `subjectAltName=DNS:${MITM_HOST}\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n`;
 try {
   ossl(
     "req",
@@ -214,17 +256,43 @@ try {
   );
   caKey = fs.readFileSync(p("ca.key"));
   fs.rmSync(p("ca.key"));
-  fs.writeFileSync(
-    p("leaf.ext"),
-    `subjectAltName=DNS:${MITM_HOST}\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n`,
-  );
+  caPem = fs.readFileSync(p("ca.pem"));
+  fs.writeFileSync(p("leaf.ext"), LEAF_EXT);
 } catch (e) {
   fs.rmSync(p("ca.key"), { force: true });
   die(`could not mint the ephemeral CA with openssl: ${osslErr(e)}`);
 }
 
+// Recreate caDir and its long-lived files from memory if something deleted them, and refresh
+// every atime/mtime so the cleaner does not try again (see the block comment above).
+// keepPrivateDir (rc-state.mjs) only ever reuses a dir that is ours: a real 0700 directory owned by
+// this uid, checked on an fd opened without following a symlink. Anything else could hand Claude
+// Code a CA someone else controls. Throws when the dir cannot be made safe (mintLeaf then fails
+// and the current leaf stays); otherwise returns the names it restored.
+const keepCaDir = () =>
+  keepPrivateDir(
+    caDir,
+    [
+      ["ca.pem", caPem, 0o644],
+      ["leaf.ext", Buffer.from(LEAF_EXT), 0o644],
+      [OWNER_FILE, Buffer.from(OWNER), 0o600],
+    ],
+    { logfile: LOGFILE },
+  );
+
+function keepAlive(why) {
+  try {
+    const restored = keepCaDir();
+    if (restored.length) log(`ca keep-alive (${why}): restored ${restored.join(", ")}`);
+  } catch (e) {
+    log(`ca keep-alive FAILED (${why}): ${e.message}`);
+  }
+}
+
 // Mint a fresh leaf key + cert signed by the in-memory CA key. Returns { key, cert, notAfter }.
 function mintLeaf() {
+  const restored = keepCaDir(); // a rotation must never fail on a deleted file
+  if (restored.length) log(`ca keep-alive (mint): restored ${restored.join(", ")}`);
   ossl(
     "req",
     "-newkey",
@@ -563,6 +631,8 @@ function rotateLeaf(why) {
 }
 rotateTimer = setInterval(() => rotateLeaf("interval"), LEAF_ROTATE_MS);
 rotateTimer.unref();
+keepAliveTimer = setInterval(() => keepAlive("interval"), CA_KEEPALIVE_MS);
+keepAliveTimer.unref();
 
 const proxy = http.createServer((req, res) => handle(req, res, true));
 proxy.on("connect", (req, sock, head) => {