@mnemom/mnemom 0.17.24 → 0.17.26

package/dist/commands/agent-slack.js

@@ -6,25 +6,28 @@
  *   mnemom agent slack login                 # store the bot + app-level tokens (0600)
  *   mnemom agent slack logout                # remove them
  *   mnemom agent slack status                # tokens, bot identity, router, live sessions
- *   mnemom agent slack post [--channel C] [--thread TS] [--icon-emoji E] <text…|->
+ *   mnemom agent slack post [--channel C] [--thread TS] [--icon-emoji E] [--] <text…|->
+ *                                            # --help prints usage; unknown flags are refused
  *   mnemom agent slack delete [--channel C] <ts>   # delete a message THIS session posted
  *   mnemom agent slack inbox [--peek]        # unread messages addressed to THIS session
+ *   mnemom agent slack alias                 # list handle → session aliases
+ *   mnemom agent slack alias <handle> <session>   # route @handle to <session> (idempotent)
+ *   mnemom agent slack alias --remove <handle>    # stop routing @handle
  *   mnemom agent slack listen                # this session's channel server (spawned by --slack)
  *   mnemom agent slack router                # the per-operator Socket Mode router (foreground)
  *
  * The poster name is MNEMOM_AGENT_SESSION_NAME, which the launcher sets in the
  * session's environment — an agent cannot pick another session's name here.
  */
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync } from "node:fs";
 import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
 import { runChannelServer } from "../lib/slack-channel.js";
 import { mergeStore, readStore } from "../lib/launcher-store.js";
 import { askInput, isInteractive } from "../lib/prompt.js";
 import { explainSlackError, looksLikeAppToken, looksLikeBotToken, deleteMessage, postMessage, resolveSlackToken, sessionPosterName, slackAppManifest, slackCall, SLACK_APP_TOKEN_STORE_KEY, SLACK_TOKEN_STORE_KEY, } from "../lib/slack.js";
 import { routerStatus, runRouter } from "../lib/slack-router.js";
-import { normSession } from "../lib/slack-route.js";
-import { findOwnPost, liveSessions, readInboxFrom, recordPost, slackDir, } from "../lib/slack-state.js";
+import { normHandle } from "../lib/slack-route.js";
+import { findOwnPost, freshInbox, listAliases, liveSessions, readInboxFrom, readOffset, recordPost, removeAlias, setAlias, writeOffset, } from "../lib/slack-state.js";
 const out = (line = "") => console.log(line);
 /** Entry point for `mnemom agent slack <verb> [args...]`. Throws on misuse. */
 export async function agentSlackCommand(argv) {
@@ -50,12 +53,14 @@ export async function agentSlackCommand(argv) {
             return del(rest);
         case "inbox":
             return inbox(rest);
+        case "alias":
+            return alias(rest);
         case "router":
             return router();
         case "listen":
             return listen();
         default:
-            throw new Error(`mnemom agent slack: unknown verb '${verb}'. Use manifest | login | logout | status | post | delete | inbox | listen | router.`);
+            throw new Error(`mnemom agent slack: unknown verb '${verb}'. Use manifest | login | logout | status | post | delete | inbox | alias | listen | router.`);
     }
 }
 function defaultAppName() {
@@ -118,18 +123,46 @@ async function status() {
     out(`router:         ${r.running ? `running (pid ${r.pid})` : "not running"}`);
     const live = liveSessions();
     out(`listening:      ${live.length ? live.join(", ") : "none"}`);
-    const allow = loadLauncherConfig().slackAllow ?? [];
+    const cfg = loadLauncherConfig();
+    const aliases = listAliases();
+    out(`aliases:        ${aliases.length ? aliases.map((a) => `@${a.handle} → ${a.session}`).join(", ") : "none"}${cfg.slackAliases ? "" : " (routing off — `mnemom agent config set slack_aliases true`)"}`);
+    out(`sticky threads: ${cfg.slackStickyThreads ? "on" : "off"}`);
+    const allow = cfg.slackAllow ?? [];
     out(`allowed senders: ${allow.length ? allow.join(", ") : "none — no message will reach a session"}`);
 }
+export const POST_USAGE = `Usage: mnemom agent slack post [options] [--] <text…|->
+
+Post a message to Slack as this session.
+
+Options:
+  -c, --channel <C>     channel name or id (default: slack_channel from \`mnemom agent config\`)
+  -t, --thread <TS>     reply in the thread whose parent message has this ts
+      --icon-emoji <E>  emoji to show as the poster's icon
+  -h, --help            show this help and exit; nothing is posted
+
+Text:
+  The remaining words, joined by spaces. \`-\` (or no words with a piped stdin) reads stdin.
+  Any other word starting with "-" before \`--\` is refused as an unknown flag. A message
+  that starts with "-" must come after \`--\`, e.g.  mnemom agent slack post -c C1 -- "-1 on this"`;
+const POST_SHORT_FLAGS = new Set(["-c", "-t", "-h"]);
+/**
+ * Parse `post` arguments. Before a `--` separator, `--help`/`-h` asks for usage and any
+ * other dash-word that is not a known flag is refused, so a typo or a guessed flag can
+ * never be posted as message text. Everything after `--` is text, verbatim.
+ */
 export function parsePostArgs(argv) {
     const res = { text: "" };
     const words = [];
+    let unknown;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         const val = () => {
             const v = argv[++i];
-            if (v === undefined)
+            // A flag is never a value: `--channel --help` must not eat the --help. (A short
+            // dash-word that is not a flag stays a value: `--icon-emoji -1` is Slack's thumbsdown.)
+            if (v === undefined || v.startsWith("--") || POST_SHORT_FLAGS.has(v)) {
                 throw new Error(`mnemom agent slack post: ${a} needs a value.`);
+            }
             return v;
         };
         if (a === "--channel" || a === "-c")
@@ -138,18 +171,32 @@ export function parsePostArgs(argv) {
             res.thread = val();
         else if (a === "--icon-emoji")
             res.iconEmoji = val();
+        else if (a === "--help" || a === "-h")
+            res.help = true;
         else if (a === "--") {
             words.push(...argv.slice(i + 1));
             break;
         }
+        else if (a.startsWith("-") && a !== "-")
+            unknown ??= a;
         else
             words.push(a);
     }
+    // Help wins over an unknown flag: someone asking for usage should get it.
+    if (res.help)
+        return { help: true, text: "" };
+    if (unknown !== undefined) {
+        throw new Error(`mnemom agent slack post: unknown flag ${unknown}; put message text after --. See \`mnemom agent slack post --help\`.`);
+    }
     res.text = words.join(" ");
     return res;
 }
 async function post(argv) {
     const args = parsePostArgs(argv);
+    if (args.help) {
+        process.stdout.write(POST_USAGE + "\n");
+        return;
+    }
     let text = args.text;
     if (text === "-" || (!text && !process.stdin.isTTY))
         text = readFileSync(0, "utf8");
@@ -196,37 +243,75 @@ async function del(argv) {
     out(JSON.stringify({ ok: true, deleted: own.ts, channel: own.channel }));
 }
 // ── inbox (pull) ─────────────────────────────────────────────────────────────
-// Normalised like the inbox file name, so a session name can never escape offsets/.
-const offsetFile = (session) => join(slackDir(), "offsets", `${normSession(session)}.off`);
-function readOffset(session) {
-    try {
-        return Number(readFileSync(offsetFile(session), "utf8")) || 0;
-    }
-    catch {
-        return 0;
-    }
-}
 /** Print (and, unless --peek, consume) the messages routed to this session. */
 async function inbox(argv) {
     const session = sessionPosterName(process.env);
     if (!session)
         throw new Error("mnemom agent slack inbox: not inside a `mnemom agent` session.");
     const { messages, offset } = readInboxFrom(session, readOffset(session));
-    if (!argv.includes("--peek")) {
-        mkdirSync(join(slackDir(), "offsets"), { recursive: true, mode: 0o700 });
-        writeFileSync(offsetFile(session), String(offset), { mode: 0o600 });
+    if (!argv.includes("--peek"))
+        writeOffset(session, offset);
+    // A held message past its expiry was already reported undelivered to its sender.
+    out(JSON.stringify(freshInbox(messages)));
+}
+export const ALIAS_USAGE = `Usage: mnemom agent slack alias                      # list
+       mnemom agent slack alias <handle> <session>   # route @handle to <session>
+       mnemom agent slack alias --remove <handle>    # stop routing @handle
+
+A handle is letters, digits and dashes (a leading @ is fine). The session is the name
+\`mnemom agent slack status\` lists under "listening" (e.g. agent-hdc-henry-dorsett-case);
+it need not be live yet. Setting the same pair again is a no-op.
+
+Aliases only route when \`mnemom agent config set slack_aliases true\` is set (off by
+default). Then a message for a session that is not listening is held: the sender is
+told it is waiting, and if the session has not read it within an hour, that it was
+not delivered.`;
+/**
+ * `alias` — list / set / remove operator-registered handle → session routes. Pure
+ * local state (lib/slack-state.ts); no Slack call, so a session can register its own
+ * handle at launch before the router has seen it.
+ */
+async function alias(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write(ALIAS_USAGE + "\n");
+        return;
+    }
+    const rm = argv.indexOf("--remove");
+    if (rm !== -1) {
+        const handle = argv[rm + 1];
+        if (!handle || argv.length !== 2 || handle.startsWith("-"))
+            throw new Error(`mnemom agent slack alias: --remove takes exactly one handle.\n${ALIAS_USAGE}`);
+        if (!normHandle(handle))
+            throw new Error(`mnemom agent slack alias: '${handle}' is not a usable handle (letters, digits, dashes).`);
+        const removed = removeAlias(handle);
+        out(JSON.stringify({ ok: true, removed, handle: normHandle(handle) }));
+        return;
     }
-    out(JSON.stringify(messages));
+    const unknown = argv.find((a) => a.startsWith("-"));
+    if (unknown)
+        throw new Error(`mnemom agent slack alias: unknown flag ${unknown}.\n${ALIAS_USAGE}`);
+    if (argv.length === 0) {
+        out(JSON.stringify(listAliases()));
+        return;
+    }
+    if (argv.length !== 2)
+        throw new Error(`mnemom agent slack alias: expected <handle> <session>.\n${ALIAS_USAGE}`);
+    const rec = setAlias(argv[0], argv[1]);
+    out(JSON.stringify({ ok: true, ...rec }));
 }
 async function router() {
     const store = readStore();
     const app = resolveSlackToken(process.env, store, "app").token;
     if (!app)
         throw new Error("mnemom agent slack router: no app-level token — run `mnemom agent slack login`.");
+    const cfg = loadLauncherConfig();
     await runRouter({
         botToken: botToken(),
         appToken: app,
-        allow: loadLauncherConfig().slackAllow ?? [],
+        allow: cfg.slackAllow ?? [],
+        // Both off unless the operator turned them on: off, routing is unchanged.
+        aliases: cfg.slackAliases === true,
+        stickyThreads: cfg.slackStickyThreads === true,
     });
 }
 async function listen() {

package/dist/commands/agent.d.ts

@@ -49,8 +49,13 @@ export interface AgentOptions {
     implicit?: boolean;
     /** `--lead-directed`: see `ContractFlags.leadDirected` (lib/agent.ts, MNE-8152). */
     leadDirected?: boolean;
-    /** x-mnemom-agent value (defaults to "code-agent"). */
+    /**
+     * `--agent` (or launcher.toml `agent`): a NAME (x-mnemom-agent; defaults to `agent-<handle>`), or
+     * a full `mnm-<uuid>` id, which PINS the launch to that agent (x-mnemom-agent-id).
+     */
     agent?: string;
+    /** launcher.toml `agent_id`: the pin when no `--agent` is given (selectLaunchAgent). */
+    agentId?: string;
     conversationId?: string;
     cli?: string;
     remoteControl?: boolean;
@@ -222,6 +227,8 @@ export declare function recordSessionLaunch(ctx: {
     agent: string;
     /** The claimed mnm- id the gateway serves for this launch (ensureClaimedServedAgent). */
     agentId: string;
+    /** The launch pinned `agentId` (`--agent mnm-<uuid>` / launcher.toml `agent_id`). */
+    pinned?: boolean;
     account: {
         orgId: string;
         orgLabel: string;
@@ -321,6 +328,22 @@ export interface BaseUrlProxyOptions {
  * pass through it), exits with this process, and is killed on exit.
  */
 export declare function startBaseUrlProxy(door: string, done: (baseUrl: string | null) => void, opts?: BaseUrlProxyOptions): void;
+/**
+ * The three secret lines the Remote Control proxy reads on stdin (anthropic, mnemom, openai). The
+ * Mnemom key rides line 2 on BOTH auth modes when the launch has one — the proxy forwards it as
+ * x-mnemom-api-key either way; a subscription launch always has one, an api-key launch has one
+ * when this machine stores one or the launch pins. Never logged.
+ */
+export declare function rcProxyStdin(ctx: {
+    anthropicKey?: string;
+    mnemomKey?: string;
+}): string;
+/**
+ * The agent id a launch pins, or undefined for a name launch: `--agent` when it is a full
+ * `mnm-<uuid>` (any case), else launcher.toml `agent_id` (only when no `--agent` was given —
+ * selectLaunchAgent). A truncated/garbled `mnm-…` throws instead of becoming a name.
+ */
+export declare function resolveLaunchPin(options: Pick<AgentOptions, "agent" | "agentId">): string | undefined;
 /**
  * Locates the `handoff` MCP server (src/mcp/handoff-server.mjs in dev, dist/mcp/handoff-server.mjs
  * once built — a raw, uncompiled `.mjs` file that `copy-assets.mjs` copies verbatim, exactly like
@@ -383,6 +406,11 @@ export declare function logLaunch(ctx: {
     cli: ResolvedCli;
     /** The plugin line (`pluginPlanLine`): `off`, `off (<why>)` or `<name> (<dir>)`. */
     plugin: string;
+    /**
+     * The composed Safe House mode (`readComposedProtection`), printed after the goal lines so
+     * the goal-contract mode and the protection mode are never mistaken for each other.
+     */
+    protection?: string;
 }): void;
 /** The launch line for the yolo default: permission prompts are skipped, and how to keep them. */
 export declare function permissionPromptsLine(cli: ResolvedCli): string;

package/dist/commands/agent.js

@@ -34,7 +34,7 @@ import { fileURLToPath } from "node:url";
 import { MEASURED_ENV, statuslineLaunch } from "../lib/statusline.js";
 import { getApiUrl, getGatewayUrl, MNEMOM_DIR } from "../lib/config.js";
 import { createApiKey } from "../lib/api.js";
-import { MNEMOM_KEY_STORE_FIELD, resolveAgentAuth, sayRetiredConsoleNotice, resolveSubscriptionMnemomKey, subscriptionChildEnv, subscriptionShape, } from "../lib/subscription-login.js";
+import { MNEMOM_KEY_STORE_FIELD, resolveAgentAuth, sayRetiredConsoleNotice, readMnemomKey, resolveSubscriptionMnemomKey, subscriptionChildEnv, subscriptionShape, } from "../lib/subscription-login.js";
 import { LEDGER_FILE, appendSessionRecord, findResumeCandidate, readSessionRecords, resolveRetentionDays, resumedContextProfile, toLedgerContract, } from "../lib/agent-ledger.js";
 import { isLoggedIn } from "../lib/auth.js";
 import { loadCliConfig } from "../lib/cli-config.js";
@@ -44,8 +44,8 @@ import { fmt } from "../lib/format.js";
 import { askInput, askSelect, askYesNo, isInteractive } from "../lib/prompt.js";
 import { authConfigured, chooseAuth, detectClaudeLogin, readClaudeLoginState, } from "../lib/login-detect.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
-import { defaultAgentSlug, ensureClaimedServedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.js";
-import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, assertCompactAtCompatible, assertOffProfileCompatible, compactAtWindowWarning, describeCompactAt, launchWindow, resolveCompactAt, applyGatewayHintHeaders, resolveCompactionIntercept, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, resolveUsageSavings, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, resumeCommand, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
+import { defaultAgentSlug, ensureClaimedServedAgent, ensureSessionAndBalance, isQuietPreambleExit, readComposedProtection, resolveDefaultSlug, resolvePinnedAgent, resolvePreflightedAccount, } from "./agent-setup.js";
+import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, assertCompactAtCompatible, assertOffProfileCompatible, compactAtWindowWarning, describeCompactAt, launchWindow, resolveCompactAt, applyGatewayHintHeaders, resolveCompactionIntercept, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, resolveUsageSavings, HANDOFF_RC_KEY_ENV_NAME, HANDOFF_RC_MNEMOM_KEY_ENV_NAME, malformedAgentIdMessage, parseAgentRef, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, resumeCommand, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
 import { LAUNCHER_STORE_PATH, mergeStore } from "../lib/launcher-store.js";
 import { slackChannelArgs } from "../lib/slack-launch.js";
 import { appendPluginDirsEnv, applyPluginEnv, pluginEnabled, pluginPlanLine, resolvePluginDir, } from "../lib/claude-plugin.js";
@@ -172,7 +172,13 @@ export async function agentCommand(scenarioArg, options = {}) {
     // "code-agent" — see defaultAgentSlug; provisioning claims exactly this slug.
     // `let` because a brand-new user who signs in during the pre-launch gate below
     // gets their real handle re-derived once the session exists.)
-    let agent = sanitizeAgentName(options.agent?.trim() || defaultAgentSlug());
+    //
+    // A full `mnm-<uuid>` (--agent, else launcher.toml agent_id) PINS the launch to that agent: its
+    // name is read after sign-in (resolvePinnedAgent) and the gateway must serve exactly it. A
+    // truncated `mnm-…` is refused rather than sent as a name — the gateway would birth a new agent
+    // named after the id (how a resume hint's id became a stray agent, 2026-10-08).
+    const pin = resolveLaunchPin(options);
+    let agent = pin ?? sanitizeAgentName(options.agent?.trim() || defaultAgentSlug());
     if (!agent) {
         throw new Error("mnemom agent: --agent sanitised to an empty string — pick a value with at least one letter or digit.");
     }
@@ -300,7 +306,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         // A defaulted slug is `agent-<handle>` from the login (resolved for real after
         // sign-in, below). Signed in: show that name. Signed out, or no usable handle:
         // say where it comes from rather than print the "agent-user" fallback as if it were it.
-        if (!options.agent?.trim()) {
+        if (!pin && !options.agent?.trim()) {
             agent =
                 ((await isLoggedIn()) && sanitizeAgentName(await resolveDefaultSlug())) ||
                     DRY_RUN_SIGNED_OUT_AGENT;
@@ -327,7 +333,9 @@ export async function agentCommand(scenarioArg, options = {}) {
         if (auth === "subscription") {
             say("mnemom agent: auth = subscription — Claude Code would use your claude.ai login (Team/Enterprise plans only) with a Mnemom API key; no Anthropic key.");
         }
-        say(`mnemom agent: the real launch first confirms the agent the gateway serves for '${agent}' is claimed — claiming it into the org the launch bills if it is not — and never runs on an unclaimed agent.`);
+        say(pin
+            ? `mnemom agent: pinned to ${pin} — the real launch reads its name, then runs only if the gateway serves exactly that agent (yours, claimed); it never claims or creates one.`
+            : `mnemom agent: the real launch first confirms the agent the gateway serves for '${agent}' is claimed — claiming it into the org the launch bills if it is not — and never runs on an unclaimed agent.`);
         if (expNotice)
             say(expNotice);
         if (shape !== "terminal") {
@@ -404,18 +412,33 @@ export async function agentCommand(scenarioArg, options = {}) {
     // Subscription login: Remote Control only for RC-entitled (internal) accounts, and the governed identity anchors on a
     // Mnemom API key (minted once and stored if there is none). Resolved after sign-in so
     // minting can use the session.
+    //
+    // An api-key launch sends this machine's existing Mnemom key too (env, else the store; never
+    // minted), so the gateway can resolve the key's owner — the safe core of #2291, which minted a
+    // new key and swapped it in on subscription launches (reverted, #2323). A pinned launch needs a
+    // key on every auth mode (the gateway honours a pin only with one), so it mints one if there
+    // is none. A subscription launch's key is resolved exactly as before.
     let mnemomKey;
     if (auth === "subscription") {
         shape = subscriptionShape(shape, shapeExplicit, rcAllowed, say);
         mnemomKey = await resolveSubscriptionMnemomKey(defaultMnemomKeyDeps());
     }
+    else {
+        mnemomKey = pin
+            ? await resolveSubscriptionMnemomKey(defaultMnemomKeyDeps(), "pinning an agent")
+            : readMnemomKey(defaultMnemomKeyDeps());
+    }
     // Now that a session exists, a defaulted slug uses the real login handle from
     // /v1/auth/me (the stored token has no email, so the pre-sign-in value was the
     // "agent-user" fallback). Only when the caller didn't name an agent. Under an
     // explicit --setup the lookup is strict and a missing handle aborts the launch:
     // provisioning "agent-user" would govern a different gateway identity than the
     // one a prior setup under the real handle created (MNE-7650).
-    if (!options.agent?.trim()) {
+    if (pin) {
+        // The pinned agent must be visible and claimed; its own name rides as x-mnemom-agent.
+        agent = (await resolvePinnedAgent(pin)).slug;
+    }
+    else if (!options.agent?.trim()) {
         const refreshed = sanitizeAgentName(await resolveDefaultSlug({ strict: options.setup === true }));
         if (refreshed)
             agent = refreshed;
@@ -425,16 +448,26 @@ export async function agentCommand(scenarioArg, options = {}) {
     // launch bills (account.orgId — the active/default org is never changed); anything else
     // refuses the launch. No prompt and no unclaimed fallback, interactive or not, preflighted or
     // not. `--no-setup` only skips the default-card writes.
-    const { agentId: servedAgentId } = await ensureClaimedServedAgent({
+    // A pinned launch takes ensureClaimedServedAgent's pin path: served must equal the pin.
+    const served = await ensureClaimedServedAgent({
         slug: agent,
         anthropicKey,
         mnemomKey,
+        pin,
         gatewayHost,
         orgId: account.orgId,
         orgLabel: account.orgLabel,
         setup: options.setup,
         governance: options.governance,
     });
+    const servedAgentId = served.agentId;
+    // The composed Safe House mode for the launch summary (MNE-8612). Started now so the read
+    // overlaps the continuation and ledger work below, awaited at logLaunch. Never rejects.
+    const protection = readComposedProtection(servedAgentId);
+    // The gateway refused the stored Mnemom key an api-key launch offered: its requests must not
+    // carry it either (the gateway would 401 every one).
+    if (served.mnemomKeyRejected)
+        mnemomKey = undefined;
     // ── conversation id ── an implicit relaunch continues its earlier conversation (IG5 #1, D1)
     // so the goal the gateway inferred there is still the one it steers by. Resolved here, after
     // sign-in and the agent refresh, because a resume needs the org, agent and gateway host to
@@ -524,6 +557,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         conversationId,
         agent,
         agentId: servedAgentId,
+        pinned: pin !== undefined,
         account,
         gatewayHost,
         shape,
@@ -547,6 +581,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         goalMode,
         cli,
         plugin: launchPlugin.line,
+        protection: await protection,
     });
     if (pluginWanted && cli.name === "claude" && !bundledPluginDir) {
         say(fmt.warn("mnemom agent: the Mnemom plugin folder is not in this install — launching without the Mnemom band and /mnemom."));
@@ -610,6 +645,7 @@ export async function agentCommand(scenarioArg, options = {}) {
                 gatewayHost: resolveHandoffGatewayHost(door),
                 anthropicKeySource,
                 agent,
+                agentId: pin,
                 conversationId,
                 sessionConfigB64,
                 serverScript: resolveHandoffServerScript(),
@@ -628,6 +664,7 @@ export async function agentCommand(scenarioArg, options = {}) {
             anthropicKey,
             mnemomKey,
             agent,
+            agentId: pin,
             scenario,
             conversationId,
             envelope,
@@ -641,7 +678,10 @@ export async function agentCommand(scenarioArg, options = {}) {
             handoffMcpConfigPath,
             resumeHint: (id) => resumeHintLine({
                 scenario,
-                agent: options.agent?.trim() ? agent : undefined,
+                // A pinned launch resumes pinned to the agent it was SERVED (servedAgentId === pin):
+                // the id is the one value that resumes into the same agent. A named launch repeats its
+                // name; a defaulted one repeats nothing.
+                agent: pin ? servedAgentId : options.agent?.trim() ? agent : undefined,
                 ccSessionId: id,
             }),
             knownCcSessionId: cc.id ?? continuedCcSessionId,
@@ -656,6 +696,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         anthropicKey,
         mnemomKey,
         agent,
+        agentId: pin,
         conversationId,
         scenario,
         envelope,
@@ -838,6 +879,7 @@ export function recordSessionLaunch(ctx) {
         conversation_id: ctx.conversationId,
         agent_slug: ctx.agent,
         agent_id: ctx.agentId,
+        ...(ctx.pinned ? { agent_pinned: true } : {}),
         org_id: ctx.account.orgId,
         org_label: ctx.account.orgLabel,
         gateway_host: ctx.gatewayHost,
@@ -1132,6 +1174,7 @@ function launchTerminal(ctx) {
         anthropicKey: ctx.anthropicKey,
         mnemomKey: ctx.mnemomKey,
         agent: ctx.agent,
+        agentId: ctx.agentId,
         conversationId: ctx.conversationId,
         contractB64: ctx.envelope?.base64,
         goalMode: ctx.goalMode ?? undefined,
@@ -1305,6 +1348,31 @@ export function startBaseUrlProxy(door, done, opts = {}) {
 // ───────────────────────────────────────────────────────────────────────────
 // Remote Control launch (terminal RC + headless server) — behind the bundled proxy
 // ───────────────────────────────────────────────────────────────────────────
+/**
+ * The three secret lines the Remote Control proxy reads on stdin (anthropic, mnemom, openai). The
+ * Mnemom key rides line 2 on BOTH auth modes when the launch has one — the proxy forwards it as
+ * x-mnemom-api-key either way; a subscription launch always has one, an api-key launch has one
+ * when this machine stores one or the launch pins. Never logged.
+ */
+export function rcProxyStdin(ctx) {
+    return `${ctx.anthropicKey ?? ""}\n${ctx.mnemomKey ?? ""}\n\n`;
+}
+/**
+ * The agent id a launch pins, or undefined for a name launch: `--agent` when it is a full
+ * `mnm-<uuid>` (any case), else launcher.toml `agent_id` (only when no `--agent` was given —
+ * selectLaunchAgent). A truncated/garbled `mnm-…` throws instead of becoming a name.
+ */
+export function resolveLaunchPin(options) {
+    const fromFlag = options.agent?.trim();
+    const raw = fromFlag || options.agentId?.trim();
+    if (!raw)
+        return undefined;
+    const ref = parseAgentRef(raw);
+    if (ref.kind === "malformed-id" || (!fromFlag && ref.kind === "name")) {
+        throw new Error(malformedAgentIdMessage(raw, fromFlag ? "--agent" : "agent_id"));
+    }
+    return ref.kind === "id" ? ref.id : undefined;
+}
 function launchRemoteControl(ctx) {
     warnAdapter(ctx.cli);
     for (const tool of ["node", "openssl"]) {
@@ -1321,6 +1389,7 @@ function launchRemoteControl(ctx) {
             ...process.env,
             MNEMOM_AGENT_RC_DOOR: ctx.door,
             MNEMOM_AGENT_RC_AGENT: ctx.agent,
+            MNEMOM_AGENT_RC_AGENT_ID: ctx.agentId ?? "",
             MNEMOM_AGENT_RC_CONVERSATION_ID: ctx.conversationId,
             MNEMOM_AGENT_RC_CONTRACT_B64: ctx.envelope?.base64 ?? "",
             MNEMOM_AGENT_RC_GOAL_MODE: ctx.goalMode ?? "",
@@ -1353,8 +1422,9 @@ function launchRemoteControl(ctx) {
     };
     process.on("exit", onExit);
     // Secrets on stdin — three lines (anthropic, mnemom, openai). An api-key launch sends the
-    // Anthropic key only; a subscription launch sends the Mnemom key only (the identity anchor —
-    // the user's OAuth bearer is what pays). openai is always empty on this Anthropic-only door.
+    // Anthropic key, plus this machine's Mnemom key when it has one (the key principal; always
+    // with a pin); a subscription launch sends the Mnemom key only (the identity anchor — the
+    // user's OAuth bearer is what pays). openai is always empty on this Anthropic-only door.
     // A proxy that exits before reading them turns this write into an EPIPE; that is
     // not a failure of its own — the exited-before-READY check below refuses the
     // launch. Any other stdin error fails closed like a spawn error.
@@ -1365,7 +1435,7 @@ function launchRemoteControl(ctx) {
         onExit();
         process.exit(1);
     });
-    proxy.stdin?.end(`${ctx.anthropicKey ?? ""}\n${ctx.anthropicKey ? "" : (ctx.mnemomKey ?? "")}\n\n`);
+    proxy.stdin?.end(rcProxyStdin(ctx));
     let stdoutBuf = "";
     const start = Date.now();
     const tryStart = () => {
@@ -1462,6 +1532,10 @@ function spawnRcCli(ctx) {
     // (Never on a subscription launch — handoff is turned off there, so there is no key to set.)
     if (ctx.handoffMcpConfigPath && ctx.anthropicKey) {
         childEnv[HANDOFF_RC_KEY_ENV_NAME] = ctx.anthropicKey;
+        // The Mnemom key the session's own requests carry (the proxy adds it), so a pinned handoff
+        // call proves the same principal.
+        if (ctx.mnemomKey)
+            childEnv[HANDOFF_RC_MNEMOM_KEY_ENV_NAME] = ctx.mnemomKey;
     }
     // The plugin's non-secret launch facts (MNEMOM_CC_*), also after the strip loop: not an
     // ANTHROPIC_* var, so the RC gate ignores them, and nothing here is a key or a header value.
@@ -1748,10 +1822,13 @@ export function logLaunch(ctx) {
     if (ctx.envelope) {
         say(`mnemom agent: contract statement: ${ctx.envelope.contract.statement}`);
         say(`mnemom agent: contract sha256[0:16]: ${ctx.envelope.sha}`);
+        say(`mnemom agent: contract mode: ${ctx.envelope.contract.mode ?? "nudge"}`);
     }
     else if (ctx.goalMode) {
         say(`mnemom agent: goal mode: ${ctx.goalMode} (inferred from your messages; watch x-mnemom-goal-revision / x-mnemom-goal-steer on each response)`);
     }
+    if (ctx.protection !== undefined)
+        say(`mnemom agent: protection: ${ctx.protection}`);
 }
 /** The launch line for the yolo default: permission prompts are skipped, and how to keep them. */
 export function permissionPromptsLine(cli) {

package/dist/commands/wrap.d.ts

@@ -26,5 +26,7 @@ export interface WrapOptions {
 export declare function wrapCommand(options?: WrapOptions): Promise<void>;
 export declare function birthThroughGateway(gatewayUrl: string, provider: Provider, agentName: string, providerKey: string, opts?: {
     timeoutMs?: number;
+    /** More request headers (e.g. the launch's `x-mnemom-api-key`, so the probe is asked as the launch will be). */
+    extraHeaders?: Record<string, string>;
 }): Promise<string>;
 export {};

package/dist/commands/wrap.js

@@ -211,6 +211,8 @@ export async function birthThroughGateway(gatewayUrl, provider, agentName, provi
     if (provider === "anthropic") {
         headers["anthropic-version"] = "2023-06-01";
     }
+    if (opts.extraHeaders)
+        Object.assign(headers, opts.extraHeaders);
     let url;
     let body;
     switch (provider) {
@@ -244,7 +246,17 @@ export async function birthThroughGateway(gatewayUrl, provider, agentName, provi
     const agentId = response.headers.get(AGENT_HEADER);
     if (!response.ok && !agentId) {
         const text = await response.text().catch(() => "");
-        throw new MnemomApiError(response.status, `Gateway returned ${response.status}: ${text.slice(0, 300)}`);
+        // The gateway's `{error:{code}}` (e.g. agent_name_ambiguous) rides on the error so a caller
+        // can say what to fix.
+        let code;
+        try {
+            const c = JSON.parse(text)?.error?.code;
+            code = typeof c === "string" ? c : undefined;
+        }
+        catch {
+            code = undefined;
+        }
+        throw new MnemomApiError(response.status, `Gateway returned ${response.status}: ${text.slice(0, 300)}`, { code });
     }
     if (!agentId || !/^mnm-/.test(agentId)) {
         throw new Error(`Gateway returned no mnm- agent id on the ${AGENT_HEADER} response header (status ${response.status}).`);

package/dist/index.js

@@ -37,7 +37,7 @@ import { applyConfigToEnv, launcherEntries, loadLauncherConfig, withoutDisabledE
 import { loadExperimentalState } from "./lib/cli-config.js";
 import { assertEnabled, EXPERIMENTAL_CONTRACT, gateCheck, ignoredSettingLines, reportCliError, } from "./lib/experimental.js";
 import { experimentalDisableCommand, experimentalEnableCommand, experimentalListCommand, runExperimentalMigration, } from "./commands/experimental.js";
-import { parseCompactAt, parseContextProfile, resolveImplicit, } from "./lib/agent.js";
+import { parseCompactAt, parseContextProfile, resolveImplicit, selectLaunchAgent, } from "./lib/agent.js";
 import { wrapCommand } from "./commands/wrap.js";
 import { onboardCommand } from "./commands/onboard.js";
 import { skillsListCommand, skillsDescribeCommand } from "./commands/skills.js";
@@ -154,9 +154,11 @@ const agentCmd = program
     .option("--budget <usd>", "Guardrail: spend ceiling in USD (positive number)")
     .option("--max-turns <n>", "Guardrail: turn ceiling (positive integer)")
     .option("--stall <n>", "Guardrail: consecutive no-write turns (positive integer)")
-    .option("--mode <nudge|enforce>", "Sealed contract mode (MNE-8199; default nudge). Under enforce, a crossed turn/budget/time " +
+    .option("--mode <nudge|enforce>", "Goal-contract mode (MNE-8199, default nudge). Under enforce, a crossed turn/budget/time " +
     "ceiling REFUSES the next request on this conversation until the owner raises it via a " +
-    "contract update — under nudge the ceiling only nudges, unchanged. Requires --goal.")
+    "contract update. Under nudge the ceiling only nudges, unchanged. Requires --goal. " +
+    "This is not the Safe House protection mode, which composes from the agent, team, org and " +
+    "platform cards (strictest wins). See `mnemom protection` for that mode.")
     .option("--lead-directed", "Seal the standard lead-directed requirement: own-branch push and draft/ready PR creation, " +
     "from a git worktree, on the lead's direction — not merging. Requires --goal; idempotent.")
     .addOption(new Option("--implicit", "EXPERIMENTAL (`mnemom experimental enable implicit`): implicit goal alignment — the gateway infers the goal from your messages and revises it as you steer (the default while the feature is on; not combinable with --goal/--requirement/--allow/--forbid/--goal-id/--mode/--lead-directed; the guardrail ceilings still apply)").hideHelp(hiddenUnless("implicit")))
@@ -313,7 +315,14 @@ const agentCmd = program
         // Sub-verb: `mnemom agent setup` provisions/claims the governed agent and
         // never launches. The agent slug follows the same precedence as a launch.
         if (scenario === "setup") {
-            await agentSetupCommand({ agent: program.opts().agent ?? cfg.agent, governance });
+            await agentSetupCommand({
+                ...selectLaunchAgent({
+                    flag: program.opts().agent,
+                    configAgent: cfg.agent,
+                    configAgentId: cfg.agentId,
+                }),
+                governance,
+            });
             return;
         }
         const numToStr = (n) => n === undefined ? undefined : String(n);
@@ -351,7 +360,12 @@ const agentCmd = program
             maxTurns: opts.maxTurns ?? (contractIntended ? numToStr(cfg.guardrails?.maxTurns) : undefined),
             stall: opts.stall ?? (contractIntended ? numToStr(cfg.guardrails?.stallTurns) : undefined),
             mode: opts.mode,
-            agent: parentOpts.agent ?? cfg.agent,
+            // --agent wins; else launcher.toml agent_id (a pin) over agent (a name).
+            ...selectLaunchAgent({
+                flag: parentOpts.agent,
+                configAgent: cfg.agent,
+                configAgentId: cfg.agentId,
+            }),
             conversationId: opts.conversationId,
             cli: opts.cli,
             remoteControl: opts.remoteControl,