@mnemom/mnemom 0.17.25 → 0.17.26

package/dist/commands/agent-setup.js

@@ -13,7 +13,7 @@
  * on drift). Specifically:
  *   - alignment card: autonomy_mode = observe, integrity_mode = off,
  *     principal.relationship = delegated_authority, coding bounded/forbidden
- *     actions, escalate-on-irreversible;
+ *     actions, no default escalation triggers (the customer adds their own);
  *   - protection card: mode = off, thresholds 0.60/0.80/0.95 and all four
  *     screen_surfaces declared, ready for when it is turned on.
  *   - goal-alignment: nudge — sealed per-conversation via the goal contract
@@ -31,20 +31,21 @@
  * (agents.ts), claimAgent + putAlignmentCard/putProtectionCard (lib/api.ts) — rather than
  * reinventing it.
  */
-import { claimAgent, getAgent, getAgentByName, getCardSources, getMe, getMuBalance, getMyPersonalOrg, MnemomApiError, mintProtectionCapability, putAlignmentCard, putProtectionCard, } from "../lib/api.js";
+import { claimAgent, getAgent, getAgentByName, getCardSources, getMe, getMuBalance, getMyPersonalOrg, listMyAgents, MnemomApiError, mintProtectionCapability, putAlignmentCard, putProtectionCard, } from "../lib/api.js";
 import { getAuthInfo, loginWithBrowser, loginWithDeviceFlow, resolveAuth } from "../lib/auth.js";
 import { getActiveOrg } from "../lib/cli-config.js";
 import { getApiUrl, getGatewayUrl, getWebsiteUrl, MNEMOM_DIR } from "../lib/config.js";
 import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.js";
-import { resolveAnthropicDoor, resolveGatewayHost, sanitizeAgentName, singleCellError, } from "../lib/agent.js";
+import { malformedAgentIdMessage, parseAgentRef, resolveAnthropicDoor, resolveGatewayHost, sanitizeAgentName, singleCellError, } from "../lib/agent.js";
+import { readMnemomKey, resolveSubscriptionMnemomKey } from "../lib/subscription-login.js";
 import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
-import { IdentityRouteMissingError, resolveServedIdentity } from "../lib/agent-identity-route.js";
+import { IdentityRouteMissingError, resolveServedIdentity, resolveServedIdentityDetail, } from "../lib/agent-identity-route.js";
 import { readConfirmedAgent, readServedAgent, servedFingerprint, writeConfirmedAgent, writeServedAgent, } from "../lib/served-agent-cache.js";
 import { deriveHashProof } from "./agents.js";
 import { birthThroughGateway } from "./wrap.js";
-import { resolveAnthropicKey } from "./agent.js";
-import { assertCodeEnabled, CodeNotEnabledError, REQUEST_ACCESS_URL } from "./agent-invite.js";
+import { defaultMnemomKeyDeps, resolveAnthropicKey } from "./agent.js";
+import { assertCodeEnabled, CodeNotEnabledError, REQUEST_ACCESS_URL, sanitizeTerminalText, } from "./agent-invite.js";
 const say = (line = "") => console.error(line);
 /** The feature names `--governance <list>` accepts (plus `all` / `none`). */
 export const GOVERNANCE_FEATURES = ["integrity", "safe-house"];
@@ -92,6 +93,105 @@ const modeOf = (on) => (on ? "observe" : "off");
 export function describeModes(m) {
     return `integrity ${m.integrity}, Safe House ${m.protection}`;
 }
+/**
+ * The governance mode ladder, weakest first. The same order mnemom-api composes
+ * on (compose.ts ALIGNMENT_MODE_ORDER and PROTECTION_MODE_ORDER): strictest wins.
+ */
+export const MODE_LADDER = ["off", "observe", "nudge", "enforce"];
+/** A mode's rung on MODE_LADDER, or -1 when it is not on the ladder (absent, "unknown"). */
+export function modeRank(mode) {
+    return mode === undefined ? -1 : MODE_LADDER.indexOf(mode);
+}
+/**
+ * True when the composed mode sits on a higher rung than the agent's own card, so a
+ * stricter layer decides the mode that runs. An agent card that sets no mode, or a
+ * composed mode that is not on the ladder, is never an outrank.
+ */
+export function outranksAgentCard(own, effective) {
+    const mine = modeRank(own);
+    return mine >= 0 && modeRank(effective) > mine;
+}
+/**
+ * The upstream layers of a sources envelope whose own card sets `field` to `mode`,
+ * named for a person (`team "Lane Leads"`, `org "Acme"`, `platform`), in cascade
+ * order. Those are the layers that put the composed mode where it is. `platform`
+ * is asked for only where the platform card is a floor (protection mode); for
+ * integrity_mode it is only a default, so it never outranks an agent card that
+ * sets one. Empty when no layer row matches (an older api without the rows, or a
+ * composed card older than a template edit).
+ */
+export function layersSettingMode(sources, field, mode, opts) {
+    if (!sources)
+        return [];
+    // Org and team names are customer-written: drop control characters before they print.
+    const named = (kind, name, id) => name
+        ? `${kind} "${sanitizeTerminalText(name)}"`
+        : id
+            ? `${kind} ${sanitizeTerminalText(id)}`
+            : kind;
+    const out = [];
+    if (opts.platform && modeField(sources.platform?.card_json, field) === mode) {
+        out.push("platform");
+    }
+    const org = sources.org;
+    if (modeField(org?.card_json, field) === mode) {
+        out.push(named("org", org?.org_name, org?.org_id));
+    }
+    for (const team of sources.teams ?? []) {
+        if (modeField(team.card_json, field) === mode) {
+            out.push(named("team", team.team_name, team.team_id));
+        }
+    }
+    return out;
+}
+/**
+ * The composed Safe House (protection) mode for the launch summary, naming the
+ * layer that set it when the agent's own card says something else:
+ * `enforce (from team "Lane Leads"; agent card: observe)`. Same mode as the
+ * agent card prints the mode alone. No composed card reads `unknown`.
+ */
+export function describeComposedProtection(sources) {
+    const effective = modeField(sources?.composed?.card_json, "mode");
+    if (!effective)
+        return "unknown (no composed protection card yet)";
+    const own = modeField(sources?.agent?.card_json, "mode");
+    if (own === effective)
+        return sanitizeTerminalText(effective);
+    const layers = layersSettingMode(sources, "mode", effective, { platform: true });
+    const from = layers.length > 0
+        ? `from ${layers.join(" and ")}`
+        : "from a stricter org, team or platform layer";
+    return sanitizeTerminalText(`${effective} (${from}; agent card: ${own ?? "none"})`);
+}
+/**
+ * How long the launch waits for the protection card sources before printing the
+ * line without them. An object so tests can shorten it, like TWIN_LISTING.
+ */
+export const PROTECTION_READ = { timeoutMs: 5_000 };
+/**
+ * The launch summary's protection phrase for `agentId`: one `getCardSources`
+ * read (`GET /v1/protection/agent/:id?include=sources`, the same read the doctor
+ * makes), which carries both the composed card and every layer's own card. Best
+ * effort: it never throws, so the caller can start it early and await it later,
+ * and a failed or slow read prints `unknown` rather than holding up the launch.
+ */
+export async function readComposedProtection(agentId) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("timed out reading the protection card")), PROTECTION_READ.timeoutMs);
+    });
+    try {
+        const sources = await Promise.race([getCardSources("protection", agentId), timeout]);
+        return describeComposedProtection(sources);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return `unknown (could not read the agent's protection card: ${sanitizeTerminalText(detail)})`;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** The mode string a raw card carries in `field`, or undefined when absent/not a string. */
 function modeField(card, field) {
     const v = card?.[field];
@@ -220,6 +320,19 @@ export const SERVED_PROBE_TIMEOUT_MS = 10_000;
  * three tries, about four seconds of backoff. Exported so tests can zero it.
  */
 export const CONFIRM_RETRY_DELAYS_MS = [1000, 3000];
+/** The gateway refused the Mnemom key an api-key launch sent alongside its Anthropic key. */
+class MnemomKeyRejectedError extends Error {
+    constructor() {
+        super("the gateway rejected the Mnemom API key");
+        this.name = "MnemomKeyRejectedError";
+    }
+}
+/** The gateway's 401 for a Mnemom key it looked up and found invalid (gateway/src/index.ts). */
+function isRejectedMnemomKey(err) {
+    return (err instanceof MnemomApiError &&
+        err.effectiveStatus === 401 &&
+        /invalid mnemom api key/i.test(err.message));
+}
 /**
  * Mnemom couldn't be reached to answer (a transient failure that outlived its retries). Carries
  * the served id when the gateway did answer before the api failed.
@@ -281,20 +394,36 @@ async function withRetry(call) {
  * Interactive and non-interactive runs behave the same: there is no prompt to decline.
  * MNE-7650: the name is client-controlled, so a same-named org agent proves nothing — only the
  * served id counts.
+ *
+ * A PINNED launch (`opts.pin`, from `--agent mnm-<uuid>` / launcher.toml `agent_id`) takes a
+ * separate path (ensurePinnedAgent): the gateway must serve exactly the pin, and it never claims.
+ *
+ * An api-key launch that also carries a Mnemom key (`opts.mnemomKey` beside `opts.anthropicKey`)
+ * asks the probe with it too, so the answer is the one its requests will get. If the gateway
+ * rejects that key, the launch continues without it (result.mnemomKeyRejected) rather than fail.
  */
 export async function ensureClaimedServedAgent(opts) {
     const slug = opts.slug;
+    if (opts.pin)
+        return ensurePinnedAgent(opts, opts.pin);
     const anchorKey = opts.anthropicKey || opts.mnemomKey;
     if (!anchorKey) {
         throw new UnclaimedAgentError(`mnemom agent: no credential anchors '${slug}' — an Anthropic key or a Mnemom API key is required.`);
     }
     const cacheDir = opts.cacheDir ?? MNEMOM_DIR;
-    const fp = servedFingerprint(anchorKey, slug, opts.gatewayHost.replace(/\/+$/, ""));
+    const fp = servedFingerprint(anchorKey, slug, opts.gatewayHost.replace(/\/+$/, ""), {
+        withMnemomKey: Boolean(opts.anthropicKey && opts.mnemomKey),
+    });
     let result;
     try {
         result = await confirmClaimed(opts, anchorKey, fp);
     }
     catch (err) {
+        if (err instanceof MnemomKeyRejectedError) {
+            say(fmt.warn("mnemom agent: the gateway rejected your stored Mnemom API key — launching without it (fix: `mnemom agent config` / re-run subscription setup, or unset MNEMOM_AGENT_MNEMOM_KEY)."));
+            const retried = await ensureClaimedServedAgent({ ...opts, mnemomKey: undefined });
+            return { ...retried, mnemomKeyRejected: true };
+        }
         if (!(err instanceof MnemomUnreachableError))
             throw err;
         const confirmed = readConfirmedAgent(cacheDir, fp);
@@ -310,7 +439,9 @@ export async function ensureClaimedServedAgent(opts) {
 async function confirmClaimed(opts, anchorKey, fp) {
     const slug = opts.slug;
     const agentId = await resolveServedAgent(opts, fp);
+    warnIfKeyReKeyed(opts, agentId);
     if (await isClaimed(slug, agentId)) {
+        await warnIfNameAmbiguous(slug, agentId, opts.orgId);
         if (opts.setup === true || (opts.governance && opts.setup !== false)) {
             // An explicit `mnemom agent setup` / --setup repairs or completes the cards (e.g. a
             // protection card that failed on a prior run before its one-time grant was minted).
@@ -335,6 +466,18 @@ async function confirmClaimed(opts, anchorKey, fp) {
         throw new UnclaimedAgentError(`mnemom agent: '${slug}' (${agentId}) is not claimed, and this launch has no org to claim it into. ` +
             "Choose one with `mnemom org use <org>`, then run `mnemom agent` again.");
     }
+    // Anti-twin: the caller already has a claimed agent of this name in this org, yet the gateway
+    // served a NEW one (another credential on the same name — a rotated Anthropic key, a new
+    // machine). Claiming it would mint a same-named twin that splits the agent's history and cards
+    // (the 2026-10-07 agent-wassim split). Refuse and say how to pin the existing one instead.
+    //
+    // If the listing itself fails (api down, a timeout, an older api), the guard is skipped and
+    // the launch claims as before: refusing on a failed read would turn a Mnemom hiccup into a
+    // hard stop for every first launch, and the claim below is still the P0 rule's own gate.
+    const twins = await claimedSameNamedAgents(slug, agentId, opts.orgId).catch(() => null);
+    if (twins && twins.length > 0) {
+        throw new UnclaimedAgentError(twinRefusal(slug, agentId, twins, opts.orgLabel));
+    }
     try {
         const hashProof = deriveHashProof(anchorKey, slug);
         await withRetry(() => claimAgent(agentId, { hashProof, orgId: opts.orgId }));
@@ -385,6 +528,8 @@ async function resolveServedAgent(opts, fp) {
                 return cached;
             const served = await withRetry(() => birthThroughGateway(gatewayUrl, "anthropic", slug, anthropicKey, {
                 timeoutMs: opts.setup === true ? undefined : SERVED_PROBE_TIMEOUT_MS,
+                // Asked exactly as the launch's requests will be: with the Mnemom key when it sends one.
+                extraHeaders: opts.mnemomKey ? { "x-mnemom-api-key": opts.mnemomKey } : undefined,
             }));
             writeServedAgent(cacheDir, fp, served);
             return served;
@@ -395,16 +540,247 @@ async function resolveServedAgent(opts, fp) {
         return await withRetry(() => resolveServedIdentity(gatewayUrl, slug, mnemomKey, { timeoutMs: SERVED_PROBE_TIMEOUT_MS }));
     }
     catch (err) {
+        if (opts.anthropicKey && opts.mnemomKey && isRejectedMnemomKey(err)) {
+            throw new MnemomKeyRejectedError();
+        }
         if (err instanceof IdentityRouteMissingError) {
             throw new UnclaimedAgentError(`mnemom agent: ${err.message}, so it can't confirm '${slug}' is claimed. ` +
                 "Launch with an Anthropic API key instead (`--auth api-key`), or try again once the gateway is updated.");
         }
+        if (err instanceof MnemomApiError && err.code === "agent_name_ambiguous") {
+            // The gateway won't pick between several of the caller's claimed agents of this name for a
+            // credential it has no agent for (and won't birth another). Name them when we can.
+            const ids = opts.orgId
+                ? await claimedSameNamedAgents(slug, "", opts.orgId).catch(() => null)
+                : null;
+            const which = ids && ids.length > 0 ? ` (${ids.join(", ")})` : "";
+            throw new UnclaimedAgentError(`mnemom agent: several of your agents are named '${slug}'${which} and this launch's credential has none of its own, so the gateway won't choose (agent_name_ambiguous).\n` +
+                `  Pin the one you mean: \`mnemom agent --agent mnm-<id>\`, or \`mnemom agent config set agent_id mnm-<id>\`.`);
+        }
         if (isTransient(err))
             throw new MnemomUnreachableError(err);
         throw new UnclaimedAgentError(`mnemom agent: the gateway wouldn't say which agent it serves for '${slug}' (${describeApiError(err)}). ` +
             "mnemom agent never runs on an agent it can't confirm is claimed.");
     }
 }
+/**
+ * How long the anti-twin listing may take before it is treated as failed (best effort). An
+ * object so tests can shorten it, like CONFIRM_RETRY_DELAYS_MS.
+ */
+export const TWIN_LISTING = { timeoutMs: 8_000 };
+/**
+ * The ids of the caller's OTHER live, claimed agents named `slug` in `orgId` — the same set the
+ * gateway's principal resolution picks from (claimed_by = the caller). Reads the caller's own
+ * agents (`GET /v1/agents?scope=all`), then each same-named one's full record for its claim and
+ * org; a tombstoned one (404) is skipped. Throws when the listing can't be completed in
+ * TWIN_LISTING.timeoutMs — every caller treats that as "unknown", never as "none".
+ */
+export async function claimedSameNamedAgents(slug, excludeId, orgId) {
+    const work = async () => {
+        const want = slug.toLowerCase();
+        const named = (await listMyAgents()).filter((a) => a.id !== excludeId && (a.name ?? "").toLowerCase() === want);
+        if (named.length === 0)
+            return [];
+        const me = (await getMe()).user_id;
+        const out = [];
+        for (const row of named) {
+            let agent;
+            try {
+                agent = await getAgent(row.id);
+            }
+            catch (err) {
+                if (err instanceof MnemomApiError && err.effectiveStatus === 404)
+                    continue;
+                throw err;
+            }
+            if (agent.claimed_by && agent.claimed_by === me && agent.org_id === orgId)
+                out.push(row.id);
+        }
+        return out;
+    };
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("timed out listing same-named agents")), TWIN_LISTING.timeoutMs);
+    });
+    try {
+        return await Promise.race([work(), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The refusal when an unclaimed served agent would become a same-named twin. */
+export function twinRefusal(slug, servedId, twins, orgLabel) {
+    const ids = twins.join(", ");
+    const example = twins[0];
+    return (`mnemom agent: you already have ${twins.length === 1 ? "an agent" : `${twins.length} agents`} named '${slug}' in ${orgLabel} (${ids}), ` +
+        `but this launch's credential is served a new, unclaimed one (${servedId}). ` +
+        "Claiming it would create a same-named twin, so mnemom agent stopped without claiming.\n" +
+        `  Pin the agent you mean: \`mnemom agent --agent ${example}\`, or set it once with \`mnemom agent config set agent_id ${example}\`.`);
+}
+/**
+ * A served agent that is already claimed while OTHER claimed agents of the caller share its name
+ * in this org: say once which one this launch runs as, and how to choose. Never refuses (that
+ * would break every launch that works today); a failed listing says nothing.
+ */
+async function warnIfNameAmbiguous(slug, servedId, orgId) {
+    if (!orgId)
+        return;
+    const others = await claimedSameNamedAgents(slug, servedId, orgId).catch(() => null);
+    if (!others || others.length === 0)
+        return;
+    say(fmt.dim(`mnemom agent: runs as ${servedId}; ${others.length + 1} of your agents are named '${slug}' (also ${others.join(", ")}) — pin one with --agent mnm-<id> or agent_id in launcher.toml.`));
+}
+/**
+ * An api-key launch that carries this machine's stored Mnemom key (the safe re-land of #2291)
+ * can be served a DIFFERENT agent than the same key + name without it — that's the entire point
+ * (the gateway's key-principal resolution; see CLAUDE.md "Changing resolveRequestIdentity
+ * re-keys scoped gateway state"). Every per-conversation key the gateway stores (fold state,
+ * compaction snapshots, goal contracts) is prefixed by the served agent id, so routing a launch
+ * to a different one silently strands that state behind the one this machine used to run as.
+ *
+ * This never refuses (the re-land is deliberate and the new agent may be exactly the right one
+ * — e.g. the key owner's own claimed agent), but it must not happen silently: say so, name both
+ * ids, and say how to keep running as the old one (pin it).
+ */
+function warnIfKeyReKeyed(opts, agentId) {
+    if (!opts.anthropicKey || !opts.mnemomKey)
+        return; // not an api-key launch carrying a key
+    const cacheDir = opts.cacheDir ?? MNEMOM_DIR;
+    const plainFp = servedFingerprint(opts.anthropicKey, opts.slug, opts.gatewayHost.replace(/\/+$/, ""));
+    const prior = readConfirmedAgent(cacheDir, plainFp);
+    if (!prior || prior === agentId)
+        return;
+    say(fmt.warn(`mnemom agent: carrying this machine's stored Mnemom key now serves '${opts.slug}' as ${agentId}, not ${prior} — the agent this machine last confirmed without that key. ` +
+        `${prior}'s goal history and compaction snapshots stay with ${prior}; they do not follow this launch. ` +
+        `To keep running as ${prior}, pin it: \`mnemom agent <scenario> --agent ${prior}\` (or \`agent_id\` in launcher.toml).`));
+}
+/**
+ * Resolve a pin before launch: the agent must be visible to the caller (the org-member view) and
+ * claimed; its name becomes the launch's slug (`x-mnemom-agent`, which the gateway checks against
+ * the pin). Any failure refuses — a pinned launch never falls back to a name.
+ */
+export async function resolvePinnedAgent(id) {
+    let agent;
+    try {
+        agent = await withRetry(() => getAgent(id));
+    }
+    catch (err) {
+        const status = err instanceof MnemomApiError ? err.effectiveStatus : undefined;
+        if (status === 404 || status === 403) {
+            throw new UnclaimedAgentError(`mnemom agent: agent ${id} was not found — it doesn't exist, was deleted, or isn't in an org you belong to. ` +
+                "See your agents with `mnemom agent list`.");
+        }
+        throw new UnclaimedAgentError(`mnemom agent: couldn't read the pinned agent ${id} (${describeApiError(err)}); try again. A pinned launch never falls back to another agent.`);
+    }
+    // The org-member view carries claimed_by; the public projection (someone else's public agent)
+    // does not — and a pin to it would be refused by the gateway anyway.
+    if (agent.claimed_by === undefined || (agent.caller && agent.caller !== "org_member")) {
+        throw new UnclaimedAgentError(`mnemom agent: agent ${id} isn't in an org you belong to, so this launch can't pin it. See your agents with \`mnemom agent list\`.`);
+    }
+    if (!agent.claimed_by) {
+        throw new UnclaimedAgentError(`mnemom agent: agent ${id} is not claimed, and mnemom agent never runs on an unclaimed agent. ` +
+            `Claim it first: \`mnemom agent claim ${id} --key <key>\`.`);
+    }
+    const slug = sanitizeAgentName(agent.name ?? "");
+    if (!slug) {
+        throw new UnclaimedAgentError(`mnemom agent: agent ${id} has no usable name to send as x-mnemom-agent; rename it, or launch by name.`);
+    }
+    return { id, slug };
+}
+/** The refusal for a pinned launch the gateway did not (or could not) honour. */
+function pinRefusal(err, pin, slug) {
+    const head = `mnemom agent: the gateway would not run this launch as ${pin}`;
+    if (err instanceof IdentityRouteMissingError) {
+        return `${head}: ${err.message}, so it can't pin yet. Launch by name (drop --agent ${pin} / agent_id) or try again once the gateway is updated.`;
+    }
+    const code = err instanceof MnemomApiError ? err.code : undefined;
+    const status = err instanceof MnemomApiError ? err.effectiveStatus : undefined;
+    if (code === "agent_pin_forbidden") {
+        return (`${head} (agent_pin_forbidden): it is not your claimed agent, or not in the org of the Mnemom API key this launch sends. ` +
+            "See your agents with `mnemom agent list`; a key minted in another org can't pin it.");
+    }
+    if (code === "agent_pin_mismatch") {
+        return `${head} (agent_pin_mismatch): its name is not '${slug}'. Pass the id alone (--agent ${pin}) so the launcher sends the agent's own name.`;
+    }
+    if (code === "agent_name_ambiguous") {
+        return `${head} (agent_name_ambiguous): it reports several of your agents named '${slug}' without honouring the pin, so it can't pin yet. Try again once the gateway is updated.`;
+    }
+    if (code === "mnemom_api_key_required" || status === 401) {
+        return (`${head}: a pin needs a valid Mnemom API key (${code ?? "401"}). ` +
+            "Set MNEMOM_AGENT_MNEMOM_KEY, or delete mnemom_api_key from ~/.mnemom/launcher.json so the next pinned launch mints a fresh one.");
+    }
+    return `${head} (${describeApiError(err)}). A pinned launch never falls back to another agent.`;
+}
+/**
+ * A pinned launch: ask the gateway's identity route which agent it serves for (Mnemom key, name,
+ * pin) on EVERY auth mode, and run only when it answers exactly the pin with `resolved_by:
+ * "pin"`. A gateway that predates pinning ignores the header and answers by name — that is a
+ * different agent, or the right one by coincidence for the wrong reason — so anything else
+ * refuses. Never claims, never births. The claim is re-checked here (P0) even though the
+ * gateway only honours a pin to the caller's own claimed agent. A transient failure may fall back
+ * to this machine's last confirmation of the SAME pin, exactly like the unpinned outage fallback.
+ */
+async function ensurePinnedAgent(opts, pin) {
+    const { slug } = opts;
+    const mnemomKey = opts.mnemomKey;
+    if (!mnemomKey) {
+        throw new UnclaimedAgentError(`mnemom agent: pinning ${pin} needs a Mnemom API key (the gateway honours a pin only with one). Set MNEMOM_AGENT_MNEMOM_KEY.`);
+    }
+    const gatewayUrl = opts.gatewayHost.replace(/\/+$/, "");
+    const cacheDir = opts.cacheDir ?? MNEMOM_DIR;
+    const fp = servedFingerprint(opts.anthropicKey || mnemomKey, slug, gatewayUrl, {
+        withMnemomKey: true,
+        pin,
+    });
+    const outageFallback = (reason) => {
+        if (readConfirmedAgent(cacheDir, fp) === pin) {
+            say(fmt.warn(`mnemom agent: couldn't reach Mnemom to confirm the pin (${describeApiError(reason)}) — launching on ${pin}, which this machine last confirmed.`));
+            return { slug, agentId: pin, claimedNow: false };
+        }
+        throw new UnclaimedAgentError(`mnemom agent: couldn't reach Mnemom to confirm the pinned agent ${pin} (${describeApiError(reason)}); try again.`);
+    };
+    let served;
+    try {
+        served = await withRetry(() => resolveServedIdentityDetail(gatewayUrl, slug, mnemomKey, {
+            timeoutMs: SERVED_PROBE_TIMEOUT_MS,
+            pin,
+        }));
+    }
+    catch (err) {
+        if (isTransient(err))
+            return outageFallback(err);
+        throw new UnclaimedAgentError(pinRefusal(err, pin, slug));
+    }
+    if (served.agentId !== pin || served.resolvedBy !== "pin") {
+        throw new UnclaimedAgentError(`mnemom agent: this gateway can't pin yet — asked for ${pin}, it answered ${served.agentId} (${served.resolvedBy ? `resolved by ${served.resolvedBy}` : "by name"}). ` +
+            `A pinned launch never runs as a different agent: launch by name (drop --agent ${pin} / agent_id), or try again once the gateway is updated.`);
+    }
+    let claimed;
+    try {
+        claimed = await isClaimed(slug, pin);
+    }
+    catch (err) {
+        if (err instanceof MnemomUnreachableError)
+            return outageFallback(err.reason);
+        throw err;
+    }
+    if (!claimed) {
+        throw new UnclaimedAgentError(`mnemom agent: the pinned agent ${pin} is not claimed, and mnemom agent never runs on an unclaimed agent. ` +
+            `Claim it first: \`mnemom agent claim ${pin} --key <key>\`.`);
+    }
+    if (opts.setup === true || (opts.governance && opts.setup !== false)) {
+        say(fmt.dim(`mnemom agent: pinned to ${pin} ('${slug}') — refreshing its cards.`));
+        const modes = await existingAgentModes(pin, opts.governance);
+        if (modes)
+            await publishDefaultCards(pin, modes);
+    }
+    else {
+        say(fmt.dim(`mnemom agent: pinned to ${pin} ('${slug}'), claimed.`));
+    }
+    writeConfirmedAgent(cacheDir, fp, pin);
+    return { slug, agentId: pin, claimedNow: false };
+}
 /**
  * Whether `agentId` is claimed. A 404/403 reads as unclaimed (an unclaimed sandbox agent can be
  * invisible to a normal user), so the caller claims it. A transient failure is retried and then
@@ -521,8 +897,17 @@ async function publishDefaultCards(agentId, modes) {
         say(fmt.dim(`  The agent is claimed and running; finish it later with \`${publishCmd}\`.`));
     }
 }
-/** `mnemom agent setup [--agent <slug>] [--governance …]` — the explicit provisioning entry point. */
+/**
+ * `mnemom agent setup [--agent <slug|mnm-id>] [--governance …]` — the explicit provisioning entry
+ * point. An id (`--agent mnm-<uuid>`, or launcher.toml `agent_id`) refreshes that pinned agent's
+ * cards and never claims or births; a malformed `mnm-…` refuses.
+ */
 export async function agentSetupCommand(opts = {}) {
+    const rawRef = opts.agent?.trim() || opts.agentId?.trim() || "";
+    const ref = rawRef ? parseAgentRef(rawRef) : null;
+    if (ref?.kind === "malformed-id") {
+        throw new Error(malformedAgentIdMessage(ref.raw, opts.agent?.trim() ? "--agent" : "agent_id").replace("mnemom agent:", "mnemom agent setup:"));
+    }
     const gatewayHost = resolveGatewayHost(process.env);
     const cellError = singleCellError({
         door: resolveAnthropicDoor(process.env),
@@ -542,16 +927,31 @@ export async function agentSetupCommand(opts = {}) {
         throw err;
     }
     const anthropicKey = await resolveAnthropicKey(process.env, { allowPrompt: true });
+    if (ref?.kind === "id") {
+        const pinned = await resolvePinnedAgent(ref.id);
+        await ensureClaimedServedAgent({
+            slug: pinned.slug,
+            anthropicKey,
+            mnemomKey: await resolveSubscriptionMnemomKey(defaultMnemomKeyDeps(), "pinning an agent"),
+            pin: pinned.id,
+            gatewayHost,
+            orgId: account.orgId,
+            orgLabel: account.orgLabel,
+            setup: true,
+            governance: opts.governance,
+        });
+        return;
+    }
     // Session exists now, so derive the real handle from /v1/auth/me. Strict: an
     // explicit setup never silently provisions "agent-user" (MNE-7650).
-    const slug = opts.agent?.trim()
-        ? sanitizeAgentName(opts.agent.trim())
-        : await resolveDefaultSlug({ strict: true });
+    const slug = ref?.kind === "name" ? sanitizeAgentName(ref.name) : await resolveDefaultSlug({ strict: true });
     if (!slug)
         throw new Error("mnemom agent setup: agent slug sanitised to empty — pass --agent <slug>.");
     await ensureClaimedServedAgent({
         slug,
         anthropicKey,
+        // Asked the way a launch asks: with this machine's Mnemom key when it has one (never minted).
+        mnemomKey: readMnemomKey(defaultMnemomKeyDeps()),
         gatewayHost,
         orgId: account.orgId,
         orgLabel: account.orgLabel,
@@ -780,13 +1180,9 @@ export function buildCodeAlignmentCard(agentId, modes = {
                 "exfiltrate_credentials",
                 "modify_ci_secrets",
             ],
-            escalation_triggers: [
-                {
-                    condition: "an irreversible or destructive operation is requested",
-                    action: "escalate",
-                    reason: "a human should confirm before irreversible changes",
-                },
-            ],
+            // No default "confirm irreversible operations" trigger (operator 2026-10-09):
+            // which operations need a human is the customer's call, added on their own card.
+            escalation_triggers: [],
         },
         audit: { retention_days: 30, queryable: false, trace_format: "otel" },
     };

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 {};