@mnemom/mnemom 0.17.20 → 0.17.22

package/dist/lib/agent-export.js

@@ -0,0 +1,293 @@
+/**
+ * `mnemom agent export` — the pure half: option parsing (format, --since /
+ * --from / --to), the default output filename, the per-section counts (from the
+ * JSON body / the CSV `X-Mnemom-Export-Counts` header), the summary, and the
+ * error-message mapping. No I/O here; the command driver
+ * (commands/agent-export.ts) does the network and filesystem work, so every
+ * branch below is unit-tested directly.
+ *
+ * Server side: `GET /v1/agents/{id}/compliance-export?format=json|csv&from=&to=`
+ * (mnemom-api reclassification/handlers.ts handleComplianceExport). `from`/`to`
+ * are passed straight into PostgREST `gte.`/`lte.` filters, so they are
+ * normalised here to full UTC ISO timestamps.
+ */
+import { createHash } from "node:crypto";
+import { sanitizeAgentName } from "./agent.js";
+import { MnemomApiError } from "./api.js";
+/** The record's sections, in the order the summary prints them. */
+export const EXPORT_SECTIONS = [
+    "checkpoints",
+    "score_history",
+    "reclassifications",
+    "card_amendments",
+    "disagreement_reviews",
+    "policy_evaluations_with_gaps",
+];
+export const COUNTS_HEADER = "X-Mnemom-Export-Counts";
+/** A bad flag value — reported as-is, before any network call. */
+export class ExportUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ExportUsageError";
+    }
+}
+// ─── option parsing ───────────────────────────────────────────────────────────
+export function parseFormat(raw) {
+    const v = (raw ?? "json").trim().toLowerCase();
+    if (v === "json" || v === "csv")
+        return v;
+    throw new ExportUsageError(`--format must be json or csv (got "${raw}").`);
+}
+const SINCE_RE = /^(\d+)([dh])$/i;
+const HOUR_MS = 3_600_000;
+/** `--since 7d` / `--since 12h` → the UTC ISO timestamp that long before `now`. */
+export function parseSince(raw, now) {
+    const m = SINCE_RE.exec(raw.trim());
+    const n = m ? Number(m[1]) : 0;
+    if (!m || n <= 0) {
+        throw new ExportUsageError(`--since must be a positive number of days or hours, like 7d or 12h (got "${raw}").`);
+    }
+    const unitMs = m[2].toLowerCase() === "d" ? 24 * HOUR_MS : HOUR_MS;
+    return new Date(now.getTime() - n * unitMs).toISOString();
+}
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATETIME_RE = /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?$/i;
+/** True when y-m-d is a real calendar day (rejects 2026-02-30, month 13, …). */
+function isCalendarDate(y, m, d) {
+    const date = new Date(Date.UTC(Number(y), Number(m) - 1, Number(d)));
+    return (date.getUTCFullYear() === Number(y) &&
+        date.getUTCMonth() === Number(m) - 1 &&
+        date.getUTCDate() === Number(d));
+}
+/**
+ * Validate an ISO-8601 date or datetime for `--from` / `--to` and normalise it to
+ * a UTC ISO timestamp. A bare date is a UTC day: `--from` starts at its first
+ * millisecond and `--to` includes the whole day (ends at its last millisecond).
+ * A datetime with no offset is read in local time, like `new Date()` does.
+ */
+export function parseDateBound(raw, flag) {
+    const v = raw.trim();
+    const dateOnly = DATE_RE.exec(v);
+    const parts = dateOnly ?? DATETIME_RE.exec(v);
+    const ms = parts ? Date.parse(v) : NaN;
+    if (!parts || Number.isNaN(ms) || !isCalendarDate(parts[1], parts[2], parts[3])) {
+        throw new ExportUsageError(`${flag} must be an ISO-8601 date or datetime, like 2026-09-01 or 2026-09-01T09:30:00Z (got "${raw}").`);
+    }
+    if (dateOnly && flag === "--to")
+        return `${v}T23:59:59.999Z`;
+    return new Date(ms).toISOString();
+}
+/** Resolve `--since` / `--from` / `--to` into the period sent to the server. */
+export function resolvePeriod(flags, now) {
+    if (flags.since !== undefined && flags.from !== undefined) {
+        throw new ExportUsageError("Use either --since or --from, not both.");
+    }
+    const from = flags.since !== undefined
+        ? parseSince(flags.since, now)
+        : flags.from !== undefined
+            ? parseDateBound(flags.from, "--from")
+            : null;
+    const to = flags.to !== undefined ? parseDateBound(flags.to, "--to") : null;
+    if (from !== null && to !== null && from > to) {
+        throw new ExportUsageError(`The start of the period (${from}) is after its end (${to}).`);
+    }
+    return { from, to };
+}
+/** All the flag validation, done locally before any network call. */
+export function parseExportFlags(flags, now) {
+    const output = flags.output?.trim();
+    if (output === "")
+        throw new ExportUsageError("-o/--output needs a file path, or - for stdout.");
+    return {
+        format: parseFormat(flags.format),
+        period: resolvePeriod(flags, now),
+        output,
+        force: flags.force === true,
+        json: flags.json === true,
+    };
+}
+/** `?format=…&from=…&to=…` for the compliance-export route. */
+export function buildExportQuery(format, period) {
+    const params = new URLSearchParams({ format });
+    if (period.from !== null)
+        params.set("from", period.from);
+    if (period.to !== null)
+        params.set("to", period.to);
+    return `?${params.toString()}`;
+}
+// ─── agent ────────────────────────────────────────────────────────────────────
+export const NO_AGENT_MESSAGE = "No agent given. Pass one: mnemom agent export <id-or-name> (see mnemom agent list)";
+/**
+ * The agent to export: the positional `[id-or-name]` when given; else, in
+ * order, MNEMOM_AGENT, the saved launcher-config `agent`, and the agent of the
+ * newest launch in the session ledger that resolved one (resolved by id, named
+ * after its slug). null when none of them has an agent.
+ */
+export function pickAgentRef(given, sources) {
+    const named = given?.trim() || sources.env()?.trim() || sources.configAgent()?.trim();
+    if (named)
+        return { ref: named, label: named };
+    const launch = sources
+        .ledger()
+        .find((r) => Boolean(r.agent_id));
+    if (!launch)
+        return null;
+    return { ref: launch.agent_id, label: launch.agent_slug || launch.agent_id };
+}
+// ─── output path ──────────────────────────────────────────────────────────────
+/** The filename-safe agent label: `label` sanitised; the resolved id when that leaves nothing. */
+export function filenameLabel(label, agentId) {
+    return sanitizeAgentName(label) || sanitizeAgentName(agentId);
+}
+/** `./mnemom-record-<label>-<YYYY-MM-DD>.<json|csv>` (UTC date). */
+export function defaultOutputPath(label, format, now) {
+    return `./mnemom-record-${label}-${now.toISOString().slice(0, 10)}.${format}`;
+}
+// ─── counts ───────────────────────────────────────────────────────────────────
+function isCount(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0;
+}
+/**
+ * Counts from a JSON export body: the server's `counts` object where it has a
+ * section, else the length of that section's array. null when the body is not
+ * a JSON object.
+ */
+export function countsFromJsonBody(text) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return null;
+    const record = body;
+    const declared = record.counts !== null && typeof record.counts === "object"
+        ? record.counts
+        : {};
+    const counts = {};
+    for (const section of EXPORT_SECTIONS) {
+        const fromServer = declared[section];
+        const rows = record[section];
+        counts[section] = isCount(fromServer) ? fromServer : Array.isArray(rows) ? rows.length : null;
+    }
+    return counts;
+}
+/**
+ * Counts from the CSV response header
+ * `checkpoints=N;score_history=N;…`. null when the header is absent or carries
+ * no recognisable section (an older API) — the summary then says so.
+ */
+const COUNT_PAIR_RE = /^\s*([a-z_]+)\s*=\s*(\d+)\s*$/;
+export function countsFromHeader(header) {
+    if (header === null)
+        return null;
+    const counts = Object.fromEntries(EXPORT_SECTIONS.map((s) => [s, null]));
+    let found = false;
+    for (const pair of header.split(";")) {
+        const m = COUNT_PAIR_RE.exec(pair);
+        if (m && EXPORT_SECTIONS.includes(m[1])) {
+            counts[m[1]] = Number(m[2]);
+            found = true;
+        }
+    }
+    return found ? counts : null;
+}
+export function extractCounts(format, body, headers) {
+    return format === "csv"
+        ? countsFromHeader(headers.get(COUNTS_HEADER))
+        : countsFromJsonBody(new TextDecoder().decode(body));
+}
+// ─── summary ──────────────────────────────────────────────────────────────────
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export function verificationLinks(agentId, websiteBase, apiBase) {
+    const id = encodeURIComponent(agentId);
+    return {
+        reputation_url: `${websiteBase}/agents/${id}/reputation`,
+        verify_url: `${apiBase}/v1/reputation/${id}/verify`,
+    };
+}
+export function buildSummary(input) {
+    return {
+        agent_id: input.agentId,
+        output: input.output,
+        format: input.format,
+        period: input.period,
+        counts: input.counts,
+        bytes: input.body.byteLength,
+        sha256: sha256Hex(input.body),
+        verification: verificationLinks(input.agentId, input.websiteBase, input.apiBase),
+    };
+}
+export function describePeriod(period) {
+    if (period.from !== null && period.to !== null)
+        return `${period.from} to ${period.to}`;
+    if (period.from !== null)
+        return `${period.from} to now`;
+    if (period.to !== null)
+        return `everything up to ${period.to}`;
+    return "all time";
+}
+/** The human summary, one line per entry (no colour; the driver adds none). */
+export function formatSummaryLines(summary) {
+    const lines = [
+        `Exported the record of ${summary.agent_id}`,
+        `  Output:   ${summary.output === "-" ? "stdout" : summary.output} (${summary.format}, ${summary.bytes} bytes)`,
+        `  Period:   ${describePeriod(summary.period)}`,
+    ];
+    if (summary.counts === null) {
+        lines.push("  Counts:   unavailable (this server version does not report them)");
+    }
+    else {
+        lines.push("  Counts:");
+        const width = Math.max(...EXPORT_SECTIONS.map((s) => s.length));
+        for (const section of EXPORT_SECTIONS) {
+            const n = summary.counts[section];
+            lines.push(`    ${section.padEnd(width)}  ${n === null ? "unavailable" : n}`);
+        }
+    }
+    lines.push(`  SHA-256:  ${summary.sha256}`);
+    lines.push("            (file checksum — lets the recipient confirm the file was not altered in transit)");
+    lines.push(`  Verify:   ${summary.verification.reputation_url}`);
+    lines.push(`            ${summary.verification.verify_url}`);
+    return lines;
+}
+/** The one-line sensitivity note (the driver prints it dim, on stderr). */
+export function sensitivityNote(toStdout) {
+    const where = toStdout
+        ? "handle it as confidential"
+        : "the file is readable by you only (mode 0600)";
+    return (`This export holds full checkpoint reasoning and concerns that outsiders normally see redacted — ${where}. ` +
+        "To share proof without the contents, send the public verification link instead.");
+}
+// ─── errors ───────────────────────────────────────────────────────────────────
+/** The user-facing message for a failed export request. */
+export function exportErrorMessage(error, agentId) {
+    if (error instanceof MnemomApiError) {
+        // effectiveStatus, not status: the enforce hook can rewrite an undocumented
+        // status to a synthetic 500 carrying spec_deviation.original_status.
+        const status = error.effectiveStatus;
+        if (status === 401)
+            return "Not signed in, or your session has expired. Run `mnemom login`.";
+        if (status === 403)
+            return `You are not a member of the org that owns agent ${agentId}.`;
+        if (status === 404)
+            return `Agent not found: ${agentId}.`;
+        if (status === 413 || error.code === "export_too_large") {
+            return "That period has more rows than the server exports in one go. Narrow it with --since, --from or --to.";
+        }
+        return `Export failed: ${error.message}`;
+    }
+    return `Export failed: ${error instanceof Error ? error.message : String(error)}`;
+}
+/** The user-facing message for a failed file write. */
+export function writeErrorMessage(error, path) {
+    const code = error?.code;
+    if (code === "EEXIST") {
+        return `${path} already exists. Pass --force to overwrite it, or pick another path with -o.`;
+    }
+    return `Could not write ${path}: ${error instanceof Error ? error.message : String(error)}`;
+}

package/dist/lib/api.d.ts

@@ -371,6 +371,18 @@ export interface MoveAgentResult {
 export declare function moveAgent(agentId: string, destOrgId: string, opts?: {
     idempotencyKey?: string;
 }): Promise<MoveAgentResult>;
+/**
+ * GET /v1/agents/:id/compliance-export — the agent's full record (JSON or CSV).
+ *
+ * Returns the raw body bytes (written to disk verbatim so the checksum the CLI
+ * prints matches what the server sent) plus the response headers (CSV carries
+ * its per-section counts in `X-Mnemom-Export-Counts`). `query` is the full
+ * `?format=…&from=…&to=…` string (see lib/agent-export.ts buildExportQuery).
+ */
+export declare function getComplianceExport(agentId: string, query: string): Promise<{
+    body: Uint8Array;
+    headers: Headers;
+}>;
 /**
  * GET /v1/auth/me/personal-org — accessor for the user's personal org.
  * Idempotent: lazily provisions for legacy accounts that pre-date the
@@ -1305,6 +1317,29 @@ export interface AgentSessionVerdictTrailEntry {
     fence_breach: boolean | null;
     at: string;
 }
+/**
+ * The seal's lifecycle (MNE-8149 R2, MNE-8199 D9/R9, MNE-8234/mnemom-api#3541). `live`: a sealed
+ * contract currently governs — `mode` says whether a crossed guardrail only nudges or enforces
+ * (refuses the next request). `expired`: the prior seal lapsed (24h idle) and the next engaged
+ * request will seal afresh; no `mode` because nothing is being enforced.
+ */
+export interface AgentSessionSealLive {
+    state: "live";
+    version: number;
+    hash: string;
+    sealed_at: string;
+    reason: "first" | "after_expiry" | null;
+    expired_hash: string | null;
+    updated_from_hash: string | null;
+    mode: "nudge" | "enforce";
+}
+export interface AgentSessionSealExpired {
+    state: "expired";
+    version: number;
+    hash: string;
+    sealed_at: string;
+}
+export type AgentSessionSeal = AgentSessionSealLive | AgentSessionSealExpired;
 /** `GET /v1/agent/sessions/{conversationId}` 200 body. Nulls mean "nothing stored" — absence is data. */
 export interface AgentSessionResponse {
     conversation_id: string;
@@ -1319,6 +1354,24 @@ export interface AgentSessionResponse {
     guardrails: AgentSessionGuardrails | null;
     /** Absent on an older server (back-compat) — never shown then, never an empty-array assumption. */
     verdict_trail?: AgentSessionVerdictTrailEntry[];
+    /**
+     * MNE-8234: the seal's lifecycle, incl. `expired`. Absent on an older server (back-compat —
+     * never shown then). `null` means the API itself reports no seal: either none was ever made for
+     * this conversation, or the gateway sent a seal payload out of contract and the API dropped it
+     * rather than relay it half-trusted — the two are indistinguishable from this field alone.
+     */
+    seal?: AgentSessionSeal | null;
+    /**
+     * MNE-8166 R4 / MNE-8234: assistant turns under the current seal with no verdict (a cut-off/
+     * aborted response, a judge that failed or never ran, a non-streamed final turn). Absent on an
+     * older server (back-compat). `null` when no judge ledger counts under the current seal.
+     */
+    unjudged_turns?: number | null;
+    /**
+     * MNE-8166 R4 / MNE-8234: turns the judge memo graded (aligned by inheritance, no verdict
+     * stored). Absent on an older server (back-compat). `null` alongside `unjudged_turns`.
+     */
+    memoised_turns?: number | null;
 }
 /**
  * The live goal state of one `mnemom agent` session, read through mnemom-api

package/dist/lib/api.js

@@ -367,6 +367,23 @@ export async function moveAgent(agentId, destOrgId, opts = {}) {
         to_org_id: data.to_org_id ?? null,
     };
 }
+/**
+ * GET /v1/agents/:id/compliance-export — the agent's full record (JSON or CSV).
+ *
+ * Returns the raw body bytes (written to disk verbatim so the checksum the CLI
+ * prints matches what the server sent) plus the response headers (CSV carries
+ * its per-section counts in `X-Mnemom-Export-Counts`). `query` is the full
+ * `?format=…&from=…&to=…` string (see lib/agent-export.ts buildExportQuery).
+ */
+export async function getComplianceExport(agentId, query) {
+    const url = validateUrl(`${API_BASE}/v1/agents/${encodeURIComponent(agentId)}/compliance-export${query}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: { ...(await authHeaders()), Accept: "application/json, text/csv" },
+    }));
+    if (!response.ok)
+        throw await readApiError(response, "Failed to export the agent record");
+    return { body: new Uint8Array(await response.arrayBuffer()), headers: response.headers };
+}
 /**
  * GET /v1/auth/me/personal-org — accessor for the user's personal org.
  * Idempotent: lazily provisions for legacy accounts that pre-date the

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

@@ -14,13 +14,12 @@
  * Only Claude Code proper (`cli.name === "claude"`) understands `--plugin-dir`; every other
  * adapter launches without the plugin.
  *
- * OFF BY DEFAULT, AND NOT IN THE PUBLISHED PACKAGE YET. The plugin is committed under
- * `cli/plugins/` but `package.json` `files` leaves it out of the npm tarball, so an installed
- * `mnemom` has no folder to load and never looks for one. `--plugin` or
- * MNEMOM_AGENT_PLUGIN=1|true|yes|on opts a launch in (`--no-plugin` or 0|false|off|no wins over
- * the env); from a source checkout that loads the folder, from an install it says the folder is
- * not there and launches without it. Turning it on for everyone later is two edits: `plugins`
- * back into `files`, and `pluginEnabled`'s default to true. It never blocks the launch.
+ * 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";
@@ -68,7 +67,7 @@ export declare const PLUGIN_ENV: {
 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 is not published yet.
+ * 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;
 /**

package/dist/lib/claude-plugin.js

@@ -14,13 +14,12 @@
  * Only Claude Code proper (`cli.name === "claude"`) understands `--plugin-dir`; every other
  * adapter launches without the plugin.
  *
- * OFF BY DEFAULT, AND NOT IN THE PUBLISHED PACKAGE YET. The plugin is committed under
- * `cli/plugins/` but `package.json` `files` leaves it out of the npm tarball, so an installed
- * `mnemom` has no folder to load and never looks for one. `--plugin` or
- * MNEMOM_AGENT_PLUGIN=1|true|yes|on opts a launch in (`--no-plugin` or 0|false|off|no wins over
- * the env); from a source checkout that loads the folder, from an install it says the folder is
- * not there and launches without it. Turning it on for everyone later is two edits: `plugins`
- * back into `files`, and `pluginEnabled`'s default to true. It never blocks the launch.
+ * 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";
@@ -71,7 +70,7 @@ export const PLUGIN_ENV = {
 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 is not published yet.
+ * then MNEMOM_AGENT_PLUGIN (1/true/yes/on ⇒ on), else OFF: the plugin lands dark.
  */
 export function pluginEnabled(optionPlugin, env) {
     if (optionPlugin !== undefined)
@@ -144,6 +143,6 @@ export function pluginPlanLine(pluginDir, enabled) {
     if (!enabled)
         return "off";
     if (!pluginDir)
-        return "off (the plugin folder is not in this install — run from a source checkout)";
+        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/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);
+}