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

package/dist/commands/agent-slack.js

@@ -0,0 +1,212 @@
+/**
+ * `mnemom agent slack …` — let governed sessions talk in Slack, each under its
+ * own session name, through ONE Slack app per operator (see lib/slack.ts).
+ *
+ *   mnemom agent slack manifest [app-name]   # print the app manifest to paste at api.slack.com
+ *   mnemom agent slack login                 # store the bot + app-level tokens (0600)
+ *   mnemom agent slack logout                # remove them
+ *   mnemom agent slack status                # tokens, bot identity, router, live sessions
+ *   mnemom agent slack post [--channel C] [--thread TS] [--icon-emoji E] <text…|->
+ *   mnemom agent slack inbox [--peek]        # unread messages addressed to THIS session
+ *   mnemom agent slack listen                # this session's channel server (spawned by --slack)
+ *   mnemom agent slack router                # the per-operator Socket Mode router (foreground)
+ *
+ * The poster name is MNEMOM_AGENT_SESSION_NAME, which the launcher sets in the
+ * session's environment — an agent cannot pick another session's name here.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
+import { runChannelServer } from "../lib/slack-channel.js";
+import { mergeStore, readStore } from "../lib/launcher-store.js";
+import { askInput, isInteractive } from "../lib/prompt.js";
+import { explainSlackError, looksLikeAppToken, looksLikeBotToken, postMessage, resolveSlackToken, sessionPosterName, slackAppManifest, slackCall, SLACK_APP_TOKEN_STORE_KEY, SLACK_TOKEN_STORE_KEY, } from "../lib/slack.js";
+import { routerStatus, runRouter } from "../lib/slack-router.js";
+import { normSession } from "../lib/slack-route.js";
+import { liveSessions, readInboxFrom, recordPost, slackDir } from "../lib/slack-state.js";
+const out = (line = "") => console.log(line);
+/** Entry point for `mnemom agent slack <verb> [args...]`. Throws on misuse. */
+export async function agentSlackCommand(argv) {
+    const [verb, ...rest] = argv;
+    switch (verb) {
+        case "manifest":
+            // The manifest holds scope NAMES, never a credential; written to stdout (not logged)
+            // so it can be piped straight into Slack's "create from manifest" box.
+            process.stdout.write(JSON.stringify(slackAppManifest(rest.join(" ") || defaultAppName()), null, 2) + "\n");
+            return;
+        case "login":
+            return login();
+        case "logout":
+            mergeStore({ [SLACK_TOKEN_STORE_KEY]: null, [SLACK_APP_TOKEN_STORE_KEY]: null });
+            out("mnemom agent slack: tokens removed from ~/.mnemom/launcher.json.");
+            return;
+        case undefined:
+        case "status":
+            return status();
+        case "post":
+            return post(rest);
+        case "inbox":
+            return inbox(rest);
+        case "router":
+            return router();
+        case "listen":
+            return listen();
+        default:
+            throw new Error(`mnemom agent slack: unknown verb '${verb}'. Use manifest | login | logout | status | post | inbox | listen | router.`);
+    }
+}
+function defaultAppName() {
+    const user = (process.env.USER ?? "").replace(/[^A-Za-z0-9-]/g, "");
+    return user ? `${user}-agents` : "mnemom-agents";
+}
+function botToken() {
+    const { token } = resolveSlackToken(process.env, readStore(), "bot");
+    if (!token) {
+        throw new Error("mnemom agent slack: no bot token — run `mnemom agent slack login` (or set MNEMOM_SLACK_BOT_TOKEN).");
+    }
+    return token;
+}
+async function login() {
+    if (!isInteractive()) {
+        throw new Error("mnemom agent slack login: needs a terminal (tokens are read masked, never from argv).");
+    }
+    const bot = (await askInput("Bot User OAuth Token (xoxb-…): ", true)).trim();
+    if (!looksLikeBotToken(bot))
+        throw new Error("that is not a bot token (expected xoxb-…).");
+    const auth = await slackCall("auth.test", bot, {});
+    if (!auth.ok)
+        throw new Error(explainSlackError(auth.error));
+    const app = (await askInput("App-Level Token with connections:write (xapp-…, Enter to skip): ", true)).trim();
+    if (app && !looksLikeAppToken(app))
+        throw new Error("that is not an app-level token (expected xapp-…).");
+    mergeStore({
+        [SLACK_TOKEN_STORE_KEY]: bot,
+        ...(app ? { [SLACK_APP_TOKEN_STORE_KEY]: app } : {}),
+    });
+    const cfg = loadLauncherConfig();
+    if (!cfg.slackAllow?.length) {
+        const me = (await askInput("Your Slack member ID — only allowlisted members can reach a session (U…): ")).trim();
+        if (me) {
+            configKeySpec("slack_allow")?.set(cfg, me);
+            writeLauncherConfig(cfg);
+        }
+    }
+    out(`mnemom agent slack: saved. Bot ${String(auth.user)} in ${String(auth.team)}.`);
+    if (!app)
+        out("  (No app-level token: sessions can post, but cannot receive replies until you add one.)");
+    out("  Invite the bot to a channel with /invite @" + String(auth.user) + " before posting there.");
+}
+async function status() {
+    const store = readStore();
+    const bot = resolveSlackToken(process.env, store, "bot");
+    const app = resolveSlackToken(process.env, store, "app");
+    out(`bot token:      ${bot.source ?? "not set"}`);
+    out(`app token:      ${app.source ?? "not set"}`);
+    if (bot.token) {
+        const a = await slackCall("auth.test", bot.token, {}).catch((e) => ({
+            ok: false,
+            error: e.message,
+        }));
+        out(`bot identity:   ${a.ok ? `${String(a.user)} @ ${String(a.team)}` : explainSlackError(a.error)}`);
+    }
+    out(`default channel: ${loadLauncherConfig().slackChannel ?? "(none — pass --channel)"}`);
+    out(`this session:   ${sessionPosterName(process.env) ?? "(not inside a `mnemom agent` session)"}`);
+    const r = routerStatus();
+    out(`router:         ${r.running ? `running (pid ${r.pid})` : "not running"}`);
+    const live = liveSessions();
+    out(`listening:      ${live.length ? live.join(", ") : "none"}`);
+    const allow = loadLauncherConfig().slackAllow ?? [];
+    out(`allowed senders: ${allow.length ? allow.join(", ") : "none — no message will reach a session"}`);
+}
+export function parsePostArgs(argv) {
+    const res = { text: "" };
+    const words = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const val = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error(`mnemom agent slack post: ${a} needs a value.`);
+            return v;
+        };
+        if (a === "--channel" || a === "-c")
+            res.channel = val();
+        else if (a === "--thread" || a === "-t")
+            res.thread = val();
+        else if (a === "--icon-emoji")
+            res.iconEmoji = val();
+        else if (a === "--") {
+            words.push(...argv.slice(i + 1));
+            break;
+        }
+        else
+            words.push(a);
+    }
+    res.text = words.join(" ");
+    return res;
+}
+async function post(argv) {
+    const args = parsePostArgs(argv);
+    let text = args.text;
+    if (text === "-" || (!text && !process.stdin.isTTY))
+        text = readFileSync(0, "utf8");
+    text = text.trim();
+    if (!text)
+        throw new Error("mnemom agent slack post: nothing to post.");
+    const channel = args.channel ?? loadLauncherConfig().slackChannel;
+    if (!channel) {
+        throw new Error("mnemom agent slack post: no channel — pass --channel or `mnemom agent config set slack_channel <#name>`.");
+    }
+    const session = sessionPosterName(process.env);
+    const res = await postMessage({
+        token: botToken(),
+        channel,
+        text,
+        username: session,
+        iconEmoji: args.iconEmoji,
+        threadTs: args.thread,
+    });
+    if (session)
+        recordPost({ session, channel: res.channel, ts: res.ts, thread_ts: args.thread });
+    out(JSON.stringify({ ok: true, channel: res.channel, ts: res.ts, as: session ?? null }));
+}
+// ── inbox (pull) ─────────────────────────────────────────────────────────────
+// Normalised like the inbox file name, so a session name can never escape offsets/.
+const offsetFile = (session) => join(slackDir(), "offsets", `${normSession(session)}.off`);
+function readOffset(session) {
+    try {
+        return Number(readFileSync(offsetFile(session), "utf8")) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Print (and, unless --peek, consume) the messages routed to this session. */
+async function inbox(argv) {
+    const session = sessionPosterName(process.env);
+    if (!session)
+        throw new Error("mnemom agent slack inbox: not inside a `mnemom agent` session.");
+    const { messages, offset } = readInboxFrom(session, readOffset(session));
+    if (!argv.includes("--peek")) {
+        mkdirSync(join(slackDir(), "offsets"), { recursive: true, mode: 0o700 });
+        writeFileSync(offsetFile(session), String(offset), { mode: 0o600 });
+    }
+    out(JSON.stringify(messages));
+}
+async function router() {
+    const store = readStore();
+    const app = resolveSlackToken(process.env, store, "app").token;
+    if (!app)
+        throw new Error("mnemom agent slack router: no app-level token — run `mnemom agent slack login`.");
+    await runRouter({
+        botToken: botToken(),
+        appToken: app,
+        allow: loadLauncherConfig().slackAllow ?? [],
+    });
+}
+async function listen() {
+    const session = sessionPosterName(process.env);
+    if (!session)
+        throw new Error("mnemom agent slack listen: not inside a `mnemom agent` session.");
+    await runChannelServer({ session, botToken: botToken() });
+}

package/dist/commands/agent.d.ts

@@ -60,6 +60,14 @@ export interface AgentOptions {
     context?: boolean;
     /** context-hint seed default: commander `--no-context-hint` sets this false. */
     contextHint?: boolean;
+    /** Attach the Slack channel server (`--slack`; lib/slack-launch.ts). */
+    slack?: 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 +106,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 +163,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

@@ -26,7 +26,8 @@
  * an argv value.
  */
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, renameSync, } from "node:fs";
+import { existsSync, 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,9 +39,11 @@ 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, passthroughName, sanitizeAgentName, sessionDisplayName, SESSION_NAME_ENV, } 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. */
-const CODE_STORE = join(MNEMOM_DIR, "launcher.json");
+const CODE_STORE = LAUNCHER_STORE_PATH;
 const say = (line = "") => console.error(line);
 /** Entry point for `mnemom agent [scenario]`. Throws on fatal misconfig. */
 export async function agentCommand(scenarioArg, options = {}) {
@@ -99,7 +102,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 +149,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 +244,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,18 +259,56 @@ 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,
             door,
             anthropicKey,
             agent,
+            scenario,
             conversationId,
             envelope,
             goalMode,
@@ -267,6 +316,8 @@ export async function agentCommand(scenarioArg, options = {}) {
             options,
             yolo,
             contextHint,
+            ccSessionId,
+            handoffMcpConfigPath,
         });
         return; // launchTerminal exits the process
     }
@@ -281,8 +332,10 @@ export async function agentCommand(scenarioArg, options = {}) {
         envelope,
         goalMode,
         sessionConfigB64,
+        handoffMcpConfigPath,
         options,
         yolo,
+        ccSessionId,
     });
 }
 // ───────────────────────────────────────────────────────────────────────────
@@ -315,6 +368,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.`));
@@ -394,13 +448,10 @@ function readStoredKey() {
         return undefined;
     }
 }
-/** Persist the provider key to ~/.mnemom/launcher.json at 0600 (atomic). Best-effort. */
+/** Persist the provider key to ~/.mnemom/launcher.json at 0600 (atomic, merged). Best-effort. */
 function storeKey(key) {
     try {
-        mkdirSync(MNEMOM_DIR, { recursive: true });
-        const tmp = join(MNEMOM_DIR, `.code-tmp-${process.pid}-${Date.now()}.json`);
-        writeFileSync(tmp, JSON.stringify({ anthropic_key: key }, null, 2), { mode: 0o600 });
-        renameSync(tmp, CODE_STORE);
+        mergeStore({ anthropic_key: key }, CODE_STORE);
     }
     catch {
         // best effort — the launch proceeds with the in-memory key either way
@@ -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.
@@ -576,6 +632,10 @@ function launchTerminal(ctx) {
     childEnv.ANTHROPIC_BASE_URL = ctx.door;
     childEnv.ANTHROPIC_AUTH_TOKEN = "mnemom-gateway";
     childEnv.ANTHROPIC_CUSTOM_HEADERS = headers;
+    const sessionName = passthroughName(ctx.options.passthrough ?? []) ?? sessionDisplayName(ctx.agent, ctx.scenario);
+    childEnv[SESSION_NAME_ENV] = sessionName;
+    if (ctx.options.slack)
+        args.push(...slackChannelArgs(sessionName));
     if (ctx.contextHint) {
         seedContextHintFlag(childEnv);
         childEnv.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
@@ -643,6 +703,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();
@@ -686,7 +756,7 @@ function spawnRcCli(ctx) {
     // Session name for the claude.ai session list: "<agent>-<scenario>", unless
     // the caller passed their own `--name <x>` after `--` (lifted out here).
     const rawPassthrough = ctx.options.passthrough ?? [];
-    let rcName = sanitizeAgentName(`${ctx.agent}-${ctx.scenario}`) || ctx.agent;
+    let rcName = sessionDisplayName(ctx.agent, ctx.scenario);
     const passthrough = [];
     for (let i = 0; i < rawPassthrough.length; i++) {
         if (rawPassthrough[i] === "--name" && i + 1 < rawPassthrough.length) {
@@ -720,6 +790,16 @@ 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;
+    childEnv[SESSION_NAME_ENV] = rcName;
+    // 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
@@ -727,15 +807,30 @@ function spawnRcCli(ctx) {
         warnServerDrops(ctx.options, ctx.yolo);
         if (ctx.options.model)
             childEnv.ANTHROPIC_MODEL = ctx.options.model;
+        if (ctx.options.slack) {
+            say("mnemom agent: --slack is not applied to a headless server (a channel server needs an interactive confirmation); use the terminal or remote-control shape.");
+        }
         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];
+        if (ctx.options.slack)
+            args.push(...slackChannelArgs(rcName));
         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.`);
     }
     const child = spawn(ctx.cli.bin, args, { stdio: "inherit", env: childEnv });
@@ -771,6 +866,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 +922,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 +941,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
 // ───────────────────────────────────────────────────────────────────────────