@mnemom/mnemom 0.17.3 → 0.17.4-next.1

package/dist/commands/agent-doctor.js

@@ -14,6 +14,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { anthropicKeySource, checkRcCapability, resolveCliBin } from "./agent.js";
+import { resolveAgentAuth } from "../lib/subscription-login.js";
 import { isProdGateway, resolveAnthropicDoor, resolveGatewayHost, singleCellError, } from "../lib/agent.js";
 import { getApiUrl, getGatewayUrl } from "../lib/config.js";
 import { LAUNCHER_CONFIG_PATH } from "../lib/launcher-config.js";
@@ -45,14 +46,26 @@ export async function agentDoctorCommand(options = {}) {
     catch (err) {
         add("miss", `coding-agent CLI: ${err instanceof Error ? err.message.split("\n")[0] : err}`, "install Claude Code, or pass --cli <name|/full/path> / set it with `mnemom agent config set cli <path>`");
     }
-    // ── Anthropic key ──
-    const keySrc = anthropicKeySource(env);
-    if (keySrc === "env")
-        add("ok", "Anthropic key: found in the environment");
-    else if (keySrc === "store")
-        add("ok", "Anthropic key: found in ~/.mnemom/launcher.json");
-    else
-        add("miss", "Anthropic key: none found", "export MNEMOM_AGENT_ANTHROPIC_KEY=sk-ant-… (or ANTHROPIC_API_KEY), or run `mnemom agent` once and accept the save prompt");
+    // ── auth: an Anthropic key, or the claude.ai subscription login (no key needed) ──
+    let auth = "api-key";
+    try {
+        auth = resolveAgentAuth(undefined, env);
+    }
+    catch (err) {
+        add("miss", `auth: ${err instanceof Error ? err.message : String(err)}`, "`mnemom agent config set auth api-key` (or subscription)");
+    }
+    if (auth === "subscription") {
+        add("ok", "auth: subscription — Claude Code uses your claude.ai login (Team/Enterprise plans only); no Anthropic key needed");
+    }
+    else {
+        const keySrc = anthropicKeySource(env);
+        if (keySrc === "env")
+            add("ok", "Anthropic key: found in the environment");
+        else if (keySrc === "store")
+            add("ok", "Anthropic key: found in ~/.mnemom/launcher.json");
+        else
+            add("miss", "Anthropic key: none found", "export MNEMOM_AGENT_ANTHROPIC_KEY=sk-ant-… (or ANTHROPIC_API_KEY), or run `mnemom agent` once and accept the save prompt");
+    }
     // ── one cell: the launch door must be the CLI's own cell ──
     const cellError = singleCellError({
         door: resolveAnthropicDoor(env),

package/dist/commands/agent.d.ts

@@ -25,6 +25,8 @@
  * line, or the proxy's stdin under RC). It is never logged, printed, or passed as
  * an argv value.
  */
+import { type MnemomKeyDeps } from "../lib/subscription-login.js";
+import { type SessionRecord } from "../lib/agent-ledger.js";
 import { type ExperimentalId } from "../lib/experimental.js";
 import { type ContextProfile, type LaunchShape, type SealedContractEnvelope } from "../lib/agent.js";
 export interface AgentOptions {
@@ -48,6 +50,8 @@ export interface AgentOptions {
     cli?: string;
     remoteControl?: boolean;
     server?: boolean;
+    /** `--auth api-key|subscription` (lib/subscription-login.ts); else MNEMOM_AGENT_AUTH / config. */
+    auth?: string;
     model?: string;
     effort?: string;
     trimMcp?: boolean;
@@ -100,6 +104,34 @@ export interface AgentOptions {
 }
 /** Entry point for `mnemom agent [scenario]`. Throws on fatal misconfig. */
 export declare function agentCommand(scenarioArg: string | undefined, options?: AgentOptions): Promise<void>;
+/** The Claude Code session id a passthrough `--resume <id>` / `-r <id>` / `--resume=<id>` names. */
+export declare function passthroughResumeId(passthrough: readonly string[]): string | null;
+/**
+ * The conversation id this launch runs under (IG5 #1, decision D1). The gateway keys the
+ * implicit goal by conversation id, so an implicit relaunch reuses the earlier one:
+ *   - `--conversation-id` → that id, no lookup;
+ *   - not implicit (a sealed contract, or alignment off) → a new id;
+ *   - only an earlier implicit launch with the same session name, org, agent and gateway host
+ *     is continued; any mismatch → a new id, no prompt;
+ *   - `-- --resume <cc-session-id>` → the matching row that pinned that Claude Code session
+ *     (else the newest matching row), reused without asking;
+ *   - no `--resume` → "Resume previous session <name>? [Y/n]", default Y; Y reuses that row's
+ *     conversation, n mints a new one. `--resume` is NOT added to Claude Code (the user often
+ *     resumes inside it with /resume). No TTY: Y.
+ * The ledger read is best-effort: a failure means a new id.
+ */
+export declare function resolveLaunchConversationId(input: {
+    session: string;
+    orgId: string;
+    agent: string;
+    gatewayHost: string;
+    explicit?: string;
+    implicit: boolean;
+    passthrough: readonly string[];
+    interactive: boolean;
+    records: () => SessionRecord[];
+    askYesNo: (question: string, defaultYes: boolean) => Promise<boolean>;
+}): Promise<string>;
 /**
  * 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
@@ -124,6 +156,8 @@ export declare function recordSessionLaunch(ctx: {
     /** The resolved context profile this launch runs under. */
     contextProfile: ContextProfile;
 }): Promise<void>;
+/** The real I/O behind a subscription launch's Mnemom key (lib/subscription-login.ts). */
+export declare function defaultMnemomKeyDeps(storePath?: string): MnemomKeyDeps;
 /**
  * Resolve the Anthropic key with NO 1Password dependency (built for external
  * customer adoption), in order:

package/dist/commands/agent.js

@@ -28,12 +28,13 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, renameSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { tmpdir, homedir } from "node:os";
+import { tmpdir, homedir, hostname } from "node:os";
 import { basename, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getApiUrl, getGatewayUrl, MNEMOM_DIR } from "../lib/config.js";
-import { getAgentByName } from "../lib/api.js";
-import { LEDGER_FILE, appendSessionRecord, resolveRetentionDays, toLedgerContract, } from "../lib/agent-ledger.js";
+import { createApiKey, getAgentByName } 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, toLedgerContract, } from "../lib/agent-ledger.js";
 import { loadCliConfig } from "../lib/cli-config.js";
 import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
 import { experimentalNotice } from "../lib/experimental.js";
@@ -41,7 +42,7 @@ import { fmt } from "../lib/format.js";
 import { askInput, askYesNo, isInteractive } from "../lib/prompt.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
 import { AgentIdentityMismatchError, defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.js";
-import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
+import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, sessionDisplayName, GATEWAY_HINT_HEADERS_ENV, 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";
 /** The CLI's own provider-key store (zero 1Password): ~/.mnemom/launcher.json, 0600. */
@@ -77,6 +78,9 @@ export async function agentCommand(scenarioArg, options = {}) {
     const env = process.env;
     let shape = resolveLaunchShape({ remoteControl: options.remoteControl, server: options.server }, env);
     const shapeExplicit = launchPreferenceExplicit({ remoteControl: options.remoteControl, server: options.server }, env);
+    // How Claude Code authenticates: an Anthropic key (default) or the user's claude.ai
+    // subscription login (Team/Enterprise; lib/subscription-login.ts).
+    const auth = resolveAgentAuth(options.auth, env);
     // ── governed identity ── (default: per-customer `agent-<handle>`, not a shared
     // "code-agent" — see defaultAgentSlug; provisioning claims exactly this slug.
     // `let` because a brand-new user who signs in during the pre-launch gate below
@@ -85,7 +89,6 @@ export async function agentCommand(scenarioArg, options = {}) {
     if (!agent) {
         throw new Error("mnemom agent: --agent sanitised to an empty string — pick a value with at least one letter or digit.");
     }
-    const conversationId = resolveConversationId(options.conversationId);
     // ── contract (built only if a contract flag was given; --goal then required) ──
     const envelope = assembleContract({
         goal: session.goal,
@@ -124,7 +127,12 @@ export async function agentCommand(scenarioArg, options = {}) {
         context: options.context,
         env,
     });
-    const contextHandoff = resolveContextHandoff({ contextHandoff: options.contextHandoff, env });
+    let contextHandoff = resolveContextHandoff({ contextHandoff: options.contextHandoff, env });
+    if (contextHandoff && auth === "subscription") {
+        // The handoff tool authenticates with the Anthropic key a subscription launch does not have.
+        say("mnemom agent: context handoff is not available with subscription login yet — launching without it.");
+        contextHandoff = false;
+    }
     const experimental = options.experimental ?? [];
     const sessionConfig = buildSessionConfig({ profile: contextProfile, contextHandoff });
     const sessionConfigB64 = buildSessionConfigB64({
@@ -164,7 +172,8 @@ export async function agentCommand(scenarioArg, options = {}) {
             scenario,
             shape: previewShape,
             agent,
-            conversationId,
+            // The org is only known after sign-in, so a dry run never offers a resume (IG5 #1).
+            conversationId: resolveConversationId(options.conversationId),
             door,
             cellNote,
             envelope,
@@ -175,6 +184,9 @@ export async function agentCommand(scenarioArg, options = {}) {
             sessionConfig,
             experimental,
         });
+        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, terminal-only.");
+        }
         if (expNotice)
             say(expNotice);
         if (previewShape === "remote-control") {
@@ -193,10 +205,10 @@ export async function agentCommand(scenarioArg, options = {}) {
         cli = await promptForCliPath(options.cli, env, cliError);
     }
     // ── resolve the Anthropic key (zero 1Password; never logged) ──
-    const anthropicKey = await resolveAnthropicKey(env, {
-        allowPrompt: true,
-        keySource: options.keySource,
-    });
+    // Not on a subscription launch: Claude Code then sends its own claude.ai login instead.
+    const anthropicKey = auth === "api-key"
+        ? await resolveAnthropicKey(env, { allowPrompt: true, keySource: options.keySource })
+        : undefined;
     // ── account + µ-balance gate (no free tier) ─────────────────────────────────
     // mnemom agent runs governed and on µ, so before we seal a contract or launch we
     // (1) ensure a Mnemom session — offering the try-me-style sign-in / sign-up when
@@ -245,6 +257,14 @@ export async function agentCommand(scenarioArg, options = {}) {
         rcCapable: rc.ok,
         say,
     });
+    // Subscription login: terminal-only for now, and the governed identity anchors on a
+    // Mnemom API key (minted once and stored if there is none). Resolved after sign-in so
+    // minting can use the session.
+    let mnemomKey;
+    if (auth === "subscription") {
+        shape = subscriptionShape(shape, shapeExplicit, say);
+        mnemomKey = await resolveSubscriptionMnemomKey(defaultMnemomKeyDeps());
+    }
     // Now that a session exists, a defaulted slug uses the real login handle from
     // /v1/auth/me (the stored token has no email, so the pre-sign-in value was the
     // "agent-user" fallback). Only when the caller didn't name an agent. Under an
@@ -261,7 +281,12 @@ export async function agentCommand(scenarioArg, options = {}) {
     // 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.
-    if (options.setup !== false) {
+    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) {
         try {
             await ensureGovernedAgent({
                 slug: agent,
@@ -280,6 +305,22 @@ export async function agentCommand(scenarioArg, options = {}) {
             say(fmt.warn(`mnemom agent: agent setup did not complete (${msg}) — launching with the unclaimed identity.`));
         }
     }
+    // ── 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
+    // match the earlier launch.
+    const conversationId = await resolveLaunchConversationId({
+        session: scenario,
+        orgId: account.orgId,
+        agent,
+        gatewayHost,
+        explicit: options.conversationId,
+        implicit: goalAlignmentMode(envelope, goalMode) === "implicit",
+        passthrough: options.passthrough ?? [],
+        interactive: isInteractive(),
+        records: () => readSessionRecords({ dir: MNEMOM_DIR }),
+        askYesNo: (q, d) => askYesNo(q, d),
+    });
     // ── local session ledger (~/.mnemom/sessions.jsonl) ── one line per real
     // launch so `mnemom agent sessions` / `show` can find this conversation later.
     // Written after provisioning so a freshly claimed agent's id resolves. Holds
@@ -343,11 +384,13 @@ export async function agentCommand(scenarioArg, options = {}) {
             say(fmt.warn(`mnemom agent: context handoff could not be registered (${err instanceof Error ? err.message : String(err)}) — launching without the handoff tool.`));
         }
     }
-    if (shape === "terminal") {
+    // A subscription launch (no Anthropic key) is always terminal — see subscriptionShape.
+    if (shape === "terminal" || !anthropicKey) {
         launchTerminal({
             cli,
             door,
             anthropicKey,
+            mnemomKey,
             agent,
             scenario,
             conversationId,
@@ -382,6 +425,63 @@ export async function agentCommand(scenarioArg, options = {}) {
 // ───────────────────────────────────────────────────────────────────────────
 // Session ledger (thin driver over lib/agent-ledger.ts)
 // ───────────────────────────────────────────────────────────────────────────
+/** The Claude Code session id a passthrough `--resume <id>` / `-r <id>` / `--resume=<id>` names. */
+export function passthroughResumeId(passthrough) {
+    for (let i = 0; i < passthrough.length; i++) {
+        const a = passthrough[i];
+        if (a === "--resume" || a === "-r") {
+            const next = passthrough[i + 1];
+            return next !== undefined && !next.startsWith("-") && next.trim() !== "" ? next.trim() : null;
+        }
+        if (a.startsWith("--resume="))
+            return a.slice("--resume=".length).trim() || null;
+    }
+    return null;
+}
+/**
+ * The conversation id this launch runs under (IG5 #1, decision D1). The gateway keys the
+ * implicit goal by conversation id, so an implicit relaunch reuses the earlier one:
+ *   - `--conversation-id` → that id, no lookup;
+ *   - not implicit (a sealed contract, or alignment off) → a new id;
+ *   - only an earlier implicit launch with the same session name, org, agent and gateway host
+ *     is continued; any mismatch → a new id, no prompt;
+ *   - `-- --resume <cc-session-id>` → the matching row that pinned that Claude Code session
+ *     (else the newest matching row), reused without asking;
+ *   - no `--resume` → "Resume previous session <name>? [Y/n]", default Y; Y reuses that row's
+ *     conversation, n mints a new one. `--resume` is NOT added to Claude Code (the user often
+ *     resumes inside it with /resume). No TTY: Y.
+ * The ledger read is best-effort: a failure means a new id.
+ */
+export async function resolveLaunchConversationId(input) {
+    if ((input.explicit ?? "").trim())
+        return resolveConversationId(input.explicit);
+    if (!input.implicit)
+        return resolveConversationId(undefined);
+    let records;
+    try {
+        records = input.records();
+    }
+    catch {
+        return resolveConversationId(undefined);
+    }
+    const found = findResumeCandidate(records, {
+        session: input.session,
+        orgId: input.orgId,
+        agent: input.agent,
+        gatewayHost: input.gatewayHost,
+        resumeId: passthroughResumeId(input.passthrough),
+    });
+    if (!found)
+        return resolveConversationId(undefined);
+    const conv = found.record.conversation_id;
+    if (found.source === "session_name" && input.interactive) {
+        const yes = await input.askYesNo(`Resume previous session ${input.session}?`, true);
+        if (!yes)
+            return resolveConversationId(undefined);
+    }
+    say(`mnemom agent: continuing conversation ${conv} from the earlier '${found.record.session}' launch (${found.record.started_at}), so its goal carries over.`);
+    return resolveConversationId(conv);
+}
 /**
  * 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
@@ -425,6 +525,25 @@ export async function recordSessionLaunch(ctx) {
 // ───────────────────────────────────────────────────────────────────────────
 // Credential resolution (zero 1Password)
 // ───────────────────────────────────────────────────────────────────────────
+/** The real I/O behind a subscription launch's Mnemom key (lib/subscription-login.ts). */
+export function defaultMnemomKeyDeps(storePath = CODE_STORE) {
+    return {
+        env: process.env,
+        readStored: () => {
+            try {
+                const data = JSON.parse(readFileSync(storePath, "utf8"));
+                const v = data[MNEMOM_KEY_STORE_FIELD];
+                return typeof v === "string" ? stripCrlf(v) : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        mint: async () => (await createApiKey(`mnemom-agent ${hostname()}`, ["gateway"])).key,
+        store: (key) => mergeStore({ [MNEMOM_KEY_STORE_FIELD]: key }, storePath),
+        say,
+    };
+}
 /**
  * Resolve the Anthropic key with NO 1Password dependency (built for external
  * customer adoption), in order:
@@ -660,6 +779,7 @@ function launchTerminal(ctx) {
     warnAdapter(ctx.cli);
     const headers = buildCustomHeaders({
         anthropicKey: ctx.anthropicKey,
+        mnemomKey: ctx.mnemomKey,
         agent: ctx.agent,
         conversationId: ctx.conversationId,
         contractB64: ctx.envelope?.base64,
@@ -675,13 +795,23 @@ function launchTerminal(ctx) {
     // Claude Code logged in via claude.ai (OAuth) PREEMPTS ANTHROPIC_API_KEY, so
     // it is force-unset; the real key rides in ANTHROPIC_CUSTOM_HEADERS and
     // ANTHROPIC_AUTH_TOKEN is a fixed non-secret placeholder.
-    const childEnv = { ...process.env };
-    delete childEnv.ANTHROPIC_API_KEY;
-    childEnv.ANTHROPIC_BASE_URL = ctx.door;
-    childEnv.ANTHROPIC_AUTH_TOKEN = "mnemom-gateway";
-    childEnv.ANTHROPIC_CUSTOM_HEADERS = headers;
+    //
+    // A subscription launch (no Anthropic key) sets NO auth token: Claude Code then sends its
+    // own claude.ai login to the gateway (lib/subscription-login.ts).
+    let childEnv;
+    if (ctx.anthropicKey) {
+        childEnv = { ...process.env };
+        delete childEnv.ANTHROPIC_API_KEY;
+        childEnv.ANTHROPIC_BASE_URL = ctx.door;
+        childEnv.ANTHROPIC_AUTH_TOKEN = "mnemom-gateway";
+        childEnv.ANTHROPIC_CUSTOM_HEADERS = headers;
+    }
+    else {
+        childEnv = subscriptionChildEnv(process.env, ctx.door, headers);
+    }
     const sessionName = passthroughName(ctx.options.passthrough ?? []) ?? sessionDisplayName(ctx.agent, ctx.scenario);
     childEnv[SESSION_NAME_ENV] = sessionName;
+    childEnv[GATEWAY_HINT_HEADERS_ENV] = "1";
     if (ctx.options.slack)
         args.push(...slackChannelArgs(sessionName));
     if (ctx.contextHint) {

package/dist/index.js

@@ -142,6 +142,7 @@ const agentCmd = program
     .option("--gateway <url>", "Gateway host override — must be the same cell as the rest of the CLI (default: that cell's gateway; or MNEMOM_AGENT_GATEWAY)")
     .option("--remote-control", "Interactive Remote Control session in THIS terminal (behind a local proxy)")
     .option("--server", "Headless `claude remote-control` dispatcher (behind a local proxy)")
+    .option("--auth <mode>", "How Claude Code authenticates: api-key (default) | subscription (your Claude Team/Enterprise login; terminal-only)")
     .option("--model <alias|id>", "Model to launch (CLI alias or concrete id)")
     .addOption(new Option("--effort <level>", "Reasoning effort").choices([
     "low",
@@ -278,6 +279,7 @@ const agentCmd = program
             conversationId: opts.conversationId,
             cli: opts.cli,
             remoteControl: opts.remoteControl,
+            auth: opts.auth,
             server: opts.server,
             model: opts.model ?? cfg.model,
             effort: opts.effort ?? cfg.effort,

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

@@ -133,3 +133,30 @@ export declare function appendSessionRecord(input: SessionRecordInput, deps: Led
 export declare function readSessionRecords(deps: Pick<LedgerDeps, "dir">): SessionRecord[];
 /** One ledger line → a record, or null when it is not a v1 record object. */
 export declare function parseRecord(line: string): SessionRecord | null;
+/**
+ * Which earlier launch a new one continues (IG5 #1, decision D1). The gateway keys the implicit
+ * goal by conversation id, so a relaunch that mints a fresh id starts goal-less. A row
+ * qualifies only when it is an implicit-mode launch (a sealed contract is sealed on its own
+ * conversation and is never carried) with the same session name, org, agent and gateway host as
+ * this launch; an empty org never matches. `records` is file order (oldest first); the newest
+ * qualifying row wins.
+ *   - `resumeId` (the `--resume <cc-session-id>` passed through to Claude Code) → the qualifying
+ *     row that pinned that Claude Code session, else the newest qualifying row; `source:
+ *     "resume_flag"` — reused without asking.
+ *   - no `resumeId` → the newest qualifying row; `source: "session_name"` — the launcher asks
+ *     first.
+ *   - nothing qualifies → null (a new conversation id).
+ */
+export interface ResumeCandidate {
+    record: SessionRecord;
+    source: "resume_flag" | "session_name";
+    /** True when the row was found by its Claude Code session id (not by the name fallback). */
+    byCcSession: boolean;
+}
+export declare function findResumeCandidate(records: readonly SessionRecord[], want: {
+    session: string;
+    orgId: string;
+    agent: string;
+    gatewayHost: string;
+    resumeId?: string | null;
+}): ResumeCandidate | null;

package/dist/lib/agent-ledger.js

@@ -170,3 +170,30 @@ export function parseRecord(line) {
 function nonEmptyLines(text) {
     return text.split("\n").filter((l) => l.trim().length > 0);
 }
+export function findResumeCandidate(records, want) {
+    const implicitRows = records.filter((r) => r.goal_mode === "implicit" &&
+        typeof r.conversation_id === "string" &&
+        r.conversation_id &&
+        r.session === want.session &&
+        !!want.orgId &&
+        r.org_id === want.orgId &&
+        r.agent_slug === want.agent &&
+        r.gateway_host === want.gatewayHost);
+    const newest = (pred) => {
+        for (let i = implicitRows.length - 1; i >= 0; i--) {
+            const r = implicitRows[i];
+            if (pred(r))
+                return r;
+        }
+        return undefined;
+    };
+    const latest = newest(() => true);
+    const resumeId = want.resumeId?.trim();
+    if (resumeId) {
+        const byCc = newest((r) => r.cc_session_id === resumeId);
+        if (byCc)
+            return { record: byCc, source: "resume_flag", byCcSession: true };
+        return latest ? { record: latest, source: "resume_flag", byCcSession: false } : null;
+    }
+    return latest ? { record: latest, source: "session_name", byCcSession: false } : null;
+}

package/dist/lib/agent.d.ts

@@ -116,6 +116,15 @@ export declare function sanitizeAgentName(raw: string): string;
  * post`) can identify themselves by the same name the claude.ai session list shows.
  */
 export declare const SESSION_NAME_ENV = "MNEMOM_AGENT_SESSION_NAME";
+/**
+ * Claude Code's opt-in for its gateway hint headers (`x-claude-code-request-class`,
+ * `x-claude-code-agent-type`, `x-claude-code-prompt-id`). CC sends them to api.anthropic.com on
+ * its own, so a Remote Control launch (rc-proxy in front of api.anthropic.com) already carries
+ * them; with `ANTHROPIC_BASE_URL` pointing at the gateway door (the terminal shape) CC sends them
+ * only when this is "1". The gateway reads them to keep away summaries, titles, compaction and
+ * teammates off the main implicit goal.
+ */
+export declare const GATEWAY_HINT_HEADERS_ENV = "CLAUDE_CODE_GATEWAY_HINT_HEADERS";
 /** The session display name: "<agent>-<scenario>" (sanitised), else the agent slug. */
 export declare function sessionDisplayName(agent: string, scenario: string): string;
 /** A caller's own `--name <x>` in the passthrough args, if any (last one wins). */
@@ -283,7 +292,10 @@ export declare function resolveRemoteControlShape(args: {
  * callers must place it only in the child's env, never in a log line.
  */
 export declare function buildCustomHeaders(opts: {
-    anthropicKey: string;
+    /** 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). */
+    mnemomKey?: string;
     agent: string;
     conversationId: string;
     contractB64?: string;

package/dist/lib/agent.js

@@ -117,6 +117,15 @@ export function sanitizeAgentName(raw) {
  * post`) can identify themselves by the same name the claude.ai session list shows.
  */
 export const SESSION_NAME_ENV = "MNEMOM_AGENT_SESSION_NAME";
+/**
+ * Claude Code's opt-in for its gateway hint headers (`x-claude-code-request-class`,
+ * `x-claude-code-agent-type`, `x-claude-code-prompt-id`). CC sends them to api.anthropic.com on
+ * its own, so a Remote Control launch (rc-proxy in front of api.anthropic.com) already carries
+ * them; with `ANTHROPIC_BASE_URL` pointing at the gateway door (the terminal shape) CC sends them
+ * only when this is "1". The gateway reads them to keep away summaries, titles, compaction and
+ * teammates off the main implicit goal.
+ */
+export const GATEWAY_HINT_HEADERS_ENV = "CLAUDE_CODE_GATEWAY_HINT_HEADERS";
 /** The session display name: "<agent>-<scenario>" (sanitised), else the agent slug. */
 export function sessionDisplayName(agent, scenario) {
     return sanitizeAgentName(`${agent}-${scenario}`) || agent;
@@ -466,7 +475,8 @@ export function resolveRemoteControlShape(args) {
  */
 export function buildCustomHeaders(opts) {
     const lines = [
-        `x-api-key: ${opts.anthropicKey}`,
+        ...(opts.anthropicKey ? [`x-api-key: ${opts.anthropicKey}`] : []),
+        ...(opts.mnemomKey ? [`x-mnemom-api-key: ${opts.mnemomKey}`] : []),
         `x-mnemom-agent: ${opts.agent}`,
         `x-mnemom-conversation-id: ${opts.conversationId}`,
     ];

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

@@ -15,6 +15,7 @@
  * resolvers in lib/code.ts keep the built-in default as the final fallback);
  * the caller folds the plain-value settings under the CLI flags.
  */
+import { type AgentAuth } from "./subscription-login.js";
 import type { ExperimentalId } from "./experimental.js";
 import { type ContextProfile, type GoalModeDefault, type LaunchShape } from "./agent.js";
 /** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
@@ -29,6 +30,8 @@ export interface LauncherConfig {
     effort?: string;
     cli?: string;
     launch?: LaunchShape;
+    /** How Claude Code authenticates (lib/subscription-login.ts); api-key when unset. */
+    auth?: AgentAuth;
     keySource?: KeySource;
     /** Standing goal-alignment default when neither --goal nor --implicit is given. */
     goalMode?: GoalModeDefault;

package/dist/lib/launcher-config.js

@@ -15,6 +15,7 @@
  * resolvers in lib/code.ts keep the built-in default as the final fallback);
  * the caller folds the plain-value settings under the CLI flags.
  */
+import { AGENT_AUTH_ENV, AGENT_AUTHS, coerceAgentAuth, } from "./subscription-login.js";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parse as parseToml, stringify as stringifyToml, TomlError } from "smol-toml";
@@ -132,6 +133,14 @@ export const CONFIG_KEYS = [
             c.launch = coerceLaunch(v);
         },
     },
+    {
+        key: "auth",
+        describe: `How Claude Code authenticates (${AGENT_AUTHS.join("|")}); subscription = your Claude Team/Enterprise login, terminal-only`,
+        get: (c) => c.auth,
+        set: (c, v) => {
+            c.auth = coerceAgentAuth(v);
+        },
+    },
     {
         key: "key_source",
         describe: `Where to source the Anthropic key (${KEY_SOURCES.join("|")})`,
@@ -258,6 +267,8 @@ export function parseLauncherConfig(text) {
         cfg.cli = coerceNonEmpty("cli", str(raw.cli) ?? "");
     if (raw.launch !== undefined)
         cfg.launch = coerceLaunch(str(raw.launch) ?? "");
+    if (raw.auth !== undefined)
+        cfg.auth = coerceAgentAuth(str(raw.auth) ?? "");
     if (raw.key_source !== undefined)
         cfg.keySource = coerceKeySource(str(raw.key_source) ?? "");
     if (raw.goal_mode !== undefined)
@@ -330,6 +341,8 @@ export function serializeLauncherConfig(cfg) {
         doc.cli = cfg.cli;
     if (cfg.launch !== undefined)
         doc.launch = cfg.launch;
+    if (cfg.auth !== undefined)
+        doc.auth = cfg.auth;
     if (cfg.keySource !== undefined)
         doc.key_source = cfg.keySource;
     if (cfg.goalMode !== undefined)
@@ -392,6 +405,9 @@ export function applyConfigToEnv(cfg, env = process.env) {
         env.MNEMOM_AGENT_REMOTE_CONTROL =
             cfg.launch === "server" ? "server" : cfg.launch === "remote-control" ? "1" : "0";
     }
+    if (cfg.auth && !(env[AGENT_AUTH_ENV] ?? "").trim()) {
+        env[AGENT_AUTH_ENV] = cfg.auth;
+    }
     if (cfg.context !== undefined && !(env.MNEMOM_AGENT_CONTEXT ?? "").trim()) {
         env.MNEMOM_AGENT_CONTEXT = cfg.context ? "1" : "0";
     }

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

@@ -0,0 +1,53 @@
+/**
+ * `mnemom agent` with a Claude subscription login (`auth = subscription`) — Team and
+ * Enterprise plans only; the gateway checks the plan with Anthropic and refuses anything
+ * else (gateway/src/subscription-auth.ts).
+ *
+ * Claude Code then authenticates to the gateway with its own claude.ai OAuth login: the
+ * launch sets ANTHROPIC_BASE_URL and leaves ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN unset,
+ * so Claude Code sends `Authorization: Bearer <its login>`. No Anthropic key is involved.
+ * The gateway anchors the governed identity on a Mnemom API key instead
+ * (`x-mnemom-api-key`), which this module resolves — env, then the 0600 store, then a
+ * freshly minted gateway-only key — and the agent is created in that key's org on the
+ * first turn, so there is no CLI-side birth or claim.
+ *
+ * v1 is terminal-only: the Remote Control proxy rewrites the OAuth bearer away by design,
+ * and the context-handoff tool authenticates with an Anthropic key.
+ *
+ * Pure apart from the injected deps, so every arm is unit-tested.
+ */
+import type { LaunchShape } from "./agent.js";
+export type AgentAuth = "api-key" | "subscription";
+export declare const AGENT_AUTHS: readonly AgentAuth[];
+/** Env override for the setting (the launcher.toml `auth` key folds into it). */
+export declare const AGENT_AUTH_ENV = "MNEMOM_AGENT_AUTH";
+/** Env override for the Mnemom key a subscription launch sends. */
+export declare const MNEMOM_KEY_ENV = "MNEMOM_AGENT_MNEMOM_KEY";
+/** Field in ~/.mnemom/launcher.json (0600) holding the minted key. */
+export declare const MNEMOM_KEY_STORE_FIELD = "mnemom_api_key";
+export declare function coerceAgentAuth(raw: string): AgentAuth;
+/** `--auth` flag > MNEMOM_AGENT_AUTH (launcher.toml folds in here) > api-key. */
+export declare function resolveAgentAuth(flag: string | undefined, env: Record<string, string | undefined>): AgentAuth;
+export interface MnemomKeyDeps {
+    env: Record<string, string | undefined>;
+    readStored(): string | undefined;
+    /** Mint a gateway-only personal key for this machine; returns the secret. */
+    mint(): Promise<string>;
+    store(key: string): void;
+    say(line: string): void;
+}
+/**
+ * The Mnemom key a subscription launch sends: MNEMOM_AGENT_MNEMOM_KEY, else the stored
+ * key, else mint one (gateway scope only) and store it. The key is never printed.
+ */
+export declare function resolveSubscriptionMnemomKey(deps: MnemomKeyDeps): Promise<string>;
+/**
+ * Subscription login is terminal-only in v1. An explicit Remote Control / server request
+ * is refused; an automatic upgrade to Remote Control falls back to terminal with a notice.
+ */
+export declare function subscriptionShape(shape: LaunchShape, shapeExplicit: boolean, say: (line: string) => void): LaunchShape;
+/**
+ * The child env for a subscription launch: the gateway door, the Mnemom headers, and
+ * NOTHING that would make Claude Code send a key instead of its claude.ai login.
+ */
+export declare function subscriptionChildEnv(base: NodeJS.ProcessEnv, door: string, headers: string): NodeJS.ProcessEnv;

package/dist/lib/subscription-login.js

@@ -0,0 +1,103 @@
+/**
+ * `mnemom agent` with a Claude subscription login (`auth = subscription`) — Team and
+ * Enterprise plans only; the gateway checks the plan with Anthropic and refuses anything
+ * else (gateway/src/subscription-auth.ts).
+ *
+ * Claude Code then authenticates to the gateway with its own claude.ai OAuth login: the
+ * launch sets ANTHROPIC_BASE_URL and leaves ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN unset,
+ * so Claude Code sends `Authorization: Bearer <its login>`. No Anthropic key is involved.
+ * The gateway anchors the governed identity on a Mnemom API key instead
+ * (`x-mnemom-api-key`), which this module resolves — env, then the 0600 store, then a
+ * freshly minted gateway-only key — and the agent is created in that key's org on the
+ * first turn, so there is no CLI-side birth or claim.
+ *
+ * v1 is terminal-only: the Remote Control proxy rewrites the OAuth bearer away by design,
+ * and the context-handoff tool authenticates with an Anthropic key.
+ *
+ * Pure apart from the injected deps, so every arm is unit-tested.
+ */
+export const AGENT_AUTHS = ["api-key", "subscription"];
+/** Env override for the setting (the launcher.toml `auth` key folds into it). */
+export const AGENT_AUTH_ENV = "MNEMOM_AGENT_AUTH";
+/** Env override for the Mnemom key a subscription launch sends. */
+export const MNEMOM_KEY_ENV = "MNEMOM_AGENT_MNEMOM_KEY";
+/** Field in ~/.mnemom/launcher.json (0600) holding the minted key. */
+export const MNEMOM_KEY_STORE_FIELD = "mnemom_api_key";
+/**
+ * The key is spliced into the newline-joined ANTHROPIC_CUSTOM_HEADERS block, so an embedded
+ * CR/LF (a multi-line paste, a bad env value) would inject extra header lines.
+ */
+function headerSafe(raw) {
+    return raw.replace(/[\r\n]+/g, "").trim();
+}
+export function coerceAgentAuth(raw) {
+    const v = raw.trim().toLowerCase();
+    if (AGENT_AUTHS.includes(v))
+        return v;
+    throw new Error(`auth must be one of ${AGENT_AUTHS.join(", ")} (got '${raw}').`);
+}
+/** `--auth` flag > MNEMOM_AGENT_AUTH (launcher.toml folds in here) > api-key. */
+export function resolveAgentAuth(flag, env) {
+    if (flag !== undefined && flag.trim())
+        return coerceAgentAuth(flag);
+    const fromEnv = (env[AGENT_AUTH_ENV] ?? "").trim();
+    return fromEnv ? coerceAgentAuth(fromEnv) : "api-key";
+}
+/**
+ * The Mnemom key a subscription launch sends: MNEMOM_AGENT_MNEMOM_KEY, else the stored
+ * key, else mint one (gateway scope only) and store it. The key is never printed.
+ */
+export async function resolveSubscriptionMnemomKey(deps) {
+    const fromEnv = headerSafe(deps.env[MNEMOM_KEY_ENV] ?? "");
+    if (fromEnv)
+        return fromEnv;
+    const stored = headerSafe(deps.readStored() ?? "");
+    if (stored)
+        return stored;
+    let minted;
+    try {
+        minted = headerSafe(await deps.mint());
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`mnemom agent: subscription login needs a Mnemom API key and minting one failed (${msg}).\n` +
+            `  Create one with \`mnemom api-key create --name mnemom-agent --scopes gateway\` and set ${MNEMOM_KEY_ENV}.`, { cause: err });
+    }
+    if (!minted)
+        throw new Error("mnemom agent: the API returned an empty Mnemom key.");
+    try {
+        deps.store(minted);
+        deps.say("mnemom agent: minted a gateway-only Mnemom API key for subscription login (saved to ~/.mnemom/launcher.json, 0600).");
+    }
+    catch {
+        deps.say("mnemom agent: minted a gateway-only Mnemom API key for this launch but could not save it — the next launch mints another.");
+    }
+    return minted;
+}
+/**
+ * Subscription login is terminal-only in v1. An explicit Remote Control / server request
+ * is refused; an automatic upgrade to Remote Control falls back to terminal with a notice.
+ */
+export function subscriptionShape(shape, shapeExplicit, say) {
+    if (shape === "terminal")
+        return shape;
+    if (shapeExplicit) {
+        throw new Error(`mnemom agent: subscription login runs terminal-only for now — drop --${shape === "server" ? "server" : "remote-control"} (or \`mnemom agent config set launch terminal\`), or use auth = api-key.`);
+    }
+    say("mnemom agent: subscription login runs terminal-only for now — launching in this terminal.");
+    return "terminal";
+}
+/**
+ * The child env for a subscription launch: the gateway door, the Mnemom headers, and
+ * NOTHING that would make Claude Code send a key instead of its claude.ai login.
+ */
+export function subscriptionChildEnv(base, door, headers) {
+    const env = { ...base };
+    delete env.ANTHROPIC_API_KEY;
+    delete env.ANTHROPIC_AUTH_TOKEN;
+    // The key already rides in the headers; the child process has no other use for it.
+    delete env.MNEMOM_AGENT_MNEMOM_KEY;
+    env.ANTHROPIC_BASE_URL = door;
+    env.ANTHROPIC_CUSTOM_HEADERS = headers;
+    return env;
+}

package/package.json

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