@mnemom/mnemom 0.17.9 → 0.17.11-next.0

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

@@ -17,12 +17,13 @@
  *   - goal-alignment: nudge — sealed per-conversation via the goal contract
  *     (--goal …), graded and re-anchored by the gateway.
  *
- * All account writes are gated: interactive runs show the plan and confirm;
- * non-interactive runs provision only with an explicit `--setup`, and otherwise
- * launch under the unclaimed (fail-open) identity with a clear warning. A
- * provisioning failure never blocks the launch. Reuses the existing machinery —
- * birthThroughGateway (wrap.ts), deriveHashProof (agents.ts), claimAgent +
- * putAlignmentCard/putProtectionCard (lib/api.ts) — rather than reinventing it.
+ * A launch never runs on an unclaimed agent (operator 2026-10-03): an unclaimed agent lands in
+ * the sandbox org and bills nobody. ensureClaimedServedAgent asks the gateway which agent it
+ * serves for this launch's credential + name, claims it into the org the launch bills when it
+ * is not claimed yet, and refuses otherwise — interactive or not, there is no unclaimed
+ * fallback. Reuses the existing machinery — birthThroughGateway (wrap.ts), deriveHashProof
+ * (agents.ts), claimAgent + putAlignmentCard/putProtectionCard (lib/api.ts) — rather than
+ * reinventing it.
  */
 import { type CodeEntitlement } from "../lib/api.js";
 /**
@@ -48,58 +49,75 @@ export declare function resolveDefaultSlug(opts?: {
     strict?: boolean;
 }): Promise<string>;
 /**
- * Thrown when a name-matched agent in the caller's org is NOT the agent the
- * gateway serves for (credential, name). Both ids are in the message; the
- * launcher treats it as fatal on an explicit `--setup` (MNE-7650).
+ * `mnemom agent` refuses to launch: the agent the gateway would serve is not claimed and could
+ * not be claimed here (or could not be identified at all). An unclaimed agent lands in the
+ * sandbox org and bills nobody, so there is no fallback — the message says what to do.
  */
-export declare class AgentIdentityMismatchError extends Error {
-    readonly slug: string;
-    /** The agent the org lookup found by name. */
-    readonly namedId: string;
-    /** The agent the gateway answered with on x-mnemom-agent. */
-    readonly servedId: string;
-    constructor(slug: string, 
-    /** The agent the org lookup found by name. */
-    namedId: string, 
-    /** The agent the gateway answered with on x-mnemom-agent. */
-    servedId: string);
+export declare class UnclaimedAgentError extends Error {
+    constructor(message: string);
 }
-export interface EnsureAgentOptions {
+export interface ClaimedAgentOptions {
     /** The already-resolved final agent slug (what rides as x-mnemom-agent). */
     slug: string;
-    /** The customer's Anthropic key (for the birth call + hash-proof). Never logged. */
-    anthropicKey: string;
-    /** undefined = auto, true = force (--setup), false handled by the caller (skip). */
-    setup?: boolean;
-    /** Gateway host the launch targets (birth goes to the same cell). */
+    /** Anthropic-key launch: the key that anchors the gateway identity. Never logged. */
+    anthropicKey?: string;
+    /** Subscription launch: the Mnemom API key that anchors the gateway identity. Never logged. */
+    mnemomKey?: string;
+    /** Gateway host the launch targets (the probe goes to the same cell). */
     gatewayHost: string;
-    /** Override interactivity (defaults to isInteractive()). */
-    interactive?: boolean;
+    /**
+     * The org this launch bills — the one ensureSessionAndBalance resolved and checked the µ of.
+     * A claim lands here. The active/default org is never changed.
+     */
+    orgId: string;
+    orgLabel: string;
+    /** true = --setup (re-ask the gateway, refresh the cards); false = --no-setup (no card writes). */
+    setup?: boolean;
     /** Where the served-agent cache lives (defaults to ~/.mnemom). */
     cacheDir?: string;
 }
 /** A bare launch never waits on the served-agent probe longer than this. */
 export declare const SERVED_PROBE_TIMEOUT_MS = 10000;
-export interface EnsureAgentResult {
+/**
+ * The waits between the tries of a call that failed transiently (network, timeout, 429, 5xx):
+ * three tries, about four seconds of backoff. Exported so tests can zero it.
+ */
+export declare const CONFIRM_RETRY_DELAYS_MS: number[];
+export interface ClaimedAgentResult {
     slug: string;
-    /** true only when this call actually birthed/claimed/published. */
-    provisioned: boolean;
-    /**
-     * The mnm- id the gateway serves for (key, slug), when this call learned it (a verified name
-     * match, a mismatch, or a fresh birth). Absent when it never asked the gateway.
-     */
-    agentId?: string;
+    /** The mnm- id the gateway serves for (credential, slug) — claimed when this returns. */
+    agentId: string;
+    /** true only when this call claimed it. */
+    claimedNow: boolean;
 }
 /**
- * Ensure `slug` is a usable governed agent in the customer's org. Returns
- * {provisioned:false} when it is already usable, when provisioning is not
- * allowed here (non-interactive without --setup, or not logged in), or when the
- * customer declines the confirm — in all those cases the launch continues under
- * the given slug. THROWS only on an actual provisioning failure (birth/claim/
- * card write) so the caller can decide whether that is fatal (`mnemom agent
- * setup`) or a warn-and-continue (a bare launch).
+ * A failure worth retrying, and that an outage fallback may cover: no answer at all (network,
+ * timeout, an unparseable reply) or a 408/429/5xx. A 4xx, a missing route, or a refusal is a
+ * definite answer.
+ */
+export declare function isTransient(err: unknown): boolean;
+/**
+ * The one invariant behind every `mnemom agent` launch: the coding CLI never starts unless the
+ * agent the gateway serves for THIS launch's credential + name is claimed.
+ *
+ * 1. Ask which agent the gateway serves (an Anthropic-key launch: the birth probe, cached per
+ *    key + name + gateway; a subscription launch: the gateway's identity route).
+ * 2. Read its claim state. Claimed ⇒ launch, and never claim it again: a re-claim by its owner
+ *    MOVES it to the requested org.
+ * 3. Unclaimed ⇒ claim it into `orgId` with the hash proof of the key that anchors it. Another
+ *    account owns it ⇒ refuse; any other claim failure ⇒ refuse.
+ *
+ * A definite answer (unclaimed and can't be claimed, owned by another account, the identity
+ * route missing, a rejected key) always refuses. A transient failure is retried; if Mnemom still
+ * can't be reached, the launch uses the agent this machine last confirmed claimed for the same
+ * credential + name — and only when the gateway hasn't since named a different one — or
+ * refuses. There is deliberately no switch that launches unclaimed (operator ruling 2026-10-03).
+ *
+ * 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.
  */
-export declare function ensureGovernedAgent(opts: EnsureAgentOptions): Promise<EnsureAgentResult>;
+export declare function ensureClaimedServedAgent(opts: ClaimedAgentOptions): Promise<ClaimedAgentResult>;
 /**
  * One line for an api failure that keeps the parts an operator can act on: the
  * message, the error code, and the scope the endpoint said it needed

package/dist/commands/agent-setup.js

@@ -17,22 +17,24 @@
  *   - goal-alignment: nudge — sealed per-conversation via the goal contract
  *     (--goal …), graded and re-anchored by the gateway.
  *
- * All account writes are gated: interactive runs show the plan and confirm;
- * non-interactive runs provision only with an explicit `--setup`, and otherwise
- * launch under the unclaimed (fail-open) identity with a clear warning. A
- * provisioning failure never blocks the launch. Reuses the existing machinery —
- * birthThroughGateway (wrap.ts), deriveHashProof (agents.ts), claimAgent +
- * putAlignmentCard/putProtectionCard (lib/api.ts) — rather than reinventing it.
+ * A launch never runs on an unclaimed agent (operator 2026-10-03): an unclaimed agent lands in
+ * the sandbox org and bills nobody. ensureClaimedServedAgent asks the gateway which agent it
+ * serves for this launch's credential + name, claims it into the org the launch bills when it
+ * is not claimed yet, and refuses otherwise — interactive or not, there is no unclaimed
+ * fallback. Reuses the existing machinery — birthThroughGateway (wrap.ts), deriveHashProof
+ * (agents.ts), claimAgent + putAlignmentCard/putProtectionCard (lib/api.ts) — rather than
+ * reinventing it.
  */
-import { claimAgent, getAgentByName, getMe, getMuBalance, getMyPersonalOrg, MnemomApiError, mintProtectionCapability, putAlignmentCard, putProtectionCard, } from "../lib/api.js";
-import { getAuthInfo, isLoggedIn, loginWithBrowser, loginWithDeviceFlow, resolveAuth, } from "../lib/auth.js";
+import { claimAgent, getAgent, getAgentByName, getMe, getMuBalance, getMyPersonalOrg, 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 { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
-import { readServedAgent, servedFingerprint, writeServedAgent } from "../lib/served-agent-cache.js";
+import { IdentityRouteMissingError, resolveServedIdentity } 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";
@@ -83,152 +85,230 @@ export async function resolveDefaultSlug(opts = {}) {
     return defaultAgentSlug();
 }
 /**
- * Thrown when a name-matched agent in the caller's org is NOT the agent the
- * gateway serves for (credential, name). Both ids are in the message; the
- * launcher treats it as fatal on an explicit `--setup` (MNE-7650).
+ * `mnemom agent` refuses to launch: the agent the gateway would serve is not claimed and could
+ * not be claimed here (or could not be identified at all). An unclaimed agent lands in the
+ * sandbox org and bills nobody, so there is no fallback — the message says what to do.
  */
-export class AgentIdentityMismatchError extends Error {
-    slug;
-    namedId;
-    servedId;
-    constructor(slug, 
-    /** The agent the org lookup found by name. */
-    namedId, 
-    /** The agent the gateway answered with on x-mnemom-agent. */
-    servedId) {
-        super(`mnemom agent setup: '${slug}' in your org is ${namedId}, but the gateway serves ${servedId} for this Anthropic key + name. ` +
-            "Refusing to govern the wrong agent. The gateway identity is hash(credential, name): a different key, " +
-            "or a prior setup under another slug, is a different agent. " +
-            `Either claim the served one (mnemom agent claim ${servedId} --key <the same key>) or launch with the --agent and key you set up.`);
-        this.slug = slug;
-        this.namedId = namedId;
-        this.servedId = servedId;
-        this.name = "AgentIdentityMismatchError";
+export class UnclaimedAgentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnclaimedAgentError";
     }
 }
 /** A bare launch never waits on the served-agent probe longer than this. */
 export const SERVED_PROBE_TIMEOUT_MS = 10_000;
 /**
- * Ensure `slug` is a usable governed agent in the customer's org. Returns
- * {provisioned:false} when it is already usable, when provisioning is not
- * allowed here (non-interactive without --setup, or not logged in), or when the
- * customer declines the confirm — in all those cases the launch continues under
- * the given slug. THROWS only on an actual provisioning failure (birth/claim/
- * card write) so the caller can decide whether that is fatal (`mnemom agent
- * setup`) or a warn-and-continue (a bare launch).
+ * The waits between the tries of a call that failed transiently (network, timeout, 429, 5xx):
+ * three tries, about four seconds of backoff. Exported so tests can zero it.
+ */
+export const CONFIRM_RETRY_DELAYS_MS = [1000, 3000];
+/**
+ * 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.
+ */
+class MnemomUnreachableError extends Error {
+    reason;
+    servedId;
+    constructor(reason, servedId) {
+        super(describeApiError(reason));
+        this.reason = reason;
+        this.servedId = servedId;
+        this.name = "MnemomUnreachableError";
+    }
+}
+/**
+ * A failure worth retrying, and that an outage fallback may cover: no answer at all (network,
+ * timeout, an unparseable reply) or a 408/429/5xx. A 4xx, a missing route, or a refusal is a
+ * definite answer.
  */
-export async function ensureGovernedAgent(opts) {
+export function isTransient(err) {
+    if (err instanceof UnclaimedAgentError || err instanceof IdentityRouteMissingError)
+        return false;
+    if (err instanceof MnemomApiError) {
+        const status = err.effectiveStatus;
+        return status === 408 || status === 429 || status >= 500;
+    }
+    return true;
+}
+/** `call`, retried with backoff while it fails transiently; the last failure is rethrown. */
+async function withRetry(call) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await call();
+        }
+        catch (err) {
+            if (!isTransient(err) || attempt >= CONFIRM_RETRY_DELAYS_MS.length)
+                throw err;
+            await sleep(CONFIRM_RETRY_DELAYS_MS[attempt]);
+        }
+    }
+}
+/**
+ * The one invariant behind every `mnemom agent` launch: the coding CLI never starts unless the
+ * agent the gateway serves for THIS launch's credential + name is claimed.
+ *
+ * 1. Ask which agent the gateway serves (an Anthropic-key launch: the birth probe, cached per
+ *    key + name + gateway; a subscription launch: the gateway's identity route).
+ * 2. Read its claim state. Claimed ⇒ launch, and never claim it again: a re-claim by its owner
+ *    MOVES it to the requested org.
+ * 3. Unclaimed ⇒ claim it into `orgId` with the hash proof of the key that anchors it. Another
+ *    account owns it ⇒ refuse; any other claim failure ⇒ refuse.
+ *
+ * A definite answer (unclaimed and can't be claimed, owned by another account, the identity
+ * route missing, a rejected key) always refuses. A transient failure is retried; if Mnemom still
+ * can't be reached, the launch uses the agent this machine last confirmed claimed for the same
+ * credential + name — and only when the gateway hasn't since named a different one — or
+ * refuses. There is deliberately no switch that launches unclaimed (operator ruling 2026-10-03).
+ *
+ * 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.
+ */
+export async function ensureClaimedServedAgent(opts) {
     const slug = opts.slug;
+    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 interactive = opts.interactive ?? isInteractive();
-    // 1. Already usable? A named agent in the caller's fleet is claimed by them.
-    const loggedIn = await isLoggedIn();
-    if (loggedIn) {
-        const existing = await getAgentByName(slug).catch(() => null);
-        if (existing) {
-            // MNE-7650: the name is client-controlled and the API exposes no
-            // agent_hash, so a name match proves nothing about which agent the
-            // gateway will serve for (key, slug) — it looks agents up by
-            // hash(credential, name) only. Ask the gateway on EVERY launch, not just
-            // under --setup: the same 16-token "hello" the birth path uses answers
-            // with the served mnm- id on x-mnemom-agent. A bare launch that trusted
-            // the name recorded and reported an org agent while the gateway governed
-            // a different, unclaimed one (a second Anthropic key on a shared name).
-            //
-            // The answer is stable per (key, name, gateway), so a bare launch reuses a cached one and
-            // only probes (time-boxed) the first time; --setup always re-asks.
-            const gatewayUrl = opts.gatewayHost.replace(/\/+$/, "");
-            const fp = servedFingerprint(opts.anthropicKey, slug, gatewayUrl);
-            const cached = opts.setup === true ? null : readServedAgent(cacheDir, fp);
-            let served;
-            try {
-                served =
-                    cached ??
-                        (await birthThroughGateway(gatewayUrl, "anthropic", slug, opts.anthropicKey, {
-                            timeoutMs: opts.setup === true ? undefined : SERVED_PROBE_TIMEOUT_MS,
-                        }));
-            }
-            catch (err) {
-                // --setup must know which agent it governs; a bare launch carries on
-                // with the id unresolved rather than guessing it from the name.
-                if (opts.setup === true)
-                    throw err;
-                say(fmt.dim(`mnemom agent: couldn't confirm which agent the gateway serves for '${slug}' (${err instanceof Error ? err.message : String(err)}) — launching anyway.`));
-                return { slug, provisioned: false };
-            }
-            if (!cached)
-                writeServedAgent(cacheDir, fp, served);
-            if (served !== existing.id) {
-                if (opts.setup === true)
-                    throw new AgentIdentityMismatchError(slug, existing.id, served);
-                warnServedMismatch(slug, existing.id, served);
-                return { slug, provisioned: false, agentId: served };
-            }
-            // On an EXPLICIT `mnemom agent setup`, repair/complete the cards on the
-            // already-claimed agent (e.g. a protection card that failed on a prior run
-            // before we minted its one-time grant). A bare launch leaves it alone.
-            if (opts.setup === true) {
-                say(fmt.dim(`mnemom agent: '${slug}' is already claimed (${existing.id}, the agent the gateway serves) — refreshing its cards.`));
-                await publishDefaultCards(existing.id);
-                persistAgentSlug(slug);
-                return { slug, provisioned: true, agentId: existing.id };
-            }
-            return { slug, provisioned: false, agentId: existing.id };
+    const fp = servedFingerprint(anchorKey, slug, opts.gatewayHost.replace(/\/+$/, ""));
+    let result;
+    try {
+        result = await confirmClaimed(opts, anchorKey, fp);
+    }
+    catch (err) {
+        if (!(err instanceof MnemomUnreachableError))
+            throw err;
+        const confirmed = readConfirmedAgent(cacheDir, fp);
+        if (confirmed && (err.servedId === undefined || err.servedId === confirmed)) {
+            say(fmt.warn(`mnemom agent: couldn't reach Mnemom to confirm '${slug}' (${err.message}) — launching on ${confirmed}, the agent this machine last confirmed claimed.`));
+            return { slug, agentId: confirmed, claimedNow: false };
         }
+        throw new UnclaimedAgentError(`mnemom agent: couldn't reach Mnemom to confirm your agent '${slug}' (${err.message}); try again.`);
     }
-    // 2. Are we allowed to provision here?
-    const canProvision = opts.setup === true || (opts.setup !== false && interactive);
-    if (!canProvision) {
-        warnUnclaimed(slug);
-        return { slug, provisioned: false };
+    writeConfirmedAgent(cacheDir, fp, result.agentId);
+    return result;
+}
+async function confirmClaimed(opts, anchorKey, fp) {
+    const slug = opts.slug;
+    const agentId = await resolveServedAgent(opts, fp);
+    if (await isClaimed(slug, agentId)) {
+        if (opts.setup === true) {
+            // 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).
+            say(fmt.dim(`mnemom agent: '${slug}' is ${agentId}, already claimed — refreshing its cards.`));
+            await publishDefaultCards(agentId);
+            persistAgentSlug(slug);
+        }
+        else {
+            say(fmt.dim(`mnemom agent: '${slug}' is ${agentId}, claimed.`));
+        }
+        return { slug, agentId, claimedNow: false };
+    }
+    // From here the agent is known to be unclaimed: every failure refuses, none falls back.
+    if (!opts.orgId) {
+        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.");
+    }
+    try {
+        const hashProof = deriveHashProof(anchorKey, slug);
+        await withRetry(() => claimAgent(agentId, { hashProof, orgId: opts.orgId }));
     }
-    // 3. Writing to the org needs a mnemom session.
-    if (!loggedIn) {
-        if (opts.setup === true && !interactive) {
-            throw new Error("not authenticated — run `mnemom login` (or set MNEMOM_API_KEY) first.");
+    catch (err) {
+        if (err instanceof MnemomApiError && err.code === "agent_cross_tenant") {
+            throw new UnclaimedAgentError(`mnemom agent: the agent for this key + name ('${slug}', ${agentId}) belongs to another Mnemom account. ` +
+                "Use a name of your own: `mnemom agent <scenario> --agent <a-name-of-your-own>`.");
         }
-        say(fmt.warn(`mnemom agent: not logged in — can't provision '${slug}'.`));
-        say(fmt.dim("  Run `mnemom login`, then `mnemom agent setup`. Launching with the unclaimed identity for now."));
-        return { slug, provisioned: false };
-    }
-    // 4. Confirm the plan (interactive runs; --setup non-interactive proceeds).
-    const org = getActiveOrg();
-    const orgLabel = org ? `${org.name} (${org.slug})` : "your personal org";
-    if (interactive) {
-        say(fmt.section("Set up a governed coding agent"));
-        say(fmt.label("  Agent:", slug));
-        say(fmt.label("  Org:", orgLabel));
-        say(fmt.label("  Posture:", "alignment + protection off (turn them on with `mnemom card` / `mnemom protection`); goal contracts nudge"));
-        say(fmt.dim("  Births the agent through the gateway, claims it to your org, and publishes its cards."));
-        if (!(await askYesNo("Provision and claim this agent now?", true))) {
-            say(fmt.dim("  Skipped — launching under the unclaimed identity. Run `mnemom agent setup` anytime."));
-            return { slug, provisioned: false };
+        // A concurrent launch of the same user (another fleet lane) may have claimed it first.
+        if (await isClaimed(slug, agentId).catch(() => false)) {
+            say(fmt.dim(`mnemom agent: '${slug}' is ${agentId}, claimed by another launch just now.`));
+            return { slug, agentId, claimedNow: false };
         }
+        throw new UnclaimedAgentError(`mnemom agent: couldn't claim '${slug}' (${agentId}) into ${opts.orgLabel} — ${describeApiError(err)}. ` +
+            "mnemom agent never runs on an unclaimed agent; fix that and run it again.");
     }
-    // 5. Birth → claim → publish the default (off) cards. (Key never logged.)
-    const gatewayUrl = opts.gatewayHost.replace(/\/+$/, "");
-    const agentId = await birthThroughGateway(gatewayUrl, "anthropic", slug, opts.anthropicKey);
-    const hashProof = deriveHashProof(opts.anthropicKey, slug);
-    await claimAgent(agentId, { hashProof, orgId: org?.org_id });
-    say(fmt.success(`mnemom agent: claimed '${slug}' (${agentId}) in ${orgLabel}.`));
-    // Publish the default (off) cards. A card write that can't complete (propagation
-    // right after the claim, or a missing cards:write scope) does NOT abort the
-    // provision — the agent is claimed and governed on whatever landed; we warn how
-    // to finish it. So `provisioned` reflects the claim, not a perfect card set.
-    await publishDefaultCards(agentId);
-    // 6. Remember the slug so future launches skip straight to usable.
+    say(fmt.success(`mnemom agent: claimed '${slug}' (${agentId}) in ${opts.orgLabel}.`));
+    await noteSameNamedAgent(slug, agentId);
+    // Publish the default (off) cards. A card write that can't complete does NOT undo the claim —
+    // the agent is claimed and governed on whatever landed; we warn how to finish it.
+    if (opts.setup !== false)
+        await publishDefaultCards(agentId);
     persistAgentSlug(slug);
-    return { slug, provisioned: true, agentId };
+    return { slug, agentId, claimedNow: true };
+}
+/**
+ * Which mnm- agent the gateway serves for this launch's credential + slug. A definite failure
+ * throws UnclaimedAgentError; a transient one that outlives its retries throws
+ * MnemomUnreachableError. A launch never guesses its agent from the name.
+ */
+async function resolveServedAgent(opts, fp) {
+    const { slug } = opts;
+    const gatewayUrl = opts.gatewayHost.replace(/\/+$/, "");
+    const cacheDir = opts.cacheDir ?? MNEMOM_DIR;
+    try {
+        if (opts.anthropicKey) {
+            const anthropicKey = opts.anthropicKey;
+            // The answer is stable per (key, name, gateway) and the probe costs a completion, so a
+            // bare launch reuses a cached one and only probes (time-boxed) the first time; --setup
+            // re-asks.
+            const cached = opts.setup === true ? null : readServedAgent(cacheDir, fp);
+            if (cached)
+                return cached;
+            const served = await withRetry(() => birthThroughGateway(gatewayUrl, "anthropic", slug, anthropicKey, {
+                timeoutMs: opts.setup === true ? undefined : SERVED_PROBE_TIMEOUT_MS,
+            }));
+            writeServedAgent(cacheDir, fp, served);
+            return served;
+        }
+        // Subscription: the identity route makes no upstream call, so it is asked on every launch
+        // (a later claim can change which agent the key's owner is served).
+        const mnemomKey = opts.mnemomKey ?? "";
+        return await withRetry(() => resolveServedIdentity(gatewayUrl, slug, mnemomKey, { timeoutMs: SERVED_PROBE_TIMEOUT_MS }));
+    }
+    catch (err) {
+        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 (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.");
+    }
 }
 /**
- * A bare launch whose name matches an org agent the gateway does NOT serve for this key. Not
- * fatal (no --setup asked to govern it), but the user must know their governance lands on the
- * served agent, and how to get a governed one of their own.
+ * 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
+ * throws MnemomUnreachableError; any other failure refuses.
  */
-function warnServedMismatch(slug, namedId, servedId) {
-    say(fmt.warn(`mnemom agent: '${slug}' in your org is ${namedId}, but the gateway serves ${servedId} for this Anthropic key + name — this session is governed as ${servedId}, which is not claimed to your org.`));
-    say(fmt.dim("  The gateway identity is hash(Anthropic key, name), so another key on the same name is a different agent. " +
-        `Use a name of your own: \`mnemom agent <scenario> --agent <unique-name> --setup\` (or claim the served one: \`mnemom agent claim ${servedId} --key <this key>\`).`));
+async function isClaimed(slug, agentId) {
+    let agent;
+    try {
+        agent = await withRetry(() => getAgent(agentId));
+    }
+    catch (err) {
+        const status = err instanceof MnemomApiError ? err.effectiveStatus : undefined;
+        if (status === 404 || status === 403)
+            return false;
+        if (isTransient(err))
+            throw new MnemomUnreachableError(err, agentId);
+        throw new UnclaimedAgentError(`mnemom agent: couldn't read whether '${slug}' (${agentId}) is claimed — ${describeApiError(err)}. ` +
+            "mnemom agent never runs on an agent it can't confirm is claimed.");
+    }
+    // The org-member view carries the claimed_by column; the public projection a `claimed` flag.
+    return agent.claimed_by !== undefined ? !!agent.claimed_by : agent.claimed === true;
+}
+/**
+ * After a claim: if the caller's org already had an agent of this name that is NOT the served
+ * one (another key on the same name, MNE-7650), say so — this launch governs the served one.
+ * Best effort.
+ */
+async function noteSameNamedAgent(slug, servedId) {
+    const named = await getAgentByName(slug).catch(() => null);
+    if (!named || named.id === servedId)
+        return;
+    say(fmt.dim(`  Note: '${slug}' in your org is ${named.id}, a different agent — the gateway identity is hash(key, name), ` +
+        `so this key runs as ${servedId}.`));
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
@@ -279,9 +359,9 @@ async function publishDefaultCards(agentId) {
     const align = await tryPublishCard("alignment", () => putAlignmentCard(agentId, JSON.stringify(buildCodeAlignmentCard(agentId)), "application/json"));
     // Protection is the "locked door": it needs a one-time cards:write:protection
     // grant that the claim does NOT include (alignment rides a standing cap). Mint
-    // it with our human login JWT — the "Provision and claim?" confirm is the
-    // explicit human approval, and the mint endpoint accepts a human operator (only
-    // agent OAuth principals are rejected). The next write consumes the grant. A
+    // it with our human login JWT — the human running `mnemom agent` (which claims
+    // the agent for them) is the approval, and the mint endpoint accepts a human
+    // operator (only agent OAuth principals are rejected). The next write consumes the grant. A
     // mint failure falls through to the write's retry + graceful degrade, but it
     // is NAMED: the mint's error code (e.g. an ownership `agent_org_forbidden`)
     // and `details.required_scope` are the actionable diagnosis — the downstream
@@ -323,8 +403,9 @@ export async function agentSetupCommand(opts = {}) {
     if (cellError)
         throw new Error(cellError.replace("mnemom agent:", "mnemom agent setup:"));
     // Sign in (offer sign-up) and enforce the MU balance before any account write.
+    let account;
     try {
-        await ensureSessionAndBalance({});
+        account = await ensureSessionAndBalance({});
     }
     catch (err) {
         if (isQuietPreambleExit(err))
@@ -339,14 +420,14 @@ export async function agentSetupCommand(opts = {}) {
         : await resolveDefaultSlug({ strict: true });
     if (!slug)
         throw new Error("mnemom agent setup: agent slug sanitised to empty — pass --agent <slug>.");
-    const result = await ensureGovernedAgent({ slug, anthropicKey, setup: true, gatewayHost });
-    if (!result.provisioned) {
-        say(fmt.dim(`  '${slug}' is ready (already claimed) or setup was skipped.`));
-    }
-}
-function warnUnclaimed(slug) {
-    say(fmt.warn(`mnemom agent: agent '${slug}' is not set up in your org — launching with an UNCLAIMED identity (governance is advisory/fail-open).`));
-    say(fmt.dim("  Provision it (creates + claims the agent, publishes default cards): mnemom agent setup"));
+    await ensureClaimedServedAgent({
+        slug,
+        anthropicKey,
+        gatewayHost,
+        orgId: account.orgId,
+        orgLabel: account.orgLabel,
+        setup: true,
+    });
 }
 function persistAgentSlug(slug) {
     try {

package/dist/commands/agent.d.ts

@@ -97,9 +97,9 @@ export interface AgentOptions {
      */
     compactionIntercept?: boolean;
     /**
-     * Governed-agent provisioning: undefined = AUTO (provision-with-confirm when
-     * interactive, warn-and-continue otherwise), true = force (`--setup`), false =
-     * skip entirely (`--no-setup`).
+     * Governed-agent cards. Every launch confirms (and if needed claims) the served
+     * agent regardless; true (`--setup`) re-asks the gateway and refreshes the
+     * default cards, false (`--no-setup`) skips the card writes.
      */
     setup?: boolean;
     /**
@@ -171,19 +171,16 @@ interface LaunchContinuationInput {
     ccSessionExists: (ccSessionId: string) => boolean;
 }
 /**
- * Record this launch in ~/.mnemom/sessions.jsonl. The agent record id is
- * resolved best-effort (a lookup failure or an unknown slug records null); a
- * ledger write failure warns to stderr and the launch proceeds regardless.
+ * Record this launch in ~/.mnemom/sessions.jsonl, with the claimed agent id the
+ * gateway serves; a ledger write failure warns to stderr and the launch proceeds
+ * regardless.
  */
 export declare function recordSessionLaunch(ctx: {
     session: string;
     conversationId: string;
     agent: string;
-    /**
-     * The id the gateway serves, as setup learned it (null = asked, unknown). Undefined = setup
-     * never asked, so fall back to the org's name lookup.
-     */
-    agentId?: string | null;
+    /** The claimed mnm- id the gateway serves for this launch (ensureClaimedServedAgent). */
+    agentId: string;
     account: {
         orgId: string;
         orgLabel: string;
@@ -200,7 +197,7 @@ export declare function recordSessionLaunch(ctx: {
     contextProfile: ContextProfile | null;
     /** The resolved compaction target this launch runs under (`resolveCompactAt`). */
     compactAt: number | null;
-}): Promise<void>;
+}): void;
 /** The real I/O behind a subscription launch's Mnemom key (lib/subscription-login.ts). */
 export declare function defaultMnemomKeyDeps(storePath?: string): MnemomKeyDeps;
 /** The real machine behind lib/console-key.ts: the macOS keychain via `security`, no shell. */

package/dist/commands/agent.js

@@ -33,7 +33,7 @@ import { basename, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { statuslineLaunch } from "../lib/statusline.js";
 import { getApiUrl, getGatewayUrl, MNEMOM_DIR } from "../lib/config.js";
-import { createApiKey, getAgentByName } from "../lib/api.js";
+import { createApiKey } from "../lib/api.js";
 import { MNEMOM_KEY_STORE_FIELD, resolveAgentAuth, resolveSubscriptionMnemomKey, subscriptionChildEnv, subscriptionShape, } from "../lib/subscription-login.js";
 import { LEDGER_FILE, appendSessionRecord, findResumeCandidate, readSessionRecords, resolveRetentionDays, resumedContextProfile, toLedgerContract, } from "../lib/agent-ledger.js";
 import { loadCliConfig } from "../lib/cli-config.js";
@@ -44,7 +44,7 @@ import { askInput, askSelect, askYesNo, isInteractive } from "../lib/prompt.js";
 import { authConfigured, chooseAuth, detectClaudeLogin, readClaudeLoginState, } from "../lib/login-detect.js";
 import { requireConsoleKey, readConsoleKey } from "../lib/console-key.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
-import { AgentIdentityMismatchError, defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.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, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, 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";
@@ -292,6 +292,7 @@ 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.`);
         if (auth === "console") {
             say("mnemom agent: auth = console — the launch would use the API key your Claude Code Anthropic Console login created.");
         }
@@ -388,40 +389,20 @@ export async function agentCommand(scenarioArg, options = {}) {
         if (refreshed)
             agent = refreshed;
     }
-    // ── zero-friction governed agent: make sure `agent` exists + is claimed in the
-    // customer's org (with the nudge/nudge coding posture) before we launch. AUTO
-    // provisions-with-confirm when interactive; warns and continues otherwise.
-    // Skipped entirely by `--no-setup`. A provisioning failure never blocks the
-    // launch — it degrades to the unclaimed (fail-open) identity with a warning.
-    // The agent id the gateway serves, when setup asked it (undefined = never asked, so the ledger
-    // falls back to the org's name lookup).
-    let servedAgentId;
-    if (options.setup !== false && !anthropicKey) {
-        // Subscription login: the gateway creates the agent in the Mnemom key's org on the first
-        // turn, so there is nothing to birth or claim here.
-        say(`mnemom agent: subscription login — '${agent}' is created in your org on the first turn (identity: your Mnemom API key).`);
-    }
-    else if (options.setup !== false && anthropicKey) {
-        servedAgentId = null; // asked below; stays null if setup can't tell
-        try {
-            const ensured = await ensureGovernedAgent({
-                slug: agent,
-                anthropicKey,
-                setup: options.setup,
-                gatewayHost,
-            });
-            servedAgentId = ensured.agentId ?? null;
-        }
-        catch (err) {
-            // An identity mismatch is the one setup failure that must NOT degrade: the
-            // launch would run as an agent other than the one --setup just tried to
-            // govern. Refuse, with both ids in the message (MNE-7650).
-            if (err instanceof AgentIdentityMismatchError)
-                throw err;
-            const msg = err instanceof Error ? err.message : String(err);
-            say(fmt.warn(`mnemom agent: agent setup did not complete (${msg}) — launching with the unclaimed identity.`));
-        }
-    }
+    // ── never an unclaimed agent ── the gateway serves hash(credential, name); the coding CLI
+    // starts only once THAT agent is claimed. An unclaimed one is claimed here into the org this
+    // 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({
+        slug: agent,
+        anthropicKey,
+        mnemomKey,
+        gatewayHost,
+        orgId: account.orgId,
+        orgLabel: account.orgLabel,
+        setup: options.setup,
+    });
     // ── 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
@@ -499,7 +480,7 @@ export async function agentCommand(scenarioArg, options = {}) {
     if (win?.reason === "one-m") {
         say(`mnemom agent: model ${win.from} → ${win.model} (1M context window; set ${DISABLE_1M_ENV}=1, or pass the model as \`-- --model <id>\`, to keep the standard window).`);
     }
-    await recordSessionLaunch({
+    recordSessionLaunch({
         session: scenario,
         conversationId,
         agent,
@@ -706,30 +687,19 @@ export async function resolveLaunchContinuation(input) {
     return { conversationId: resolveConversationId(conv), resumeCcSessionId };
 }
 /**
- * Record this launch in ~/.mnemom/sessions.jsonl. The agent record id is
- * resolved best-effort (a lookup failure or an unknown slug records null); a
- * ledger write failure warns to stderr and the launch proceeds regardless.
+ * Record this launch in ~/.mnemom/sessions.jsonl, with the claimed agent id the
+ * gateway serves; a ledger write failure warns to stderr and the launch proceeds
+ * regardless.
  */
-export async function recordSessionLaunch(ctx) {
-    // Never re-derive a known id from the name: the name can match an org agent the gateway does
-    // not serve for this key (MNE-7650), which is exactly what the ledger must not record.
-    let agentId;
-    if (ctx.agentId !== undefined) {
-        agentId = ctx.agentId;
-    }
-    else {
-        try {
-            agentId = (await getAgentByName(ctx.agent))?.id ?? null;
-        }
-        catch {
-            agentId = null; // unresolvable right now — the ledger still records the launch
-        }
-    }
+export function recordSessionLaunch(ctx) {
+    // The SERVED id, never one re-derived from the name: the name can match an org agent the
+    // gateway does not serve for this key (MNE-7650), which is exactly what the ledger must not
+    // record.
     const result = appendSessionRecord({
         session: ctx.session,
         conversation_id: ctx.conversationId,
         agent_slug: ctx.agent,
-        agent_id: agentId,
+        agent_id: ctx.agentId,
         org_id: ctx.account.orgId,
         org_label: ctx.account.orgLabel,
         gateway_host: ctx.gatewayHost,

package/dist/commands/try-me.d.ts

@@ -48,5 +48,18 @@ export interface TryMeOptions {
  * are surfaced as human guidance.
  */
 export declare function tryMeCommand(token: string, options?: TryMeOptions): Promise<void>;
+/**
+ * Classify a 401/403 card-write failure BY ITS ERROR CODE, never by status alone.
+ *
+ * - `grant-pending`: a PROTECTION 403 whose code says the one-time CISO grant
+ *   hasn't landed in the browser yet. This is expected and is polled for the
+ *   window; it must NOT trigger a re-login.
+ * - `refused`: any OTHER protection 403 (e.g. `feature_gated`, a billing
+ *   refusal). Waiting cannot fix it, so it fails fast with the server's reason
+ *   instead of polling for a grant the human already approved.
+ * - `auth`: a 401 anywhere, or an alignment 403 — the caller isn't authorized.
+ *   After a short propagation grace this means the session is stale/mismatched.
+ */
+export declare function classifyAuthError(kind: "alignment" | "protection", status: number | undefined, code?: string): "grant-pending" | "refused" | "auth";
 /** Render the resolved plan as human-readable text (no side effects). */
 export declare function renderPlan(manifest: BriefingManifest): string;

package/dist/commands/try-me.js

@@ -23,12 +23,12 @@
  * sign-in). That session IS the human's own — it is the headless twin of the
  * host-connector authorization in the MCP flow, not a forged credential.
  */
-import { resolveBriefing, birthAgent, fetchAgentClaimed, buildClaimUrl, buildGrantUrl, buildDojoDeepLink, claimProof, isTokenMode, looksLikeTryMeToken, sleep, } from "../lib/try-me.js";
+import { resolveBriefing, birthAgent, fetchAgentClaimed, buildClaimUrl, buildGrantUrl, buildDojoDeepLink, claimProof, describeOutOfMu, isTokenMode, looksLikeTryMeToken, sleep, } from "../lib/try-me.js";
 import { putAlignmentCard, putProtectionCard, listOrgAgents, MnemomApiError } from "../lib/api.js";
 import { resolveAuth, loginWithBrowser, loginWithDeviceFlow } from "../lib/auth.js";
 import { openBrowser } from "../lib/oauth.js";
 import { askSelect, askInput, askYesNo, isInteractive } from "../lib/prompt.js";
-import { getApiUrl, setApiUrlOverride } from "../lib/config.js";
+import { getApiUrl, getWebsiteUrl, setApiUrlOverride } from "../lib/config.js";
 import { fmt } from "../lib/format.js";
 import { getAgentName, mergeAgentConfig } from "../lib/agent-config.js";
 const POLL_INTERVAL_MS = 3000;
@@ -352,21 +352,44 @@ async function ensureSession(ctx, opts = {}) {
  */
 const AUTH_PROPAGATION_GRACE_MS = 20_000;
 /**
- * Classify a retriable (401/403) card-write failure.
+ * The 403 codes that mean "the one-time protection grant hasn't landed yet":
+ * mnemom-api's `agent_scope_forbidden` (a protection write with no live one-time
+ * capability) and the RFC 6750 `insufficient_scope` the manifest names.
+ */
+const GRANT_PENDING_CODES = new Set(["agent_scope_forbidden", "insufficient_scope"]);
+/**
+ * Classify a 401/403 card-write failure BY ITS ERROR CODE, never by status alone.
  *
- * - `grant-pending`: a PROTECTION 403 — the one-time CISO grant hasn't landed in
- *   the browser yet (the manifest's `insufficient_scope`). This is expected and
- *   is polled for the full window; it must NOT trigger a re-login. (Alignment is
- *   written first and has no grant, so a stale/wrong-account session is caught
- *   there before protection runs — making a protection 403 reliably the grant.)
+ * - `grant-pending`: a PROTECTION 403 whose code says the one-time CISO grant
+ *   hasn't landed in the browser yet. This is expected and is polled for the
+ *   window; it must NOT trigger a re-login.
+ * - `refused`: any OTHER protection 403 (e.g. `feature_gated`, a billing
+ *   refusal). Waiting cannot fix it, so it fails fast with the server's reason
+ *   instead of polling for a grant the human already approved.
  * - `auth`: a 401 anywhere, or an alignment 403 — the caller isn't authorized.
  *   After a short propagation grace this means the session is stale/mismatched.
  */
-function classifyAuthError(kind, status) {
-    if (status === 403 && kind === "protection")
-        return "grant-pending";
+export function classifyAuthError(kind, status, code) {
+    if (status === 403 && kind === "protection") {
+        return code !== undefined && GRANT_PENDING_CODES.has(code) ? "grant-pending" : "refused";
+    }
     return "auth";
 }
+/**
+ * The error for a card write that waiting or re-authenticating cannot fix: the
+ * server's own reason (and code), with a recharge link when it is about µ.
+ */
+function cardWriteRefusal(kind, agentId, err) {
+    const outOfMu = describeOutOfMu({ status: err.effectiveStatus, code: err.code, message: err.message, details: err.details }, getWebsiteUrl());
+    if (outOfMu) {
+        return new Error(`Couldn't set the ${kind} card. ${outOfMu} (--resume ${agentId})`, {
+            cause: err,
+        });
+    }
+    return new Error(`The server refused the ${kind} card for ${agentId}: ${err.message}` +
+        (err.code ? ` (${err.code})` : "") +
+        `. Fix that, then re-run with --resume ${agentId}.`, { cause: err });
+}
 /**
  * Write a card, tolerating the two legitimate transient unauthorized states and
  * escalating a persistent one instead of hanging:
@@ -397,10 +420,18 @@ async function writeCardWithRetry(kind, card, timeoutSeconds, ctx) {
             return;
         }
         catch (err) {
-            const status = err instanceof MnemomApiError ? err.effectiveStatus : undefined;
+            if (!(err instanceof MnemomApiError))
+                throw err; // not a server answer — surface it
+            const status = err.effectiveStatus;
+            // Out of µ / no billing account: a recharge prompt, not the raw error.
+            if (status === 402)
+                throw cardWriteRefusal(kind, agentId, err);
             if (status !== 401 && status !== 403)
                 throw err; // a real error — surface it
-            const kindOfFailure = classifyAuthError(kind, status);
+            const kindOfFailure = classifyAuthError(kind, status, err.code);
+            // Not a grant that hasn't landed: waiting won't help — say why, now.
+            if (kindOfFailure === "refused")
+                throw cardWriteRefusal(kind, agentId, err);
             // A stale/mismatched session: once the short propagation grace is spent,
             // re-authenticate as the agent's owner and retry the write exactly once.
             if (kindOfFailure === "auth" && Date.now() >= authGraceDeadline) {

package/dist/index.js

@@ -168,8 +168,8 @@ const agentCmd = program
 ]))
     .option("--trim-mcp", "Launch the CLI with no MCP servers (--strict-mcp-config + empty --mcp-config)")
     .option("--invite <token>", "Redeem a Mnemom Agent invitation (pinv_…): unlocks Mnemom Agent for you + credits your starter µ; launches too when a session name is given")
-    .option("--setup", "Provision + claim the governed agent before launch (non-interactive opt-in)")
-    .option("--no-setup", "Skip governed-agent provisioning entirely for this launch")
+    .option("--setup", "Re-check the served agent and refresh its default cards before launch")
+    .option("--no-setup", "Skip the default-card writes (the agent is still confirmed and claimed)")
     .option("--no-yolo", "Do NOT pass --dangerously-skip-permissions (yolo is on by default)")
     .option("--no-context-hint", "Do NOT seed Claude Code's context-hint feature flag before launch")
     .addOption(new Option("--slack", "EXPERIMENTAL (`mnemom experimental enable slack`): attach the Slack channel — messages addressed to this session arrive in it, and it can reply (see `mnemom agent slack`)").hideHelp(hiddenUnless("slack")))

package/dist/lib/agent-identity-route.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Which agent the gateway serves a SUBSCRIPTION-login launch (claude.ai login + a Mnemom API
+ * key) for one agent name — `POST /mnemom/agent/identity` on the gateway.
+ *
+ * An Anthropic-key launch learns its served agent from a 16-token birth completion
+ * (birthThroughGateway). A subscription launch has no Anthropic key to send, so the gateway
+ * exposes this route instead: it resolves the agent exactly as a proxied subscription request
+ * with the same Mnemom key + name would (the key owner's claimed agent of that name, else the
+ * hash(Mnemom key, name) agent, birthed if absent) and makes no upstream call. The key rides
+ * only in the request header and is never logged or echoed.
+ */
+export declare const IDENTITY_ROUTE_PATH = "/mnemom/agent/identity";
+/**
+ * The gateway answered 404: the identity route is not deployed on this cell. A subscription
+ * launch can't confirm its agent is claimed without it, so the launcher refuses.
+ */
+export declare class IdentityRouteMissingError extends Error {
+    readonly gatewayUrl: string;
+    constructor(gatewayUrl: string);
+}
+/**
+ * The mnm- id the gateway serves for (Mnemom key, name). Its response also carries claimed /
+ * org_id / resolved_by / created; the launcher reads the claim state from the api instead, so
+ * only the id is used here.
+ */
+export declare function resolveServedIdentity(gatewayUrl: string, agentName: string, mnemomKey: string, opts?: {
+    timeoutMs?: number;
+}): Promise<string>;

package/dist/lib/agent-identity-route.js

@@ -0,0 +1,57 @@
+/**
+ * Which agent the gateway serves a SUBSCRIPTION-login launch (claude.ai login + a Mnemom API
+ * key) for one agent name — `POST /mnemom/agent/identity` on the gateway.
+ *
+ * An Anthropic-key launch learns its served agent from a 16-token birth completion
+ * (birthThroughGateway). A subscription launch has no Anthropic key to send, so the gateway
+ * exposes this route instead: it resolves the agent exactly as a proxied subscription request
+ * with the same Mnemom key + name would (the key owner's claimed agent of that name, else the
+ * hash(Mnemom key, name) agent, birthed if absent) and makes no upstream call. The key rides
+ * only in the request header and is never logged or echoed.
+ */
+import { MnemomApiError } from "./api.js";
+export const IDENTITY_ROUTE_PATH = "/mnemom/agent/identity";
+/**
+ * The gateway answered 404: the identity route is not deployed on this cell. A subscription
+ * launch can't confirm its agent is claimed without it, so the launcher refuses.
+ */
+export class IdentityRouteMissingError extends Error {
+    gatewayUrl;
+    constructor(gatewayUrl) {
+        super(`this gateway (${gatewayUrl}) can't tell which agent a subscription login runs as yet ` +
+            `(POST ${IDENTITY_ROUTE_PATH} is not deployed there)`);
+        this.gatewayUrl = gatewayUrl;
+        this.name = "IdentityRouteMissingError";
+    }
+}
+/**
+ * The mnm- id the gateway serves for (Mnemom key, name). Its response also carries claimed /
+ * org_id / resolved_by / created; the launcher reads the claim state from the api instead, so
+ * only the id is used here.
+ */
+export async function resolveServedIdentity(gatewayUrl, agentName, mnemomKey, opts = {}) {
+    const response = await fetch(`${gatewayUrl}${IDENTITY_ROUTE_PATH}`, {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            "x-mnemom-api-key": mnemomKey,
+            "x-mnemom-agent": agentName,
+        },
+        signal: opts.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined,
+    });
+    if (response.status === 404)
+        throw new IdentityRouteMissingError(gatewayUrl);
+    if (response.status === 401) {
+        throw new MnemomApiError(401, "the gateway rejected your Mnemom API key");
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new MnemomApiError(response.status, `Gateway returned ${response.status}: ${text.slice(0, 300)}`);
+    }
+    const body = (await response.json().catch(() => null));
+    const agentId = body?.agent_id;
+    if (typeof agentId !== "string" || !/^mnm-/.test(agentId)) {
+        throw new Error(`Gateway returned no mnm- agent id from ${IDENTITY_ROUTE_PATH}.`);
+    }
+    return agentId;
+}

package/dist/lib/login-detect.d.ts

@@ -8,8 +8,8 @@
  *   - Claude subscription, Pro / Max (individual) → not supported (Team/Enterprise only).
  *   - Anthropic Console login (`/login` → Console account) → `auth = console` (supported): the
  *     API key Claude Code created is read from its keychain (lib/console-key.ts). A
- *     `claude auth login --console` profile creates no key → not supported yet.
- *   - Third-party provider (Bedrock / Vertex / Foundry) → not supported yet (no gateway door).
+ *     `claude auth login --console` profile creates no key → not supported.
+ *   - Third-party provider (Bedrock / Vertex / Foundry) → not supported (no gateway door).
  * An Anthropic API key always works (`auth = api-key`, the default).
  *
  * The signals are Claude Code's own client-side state (~/.claude.json `oauthAccount`, the

package/dist/lib/login-detect.js

@@ -8,8 +8,8 @@
  *   - Claude subscription, Pro / Max (individual) → not supported (Team/Enterprise only).
  *   - Anthropic Console login (`/login` → Console account) → `auth = console` (supported): the
  *     API key Claude Code created is read from its keychain (lib/console-key.ts). A
- *     `claude auth login --console` profile creates no key → not supported yet.
- *   - Third-party provider (Bedrock / Vertex / Foundry) → not supported yet (no gateway door).
+ *     `claude auth login --console` profile creates no key → not supported.
+ *   - Third-party provider (Bedrock / Vertex / Foundry) → not supported (no gateway door).
  * An Anthropic API key always works (`auth = api-key`, the default).
  *
  * The signals are Claude Code's own client-side state (~/.claude.json `oauthAccount`, the
@@ -63,9 +63,9 @@ export function unsupportedReason(login) {
         case "individual":
             return `your Claude ${login.plan} plan is a personal plan — Mnemom supports subscription login on Team and Enterprise plans only`;
         case "console":
-            return "your Anthropic Console login has no API key Claude Code created with /login (a `claude auth login --console` profile is not supported yet)";
+            return "your Anthropic Console login has no API key from Claude Code's /login (Mnemom uses the key /login creates)";
         case "third-party":
-            return `${PROVIDER_NAMES[login.provider]} is not supported yet`;
+            return `Claude Code is set to use ${PROVIDER_NAMES[login.provider]}, and Mnemom supports Anthropic sign-in only (an Anthropic API key, an Anthropic Console login, or a Claude Team or Enterprise plan)`;
     }
 }
 export const MENU_SUBSCRIPTION = "Claude subscription — Team or Enterprise (your claude.ai login)";

package/dist/lib/served-agent-cache.d.ts

@@ -5,6 +5,10 @@
  * once a launch has asked, later launches reuse it instead of paying for another probe
  * completion. Entries are keyed by a one-way fingerprint and never hold the key itself (nor the
  * sha256(key|name) claim proof). `--setup` always re-asks and overwrites.
+ *
+ * A second file records the agent this machine last CONFIRMED claimed for the same fingerprint.
+ * It is what a launch falls back to when Mnemom can't be reached to confirm the claim (an
+ * outage degrades to the last confirmed agent, never to an unclaimed one).
  */
 /**
  * A slow KDF (scrypt), not a fast hash: the fingerprint is derived from a credential and lands on
@@ -16,3 +20,7 @@ export declare function servedFingerprint(anthropicKey: string, slug: string, ga
 export declare function readServedAgent(dir: string, fingerprint: string): string | null;
 /** Best effort: a failed write only means the next launch asks again. */
 export declare function writeServedAgent(dir: string, fingerprint: string, agentId: string): void;
+/** The agent last confirmed claimed for this fingerprint, or null. */
+export declare function readConfirmedAgent(dir: string, fingerprint: string): string | null;
+/** Best effort: a failed write only means an outage can't fall back to this agent. */
+export declare function writeConfirmedAgent(dir: string, fingerprint: string, agentId: string): void;

package/dist/lib/served-agent-cache.js

@@ -5,11 +5,16 @@
  * once a launch has asked, later launches reuse it instead of paying for another probe
  * completion. Entries are keyed by a one-way fingerprint and never hold the key itself (nor the
  * sha256(key|name) claim proof). `--setup` always re-asks and overwrites.
+ *
+ * A second file records the agent this machine last CONFIRMED claimed for the same fingerprint.
+ * It is what a launch falls back to when Mnemom can't be reached to confirm the claim (an
+ * outage degrades to the last confirmed agent, never to an unclaimed one).
  */
 import { scryptSync } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 const FILE = "served-agents.json";
+const CONFIRMED_FILE = "confirmed-agents.json";
 /**
  * A slow KDF (scrypt), not a fast hash: the fingerprint is derived from a credential and lands on
  * disk, so recovering the key from it must cost what guessing a password would. Name and
@@ -18,9 +23,9 @@ const FILE = "served-agents.json";
 export function servedFingerprint(anthropicKey, slug, gateway) {
     return scryptSync(anthropicKey, `mnemom-served-agent-v1\n${slug}\n${gateway}`, 32).toString("hex");
 }
-function readAll(dir) {
+function readAll(dir, file = FILE) {
     try {
-        const parsed = JSON.parse(fs.readFileSync(path.join(dir, FILE), "utf8"));
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, file), "utf8"));
         return parsed && typeof parsed === "object" && !Array.isArray(parsed)
             ? parsed
             : {};
@@ -31,18 +36,30 @@ function readAll(dir) {
 }
 /** The cached served id, or null (missing, unreadable, or not an mnm- id). */
 export function readServedAgent(dir, fingerprint) {
-    const id = readAll(dir)[fingerprint];
-    return typeof id === "string" && /^mnm-/.test(id) ? id : null;
+    return readId(dir, FILE, fingerprint);
 }
 /** Best effort: a failed write only means the next launch asks again. */
 export function writeServedAgent(dir, fingerprint, agentId) {
+    writeId(dir, FILE, fingerprint, agentId);
+}
+/** The agent last confirmed claimed for this fingerprint, or null. */
+export function readConfirmedAgent(dir, fingerprint) {
+    return readId(dir, CONFIRMED_FILE, fingerprint);
+}
+/** Best effort: a failed write only means an outage can't fall back to this agent. */
+export function writeConfirmedAgent(dir, fingerprint, agentId) {
+    writeId(dir, CONFIRMED_FILE, fingerprint, agentId);
+}
+function readId(dir, file, fingerprint) {
+    const id = readAll(dir, file)[fingerprint];
+    return typeof id === "string" && /^mnm-/.test(id) ? id : null;
+}
+function writeId(dir, file, fingerprint, agentId) {
     try {
         fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-        const tmp = path.join(dir, `${FILE}.${process.pid}.tmp`);
-        fs.writeFileSync(tmp, JSON.stringify({ ...readAll(dir), [fingerprint]: agentId }, null, 2), {
-            mode: 0o600,
-        });
-        fs.renameSync(tmp, path.join(dir, FILE));
+        const tmp = path.join(dir, `${file}.${process.pid}.tmp`);
+        fs.writeFileSync(tmp, JSON.stringify({ ...readAll(dir, file), [fingerprint]: agentId }, null, 2), { mode: 0o600 });
+        fs.renameSync(tmp, path.join(dir, file));
     }
     catch {
         /* best effort */

package/dist/lib/try-me.d.ts

@@ -162,6 +162,24 @@ export interface BirthResult {
 export declare function birthAgent(manifest: BriefingManifest, name: string, opts?: {
     fetchImpl?: typeof fetch;
 }): Promise<BirthResult>;
+/** A server refusal, as the CLI's error types carry it. */
+export interface ServerRefusal {
+    status?: number;
+    code?: string;
+    message?: string;
+    details?: unknown;
+}
+/**
+ * Where to recharge: the server's `details.top_up_url` (absolute, or a path on
+ * the website), else the website's billing page.
+ */
+export declare function rechargeUrl(details: unknown, websiteBase?: string): string;
+/**
+ * The human message for a refusal that means the org is out of µ (or has no
+ * billing account): what happened, where to recharge, and how to resume.
+ * Undefined for any other refusal.
+ */
+export declare function describeOutOfMu(refusal: ServerRefusal, websiteBase?: string): string | undefined;
 /** The slice of the public agent projection the claim poll reads. */
 export interface PublicAgentStatus {
     id?: string;

package/dist/lib/try-me.js

@@ -21,8 +21,8 @@
  * consumes and tolerate everything else (`[key: string]: unknown`) so a manifest
  * bump that adds fields never breaks the CLI.
  */
-import { MnemomApiError, readApiError } from "./api.js";
-import { getApiUrl } from "./config.js";
+import { MnemomApiError, normalizeApiError, readApiError } from "./api.js";
+import { getApiUrl, getWebsiteUrl } from "./config.js";
 // ── resolve (zero-auth; the token IS the credential) ─────────────────────────
 const TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
 /** True iff `token` is shaped like a try-me token (tryme_… / a bare slug). */
@@ -212,7 +212,28 @@ export async function birthAgent(manifest, name, opts = {}) {
     const agentId = response.headers.get(manifest.gateway.agent_header.toLowerCase());
     if (!response.ok && !agentId) {
         const text = await response.text().catch(() => "");
-        throw new MnemomApiError(response.status, `Birth call failed (${response.status}) and no agent id was minted: ${text.slice(0, 300)}`);
+        let raw;
+        try {
+            raw = JSON.parse(text);
+        }
+        catch {
+            raw = null;
+        }
+        const parsed = normalizeApiError(raw);
+        const outOfMu = describeOutOfMu({
+            status: response.status,
+            code: parsed.code,
+            message: parsed.message,
+            details: parsed.details,
+        });
+        if (outOfMu) {
+            throw new MnemomApiError(response.status, outOfMu, {
+                code: parsed.code,
+                details: parsed.details,
+            });
+        }
+        throw new MnemomApiError(response.status, `Birth call failed (${response.status}) and no agent id was minted: ` +
+            (parsed.message ?? text.slice(0, 300)), { code: parsed.code, details: parsed.details });
     }
     if (!agentId || !/^mnm-/.test(agentId)) {
         throw new Error(`Birth succeeded (${response.status}) but the gateway returned no mnm- agent id on the ` +
@@ -220,6 +241,52 @@ export async function birthAgent(manifest, name, opts = {}) {
     }
     return { agentId, status: response.status };
 }
+/**
+ * Error codes that mean "Dojo play needs µ": the gateway's 402 `billing_error`
+ * (balance_depleted / dojo_billing_account_required) and mnemom-api's Dojo and
+ * card-publish balance refusals.
+ */
+const OUT_OF_MU_CODES = new Set([
+    "billing_error",
+    "balance_depleted",
+    "balance_required",
+    "dojo_balance_depleted",
+    "dojo_billing_unconfigured",
+]);
+/**
+ * Where to recharge: the server's `details.top_up_url` (absolute, or a path on
+ * the website), else the website's billing page.
+ */
+export function rechargeUrl(details, websiteBase = getWebsiteUrl()) {
+    const base = websiteBase.replace(/\/$/, "");
+    const fromServer = details && typeof details === "object"
+        ? details.top_up_url
+        : undefined;
+    if (typeof fromServer === "string") {
+        if (/^https?:\/\//.test(fromServer))
+            return fromServer;
+        if (fromServer.startsWith("/"))
+            return `${base}${fromServer}`;
+    }
+    return `${base}/settings/billing`;
+}
+/**
+ * The human message for a refusal that means the org is out of µ (or has no
+ * billing account): what happened, where to recharge, and how to resume.
+ * Undefined for any other refusal.
+ */
+export function describeOutOfMu(refusal, websiteBase = getWebsiteUrl()) {
+    const isOutOfMu = refusal.status === 402 || (refusal.code !== undefined && OUT_OF_MU_CODES.has(refusal.code));
+    if (!isOutOfMu)
+        return undefined;
+    const url = rechargeUrl(refusal.details, websiteBase);
+    const said = refusal.message?.trim();
+    const lead = said || "Your organization's µ balance is used up.";
+    const withUrl = lead.includes(url) ? lead : `${lead} Recharge at ${url}.`;
+    const headline = /^out of µ/i.test(withUrl) ? withUrl : `Out of µ — ${withUrl}`;
+    return (`${headline} Dojo play is charged to your organization's µ balance; ` +
+        "once it is recharged, re-run this command to keep going.");
+}
 /**
  * Read the PUBLIC (no-auth) agent projection used to detect the human's claim.
  * Never throws — a transient 404/5xx (the agent not yet queryable, or a blip)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.9",
+  "version": "0.17.11-next.0",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {