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

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";
@@ -38,7 +39,7 @@ import { fmt } from "../lib/format.js";
 import { askInput, askYesNo, isInteractive } from "../lib/prompt.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
 import { defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.js";
-import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildSessionConfigB64, resolveContextFold, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, resolveLaunchShape, resolveRemoteControlShape, sanitizeAgentName, } from "../lib/agent.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);
@@ -99,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;
@@ -145,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,
@@ -237,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,
@@ -248,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,
@@ -267,6 +313,8 @@ export async function agentCommand(scenarioArg, options = {}) {
             options,
             yolo,
             contextHint,
+            ccSessionId,
+            handoffMcpConfigPath,
         });
         return; // launchTerminal exits the process
     }
@@ -281,8 +329,10 @@ export async function agentCommand(scenarioArg, options = {}) {
         envelope,
         goalMode,
         sessionConfigB64,
+        handoffMcpConfigPath,
         options,
         yolo,
+        ccSessionId,
     });
 }
 // ───────────────────────────────────────────────────────────────────────────
@@ -315,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.`));
@@ -567,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.
@@ -643,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();
@@ -720,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
@@ -728,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.`);
     }
@@ -771,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");
@@ -787,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 = [];
@@ -800,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
 // ───────────────────────────────────────────────────────────────────────────

package/dist/index.js

@@ -11,6 +11,7 @@ import { policyInitCommand, policyValidateCommand, policyPublishCommand, policyL
 import { protectionShowCommand, protectionPublishCommand, protectionValidateCommand, protectionEditCommand, protectionDriftCommand, } from "./commands/protection.js";
 import { agentsListCommand, agentsClaimCommand, agentsMoveCommand } from "./commands/agents.js";
 import { agentSessionsCommand, agentShowCommand, liveSessionDeps, } from "./commands/agent-sessions.js";
+import { agentGoalPinCommand, agentGoalResetCommand, agentGoalShowCommand, liveGoalDeps, } from "./commands/agent-goal.js";
 import { orgListCommand, orgShowCommand, orgUseCommand } from "./commands/org.js";
 import { teamListCommand, teamShowCommand, teamTemplateCommand, teamPreviewComposeCommand, teamAdminGrantCommand, teamAdminRevokeCommand, teamAdminListCommand, teamCoverageCommand, } from "./commands/team.js";
 import { advisoriesListCommand, advisoriesShowCommand } from "./commands/advisories.js";
@@ -136,6 +137,8 @@ const agentCmd = program
     .option("--no-context-hint", "Do NOT seed Claude Code's context-hint feature flag before launch")
     .option("--context", "Force context folding ON for this launch even when launcher.toml (context = false) or MNEMOM_AGENT_CONTEXT turns it off")
     .option("--no-context", "Disable context folding for this launch (folding is on by default; tells the gateway to skip it for this session)")
+    .option("--context-handoff", "EXPERIMENTAL, off by default: register the `handoff(note)` MCP tool and tell the gateway to turn on the context-handoff capability for this session")
+    .option("--no-context-handoff", "Keep context handoff off for this launch even when launcher.toml (context_handoff = true) or MNEMOM_AGENT_CONTEXT_HANDOFF turns it on")
     .option("--dry-run", "Print the resolved launch plan and exit — no key read, no spawn")
     .action(async (scenario, passthrough, opts) => {
     try {
@@ -218,6 +221,7 @@ const agentCmd = program
             yolo: opts.yolo,
             contextHint: opts.contextHint,
             context: opts.context,
+            contextHandoff: opts.contextHandoff,
             setup: opts.setup,
             keySource: cfg.keySource,
             passthrough,
@@ -730,6 +734,69 @@ agentCmd
         process.exit(1);
     }
 });
+// `mnemom agent goal show|pin|reset` — the implicit goal the gateway inferred for a session
+// (implicit-goal CLI). The handlers set process.exitCode themselves (1 / 2); the catch is for
+// the unexpected.
+const agentGoalCmd = agentCmd
+    .command("goal")
+    .description("Read and steer the goal the gateway inferred for an implicit-mode session (show / pin / reset). " +
+    "Authenticates with the same key and agent the session launched with");
+const collectRepeat = (value, prev = []) => [...prev, value];
+agentGoalCmd
+    .command("show [ref]")
+    .description("Show the session's live inferred goal: revision, pin, statement, requirements, fences and the latest verdict. " +
+    "`ref` is a session name (newest match wins) or a unique conversation-id prefix; omitted = the newest session")
+    .option("--thread <id>", "Goal thread: main (default) or a thread id such as a.<agent-id>")
+    .option("--all-threads", "List every goal thread of the conversation (main + subagents)")
+    .option("--history", "Add the revision history table")
+    .option("--json", "Output the gateway body (source gateway) plus the ledger row (source ledger)")
+    .action(async (ref, opts) => {
+    try {
+        await agentGoalShowCommand(ref, opts, liveGoalDeps);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+agentGoalCmd
+    .command("pin [ref]")
+    .description("Pin the current inferred goal so new messages no longer revise it (--off unpins)")
+    .option("--thread <id>", "Goal thread: main (default) or a thread id such as a.<agent-id>")
+    .option("--off", "Unpin: new directions revise the goal again")
+    .option("--json", "Output the gateway body as JSON")
+    .action(async (ref, opts) => {
+    try {
+        await agentGoalPinCommand(ref, opts, liveGoalDeps);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+agentGoalCmd
+    .command("reset [ref]")
+    .description("Clear the inferred goal (the next message re-infers it), or replace it with --statement. " +
+    "Revisions keep counting up; spend and turn ceilings are never refunded")
+    .option("--thread <id>", "Goal thread: main (default) or a thread id such as a.<agent-id>")
+    .option("--statement <s>", "Replace the goal with this statement instead of clearing it")
+    .option("--requirement <r>", "A requirement for --statement (repeatable)", collectRepeat)
+    .option("--yes", "Skip the confirmation (required without a TTY)")
+    .option("--json", "Output the gateway body as JSON")
+    .action(async (ref, opts, cmd) => {
+    try {
+        // `mnemom agent` itself declares `--requirement` (a contract flag), and commander hands a
+        // parent's option to the parent wherever it appears, so the values land on `agent`.
+        // Read them from there when this command saw none.
+        const inherited = cmd.optsWithGlobals().requirement;
+        const requirement = opts.requirement ?? inherited;
+        await agentGoalResetCommand(ref, { ...opts, requirement }, liveGoalDeps);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 // ============================================================================
 // Organization management (ADR-044, Piece 1 of T1-3.1)
 // ============================================================================

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

@@ -55,6 +55,14 @@ export interface SessionRecord {
      * captured).
      */
     goal_mode?: GoalMode;
+    /**
+     * The Claude Code session id the launch pinned with `--session-id` (or the one the caller
+     * passed via `--session-id` / `--resume <id>`), so the ledger joins conversation_id ↔ the
+     * `x-claude-code-session-id` the gateway logs. `null` when Claude Code picks it (`--continue`,
+     * a bare `--resume`, `--fork-session`) or the shape hosts many sessions (`--server`). Optional:
+     * records written before this field existed omit it (still `v: 1`).
+     */
+    cc_session_id?: string | null;
 }
 /** Goal-alignment mode as recorded at launch. */
 export type GoalMode = "off" | "on" | "implicit";

package/dist/lib/agent.d.ts

@@ -76,6 +76,16 @@ export declare function resolveGatewayHost(env?: NodeJS.ProcessEnv): string;
 export declare function resolveAnthropicDoor(env?: NodeJS.ProcessEnv): string;
 /** True when the resolved gateway host is the us-2/prod cell (used for the launch banner). */
 export declare function isProdGateway(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The gateway origin the `handoff` MCP tool's own `POST /mnemom/context/handoff` must hit —
+ * always the SAME cell the launched session's own `/v1/messages` traffic goes to. Derived from
+ * the already-resolved Anthropic `door` (scheme+host only, via `new URL(...).origin`) rather
+ * than `resolveGatewayHost` directly, because `MNEMOM_AGENT_ANTHROPIC_GATEWAY` can override the
+ * door to a DIFFERENT host than `MNEMOM_AGENT_GATEWAY`/the default (e.g. a test cell) — reading
+ * `resolveGatewayHost` here would silently send handoff calls to prod (or vice versa) while the
+ * session's model traffic went elsewhere (MNE-7564 review).
+ */
+export declare function resolveHandoffGatewayHost(door: string): string;
 /**
  * Sanitise a header value into a safe wire token: lowercase, alphanumerics and
  * single hyphens only, no leading/trailing hyphen. Returns "" when nothing
@@ -135,6 +145,15 @@ export declare const GOAL_MODE_HEADER = "x-mnemom-goal-mode";
 export declare const SESSION_CONFIG_HEADER = "x-mnemom-session-config";
 /** The gateway env key that gates context folding (allow-listed for per-session overlay). */
 export declare const CONTEXT_RUNTIME_KEY = "CONTEXT_RUNTIME_ENABLED";
+/**
+ * The gateway env key that gates the whole context-handoff capability (level lines +
+ * `/mnemom/context/handoff` route + the digest note section) for a single session
+ * (MNE-7561..7565). Off by default on the gateway; turned on ONLY when this launch's
+ * `contextHandoff` setting is true (see `resolveContextHandoff`), which also registers the
+ * `handoff` MCP tool (MNE-7564) — a session never gets the tool without the header, or the
+ * header without the tool.
+ */
+export declare const CONTEXT_HANDOFF_KEY = "CONTEXT_HANDOFF_ENABLED";
 /**
  * The `x-mnemom-goal-mode` header value for `--implicit`, or null when the flag
  * is absent: `implicit[; max_turns=N][; budget_usd=X][; stall_turns=N]` — the
@@ -238,11 +257,95 @@ export declare function resolveContextFold(opts: {
     env?: NodeJS.ProcessEnv;
 }): boolean;
 /**
- * The `x-mnemom-session-config` value that turns context folding OFF, or
- * `undefined` when folding is ON (the default — nothing is sent, the gateway's
- * own default stands). base64url so it survives the gateway's inbound strip.
+ * The `x-mnemom-session-config` value for this launch, or `undefined` when there is
+ * nothing to override (the gateway's own defaults stand — the common case). Two
+ * independent overlays, both OFF by default (folding is ON by default so only its OFF
+ * state is ever sent; handoff is OFF by default so only its ON state is ever sent):
+ *   - `fold: false` → `CONTEXT_RUNTIME_ENABLED: "false"` (`--no-context`).
+ *   - `contextHandoff: true` → `CONTEXT_HANDOFF_ENABLED: "true"` (the `context_handoff`
+ *     setting) — the SAME header the `handoff` MCP tool's own call to
+ *     `/mnemom/context/handoff` must also send, since the gateway resolves the flag
+ *     per request (see `commands/agent.ts` handoff MCP wiring).
+ * base64url so it survives the gateway's inbound strip.
+ */
+export declare function buildSessionConfigB64(opts: {
+    fold: boolean;
+    contextHandoff: boolean;
+}): string | undefined;
+/**
+ * Is the `handoff` MCP tool + `CONTEXT_HANDOFF_ENABLED` session-config header ON for
+ * this launch? OFF by default (operator directive, curation 2026-09-25): an absent flag
+ * and an absent `context_handoff` setting are both "off", matching `resolveContextFold`'s
+ * shape but the opposite default. Precedence: an explicit `--context-handoff`/
+ * `--no-context-handoff` flag wins, else `MNEMOM_AGENT_CONTEXT_HANDOFF` (which
+ * `applyConfigToEnv` sets from the `context_handoff` config key), else OFF.
+ */
+export declare function resolveContextHandoff(opts: {
+    contextHandoff?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): boolean;
+/** The name the `handoff` MCP tool server is registered under in `--mcp-config`. */
+export declare const HANDOFF_MCP_SERVER_NAME = "mnemom-handoff";
+/**
+ * The name of the non-`ANTHROPIC_*` env var `spawnRcCli` (commands/agent.ts) adds to Claude
+ * Code's Remote Control child env, carrying the real Anthropic key, ONLY when context handoff is
+ * on. `spawnRcCli` strips every `ANTHROPIC_*` auth var (including `ANTHROPIC_CUSTOM_HEADERS`) so
+ * the RC gate sees a clean first-party-OAuth setup, but that gate only inspects the recognized
+ * `ANTHROPIC_*` base-url/key/socket family — a custom-named var rides through ungated, exactly
+ * like `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` already do for the proxy. The handoff server inherits
+ * it the same way it inherits `ANTHROPIC_CUSTOM_HEADERS` under the terminal shape.
  */
-export declare function buildSessionConfigB64(fold: boolean): string | undefined;
+export declare const HANDOFF_RC_KEY_ENV_NAME = "MNEMOM_HANDOFF_KEY";
+/**
+ * How the `handoff` MCP server (cli/src/mcp/handoff-server.mjs) recovers the Anthropic key
+ * WITHOUT it ever being written into the `--mcp-config` file on disk: `envName` is the NAME of a
+ * var already present in Claude Code's OWN process env, which every stdio MCP server inherits in
+ * full (verified experimentally for MNE-7564: a probe server registered via `--mcp-config`
+ * received vars set only in the parent `claude` process's env, unfiltered).
+ *   - Terminal shape: `{ envName: "ANTHROPIC_CUSTOM_HEADERS" }` — that var carries the real key
+ *     as its `x-api-key:` line (`buildCustomHeaders` above), so the server parses that line out
+ *     of its own inherited env at request time.
+ *   - Remote Control (both `--remote-control` and `--server`): `{ envName:
+ *     HANDOFF_RC_KEY_ENV_NAME }` — `spawnRcCli` sets that var directly (see above) since RC's
+ *     child env carries the key nowhere else (it rides the local proxy's stdin instead, deleted
+ *     from Claude Code's own env by the strip list).
+ * There is deliberately no embedded-value ("rawKey") variant: every launch shape has an
+ * inherited-env channel, so the config file never needs to carry the key itself.
+ */
+export interface HandoffAnthropicKeySource {
+    envName: string;
+}
+/**
+ * The env vars the launcher hands the `handoff` MCP server so it can call
+ * `POST /mnemom/context/handoff` with the SAME identity + session config the launched
+ * coding-agent session's own `/v1/messages` requests carry. No secret rides in this object or
+ * the config file it produces, but the file is still written to a 0600 path and passed to
+ * `--mcp-config` as a PATH, never inlined into argv (see `commands/agent.ts`
+ * `writeHandoffMcpConfigFile`), since even an env-var NAME is worth protecting from a stray read.
+ */
+export interface HandoffMcpParams {
+    /** The gateway ORIGIN (e.g. https://gateway.mnemom.ai) — see `resolveHandoffGatewayHost`. */
+    gatewayHost: string;
+    anthropicKeySource: HandoffAnthropicKeySource;
+    agent: string;
+    conversationId: string;
+    /** `buildSessionConfigB64` output — forwarded so the route resolves the SAME per-session flag. */
+    sessionConfigB64?: string;
+    /** Absolute path to the compiled server entry point (`resolveHandoffServerScript`). */
+    serverScript: string;
+    /** The node executable to run it with (the launcher's own `process.execPath`). */
+    nodeBin: string;
+}
+/** The `--mcp-config` document registering exactly the `handoff` tool. Pure — no I/O. */
+export declare function buildHandoffMcpConfig(p: HandoffMcpParams): {
+    mcpServers: Record<string, {
+        command: string;
+        args: string[];
+        env: Record<string, string>;
+    }>;
+};
+/** `JSON.stringify(buildHandoffMcpConfig(p))` — the exact bytes written to the config file. */
+export declare function buildHandoffMcpConfigJson(p: HandoffMcpParams): string;
 /**
  * The persistable goal-alignment default (`launcher.toml` `goal_mode`). Only the
  * two statement-free modes can be a standing default: a SEALED contract needs a