@mnemom/mnemom 0.16.1 → 0.17.0-next.0

package/dist/commands/code.js

@@ -0,0 +1,661 @@
+/**
+ * `mnemom code <scenario>` — the CLI's first-class governed-coding-agent launcher.
+ *
+ * Launches your coding-agent CLI (Claude Code in v1) with its dev-time model
+ * traffic routed through the Mnemom gateway's /anthropic door for observability +
+ * governance, under a governed agent identity and an optional per-conversation
+ * CONTRACT the gateway seals on the first turn.
+ *
+ * v1 scope:
+ *   - The Claude Code launch adapter (Anthropic /anthropic door; Anthropic-only,
+ *     no router door / Mnemom key). `--cli` selects the executable to run (name or
+ *     full path) so codex/cursor/github adapters can be added later.
+ *   - The us-2/PROD gateway is the DEFAULT door (https://gateway.mnemom.ai); an
+ *     explicit MNEMOM_CODE_GATEWAY / --gateway still wins, never silently prod.
+ *   - Three launch shapes: `terminal` (DEFAULT), `remote-control` (interactive RC
+ *     in this terminal), `server` (headless RC dispatcher). RC runs the CLI
+ *     UNTOUCHED behind a bundled local TLS proxy (rc-proxy.mjs) — Claude Code
+ *     gates RC on a first-party claude.ai-OAuth setup, so the gateway door cannot
+ *     be wired via env there.
+ *   - yolo (`--dangerously-skip-permissions`) is ON by default; `--no-yolo` opts out.
+ *
+ * The Anthropic key is resolved from a credential source with ZERO 1Password
+ * dependency (env → the CLI's own ~/.mnemom/code.json store → interactive
+ * prompt) and placed ONLY in the launched process (an `ANTHROPIC_CUSTOM_HEADERS`
+ * line, or the proxy's stdin under RC). It is never logged, printed, or passed as
+ * an argv value.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, renameSync, } from "node:fs";
+import { tmpdir, homedir } from "node:os";
+import { basename, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { MNEMOM_DIR } from "../lib/config.js";
+import { fmt } from "../lib/format.js";
+import { askInput, askYesNo, isInteractive } from "../lib/prompt.js";
+import { defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, MuInsufficientError, } from "./code-setup.js";
+import { assembleContract, buildCustomHeaders, isProdGateway, launchPreferenceExplicit, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, resolveLaunchShape, sanitizeAgentName, } from "../lib/code.js";
+/** The CLI's own provider-key store (zero 1Password): ~/.mnemom/code.json, 0600. */
+const CODE_STORE = join(MNEMOM_DIR, "code.json");
+const say = (line = "") => console.error(line);
+/** Entry point for `mnemom code <scenario>`. Throws on fatal misconfig. */
+export async function codeCommand(scenario, options = {}) {
+    if (!scenario || !scenario.trim()) {
+        throw new Error("mnemom code: a <scenario> slug is required (e.g. `mnemom code onboarding`).");
+    }
+    const env = process.env;
+    let shape = resolveLaunchShape({ remoteControl: options.remoteControl, server: options.server }, env);
+    const shapeExplicit = launchPreferenceExplicit({ remoteControl: options.remoteControl, server: options.server }, env);
+    // ── governed identity ── (default: per-customer `code-<handle>`, not a shared
+    // "code-agent" — see defaultAgentSlug; provisioning claims exactly this slug.
+    // `let` because a brand-new user who signs in during the pre-launch gate below
+    // gets their real handle re-derived once the session exists.)
+    let agent = sanitizeAgentName(options.agent?.trim() || defaultAgentSlug());
+    if (!agent) {
+        throw new Error("mnemom code: --agent sanitised to an empty string — pick a value with at least one letter or digit.");
+    }
+    const conversationId = resolveConversationId(options.conversationId);
+    // ── contract (built only if a contract flag was given; --goal then required) ──
+    const envelope = assembleContract({
+        goal: options.goal,
+        requirement: options.requirement,
+        allow: options.allow,
+        forbid: options.forbid,
+        goalId: options.goalId,
+        budget: options.budget,
+        maxTurns: options.maxTurns,
+        stall: options.stall,
+    });
+    // ── door ──
+    const gatewayHost = resolveGatewayHost(env);
+    const door = resolveAnthropicDoor(env);
+    const cellNote = isProdGateway(env) ? "us-2/prod" : `custom (${gatewayHost})`;
+    const yolo = options.yolo !== false; // default ON
+    const contextHint = options.contextHint !== false; // default ON
+    // ── which CLI executable (name or full path) ──
+    const cli = resolveCliBin(options.cli, env);
+    // ── default launch shape: prefer Remote-Control-in-terminal (the good default
+    // — one session steerable from this terminal AND claude.ai/the app) when the
+    // machine can do it; otherwise fall back to terminal-only with a clear notice.
+    // An explicit choice (flag / env / config launch=) is always respected. ──
+    if (!shapeExplicit && shape === "terminal") {
+        const rc = checkRcCapability(cli);
+        if (rc.ok) {
+            shape = "remote-control";
+        }
+        else {
+            say(`mnemom code: launching terminal-only (Remote Control unavailable: ${rc.missing.join("; ")}).`);
+            say("mnemom code: once those are in place, `mnemom code <scenario> --remote-control` (or `config set launch remote-control`) gives you a session steerable from claude.ai and the Claude app too.");
+        }
+    }
+    if (options.dryRun) {
+        printPlan({ scenario, shape, agent, conversationId, door, cellNote, envelope, yolo, cli });
+        return;
+    }
+    // ── resolve the Anthropic key (zero 1Password; never logged) ──
+    const anthropicKey = await resolveAnthropicKey(env, {
+        allowPrompt: true,
+        keySource: options.keySource,
+    });
+    // ── account + Mnemom Units gate (no free tier) ──────────────────────────────
+    // mnemom code runs governed and on Mnemom Units, so before we seal a contract
+    // or launch we (1) ensure a Mnemom session — offering the try-me-style sign-in
+    // / sign-up when there isn't one — and (2) enforce a positive MU balance on the
+    // org the agent lives in (default: the user's personal org). No MUs ⇒ blocked
+    // with a portal-style top-up message. Skipped only on --dry-run (handled above).
+    try {
+        await ensureSessionAndBalance({ interactive: isInteractive() });
+    }
+    catch (err) {
+        if (err instanceof MuInsufficientError)
+            process.exit(1); // top-up message already printed
+        throw err;
+    }
+    // Now that a session exists, a defaulted slug can use the real login handle
+    // (a first-ever run computed it before sign-in, when only "code-user" was known).
+    if (!options.agent?.trim()) {
+        const refreshed = sanitizeAgentName(defaultAgentSlug());
+        if (refreshed)
+            agent = refreshed;
+    }
+    // ── zero-friction governed agent: make sure `agent` exists + is claimed in the
+    // customer's org (with the nudge/nudge coding posture) before we launch. AUTO
+    // provisions-with-confirm when interactive; warns and continues otherwise.
+    // Skipped entirely by `--no-setup`. A provisioning failure never blocks the
+    // launch — it degrades to the unclaimed (fail-open) identity with a warning.
+    if (options.setup !== false) {
+        try {
+            await ensureGovernedAgent({
+                slug: agent,
+                anthropicKey,
+                setup: options.setup,
+                gatewayHost,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            say(fmt.warn(`mnemom code: agent setup did not complete (${msg}) — launching with the unclaimed identity.`));
+        }
+    }
+    logLaunch({ shape, door, agent, conversationId, cellNote, envelope, cli });
+    if (shape === "terminal") {
+        launchTerminal({
+            cli,
+            door,
+            anthropicKey,
+            agent,
+            conversationId,
+            envelope,
+            options,
+            yolo,
+            contextHint,
+        });
+        return; // launchTerminal exits the process
+    }
+    launchRemoteControl({
+        shape,
+        cli,
+        door,
+        anthropicKey,
+        agent,
+        conversationId,
+        scenario,
+        envelope,
+        options,
+        yolo,
+    });
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Credential resolution (zero 1Password)
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Resolve the Anthropic key with NO 1Password dependency (built for external
+ * customer adoption), in order:
+ *   1. env: MNEMOM_CODE_ANTHROPIC_KEY, else ANTHROPIC_API_KEY
+ *   2. the CLI's own store: ~/.mnemom/code.json (`anthropic_key`)
+ *   3. interactive prompt (masked), offering to save it to the store
+ * Never logged / printed. Throws with guidance when nothing resolves — we refuse
+ * to launch un-routed.
+ */
+export async function resolveAnthropicKey(env, opts) {
+    const source = opts.keySource;
+    // "prompt" forces the interactive prompt (skips env + store).
+    if (source !== "prompt") {
+        const fromEnv = (env.MNEMOM_CODE_ANTHROPIC_KEY || env.ANTHROPIC_API_KEY || "").trim();
+        if (fromEnv)
+            return fromEnv;
+        // "env" restricts to env only — no store, no prompt.
+        if (source === "env") {
+            throw new Error("mnemom code: key_source is 'env' but no Anthropic key is set.\n" +
+                "  Set one:   export MNEMOM_CODE_ANTHROPIC_KEY=sk-ant-...   (or ANTHROPIC_API_KEY)");
+        }
+        const stored = readStoredKey();
+        if (stored)
+            return stored;
+    }
+    // (source can only be "store", "prompt", or undefined here — "env" threw above.)
+    if (opts.allowPrompt && isInteractive()) {
+        say("mnemom code: no Anthropic key in env (MNEMOM_CODE_ANTHROPIC_KEY / ANTHROPIC_API_KEY) or ~/.mnemom/code.json.");
+        const entered = (await askInput("Enter your Anthropic API key (sk-ant-…):", true)).trim();
+        if (entered) {
+            if (await askYesNo("Save it to ~/.mnemom/code.json (0600) for next time?", true)) {
+                storeKey(entered);
+                say("mnemom code: saved to ~/.mnemom/code.json.");
+            }
+            return entered;
+        }
+    }
+    throw new Error("mnemom code: no Anthropic key found — refusing to launch un-routed.\n" +
+        "  Set one:   export MNEMOM_CODE_ANTHROPIC_KEY=sk-ant-...   (or ANTHROPIC_API_KEY)\n" +
+        "  Or save it: run `mnemom code` interactively and accept the save prompt\n" +
+        "  (stored 0600 at ~/.mnemom/code.json).");
+}
+/**
+ * Where an Anthropic key would resolve from RIGHT NOW, without reading its value:
+ * "env" (MNEMOM_CODE_ANTHROPIC_KEY / ANTHROPIC_API_KEY), "store" (~/.mnemom/code.json),
+ * or null (would fall to the interactive prompt). For `mnemom code doctor`.
+ */
+export function anthropicKeySource(env = process.env) {
+    if ((env.MNEMOM_CODE_ANTHROPIC_KEY || env.ANTHROPIC_API_KEY || "").trim())
+        return "env";
+    if (readStoredKey())
+        return "store";
+    return null;
+}
+/** Read the stored provider key, or undefined. Best-effort, never throws. */
+function readStoredKey() {
+    try {
+        const data = JSON.parse(readFileSync(CODE_STORE, "utf8"));
+        const key = typeof data.anthropic_key === "string" ? data.anthropic_key.trim() : "";
+        return key || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Persist the provider key to ~/.mnemom/code.json at 0600 (atomic). 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);
+    }
+    catch {
+        // best effort — the launch proceeds with the in-memory key either way
+    }
+}
+/**
+ * Resolve which coding-agent CLI to launch. `--cli` (or MNEMOM_CODE_CLI) is a
+ * name or a full path; default "claude". A value with a path separator is used
+ * verbatim (must exist); a bare name is resolved on PATH, then — for claude — the
+ * fnm/nvm/asdf install dirs (a version-manager shim / shell function is absent in
+ * the fresh shell that runs the launch). v1 wires only the Claude Code adapter;
+ * a non-claude executable is launched through it with a warning.
+ */
+export function resolveCliBin(cliOpt, env) {
+    const requested = (cliOpt || env.MNEMOM_CODE_CLI || "claude").trim();
+    const name = basename(requested);
+    if (requested.includes("/")) {
+        if (existsSync(requested))
+            return { bin: requested, name };
+        throw new Error(`mnemom code: --cli path '${requested}' not found.`);
+    }
+    for (const dir of (env.PATH || "").split(":")) {
+        const cand = join(dir || ".", requested);
+        if (existsSync(cand))
+            return { bin: cand, name };
+    }
+    if (name === "claude") {
+        const home = homedir();
+        const bases = [
+            join(home, ".local/share/fnm/node-versions"),
+            join(home, ".nvm/versions/node"),
+            join(home, ".asdf/installs/nodejs"),
+        ];
+        for (const base of bases) {
+            if (!existsSync(base))
+                continue;
+            try {
+                for (const v of readdirSync(base)) {
+                    const cand = base.includes("fnm")
+                        ? join(base, v, "installation/bin/claude")
+                        : join(base, v, "bin/claude");
+                    if (existsSync(cand))
+                        return { bin: cand, name };
+                }
+            }
+            catch {
+                // best effort
+            }
+        }
+    }
+    throw new Error(`mnemom code: coding-agent CLI '${requested}' not found.\n` +
+        "  Looked on $PATH" +
+        (name === "claude" ? " and in the fnm/nvm/asdf node dirs" : "") +
+        ".\n  Pass --cli <name|/full/path> or set MNEMOM_CODE_CLI.");
+}
+export function commandExists(cmd) {
+    const res = spawnSync("sh", ["-c", `command -v "$1" >/dev/null 2>&1`, "sh", cmd], {
+        stdio: "ignore",
+    });
+    return res.status === 0;
+}
+/**
+ * Does the resolved coding-agent CLI advertise the `--remote-control` startup
+ * flag (Claude Code >= 2.1.269)? Determined by scanning its `--help`. Best-effort:
+ * a spawn failure or timeout reads as "no". Only the claude adapter wires RC.
+ */
+export function cliSupportsRemoteControl(bin) {
+    try {
+        const res = spawnSync(bin, ["--help"], { encoding: "utf8", timeout: 10_000 });
+        const text = `${res.stdout ?? ""}${res.stderr ?? ""}`;
+        return /--remote-control/.test(text);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Can we launch the DEFAULT Remote-Control-in-terminal shape on this machine?
+ * Needs node + openssl (the local proxy mints an ephemeral CA) and a claude
+ * adapter that advertises `--remote-control`. Used both by `mnemom code doctor`
+ * and by the auto-default selection (a bare launch prefers RC when capable).
+ */
+export function checkRcCapability(cli) {
+    const missing = [];
+    if (cli.name !== "claude") {
+        missing.push(`Remote Control is wired only for the Claude Code adapter (got '${cli.name}')`);
+        return { ok: false, missing };
+    }
+    if (!commandExists("node"))
+        missing.push("node is not on PATH");
+    if (!commandExists("openssl"))
+        missing.push("openssl is not on PATH");
+    if (!cliSupportsRemoteControl(cli.bin)) {
+        missing.push("this claude build has no --remote-control flag (needs Claude Code >= 2.1.269)");
+    }
+    return { ok: missing.length === 0, missing };
+}
+/** Warn once when a non-claude executable rides the v1 Claude Code adapter. */
+function warnAdapter(cli) {
+    if (cli.name !== "claude") {
+        say(`mnemom code: only the Claude Code adapter is wired in v1 — launching '${cli.name}' with the Anthropic gateway env. codex/cursor/github adapters are coming.`);
+    }
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Terminal-only launch (the default shape)
+// ───────────────────────────────────────────────────────────────────────────
+function launchTerminal(ctx) {
+    warnAdapter(ctx.cli);
+    const headers = buildCustomHeaders({
+        anthropicKey: ctx.anthropicKey,
+        agent: ctx.agent,
+        conversationId: ctx.conversationId,
+        contractB64: ctx.envelope?.base64,
+    });
+    const args = buildCliArgs(ctx.options, { yolo: ctx.yolo, allowCliFlags: true });
+    // 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.
+    const childEnv = { ...process.env };
+    delete childEnv.ANTHROPIC_API_KEY;
+    childEnv.ANTHROPIC_BASE_URL = ctx.door;
+    childEnv.ANTHROPIC_AUTH_TOKEN = "mnemom-gateway";
+    childEnv.ANTHROPIC_CUSTOM_HEADERS = headers;
+    if (ctx.contextHint) {
+        seedContextHintFlag(childEnv);
+        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 code: 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);
+    });
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Remote Control launch (terminal RC + headless server) — behind the bundled proxy
+// ───────────────────────────────────────────────────────────────────────────
+function launchRemoteControl(ctx) {
+    warnAdapter(ctx.cli);
+    for (const tool of ["node", "openssl"]) {
+        if (!commandExists(tool)) {
+            throw new Error(`mnemom code: --remote-control needs '${tool}' on PATH (the local proxy is a Node script that mints an ephemeral CA with openssl).`);
+        }
+    }
+    const proxyScript = resolveProxyScript();
+    const rcDir = mkdtempSync(join(tmpdir(), "mnemom-code-rc."));
+    const proxyLog = process.env.MNEMOM_CODE_RC_PROXY_LOG || join(rcDir, "proxy.log");
+    const proxy = spawn("node", [proxyScript], {
+        env: {
+            ...process.env,
+            MNEMOM_CODE_RC_DOOR: ctx.door,
+            MNEMOM_CODE_RC_AGENT: ctx.agent,
+            MNEMOM_CODE_RC_CONVERSATION_ID: ctx.conversationId,
+            MNEMOM_CODE_RC_CONTRACT_B64: ctx.envelope?.base64 ?? "",
+            MNEMOM_CODE_RC_PROXY_LOG: proxyLog,
+            MNEMOM_CODE_RC_PARENT_PID: String(process.pid),
+        },
+        stdio: ["pipe", "pipe", "inherit"],
+    });
+    let stopped = false;
+    const onExit = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        if (!proxy.killed) {
+            try {
+                proxy.kill("SIGTERM");
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        try {
+            rmSync(rcDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    };
+    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.
+    proxy.stdin?.end(`${ctx.anthropicKey}\n\n\n`);
+    let stdoutBuf = "";
+    const start = Date.now();
+    const tryStart = () => {
+        const m = stdoutBuf.match(/^READY (\d+) (.+)$/m);
+        if (m) {
+            const port = m[1];
+            const ca = m[2].trim();
+            if (!existsSync(ca)) {
+                say("mnemom code: malformed READY line from the Remote Control proxy.");
+                onExit();
+                process.exit(1);
+            }
+            spawnRcCli({ ...ctx, port, ca, onExit });
+            return;
+        }
+        if (proxy.exitCode !== null) {
+            say("mnemom code: the Remote Control proxy exited before it was ready — refusing to launch un-routed.");
+            redactedProxyLog(proxyLog);
+            onExit();
+            process.exit(1);
+        }
+        if (Date.now() - start > 15_000) {
+            say("mnemom code: the Remote Control proxy did not report READY within 15s.");
+            onExit();
+            process.exit(1);
+        }
+        setTimeout(tryStart, 200);
+    };
+    proxy.stdout?.on("data", (chunk) => {
+        stdoutBuf += chunk.toString("utf8");
+    });
+    proxy.on("error", (err) => {
+        say(`mnemom code: failed to launch the Remote Control proxy: ${err.message}`);
+        onExit();
+        process.exit(1);
+    });
+    tryStart();
+}
+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;
+    const passthrough = [];
+    for (let i = 0; i < rawPassthrough.length; i++) {
+        if (rawPassthrough[i] === "--name" && i + 1 < rawPassthrough.length) {
+            rcName = rawPassthrough[i + 1];
+            i++; // consume the value
+            continue;
+        }
+        passthrough.push(rawPassthrough[i]);
+    }
+    const scopedOptions = { ...ctx.options, passthrough };
+    // Every auth-shaped ANTHROPIC_* var is UNSET so the RC gate sees a first-party
+    // OAuth setup; NO_PROXY/HTTP_PROXY unset so api.anthropic.com is not excluded.
+    // Built by FILTERING rather than deleting.
+    const strip = new Set([
+        "ANTHROPIC_API_KEY",
+        "ANTHROPIC_AUTH_TOKEN",
+        "ANTHROPIC_BASE_URL",
+        "ANTHROPIC_CUSTOM_HEADERS",
+        "CLAUDE_CODE_OAUTH_TOKEN",
+        "ANTHROPIC_UNIX_SOCKET",
+        "NO_PROXY",
+        "no_proxy",
+        "HTTP_PROXY",
+        "http_proxy",
+    ]);
+    const childEnv = {};
+    for (const [k, v] of Object.entries(process.env)) {
+        if (!strip.has(k))
+            childEnv[k] = v;
+    }
+    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;
+    let args;
+    if (ctx.shape === "server") {
+        // Headless dispatcher: no --model/--effort/--trim-mcp/yolo flags; the model
+        // rides in ANTHROPIC_MODEL. effort/trim-mcp/yolo are not applied (warned).
+        warnServerDrops(ctx.options, ctx.yolo);
+        if (ctx.options.model)
+            childEnv.ANTHROPIC_MODEL = ctx.options.model;
+        args = ["remote-control", "--name", rcName, ...passthrough];
+        say(`mnemom code: 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 });
+        args = ["--remote-control", rcName, ...flagArgs];
+        say(`mnemom code: 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 });
+    child.on("error", (err) => {
+        say(`mnemom code: failed to launch ${ctx.cli.name} under Remote Control: ${err.message}`);
+        ctx.onExit();
+        process.exit(1);
+    });
+    child.on("exit", (code, signal) => {
+        ctx.onExit();
+        if (signal)
+            process.kill(process.pid, signal);
+        else
+            process.exit(code ?? 0);
+    });
+}
+function warnServerDrops(options, yolo) {
+    if (options.effort) {
+        say("mnemom code: --effort is not applied under --server (set it from the session instead).");
+    }
+    if (options.trimMcp) {
+        say("mnemom code: --trim-mcp is not applied under --server (sessions load the full MCP set).");
+    }
+    if (yolo) {
+        say("mnemom code: yolo (--dangerously-skip-permissions) is not applied under --server; set permissions from the driven sessions.");
+    }
+}
+function resolveProxyScript() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const cand = join(here, "..", "rc-proxy.mjs");
+    if (!existsSync(cand)) {
+        throw new Error(`mnemom code: the Remote Control proxy is missing (expected ${cand}). Reinstall the CLI.`);
+    }
+    return cand;
+}
+function redactedProxyLog(logPath) {
+    try {
+        const text = readFileSync(logPath, "utf8").replace(/sk-ant-[A-Za-z0-9_-]+/g, "sk-ant-REDACTED");
+        say("Proxy log:");
+        say(text);
+    }
+    catch {
+        /* nothing to show */
+    }
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Shared CLI-arg building
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * 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`
+ * appends `--strict-mcp-config --mcp-config {}` LAST so it wins over any
+ * caller-supplied --mcp-config.
+ */
+export function buildCliArgs(options, ctx) {
+    const args = [];
+    if (ctx.allowCliFlags) {
+        if (options.model)
+            args.push("--model", options.model);
+        if (options.effort)
+            args.push("--effort", options.effort);
+        if (ctx.yolo)
+            args.push("--dangerously-skip-permissions");
+    }
+    if (options.passthrough?.length)
+        args.push(...options.passthrough);
+    if (ctx.allowCliFlags && options.trimMcp) {
+        args.push("--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}');
+    }
+    return args;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Context-hint seed (opt-out) — best-effort, never throws
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Set cachedGrowthBookFeatures.tengu_hazel_osprey = true in the local Claude
+ * Code config (${CLAUDE_CONFIG_DIR:-$HOME}/.claude.json) so the client offers the
+ * gateway's context-hint protocol. Never creates or damages the file: skipped
+ * silently if it is missing or does not parse as a JSON object. Idempotent; every
+ * other key preserved; the write is atomic (temp + rename).
+ */
+function seedContextHintFlag(childEnv) {
+    try {
+        const cfgDir = childEnv.CLAUDE_CONFIG_DIR || homedir();
+        const cfgFile = join(cfgDir, ".claude.json");
+        if (!existsSync(cfgFile))
+            return;
+        const data = JSON.parse(readFileSync(cfgFile, "utf8"));
+        if (!data || typeof data !== "object" || Array.isArray(data))
+            return;
+        let features = data.cachedGrowthBookFeatures;
+        if (!features || typeof features !== "object" || Array.isArray(features)) {
+            features = {};
+            data.cachedGrowthBookFeatures = features;
+        }
+        if (features.tengu_hazel_osprey === true)
+            return; // already set
+        features.tengu_hazel_osprey = true;
+        const tmp = join(cfgDir, `.mnemom-code-tmp-${process.pid}-${Date.now()}.json`);
+        writeFileSync(tmp, JSON.stringify(data));
+        renameSync(tmp, cfgFile);
+    }
+    catch {
+        // best effort — the launch proceeds either way
+    }
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Human-facing logging (never prints the key)
+// ───────────────────────────────────────────────────────────────────────────
+function logLaunch(ctx) {
+    say(`mnemom code: routing ${ctx.cli.name} through ${ctx.door} [${ctx.cellNote}] as '${ctx.agent}' (conversation ${ctx.conversationId}).`);
+    if (ctx.envelope) {
+        say(`mnemom code: contract statement: ${ctx.envelope.contract.statement}`);
+        say(`mnemom code: contract sha256[0:16]: ${ctx.envelope.sha}`);
+    }
+}
+function printPlan(ctx) {
+    const L = [];
+    L.push("mnemom code — launch plan (dry run)");
+    L.push(`  scenario:      ${ctx.scenario}`);
+    L.push(`  cli:           ${ctx.cli.name} (${ctx.cli.bin})`);
+    L.push(`  shape:         ${ctx.shape}`);
+    L.push(`  door:          ${ctx.door}  [${ctx.cellNote}]`);
+    L.push(`  agent:         ${ctx.agent}`);
+    L.push(`  conversation:  ${ctx.conversationId}`);
+    L.push(`  yolo:          ${ctx.yolo ? "on (--dangerously-skip-permissions)" : "off"}`);
+    if (ctx.envelope) {
+        L.push(`  contract:      ${ctx.envelope.canonical}`);
+        L.push(`  contract sha:  ${ctx.envelope.sha}`);
+    }
+    else {
+        L.push("  contract:      (none — no contract flag given)");
+    }
+    L.push("");
+    L.push("  Dry run — no key was read and nothing was launched.");
+    process.stdout.write(`${L.join("\n")}\n`);
+}

package/dist/commands/logs.js

@@ -46,7 +46,17 @@ function displayTrace(trace) {
     // (The old flat `trace.verified` was always undefined on the nested wire → every
     // trace was mis-flagged [VIOLATION] and the action rendered as "[object Object]".)
     const verified = trace.verification?.verified ?? true;
-    const statusMsg = verified ? fmt.success(timestamp) : fmt.error(`${timestamp} [VIOLATION]`);
+    // MNE-596 — AAP flagged a structural violation, but the observer's DDR
+    // cross-check confirmed AIP independently saw `clear` and no bounded action
+    // was ever executed: the agent was attacked and correctly refused. Render
+    // this distinctly from a real [VIOLATION] — it's good behavior, not bad —
+    // while still surfacing it (never silently swallowed).
+    const isBoundedRefusal = trace.verification?.classification === "bounded_refusal";
+    const statusMsg = verified
+        ? fmt.success(timestamp)
+        : isBoundedRefusal
+            ? fmt.warn(`${timestamp} [BOUNDED REFUSAL — policy-enforced, not counted]`)
+            : fmt.error(`${timestamp} [VIOLATION]`);
     console.log(`\n  ${statusMsg}`);
     // action.name is the canonical label (the tool name lives here in the AIP-nested
     // shape); fall back to the action type, then a dash.