@mnemom/mnemom 0.17.3-next.5 → 0.17.3

package/dist/index.js

@@ -28,7 +28,10 @@ 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 { applyConfigToEnv, loadLauncherConfig } from "./lib/launcher-config.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";
+import { experimentalDisableCommand, experimentalEnableCommand, experimentalListCommand, runExperimentalMigration, } from "./commands/experimental.js";
 import { parseContextProfile, resolveImplicit } from "./lib/agent.js";
 import { wrapCommand } from "./commands/wrap.js";
 import { onboardCommand } from "./commands/onboard.js";
@@ -97,12 +100,25 @@ program
 // CONTRACT the gateway seals on the first turn. Three launch shapes — terminal
 // (default), --remote-control (interactive RC in this terminal), --server
 // (headless RC dispatcher) — with yolo on by default. `--cli` selects the
-// executable (name or full path; default claude). The us-2/prod door is the
-// DEFAULT; set MNEMOM_AGENT_GATEWAY (or --gateway) to point elsewhere. The
+// executable (name or full path; default claude). The door is the gateway of the
+// cell the CLI uses (prod by default); a door on another cell is refused. The
 // Anthropic key is resolved with zero 1Password dependency (env → ~/.mnemom store
 // → interactive prompt) inside the launched process and never logged. See
 // commands/code.ts.
 // ─────────────────────────────────────────────────────────────────────────────
+// ── experimental features (lib/experimental.ts) ── While a feature is off its flags and
+// commands are hidden from --help (decided once, at load) and using one fails with a
+// pointer to `mnemom experimental enable <id>` (decided per invocation, in the action).
+const experimentalAtLoad = loadExperimentalState().enabled;
+const hiddenUnless = (id) => !experimentalAtLoad.includes(id);
+/** preAction guard for a gated command: print the guidance and exit 2 while `id` is off. */
+function requireExperimental(what, id) {
+    const message = gateCheck(what, id, loadExperimentalState().enabled);
+    if (message) {
+        console.error(message);
+        process.exit(2);
+    }
+}
 const collectRepeatable = (value, previous) => {
     previous.push(value);
     return previous;
@@ -119,11 +135,11 @@ const agentCmd = program
     .option("--budget <usd>", "Guardrail: spend ceiling in USD (positive number)")
     .option("--max-turns <n>", "Guardrail: turn ceiling (positive integer)")
     .option("--stall <n>", "Guardrail: consecutive no-write turns (positive integer)")
-    .option("--implicit", "Implicit goal alignment (the default): the gateway infers the goal from your messages and revises it as you steer (not combinable with --goal/--requirement/--allow/--forbid/--goal-id; the guardrail ceilings still apply)")
-    .option("--no-implicit", "Turn goal alignment OFF for this launch (implicit alignment is on by default; also overrides launcher.toml goal_mode = implicit)")
+    .addOption(new Option("--implicit", "EXPERIMENTAL (`mnemom experimental enable implicit`): implicit goal alignment — the gateway infers the goal from your messages and revises it as you steer (the default while the feature is on; not combinable with --goal/--requirement/--allow/--forbid/--goal-id; the guardrail ceilings still apply)").hideHelp(hiddenUnless("implicit")))
+    .option("--no-implicit", "Turn implicit goal alignment OFF for this launch (overrides launcher.toml goal_mode = implicit)")
     .option("--conversation-id <id>", "x-mnemom-conversation-id (default: auto-generated)")
     .option("--cli <name|path>", "Coding-agent CLI to launch: a name or full path (default: claude)")
-    .option("--gateway <url>", "Gateway host override (default: https://gateway.mnemom.ai; or MNEMOM_AGENT_GATEWAY)")
+    .option("--gateway <url>", "Gateway host override — must be the same cell as the rest of the CLI (default: that cell's gateway; or MNEMOM_AGENT_GATEWAY)")
     .option("--remote-control", "Interactive Remote Control session in THIS terminal (behind a local proxy)")
     .option("--server", "Headless `claude remote-control` dispatcher (behind a local proxy)")
     .option("--model <alias|id>", "Model to launch (CLI alias or concrete id)")
@@ -140,7 +156,7 @@ 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`)")
+    .addOption(new Option("--slack", "EXPERIMENTAL (`mnemom experimental enable slack`): attach the Slack channel — messages addressed to this session arrive in it, and it can reply (see `mnemom agent slack`)").hideHelp(hiddenUnless("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)")
     .addOption(new Option("--context-profile <profile>", 'How the gateway folds this session\'s context. "balanced" (default) keeps more of the earlier work verbatim and folds later — for long sessions that revisit earlier files and decisions. "aggressive" folds earlier and keeps a tighter working set — for cost-sensitive sessions and short, focused tasks. "off" leaves compaction to the coding agent. Also: config key context_profile, env MNEMOM_AGENT_CONTEXT_PROFILE.').argParser((v) => {
@@ -153,7 +169,7 @@ const agentCmd = program
         throw new InvalidArgumentError(e.message);
     }
 }))
-    .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")
+    .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")
     .action(async (scenario, passthrough, opts) => {
@@ -168,29 +184,53 @@ const agentCmd = program
         });
     }
     catch (error) {
-        console.error("Error:", error instanceof Error ? error.message : error);
-        process.exit(1);
+        const report = reportCliError(error);
+        console.error(...report.args);
+        process.exit(report.code);
     }
     async function launchAgent(scenario) {
+        const experimental = loadExperimentalState().enabled;
         // Sub-verb: `mnemom agent config …` manages persistent settings and never
         // launches. (A scenario literally named "config" is reserved for this.)
         if (scenario === "config") {
-            await agentConfigCommand(passthrough);
+            await agentConfigCommand(passthrough, { enabled: experimental });
             return;
         }
         // Sub-verb: `mnemom agent slack …` posts/receives Slack messages as this
-        // session (lib/slack.ts) and never launches.
+        // session (lib/slack.ts) and never launches. Experimental (`slack`).
         if (scenario === "slack") {
+            assertEnabled([{ what: "`mnemom agent slack`", id: "slack", used: true }], experimental);
             await agentSlackCommand(passthrough);
             return;
         }
+        // Experimental flags while their feature is off: refuse (exit 2) with the pointer.
+        // The `--no-*` spellings stay available — turning an off feature off is harmless.
+        assertEnabled([
+            { what: "--slack", id: "slack", used: opts.slack === true },
+            {
+                what: "--context-handoff",
+                id: "context-handoff",
+                used: opts.contextHandoff === true,
+            },
+            { what: "--implicit", id: "implicit", used: opts.implicit === true },
+        ], experimental);
         if (opts.gateway)
             process.env.MNEMOM_AGENT_GATEWAY = opts.gateway;
         // Persistent settings (~/.mnemom/launcher.toml) sit UNDER env and flags:
         // precedence is flag > env > launcher.toml > built-in. Env-backed settings are
         // folded into env only when unset (so env/flags still win); the resolvers
         // in lib/code.ts keep the built-in default as the final fallback.
-        const cfg = loadLauncherConfig();
+        // Settings of experimental features that are off are ignored (with the pointer),
+        // before they can reach env or the launch.
+        const rawCfg = loadLauncherConfig();
+        for (const line of ignoredSettingLines({
+            entries: launcherEntries(rawCfg),
+            env: process.env,
+            enabled: experimental,
+        })) {
+            console.error(line);
+        }
+        const cfg = withoutDisabledExperimental(rawCfg, experimental);
         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.
@@ -207,11 +247,13 @@ const agentCmd = program
         const numToStr = (n) => n === undefined ? undefined : String(n);
         // Implicit mode: --implicit / --no-implicit win; a --goal statement seals
         // (the standing config default never overrides it); else launcher.toml
-        // `goal_mode`; else off. Pure + unit-tested in lib/agent.ts.
+        // `goal_mode`; else implicit while the `implicit` feature is on, off while it is
+        // off. Pure + unit-tested in lib/agent.ts.
         const implicit = resolveImplicit({
             goal: opts.goal,
             implicit: opts.implicit,
             configGoalMode: cfg.goalMode,
+            experimentalOn: experimental.includes("implicit"),
         });
         // Config guardrails apply only when goal alignment is actually intended (a
         // --goal is present, or implicit mode — where they ride on the mode header),
@@ -245,7 +287,9 @@ const agentCmd = program
             slack: opts.slack ?? cfg.slackListen,
             context: opts.context,
             contextProfile: opts.contextProfile,
-            contextHandoff: opts.contextHandoff,
+            // Off ⇒ an explicit false, so MNEMOM_AGENT_CONTEXT_HANDOFF cannot turn it on.
+            contextHandoff: experimental.includes("context-handoff") ? opts.contextHandoff : false,
+            experimental,
             setup: opts.setup,
             keySource: cfg.keySource,
             passthrough,
@@ -763,9 +807,10 @@ agentCmd
 // (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");
+    .command("goal", { hidden: hiddenUnless("implicit") })
+    .description("EXPERIMENTAL (`mnemom experimental enable implicit`): 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")
+    .hook("preAction", () => requireExperimental("`mnemom agent goal`", "implicit"));
 const collectRepeat = (value, prev = []) => [...prev, value];
 agentGoalCmd
     .command("show [ref]")
@@ -1928,6 +1973,23 @@ configCmd
     .command("unset <key>")
     .description("Reset a preference to its default")
     .action((key) => runAction(() => configUnsetCommand(key)));
+// ── experimental (lib/experimental.ts) — turn experimental features on and off ──
+const experimentalCmd = program
+    .command("experimental")
+    .description(`List, enable and disable experimental features (stored in ~/.mnemom/config.json; MNEMOM_EXPERIMENTAL=<ids>|all overrides). ${EXPERIMENTAL_CONTRACT}`);
+experimentalCmd
+    .command("list", { isDefault: true })
+    .description("Show every experimental feature, whether it is on, and what it gates")
+    .option("--json", "Emit machine-readable JSON")
+    .action((options) => runAction(() => experimentalListCommand(options)));
+experimentalCmd
+    .command("enable <id>")
+    .description("Turn an experimental feature on")
+    .action((id) => runAction(() => experimentalEnableCommand(id)));
+experimentalCmd
+    .command("disable <id>")
+    .description("Turn an experimental feature off")
+    .action((id) => runAction(() => experimentalDisableCommand(id)));
 // Export the fully-assembled commander program so tooling (e.g. the
 // command-tree snapshot generator in scripts/gen-command-tree.mjs) can
 // statically introspect the command surface WITHOUT executing the CLI.
@@ -1941,8 +2003,12 @@ export { program };
  * 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)) {
+export function runEntrypoint(argv = process.argv.slice(2), migrate = runExperimentalMigration) {
+    // First run after the upgrade that introduced experimental features: keep on whatever
+    // launcher.toml already uses (commands/experimental.ts; never throws).
+    migrate();
     if (argv[0] === "agent" && argv[1] === "slack") {
+        requireExperimental("`mnemom agent slack`", "slack");
         agentSlackCommand(argv.slice(2)).catch((err) => {
             console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
             process.exit(1);

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

@@ -81,6 +81,11 @@ export interface SessionRecord {
      * before profiles existed omit it (still `v: 1`).
      */
     context_profile?: ContextProfile;
+    /**
+     * The experimental features on for the launch (`mnemom experimental`). Optional and only
+     * written when at least one was on; older records omit it (still `v: 1`).
+     */
+    experimental?: string[];
 }
 /** Goal-alignment mode as recorded at launch. */
 export type GoalMode = "off" | "on" | "implicit";

package/dist/lib/agent-ledger.js

@@ -160,6 +160,11 @@ export function parseRecord(line) {
     const rec = value;
     if (rec.v !== 1)
         return null;
+    // A hand-edited or future `experimental` that is not a string list is dropped, not trusted.
+    if (rec.experimental !== undefined &&
+        !(Array.isArray(rec.experimental) && rec.experimental.every((x) => typeof x === "string"))) {
+        delete rec.experimental;
+    }
     return rec;
 }
 function nonEmptyLines(text) {

package/dist/lib/agent.d.ts

@@ -63,11 +63,27 @@ export interface ContractFlags {
 export type LaunchShape = "terminal" | "remote-control" | "server";
 /**
  * Resolve the gateway HOST (scheme + host, no path). An explicit, non-empty
- * `MNEMOM_AGENT_GATEWAY` wins verbatim; otherwise the us-2/prod host. The default
- * is PROD — an unset var resolves to prod, and any other cell is reached only by
- * NAMING it. Trailing slash trimmed so door concatenation is clean.
- */
-export declare function resolveGatewayHost(env?: NodeJS.ProcessEnv): string;
+ * `MNEMOM_AGENT_GATEWAY` wins verbatim; otherwise the gateway of the cell the rest
+ * of the CLI uses (`getGatewayUrl()`: prod unless MNEMOM_ENV / MNEMOM_RING /
+ * MNEMOM_GATEWAY_URL name another). An override on a different cell is refused at
+ * launch — see `singleCellError`. Trailing slash trimmed so door concatenation is clean.
+ */
+export declare function resolveGatewayHost(env?: NodeJS.ProcessEnv, cellGateway?: string): string;
+/** Same scheme+host+port. An unparseable URL never matches. */
+export declare function sameOrigin(a: string, b: string): boolean;
+/**
+ * A launch must use ONE cell: the Anthropic `door` its traffic goes to must be the
+ * gateway of the cell the CLI signs in, resolves the agent and reads sessions on
+ * (`cellGateway`, paired with `apiUrl`). A mixed launch records one cell's agent
+ * and runs as another cell's, so `sessions`/`show` never find its goal state.
+ * Returns the refusal message, or null. A loopback door is a local dev gateway and
+ * is exempt.
+ */
+export declare function singleCellError(opts: {
+    door: string;
+    apiUrl: string;
+    cellGateway: string;
+}): string | null;
 /**
  * The Anthropic door the CLI points Claude Code at:
  * `${MNEMOM_AGENT_GATEWAY}/anthropic`, or the full-door override
@@ -324,6 +340,20 @@ export declare function buildSessionConfig(opts: {
     profile: ContextProfile;
     contextHandoff: boolean;
 }): Record<string, string>;
+/**
+ * The `x-mnemom-session-config` payload: `{ v: 1, config, experimental? }`. The active
+ * experimental ids ride as a top-level array, beside (not inside) the env overlay, so the
+ * gateway's allow-list never sees them as env keys; it ignores unknown envelope fields.
+ */
+export declare function buildSessionConfigPayload(opts: {
+    profile: ContextProfile;
+    contextHandoff: boolean;
+    experimental?: readonly string[];
+}): {
+    v: 1;
+    config: Record<string, string>;
+    experimental?: string[];
+} | undefined;
 /**
  * The `x-mnemom-session-config` value for this launch, or `undefined` when there is
  * nothing to override (the gateway's own defaults stand — `balanced` with handoff off,
@@ -339,6 +369,7 @@ export declare function buildSessionConfig(opts: {
 export declare function buildSessionConfigB64(opts: {
     profile: ContextProfile;
     contextHandoff: boolean;
+    experimental?: readonly string[];
 }): string | undefined;
 /**
  * Is the `handoff` MCP tool + `CONTEXT_HANDOFF_ENABLED` session-config header ON for
@@ -427,10 +458,10 @@ export type GoalModeDefault = "implicit" | "off";
  *      standing config default must never silently override;
  *   3. the config default `goal_mode` — `"off"` turns alignment off, `"implicit"`
  *      keeps it implicit;
- *   4. IMPLICIT (the default). A bare `mnemom agent` runs with implicit goal
- *      alignment on: the gateway infers the goal from the user's own messages.
- *      Turn it off for a launch with `--no-implicit`, or standing with
- *      `goal_mode = "off"`.
+ *   4. with the `implicit` experimental feature ON, IMPLICIT: the gateway infers
+ *      the goal from the user's own messages (turn it off for a launch with
+ *      `--no-implicit`, or standing with `goal_mode = "off"`); with it OFF (the
+ *      default), OFF.
  * Pure so every arm is unit-tested; the caller passes the resolved value on to
  * `assembleContract` / `buildGoalModeHeader` (which still refuse `--implicit`
  * combined with a contract flag — that conflict is EXPLICIT and is reported).
@@ -439,4 +470,10 @@ export declare function resolveImplicit(opts: {
     goal?: string;
     implicit?: boolean;
     configGoalMode?: GoalModeDefault;
+    /**
+     * Is the `implicit` experimental feature on? Off ⇒ the default is OFF and
+     * `goal_mode = implicit` is ignored (`--implicit` is refused upstream, before
+     * this runs). Omitted ⇒ on.
+     */
+    experimentalOn?: boolean;
 }): boolean;

package/dist/lib/agent.js

@@ -20,19 +20,56 @@
  * NAMED), but prod is never selected silently — see `resolveGatewayHost`.
  */
 import { createHash, randomUUID } from "node:crypto";
+import { getGatewayUrl } from "./config.js";
 /** The us-2/prod gateway host. The default door — never any other cell silently. */
 export const PROD_GATEWAY_HOST = "https://gateway.mnemom.ai";
 /**
  * Resolve the gateway HOST (scheme + host, no path). An explicit, non-empty
- * `MNEMOM_AGENT_GATEWAY` wins verbatim; otherwise the us-2/prod host. The default
- * is PROD — an unset var resolves to prod, and any other cell is reached only by
- * NAMING it. Trailing slash trimmed so door concatenation is clean.
+ * `MNEMOM_AGENT_GATEWAY` wins verbatim; otherwise the gateway of the cell the rest
+ * of the CLI uses (`getGatewayUrl()`: prod unless MNEMOM_ENV / MNEMOM_RING /
+ * MNEMOM_GATEWAY_URL name another). An override on a different cell is refused at
+ * launch — see `singleCellError`. Trailing slash trimmed so door concatenation is clean.
  */
-export function resolveGatewayHost(env = process.env) {
+export function resolveGatewayHost(env = process.env, cellGateway = getGatewayUrl()) {
     const raw = (env.MNEMOM_AGENT_GATEWAY ?? "").trim();
-    const host = raw.length > 0 ? raw : PROD_GATEWAY_HOST;
+    const host = raw.length > 0 ? raw : cellGateway;
     return host.replace(/\/+$/, "");
 }
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** Same scheme+host+port. An unparseable URL never matches. */
+export function sameOrigin(a, b) {
+    try {
+        return new URL(a).origin === new URL(b).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A launch must use ONE cell: the Anthropic `door` its traffic goes to must be the
+ * gateway of the cell the CLI signs in, resolves the agent and reads sessions on
+ * (`cellGateway`, paired with `apiUrl`). A mixed launch records one cell's agent
+ * and runs as another cell's, so `sessions`/`show` never find its goal state.
+ * Returns the refusal message, or null. A loopback door is a local dev gateway and
+ * is exempt.
+ */
+export function singleCellError(opts) {
+    let doorUrl;
+    try {
+        doorUrl = new URL(opts.door);
+    }
+    catch {
+        return `mnemom agent: the gateway '${opts.door}' is not a valid URL.`;
+    }
+    if (LOOPBACK_HOSTS.has(doorUrl.hostname))
+        return null;
+    if (sameOrigin(opts.door, opts.cellGateway))
+        return null;
+    return (`mnemom agent: the gateway ${doorUrl.origin} is on a different cell from the one this CLI uses ` +
+        `(API ${opts.apiUrl}, gateway ${opts.cellGateway}). A launch must use one cell. Point the whole ` +
+        "CLI at that cell (MNEMOM_API_URL + MNEMOM_GATEWAY_URL, or MNEMOM_RING) and drop the gateway " +
+        "override (--gateway, MNEMOM_AGENT_GATEWAY, MNEMOM_AGENT_ANTHROPIC_GATEWAY, or `gateway` in launcher.toml).");
+}
 /**
  * The Anthropic door the CLI points Claude Code at:
  * `${MNEMOM_AGENT_GATEWAY}/anthropic`, or the full-door override
@@ -513,6 +550,20 @@ export function buildSessionConfig(opts) {
         config[CONTEXT_HANDOFF_KEY] = "true";
     return config;
 }
+/**
+ * The `x-mnemom-session-config` payload: `{ v: 1, config, experimental? }`. The active
+ * experimental ids ride as a top-level array, beside (not inside) the env overlay, so the
+ * gateway's allow-list never sees them as env keys; it ignores unknown envelope fields.
+ */
+export function buildSessionConfigPayload(opts) {
+    const config = buildSessionConfig(opts);
+    const experimental = opts.experimental ?? [];
+    if (Object.keys(config).length === 0 && experimental.length === 0)
+        return undefined;
+    return experimental.length > 0
+        ? { v: 1, config, experimental: [...experimental] }
+        : { v: 1, config };
+}
 /**
  * The `x-mnemom-session-config` value for this launch, or `undefined` when there is
  * nothing to override (the gateway's own defaults stand — `balanced` with handoff off,
@@ -526,11 +577,10 @@ export function buildSessionConfig(opts) {
  * base64url so it survives the gateway's inbound strip.
  */
 export function buildSessionConfigB64(opts) {
-    const config = buildSessionConfig(opts);
-    if (Object.keys(config).length === 0)
+    const payload = buildSessionConfigPayload(opts);
+    if (!payload)
         return undefined;
-    const payload = JSON.stringify({ v: 1, config });
-    return Buffer.from(payload, "utf8").toString("base64url");
+    return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
 }
 /**
  * Is the `handoff` MCP tool + `CONTEXT_HANDOFF_ENABLED` session-config header ON for
@@ -587,10 +637,10 @@ export function buildHandoffMcpConfigJson(p) {
  *      standing config default must never silently override;
  *   3. the config default `goal_mode` — `"off"` turns alignment off, `"implicit"`
  *      keeps it implicit;
- *   4. IMPLICIT (the default). A bare `mnemom agent` runs with implicit goal
- *      alignment on: the gateway infers the goal from the user's own messages.
- *      Turn it off for a launch with `--no-implicit`, or standing with
- *      `goal_mode = "off"`.
+ *   4. with the `implicit` experimental feature ON, IMPLICIT: the gateway infers
+ *      the goal from the user's own messages (turn it off for a launch with
+ *      `--no-implicit`, or standing with `goal_mode = "off"`); with it OFF (the
+ *      default), OFF.
  * Pure so every arm is unit-tested; the caller passes the resolved value on to
  * `assembleContract` / `buildGoalModeHeader` (which still refuse `--implicit`
  * combined with a contract flag — that conflict is EXPLICIT and is reported).
@@ -600,5 +650,7 @@ export function resolveImplicit(opts) {
         return opts.implicit;
     if (hasText(opts.goal))
         return false;
+    if (opts.experimentalOn === false)
+        return false;
     return opts.configGoalMode !== "off";
 }

package/dist/lib/cli-config.d.ts

@@ -17,6 +17,7 @@
  * Membership can change after it's stored — consumers must treat a server
  * 403 as the truth (the claim path already renders the teaching list).
  */
+import { type ExperimentalId, type ExperimentalPrefs, type ExperimentalState } from "./experimental.js";
 import type { UpdatePrefs } from "./update/decide.js";
 export interface ActiveOrg {
     org_id: string;
@@ -32,6 +33,11 @@ export interface CliConfig {
     /** Auto-update preferences (`mnemom config set update.channel|update.mode`). */
     update?: UpdatePrefs;
     sessions?: SessionPrefs;
+    /**
+     * Experimental features the user turned on (`mnemom experimental enable <id>`). The
+     * section's presence (even `{ enabled: [] }`) also marks the one-time migration done.
+     */
+    experimental?: ExperimentalPrefs;
 }
 /** The config.json sections `mnemom config` edits. */
 export interface PrefSections {
@@ -52,3 +58,7 @@ export declare function getActiveOrg(): ActiveOrg | undefined;
 export declare function setPref<S extends keyof PrefSections, K extends keyof PrefSections[S] & string>(section: S, key: K, value: PrefSections[S][K] | undefined): void;
 /** One auto-update preference — `setPref("update", …)`. */
 export declare function setUpdatePref<K extends keyof UpdatePrefs>(key: K, value: UpdatePrefs[K] | undefined): void;
+/** Persist the full set of enabled experimental features (an empty list is kept). */
+export declare function setExperimentalEnabled(ids: readonly ExperimentalId[]): void;
+/** Which experimental features are on right now (MNEMOM_EXPERIMENTAL > config.json > off). */
+export declare function loadExperimentalState(env?: Record<string, string | undefined>): ExperimentalState;

package/dist/lib/cli-config.js

@@ -20,6 +20,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { MNEMOM_DIR } from "./config.js";
+import { resolveExperimental, } from "./experimental.js";
 function configFile() {
     return path.join(MNEMOM_DIR, "config.json");
 }
@@ -84,3 +85,13 @@ export function setPref(section, key, value) {
 export function setUpdatePref(key, value) {
     setPref("update", key, value);
 }
+/** Persist the full set of enabled experimental features (an empty list is kept). */
+export function setExperimentalEnabled(ids) {
+    const config = loadCliConfig();
+    config.experimental = { enabled: [...ids] };
+    saveCliConfig(config);
+}
+/** Which experimental features are on right now (MNEMOM_EXPERIMENTAL > config.json > off). */
+export function loadExperimentalState(env = process.env) {
+    return resolveExperimental({ stored: loadCliConfig().experimental, env });
+}

package/dist/lib/experimental.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Experimental features — the single registry and the pure logic around it.
+ *
+ * An experimental feature is OFF unless the user turns it on (`mnemom experimental
+ * enable <id>`, stored in ~/.mnemom/config.json `experimental.enabled`, or the
+ * MNEMOM_EXPERIMENTAL env var). While it is off its flags and commands are hidden
+ * from --help, using one fails with a pointer to `mnemom experimental enable`, and
+ * its launcher.toml keys are ignored with the same pointer. The contract: an
+ * experimental feature may change or be removed in any release, with no
+ * deprecation period.
+ *
+ * Everything here is pure or dependency-injected; index.ts and the command
+ * modules are the thin drivers.
+ */
+export type ExperimentalId = "context-handoff" | "slack" | "implicit";
+export interface ExperimentalFeature {
+    id: ExperimentalId;
+    summary: string;
+    /** The first CLI release that shipped the feature as experimental. */
+    since: string;
+    /** What the feature gates while it is off (for `mnemom experimental list`). */
+    gates: {
+        flags: string[];
+        configKeys: string[];
+        commands: string[];
+        env: string[];
+    };
+}
+export declare const EXPERIMENTAL_FEATURES: readonly ExperimentalFeature[];
+export declare const EXPERIMENTAL_IDS: readonly ExperimentalId[];
+export declare const EXPERIMENTAL_ENV = "MNEMOM_EXPERIMENTAL";
+export declare const EXPERIMENTAL_CONTRACT = "Experimental features may change or be removed in any release, with no deprecation period.";
+export declare function isExperimentalId(value: string): value is ExperimentalId;
+/** The config.json `experimental` section. */
+export interface ExperimentalPrefs {
+    enabled?: string[];
+}
+export interface ExperimentalState {
+    enabled: ExperimentalId[];
+    source: "env" | "config" | "default";
+    /** Ids named in MNEMOM_EXPERIMENTAL or config.json that this CLI does not know. */
+    unknown: string[];
+}
+/**
+ * Which experimental features are on. Precedence: MNEMOM_EXPERIMENTAL (a comma
+ * list of ids, `all`, or `none`) replaces the stored set; else config.json
+ * `experimental.enabled`; else everything off.
+ */
+export declare function resolveExperimental(opts: {
+    stored: ExperimentalPrefs | undefined;
+    env: Record<string, string | undefined>;
+}): ExperimentalState;
+/** The one-line stderr notice for a launch with experimental features on; null when none are. */
+export declare function experimentalNotice(enabled: readonly ExperimentalId[]): string | null;
+/** The error for using an experimental flag or command while its feature is off. */
+export declare function gatedMessage(what: string, id: ExperimentalId): string;
+/** Thrown when a gated flag or command is used while its feature is off; the CLI exits 2. */
+export declare class ExperimentalGateError extends Error {
+    readonly exitCode = 2;
+    constructor(what: string, id: ExperimentalId);
+}
+/** Throw for the first use whose feature is off. */
+export declare function assertEnabled(uses: ReadonlyArray<{
+    what: string;
+    id: ExperimentalId;
+    used: boolean;
+}>, enabled: readonly ExperimentalId[]): void;
+/**
+ * The feature a launcher.toml key/value belongs to, when setting it only has an
+ * effect with that feature on. `goal_mode = off`, `context_handoff = false` and
+ * `slack_listen = false` are harmless either way.
+ */
+export declare function experimentalIdForConfigKey(key: string, value: string): ExperimentalId | undefined;
+/**
+ * The stderr lines for experimental settings a launch ignores because their feature
+ * is off: launcher.toml keys (`entries` as `[key, value]`) and MNEMOM_AGENT_CONTEXT_HANDOFF.
+ */
+export declare function ignoredSettingLines(opts: {
+    entries: ReadonlyArray<[string, string]>;
+    env: Record<string, string | undefined>;
+    enabled: readonly ExperimentalId[];
+}): string[];
+/** The features an existing launcher.toml already uses (the one-time migration). */
+export declare function featuresInUse(entries: ReadonlyArray<[string, string]>): ExperimentalId[];
+export interface MigrationDeps {
+    stored(): ExperimentalPrefs | undefined;
+    /** launcher.toml as `[key, value]` pairs; may throw on a malformed file. */
+    launcherEntries(): Array<[string, string]>;
+    persist(ids: ExperimentalId[]): void;
+    writeErr(line: string): void;
+}
+/** One-time notice for users who had implicit goal alignment by default (no goal_mode set). */
+export declare const IMPLICIT_NOW_OFF_NOTICE: string;
+/**
+ * First run after the upgrade that introduced experimental features: config.json has
+ * no `experimental` section yet, so turn on whatever the user's launcher.toml already
+ * uses, persist (an empty list too — the section's presence marks the migration
+ * done), and say once which were kept on. A malformed launcher.toml skips the
+ * migration this run (the launch reports that file itself) so it retries next time.
+ * Never throws.
+ */
+export declare function migrateExperimental(deps: MigrationDeps): ExperimentalId[] | null;
+/** The feature a launcher.toml key belongs to at all (for marking `mnemom agent config list`). */
+export declare function configKeyFeature(key: string): ExperimentalId | undefined;
+/**
+ * ` (experimental, off)` for a launcher.toml key whose feature is off, else "". With a
+ * `value`, only a setting that would take effect is marked (`goal_mode = off` is not).
+ */
+export declare function configKeyMark(key: string, value: string | undefined, enabled: readonly ExperimentalId[]): string;
+/** `null` when `id` is on, else the gated-use message. */
+export declare function gateCheck(what: string, id: ExperimentalId, enabled: readonly ExperimentalId[]): string | null;
+/**
+ * How a command's catch reports an error: a gated use prints its guidance bare and
+ * exits 2; anything else keeps the CLI's `Error: <message>` and exit 1.
+ */
+export declare function reportCliError(error: unknown): {
+    args: unknown[];
+    code: number;
+};