@mnemom/mnemom 0.17.0-next.6 → 0.17.0-next.8

package/README.md

@@ -44,6 +44,32 @@ That's it. `mnemom init` detects your configured AI provider API keys (Anthropic
 | `mnemom card publish <file>`  | Publish alignment card from JSON file                |
 | `mnemom card validate <file>` | Validate card JSON locally                           |
 | `mnemom usage --org <id>`     | Show per-person token and request consumption        |
+| `mnemom agent [name]`         | Launch a governed coding agent through the gateway   |
+
+### `mnemom agent` — goal alignment
+
+`mnemom agent` launches your coding-agent CLI (Claude Code today) with its model traffic
+routed through the Mnemom gateway under a governed identity. Goal alignment — the judge
+nudging the agent back when it drifts from your goal — comes in three modes; a bare
+`mnemom agent` in a terminal asks which one you want (Enter = off, for now):
+
+| Mode         | How                                                                                                            | What is sent                                |
+| ------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| **Implicit** | `--implicit` — the gateway infers the goal from your own messages and revises it as you steer; nothing to type | `x-mnemom-goal-mode: implicit`, no contract |
+| **Sealed**   | `--goal "<statement>"` (+ `--requirement/--allow/--forbid/--goal-id`) — sealed as a contract on the first turn | `x-mnemom-contract`                         |
+| **Off**      | neither                                                                                                        | neither header                              |
+
+`--implicit` cannot be combined with the sealed-contract flags: a sealed contract always
+wins on the gateway and would silently switch implicit mode off, so the launch refuses the
+mix. The guardrail ceilings (`--budget`, `--max-turns`, `--stall`, or `guardrails.*` in
+`~/.mnemom/launcher.toml`) apply in both modes — in implicit mode they ride on the mode
+header. In implicit mode the goal lags your steering by one request: a response to a new
+message carries `x-mnemom-goal-steer: queued` and the revision the agent acted under;
+the next request reads the new revision (`x-mnemom-goal-revision`).
+
+Make one mode the standing default with `mnemom agent config set goal_mode implicit`
+(or `off`); `--goal` still seals for that launch and `--no-implicit` turns it off for one
+launch. A sealed contract needs a per-launch statement, so it cannot be the default.
 
 ## How It Works
 

package/dist/commands/agent-config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `mnemom agent config …` — read and write the persistent per-customer settings
+ * for `mnemom agent` (see lib/code-config.ts). A sub-verb of `mnemom agent`, so a
+ * customer configures the launcher once and never retypes their flags:
+ *
+ *   mnemom agent config list                 # show the current settings
+ *   mnemom agent config get <key>            # print one value
+ *   mnemom agent config set <key> <value>    # validate + persist one value
+ *   mnemom agent config unset <key>          # remove one value
+ *   mnemom agent config edit                 # open ~/.mnemom/launcher.toml in $EDITOR
+ *   mnemom agent config path                 # print the settings file path
+ *
+ * Settable keys are the single source of truth in lib/code-config.ts CONFIG_KEYS.
+ * The secret Anthropic key is NOT a config key — it lives in ~/.mnemom/launcher.json.
+ */
+/** Entry point for `mnemom agent config <verb> [args...]`. Throws on misuse. */
+export declare function agentConfigCommand(argv: string[]): Promise<void>;
+/**
+ * `$VISUAL` / `$EDITOR` is a program plus optional plain flags (`code --wait`, `emacsclient -t`),
+ * never shell syntax: the value is split on whitespace and every token must be a bare
+ * program name, path, or flag. Anything else (quotes, `;`, `$(`, backticks, redirections, …) is
+ * refused with a remediation rather than handed to spawnSync — the editor is launched WITHOUT a
+ * shell, so such a value could only ever fail confusingly or, via a lookalike binary on PATH, run
+ * something the user did not mean. Exported for the tests.
+ */
+export declare function parseEditorSpec(spec: string): {
+    bin: string;
+    args: string[];
+};

package/dist/commands/agent-config.js

@@ -0,0 +1,193 @@
+/**
+ * `mnemom agent config …` — read and write the persistent per-customer settings
+ * for `mnemom agent` (see lib/code-config.ts). A sub-verb of `mnemom agent`, so a
+ * customer configures the launcher once and never retypes their flags:
+ *
+ *   mnemom agent config list                 # show the current settings
+ *   mnemom agent config get <key>            # print one value
+ *   mnemom agent config set <key> <value>    # validate + persist one value
+ *   mnemom agent config unset <key>          # remove one value
+ *   mnemom agent config edit                 # open ~/.mnemom/launcher.toml in $EDITOR
+ *   mnemom agent config path                 # print the settings file path
+ *
+ * Settable keys are the single source of truth in lib/code-config.ts CONFIG_KEYS.
+ * The secret Anthropic key is NOT a config key — it lives in ~/.mnemom/launcher.json.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { LAUNCHER_CONFIG_PATH, CONFIG_KEYS, configKeySpec, loadLauncherConfig, writeLauncherConfig, } from "../lib/launcher-config.js";
+const out = (line = "") => console.log(line);
+const err = (line = "") => console.error(line);
+/** Entry point for `mnemom agent config <verb> [args...]`. Throws on misuse. */
+export async function agentConfigCommand(argv) {
+    const [verb, ...rest] = argv;
+    switch (verb) {
+        case undefined:
+        case "list":
+            return listConfig();
+        case "path":
+            out(LAUNCHER_CONFIG_PATH);
+            return;
+        case "get":
+            return getConfig(rest[0]);
+        case "set":
+            return setConfig(rest[0], rest[1]);
+        case "unset":
+            return unsetConfig(rest[0]);
+        case "edit":
+            return editConfig();
+        default:
+            throw new Error(`mnemom agent config: unknown verb '${verb}'. Use list | get | set | unset | edit | path.`);
+    }
+}
+function listConfig() {
+    const cfg = loadLauncherConfig();
+    const rows = [];
+    for (const spec of CONFIG_KEYS) {
+        const v = spec.get(cfg);
+        if (v !== undefined)
+            rows.push([spec.key, String(v)]);
+    }
+    if (!rows.length) {
+        out(`No settings yet at ${LAUNCHER_CONFIG_PATH}.`);
+        out("Set one with:  mnemom agent config set <key> <value>");
+        out("");
+        out("Settable keys:");
+        for (const spec of CONFIG_KEYS)
+            out(`  ${spec.key.padEnd(22)} ${spec.describe}`);
+        return;
+    }
+    const width = Math.max(...rows.map(([k]) => k.length));
+    out(`# ${LAUNCHER_CONFIG_PATH}`);
+    for (const [k, v] of rows)
+        out(`${k.padEnd(width)}  ${v}`);
+}
+function getConfig(key) {
+    if (!key)
+        throw new Error("mnemom agent config get: a <key> is required.");
+    const spec = requireSpec(key);
+    const value = spec.get(loadLauncherConfig());
+    if (value === undefined) {
+        err(`mnemom agent config: '${key}' is not set.`);
+        process.exitCode = 1;
+        return;
+    }
+    out(String(value));
+}
+function setConfig(key, value) {
+    if (!key)
+        throw new Error("mnemom agent config set: a <key> is required.");
+    if (value === undefined)
+        throw new Error(`mnemom agent config set: a value for '${key}' is required.`);
+    const spec = requireSpec(key);
+    const cfg = loadLauncherConfig();
+    spec.set(cfg, value); // validates + coerces; throws on invalid
+    writeLauncherConfig(cfg);
+    out(`${key} = ${String(spec.get(cfg))}   (saved to ${LAUNCHER_CONFIG_PATH})`);
+}
+function unsetConfig(key) {
+    if (!key)
+        throw new Error("mnemom agent config unset: a <key> is required.");
+    requireSpec(key);
+    const cfg = loadLauncherConfig();
+    deleteKey(cfg, key);
+    writeLauncherConfig(cfg);
+    out(`unset ${key}   (saved to ${LAUNCHER_CONFIG_PATH})`);
+}
+function editConfig() {
+    // Seed a header-only file so $EDITOR opens something with guidance, not a blank.
+    if (!existsSync(LAUNCHER_CONFIG_PATH))
+        writeLauncherConfig(loadLauncherConfig());
+    const { bin: editor, args: editorArgs } = parseEditorSpec(process.env.VISUAL || process.env.EDITOR || fallbackEditor());
+    const res = spawnSync(editor, [...editorArgs, LAUNCHER_CONFIG_PATH], { stdio: "inherit" });
+    if (res.error) {
+        throw new Error(`mnemom agent config edit: could not launch editor '${editor}': ${res.error.message}\n` +
+            `  Set $EDITOR, or edit ${LAUNCHER_CONFIG_PATH} directly.`);
+    }
+    // Re-parse so a typo surfaces now, not at the next launch.
+    loadLauncherConfig();
+    out(`Saved ${LAUNCHER_CONFIG_PATH}.`);
+}
+/**
+ * `$VISUAL` / `$EDITOR` is a program plus optional plain flags (`code --wait`, `emacsclient -t`),
+ * never shell syntax: the value is split on whitespace and every token must be a bare
+ * program name, path, or flag. Anything else (quotes, `;`, `$(`, backticks, redirections, …) is
+ * refused with a remediation rather than handed to spawnSync — the editor is launched WITHOUT a
+ * shell, so such a value could only ever fail confusingly or, via a lookalike binary on PATH, run
+ * something the user did not mean. Exported for the tests.
+ */
+export function parseEditorSpec(spec) {
+    const tokens = spec.trim().split(/\s+/).filter(Boolean);
+    const SAFE = /^[A-Za-z0-9_./+=:@,-]+$/;
+    if (tokens.length === 0 || !tokens.every((t) => SAFE.test(t))) {
+        throw new Error(`mnemom agent config edit: refusing to run $VISUAL/$EDITOR value '${spec}' — only a program name or path plus plain flags is accepted (no shell syntax).\n` +
+            `  Set $EDITOR to e.g. 'code --wait', or edit ${LAUNCHER_CONFIG_PATH} directly.`);
+    }
+    return { bin: tokens[0], args: tokens.slice(1) };
+}
+function fallbackEditor() {
+    for (const cand of ["nano", "vim", "vi"]) {
+        const r = spawnSync("sh", ["-c", `command -v "$1" >/dev/null 2>&1`, "sh", cand], {
+            stdio: "ignore",
+        });
+        if (r.status === 0)
+            return cand;
+    }
+    return "vi";
+}
+function requireSpec(key) {
+    const spec = configKeySpec(key);
+    if (!spec) {
+        throw new Error(`mnemom agent config: unknown key '${key}'.\n  Known keys: ${CONFIG_KEYS.map((k) => k.key).join(", ")}`);
+    }
+    return spec;
+}
+/** Remove a (possibly dotted) key from a config object, pruning an emptied table. */
+function deleteKey(cfg, key) {
+    if (key.startsWith("guardrails.")) {
+        const g = cfg.guardrails;
+        if (!g)
+            return;
+        const field = key.slice("guardrails.".length);
+        if (field === "max_turns")
+            delete g.maxTurns;
+        if (field === "budget_usd")
+            delete g.budgetUsd;
+        if (field === "stall_turns")
+            delete g.stallTurns;
+        if (g.maxTurns === undefined && g.budgetUsd === undefined && g.stallTurns === undefined) {
+            delete cfg.guardrails;
+        }
+        return;
+    }
+    // Static, exhaustive: every top-level key the schema knows, so a typo can never
+    // delete an unrelated property (and the lint rule on dynamic delete stays honest).
+    switch (key) {
+        case "gateway":
+            delete cfg.gateway;
+            break;
+        case "model":
+            delete cfg.model;
+            break;
+        case "agent":
+            delete cfg.agent;
+            break;
+        case "effort":
+            delete cfg.effort;
+            break;
+        case "goal_mode":
+            delete cfg.goalMode;
+            break;
+        case "cli":
+            delete cfg.cli;
+            break;
+        case "launch":
+            delete cfg.launch;
+            break;
+        case "key_source":
+            delete cfg.keySource;
+            break;
+        default:
+            requireSpec(key); // throws the known-keys message for anything unknown
+    }
+}

package/dist/commands/{code-doctor.d.ts → agent-doctor.d.ts}

@@ -1,5 +1,5 @@
 /**
- * `mnemom code doctor` — a read-only preflight for `mnemom code`. It checks the
+ * `mnemom agent doctor` — a read-only preflight for `mnemom agent`. It checks the
  * things a governed launch needs and prints a checklist with clear, actionable
  * remediation, so a customer can see at a glance why a launch would fail before
  * it does. Writes nothing and reads no secret VALUE (only whether a key is
@@ -16,7 +16,7 @@ export interface DoctorOptions {
     cli?: string;
 }
 /** Run the preflight and print the checklist. Sets process.exitCode on failure. */
-export declare function codeDoctorCommand(options?: DoctorOptions): Promise<void>;
+export declare function agentDoctorCommand(options?: DoctorOptions): Promise<void>;
 export interface CodeAccessProbe {
     mark: Mark;
     text: string;

package/dist/commands/{code-doctor.js → agent-doctor.js}

@@ -1,5 +1,5 @@
 /**
- * `mnemom code doctor` — a read-only preflight for `mnemom code`. It checks the
+ * `mnemom agent doctor` — a read-only preflight for `mnemom agent`. It checks the
  * things a governed launch needs and prints a checklist with clear, actionable
  * remediation, so a customer can see at a glance why a launch would fail before
  * it does. Writes nothing and reads no secret VALUE (only whether a key is
@@ -13,27 +13,27 @@
  */
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { anthropicKeySource, checkRcCapability, resolveCliBin, } from "./code.js";
-import { isProdGateway, resolveAnthropicDoor, resolveGatewayHost, } from "../lib/code.js";
-import { CODE_CONFIG_PATH } from "../lib/code-config.js";
+import { anthropicKeySource, checkRcCapability, resolveCliBin } from "./agent.js";
+import { isProdGateway, resolveAnthropicDoor, resolveGatewayHost } from "../lib/agent.js";
+import { LAUNCHER_CONFIG_PATH } from "../lib/launcher-config.js";
 import { getCodeEntitlement, MnemomApiError } from "../lib/api.js";
 import { isLoggedIn } from "../lib/auth.js";
 import { getActiveOrg } from "../lib/cli-config.js";
-import { isCodeNotEnabled, sourceLabel } from "./code-invite.js";
+import { isCodeNotEnabled, sourceLabel } from "./agent-invite.js";
 const MARK = { ok: "[ ok ]", warn: "[warn]", miss: "[MISS]", info: "[info]" };
 const out = (line = "") => console.log(line);
 /** Run the preflight and print the checklist. Sets process.exitCode on failure. */
-export async function codeDoctorCommand(options = {}) {
+export async function agentDoctorCommand(options = {}) {
     const env = process.env;
     const lines = [];
     const add = (mark, text, hint) => {
         lines.push({ mark, text, hint });
     };
     // ── settings file ──
-    if (existsSync(CODE_CONFIG_PATH))
-        add("ok", `settings: ${CODE_CONFIG_PATH}`);
+    if (existsSync(LAUNCHER_CONFIG_PATH))
+        add("ok", `settings: ${LAUNCHER_CONFIG_PATH}`);
     else
-        add("info", `settings: none yet (${CODE_CONFIG_PATH}) — using built-in defaults`, "save your defaults with `mnemom code config set <key> <value>`");
+        add("info", `settings: none yet (${LAUNCHER_CONFIG_PATH}) — using built-in defaults`, "save your defaults with `mnemom agent config set <key> <value>`");
     // ── coding-agent CLI ──
     let cli;
     try {
@@ -41,16 +41,16 @@ export async function codeDoctorCommand(options = {}) {
         add("ok", `coding-agent CLI: ${cli.name} (${cli.bin})`);
     }
     catch (err) {
-        add("miss", `coding-agent CLI: ${err instanceof Error ? err.message.split("\n")[0] : err}`, "install Claude Code, or pass --cli <name|/full/path> / set it with `mnemom code config set cli <path>`");
+        add("miss", `coding-agent CLI: ${err instanceof Error ? err.message.split("\n")[0] : err}`, "install Claude Code, or pass --cli <name|/full/path> / set it with `mnemom agent config set cli <path>`");
     }
     // ── Anthropic key ──
     const keySrc = anthropicKeySource(env);
     if (keySrc === "env")
         add("ok", "Anthropic key: found in the environment");
     else if (keySrc === "store")
-        add("ok", "Anthropic key: found in ~/.mnemom/code.json");
+        add("ok", "Anthropic key: found in ~/.mnemom/launcher.json");
     else
-        add("miss", "Anthropic key: none found", "export MNEMOM_CODE_ANTHROPIC_KEY=sk-ant-… (or ANTHROPIC_API_KEY), or run `mnemom code` once and accept the save prompt");
+        add("miss", "Anthropic key: none found", "export MNEMOM_AGENT_ANTHROPIC_KEY=sk-ant-… (or ANTHROPIC_API_KEY), or run `mnemom agent` once and accept the save prompt");
     // ── gateway health ──
     const host = resolveGatewayHost(env);
     const cell = isProdGateway(env) ? "us-2/prod" : "custom";
@@ -62,7 +62,7 @@ export async function codeDoctorCommand(options = {}) {
         add("warn", `gateway: ${host} [${cell}] responded ${health.status} but without an x-mnemom-verdict header`, "the cell is up but the governance pipeline may not be wired — traces/nudges may not appear");
     }
     else {
-        add("warn", `gateway: ${host} [${cell}] unreachable (${health.detail})`, "check the host (MNEMOM_CODE_GATEWAY / `mnemom code config set gateway <url>`) and your network");
+        add("warn", `gateway: ${host} [${cell}] unreachable (${health.detail})`, "check the host (MNEMOM_AGENT_GATEWAY / `mnemom agent config set gateway <url>`) and your network");
     }
     // ── Remote Control capability ──
     if (cli) {
@@ -82,12 +82,12 @@ export async function codeDoctorCommand(options = {}) {
                 add("info", "claude.ai login: could not determine");
         }
     }
-    // ── Mnemom Code access (invited cohort gate) ──
+    // ── Mnemom Agent access (invited cohort gate) ──
     const gate = await probeCodeAccess();
     add(gate.mark, gate.text, gate.hint);
     // ── render ──
     const door = resolveAnthropicDoor(env);
-    out("mnemom code doctor");
+    out("mnemom agent doctor");
     out(`  door: ${door}`);
     out("");
     for (const l of lines) {
@@ -98,7 +98,7 @@ export async function codeDoctorCommand(options = {}) {
     out("");
     const launchReady = !lines.some((l) => l.mark === "miss");
     if (launchReady) {
-        out("  Ready to launch:  mnemom code");
+        out("  Ready to launch:  mnemom agent");
     }
     else {
         out("  Not launch-ready — resolve the [MISS] items above.");
@@ -153,26 +153,31 @@ export async function probeCodeAccess() {
     if (!(await isLoggedIn())) {
         return {
             mark: "info",
-            text: "Mnemom Code access: sign in to check",
-            hint: "run `mnemom login`; @mnemom.ai accounts are enabled by default, others need an invitation (mnemom code --invite <token>)",
+            text: "Mnemom Agent access: sign in to check",
+            hint: "run `mnemom login`; @mnemom.ai accounts are enabled by default, others need an invitation (mnemom agent --invite <token>)",
         };
     }
     const org = getActiveOrg();
     const orgLabel = org ? `${org.name} (${org.slug})` : "your personal org";
     try {
         const ent = await getCodeEntitlement(org?.org_id);
-        return { mark: "ok", text: `Mnemom Code access: enabled for ${orgLabel} (${sourceLabel(ent.source)})` };
+        return {
+            mark: "ok",
+            text: `Mnemom Agent access: enabled for ${orgLabel} (${sourceLabel(ent.source)})`,
+        };
     }
     catch (err) {
         if (isCodeNotEnabled(err)) {
             const hint = err.details?.hint;
             return {
                 mark: "miss",
-                text: `Mnemom Code access: not enabled for ${orgLabel}`,
-                hint: typeof hint === "string" && hint ? hint : "redeem an invitation: mnemom code --invite <token>",
+                text: `Mnemom Agent access: not enabled for ${orgLabel}`,
+                hint: typeof hint === "string" && hint
+                    ? hint
+                    : "redeem an invitation: mnemom agent --invite <token>",
             };
         }
         const detail = err instanceof MnemomApiError || err instanceof Error ? err.message : String(err);
-        return { mark: "info", text: `Mnemom Code access: could not determine (${detail})` };
+        return { mark: "info", text: `Mnemom Agent access: could not determine (${detail})` };
     }
 }

package/dist/commands/{code-invite.d.ts → agent-invite.d.ts}

@@ -1,7 +1,7 @@
 /**
- * Mnemom Code — the invited-cohort gate + `mnemom code --invite <token>`.
+ * Mnemom Agent — the invited-cohort gate + `mnemom agent --invite <token>`.
  *
- * `mnemom code` is open by default to Mnemom's own people (@mnemom.ai) and to
+ * `mnemom agent` is open by default to Mnemom's own people (@mnemom.ai) and to
  * customers who redeemed an invitation. The api decides
  * (`GET /v1/code/entitlement`); this module is the CLI side of that:
  *
@@ -10,13 +10,13 @@
  *     `code_not_enabled` BLOCKS with the api's own hint; anything inconclusive
  *     (network, 5xx, a membership 403) fails OPEN — the gate is a friendly
  *     pre-check, the api/gateway remain the real enforcement.
- *   - `codeInviteCommand(token)` redeems a `pinv_…` invitation
+ *   - `agentInviteCommand(token)` redeems a `pinv_…` invitation
  *     (`POST /v1/invites/accept`): signs the customer in first (creating a free
- *     account in the same flow if needed), unlocks Mnemom Code for them, and
- *     reports whether the starter µ landed. Backs both `mnemom code --invite
- *     <token> [scenario]` and the `mnemom code invite <token>` sub-verb.
+ *     account in the same flow if needed), unlocks Mnemom Agent for them, and
+ *     reports whether the starter µ landed. Backs both `mnemom agent --invite
+ *     <token> [scenario]` and the `mnemom agent invite <token>` sub-verb.
  *
- * All narration goes to stderr (the `mnemom code` convention — stdout is for
+ * All narration goes to stderr (the `mnemom agent` convention — stdout is for
  * the dry-run plan only). Copy says "µ", never "MU".
  */
 import { MnemomApiError, type AcceptProductInviteResult, type CodeEntitlement } from "../lib/api.js";
@@ -37,7 +37,7 @@ export declare function sourceLabel(source: CodeEntitlement["source"]): string;
 /** The api's `code_not_enabled` 403 — the ONE case that blocks. */
 export declare function isCodeNotEnabled(err: unknown): err is MnemomApiError;
 /**
- * Enforce the Mnemom Code gate for the org the launch targets. Blocks (prints
+ * Enforce the Mnemom Agent gate for the org the launch targets. Blocks (prints
  * guidance + throws CodeNotEnabledError) ONLY on a determined `code_not_enabled`;
  * every other failure is inconclusive and fails open with a dim note.
  */
@@ -51,15 +51,15 @@ export declare function explainAcceptError(err: unknown): string | null;
 /** Print the outcome of a successful accept. */
 export declare function printAccepted(res: AcceptProductInviteResult): void;
 /**
- * `mnemom code --invite <token>` / `mnemom code invite <token>`: sign in, redeem,
+ * `mnemom agent --invite <token>` / `mnemom agent invite <token>`: sign in, redeem,
  * report. Throws with a clear message on a bad token, no session, or an accept
  * failure the customer can act on; rethrows anything else.
  */
-export declare function codeInviteCommand(token: string | undefined, opts?: {
+export declare function agentInviteCommand(token: string | undefined, opts?: {
     interactive?: boolean;
     ensureSession?: EnsureSession;
 }): Promise<AcceptProductInviteResult>;
-export interface CodeInvocation {
+export interface AgentInvocation {
     /** The positional `[scenario]` (may be a reserved sub-verb such as "invite"). */
     scenario?: string;
     /** Everything after the scenario. */
@@ -67,7 +67,7 @@ export interface CodeInvocation {
     /** `--invite <token>`. */
     inviteFlag?: string;
 }
-export interface CodeInvocationDeps {
+export interface AgentInvocationDeps {
     redeem: (token: string | undefined) => Promise<unknown>;
     /** The launch half; `undefined` = no session name given (the launcher prompts in a terminal). */
     launch: (scenario: string | undefined) => Promise<void>;
@@ -75,10 +75,10 @@ export interface CodeInvocationDeps {
 /**
  * How the `code` command's positional + `--invite` compose — kept OUT of
  * index.ts so it is unit-testable:
- *   - `mnemom code invite <token>`            → redeem, done (sub-verb; "invite" is reserved)
- *   - `mnemom code --invite <token>`          → redeem, done
- *   - `mnemom code --invite <token> <scen>`   → redeem, then launch
- *   - `mnemom code <scen>`                    → launch
- *   - `mnemom code`                           → launch (the launcher asks for a name + goal)
+ *   - `mnemom agent invite <token>`            → redeem, done (sub-verb; "invite" is reserved)
+ *   - `mnemom agent --invite <token>`          → redeem, done
+ *   - `mnemom agent --invite <token> <scen>`   → redeem, then launch
+ *   - `mnemom agent <scen>`                    → launch
+ *   - `mnemom agent`                           → launch (the launcher asks for a name + goal)
  */
-export declare function runCodeInvocation(input: CodeInvocation, deps: CodeInvocationDeps): Promise<void>;
+export declare function runAgentInvocation(input: AgentInvocation, deps: AgentInvocationDeps): Promise<void>;

package/dist/commands/{code-invite.js → agent-invite.js}

@@ -1,7 +1,7 @@
 /**
- * Mnemom Code — the invited-cohort gate + `mnemom code --invite <token>`.
+ * Mnemom Agent — the invited-cohort gate + `mnemom agent --invite <token>`.
  *
- * `mnemom code` is open by default to Mnemom's own people (@mnemom.ai) and to
+ * `mnemom agent` is open by default to Mnemom's own people (@mnemom.ai) and to
  * customers who redeemed an invitation. The api decides
  * (`GET /v1/code/entitlement`); this module is the CLI side of that:
  *
@@ -10,13 +10,13 @@
  *     `code_not_enabled` BLOCKS with the api's own hint; anything inconclusive
  *     (network, 5xx, a membership 403) fails OPEN — the gate is a friendly
  *     pre-check, the api/gateway remain the real enforcement.
- *   - `codeInviteCommand(token)` redeems a `pinv_…` invitation
+ *   - `agentInviteCommand(token)` redeems a `pinv_…` invitation
  *     (`POST /v1/invites/accept`): signs the customer in first (creating a free
- *     account in the same flow if needed), unlocks Mnemom Code for them, and
- *     reports whether the starter µ landed. Backs both `mnemom code --invite
- *     <token> [scenario]` and the `mnemom code invite <token>` sub-verb.
+ *     account in the same flow if needed), unlocks Mnemom Agent for them, and
+ *     reports whether the starter µ landed. Backs both `mnemom agent --invite
+ *     <token> [scenario]` and the `mnemom agent invite <token>` sub-verb.
  *
- * All narration goes to stderr (the `mnemom code` convention — stdout is for
+ * All narration goes to stderr (the `mnemom agent` convention — stdout is for
  * the dry-run plan only). Copy says "µ", never "MU".
  */
 import { acceptProductInvite, CODE_NOT_ENABLED, getCodeEntitlement, MnemomApiError, } from "../lib/api.js";
@@ -28,7 +28,7 @@ const say = (line = "") => console.error(line);
 export class CodeNotEnabledError extends Error {
     orgLabel;
     constructor(orgLabel) {
-        super("Mnemom Code is not enabled for this organization");
+        super("Mnemom Agent is not enabled for this organization");
         this.orgLabel = orgLabel;
         this.name = "CodeNotEnabledError";
     }
@@ -38,7 +38,7 @@ export const INVITE_TOKEN_RE = /^pinv_[A-Za-z0-9_-]{8,}$/;
 export function looksLikeInviteToken(value) {
     return typeof value === "string" && INVITE_TOKEN_RE.test(value.trim());
 }
-const FALLBACK_HINT = "Ask your Mnemom contact for a Mnemom Code invitation, then run: mnemom code --invite <token>";
+const FALLBACK_HINT = "Ask your Mnemom contact for a Mnemom Agent invitation, then run: mnemom agent --invite <token>";
 /** Drop control characters (ANSI escapes included) from an api-supplied string before
  *  it reaches the terminal — defense in depth; the value is first-party but printed raw. */
 export function sanitizeTerminalText(s) {
@@ -70,16 +70,16 @@ function hintFrom(err) {
 }
 function printNotEnabled(orgLabel, hint) {
     say();
-    say(fmt.warn(`Mnemom Code isn't enabled for ${orgLabel} yet.`));
-    say(fmt.dim("  mnemom code is rolling out to an invited cohort. If you have an invitation token"));
+    say(fmt.warn(`Mnemom Agent isn't enabled for ${orgLabel} yet.`));
+    say(fmt.dim("  mnemom agent is rolling out to an invited cohort. If you have an invitation token"));
     say(fmt.dim("  (pinv_…), redeem it and you're in:"));
     say();
-    say("    mnemom code --invite <token>");
+    say("    mnemom agent --invite <token>");
     say();
     say(fmt.dim(`  ${hint}`));
 }
 /**
- * Enforce the Mnemom Code gate for the org the launch targets. Blocks (prints
+ * Enforce the Mnemom Agent gate for the org the launch targets. Blocks (prints
  * guidance + throws CodeNotEnabledError) ONLY on a determined `code_not_enabled`;
  * every other failure is inconclusive and fails open with a dim note.
  */
@@ -92,13 +92,13 @@ export async function assertCodeEnabled(orgId, orgLabel) {
             printNotEnabled(orgLabel, hintFrom(err));
             throw new CodeNotEnabledError(orgLabel);
         }
-        say(fmt.dim(`  (Could not verify Mnemom Code access — ${err instanceof Error ? err.message : String(err)}. Continuing.)`));
+        say(fmt.dim(`  (Could not verify Mnemom Agent access — ${err instanceof Error ? err.message : String(err)}. Continuing.)`));
     }
 }
 async function defaultEnsureSession(opts) {
     // Lazy import: code-setup imports assertCodeEnabled from THIS module, so a static
     // import here would be a cycle.
-    const { ensureMnemomSession } = await import("./code-setup.js");
+    const { ensureMnemomSession } = await import("./agent-setup.js");
     return ensureMnemomSession(opts);
 }
 /** Map an accept failure to the sentence the customer needs. Null = not ours to explain. */
@@ -121,10 +121,10 @@ export function explainAcceptError(err) {
 /** Print the outcome of a successful accept. */
 export function printAccepted(res) {
     if (res.already_accepted) {
-        say(fmt.success("This invitation was already accepted — Mnemom Code is unlocked for you."));
+        say(fmt.success("This invitation was already accepted — Mnemom Agent is unlocked for you."));
     }
     else {
-        say(fmt.success("Mnemom Code is unlocked for your account."));
+        say(fmt.success("Mnemom Agent is unlocked for your account."));
     }
     if (res.grant === "fired") {
         say(fmt.dim("  Your starter µ has been credited."));
@@ -132,27 +132,27 @@ export function printAccepted(res) {
     else if (res.grant === "deferred") {
         say(fmt.dim("  Your starter µ credit is pending — you can start now; if it hasn't landed shortly, contact support@mnemom.ai."));
     }
-    say(fmt.dim("  Start a governed session:  mnemom code"));
+    say(fmt.dim("  Start a governed session:  mnemom agent"));
 }
 /**
- * `mnemom code --invite <token>` / `mnemom code invite <token>`: sign in, redeem,
+ * `mnemom agent --invite <token>` / `mnemom agent invite <token>`: sign in, redeem,
  * report. Throws with a clear message on a bad token, no session, or an accept
  * failure the customer can act on; rethrows anything else.
  */
-export async function codeInviteCommand(token, opts = {}) {
+export async function agentInviteCommand(token, opts = {}) {
     const trimmed = (token ?? "").trim();
     if (!looksLikeInviteToken(trimmed)) {
-        throw new Error("mnemom code --invite: expected a Mnemom Code invitation token (pinv_…) — copy it from your invitation email.");
+        throw new Error("mnemom agent --invite: expected a Mnemom Agent invitation token (pinv_…) — copy it from your invitation email.");
     }
     const interactive = opts.interactive ?? isInteractive();
     const ensureSession = opts.ensureSession ?? defaultEnsureSession;
     const haveSession = await ensureSession({ interactive });
     if (!haveSession) {
-        throw new Error("mnemom code --invite: redeeming needs a Mnemom account.\n" +
+        throw new Error("mnemom agent --invite: redeeming needs a Mnemom account.\n" +
             "  Sign in:   mnemom login\n" +
             "  Then run the same --invite command again.");
     }
-    say(fmt.dim("  Redeeming your Mnemom Code invitation…"));
+    say(fmt.dim("  Redeeming your Mnemom Agent invitation…"));
     let result;
     try {
         result = await acceptProductInvite(trimmed);
@@ -160,7 +160,7 @@ export async function codeInviteCommand(token, opts = {}) {
     catch (err) {
         const explained = explainAcceptError(err);
         if (explained)
-            throw new Error(`mnemom code --invite: ${explained}`, { cause: err });
+            throw new Error(`mnemom agent --invite: ${explained}`, { cause: err });
         throw err;
     }
     printAccepted(result);
@@ -169,13 +169,13 @@ export async function codeInviteCommand(token, opts = {}) {
 /**
  * How the `code` command's positional + `--invite` compose — kept OUT of
  * index.ts so it is unit-testable:
- *   - `mnemom code invite <token>`            → redeem, done (sub-verb; "invite" is reserved)
- *   - `mnemom code --invite <token>`          → redeem, done
- *   - `mnemom code --invite <token> <scen>`   → redeem, then launch
- *   - `mnemom code <scen>`                    → launch
- *   - `mnemom code`                           → launch (the launcher asks for a name + goal)
+ *   - `mnemom agent invite <token>`            → redeem, done (sub-verb; "invite" is reserved)
+ *   - `mnemom agent --invite <token>`          → redeem, done
+ *   - `mnemom agent --invite <token> <scen>`   → redeem, then launch
+ *   - `mnemom agent <scen>`                    → launch
+ *   - `mnemom agent`                           → launch (the launcher asks for a name + goal)
  */
-export async function runCodeInvocation(input, deps) {
+export async function runAgentInvocation(input, deps) {
     if (input.scenario === "invite") {
         await deps.redeem(input.passthrough[0]);
         return;