@mnemom/mnemom 0.17.25 → 0.17.27

package/dist/index.js

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

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

@@ -18,11 +18,29 @@ export declare class IdentityRouteMissingError extends Error {
     readonly gatewayUrl: string;
     constructor(gatewayUrl: string);
 }
+/** The gateway's answer: the served id, and how it resolved it. */
+export interface ServedIdentity {
+    agentId: string;
+    /**
+     * `pin` (the `x-mnemom-agent-id` pin was honoured), `principal` (the key owner's claimed agent
+     * of that name), `hash` (hash(key, name), birthed if absent), or null when an older gateway
+     * did not say. A pinned launch accepts only `pin`: an older gateway ignores the header and
+     * answers by name instead.
+     */
+    resolvedBy: string | null;
+}
 /**
- * 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.
+ * The mnm- id the gateway serves for (Mnemom key, name[, pin]). Its response also carries
+ * claimed / org_id / created; the launcher reads the claim state from the api instead. A non-2xx
+ * answer throws a MnemomApiError carrying the gateway's error code (agent_pin_forbidden,
+ * agent_pin_mismatch, agent_name_ambiguous, mnemom_api_key_required, …) so the caller can say
+ * exactly what to fix.
  */
+export declare function resolveServedIdentityDetail(gatewayUrl: string, agentName: string, mnemomKey: string, opts?: {
+    timeoutMs?: number;
+    pin?: string;
+}): Promise<ServedIdentity>;
+/** {@link resolveServedIdentityDetail}, the id only (an unpinned launch). */
 export declare function resolveServedIdentity(gatewayUrl: string, agentName: string, mnemomKey: string, opts?: {
     timeoutMs?: number;
 }): Promise<string>;

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

@@ -24,34 +24,61 @@ export class IdentityRouteMissingError extends Error {
         this.name = "IdentityRouteMissingError";
     }
 }
+/** `{error:{code,message}}` (the gateway's envelope) → its code; anything else → undefined. */
+function errorCode(text) {
+    try {
+        const body = JSON.parse(text);
+        const code = body?.error?.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
- * 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.
+ * The mnm- id the gateway serves for (Mnemom key, name[, pin]). Its response also carries
+ * claimed / org_id / created; the launcher reads the claim state from the api instead. A non-2xx
+ * answer throws a MnemomApiError carrying the gateway's error code (agent_pin_forbidden,
+ * agent_pin_mismatch, agent_name_ambiguous, mnemom_api_key_required, …) so the caller can say
+ * exactly what to fix.
  */
-export async function resolveServedIdentity(gatewayUrl, agentName, mnemomKey, opts = {}) {
+export async function resolveServedIdentityDetail(gatewayUrl, agentName, mnemomKey, opts = {}) {
+    const headers = {
+        Accept: "application/json",
+        "x-mnemom-api-key": mnemomKey,
+        "x-mnemom-agent": agentName,
+    };
+    // AGENT_ID_HEADER (lib/agent.ts), spelled out so this module imports nothing from the launcher.
+    if (opts.pin)
+        headers["x-mnemom-agent-id"] = opts.pin;
     const response = await fetch(`${gatewayUrl}${IDENTITY_ROUTE_PATH}`, {
         method: "POST",
-        headers: {
-            Accept: "application/json",
-            "x-mnemom-api-key": mnemomKey,
-            "x-mnemom-agent": agentName,
-        },
+        headers,
         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 code = errorCode(text);
+        if (response.status === 401 && code !== "mnemom_api_key_required") {
+            throw new MnemomApiError(401, "the gateway rejected your Mnemom API key", { code });
+        }
+        throw new MnemomApiError(response.status, `Gateway returned ${response.status}: ${text.slice(0, 300)}`, { code });
     }
     const body = (await response.json().catch(() => null));
     const agentId = body?.agent_id;
-    if (typeof agentId !== "string" || !/^mnm-/.test(agentId)) {
+    // Only `mnm-` + [A-Za-z0-9-]: the id is echoed into request headers (x-mnemom-agent-id), the
+    // sessions ledger and a printed resume hint, so nothing else from the gateway is trusted there.
+    if (typeof agentId !== "string" || !/^mnm-[A-Za-z0-9-]+$/.test(agentId)) {
         throw new Error(`Gateway returned no mnm- agent id from ${IDENTITY_ROUTE_PATH}.`);
     }
-    return agentId;
+    return {
+        agentId,
+        resolvedBy: typeof body?.resolved_by === "string" ? body.resolved_by : null,
+    };
+}
+/** {@link resolveServedIdentityDetail}, the id only (an unpinned launch). */
+export async function resolveServedIdentity(gatewayUrl, agentName, mnemomKey, opts = {}) {
+    return (await resolveServedIdentityDetail(gatewayUrl, agentName, mnemomKey, opts)).agentId;
 }

package/dist/lib/agent-ledger.d.ts

@@ -49,6 +49,11 @@ export interface SessionRecord {
     agent_slug: string;
     /** The agent record id when it resolved at launch, else null. */
     agent_id: string | null;
+    /**
+     * true when the launch PINNED `agent_id` (`--agent mnm-<uuid>` / launcher.toml `agent_id`), so
+     * a resume pins it again. Absent on an unpinned launch (and on every row written before pins).
+     */
+    agent_pinned?: true;
     org_id: string;
     org_label: string;
     gateway_host: string;

package/dist/lib/agent.d.ts

@@ -102,15 +102,19 @@ export declare function resolveGatewayHost(env?: NodeJS.ProcessEnv, cellGateway?
 /** Same scheme+host+port. An unparseable URL never matches. */
 export declare function sameOrigin(a: string, b: string): boolean;
 /**
- * A launch must use ONE cell: the Anthropic `door` its traffic goes to must be the
- * gateway of the cell the CLI signs in, resolves the agent and reads sessions on
- * (`cellGateway`, paired with `apiUrl`). A mixed launch records one cell's agent
- * and runs as another cell's, so `sessions`/`show` never find its goal state.
- * Returns the refusal message, or null. A loopback door is a local dev gateway and
- * is exempt.
+ * A launch must use ONE cell: the Anthropic `door` its traffic goes to, and the `gateway`
+ * host (`resolveGatewayHost`) the launcher sends the stored Mnemom key to (the identity
+ * route, setup's birth), must both be the gateway of the cell the CLI signs in, resolves
+ * the agent and reads sessions on (`cellGateway`, paired with `apiUrl`). A mixed launch
+ * records one cell's agent and runs as another cell's, so `sessions`/`show` never find its
+ * goal state. `MNEMOM_AGENT_ANTHROPIC_GATEWAY` sets the door apart from the gateway host,
+ * so checking the door alone leaves the key's destination unchecked. Returns the refusal
+ * message for the first offender, or null. A loopback host is a local dev gateway and is
+ * exempt.
  */
 export declare function singleCellError(opts: {
     door: string;
+    gateway: string;
     apiUrl: string;
     cellGateway: string;
 }): string | null;
@@ -131,9 +135,57 @@ export declare function isProdGateway(env?: NodeJS.ProcessEnv): boolean;
  * than `resolveGatewayHost` directly, because `MNEMOM_AGENT_ANTHROPIC_GATEWAY` can override the
  * door to a DIFFERENT host than `MNEMOM_AGENT_GATEWAY`/the default (e.g. a test cell) — reading
  * `resolveGatewayHost` here would silently send handoff calls to prod (or vice versa) while the
- * session's model traffic went elsewhere (MNE-7564 review).
+ * session's model traffic went elsewhere (MNE-7564 review). `singleCellError` now refuses a launch
+ * whose door and gateway host sit on different cells, but a loopback override is exempt from that
+ * check, so the door stays the source of truth here.
  */
 export declare function resolveHandoffGatewayHost(door: string): string;
+/**
+ * The explicit agent pin header (`x-mnemom-agent-id: mnm-<uuid>`). The gateway honours it only
+ * with a verified Mnemom key, serves exactly that agent (the caller's own, claimed, live one) and
+ * never falls back to a name or births an agent; otherwise it refuses (400 agent_pin_mismatch,
+ * 403 agent_pin_forbidden, 401 mnemom_api_key_required).
+ */
+export declare const AGENT_ID_HEADER = "x-mnemom-agent-id";
+/** A full Mnemom agent id: `mnm-` + a lowercase UUID. */
+export declare const AGENT_ID_RE: RegExp;
+/** What an `--agent` / launcher.toml `agent` / `agent_id` value names. */
+export type AgentRef = {
+    kind: "id";
+    id: string;
+} | {
+    kind: "name";
+    name: string;
+}
+/** Starts with `mnm-` but is not a full id (a truncated/garbled paste). */
+ | {
+    kind: "malformed-id";
+    raw: string;
+};
+/**
+ * Classify an agent reference. A full `mnm-<uuid>` (any case — ids are lowercase on the wire, so
+ * it is lowercased) is an ID: the launch pins that exact agent. Anything else starting with
+ * `mnm-` is a MALFORMED id and refused by the caller: treating it as a name would make the
+ * gateway birth a brand-new agent named after the id (the 2026-10-08 restart-resume strays). Any
+ * other value is a NAME.
+ */
+export declare function parseAgentRef(raw: string): AgentRef;
+/**
+ * Which agent a launch asks for, from the three places it can be named. `--agent` (flag) wins
+ * outright — an id there pins, a name there launches by name even when launcher.toml pins;
+ * otherwise launcher.toml `agent_id` pins, and wins over launcher.toml `agent`. Returns the
+ * `--agent`-shaped value (`agent`) and the config pin (`agentId`) for AgentOptions.
+ */
+export declare function selectLaunchAgent(sources: {
+    flag?: string;
+    configAgent?: string;
+    configAgentId?: string;
+}): {
+    agent?: string;
+    agentId?: string;
+};
+/** The refusal for a `mnm-…` value that is not a full agent id. */
+export declare function malformedAgentIdMessage(raw: string, source: string): string;
 /**
  * Sanitise a header value into a safe wire token: lowercase, alphanumerics and
  * single hyphens only, no leading/trailing hyphen. Returns "" when nothing
@@ -597,9 +649,14 @@ export declare function resolveRemoteControlShape(args: {
 export declare function buildCustomHeaders(opts: {
     /** Absent on a subscription-login launch: Claude Code then sends its own claude.ai login. */
     anthropicKey?: string;
-    /** The governed-identity anchor on a subscription-login launch (lib/subscription-login.ts). */
+    /**
+     * The Mnemom key: the governed-identity anchor on a subscription-login launch, and the
+     * principal an api-key launch proves when one is stored (lib/subscription-login.ts).
+     */
     mnemomKey?: string;
     agent: string;
+    /** The pinned agent id (`--agent mnm-<uuid>` / launcher.toml `agent_id`), sent as AGENT_ID_HEADER. */
+    agentId?: string;
     conversationId: string;
     contractB64?: string;
     /** `buildGoalModeHeader` output for an `--implicit` launch. */
@@ -769,6 +826,14 @@ export declare const HANDOFF_MCP_SERVER_NAME = "mnemom-handoff";
  * it the same way it inherits `ANTHROPIC_CUSTOM_HEADERS` under the terminal shape.
  */
 export declare const HANDOFF_RC_KEY_ENV_NAME = "MNEMOM_HANDOFF_KEY";
+/**
+ * The Remote Control counterpart for the Mnemom key: under RC the key rides only the proxy's
+ * stdin, so when the handoff tool is registered on a launch that has one, `spawnRcCli` sets this
+ * dedicated, non-ANTHROPIC var (same reasoning as HANDOFF_RC_KEY_ENV_NAME). The terminal shape
+ * needs none — the server reads the `x-mnemom-api-key:` line of its inherited
+ * `ANTHROPIC_CUSTOM_HEADERS`.
+ */
+export declare const HANDOFF_RC_MNEMOM_KEY_ENV_NAME = "MNEMOM_HANDOFF_MNEMOM_KEY";
 /**
  * How the `handoff` MCP server (cli/src/mcp/handoff-server.mjs) recovers the Anthropic key
  * WITHOUT it ever being written into the `--mcp-config` file on disk: `envName` is the NAME of a
@@ -801,6 +866,8 @@ export interface HandoffMcpParams {
     gatewayHost: string;
     anthropicKeySource: HandoffAnthropicKeySource;
     agent: string;
+    /** The pinned agent id, when the launch pins one — the handoff call carries the same pin. */
+    agentId?: string;
     conversationId: string;
     /** `buildSessionConfigB64` output — forwarded so the route resolves the SAME per-session flag. */
     sessionConfigB64?: string;

package/dist/lib/agent.js

@@ -55,27 +55,39 @@ export function sameOrigin(a, b) {
     }
 }
 /**
- * A launch must use ONE cell: the Anthropic `door` its traffic goes to must be the
- * gateway of the cell the CLI signs in, resolves the agent and reads sessions on
- * (`cellGateway`, paired with `apiUrl`). A mixed launch records one cell's agent
- * and runs as another cell's, so `sessions`/`show` never find its goal state.
- * Returns the refusal message, or null. A loopback door is a local dev gateway and
- * is exempt.
+ * A launch must use ONE cell: the Anthropic `door` its traffic goes to, and the `gateway`
+ * host (`resolveGatewayHost`) the launcher sends the stored Mnemom key to (the identity
+ * route, setup's birth), must both be the gateway of the cell the CLI signs in, resolves
+ * the agent and reads sessions on (`cellGateway`, paired with `apiUrl`). A mixed launch
+ * records one cell's agent and runs as another cell's, so `sessions`/`show` never find its
+ * goal state. `MNEMOM_AGENT_ANTHROPIC_GATEWAY` sets the door apart from the gateway host,
+ * so checking the door alone leaves the key's destination unchecked. Returns the refusal
+ * message for the first offender, or null. A loopback host is a local dev gateway and is
+ * exempt.
  */
 export function singleCellError(opts) {
-    let doorUrl;
+    for (const target of [opts.door, opts.gateway]) {
+        const error = cellMismatch(target, opts.apiUrl, opts.cellGateway);
+        if (error)
+            return error;
+    }
+    return null;
+}
+/** {@link singleCellError} for one gateway URL. */
+function cellMismatch(target, apiUrl, cellGateway) {
+    let targetUrl;
     try {
-        doorUrl = new URL(opts.door);
+        targetUrl = new URL(target);
     }
     catch {
-        return `mnemom agent: the gateway '${opts.door}' is not a valid URL.`;
+        return `mnemom agent: the gateway '${target}' is not a valid URL.`;
     }
-    if (LOOPBACK_HOSTS.has(doorUrl.hostname))
+    if (LOOPBACK_HOSTS.has(targetUrl.hostname))
         return null;
-    if (sameOrigin(opts.door, opts.cellGateway))
+    if (sameOrigin(target, cellGateway))
         return null;
-    return (`mnemom agent: the gateway ${doorUrl.origin} is on a different cell from the one this CLI uses ` +
-        `(API ${opts.apiUrl}, gateway ${opts.cellGateway}). A launch must use one cell. Point the whole ` +
+    return (`mnemom agent: the gateway ${targetUrl.origin} is on a different cell from the one this CLI uses ` +
+        `(API ${apiUrl}, gateway ${cellGateway}). A launch must use one cell. Point the whole ` +
         "CLI at that cell (MNEMOM_API_URL + MNEMOM_GATEWAY_URL, or MNEMOM_RING) and drop the gateway " +
         "override (--gateway, MNEMOM_AGENT_GATEWAY, MNEMOM_AGENT_ANTHROPIC_GATEWAY, or `gateway` in launcher.toml).");
 }
@@ -103,11 +115,57 @@ export function isProdGateway(env = process.env) {
  * than `resolveGatewayHost` directly, because `MNEMOM_AGENT_ANTHROPIC_GATEWAY` can override the
  * door to a DIFFERENT host than `MNEMOM_AGENT_GATEWAY`/the default (e.g. a test cell) — reading
  * `resolveGatewayHost` here would silently send handoff calls to prod (or vice versa) while the
- * session's model traffic went elsewhere (MNE-7564 review).
+ * session's model traffic went elsewhere (MNE-7564 review). `singleCellError` now refuses a launch
+ * whose door and gateway host sit on different cells, but a loopback override is exempt from that
+ * check, so the door stays the source of truth here.
  */
 export function resolveHandoffGatewayHost(door) {
     return new URL(door).origin;
 }
+/**
+ * The explicit agent pin header (`x-mnemom-agent-id: mnm-<uuid>`). The gateway honours it only
+ * with a verified Mnemom key, serves exactly that agent (the caller's own, claimed, live one) and
+ * never falls back to a name or births an agent; otherwise it refuses (400 agent_pin_mismatch,
+ * 403 agent_pin_forbidden, 401 mnemom_api_key_required).
+ */
+export const AGENT_ID_HEADER = "x-mnemom-agent-id";
+/** A full Mnemom agent id: `mnm-` + a lowercase UUID. */
+export const AGENT_ID_RE = /^mnm-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/**
+ * Classify an agent reference. A full `mnm-<uuid>` (any case — ids are lowercase on the wire, so
+ * it is lowercased) is an ID: the launch pins that exact agent. Anything else starting with
+ * `mnm-` is a MALFORMED id and refused by the caller: treating it as a name would make the
+ * gateway birth a brand-new agent named after the id (the 2026-10-08 restart-resume strays). Any
+ * other value is a NAME.
+ */
+export function parseAgentRef(raw) {
+    const v = raw.trim();
+    const lower = v.toLowerCase();
+    if (AGENT_ID_RE.test(lower))
+        return { kind: "id", id: lower };
+    if (lower.startsWith("mnm-"))
+        return { kind: "malformed-id", raw: v };
+    return { kind: "name", name: v };
+}
+/**
+ * Which agent a launch asks for, from the three places it can be named. `--agent` (flag) wins
+ * outright — an id there pins, a name there launches by name even when launcher.toml pins;
+ * otherwise launcher.toml `agent_id` pins, and wins over launcher.toml `agent`. Returns the
+ * `--agent`-shaped value (`agent`) and the config pin (`agentId`) for AgentOptions.
+ */
+export function selectLaunchAgent(sources) {
+    if (sources.flag?.trim())
+        return { agent: sources.flag };
+    if (sources.configAgentId?.trim())
+        return { agentId: sources.configAgentId };
+    return sources.configAgent?.trim() ? { agent: sources.configAgent } : {};
+}
+/** The refusal for a `mnm-…` value that is not a full agent id. */
+export function malformedAgentIdMessage(raw, source) {
+    return (`mnemom agent: ${source} '${raw}' looks like an agent id but isn't a full one (mnm-<uuid>). ` +
+        "Pass the complete id (see `mnemom agents`), or a plain agent name. " +
+        "It is not used as a name: that would create a new agent named after the id.");
+}
 /**
  * Sanitise a header value into a safe wire token: lowercase, alphanumerics and
  * single hyphens only, no leading/trailing hyphen. Returns "" when nothing
@@ -966,6 +1024,7 @@ export function buildCustomHeaders(opts) {
         ...(opts.anthropicKey ? [`x-api-key: ${opts.anthropicKey}`] : []),
         ...(opts.mnemomKey ? [`x-mnemom-api-key: ${opts.mnemomKey}`] : []),
         `x-mnemom-agent: ${opts.agent}`,
+        ...(opts.agentId ? [`${AGENT_ID_HEADER}: ${opts.agentId}`] : []),
         `x-mnemom-conversation-id: ${opts.conversationId}`,
     ];
     if (opts.contractB64)
@@ -1177,6 +1236,14 @@ export const HANDOFF_MCP_SERVER_NAME = "mnemom-handoff";
  * it the same way it inherits `ANTHROPIC_CUSTOM_HEADERS` under the terminal shape.
  */
 export const HANDOFF_RC_KEY_ENV_NAME = "MNEMOM_HANDOFF_KEY";
+/**
+ * The Remote Control counterpart for the Mnemom key: under RC the key rides only the proxy's
+ * stdin, so when the handoff tool is registered on a launch that has one, `spawnRcCli` sets this
+ * dedicated, non-ANTHROPIC var (same reasoning as HANDOFF_RC_KEY_ENV_NAME). The terminal shape
+ * needs none — the server reads the `x-mnemom-api-key:` line of its inherited
+ * `ANTHROPIC_CUSTOM_HEADERS`.
+ */
+export const HANDOFF_RC_MNEMOM_KEY_ENV_NAME = "MNEMOM_HANDOFF_MNEMOM_KEY";
 /** The `--mcp-config` document registering exactly the `handoff` tool. Pure — no I/O. */
 export function buildHandoffMcpConfig(p) {
     const env = {
@@ -1187,6 +1254,8 @@ export function buildHandoffMcpConfig(p) {
     };
     if (p.sessionConfigB64)
         env.MNEMOM_HANDOFF_SESSION_CONFIG = p.sessionConfigB64;
+    if (p.agentId)
+        env.MNEMOM_HANDOFF_AGENT_ID = p.agentId;
     return {
         mcpServers: {
             [HANDOFF_MCP_SERVER_NAME]: { command: p.nodeBin, args: [p.serverScript], env },

package/dist/lib/api.d.ts

@@ -31,6 +31,13 @@ export interface Agent {
     claimed_at?: string | null;
     name?: string | null;
     claimed?: boolean;
+    /** Owner (org-member) view: the org the agent lives in. */
+    org_id?: string | null;
+    /**
+     * `org_member` on the full record, `authenticated` / `anonymous` on the public projection
+     * (handleGetAgent). Absent on an older api.
+     */
+    caller?: string;
 }
 /**
  * GET /v1/integrity/:id — components/schemas/IntegrityScore:
@@ -247,6 +254,13 @@ export interface AgentListItem {
  * routing here avoids the false "Not authenticated" error (MNE-194 F10).
  */
 export declare function listAgents(): Promise<AgentListItem[]>;
+/**
+ * Every agent the caller OWNS, across all their orgs — `GET /v1/agents?scope=all`: rows whose
+ * `created_by` or `claimed_by` is the caller (MNE-191), newest first, up to 500. No org and no
+ * claim state on the rows (read those with {@link getAgent}); a tombstoned agent can still be
+ * listed and 404s there.
+ */
+export declare function listMyAgents(): Promise<AgentListItem[]>;
 export interface OrgListItem {
     org_id: string;
     name: string;
@@ -645,7 +659,9 @@ export declare function putProtectionCard(agentId: string, body: string, content
 /**
  * The per-layer view of an agent's card (ADR-053 `?include=sources`): the raw
  * card the agent layer itself carries, next to the composed card every layer
- * produced. We type the two rows we read; the platform/org/teams rows ride along.
+ * produced. The platform, org and team rows are optional here because an older
+ * api, or a test double, can omit them. Shape per mnemom-api
+ * `buildAgentSourcesEnvelope` (src/composition/agent-handlers.ts).
  */
 export interface CardSources {
     agent: {
@@ -656,6 +672,22 @@ export interface CardSources {
         card_json: Record<string, unknown> | null;
         available: boolean;
     };
+    platform?: {
+        card_json: Record<string, unknown> | null;
+        available: boolean;
+    };
+    org?: {
+        card_json: Record<string, unknown> | null;
+        available: boolean;
+        org_id?: string | null;
+        org_name?: string | null;
+    };
+    teams?: Array<{
+        team_id: string;
+        team_name?: string | null;
+        card_json: Record<string, unknown> | null;
+        available: boolean;
+    }>;
     [key: string]: unknown;
 }
 /**

package/dist/lib/api.js

@@ -211,6 +211,16 @@ export async function listAgents() {
     const data = await gFetch("/v1/agents?limit=100", {}, { fallback: "Failed to list agents" });
     return data.agents ?? [];
 }
+/**
+ * Every agent the caller OWNS, across all their orgs — `GET /v1/agents?scope=all`: rows whose
+ * `created_by` or `claimed_by` is the caller (MNE-191), newest first, up to 500. No org and no
+ * claim state on the rows (read those with {@link getAgent}); a tombstoned agent can still be
+ * listed and 404s there.
+ */
+export async function listMyAgents() {
+    const data = await gFetch("/v1/agents?scope=all&limit=500", {}, { fallback: "Failed to list your agents" });
+    return data.agents ?? [];
+}
 /**
  * GET /v1/orgs — list every org the user is a member of, including the
  * personal-org-of-one (per ADR-044 Option A, GitHub model). Personal sorts

package/dist/lib/experimental.js

@@ -50,7 +50,13 @@ export const EXPERIMENTAL_FEATURES = [
         since: "0.17.3",
         gates: {
             flags: ["--slack"],
-            configKeys: ["slack_channel", "slack_listen", "slack_allow"],
+            configKeys: [
+                "slack_channel",
+                "slack_listen",
+                "slack_allow",
+                "slack_aliases",
+                "slack_sticky_threads",
+            ],
             commands: ["mnemom agent slack"],
             env: [],
         },
@@ -156,6 +162,8 @@ export function experimentalIdForConfigKey(key, value) {
         case "slack_allow":
             return "slack";
         case "slack_listen":
+        case "slack_aliases":
+        case "slack_sticky_threads":
             return value === "true" ? "slack" : undefined;
         case "context_handoff":
             return value === "true" ? "context-handoff" : undefined;
@@ -229,7 +237,11 @@ export function migrateExperimental(deps) {
 }
 /** The feature a launcher.toml key belongs to at all (for marking `mnemom agent config list`). */
 export function configKeyFeature(key) {
-    if (key === "slack_channel" || key === "slack_listen" || key === "slack_allow")
+    if (key === "slack_channel" ||
+        key === "slack_listen" ||
+        key === "slack_allow" ||
+        key === "slack_aliases" ||
+        key === "slack_sticky_threads")
         return "slack";
     if (key === "context_handoff")
         return "context-handoff";

package/dist/lib/goal-api.d.ts

@@ -7,8 +7,8 @@
  *   POST https://<gateway_host>/mnemom/goal/intent/reset  {conversation_id, thread, statement?, requirements?}
  *
  * Auth is the SAME credential the launch used: `x-api-key` (the Anthropic key from
- * `resolveAnthropicKey`), `x-mnemom-agent: <record.agent_slug>`, and `x-mnemom-api-key` when the
- * launch had a Mnemom key. The gateway hashes them exactly as a proxied request and only LOOKS
+ * `resolveAnthropicKey`), `x-mnemom-agent: <record.agent_slug>`, `x-mnemom-api-key` when the
+ * launch had a Mnemom key, and `x-mnemom-agent-id: <record.agent_id>` when the launch pinned it. The gateway hashes them exactly as a proxied request and only LOOKS
  * UP the agent. Key material is never printed: errors carry the status, the gateway's error code
  * and its message, nothing else.
  *
@@ -24,7 +24,7 @@ export type GoalOp = "show" | "pin" | "reset";
 export declare const GOAL_THREAD_RE: RegExp;
 export declare function isValidGoalThread(thread: string): boolean;
 /** The ledger fields the control call needs. */
-export type GoalControlRecord = Pick<SessionRecord, "gateway_host" | "agent_slug" | "conversation_id">;
+export type GoalControlRecord = Pick<SessionRecord, "gateway_host" | "agent_slug" | "conversation_id"> & Partial<Pick<SessionRecord, "agent_id" | "agent_pinned">>;
 export interface GoalControlCreds {
     /** The Anthropic key the launch sent as `x-api-key`. */
     anthropicKey: string;

package/dist/lib/goal-api.js

@@ -7,8 +7,8 @@
  *   POST https://<gateway_host>/mnemom/goal/intent/reset  {conversation_id, thread, statement?, requirements?}
  *
  * Auth is the SAME credential the launch used: `x-api-key` (the Anthropic key from
- * `resolveAnthropicKey`), `x-mnemom-agent: <record.agent_slug>`, and `x-mnemom-api-key` when the
- * launch had a Mnemom key. The gateway hashes them exactly as a proxied request and only LOOKS
+ * `resolveAnthropicKey`), `x-mnemom-agent: <record.agent_slug>`, `x-mnemom-api-key` when the
+ * launch had a Mnemom key, and `x-mnemom-agent-id: <record.agent_id>` when the launch pinned it. The gateway hashes them exactly as a proxied request and only LOOKS
  * UP the agent. Key material is never printed: errors carry the status, the gateway's error code
  * and its message, nothing else.
  *
@@ -58,6 +58,9 @@ export function goalControlHeaders(record, creds) {
     };
     if (creds.mnemomKey)
         headers["x-mnemom-api-key"] = creds.mnemomKey;
+    // A pinned launch's control calls carry the same pin, so they reach the agent it ran as.
+    if (record.agent_pinned && record.agent_id)
+        headers["x-mnemom-agent-id"] = record.agent_id;
     return headers;
 }
 /** `{error:{code,message}}` (the gateway's envelope) → its parts; anything else → nulls. */

package/dist/lib/launcher-config.d.ts

@@ -27,6 +27,11 @@ export interface LauncherConfig {
     gateway?: string;
     model?: string;
     agent?: string;
+    /**
+     * The agent this machine's launches PIN (`x-mnemom-agent-id`): a full `mnm-<uuid>`. `--agent`
+     * on the command line wins over it; it wins over `agent`.
+     */
+    agentId?: string;
     effort?: string;
     cli?: string;
     launch?: LaunchShape;
@@ -43,6 +48,17 @@ export interface LauncherConfig {
     slackListen?: boolean;
     /** Slack member ids whose messages the router may deliver into a session. */
     slackAllow?: string[];
+    /**
+     * Router: honour `mnemom agent slack alias` handles (off when unset). Off means the
+     * router routes exactly as it did before aliases existed; registered aliases are kept
+     * but ignored.
+     */
+    slackAliases?: boolean;
+    /**
+     * Router: a thread a session was addressed in keeps routing replies to it (off when
+     * unset). Off means only threads a session posted in route replies, as before.
+     */
+    slackStickyThreads?: boolean;
     /**
      * Context-handoff default (EXPERIMENTAL, off when unset): `true` registers the `handoff`
      * MCP tool and sends `CONTEXT_HANDOFF_ENABLED: "true"` in the per-session config header for
@@ -86,6 +102,8 @@ export interface ConfigKeySpec {
     get(cfg: LauncherConfig): string | number | boolean | undefined;
     set(cfg: LauncherConfig, raw: string): void;
 }
+/** launcher.toml `agent_id`: a full `mnm-<uuid>` (any case; stored lowercase). */
+export declare function coerceAgentId(v: string): string;
 /** The full set of settable keys — drives get/set/unset/list and validation. */
 export declare const CONFIG_KEYS: ConfigKeySpec[];
 export declare function configKeySpec(key: string): ConfigKeySpec | undefined;