@mnemom/mnemom 0.17.4-next.0 → 0.17.4-next.2

package/dist/commands/agent.d.ts

@@ -26,6 +26,7 @@
  * 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 {
@@ -103,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

package/dist/commands/agent.js

@@ -34,15 +34,16 @@ import { fileURLToPath } from "node:url";
 import { getApiUrl, getGatewayUrl, MNEMOM_DIR } from "../lib/config.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, resolveRetentionDays, toLedgerContract, } from "../lib/agent-ledger.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";
 import { fmt } from "../lib/format.js";
-import { askInput, askYesNo, isInteractive } from "../lib/prompt.js";
+import { askInput, askSelect, askYesNo, isInteractive } from "../lib/prompt.js";
+import { authConfigured, chooseAuth, detectClaudeLogin, readClaudeLoginState, } from "../lib/login-detect.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
 import { 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. */
@@ -80,7 +81,22 @@ export async function agentCommand(scenarioArg, options = {}) {
     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);
+    let auth = resolveAgentAuth(options.auth, env);
+    // Nothing configured it yet: detect Claude Code's own login and, when there is a real
+    // choice, ask once and save the answer (lib/login-detect.ts). Never on --dry-run.
+    if (!options.dryRun && !authConfigured(options.auth, env)) {
+        auth = await chooseAuth({
+            login: detectClaudeLogin(readClaudeLoginState(env, homedir(), (path) => readFileSync(path, "utf8"))),
+            interactive: isInteractive(),
+            select: askSelect,
+            persist: (choice) => {
+                const cfg = loadLauncherConfig();
+                cfg.auth = choice;
+                writeLauncherConfig(cfg);
+            },
+            say,
+        });
+    }
     // ── 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
@@ -89,7 +105,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,
@@ -173,7 +188,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,
@@ -185,7 +201,7 @@ export async function agentCommand(scenarioArg, options = {}) {
             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.");
+            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.");
         }
         if (expNotice)
             say(expNotice);
@@ -257,12 +273,12 @@ export async function agentCommand(scenarioArg, options = {}) {
         rcCapable: rc.ok,
         say,
     });
-    // Subscription login: terminal-only for now, and the governed identity anchors on a
+    // Subscription login: Remote Control only for RC-entitled (internal) accounts, and the governed identity anchors on a
     // Mnemom API key (minted once and stored if there is none). Resolved after sign-in so
     // minting can use the session.
     let mnemomKey;
     if (auth === "subscription") {
-        shape = subscriptionShape(shape, shapeExplicit, say);
+        shape = subscriptionShape(shape, shapeExplicit, rcAllowed, say);
         mnemomKey = await resolveSubscriptionMnemomKey(defaultMnemomKeyDeps());
     }
     // Now that a session exists, a defaulted slug uses the real login handle from
@@ -305,6 +321,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
@@ -368,8 +400,7 @@ 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.`));
         }
     }
-    // A subscription launch (no Anthropic key) is always terminal — see subscriptionShape.
-    if (shape === "terminal" || !anthropicKey) {
+    if (shape === "terminal") {
         launchTerminal({
             cli,
             door,
@@ -394,6 +425,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         cli,
         door,
         anthropicKey,
+        mnemomKey,
         agent,
         conversationId,
         scenario,
@@ -409,6 +441,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
@@ -738,6 +827,7 @@ function launchTerminal(ctx) {
     }
     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) {
@@ -781,6 +871,7 @@ function launchRemoteControl(ctx) {
             MNEMOM_AGENT_RC_SESSION_CONFIG: ctx.sessionConfigB64 ?? "",
             MNEMOM_AGENT_RC_PROXY_LOG: proxyLog,
             MNEMOM_AGENT_RC_PARENT_PID: String(process.pid),
+            MNEMOM_AGENT_RC_AUTH: ctx.anthropicKey ? "api-key" : "subscription",
         },
         stdio: ["pipe", "pipe", "inherit"],
     });
@@ -805,8 +896,9 @@ function launchRemoteControl(ctx) {
         }
     };
     process.on("exit", onExit);
-    // Secrets on stdin — three lines (anthropic, mnemom, openai). Only the
-    // Anthropic key is used on this Anthropic-only door; the other two are empty.
+    // Secrets on stdin — three lines (anthropic, mnemom, openai). An api-key launch sends the
+    // Anthropic key only; a subscription launch sends the Mnemom key only (the identity anchor —
+    // the user's OAuth bearer is what pays). openai is always empty on this Anthropic-only door.
     // A proxy that exits before reading them turns this write into an EPIPE; that is
     // not a failure of its own — the exited-before-READY check below refuses the
     // launch. Any other stdin error fails closed like a spawn error.
@@ -817,7 +909,7 @@ function launchRemoteControl(ctx) {
         onExit();
         process.exit(1);
     });
-    proxy.stdin?.end(`${ctx.anthropicKey}\n\n\n`);
+    proxy.stdin?.end(`${ctx.anthropicKey ?? ""}\n${ctx.anthropicKey ? "" : (ctx.mnemomKey ?? "")}\n\n`);
     let stdoutBuf = "";
     const start = Date.now();
     const tryStart = () => {
@@ -902,8 +994,10 @@ function spawnRcCli(ctx) {
     // ANTHROPIC_* base-url/key/socket family (same reason HTTPS_PROXY/NODE_EXTRA_CA_CERTS already
     // ride through here ungated), so this rides through untouched. Only set when the tool is
     // actually registered — never on a plain RC launch.
-    if (ctx.handoffMcpConfigPath)
+    // (Never on a subscription launch — handoff is turned off there, so there is no key to set.)
+    if (ctx.handoffMcpConfigPath && ctx.anthropicKey) {
         childEnv[HANDOFF_RC_KEY_ENV_NAME] = ctx.anthropicKey;
+    }
     let args;
     if (ctx.shape === "server") {
         // Headless dispatcher: no --model/--effort/--trim-mcp/yolo flags; the model

package/dist/index.js

@@ -142,7 +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("--auth <mode>", "How Claude Code authenticates: api-key (default) | subscription (your Claude Team/Enterprise login)")
     .option("--model <alias|id>", "Model to launch (CLI alias or concrete id)")
     .addOption(new Option("--effort <level>", "Reasoning effort").choices([
     "low",

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). */

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;

package/dist/lib/launcher-config.js

@@ -135,7 +135,7 @@ export const CONFIG_KEYS = [
     },
     {
         key: "auth",
-        describe: `How Claude Code authenticates (${AGENT_AUTHS.join("|")}); subscription = your Claude Team/Enterprise login, terminal-only`,
+        describe: `How Claude Code authenticates (${AGENT_AUTHS.join("|")}); subscription = your Claude Team/Enterprise login`,
         get: (c) => c.auth,
         set: (c, v) => {
             c.auth = coerceAgentAuth(v);

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

@@ -0,0 +1,74 @@
+/**
+ * First-run login menu for `mnemom agent`: detect how Claude Code is signed in on this
+ * machine, then — only when there is a real choice to make — ask once and save the answer
+ * as launcher.toml `auth`.
+ *
+ * Four ways Claude Code can be signed in, and what the gateway does with each today:
+ *   - Claude subscription, Team or Enterprise → `auth = subscription` (supported).
+ *   - Claude subscription, Pro / Max (individual) → not supported (Team/Enterprise only).
+ *   - Anthropic Console login → not supported yet.
+ *   - Third-party provider (Bedrock / Vertex / Foundry) → not supported yet (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
+ * CLAUDE_CODE_USE_* switches). They only pick a default: the gateway still checks the plan
+ * with Anthropic and refuses anything that isn't Team/Enterprise.
+ *
+ * Pure apart from the injected deps, so every arm is unit-tested.
+ */
+import type { AgentAuth } from "./subscription-login.js";
+export type ThirdPartyProvider = "bedrock" | "vertex" | "foundry";
+export type ClaudeLogin = {
+    kind: "subscription";
+    plan: "team" | "enterprise";
+} | {
+    kind: "individual";
+    plan: string;
+} | {
+    kind: "console";
+} | {
+    kind: "third-party";
+    provider: ThirdPartyProvider;
+} | {
+    kind: "none";
+};
+export interface DetectInput {
+    /** Process env, then the `env` block of Claude Code's settings.json (the process wins). */
+    env: Record<string, string | undefined>;
+    settingsEnv: Record<string, string | undefined>;
+    /** Parsed ~/.claude.json, or undefined when missing/unreadable. */
+    claudeJson: unknown;
+}
+export declare function detectClaudeLogin(input: DetectInput): ClaudeLogin;
+export type UnsupportedLogin = Extract<ClaudeLogin, {
+    kind: "individual" | "console" | "third-party";
+}>;
+/** Why a detected login can't be used through the gateway. */
+export declare function unsupportedReason(login: UnsupportedLogin): string;
+export declare const MENU_SUBSCRIPTION = "Claude subscription \u2014 Team or Enterprise (your claude.ai login)";
+export declare const MENU_CONSOLE = "Anthropic Console login (not supported yet)";
+export declare const MENU_THIRD_PARTY = "Amazon Bedrock / Google Vertex AI / Microsoft Foundry (not supported yet)";
+export declare const MENU_API_KEY = "Anthropic API key";
+export interface ChooseAuthDeps {
+    login: ClaudeLogin;
+    interactive: boolean;
+    select(question: string, options: string[]): Promise<string | null>;
+    persist(auth: AgentAuth): void;
+    say(line: string): void;
+}
+/**
+ * Pick `auth` when nothing configured it (no --auth, MNEMOM_AGENT_AUTH or launcher.toml).
+ *   - No Claude login detected → api-key, silently, nothing saved (today's behaviour).
+ *   - A login we can't use → api-key, say why once, save it so the note isn't repeated.
+ *   - Team/Enterprise and non-interactive → api-key, nothing saved (never switch a script's
+ *     auth without asking); interactive → the four-option menu, answer saved.
+ */
+export declare function chooseAuth(deps: ChooseAuthDeps): Promise<AgentAuth>;
+/** True when `auth` is already decided: `--auth`, or MNEMOM_AGENT_AUTH (launcher.toml folds in). */
+export declare function authConfigured(flag: string | undefined, env: Record<string, string | undefined>): boolean;
+/**
+ * Read Claude Code's own state the way Claude Code locates it: CLAUDE_CONFIG_DIR holds both
+ * `.claude.json` and `settings.json` when set; otherwise `~/.claude.json` and
+ * `~/.claude/settings.json`. A missing or corrupt file reads as "nothing there".
+ */
+export declare function readClaudeLoginState(env: Record<string, string | undefined>, home: string, readFile: (path: string) => string): DetectInput;

package/dist/lib/login-detect.js

@@ -0,0 +1,147 @@
+/**
+ * First-run login menu for `mnemom agent`: detect how Claude Code is signed in on this
+ * machine, then — only when there is a real choice to make — ask once and save the answer
+ * as launcher.toml `auth`.
+ *
+ * Four ways Claude Code can be signed in, and what the gateway does with each today:
+ *   - Claude subscription, Team or Enterprise → `auth = subscription` (supported).
+ *   - Claude subscription, Pro / Max (individual) → not supported (Team/Enterprise only).
+ *   - Anthropic Console login → not supported yet.
+ *   - Third-party provider (Bedrock / Vertex / Foundry) → not supported yet (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
+ * CLAUDE_CODE_USE_* switches). They only pick a default: the gateway still checks the plan
+ * with Anthropic and refuses anything that isn't Team/Enterprise.
+ *
+ * Pure apart from the injected deps, so every arm is unit-tested.
+ */
+const PROVIDER_SWITCHES = [
+    ["CLAUDE_CODE_USE_BEDROCK", "bedrock"],
+    ["CLAUDE_CODE_USE_VERTEX", "vertex"],
+    ["CLAUDE_CODE_USE_FOUNDRY", "foundry"],
+];
+/** Claude Code treats any non-empty value other than 0/false as on. */
+function switchOn(raw) {
+    const v = (raw ?? "").trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false";
+}
+export function detectClaudeLogin(input) {
+    // A provider switch wins over any login: Claude Code then talks to that provider.
+    for (const [name, provider] of PROVIDER_SWITCHES) {
+        if (switchOn(input.env[name] ?? input.settingsEnv[name])) {
+            return { kind: "third-party", provider };
+        }
+    }
+    const account = input.claudeJson && typeof input.claudeJson === "object"
+        ? input.claudeJson.oauthAccount
+        : undefined;
+    if (!account || typeof account !== "object")
+        return { kind: "none" };
+    const orgType = String(account.organizationType ?? "");
+    if (orgType === "claude_team")
+        return { kind: "subscription", plan: "team" };
+    if (orgType === "claude_enterprise")
+        return { kind: "subscription", plan: "enterprise" };
+    // claude_pro, claude_max, claude_free … — a personal claude.ai plan.
+    if (orgType.startsWith("claude_"))
+        return { kind: "individual", plan: orgType.slice(7) };
+    // Signed in, but not to a claude.ai plan: an Anthropic Console account.
+    return { kind: "console" };
+}
+const PROVIDER_NAMES = {
+    bedrock: "Amazon Bedrock",
+    vertex: "Google Vertex AI",
+    foundry: "Microsoft Foundry",
+};
+/** Why a detected login can't be used through the gateway. */
+export function unsupportedReason(login) {
+    switch (login.kind) {
+        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 "Anthropic Console login is not supported yet";
+        case "third-party":
+            return `${PROVIDER_NAMES[login.provider]} is not supported yet`;
+    }
+}
+export const MENU_SUBSCRIPTION = "Claude subscription — Team or Enterprise (your claude.ai login)";
+export const MENU_CONSOLE = "Anthropic Console login (not supported yet)";
+export const MENU_THIRD_PARTY = "Amazon Bedrock / Google Vertex AI / Microsoft Foundry (not supported yet)";
+export const MENU_API_KEY = "Anthropic API key";
+const SAVED_HINT = "change it any time with `mnemom agent config set auth api-key|subscription`";
+function save(deps, auth, line) {
+    try {
+        deps.persist(auth);
+        deps.say(`${line} Saved to launcher.toml — ${SAVED_HINT}.`);
+    }
+    catch {
+        deps.say(`${line} (Could not save it to launcher.toml; you'll be asked again.)`);
+    }
+    return auth;
+}
+/**
+ * Pick `auth` when nothing configured it (no --auth, MNEMOM_AGENT_AUTH or launcher.toml).
+ *   - No Claude login detected → api-key, silently, nothing saved (today's behaviour).
+ *   - A login we can't use → api-key, say why once, save it so the note isn't repeated.
+ *   - Team/Enterprise and non-interactive → api-key, nothing saved (never switch a script's
+ *     auth without asking); interactive → the four-option menu, answer saved.
+ */
+export async function chooseAuth(deps) {
+    const { login } = deps;
+    if (login.kind === "none")
+        return "api-key";
+    if (login.kind !== "subscription") {
+        return save(deps, "api-key", `mnemom agent: ${unsupportedReason(login)}, so this launch uses an Anthropic API key.`);
+    }
+    if (!deps.interactive)
+        return "api-key";
+    const options = [MENU_SUBSCRIPTION, MENU_CONSOLE, MENU_THIRD_PARTY, MENU_API_KEY];
+    const question = `mnemom agent: Claude Code is signed in with your Claude ${login.plan} plan. How should it sign in through Mnemom?`;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const picked = await deps.select(question, options);
+        if (picked === MENU_SUBSCRIPTION) {
+            return save(deps, "subscription", "mnemom agent: using your Claude subscription login.");
+        }
+        if (picked === MENU_API_KEY) {
+            return save(deps, "api-key", "mnemom agent: using an Anthropic API key.");
+        }
+        if (picked === MENU_CONSOLE || picked === MENU_THIRD_PARTY) {
+            deps.say("mnemom agent: that one isn't supported yet — pick 1 or 4.");
+            continue;
+        }
+        break; // no answer (EOF / out of range): don't loop forever
+    }
+    deps.say("mnemom agent: no choice made — using an Anthropic API key for this launch.");
+    return "api-key";
+}
+/** True when `auth` is already decided: `--auth`, or MNEMOM_AGENT_AUTH (launcher.toml folds in). */
+export function authConfigured(flag, env) {
+    return Boolean(flag?.trim()) || Boolean((env.MNEMOM_AGENT_AUTH ?? "").trim());
+}
+/**
+ * Read Claude Code's own state the way Claude Code locates it: CLAUDE_CONFIG_DIR holds both
+ * `.claude.json` and `settings.json` when set; otherwise `~/.claude.json` and
+ * `~/.claude/settings.json`. A missing or corrupt file reads as "nothing there".
+ */
+export function readClaudeLoginState(env, home, readFile) {
+    const dir = (env.CLAUDE_CONFIG_DIR ?? "").trim();
+    const parse = (path) => {
+        try {
+            return JSON.parse(readFile(path));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const claudeJson = parse(dir ? `${dir}/.claude.json` : `${home}/.claude.json`);
+    const settings = parse(dir ? `${dir}/settings.json` : `${home}/.claude/settings.json`);
+    const rawEnv = settings && typeof settings === "object" ? settings.env : undefined;
+    const settingsEnv = {};
+    if (rawEnv && typeof rawEnv === "object") {
+        for (const [k, v] of Object.entries(rawEnv))
+            if (typeof v === "string")
+                settingsEnv[k] = v;
+    }
+    return { env, settingsEnv, claudeJson };
+}

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

@@ -11,8 +11,8 @@
  * 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.
+ * Remote Control is internal-only (see subscriptionShape); the context-handoff tool
+ * authenticates with an Anthropic key, so it is off on a subscription launch.
  *
  * Pure apart from the injected deps, so every arm is unit-tested.
  */
@@ -42,10 +42,14 @@ export interface MnemomKeyDeps {
  */
 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.
+ * Remote Control on a subscription login is open to accounts entitled to Remote Control
+ * (internal Mnemom accounts): the RC proxy then forwards the user's own OAuth bearer to the
+ * gateway untouched (rc-proxy.mjs, MNEMOM_AGENT_RC_AUTH=subscription). Anyone else stays
+ * terminal-only: an explicit Remote Control / server request is refused, an automatic
+ * upgrade falls back to terminal with a notice. (resolveRemoteControlShape already degrades
+ * a non-entitled account to terminal; this is the fail-closed backstop.)
  */
-export declare function subscriptionShape(shape: LaunchShape, shapeExplicit: boolean, say: (line: string) => void): LaunchShape;
+export declare function subscriptionShape(shape: LaunchShape, shapeExplicit: boolean, rcAllowed: 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.

package/dist/lib/subscription-login.js

@@ -11,8 +11,8 @@
  * 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.
+ * Remote Control is internal-only (see subscriptionShape); the context-handoff tool
+ * authenticates with an Anthropic key, so it is off on a subscription launch.
  *
  * Pure apart from the injected deps, so every arm is unit-tested.
  */
@@ -75,11 +75,15 @@ export async function resolveSubscriptionMnemomKey(deps) {
     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.
+ * Remote Control on a subscription login is open to accounts entitled to Remote Control
+ * (internal Mnemom accounts): the RC proxy then forwards the user's own OAuth bearer to the
+ * gateway untouched (rc-proxy.mjs, MNEMOM_AGENT_RC_AUTH=subscription). Anyone else stays
+ * terminal-only: an explicit Remote Control / server request is refused, an automatic
+ * upgrade falls back to terminal with a notice. (resolveRemoteControlShape already degrades
+ * a non-entitled account to terminal; this is the fail-closed backstop.)
  */
-export function subscriptionShape(shape, shapeExplicit, say) {
-    if (shape === "terminal")
+export function subscriptionShape(shape, shapeExplicit, rcAllowed, say) {
+    if (shape === "terminal" || rcAllowed)
         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.`);

package/dist/rc-proxy.mjs

@@ -69,6 +69,11 @@
 //   MNEMOM_AGENT_RC_PROVIDER          x-mnemom-provider directive JSON (optional; router door)
 //   MNEMOM_AGENT_RC_THREAD_MODE       `reject` (default: answer thread-bearing requests locally,
 //                                  see above) | `strip` (legacy: delete `thread`, forward)
+//   MNEMOM_AGENT_RC_AUTH              `api-key` (default) | `subscription`: the user's own claude.ai
+//                                  Team/Enterprise login pays — the OAuth bearer and `oauth-*`
+//                                  betas are FORWARDED to the gateway untouched, no Anthropic key
+//                                  is involved (stdin line 1 empty), and the Mnemom key (line 2)
+//                                  is required: it anchors the governed identity.
 //   MNEMOM_AGENT_RC_PROXY_LOG         append log lines to this file instead of stderr (optional)
 //   MNEMOM_AGENT_RC_PARENT_PID        exit when this pid is gone, so no orphan holds the keys
 //   MNEMOM_AGENT_RC_PORT              listen port (default 0 = ephemeral)
@@ -107,6 +112,7 @@ const GOAL_MODE = env.MNEMOM_AGENT_RC_GOAL_MODE || "";
 const SESSION_CONFIG = env.MNEMOM_AGENT_RC_SESSION_CONFIG || "";
 const PROVIDER = env.MNEMOM_AGENT_RC_PROVIDER || "";
 const THREAD_MODE = env.MNEMOM_AGENT_RC_THREAD_MODE || "reject";
+const SUBSCRIPTION = env.MNEMOM_AGENT_RC_AUTH === "subscription";
 if (THREAD_MODE !== "reject" && THREAD_MODE !== "strip")
   die(`MNEMOM_AGENT_RC_THREAD_MODE must be 'reject' or 'strip', got '${THREAD_MODE}'`);
 const LOGFILE = env.MNEMOM_AGENT_RC_PROXY_LOG || "";
@@ -140,7 +146,9 @@ try {
 } catch {
   die("expected three lines of secrets on stdin (anthropic, mnemom, openai)");
 }
-if (!secrets.anthropic) die("the Anthropic key (stdin line 1) is empty");
+if (SUBSCRIPTION) {
+  if (!secrets.mnemom) die("subscription login needs the Mnemom key (stdin line 2)");
+} else if (!secrets.anthropic) die("the Anthropic key (stdin line 1) is empty");
 
 // --- ephemeral CA + rotating leaf for api.anthropic.com ---------------------------------
 // Private 0700 dir under the OS tmpdir, removed on exit. Claude Code reads NODE_EXTRA_CA_CERTS
@@ -403,8 +411,10 @@ function handle(req, res, viaPlain) {
       agent: gatewayAgent,
     };
     noteCcSession(headers["x-claude-code-session-id"]);
-    delete headers.authorization; // the OAuth bearer stays local
-    headers["x-api-key"] = secrets.anthropic;
+    if (!SUBSCRIPTION) {
+      delete headers.authorization; // the OAuth bearer stays local
+      headers["x-api-key"] = secrets.anthropic;
+    }
     headers["x-mnemom-agent"] = AGENT;
     headers["x-mnemom-conversation-id"] = CONV;
     if (secrets.mnemom) headers["x-mnemom-api-key"] = secrets.mnemom;
@@ -413,8 +423,8 @@ function handle(req, res, viaPlain) {
     if (CONTRACT_B64) headers["x-mnemom-contract"] = CONTRACT_B64;
     if (GOAL_MODE) headers["x-mnemom-goal-mode"] = GOAL_MODE;
     if (SESSION_CONFIG) headers["x-mnemom-session-config"] = SESSION_CONFIG;
-    if (headers["anthropic-beta"]) {
-      // drop the OAuth-only beta tokens
+    if (!SUBSCRIPTION && headers["anthropic-beta"]) {
+      // drop the OAuth-only beta tokens (a subscription leg keeps them: the bearer rides on)
       const b = String(headers["anthropic-beta"])
         .split(",")
         .map((s) => s.trim())

package/package.json

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