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

package/dist/base-url-proxy.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// mnemom-agent-base-url-proxy — the local proxy behind a TERMINAL `mnemom agent --implicit` launch.
+//
+// Claude Code's ANTHROPIC_BASE_URL points here (http://127.0.0.1:<port>); every request is
+// forwarded unchanged to the Mnemom gateway door, with ONE addition: on a `POST /v1/messages`
+// that Claude Code marks `x-claude-code-request-class: main`, the `x-mnemom-turn` header built
+// from Claude Code's own transcript (turn-origin.mjs). That lets the gateway tell the user's typed
+// words from cron ticks, skill bodies, hook text, channel relays and peer messages.
+//
+// AUTH IS PASSED THROUGH, NEVER HELD. An API-key launch carries its key in ANTHROPIC_CUSTOM_HEADERS
+// (x-api-key) and a subscription launch carries Claude Code's own claude.ai bearer; both arrive as
+// request headers and leave the same way. This proxy reads no secret, stores none, logs none.
+//
+// FAIL-OPEN. The turn header is best effort: no prompt id, no transcript, a late transcript entry
+// (> WAIT_MS) → the request is forwarded without it (the gateway then behaves as before).
+//
+// CONFIG (env, none secret)
+//   MNEMOM_AGENT_BU_DOOR         gateway door URL (required, https only), e.g. https://gateway.mnemom.ai/anthropic
+//   MNEMOM_AGENT_BU_CWD          the session cwd (Claude Code's transcript lives under its slug)
+//   MNEMOM_AGENT_BU_LOG          append log lines here instead of stderr (optional)
+//   MNEMOM_AGENT_BU_PARENT_PID   exit when this pid is gone
+//   MNEMOM_AGENT_BU_PORT         listen port (default 0 = ephemeral)
+//   MNEMOM_AGENT_TURN_HEADER     0/off disables the turn header (the proxy still forwards)
+//   CLAUDE_CONFIG_DIR            Claude Code's home (default ~/.claude)
+//
+// stdout: exactly one line, `READY <port>`, once listening. Node >= 18, no deps.
+import http from "node:http";
+import https from "node:https";
+import fs from "node:fs";
+import { TURN_HEADER, TurnOrigins, turnHeaderEnabled, turnHeaderFor } from "./turn-origin.mjs";
+
+const env = process.env;
+function die(msg) {
+  process.stderr.write(`mnemom-agent-base-url-proxy: ${msg}\n`);
+  process.exit(2);
+}
+
+let DOOR;
+try {
+  DOOR = new URL(env.MNEMOM_AGENT_BU_DOOR || "");
+} catch {
+  die("MNEMOM_AGENT_BU_DOOR is required and must be a URL");
+}
+if (DOOR.protocol !== "https:") die("MNEMOM_AGENT_BU_DOOR must be https");
+const LOGFILE = env.MNEMOM_AGENT_BU_LOG || "";
+const PARENT = Number(env.MNEMOM_AGENT_BU_PARENT_PID || 0);
+const PORT = Number(env.MNEMOM_AGENT_BU_PORT || 0);
+const TURNS = turnHeaderEnabled(env)
+  ? new TurnOrigins({ cwd: env.MNEMOM_AGENT_BU_CWD || process.cwd() })
+  : null;
+
+const log = (line) => {
+  const s = `${new Date().toISOString()} ${String(line).replace(/[\r\n]+/g, " ")}\n`;
+  if (LOGFILE) {
+    try {
+      fs.appendFileSync(LOGFILE, s);
+      return;
+    } catch {
+      /* fall through */
+    }
+  }
+  process.stderr.write(s);
+};
+
+const HOP = new Set([
+  "connection",
+  "proxy-connection",
+  "keep-alive",
+  "upgrade",
+  "host",
+  "te",
+  "trailer",
+  "transfer-encoding",
+]);
+const agent = new https.Agent({ keepAlive: true, maxSockets: 32 });
+const doorPath = DOOR.pathname.replace(/\/$/, "");
+const isMessages = (u) => u === "/v1/messages" || u.startsWith("/v1/messages?");
+
+function handle(req, res) {
+  const started = Date.now();
+  const headers = {};
+  for (const [k, v] of Object.entries(req.headers)) if (!HOP.has(k)) headers[k] = v;
+  // A client-supplied x-mnemom-turn never passes: only this proxy states turn origins.
+  delete headers["x-mnemom-turn"];
+
+  // Origin-form only: the path is appended to the door's origin, so nothing in it can name a host.
+  if (!req.url.startsWith("/")) {
+    log(`${req.method} (not origin-form) -> local 400`);
+    res.writeHead(400, { "content-type": "text/plain" });
+    res.end("mnemom local proxy: origin-form request path required\n");
+    return;
+  }
+  const tag = `${req.method} ${req.url.split("?")[0]}`;
+
+  const forward = (note) => {
+    const target = new URL(DOOR.origin + doorPath + req.url);
+    const up = https.request(target, { method: req.method, headers, agent }, (ur) => {
+      res.writeHead(ur.statusCode, ur.headers);
+      ur.pipe(res);
+      ur.on("end", () => log(`${tag} -> ${ur.statusCode} ${Date.now() - started}ms${note}`));
+      // The door dropped the connection mid-response (headers already sent): cut the client off too,
+      // so Claude Code sees a broken stream and retries. Unhandled, this error would kill the proxy.
+      ur.on("error", (e) => {
+        log(`${tag} -> ${ur.statusCode} ABORTED ${e.message}`);
+        res.destroy();
+      });
+    });
+    up.on("error", (e) => {
+      log(`${tag} -> ERROR ${e.message}`);
+      res.writeHead(502, { "content-type": "application/json" });
+      res.end(
+        JSON.stringify({
+          type: "error",
+          error: { type: "api_error", message: `mnemom local proxy: ${e.message}` },
+        }),
+      );
+    });
+    // The client went away mid-response: stop the upstream call too.
+    res.on("close", () => {
+      if (!res.writableFinished) up.destroy();
+    });
+    req.pipe(up);
+  };
+
+  if (TURNS && req.method === "POST" && isMessages(req.url)) {
+    // Never rejects (turnHeaderFor): a transcript problem only means no header.
+    turnHeaderFor(TURNS, headers).then((t) => {
+      if (t.value) headers[TURN_HEADER] = t.value;
+      forward(` turn=${t.note}`);
+    });
+  } else {
+    forward("");
+  }
+}
+
+const server = http.createServer(handle);
+server.listen(PORT, "127.0.0.1", () => {
+  const { port } = server.address();
+  log(`listening 127.0.0.1:${port} door=${DOOR.href} turn_header=${TURNS ? "on" : "off"}`);
+  process.stdout.write(`READY ${port}\n`);
+});
+
+// SIGINT is ignored: the proxy shares the terminal's process group with Claude Code, and a Ctrl-C
+// meant for Claude Code must not take the session's route down. It exits with the launcher.
+process.on("SIGINT", () => {});
+for (const sig of ["SIGTERM", "SIGHUP"]) process.on(sig, () => process.exit(0));
+if (PARENT)
+  setInterval(() => {
+    try {
+      process.kill(PARENT, 0);
+    } catch {
+      process.exit(0);
+    }
+  }, 2000).unref();

package/dist/commands/agent-first-run.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Wiring for the `mnemom agent` first-run look (lib/first-run): the opt-in offer on the
+ * first interactive launch, and `mnemom agent --first-run` to show it again.
+ *
+ * The look is local and read-only: no network call, transcripts never leave the machine.
+ * It never blocks a launch — a failure prints one note and the launch goes on.
+ */
+import { computeFirstRun, type FirstRunDeps } from "../lib/first-run/index.js";
+/** Set to 1 to never be offered the first-run look (scripts, shared machines). */
+export declare const NO_FIRST_RUN_ENV = "MNEMOM_AGENT_NO_FIRST_RUN";
+/**
+ * Ask one question; resolve the line, or null on EOF (Ctrl-D closes the stream without
+ * ever calling readline's question callback, which would otherwise hang the launch).
+ */
+export declare function askLine(question: string, input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<string | null>;
+/** The real I/O behind defaultFirstRunDeps; tests swap pieces. */
+export interface FirstRunIo {
+    tty: boolean;
+    writeErr: (s: string) => void;
+    compute: typeof computeFirstRun;
+    /** The prompt's streams (default: the terminal). */
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+}
+export declare function defaultFirstRunDeps(env?: NodeJS.ProcessEnv, io?: Partial<FirstRunIo>): FirstRunDeps;
+/** Is the first-launch offer allowed at all for this launch? */
+export declare function firstRunOfferAllowed(opts: {
+    dryRun?: boolean;
+}, env: NodeJS.ProcessEnv): boolean;
+/** Called before a real launch: offers once, records the answer, shows on yes. */
+export declare function offerFirstRunOnLaunch(opts: {
+    dryRun?: boolean;
+}, env?: NodeJS.ProcessEnv, deps?: FirstRunDeps): Promise<string>;
+/** `mnemom agent --first-run`: show the look again, no prompt, no launch. */
+export declare function agentFirstRunCommand(deps?: FirstRunDeps): void;

package/dist/commands/agent-first-run.js

@@ -0,0 +1,78 @@
+/**
+ * Wiring for the `mnemom agent` first-run look (lib/first-run): the opt-in offer on the
+ * first interactive launch, and `mnemom agent --first-run` to show it again.
+ *
+ * The look is local and read-only: no network call, transcripts never leave the machine.
+ * It never blocks a launch — a failure prints one note and the launch goes on.
+ */
+import { MNEMOM_DIR } from "../lib/config.js";
+import { resolveRetentionDays } from "../lib/agent-ledger.js";
+import { loadCliConfig } from "../lib/cli-config.js";
+import { launchPreflighted } from "../lib/agent.js";
+import { createInterface } from "node:readline";
+import { isInteractive } from "../lib/prompt.js";
+import { computeFirstRun, maybeOfferFirstRun, showFirstRun, } from "../lib/first-run/index.js";
+/** Set to 1 to never be offered the first-run look (scripts, shared machines). */
+export const NO_FIRST_RUN_ENV = "MNEMOM_AGENT_NO_FIRST_RUN";
+/**
+ * Ask one question; resolve the line, or null on EOF (Ctrl-D closes the stream without
+ * ever calling readline's question callback, which would otherwise hang the launch).
+ */
+export function askLine(question, input = process.stdin, output = process.stdout) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input, output });
+        let done = false;
+        const finish = (v) => {
+            if (done)
+                return;
+            done = true;
+            rl.close();
+            resolve(v);
+        };
+        rl.on("close", () => finish(null));
+        rl.question(`${question} `, (ans) => finish(ans));
+    });
+}
+export function defaultFirstRunDeps(env = process.env, io = {}) {
+    const tty = io.tty ?? process.stderr.isTTY === true;
+    const writeErr = io.writeErr ?? ((s) => void process.stderr.write(s));
+    const compute = io.compute ?? computeFirstRun;
+    return {
+        mnemomDir: MNEMOM_DIR,
+        interactive: isInteractive(),
+        ask: (q) => askLine(q, io.input, io.output),
+        print: (line) => process.stdout.write(`${line}\n`),
+        note: (line) => console.error(line),
+        now: () => new Date(),
+        compute: () => {
+            const res = compute({
+                retentionDays: resolveRetentionDays(loadCliConfig().sessions?.retentionDays, env),
+                progress: (m) => {
+                    if (tty)
+                        writeErr(`\r  mnemom: ${m}`.padEnd(78).slice(0, 78));
+                },
+            });
+            if (tty)
+                writeErr(`\r${" ".repeat(78)}\r`);
+            return res;
+        },
+    };
+}
+/** Is the first-launch offer allowed at all for this launch? */
+export function firstRunOfferAllowed(opts, env) {
+    if (opts.dryRun)
+        return false;
+    if (launchPreflighted(env))
+        return false; // an orchestrator's launch, not a person's
+    return env[NO_FIRST_RUN_ENV] !== "1";
+}
+/** Called before a real launch: offers once, records the answer, shows on yes. */
+export async function offerFirstRunOnLaunch(opts, env = process.env, deps = defaultFirstRunDeps(env)) {
+    if (!firstRunOfferAllowed(opts, env))
+        return "skipped";
+    return maybeOfferFirstRun(deps);
+}
+/** `mnemom agent --first-run`: show the look again, no prompt, no launch. */
+export function agentFirstRunCommand(deps = defaultFirstRunDeps()) {
+    showFirstRun(deps);
+}

package/dist/commands/agent.d.ts

@@ -212,6 +212,30 @@ export interface RcCapability {
  * and by the auto-default selection (a bare launch prefers RC when capable).
  */
 export declare function checkRcCapability(cli: ResolvedCli): RcCapability;
+/**
+ * Add 127.0.0.1 and localhost to BOTH NO_PROXY and no_proxy (proxy clients disagree on which one
+ * wins, and some read only the lowercase one), keeping whatever each already listed.
+ */
+export declare function exemptLoopbackFromProxy(env: NodeJS.ProcessEnv): void;
+/** Whether a terminal implicit launch runs the turn-origin proxy (MNEMOM_AGENT_TURN_HEADER=0 opts out). */
+export declare function turnProxyWanted(env: NodeJS.ProcessEnv): boolean;
+/** Test seams for startBaseUrlProxy (every real caller omits them). */
+export interface BaseUrlProxyOptions {
+    /** The proxy script (default: the bundled base-url-proxy.mjs beside rc-proxy.mjs). */
+    script?: string;
+    /** The node binary (default: this process's own). */
+    node?: string;
+    /** How long to wait for READY before launching straight to the door (default 5 s). */
+    readyTimeoutMs?: number;
+}
+/**
+ * Start base-url-proxy.mjs in front of `door`; calls `done` exactly once with its
+ * `http://127.0.0.1:<port>` base URL, or with null (after a one-line warning) when it does not
+ * report READY in time or exits first — the launch then goes straight to the door. A missing
+ * script is the same case (node exits 1 before READY). The proxy holds no secret (auth headers
+ * pass through it), exits with this process, and is killed on exit.
+ */
+export declare function startBaseUrlProxy(door: string, done: (baseUrl: string | null) => void, opts?: BaseUrlProxyOptions): void;
 /**
  * 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

package/dist/commands/agent.js

@@ -43,7 +43,7 @@ import { askInput, askSelect, askYesNo, isInteractive } from "../lib/prompt.js";
 import { authConfigured, chooseAuth, detectClaudeLogin, readClaudeLoginState, } from "../lib/login-detect.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
 import { AgentIdentityMismatchError, defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.js";
-import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, sessionDisplayName, GATEWAY_HINT_HEADERS_ENV, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
+import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, sessionDisplayName, GATEWAY_HINT_HEADERS_ENV, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
 import { LAUNCHER_STORE_PATH, mergeStore } from "../lib/launcher-store.js";
 import { slackChannelArgs } from "../lib/slack-launch.js";
 /** The CLI's own provider-key store (zero 1Password): ~/.mnemom/launcher.json, 0600. */
@@ -345,6 +345,25 @@ export async function agentCommand(scenarioArg, options = {}) {
     // 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;
+    // ── 1M context window by default ── the model this launch runs on gets `[1m]` when it has no
+    // window suffix and supports 1M (resolveWindowModel); an explicit choice — the
+    // CLAUDE_CODE_DISABLE_1M_CONTEXT opt-out, a passthrough `-- --model`, a suffixed id — is kept.
+    // Claude Code only: it is the adapter that reads the window off the model id.
+    const win = cli.name === "claude"
+        ? resolveWindowModel({
+            explicit: options.model,
+            passthrough: options.passthrough ?? [],
+            env: process.env,
+            settings: () => readCcSettings({
+                cwd: process.cwd(),
+                configDir: (process.env.CLAUDE_CONFIG_DIR ?? "").trim() || join(homedir(), ".claude"),
+            }),
+        })
+        : null;
+    const launchOptions = win?.reason === "one-m" ? { ...options, model: win.model } : options;
+    if (win?.reason === "one-m") {
+        say(`mnemom agent: model ${win.from} → ${win.model} (1M context window; set ${DISABLE_1M_ENV}=1, or pass the model as \`-- --model <id>\`, to keep the standard window).`);
+    }
     await recordSessionLaunch({
         session: scenario,
         conversationId,
@@ -352,7 +371,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         account,
         gatewayHost,
         shape,
-        options,
+        options: launchOptions,
         cli,
         envelope,
         goalMode,
@@ -412,7 +431,7 @@ export async function agentCommand(scenarioArg, options = {}) {
             envelope,
             goalMode,
             sessionConfigB64,
-            options,
+            options: launchOptions,
             yolo,
             contextHint,
             ccSessionId,
@@ -433,7 +452,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         goalMode,
         sessionConfigB64,
         handoffMcpConfigPath,
-        options,
+        options: launchOptions,
         yolo,
         ccSessionId,
     });
@@ -520,7 +539,13 @@ export async function recordSessionLaunch(ctx) {
         org_label: ctx.account.orgLabel,
         gateway_host: ctx.gatewayHost,
         launch_shape: ctx.shape,
-        model: ctx.options.model?.trim() || null,
+        // What the launch runs on — `--model`, else a passthrough `-- --model`, else the inherited
+        // ANTHROPIC_MODEL — verbatim, so a `[1m]` (1M-window) launch reads as one in the ledger.
+        model: resolveLaunchModel({
+            explicit: ctx.options.model,
+            passthrough: ctx.options.passthrough ?? [],
+            env: process.env,
+        }).model,
         effort: ctx.options.effort?.trim() || null,
         cli: ctx.cli.name,
         contract: toLedgerContract(ctx.envelope?.contract ?? null),
@@ -825,6 +850,9 @@ function launchTerminal(ctx) {
     else {
         childEnv = subscriptionChildEnv(process.env, ctx.door, headers);
     }
+    // Both auth arms point ANTHROPIC_BASE_URL at the gateway door, which makes Claude Code turn
+    // tool search off and inline every tool schema on every request — unless told otherwise.
+    applyToolSearchDefault(childEnv);
     const sessionName = passthroughName(ctx.options.passthrough ?? []) ?? sessionDisplayName(ctx.agent, ctx.scenario);
     childEnv[SESSION_NAME_ENV] = sessionName;
     childEnv[GATEWAY_HINT_HEADERS_ENV] = "1";
@@ -835,17 +863,101 @@ function launchTerminal(ctx) {
         childEnv.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
         childEnv.CLAUDE_CODE_GB_DISK_CACHE_WHEN_TELEMETRY_OFF = "1";
     }
-    const child = spawn(ctx.cli.bin, args, { stdio: "inherit", env: childEnv });
-    child.on("error", (err) => {
-        say(`mnemom agent: failed to launch ${ctx.cli.name}: ${err.message}`);
-        process.exit(1);
+    const run = () => {
+        const child = spawn(ctx.cli.bin, args, { stdio: "inherit", env: childEnv });
+        child.on("error", (err) => {
+            say(`mnemom agent: failed to launch ${ctx.cli.name}: ${err.message}`);
+            process.exit(1);
+        });
+        child.on("exit", (code, signal) => {
+            if (signal)
+                process.kill(process.pid, signal);
+            else
+                process.exit(code ?? 0);
+        });
+    };
+    // Implicit goal mode: put the local base-URL proxy in front of the door so each main request
+    // carries x-mnemom-turn (where each recent user turn came from, read from Claude Code's own
+    // transcript — base-url-proxy.mjs / turn-origin.mjs). The prompt id it joins on comes from the
+    // gateway hint headers set above. Fail-open: no proxy → the door directly, as before.
+    if (!ctx.goalMode || !turnProxyWanted(process.env)) {
+        run();
+        return;
+    }
+    startBaseUrlProxy(ctx.door, (baseUrl) => {
+        if (baseUrl) {
+            childEnv.ANTHROPIC_BASE_URL = baseUrl;
+            // An inherited HTTPS_PROXY must not carry the loopback hop.
+            exemptLoopbackFromProxy(childEnv);
+        }
+        run();
     });
-    child.on("exit", (code, signal) => {
-        if (signal)
-            process.kill(process.pid, signal);
-        else
-            process.exit(code ?? 0);
+}
+/**
+ * Add 127.0.0.1 and localhost to BOTH NO_PROXY and no_proxy (proxy clients disagree on which one
+ * wins, and some read only the lowercase one), keeping whatever each already listed.
+ */
+export function exemptLoopbackFromProxy(env) {
+    const upper = env.NO_PROXY ?? env.no_proxy ?? "";
+    const lower = env.no_proxy ?? env.NO_PROXY ?? "";
+    env.NO_PROXY = [upper, "127.0.0.1,localhost"].filter(Boolean).join(",");
+    env.no_proxy = [lower, "127.0.0.1,localhost"].filter(Boolean).join(",");
+}
+/** Whether a terminal implicit launch runs the turn-origin proxy (MNEMOM_AGENT_TURN_HEADER=0 opts out). */
+export function turnProxyWanted(env) {
+    const raw = (env.MNEMOM_AGENT_TURN_HEADER ?? "").trim().toLowerCase();
+    return !["0", "off", "false", "no"].includes(raw);
+}
+/**
+ * Start base-url-proxy.mjs in front of `door`; calls `done` exactly once with its
+ * `http://127.0.0.1:<port>` base URL, or with null (after a one-line warning) when it does not
+ * report READY in time or exits first — the launch then goes straight to the door. A missing
+ * script is the same case (node exits 1 before READY). The proxy holds no secret (auth headers
+ * pass through it), exits with this process, and is killed on exit.
+ */
+export function startBaseUrlProxy(door, done, opts = {}) {
+    const script = opts.script ?? join(dirname(fileURLToPath(import.meta.url)), "..", "base-url-proxy.mjs");
+    // The log carries method / path / status / latency / turn note only (never a header value or body).
+    const logDir = mkdtempSync(join(tmpdir(), "mnemom-turn-proxy."));
+    const proxy = spawn(opts.node ?? process.execPath, [script], {
+        env: {
+            ...process.env,
+            MNEMOM_AGENT_BU_DOOR: door,
+            MNEMOM_AGENT_BU_CWD: process.cwd(),
+            MNEMOM_AGENT_BU_LOG: process.env.MNEMOM_AGENT_TURN_PROXY_LOG || join(logDir, "proxy.log"),
+            MNEMOM_AGENT_BU_PARENT_PID: String(process.pid),
+        },
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    process.on("exit", () => {
+        proxy.kill("SIGTERM"); // a no-op returning false when it is already gone
+        rmSync(logDir, { recursive: true, force: true });
+    });
+    // The first of READY / timeout / exit decides; a later event (the proxy exiting at the end of the
+    // session, after READY) must not call `done` again.
+    let finished = false;
+    const finish = (url, why) => {
+        if (finished)
+            return;
+        finished = true;
+        clearTimeout(timer);
+        if (!url) {
+            say(fmt.warn(`mnemom agent: turn-origin proxy unavailable (${why}) — launching straight to the gateway; the gateway reads turn origins from the wire only.`));
+        }
+        done(url);
+    };
+    const timeoutMs = opts.readyTimeoutMs ?? 5000;
+    const timer = setTimeout(() => finish(null, `no READY within ${timeoutMs}ms`), timeoutMs);
+    let buf = "";
+    proxy.stdout?.on("data", (c) => {
+        buf += c.toString("utf8");
+        const m = buf.match(/^READY (\d+)$/m);
+        if (m)
+            finish(`http://127.0.0.1:${m[1]}`, "ready");
     });
+    proxy.on("exit", (code) => finish(null, `exited ${code ?? "by signal"} before READY`));
+    // Unhandled, a spawn failure (EAGAIN, a missing binary) would throw out of the launcher.
+    proxy.on("error", (err) => finish(null, err.message));
 }
 // ───────────────────────────────────────────────────────────────────────────
 // Remote Control launch (terminal RC + headless server) — behind the bundled proxy
@@ -987,6 +1099,10 @@ function spawnRcCli(ctx) {
     childEnv.https_proxy = `http://127.0.0.1:${ctx.port}`;
     childEnv.NODE_EXTRA_CA_CERTS = ctx.ca;
     childEnv[SESSION_NAME_ENV] = rcName;
+    // Under RC Claude Code sees a first-party host (the proxy, not ANTHROPIC_BASE_URL, routes to the
+    // gateway), so tool search is already on by default; setting it anyway keeps every launch shape
+    // on the same switch. A user value is kept.
+    applyToolSearchDefault(childEnv);
     // 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

package/dist/index.js

@@ -28,6 +28,7 @@ import { agentSlackCommand } from "./commands/agent-slack.js";
 import { agentDoctorCommand } from "./commands/agent-doctor.js";
 import { agentSetupCommand } from "./commands/agent-setup.js";
 import { agentInviteCommand, runAgentInvocation } from "./commands/agent-invite.js";
+import { agentFirstRunCommand, offerFirstRunOnLaunch } from "./commands/agent-first-run.js";
 import { applyConfigToEnv, launcherEntries, loadLauncherConfig, withoutDisabledExperimental, } from "./lib/launcher-config.js";
 import { loadExperimentalState } from "./lib/cli-config.js";
 import { assertEnabled, EXPERIMENTAL_CONTRACT, gateCheck, ignoredSettingLines, reportCliError, } from "./lib/experimental.js";
@@ -173,6 +174,7 @@ const agentCmd = program
     .addOption(new Option("--context-handoff", "EXPERIMENTAL (`mnemom experimental enable context-handoff`): register the `handoff(note)` MCP tool and tell the gateway to turn on the context-handoff capability for this session").hideHelp(hiddenUnless("context-handoff")))
     .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")
+    .option("--first-run", "Show the first-run look again: what Mnemom would have saved on your last 30 days of Claude Code (runs on this machine, read-only, nothing uploaded) — then exit")
     .action(async (scenario, passthrough, opts) => {
     try {
         // Invitation redemption — `mnemom agent invite <token>` (sub-verb) or
@@ -235,6 +237,11 @@ const agentCmd = program
         applyConfigToEnv(cfg, process.env);
         // Sub-verb: `mnemom agent doctor` runs a read-only preflight and never
         // launches. Placed after config load so it reports the effective settings.
+        // `mnemom agent --first-run`: show the first-run look again and never launch.
+        if (opts.firstRun) {
+            agentFirstRunCommand();
+            return;
+        }
         if (scenario === "doctor") {
             await agentDoctorCommand({ cli: opts.cli });
             return;
@@ -265,6 +272,9 @@ const agentCmd = program
         // shadows a subcommand `--agent` under commander@12 — the MNE-238 class),
         // exactly as status/logs/onboard read it.
         const parentOpts = program.opts();
+        // First interactive launch only: offer (opt-in) the local look at what Mnemom
+        // would have saved. Tracked in ~/.mnemom/first-run.json; never blocks the launch.
+        await offerFirstRunOnLaunch({ dryRun: opts.dryRun });
         await agentCommand(scenario, {
             goal: opts.goal,
             requirement: opts.requirement,