@mnemom/mnemom 0.17.25 → 0.17.27

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

@@ -10,6 +10,9 @@
  *                                            # --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)
  *
@@ -33,4 +36,5 @@ export declare const POST_USAGE = "Usage: mnemom agent slack post [options] [--]
  * never be posted as message text. Everything after `--` is text, verbatim.
  */
 export declare function parsePostArgs(argv: string[]): PostArgs;
+export declare const ALIAS_USAGE = "Usage: mnemom agent slack alias                      # list\n       mnemom agent slack alias <handle> <session>   # route @handle to <session>\n       mnemom agent slack alias --remove <handle>    # stop routing @handle\n\nA handle is letters, digits and dashes (a leading @ is fine). The session is the name\n`mnemom agent slack status` lists under \"listening\" (e.g. agent-hdc-henry-dorsett-case);\nit need not be live yet. Setting the same pair again is a no-op.\n\nAliases only route when `mnemom agent config set slack_aliases true` is set (off by\ndefault). Then a message for a session that is not listening is held: the sender is\ntold it is waiting, and if the session has not read it within an hour, that it was\nnot delivered.";
 export {};

package/dist/commands/agent-slack.js

@@ -10,22 +10,24 @@
  *                                            # --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) {
@@ -51,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() {
@@ -119,7 +123,11 @@ 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…|->
@@ -235,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,12 +44,13 @@ 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, passthroughModel, 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";
 import { CLI_VERSION } from "../version.js";
+import { fetchTierIndex, profileMayMisfit, profileTierWarning, resolveTier, tierLaunchModel, } from "../lib/model-tier.js";
 /** The CLI's own provider-key store (zero 1Password): ~/.mnemom/launcher.json, 0600. */
 const CODE_STORE = LAUNCHER_STORE_PATH;
 const say = (line = "") => console.error(line);
@@ -117,16 +118,46 @@ function sayCompactAt(compactAt, window) {
  * The launch's window (resolveWindowModel) — Claude Code only: it is the adapter that reads the
  * window off the model id. `null` for any other CLI (or none resolved).
  */
+/** Claude Code's settings files for this launch's cwd (lib/agent readCcSettings). */
+function ccSettings() {
+    return readCcSettings({
+        cwd: process.cwd(),
+        configDir: (process.env.CLAUDE_CONFIG_DIR ?? "").trim() || join(homedir(), ".claude"),
+    });
+}
+/**
+ * The launch line when the chosen context profile is a poor fit for the launched model's tier
+ * (lib/model-tier), else null. Asks the gateway's /models.json for the tier only when the chosen
+ * profile is a poor fit for some tier (no profile ⇒ the gateway's tier default applies, nothing to
+ * warn about; `aggressive` fits every tier). `gatewayOrigin` is the origin of this launch's own
+ * Anthropic door (resolveHandoffGatewayHost), so the tier is read from the cell the session's
+ * model traffic goes to, even under a MNEMOM_AGENT_ANTHROPIC_GATEWAY door override. Warn-only:
+ * every step fails closed to "no line" on its own (readCcSettings skips unreadable files,
+ * fetchTierIndex turns any fetch/parse failure into null, the rest is pure), so it never refuses a
+ * launch.
+ */
+async function contextProfileTierWarning(profile, options, cli, gatewayOrigin) {
+    if (!profileMayMisfit(profile))
+        return null;
+    const { model, aliasEnv } = tierLaunchModel({
+        explicit: options.model,
+        passthroughModel: passthroughModel(options.passthrough ?? []),
+        env: process.env,
+        // Claude Code's own settings files name its model only for a Claude Code launch.
+        settings: cli?.name === "claude" ? ccSettings() : [],
+    });
+    const index = await fetchTierIndex(gatewayOrigin);
+    if (index === null)
+        return null;
+    return profileTierWarning({ profile, model, tier: resolveTier(model, index, aliasEnv) });
+}
 function windowModelFor(options, cli) {
     return cli?.name === "claude"
         ? resolveWindowModel({
             explicit: options.model,
             passthrough: options.passthrough ?? [],
             env: process.env,
-            settings: () => readCcSettings({
-                cwd: process.cwd(),
-                configDir: (process.env.CLAUDE_CONFIG_DIR ?? "").trim() || join(homedir(), ".claude"),
-            }),
+            settings: ccSettings,
         })
         : null;
 }
@@ -172,7 +203,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.");
     }
@@ -201,7 +238,12 @@ export async function agentCommand(scenarioArg, options = {}) {
     // ── door ──
     const gatewayHost = resolveGatewayHost(env);
     const door = resolveAnthropicDoor(env);
-    const cellError = singleCellError({ door, apiUrl: getApiUrl(), cellGateway: getGatewayUrl() });
+    const cellError = singleCellError({
+        door,
+        gateway: gatewayHost,
+        apiUrl: getApiUrl(),
+        cellGateway: getGatewayUrl(),
+    });
     if (cellError)
         throw new Error(cellError);
     const cellNote = isProdGateway(env) ? "us-2/prod" : `custom (${gatewayHost})`;
@@ -300,7 +342,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 +369,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 +448,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 +484,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 +593,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         conversationId,
         agent,
         agentId: servedAgentId,
+        pinned: pin !== undefined,
         account,
         gatewayHost,
         shape,
@@ -547,6 +617,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."));
@@ -584,6 +655,9 @@ export async function agentCommand(scenarioArg, options = {}) {
     if (yolo && shape !== "server")
         say(permissionPromptsLine(cli));
     sayContextProfile(contextProfile);
+    const tierWarning = await contextProfileTierWarning(contextProfile, options, cli, resolveHandoffGatewayHost(door));
+    if (tierWarning)
+        say(fmt.warn(tierWarning));
     sayCompaction(contextProfile, compactionIntercept, compactAt, launchWindow(win));
     // ── handoff MCP tool (MNE-7564) ── OFF by default: absent/false ⇒ handoffMcpConfigPath stays
     // undefined and buildCliArgs/spawnRcCli are byte-identical to a build without this flag. ON:
@@ -610,6 +684,7 @@ export async function agentCommand(scenarioArg, options = {}) {
                 gatewayHost: resolveHandoffGatewayHost(door),
                 anthropicKeySource,
                 agent,
+                agentId: pin,
                 conversationId,
                 sessionConfigB64,
                 serverScript: resolveHandoffServerScript(),
@@ -628,6 +703,7 @@ export async function agentCommand(scenarioArg, options = {}) {
             anthropicKey,
             mnemomKey,
             agent,
+            agentId: pin,
             scenario,
             conversationId,
             envelope,
@@ -641,7 +717,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 +735,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         anthropicKey,
         mnemomKey,
         agent,
+        agentId: pin,
         conversationId,
         scenario,
         envelope,
@@ -838,6 +918,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 +1213,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 +1387,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 +1428,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 +1461,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 +1474,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 +1571,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 +1861,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}).`);