@mnemom/mnemom 0.17.2-next.2 → 0.17.2-next.4

package/dist/commands/agent-sessions.js

@@ -17,12 +17,20 @@ import { readSessionRecords } from "../lib/agent-ledger.js";
 import { MNEMOM_DIR } from "../lib/config.js";
 import { getAgentSession, MnemomApiError } from "../lib/api.js";
 import { fmt, formatRelativeAge } from "../lib/format.js";
+import { goalControlFetch } from "../lib/goal-api.js";
 /** The production wiring (index.ts). Lazy so a test that mocks lib/api without
  *  this export can still import index.ts. */
 export const liveSessionDeps = {
     // The ledger is oldest-first on disk; every consumer here wants newest-first.
     readRecords: () => readSessionRecords({ dir: MNEMOM_DIR }).reverse(),
     fetchSession: (conversationId, agentId, orgId) => getAgentSession(conversationId, agentId, orgId),
+    fetchGoal: async (record) => {
+        // Lazy: agent-goal.ts imports this module (ref resolution), and the key resolver behind it
+        // pulls in the launcher.
+        const { resolveLaunchCreds } = await import("./agent-goal.js");
+        const creds = await resolveLaunchCreds();
+        return goalControlFetch(record, "show", { thread: "main" }, { fetch, creds });
+    },
     out: (line) => console.log(line),
     err: (line) => console.error(line),
 };
@@ -32,8 +40,10 @@ export const DEFAULT_SESSIONS_LIMIT = 20;
  * Resolve `[ref]` against the ledger (newest first):
  *   - no ref → the newest record;
  *   - an exact session name → the newest record with that name, older ones in `others`;
- *   - else a conversation-id prefix → the unique match, or `{record: null, candidates}`
- *     when several share the prefix;
+ *   - else a conversation-id prefix → the newest record of the one conversation it names
+ *     (a relaunch / `--resume` appends another row for the same conversation id, which is not
+ *     ambiguity), or `{record: null, candidates}` — newest row per conversation — when several
+ *     distinct conversations share the prefix (an exact full id among them wins);
  *   - nothing matches (or the ledger is empty) → null.
  */
 export function resolveSessionRef(records, ref) {
@@ -47,11 +57,26 @@ export function resolveSessionRef(records, ref) {
         const others = records.filter((r) => r !== newestByName && r.session === needle);
         return { record: newestByName, others };
     }
-    const byConv = records.filter((r) => r.conversation_id.startsWith(needle));
+    // The ledger appends a row per launch, so a relaunch or `--resume` with the same
+    // `--conversation-id` leaves several rows for ONE conversation. Collapse to the newest row
+    // per conversation id (records are newest first) before deciding ambiguity: only distinct
+    // conversations are ambiguous.
+    const seen = new Set();
+    const byConv = records.filter((r) => {
+        if (!r.conversation_id.startsWith(needle) || seen.has(r.conversation_id))
+            return false;
+        seen.add(r.conversation_id);
+        return true;
+    });
     if (byConv.length === 1)
         return { record: byConv[0], others: [] };
-    if (byConv.length > 1)
+    if (byConv.length > 1) {
+        // A full conversation id that also prefixes a longer one still names exactly one.
+        const exact = byConv.find((r) => r.conversation_id === needle);
+        if (exact)
+            return { record: exact, others: [] };
         return { record: null, candidates: byConv };
+    }
     return null;
 }
 // ─── sessions table ───────────────────────────────────────────────────────────
@@ -246,6 +271,12 @@ export function unavailableReason(err) {
         return `${err.code}: ${err.message}`;
     return err instanceof Error ? err.message : String(err);
 }
+/** `rev N[ · pinned]` from a live show body, or `rev 0 (no goal yet)`. */
+export function liveGoalLine(body) {
+    if (!body.intent)
+        return "rev 0 (no goal yet)";
+    return `rev ${body.intent.revision}${body.intent.pinned ? " · pinned" : ""}`;
+}
 /** `mnemom agent show [ref] [--json]` */
 export async function agentShowCommand(ref, opts, deps) {
     const records = deps.readRecords();
@@ -290,6 +321,17 @@ export async function agentShowCommand(ref, opts, deps) {
     }
     for (const line of buildShowView(record, remote, reason))
         deps.out(line);
+    if (deps.fetchGoal && resolveGoalMode(record, remote) === "implicit") {
+        // Best effort: any failure (no key, gateway without the route, agent not found) is one dim line.
+        let line;
+        try {
+            line = liveGoalLine(await deps.fetchGoal(record));
+        }
+        catch {
+            line = fmt.dim("(live goal unavailable)");
+        }
+        deps.out(fmt.label("live goal:      ", line));
+    }
     if (others.length > 0) {
         deps.out("");
         deps.out(fmt.dim(`  ${others.length} older session(s) share this name — \`mnemom agent show <conv-id prefix>\` picks one:`));

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

@@ -115,3 +115,16 @@ export declare function ensureSessionAndBalance(opts: {
     orgLabel: string;
     entitlement: CodeEntitlement | null;
 }>;
+/**
+ * The account for a launch an orchestrator already preflighted
+ * (`MNEMOM_AGENT_PREFLIGHTED=1`, see launchPreflighted): no session prompt, no
+ * personal-org lookup, no µ-balance read. The entitlement is still fetched — it
+ * is the access gate and decides Remote Control fail-closed, which a caller's
+ * preflight can't vouch for. With no active org the api resolves the caller's
+ * primary org, and the ledger records the org id the entitlement names.
+ */
+export declare function resolvePreflightedAccount(): Promise<{
+    orgId: string;
+    orgLabel: string;
+    entitlement: CodeEntitlement | null;
+}>;

package/dist/commands/agent-setup.js

@@ -383,6 +383,20 @@ export async function ensureSessionAndBalance(opts) {
     await assertMuBalance(orgId, orgLabel);
     return { orgId, orgLabel, entitlement };
 }
+/**
+ * The account for a launch an orchestrator already preflighted
+ * (`MNEMOM_AGENT_PREFLIGHTED=1`, see launchPreflighted): no session prompt, no
+ * personal-org lookup, no µ-balance read. The entitlement is still fetched — it
+ * is the access gate and decides Remote Control fail-closed, which a caller's
+ * preflight can't vouch for. With no active org the api resolves the caller's
+ * primary org, and the ledger records the org id the entitlement names.
+ */
+export async function resolvePreflightedAccount() {
+    const active = getActiveOrg();
+    const orgLabel = active ? `${active.name} (${active.slug})` : "your primary org";
+    const entitlement = await assertCodeEnabled(active?.org_id ?? "", orgLabel);
+    return { orgId: active?.org_id ?? entitlement?.org_id ?? "", orgLabel, entitlement };
+}
 // ── The default coding posture (cards observe-only; goal contracts nudge) ────
 function buildCodeAlignmentCard(agentId) {
     return {

package/dist/commands/agent.d.ts

@@ -60,6 +60,12 @@ export interface AgentOptions {
     context?: boolean;
     /** context-hint seed default: commander `--no-context-hint` sets this false. */
     contextHint?: boolean;
+    /**
+     * EXPERIMENTAL, off by default (operator directive, MNE-7564): registers the `handoff` MCP
+     * tool and tells the gateway `CONTEXT_HANDOFF_ENABLED=true` for this session only. Absent/false
+     * ⇒ no header key, no MCP server — the launch is byte-identical to a build without this flag.
+     */
+    contextHandoff?: boolean;
     /**
      * Governed-agent provisioning: undefined = AUTO (provision-with-confirm when
      * interactive, warn-and-continue otherwise), true = force (`--setup`), false =
@@ -98,6 +104,8 @@ export declare function recordSessionLaunch(ctx: {
     cli: ResolvedCli;
     envelope: SealedContractEnvelope | null;
     goalMode: string | null;
+    /** The Claude Code session id (pickCcSessionId); null/absent when Claude Code picks it. */
+    ccSessionId?: string | null;
 }): Promise<void>;
 /**
  * Resolve the Anthropic key with NO 1Password dependency (built for external
@@ -153,17 +161,48 @@ export interface RcCapability {
  * and by the auto-default selection (a bare launch prefers RC when capable).
  */
 export declare function checkRcCapability(cli: ResolvedCli): RcCapability;
+/**
+ * Locates the `handoff` MCP server (src/mcp/handoff-server.mjs in dev, dist/mcp/handoff-server.mjs
+ * once built — a raw, uncompiled `.mjs` file that `copy-assets.mjs` copies verbatim, exactly like
+ * `resolveProxyScript`'s `rc-proxy.mjs`, so the SAME relative path resolves in both trees).
+ *
+ * `baseDirOverride` exists ONLY so a test can exercise the missing-file throw deterministically
+ * (point it at a directory with no `../mcp/handoff-server.mjs` beside it) without touching the
+ * real installed tree; every real caller omits it and gets `import.meta.url`'s own directory.
+ */
+export declare function resolveHandoffServerScript(baseDirOverride?: string): string;
 /**
  * Build the coding-agent CLI args from the model/effort/trim-mcp/yolo knobs plus
  * the caller's passthrough. `--model`/`--effort` are injected only when given (no
- * silent default). yolo appends `--dangerously-skip-permissions`. `--trim-mcp`
+ * silent default). yolo appends `--dangerously-skip-permissions`. A `ccSessionId`
+ * (pickCcSessionId, inject arm) appends `--session-id <id>`. `--trim-mcp`
  * appends `--strict-mcp-config --mcp-config {}` LAST so it wins over any
- * caller-supplied --mcp-config.
+ * caller-supplied --mcp-config — UNLESS `handoffMcpConfigPath` is set (context
+ * handoff ON, MNE-7564), in which case that file (which already declares only the
+ * `mnemom-handoff` server) is what `--strict-mcp-config` points at, so trimming
+ * strips every OTHER server but the handoff tool survives. Without `--trim-mcp`,
+ * the same path is passed WITHOUT `--strict-mcp-config` so it only ADDS the tool
+ * on top of the caller's/CLI's own MCP config rather than replacing it.
  */
 export declare function buildCliArgs(options: AgentOptions, ctx: {
     yolo: boolean;
     allowCliFlags: boolean;
+    ccSessionId?: string;
+    handoffMcpConfigPath?: string;
 }): string[];
+/**
+ * The Claude Code session id a launch runs under, from the caller's passthrough (implicit-goal
+ * CLI, cli-telemetry §1.5):
+ *   - `--session-id <uuid>` (or `=<uuid>`) → that id; the caller's own flag, nothing injected;
+ *   - `--fork-session` → null (Claude Code mints the fork's id);
+ *   - `--resume <id>` / `-r <id>` (or `--resume=<id>`) → that id, nothing injected;
+ *   - a bare `--resume` / `-r`, `--continue` / `-c` → null (Claude Code picks the session);
+ *   - otherwise → a fresh UUID the launcher injects as `--session-id`.
+ */
+export declare function pickCcSessionId(passthrough: string[], newId?: () => string): {
+    id: string | null;
+    inject: boolean;
+};
 /**
  * Which goal-alignment mode the launch status line names: a sealed contract →
  * "on"; `--implicit` (mode header, no contract) → "implicit"; neither → "off".

package/dist/commands/agent.js

@@ -27,6 +27,7 @@
  */
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, renameSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { tmpdir, homedir } from "node:os";
 import { basename, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -35,18 +36,18 @@ import { getAgentByName } from "../lib/api.js";
 import { LEDGER_FILE, appendSessionRecord, toLedgerContract } from "../lib/agent-ledger.js";
 import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
 import { fmt } from "../lib/format.js";
-import { askInput, askSelect, askYesNo, isInteractive } from "../lib/prompt.js";
+import { askInput, askYesNo, isInteractive } from "../lib/prompt.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
-import { defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, } from "./agent-setup.js";
-import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildSessionConfigB64, resolveContextFold, isProdGateway, launchPreferenceExplicit, remoteControlAllowed, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, resolveLaunchShape, resolveRemoteControlShape, sanitizeAgentName, } from "../lib/agent.js";
+import { defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.js";
+import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfigB64, resolveContextFold, resolveContextHandoff, resolveHandoffGatewayHost, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, resolveLaunchShape, resolveRemoteControlShape, sanitizeAgentName, } from "../lib/agent.js";
 /** The CLI's own provider-key store (zero 1Password): ~/.mnemom/launcher.json, 0600. */
 const CODE_STORE = join(MNEMOM_DIR, "launcher.json");
 const say = (line = "") => console.error(line);
 /** Entry point for `mnemom agent [scenario]`. Throws on fatal misconfig. */
 export async function agentCommand(scenarioArg, options = {}) {
     // ── session name + goal ── (a bare `mnemom agent` in a terminal asks for both,
-    // explaining goal alignment: infer it from your messages (implicit), type a
-    // one-line goal (sealed), or off — no contract header and no mode header)
+    // goal alignment is implicit by default (inferred from your messages); --goal
+    // seals a contract and --no-implicit turns it off — all resolved upstream.
     const session = await resolveSessionSetup({
         scenario: scenarioArg,
         goal: options.goal,
@@ -55,7 +56,6 @@ export async function agentCommand(scenarioArg, options = {}) {
     }, {
         askInput: (q) => askInput(q),
         askYesNo: (q, d) => askYesNo(q, d),
-        askSelect: (q, o) => askSelect(q, o),
     });
     const scenario = session.scenario;
     const env = process.env;
@@ -100,7 +100,8 @@ export async function agentCommand(scenarioArg, options = {}) {
     // launcher.toml → MNEMOM_AGENT_CONTEXT) turns it off for this session via the
     // per-session config header. `undefined` sessionConfigB64 ⇒ nothing sent.
     const contextFold = resolveContextFold({ context: options.context, env });
-    const sessionConfigB64 = buildSessionConfigB64(contextFold);
+    const contextHandoff = resolveContextHandoff({ contextHandoff: options.contextHandoff, env });
+    const sessionConfigB64 = buildSessionConfigB64({ fold: contextFold, contextHandoff });
     // ── which CLI executable (name or full path) ── resolve GRACEFULLY: if it's not
     // found we don't crash with a technical error — we ask for the path at launch.
     let cli;
@@ -146,6 +147,9 @@ export async function agentCommand(scenarioArg, options = {}) {
         if (!contextFold) {
             say("mnemom agent: context folding OFF for this session (--no-context or context = false).");
         }
+        if (contextHandoff) {
+            say("mnemom agent: context handoff ON (experimental) — the `handoff` MCP tool would be registered.");
+        }
         return;
     }
     // Real launch: make sure we actually have a CLI to run. If we couldn't find it,
@@ -165,9 +169,14 @@ export async function agentCommand(scenarioArg, options = {}) {
     // there isn't one — and (2) enforce a positive µ balance on the org the agent
     // lives in (default: the user's personal org). No µ ⇒ blocked with a
     // portal-style top-up message. Skipped only on --dry-run (handled above).
+    // MNEMOM_AGENT_PREFLIGHTED=1 (orchestrators such as the ADW fleet that already
+    // ran their own session + balance preflight) skips those round trips; the
+    // entitlement is still fetched — see resolvePreflightedAccount.
     let account;
     try {
-        account = await ensureSessionAndBalance({ interactive: isInteractive() });
+        account = launchPreflighted(env)
+            ? await resolvePreflightedAccount()
+            : await ensureSessionAndBalance({ interactive: isInteractive() });
     }
     catch (err) {
         if (isQuietPreambleExit(err))
@@ -182,7 +191,11 @@ export async function agentCommand(scenarioArg, options = {}) {
     // terminal-only with a notice. FAIL-CLOSED — a null entitlement (gate failed
     // open) or an api without the field yields no Remote Control.
     const rcAllowed = remoteControlAllowed(account.entitlement);
-    const rc = checkRcCapability(cli);
+    // The capability probe (`claude --help`, up to 10s, plus `command -v` for node
+    // and openssl) only feeds the auto-upgrade. An explicit shape never auto-upgrades
+    // and a non-allowed account never gets Remote Control, so both skip it; an
+    // explicit RC launch still refuses a missing node/openssl in launchRemoteControl.
+    const rc = shapeExplicit || !rcAllowed ? { ok: false, missing: [] } : checkRcCapability(cli);
     // Preserve the "how to turn Remote Control on" guidance for an allowed account
     // whose machine can't do it yet and who didn't pin a shape (the old
     // applyAutoShape behaviour). Non-allowed accounts never see it — RC isn't
@@ -229,6 +242,10 @@ export async function agentCommand(scenarioArg, options = {}) {
     // launch so `mnemom agent sessions` / `show` can find this conversation later.
     // Written after provisioning so a freshly claimed agent's id resolves. Holds
     // NO secret (never the key, the headers, or the child env); best-effort.
+    // The Claude Code session id this launch pins (terminal + interactive RC). The server shape
+    // hosts many sessions in one process, so it records none and injects nothing.
+    const cc = shape === "server" ? { id: null, inject: false } : pickCcSessionId(options.passthrough ?? []);
+    const ccSessionId = cc.inject && cc.id ? cc.id : undefined;
     await recordSessionLaunch({
         session: scenario,
         conversationId,
@@ -240,12 +257,49 @@ export async function agentCommand(scenarioArg, options = {}) {
         cli,
         envelope,
         goalMode,
+        ccSessionId: cc.id,
     });
     logLaunch({ shape, door, agent, conversationId, cellNote, envelope, goalMode, cli });
     say(goalAlignmentLine(goalAlignmentMode(envelope, goalMode)));
     if (!contextFold) {
         say("mnemom agent: context folding OFF for this session (--no-context or context = false).");
     }
+    // ── handoff MCP tool (MNE-7564) ── OFF by default: absent/false ⇒ handoffMcpConfigPath stays
+    // undefined and buildCliArgs/spawnRcCli are byte-identical to a build without this flag. ON:
+    // the config is written to a 0600 temp file and referenced by PATH only — never inlined into
+    // argv, where `ps` could see it, and — for every shape — it carries no key material at all
+    // (see `HandoffAnthropicKeySource`). A failure here degrades to "no handoff tool" with a
+    // warning; it never blocks the launch.
+    let handoffMcpConfigPath;
+    if (contextHandoff) {
+        try {
+            // Terminal shape: the real key never needs to touch this file at all — it already rides
+            // in the launched process's OWN `ANTHROPIC_CUSTOM_HEADERS` env var (buildCustomHeaders,
+            // below), which a spawned stdio MCP server inherits in full, so the server can read it
+            // back out at request time. Remote Control (both shapes) strips every ANTHROPIC_* auth
+            // var from the child's env, so `spawnRcCli` below instead sets a dedicated, non-ANTHROPIC
+            // var (HANDOFF_RC_KEY_ENV_NAME) on that same child env — still nothing in this file.
+            const anthropicKeySource = shape === "terminal"
+                ? { envName: "ANTHROPIC_CUSTOM_HEADERS" }
+                : { envName: HANDOFF_RC_KEY_ENV_NAME };
+            handoffMcpConfigPath = writeHandoffMcpConfigFile(buildHandoffMcpConfigJson({
+                // The SAME origin the session's own model traffic goes to — not resolveGatewayHost,
+                // which would ignore a MNEMOM_AGENT_ANTHROPIC_GATEWAY override (a test-cell launch
+                // must never send its handoff calls to prod, or vice versa).
+                gatewayHost: resolveHandoffGatewayHost(door),
+                anthropicKeySource,
+                agent,
+                conversationId,
+                sessionConfigB64,
+                serverScript: resolveHandoffServerScript(),
+                nodeBin: process.execPath,
+            }));
+            say("mnemom agent: context handoff ON (experimental) — the `handoff` tool is registered; call it at a natural stopping point or on the gateway's warning line.");
+        }
+        catch (err) {
+            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") {
         launchTerminal({
             cli,
@@ -259,6 +313,8 @@ export async function agentCommand(scenarioArg, options = {}) {
             options,
             yolo,
             contextHint,
+            ccSessionId,
+            handoffMcpConfigPath,
         });
         return; // launchTerminal exits the process
     }
@@ -273,8 +329,10 @@ export async function agentCommand(scenarioArg, options = {}) {
         envelope,
         goalMode,
         sessionConfigB64,
+        handoffMcpConfigPath,
         options,
         yolo,
+        ccSessionId,
     });
 }
 // ───────────────────────────────────────────────────────────────────────────
@@ -307,6 +365,7 @@ export async function recordSessionLaunch(ctx) {
         cli: ctx.cli.name,
         contract: toLedgerContract(ctx.envelope?.contract ?? null),
         goal_mode: goalAlignmentMode(ctx.envelope, ctx.goalMode),
+        cc_session_id: ctx.ccSessionId ?? null,
     }, { dir: MNEMOM_DIR, now: () => new Date(), pid: process.pid });
     if (!result.ok) {
         say(fmt.warn(`mnemom agent: could not record this session in ~/.mnemom/${LEDGER_FILE} (${result.error}) — launching anyway.`));
@@ -559,7 +618,12 @@ function launchTerminal(ctx) {
         goalMode: ctx.goalMode ?? undefined,
         sessionConfigB64: ctx.sessionConfigB64,
     });
-    const args = buildCliArgs(ctx.options, { yolo: ctx.yolo, allowCliFlags: true });
+    const args = buildCliArgs(ctx.options, {
+        yolo: ctx.yolo,
+        allowCliFlags: true,
+        ccSessionId: ctx.ccSessionId,
+        handoffMcpConfigPath: ctx.handoffMcpConfigPath,
+    });
     // 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.
@@ -635,6 +699,16 @@ 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.
+    // 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.
+    proxy.stdin?.on("error", (err) => {
+        if (err.code === "EPIPE")
+            return;
+        say(`mnemom agent: could not hand the secrets to the Remote Control proxy: ${err.message}`);
+        onExit();
+        process.exit(1);
+    });
     proxy.stdin?.end(`${ctx.anthropicKey}\n\n\n`);
     let stdoutBuf = "";
     const start = Date.now();
@@ -712,6 +786,15 @@ function spawnRcCli(ctx) {
     childEnv.HTTPS_PROXY = `http://127.0.0.1:${ctx.port}`;
     childEnv.https_proxy = `http://127.0.0.1:${ctx.port}`;
     childEnv.NODE_EXTRA_CA_CERTS = ctx.ca;
+    // Context handoff (MNE-7564), RC shapes only: the strip list above deliberately removes every
+    // ANTHROPIC_* var, so the handoff MCP server has nothing to inherit for the key unless we give
+    // it something — a dedicated, non-ANTHROPIC-named var, added AFTER the strip loop so it can
+    // never collide with anything on that list. The RC gate above only inspects the recognized
+    // 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)
+        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
@@ -720,13 +803,23 @@ function spawnRcCli(ctx) {
         if (ctx.options.model)
             childEnv.ANTHROPIC_MODEL = ctx.options.model;
         args = ["remote-control", "--name", rcName, ...passthrough];
+        // Additive, never `--strict-mcp-config`: --trim-mcp is not applied under --server (every
+        // dispatched session keeps its full MCP set, unrestricted — see warnServerDrops below), so
+        // the handoff tool rides in on TOP of that set rather than replacing it.
+        if (ctx.handoffMcpConfigPath)
+            args.push("--mcp-config", ctx.handoffMcpConfigPath);
         say(`mnemom agent: remote-control: headless server (session name '${rcName}'); drive the sessions it spawns from claude.ai/code or the Claude app. Stop this command to stop the server.`);
     }
     else {
         // Interactive RC in THIS terminal: the CLI's own `--remote-control <name>`
         // startup flag; --model/--effort/--trim-mcp/yolo apply as in a normal launch.
         // buildCliArgs already includes the (name-stripped) passthrough.
-        const flagArgs = buildCliArgs(scopedOptions, { yolo: ctx.yolo, allowCliFlags: true });
+        const flagArgs = buildCliArgs(scopedOptions, {
+            yolo: ctx.yolo,
+            allowCliFlags: true,
+            ccSessionId: ctx.ccSessionId,
+            handoffMcpConfigPath: ctx.handoffMcpConfigPath,
+        });
         args = ["--remote-control", rcName, ...flagArgs];
         say(`mnemom agent: remote-control: interactive session in THIS terminal with Remote Control on (session name '${rcName}'); it also appears under Remote Control at claude.ai/code and in the Claude app. Exit the CLI to stop everything.`);
     }
@@ -763,6 +856,46 @@ function resolveProxyScript() {
     }
     return cand;
 }
+/**
+ * Locates the `handoff` MCP server (src/mcp/handoff-server.mjs in dev, dist/mcp/handoff-server.mjs
+ * once built — a raw, uncompiled `.mjs` file that `copy-assets.mjs` copies verbatim, exactly like
+ * `resolveProxyScript`'s `rc-proxy.mjs`, so the SAME relative path resolves in both trees).
+ *
+ * `baseDirOverride` exists ONLY so a test can exercise the missing-file throw deterministically
+ * (point it at a directory with no `../mcp/handoff-server.mjs` beside it) without touching the
+ * real installed tree; every real caller omits it and gets `import.meta.url`'s own directory.
+ */
+export function resolveHandoffServerScript(baseDirOverride) {
+    const here = baseDirOverride ?? dirname(fileURLToPath(import.meta.url));
+    const cand = join(here, "..", "mcp", "handoff-server.mjs");
+    if (!existsSync(cand)) {
+        throw new Error(`the handoff MCP server is missing (expected ${cand}). Reinstall the CLI.`);
+    }
+    return cand;
+}
+/**
+ * Writes the `--mcp-config` JSON (MNE-7564) to a fresh 0600 file in its own temp dir, referenced
+ * from argv only by PATH — never inlined, where `ps` could see it. For every launch shape this
+ * file carries NO key material at all — just the NAME of an env var the handoff server already
+ * inherits from its own parent (`HandoffAnthropicKeySource`): `ANTHROPIC_CUSTOM_HEADERS` for a
+ * terminal launch, or the dedicated `HANDOFF_RC_KEY_ENV_NAME` `spawnRcCli` sets for Remote
+ * Control. Still written 0600, since even the var name is worth protecting from a stray read.
+ * The dir is removed on process exit, same pattern as the Remote Control proxy's `rcDir` above.
+ */
+function writeHandoffMcpConfigFile(json) {
+    const dir = mkdtempSync(join(tmpdir(), "mnemom-code-handoff."));
+    const path = join(dir, "mcp-config.json");
+    writeFileSync(path, json, { mode: 0o600 });
+    process.on("exit", () => {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    });
+    return path;
+}
 function redactedProxyLog(logPath) {
     try {
         const text = readFileSync(logPath, "utf8").replace(/sk-ant-[A-Za-z0-9_-]+/g, "sk-ant-REDACTED");
@@ -779,9 +912,15 @@ function redactedProxyLog(logPath) {
 /**
  * Build the coding-agent CLI args from the model/effort/trim-mcp/yolo knobs plus
  * the caller's passthrough. `--model`/`--effort` are injected only when given (no
- * silent default). yolo appends `--dangerously-skip-permissions`. `--trim-mcp`
+ * silent default). yolo appends `--dangerously-skip-permissions`. A `ccSessionId`
+ * (pickCcSessionId, inject arm) appends `--session-id <id>`. `--trim-mcp`
  * appends `--strict-mcp-config --mcp-config {}` LAST so it wins over any
- * caller-supplied --mcp-config.
+ * caller-supplied --mcp-config — UNLESS `handoffMcpConfigPath` is set (context
+ * handoff ON, MNE-7564), in which case that file (which already declares only the
+ * `mnemom-handoff` server) is what `--strict-mcp-config` points at, so trimming
+ * strips every OTHER server but the handoff tool survives. Without `--trim-mcp`,
+ * the same path is passed WITHOUT `--strict-mcp-config` so it only ADDS the tool
+ * on top of the caller's/CLI's own MCP config rather than replacing it.
  */
 export function buildCliArgs(options, ctx) {
     const args = [];
@@ -792,14 +931,65 @@ export function buildCliArgs(options, ctx) {
             args.push("--effort", options.effort);
         if (ctx.yolo)
             args.push("--dangerously-skip-permissions");
+        if (ctx.ccSessionId)
+            args.push("--session-id", ctx.ccSessionId);
     }
     if (options.passthrough?.length)
         args.push(...options.passthrough);
-    if (ctx.allowCliFlags && options.trimMcp) {
-        args.push("--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}');
+    if (ctx.allowCliFlags) {
+        if (ctx.handoffMcpConfigPath) {
+            if (options.trimMcp)
+                args.push("--strict-mcp-config", "--mcp-config", ctx.handoffMcpConfigPath);
+            else
+                args.push("--mcp-config", ctx.handoffMcpConfigPath);
+        }
+        else if (options.trimMcp) {
+            args.push("--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}');
+        }
     }
     return args;
 }
+/**
+ * The Claude Code session id a launch runs under, from the caller's passthrough (implicit-goal
+ * CLI, cli-telemetry §1.5):
+ *   - `--session-id <uuid>` (or `=<uuid>`) → that id; the caller's own flag, nothing injected;
+ *   - `--fork-session` → null (Claude Code mints the fork's id);
+ *   - `--resume <id>` / `-r <id>` (or `--resume=<id>`) → that id, nothing injected;
+ *   - a bare `--resume` / `-r`, `--continue` / `-c` → null (Claude Code picks the session);
+ *   - otherwise → a fresh UUID the launcher injects as `--session-id`.
+ */
+export function pickCcSessionId(passthrough, newId = randomUUID) {
+    const valueOf = (flags) => {
+        for (let i = 0; i < passthrough.length; i++) {
+            const a = passthrough[i];
+            for (const f of flags) {
+                if (a === f) {
+                    const next = passthrough[i + 1];
+                    return next !== undefined && !next.startsWith("-") && next.trim() !== ""
+                        ? next.trim()
+                        : null;
+                }
+                if (a.startsWith(`${f}=`))
+                    return a.slice(f.length + 1).trim() || null;
+            }
+        }
+        return undefined; // flag absent
+    };
+    const explicit = valueOf(["--session-id"]);
+    if (explicit)
+        return { id: explicit, inject: false };
+    if (explicit === null)
+        return { id: null, inject: false }; // `--session-id` with no value: CC errors, add nothing
+    if (passthrough.includes("--fork-session"))
+        return { id: null, inject: false };
+    const resumed = valueOf(["--resume", "-r"]);
+    if (resumed)
+        return { id: resumed, inject: false };
+    if (resumed === null || passthrough.includes("--continue") || passthrough.includes("-c")) {
+        return { id: null, inject: false };
+    }
+    return { id: newId(), inject: true };
+}
 // ───────────────────────────────────────────────────────────────────────────
 // Context-hint seed (opt-out) — best-effort, never throws
 // ───────────────────────────────────────────────────────────────────────────