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

package/dist/index.d.ts

@@ -1,3 +1,10 @@
 #!/usr/bin/env node
 import { program } from "commander";
 export { program };
+/**
+ * The entrypoint dispatch. `mnemom agent slack …` owns its own flags (--thread,
+ * --channel, …), which the `agent` launcher options would otherwise reject as
+ * unknown — so it bypasses commander entirely and reaches the sub-verb parser
+ * verbatim. Exported (not auto-run) so the bypass is unit-testable.
+ */
+export declare function runEntrypoint(argv?: string[]): void;

package/dist/index.js

@@ -11,6 +11,7 @@ import { policyInitCommand, policyValidateCommand, policyPublishCommand, policyL
 import { protectionShowCommand, protectionPublishCommand, protectionValidateCommand, protectionEditCommand, protectionDriftCommand, } from "./commands/protection.js";
 import { agentsListCommand, agentsClaimCommand, agentsMoveCommand } from "./commands/agents.js";
 import { agentSessionsCommand, agentShowCommand, liveSessionDeps, } from "./commands/agent-sessions.js";
+import { agentGoalPinCommand, agentGoalResetCommand, agentGoalShowCommand, liveGoalDeps, } from "./commands/agent-goal.js";
 import { orgListCommand, orgShowCommand, orgUseCommand } from "./commands/org.js";
 import { teamListCommand, teamShowCommand, teamTemplateCommand, teamPreviewComposeCommand, teamAdminGrantCommand, teamAdminRevokeCommand, teamAdminListCommand, teamCoverageCommand, } from "./commands/team.js";
 import { advisoriesListCommand, advisoriesShowCommand } from "./commands/advisories.js";
@@ -23,6 +24,7 @@ import { listenCommand } from "./commands/listen.js";
 import { tryMeCommand } from "./commands/try-me.js";
 import { agentCommand } from "./commands/agent.js";
 import { agentConfigCommand } from "./commands/agent-config.js";
+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";
@@ -134,8 +136,11 @@ const agentCmd = program
     .option("--no-setup", "Skip governed-agent provisioning entirely for this launch")
     .option("--no-yolo", "Do NOT pass --dangerously-skip-permissions (yolo is on by default)")
     .option("--no-context-hint", "Do NOT seed Claude Code's context-hint feature flag before launch")
+    .option("--slack", "Attach the Slack channel: messages addressed to this session arrive in it, and it can reply (see `mnemom agent slack`)")
     .option("--context", "Force context folding ON for this launch even when launcher.toml (context = false) or MNEMOM_AGENT_CONTEXT turns it off")
     .option("--no-context", "Disable context folding for this launch (folding is on by default; tells the gateway to skip it for this session)")
+    .option("--context-handoff", "EXPERIMENTAL, off by default: register the `handoff(note)` MCP tool and tell the gateway to turn on the context-handoff capability for this session")
+    .option("--no-context-handoff", "Keep context handoff off for this launch even when launcher.toml (context_handoff = true) or MNEMOM_AGENT_CONTEXT_HANDOFF turns it on")
     .option("--dry-run", "Print the resolved launch plan and exit — no key read, no spawn")
     .action(async (scenario, passthrough, opts) => {
     try {
@@ -159,6 +164,12 @@ const agentCmd = program
             await agentConfigCommand(passthrough);
             return;
         }
+        // Sub-verb: `mnemom agent slack …` posts/receives Slack messages as this
+        // session (lib/slack.ts) and never launches.
+        if (scenario === "slack") {
+            await agentSlackCommand(passthrough);
+            return;
+        }
         if (opts.gateway)
             process.env.MNEMOM_AGENT_GATEWAY = opts.gateway;
         // Persistent settings (~/.mnemom/launcher.toml) sit UNDER env and flags:
@@ -217,7 +228,9 @@ const agentCmd = program
             trimMcp: opts.trimMcp,
             yolo: opts.yolo,
             contextHint: opts.contextHint,
+            slack: opts.slack ?? cfg.slackListen,
             context: opts.context,
+            contextHandoff: opts.contextHandoff,
             setup: opts.setup,
             keySource: cfg.keySource,
             passthrough,
@@ -730,6 +743,69 @@ agentCmd
         process.exit(1);
     }
 });
+// `mnemom agent goal show|pin|reset` — the implicit goal the gateway inferred for a session
+// (implicit-goal CLI). The handlers set process.exitCode themselves (1 / 2); the catch is for
+// the unexpected.
+const agentGoalCmd = agentCmd
+    .command("goal")
+    .description("Read and steer the goal the gateway inferred for an implicit-mode session (show / pin / reset). " +
+    "Authenticates with the same key and agent the session launched with");
+const collectRepeat = (value, prev = []) => [...prev, value];
+agentGoalCmd
+    .command("show [ref]")
+    .description("Show the session's live inferred goal: revision, pin, statement, requirements, fences and the latest verdict. " +
+    "`ref` is a session name (newest match wins) or a unique conversation-id prefix; omitted = the newest session")
+    .option("--thread <id>", "Goal thread: main (default) or a thread id such as a.<agent-id>")
+    .option("--all-threads", "List every goal thread of the conversation (main + subagents)")
+    .option("--history", "Add the revision history table")
+    .option("--json", "Output the gateway body (source gateway) plus the ledger row (source ledger)")
+    .action(async (ref, opts) => {
+    try {
+        await agentGoalShowCommand(ref, opts, liveGoalDeps);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+agentGoalCmd
+    .command("pin [ref]")
+    .description("Pin the current inferred goal so new messages no longer revise it (--off unpins)")
+    .option("--thread <id>", "Goal thread: main (default) or a thread id such as a.<agent-id>")
+    .option("--off", "Unpin: new directions revise the goal again")
+    .option("--json", "Output the gateway body as JSON")
+    .action(async (ref, opts) => {
+    try {
+        await agentGoalPinCommand(ref, opts, liveGoalDeps);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+agentGoalCmd
+    .command("reset [ref]")
+    .description("Clear the inferred goal (the next message re-infers it), or replace it with --statement. " +
+    "Revisions keep counting up; spend and turn ceilings are never refunded")
+    .option("--thread <id>", "Goal thread: main (default) or a thread id such as a.<agent-id>")
+    .option("--statement <s>", "Replace the goal with this statement instead of clearing it")
+    .option("--requirement <r>", "A requirement for --statement (repeatable)", collectRepeat)
+    .option("--yes", "Skip the confirmation (required without a TTY)")
+    .option("--json", "Output the gateway body as JSON")
+    .action(async (ref, opts, cmd) => {
+    try {
+        // `mnemom agent` itself declares `--requirement` (a contract flag), and commander hands a
+        // parent's option to the parent wherever it appears, so the values land on `agent`.
+        // Read them from there when this command saw none.
+        const inherited = cmd.optsWithGlobals().requirement;
+        const requirement = opts.requirement ?? inherited;
+        await agentGoalResetCommand(ref, { ...opts, requirement }, liveGoalDeps);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 // ============================================================================
 // Organization management (ADR-044, Piece 1 of T1-3.1)
 // ============================================================================
@@ -1807,6 +1883,22 @@ export { program };
 // Parse argv only when invoked as the CLI entrypoint — not when imported.
 // The symlink-safe guard lives in ./lib/entrypoint so it can be unit-tested
 // without executing this module's top-level parse().
-if (isEntrypoint(import.meta.url, process.argv[1])) {
-    program.parse();
+/**
+ * The entrypoint dispatch. `mnemom agent slack …` owns its own flags (--thread,
+ * --channel, …), which the `agent` launcher options would otherwise reject as
+ * unknown — so it bypasses commander entirely and reaches the sub-verb parser
+ * verbatim. Exported (not auto-run) so the bypass is unit-testable.
+ */
+export function runEntrypoint(argv = process.argv.slice(2)) {
+    if (argv[0] === "agent" && argv[1] === "slack") {
+        agentSlackCommand(argv.slice(2)).catch((err) => {
+            console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        });
+    }
+    else {
+        program.parse();
+    }
 }
+if (isEntrypoint(import.meta.url, process.argv[1]))
+    runEntrypoint();

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

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

package/dist/lib/agent.d.ts

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

package/dist/lib/agent.js

@@ -50,6 +50,18 @@ export function resolveAnthropicDoor(env = process.env) {
 export function isProdGateway(env = process.env) {
     return resolveGatewayHost(env) === PROD_GATEWAY_HOST;
 }
+/**
+ * The gateway origin the `handoff` MCP tool's own `POST /mnemom/context/handoff` must hit —
+ * always the SAME cell the launched session's own `/v1/messages` traffic goes to. Derived from
+ * the already-resolved Anthropic `door` (scheme+host only, via `new URL(...).origin`) rather
+ * than `resolveGatewayHost` directly, because `MNEMOM_AGENT_ANTHROPIC_GATEWAY` can override the
+ * door to a DIFFERENT host than `MNEMOM_AGENT_GATEWAY`/the default (e.g. a test cell) — reading
+ * `resolveGatewayHost` here would silently send handoff calls to prod (or vice versa) while the
+ * session's model traffic went elsewhere (MNE-7564 review).
+ */
+export function resolveHandoffGatewayHost(door) {
+    return new URL(door).origin;
+}
 /**
  * Sanitise a header value into a safe wire token: lowercase, alphanumerics and
  * single hyphens only, no leading/trailing hyphen. Returns "" when nothing
@@ -62,6 +74,25 @@ export function sanitizeAgentName(raw) {
         .replace(/^-+/, "")
         .replace(/-+$/, "");
 }
+/**
+ * The env var the launcher sets in the child CLI's environment to the session's
+ * display name, so tools running INSIDE the session (e.g. `mnemom agent slack
+ * post`) can identify themselves by the same name the claude.ai session list shows.
+ */
+export const SESSION_NAME_ENV = "MNEMOM_AGENT_SESSION_NAME";
+/** The session display name: "<agent>-<scenario>" (sanitised), else the agent slug. */
+export function sessionDisplayName(agent, scenario) {
+    return sanitizeAgentName(`${agent}-${scenario}`) || agent;
+}
+/** A caller's own `--name <x>` in the passthrough args, if any (last one wins). */
+export function passthroughName(passthrough) {
+    let name;
+    for (let i = 0; i < passthrough.length - 1; i++) {
+        if (passthrough[i] === "--name")
+            name = passthrough[i + 1];
+    }
+    return name;
+}
 /** A single-line, header-safe conversation id: honour a caller value, else a uuid. */
 export function resolveConversationId(raw) {
     const trimmed = (raw ?? "").replace(/[\r\n]+/g, "").trim();
@@ -195,6 +226,15 @@ export const GOAL_MODE_HEADER = "x-mnemom-goal-mode";
 export const SESSION_CONFIG_HEADER = "x-mnemom-session-config";
 /** The gateway env key that gates context folding (allow-listed for per-session overlay). */
 export const CONTEXT_RUNTIME_KEY = "CONTEXT_RUNTIME_ENABLED";
+/**
+ * The gateway env key that gates the whole context-handoff capability (level lines +
+ * `/mnemom/context/handoff` route + the digest note section) for a single session
+ * (MNE-7561..7565). Off by default on the gateway; turned on ONLY when this launch's
+ * `contextHandoff` setting is true (see `resolveContextHandoff`), which also registers the
+ * `handoff` MCP tool (MNE-7564) — a session never gets the tool without the header, or the
+ * header without the tool.
+ */
+export const CONTEXT_HANDOFF_KEY = "CONTEXT_HANDOFF_ENABLED";
 const SEALED_ONLY_FLAGS = "--goal/--requirement/--allow/--forbid/--goal-id";
 /**
  * `--implicit` and a sealed contract are mutually exclusive: on the gateway a
@@ -393,16 +433,76 @@ export function resolveContextFold(opts) {
     return !(raw === "0" || raw === "false" || raw === "off" || raw === "no");
 }
 /**
- * The `x-mnemom-session-config` value that turns context folding OFF, or
- * `undefined` when folding is ON (the default — nothing is sent, the gateway's
- * own default stands). base64url so it survives the gateway's inbound strip.
+ * The `x-mnemom-session-config` value for this launch, or `undefined` when there is
+ * nothing to override (the gateway's own defaults stand — the common case). Two
+ * independent overlays, both OFF by default (folding is ON by default so only its OFF
+ * state is ever sent; handoff is OFF by default so only its ON state is ever sent):
+ *   - `fold: false` → `CONTEXT_RUNTIME_ENABLED: "false"` (`--no-context`).
+ *   - `contextHandoff: true` → `CONTEXT_HANDOFF_ENABLED: "true"` (the `context_handoff`
+ *     setting) — the SAME header the `handoff` MCP tool's own call to
+ *     `/mnemom/context/handoff` must also send, since the gateway resolves the flag
+ *     per request (see `commands/agent.ts` handoff MCP wiring).
+ * base64url so it survives the gateway's inbound strip.
  */
-export function buildSessionConfigB64(fold) {
-    if (fold)
+export function buildSessionConfigB64(opts) {
+    const config = {};
+    if (!opts.fold)
+        config[CONTEXT_RUNTIME_KEY] = "false";
+    if (opts.contextHandoff)
+        config[CONTEXT_HANDOFF_KEY] = "true";
+    if (Object.keys(config).length === 0)
         return undefined;
-    const payload = JSON.stringify({ v: 1, config: { [CONTEXT_RUNTIME_KEY]: "false" } });
+    const payload = JSON.stringify({ v: 1, config });
     return Buffer.from(payload, "utf8").toString("base64url");
 }
+/**
+ * Is the `handoff` MCP tool + `CONTEXT_HANDOFF_ENABLED` session-config header ON for
+ * this launch? OFF by default (operator directive, curation 2026-09-25): an absent flag
+ * and an absent `context_handoff` setting are both "off", matching `resolveContextFold`'s
+ * shape but the opposite default. Precedence: an explicit `--context-handoff`/
+ * `--no-context-handoff` flag wins, else `MNEMOM_AGENT_CONTEXT_HANDOFF` (which
+ * `applyConfigToEnv` sets from the `context_handoff` config key), else OFF.
+ */
+export function resolveContextHandoff(opts) {
+    if (opts.contextHandoff !== undefined)
+        return opts.contextHandoff;
+    const raw = (opts.env?.MNEMOM_AGENT_CONTEXT_HANDOFF ?? "").trim().toLowerCase();
+    if (raw === "")
+        return false;
+    return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+/** The name the `handoff` MCP tool server is registered under in `--mcp-config`. */
+export const HANDOFF_MCP_SERVER_NAME = "mnemom-handoff";
+/**
+ * The name of the non-`ANTHROPIC_*` env var `spawnRcCli` (commands/agent.ts) adds to Claude
+ * Code's Remote Control child env, carrying the real Anthropic key, ONLY when context handoff is
+ * on. `spawnRcCli` strips every `ANTHROPIC_*` auth var (including `ANTHROPIC_CUSTOM_HEADERS`) so
+ * the RC gate sees a clean first-party-OAuth setup, but that gate only inspects the recognized
+ * `ANTHROPIC_*` base-url/key/socket family — a custom-named var rides through ungated, exactly
+ * like `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` already do for the proxy. The handoff server inherits
+ * it the same way it inherits `ANTHROPIC_CUSTOM_HEADERS` under the terminal shape.
+ */
+export const HANDOFF_RC_KEY_ENV_NAME = "MNEMOM_HANDOFF_KEY";
+/** The `--mcp-config` document registering exactly the `handoff` tool. Pure — no I/O. */
+export function buildHandoffMcpConfig(p) {
+    const env = {
+        MNEMOM_HANDOFF_GATEWAY_HOST: p.gatewayHost,
+        MNEMOM_HANDOFF_ANTHROPIC_KEY_ENV_NAME: p.anthropicKeySource.envName,
+        MNEMOM_HANDOFF_AGENT: p.agent,
+        MNEMOM_HANDOFF_CONVERSATION_ID: p.conversationId,
+    };
+    if (p.sessionConfigB64)
+        env.MNEMOM_HANDOFF_SESSION_CONFIG = p.sessionConfigB64;
+    return {
+        mcpServers: {
+            [HANDOFF_MCP_SERVER_NAME]: { command: p.nodeBin, args: [p.serverScript], env },
+        },
+    };
+}
+/** `JSON.stringify(buildHandoffMcpConfig(p))` — the exact bytes written to the config file. */
+export function buildHandoffMcpConfigJson(p) {
+    return JSON.stringify(buildHandoffMcpConfig(p));
+}
 /**
  * Is this launch implicit-mode? Precedence, highest wins:
  *   1. an explicit flag — `--implicit` (true) or `--no-implicit` (false);

package/dist/lib/goal-api.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The client for the gateway's implicit-goal control route (implicit-goal CLI, cli-telemetry
+ * §1.2 / §1.4; the route is gateway/src/goal-intent-control.ts):
+ *
+ *   GET  https://<gateway_host>/mnemom/goal/intent?conversation_id=…&thread=…
+ *   POST https://<gateway_host>/mnemom/goal/intent/pin    {conversation_id, thread, pinned}
+ *   POST https://<gateway_host>/mnemom/goal/intent/reset  {conversation_id, thread, statement?, requirements?}
+ *
+ * Auth is the SAME credential the launch used: `x-api-key` (the Anthropic key from
+ * `resolveAnthropicKey`), `x-mnemom-agent: <record.agent_slug>`, and `x-mnemom-api-key` when the
+ * launch had a Mnemom key. The gateway hashes them exactly as a proxied request and only LOOKS
+ * UP the agent. Key material is never printed: errors carry the status, the gateway's error code
+ * and its message, nothing else.
+ *
+ * Pure apart from the injected `fetch`, so every arm is unit-tested.
+ */
+import type { SessionRecord } from "./agent-ledger.js";
+export type GoalOp = "show" | "pin" | "reset";
+/**
+ * A thread id the gateway accepts (PLAN K3 plus `all` for reads, plus the `m.<sha16>` per-process
+ * main ids the gateway's goal-thread.ts THREAD_ID_RE also accepts). Validated locally so a typo
+ * never costs a round trip.
+ */
+export declare const GOAL_THREAD_RE: RegExp;
+export declare function isValidGoalThread(thread: string): boolean;
+/** The ledger fields the control call needs. */
+export type GoalControlRecord = Pick<SessionRecord, "gateway_host" | "agent_slug" | "conversation_id">;
+export interface GoalControlCreds {
+    /** The Anthropic key the launch sent as `x-api-key`. */
+    anthropicKey: string;
+    /** The Mnemom key, only when the launch sent `x-mnemom-api-key`. */
+    mnemomKey?: string | null;
+}
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export interface GoalControlDeps {
+    fetch: FetchLike;
+    creds: GoalControlCreds;
+}
+export interface GoalShowBodyInput {
+    thread?: string;
+}
+export interface GoalPinBodyInput {
+    thread?: string;
+    pinned: boolean;
+}
+export interface GoalResetBodyInput {
+    thread?: string;
+    statement?: string;
+    requirements?: string[];
+}
+export interface GoalPinned {
+    at: string;
+    revision: number;
+    by: "cli";
+}
+export interface GoalHistoryEntry {
+    revision: number;
+    hash: string;
+    class: string;
+    ops: number;
+    at: string;
+    source: string | null;
+}
+export interface GoalIntentView {
+    intent_id: string;
+    revision: number;
+    contract_hash: string;
+    statement: string;
+    requirements: string[];
+    allowed_paths: string[];
+    forbidden_paths: string[];
+    pinned: GoalPinned | null;
+    pending_count: number;
+    history: GoalHistoryEntry[];
+    revisions_10m: number;
+    gates_10m: number;
+    updated_at: string;
+}
+export interface GoalVerdictView {
+    verdict: string;
+    turn: number;
+    at: string;
+    superseded: boolean;
+}
+export interface GoalThreadRow {
+    thread: string;
+    role: string;
+    revision: number;
+    statement: string | null;
+    pinned: boolean;
+}
+/** `GET /mnemom/goal/intent` (cli-telemetry §1.2 plus the `thread` echo and `last_revision`). */
+export interface GoalShowResponse {
+    conversation_id: string;
+    thread: string;
+    mode: "implicit" | "sealed" | "none";
+    sealed_hash?: string;
+    intent: GoalIntentView | null;
+    verdict: GoalVerdictView | null;
+    last_revision: number;
+    threads?: GoalThreadRow[];
+}
+export interface GoalPinResponse {
+    conversation_id: string;
+    thread: string;
+    pinned: GoalPinned | null;
+    revision: number;
+}
+export interface GoalResetResponse {
+    conversation_id: string;
+    thread: string;
+    reset: true;
+    revision: number;
+    prior_revision: number;
+    intent: GoalIntentView | null;
+    verdict_superseded: boolean;
+}
+/** A non-2xx answer (status > 0) or a transport failure (status 0). Never carries key material. */
+export declare class GoalControlError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    constructor(status: number, code: string | null, message: string);
+}
+/** `https://<host>` for a bare host; a host that already names a scheme is kept (trailing / dropped). */
+export declare function gatewayOrigin(host: string): string;
+export declare const GOAL_CONTROL_PATH = "/mnemom/goal/intent";
+/** The route URL for one op (the show query carries the conversation id and thread). */
+export declare function goalControlUrl(record: GoalControlRecord, op: GoalOp, thread?: string): string;
+/** The launch's identity headers (never logged). */
+export declare function goalControlHeaders(record: GoalControlRecord, creds: GoalControlCreds): Record<string, string>;
+export declare function goalControlFetch(record: GoalControlRecord, op: "show", body: GoalShowBodyInput, deps: GoalControlDeps): Promise<GoalShowResponse>;
+export declare function goalControlFetch(record: GoalControlRecord, op: "pin", body: GoalPinBodyInput, deps: GoalControlDeps): Promise<GoalPinResponse>;
+export declare function goalControlFetch(record: GoalControlRecord, op: "reset", body: GoalResetBodyInput, deps: GoalControlDeps): Promise<GoalResetResponse>;