@mnemom/mnemom 0.17.3-next.5 → 0.17.3-next.6

package/dist/commands/agent-config.d.ts

@@ -13,8 +13,11 @@
  * Settable keys are the single source of truth in lib/code-config.ts CONFIG_KEYS.
  * The secret Anthropic key is NOT a config key — it lives in ~/.mnemom/launcher.json.
  */
+import { type ExperimentalId } from "../lib/experimental.js";
 /** Entry point for `mnemom agent config <verb> [args...]`. Throws on misuse. */
-export declare function agentConfigCommand(argv: string[]): Promise<void>;
+export declare function agentConfigCommand(argv: string[], opts?: {
+    enabled?: readonly ExperimentalId[];
+}): Promise<void>;
 /**
  * `$VISUAL` / `$EDITOR` is a program plus optional plain flags (`code --wait`, `emacsclient -t`),
  * never shell syntax: the value is split on whitespace and every token must be a bare

package/dist/commands/agent-config.js

@@ -16,15 +16,17 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { LAUNCHER_CONFIG_PATH, CONFIG_KEYS, configKeySpec, loadLauncherConfig, writeLauncherConfig, } from "../lib/launcher-config.js";
+import { loadExperimentalState } from "../lib/cli-config.js";
+import { configKeyMark } from "../lib/experimental.js";
 const out = (line = "") => console.log(line);
 const err = (line = "") => console.error(line);
 /** Entry point for `mnemom agent config <verb> [args...]`. Throws on misuse. */
-export async function agentConfigCommand(argv) {
+export async function agentConfigCommand(argv, opts = {}) {
     const [verb, ...rest] = argv;
     switch (verb) {
         case undefined:
         case "list":
-            return listConfig();
+            return listConfig(opts.enabled ?? loadExperimentalState().enabled);
         case "path":
             out(LAUNCHER_CONFIG_PATH);
             return;
@@ -40,7 +42,8 @@ export async function agentConfigCommand(argv) {
             throw new Error(`mnemom agent config: unknown verb '${verb}'. Use list | get | set | unset | edit | path.`);
     }
 }
-function listConfig() {
+/** Settings of experimental features that are off are marked `(experimental, off)`. */
+function listConfig(enabled) {
     const cfg = loadLauncherConfig();
     const rows = [];
     for (const spec of CONFIG_KEYS) {
@@ -54,13 +57,13 @@ function listConfig() {
         out("");
         out("Settable keys:");
         for (const spec of CONFIG_KEYS)
-            out(`  ${spec.key.padEnd(22)} ${spec.describe}`);
+            out(`  ${spec.key.padEnd(22)} ${spec.describe}${configKeyMark(spec.key, undefined, enabled)}`);
         return;
     }
     const width = Math.max(...rows.map(([k]) => k.length));
     out(`# ${LAUNCHER_CONFIG_PATH}`);
     for (const [k, v] of rows)
-        out(`${k.padEnd(width)}  ${v}`);
+        out(`${k.padEnd(width)}  ${v}${configKeyMark(k, v, enabled)}`);
 }
 function getConfig(key) {
     if (!key)

package/dist/commands/agent-session.d.ts

@@ -8,12 +8,13 @@
  *   1. a SESSION NAME — labels the session in traces and the claude.ai session
  *      list (defaults to the current folder's name).
  *
- * GOAL ALIGNMENT is not prompted for: it defaults to IMPLICIT. A bare launch
- * runs governed with the goal inferred from your own messages
- * (`x-mnemom-goal-mode: implicit`, no contract). `--goal` seals a one-line
- * contract instead (`x-mnemom-contract`); `--no-implicit` (or launcher.toml
- * `goal_mode = "off"`) turns alignment off — neither header is sent. The mode is
- * resolved upstream (`resolveImplicit`) and announced on the launch line.
+ * GOAL ALIGNMENT is not prompted for. `--goal` seals a one-line contract
+ * (`x-mnemom-contract`). Implicit alignment — the goal inferred from your own
+ * messages (`x-mnemom-goal-mode: implicit`, no contract) — is the experimental
+ * `implicit` feature: while it is on a bare launch runs implicit, while it is off
+ * (the default) a bare launch runs with alignment off. `--no-implicit` (or
+ * launcher.toml `goal_mode = "off"`) turns it off. The mode is resolved upstream
+ * (`resolveImplicit`) and announced on the launch line.
  *
  * Non-interactive runs (pipes, CI) never prompt — they get a clear error asking
  * for a name. Pure apart from the injected `ask` functions, so every arm is

package/dist/commands/agent-session.js

@@ -8,12 +8,13 @@
  *   1. a SESSION NAME — labels the session in traces and the claude.ai session
  *      list (defaults to the current folder's name).
  *
- * GOAL ALIGNMENT is not prompted for: it defaults to IMPLICIT. A bare launch
- * runs governed with the goal inferred from your own messages
- * (`x-mnemom-goal-mode: implicit`, no contract). `--goal` seals a one-line
- * contract instead (`x-mnemom-contract`); `--no-implicit` (or launcher.toml
- * `goal_mode = "off"`) turns alignment off — neither header is sent. The mode is
- * resolved upstream (`resolveImplicit`) and announced on the launch line.
+ * GOAL ALIGNMENT is not prompted for. `--goal` seals a one-line contract
+ * (`x-mnemom-contract`). Implicit alignment — the goal inferred from your own
+ * messages (`x-mnemom-goal-mode: implicit`, no contract) — is the experimental
+ * `implicit` feature: while it is on a bare launch runs implicit, while it is off
+ * (the default) a bare launch runs with alignment off. `--no-implicit` (or
+ * launcher.toml `goal_mode = "off"`) turns it off. The mode is resolved upstream
+ * (`resolveImplicit`) and announced on the launch line.
  *
  * Non-interactive runs (pipes, CI) never prompt — they get a clear error asking
  * for a name. Pure apart from the injected `ask` functions, so every arm is
@@ -65,11 +66,9 @@ export async function resolveSessionSetup(input, ask) {
     say(`  (Next time you can pass it directly: mnemom agent <name>.)`);
     const typed = await ask.askInput(`Session name [${fallback}]:`);
     const scenario = sanitizeAgentName(typed.trim()) || fallback;
-    // ── 2. goal alignment — resolved upstream, no prompt. Implicit is the DEFAULT
-    // (a bare launch runs governed with the goal inferred from your messages), so
-    // there is nothing to pick here: `--goal` seals a contract, the default (and
-    // `--implicit` / `goal_mode = "implicit"`) is implicit, and `--no-implicit` /
-    // `goal_mode = "off"` turns it off. The launch line announces the mode.
+    // ── 2. goal alignment — resolved upstream, no prompt: `--goal` seals a contract,
+    // the `implicit` experimental feature (when on) makes implicit the default, and
+    // `--no-implicit` / `goal_mode = "off"` turns it off. The launch line announces the mode.
     if (flagGoal) {
         return { scenario, goal: flagGoal, goalAlignment: "on", prompted: true };
     }

package/dist/commands/agent-sessions.js

@@ -180,6 +180,9 @@ export function buildShowView(local, remote, reason) {
     if (local.context_profile)
         launchBits.push(`context ${local.context_profile}`);
     L.push(fmt.label("launch:       ", launchBits.join(" · ")));
+    if (local.experimental?.length) {
+        L.push(fmt.label("experimental: ", local.experimental.join(", ")));
+    }
     L.push(fmt.label("conversation: ", local.conversation_id));
     const goalMode = resolveGoalMode(local, remote);
     L.push(fmt.label("goal alignment:", goalBadge(goalMode)));

package/dist/commands/agent.d.ts

@@ -25,6 +25,7 @@
  * line, or the proxy's stdin under RC). It is never logged, printed, or passed as
  * an argv value.
  */
+import { type ExperimentalId } from "../lib/experimental.js";
 import { type ContextProfile, type LaunchShape, type SealedContractEnvelope } from "../lib/agent.js";
 export interface AgentOptions {
     goal?: string;
@@ -87,6 +88,12 @@ export interface AgentOptions {
      * Undefined = the full default order.
      */
     keySource?: "env" | "store" | "prompt";
+    /**
+     * The experimental features on for this launch (`mnemom experimental`), already gated
+     * upstream in index.ts. Announced on stderr, recorded in the ledger, and sent in the
+     * session-config header's `experimental` array. Absent/empty ⇒ none of the three.
+     */
+    experimental?: readonly ExperimentalId[];
     passthrough?: string[];
     /** Print the resolved launch plan and exit — no key read, no spawn. */
     dryRun?: boolean;
@@ -245,4 +252,6 @@ export declare function printPlan(ctx: {
     contextProfile: ContextProfile;
     /** The decoded `x-mnemom-session-config` overlay (`buildSessionConfig`); empty ⇒ no header. */
     sessionConfig: Record<string, string>;
+    /** The experimental features on for this launch (the header's `experimental` array). */
+    experimental?: readonly string[];
 }): void;

package/dist/commands/agent.js

@@ -36,6 +36,7 @@ import { getAgentByName } from "../lib/api.js";
 import { LEDGER_FILE, appendSessionRecord, resolveRetentionDays, toLedgerContract, } from "../lib/agent-ledger.js";
 import { loadCliConfig } from "../lib/cli-config.js";
 import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
+import { experimentalNotice } from "../lib/experimental.js";
 import { fmt } from "../lib/format.js";
 import { askInput, askYesNo, isInteractive } from "../lib/prompt.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
@@ -60,9 +61,9 @@ function sayContextProfile(profile) {
 }
 /** Entry point for `mnemom agent [scenario]`. Throws on fatal misconfig. */
 export async function agentCommand(scenarioArg, options = {}) {
-    // ── session name + goal ── (a bare `mnemom agent` in a terminal asks for both,
-    // goal alignment is implicit by default (inferred from your messages); --goal
-    // seals a contract and --no-implicit turns it off — all resolved upstream.
+    // ── session name + goal ── (a bare `mnemom agent` in a terminal asks for the name;
+    // goal alignment is resolved upstream: --goal seals a contract, implicit alignment
+    // is on by default only while the `implicit` experimental feature is on.
     const session = await resolveSessionSetup({
         scenario: scenarioArg,
         goal: options.goal,
@@ -121,8 +122,14 @@ export async function agentCommand(scenarioArg, options = {}) {
         env,
     });
     const contextHandoff = resolveContextHandoff({ contextHandoff: options.contextHandoff, env });
+    const experimental = options.experimental ?? [];
     const sessionConfig = buildSessionConfig({ profile: contextProfile, contextHandoff });
-    const sessionConfigB64 = buildSessionConfigB64({ profile: contextProfile, contextHandoff });
+    const sessionConfigB64 = buildSessionConfigB64({
+        profile: contextProfile,
+        contextHandoff,
+        experimental,
+    });
+    const expNotice = experimentalNotice(experimental);
     // ── which CLI executable (name or full path) ── resolve GRACEFULLY: if it's not
     // found we don't crash with a technical error — we ask for the path at launch.
     let cli;
@@ -163,7 +170,10 @@ export async function agentCommand(scenarioArg, options = {}) {
             cli: planCli,
             contextProfile,
             sessionConfig,
+            experimental,
         });
+        if (expNotice)
+            say(expNotice);
         if (previewShape === "remote-control") {
             say("mnemom agent: the plan shows Remote Control because this machine can run it; the real launch uses it only if your account is entitled (internal Mnemom accounts), else terminal-only.");
         }
@@ -290,6 +300,8 @@ export async function agentCommand(scenarioArg, options = {}) {
         contextProfile,
     });
     logLaunch({ shape, door, agent, conversationId, cellNote, envelope, goalMode, cli });
+    if (expNotice)
+        say(expNotice);
     say(goalAlignmentLine(goalAlignmentMode(envelope, goalMode)));
     sayContextProfile(contextProfile);
     // ── handoff MCP tool (MNE-7564) ── OFF by default: absent/false ⇒ handoffMcpConfigPath stays
@@ -396,6 +408,7 @@ export async function recordSessionLaunch(ctx) {
         goal_mode: goalAlignmentMode(ctx.envelope, ctx.goalMode),
         context_profile: ctx.contextProfile,
         cc_session_id: ctx.ccSessionId ?? null,
+        ...(ctx.options.experimental?.length ? { experimental: [...ctx.options.experimental] } : {}),
     }, {
         dir: MNEMOM_DIR,
         now: () => new Date(),
@@ -1110,6 +1123,8 @@ export function printPlan(ctx) {
         for (const [k, v] of overlay)
             L.push(`    ${k}=${v}`);
     }
+    if (ctx.experimental?.length)
+        L.push(`  experimental:  ${ctx.experimental.join(", ")}`);
     if (ctx.envelope) {
         L.push(`  contract:      ${ctx.envelope.canonical}`);
         L.push(`  contract sha:  ${ctx.envelope.sha}`);

package/dist/commands/experimental.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `mnemom experimental list [--json] | enable <id> | disable <id>` — turn experimental
+ * features on and off (registry: lib/experimental.ts; stored in ~/.mnemom/config.json).
+ */
+import { type ExperimentalId, type ExperimentalPrefs } from "../lib/experimental.js";
+export interface ExperimentalDeps {
+    stored(): ExperimentalPrefs | undefined;
+    persist(ids: ExperimentalId[]): void;
+    env: Record<string, string | undefined>;
+    log(line: string): void;
+}
+export declare function experimentalListCommand(opts?: {
+    json?: boolean;
+}, deps?: ExperimentalDeps): void;
+export declare function experimentalEnableCommand(id: string | undefined, deps?: ExperimentalDeps): void;
+export declare function experimentalDisableCommand(id: string | undefined, deps?: ExperimentalDeps): void;
+/** The one-time migration (lib/experimental.ts migrateExperimental) against the real files. */
+export declare function runExperimentalMigration(): void;

package/dist/commands/experimental.js

@@ -0,0 +1,78 @@
+/**
+ * `mnemom experimental list [--json] | enable <id> | disable <id>` — turn experimental
+ * features on and off (registry: lib/experimental.ts; stored in ~/.mnemom/config.json).
+ */
+import { EXPERIMENTAL_CONTRACT, EXPERIMENTAL_ENV, EXPERIMENTAL_FEATURES, EXPERIMENTAL_IDS, isExperimentalId, migrateExperimental, resolveExperimental, } from "../lib/experimental.js";
+import { loadCliConfig, setExperimentalEnabled } from "../lib/cli-config.js";
+import { launcherEntries, loadLauncherConfig } from "../lib/launcher-config.js";
+function defaultDeps() {
+    return {
+        stored: () => loadCliConfig().experimental,
+        persist: (ids) => setExperimentalEnabled(ids),
+        env: process.env,
+        log: (line) => console.log(line),
+    };
+}
+function requireId(id, verb) {
+    if (!id)
+        throw new Error(`mnemom experimental ${verb}: an <id> is required.`);
+    const v = id.trim().toLowerCase();
+    if (!isExperimentalId(v)) {
+        throw new Error(`Unknown experimental feature '${id}'. Valid ids: ${EXPERIMENTAL_IDS.join(", ")}.`);
+    }
+    return v;
+}
+export function experimentalListCommand(opts = {}, deps = defaultDeps()) {
+    const state = resolveExperimental({ stored: deps.stored(), env: deps.env });
+    const rows = EXPERIMENTAL_FEATURES.map((f) => ({
+        id: f.id,
+        enabled: state.enabled.includes(f.id),
+        summary: f.summary,
+        since: f.since,
+        gates: f.gates,
+    }));
+    if (opts.json) {
+        deps.log(JSON.stringify({ contract: EXPERIMENTAL_CONTRACT, source: state.source, features: rows }, null, 2));
+        return;
+    }
+    deps.log(EXPERIMENTAL_CONTRACT);
+    deps.log("");
+    const width = Math.max(...rows.map((r) => r.id.length));
+    for (const r of rows) {
+        deps.log(`${r.enabled ? "on " : "off"}  ${r.id.padEnd(width)}  ${r.summary}`);
+    }
+    deps.log("");
+    if (state.source === "env") {
+        deps.log(`(set by ${EXPERIMENTAL_ENV} in your environment — it overrides config.json)`);
+    }
+    deps.log("Turn one on with `mnemom experimental enable <id>`.");
+}
+function toggle(verb, rawId, deps) {
+    const id = requireId(rawId, verb);
+    const current = new Set(resolveExperimental({ stored: deps.stored(), env: {} }).enabled);
+    if (verb === "enable")
+        current.add(id);
+    else
+        current.delete(id);
+    const next = EXPERIMENTAL_IDS.filter((x) => current.has(x));
+    deps.persist(next);
+    deps.log(verb === "enable" ? `${id}: on. ${EXPERIMENTAL_CONTRACT}` : `${id}: off.`);
+    if ((deps.env[EXPERIMENTAL_ENV] ?? "").trim()) {
+        deps.log(`note: ${EXPERIMENTAL_ENV} is set in your environment and overrides this.`);
+    }
+}
+export function experimentalEnableCommand(id, deps = defaultDeps()) {
+    toggle("enable", id, deps);
+}
+export function experimentalDisableCommand(id, deps = defaultDeps()) {
+    toggle("disable", id, deps);
+}
+/** The one-time migration (lib/experimental.ts migrateExperimental) against the real files. */
+export function runExperimentalMigration() {
+    migrateExperimental({
+        stored: () => loadCliConfig().experimental,
+        launcherEntries: () => launcherEntries(loadLauncherConfig()),
+        persist: (ids) => setExperimentalEnabled(ids),
+        writeErr: (line) => void process.stderr.write(line),
+    });
+}

package/dist/index.d.ts

@@ -7,4 +7,4 @@ 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 declare function runEntrypoint(argv?: string[]): void;
+export declare function runEntrypoint(argv?: string[], migrate?: () => void): void;

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";
@@ -103,6 +106,19 @@ program
 // → 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,8 +135,8 @@ 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)")
@@ -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

@@ -324,6 +324,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 +353,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 +442,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 +454,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

@@ -513,6 +513,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 +540,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 +600,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 +613,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;
+};

package/dist/lib/experimental.js

@@ -0,0 +1,226 @@
+/**
+ * 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 const EXPERIMENTAL_FEATURES = [
+    {
+        id: "context-handoff",
+        summary: "Register the `handoff(note)` MCP tool and turn on the gateway's context-handoff capability for the session",
+        since: "0.17.3",
+        gates: {
+            flags: ["--context-handoff"],
+            configKeys: ["context_handoff"],
+            commands: [],
+            env: ["MNEMOM_AGENT_CONTEXT_HANDOFF"],
+        },
+    },
+    {
+        id: "slack",
+        summary: "Attach the Slack channel to a session: messages addressed to it arrive in it, and it can reply",
+        since: "0.17.3",
+        gates: {
+            flags: ["--slack"],
+            configKeys: ["slack_channel", "slack_listen", "slack_allow"],
+            commands: ["mnemom agent slack"],
+            env: [],
+        },
+    },
+    {
+        id: "implicit",
+        summary: "Implicit goal alignment: the gateway infers the goal from your messages and revises it as you steer",
+        since: "0.17.3",
+        gates: {
+            flags: ["--implicit"],
+            configKeys: ["goal_mode = implicit"],
+            commands: ["mnemom agent goal show|pin|reset"],
+            env: [],
+        },
+    },
+];
+export const EXPERIMENTAL_IDS = EXPERIMENTAL_FEATURES.map((f) => f.id);
+export const EXPERIMENTAL_ENV = "MNEMOM_EXPERIMENTAL";
+export const EXPERIMENTAL_CONTRACT = "Experimental features may change or be removed in any release, with no deprecation period.";
+export function isExperimentalId(value) {
+    return EXPERIMENTAL_IDS.includes(value);
+}
+/** Registry order, deduplicated, unknown ids dropped. */
+function normalize(ids) {
+    const set = new Set(ids);
+    return EXPERIMENTAL_IDS.filter((id) => set.has(id));
+}
+/**
+ * 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 function resolveExperimental(opts) {
+    const raw = (opts.env[EXPERIMENTAL_ENV] ?? "").trim();
+    if (raw !== "") {
+        const tokens = raw
+            .split(",")
+            .map((t) => t.trim().toLowerCase())
+            .filter(Boolean);
+        if (tokens.includes("all"))
+            return { enabled: [...EXPERIMENTAL_IDS], source: "env", unknown: [] };
+        const listed = tokens.filter((t) => t !== "none");
+        return {
+            enabled: normalize(listed),
+            source: "env",
+            unknown: listed.filter((t) => !isExperimentalId(t)),
+        };
+    }
+    const stored = Array.isArray(opts.stored?.enabled) ? opts.stored.enabled.map(String) : undefined;
+    if (stored === undefined)
+        return { enabled: [], source: "default", unknown: [] };
+    return {
+        enabled: normalize(stored),
+        source: "config",
+        unknown: stored.filter((t) => !isExperimentalId(t)),
+    };
+}
+/** The one-line stderr notice for a launch with experimental features on; null when none are. */
+export function experimentalNotice(enabled) {
+    if (enabled.length === 0)
+        return null;
+    return `mnemom agent: experimental: ${enabled.join(", ")} — may change or break without notice`;
+}
+/** The error for using an experimental flag or command while its feature is off. */
+export function gatedMessage(what, id) {
+    return `${what} is experimental. Turn it on with \`mnemom experimental enable ${id}\`.`;
+}
+/** Thrown when a gated flag or command is used while its feature is off; the CLI exits 2. */
+export class ExperimentalGateError extends Error {
+    exitCode = 2;
+    constructor(what, id) {
+        super(gatedMessage(what, id));
+        this.name = "ExperimentalGateError";
+    }
+}
+/** Throw for the first use whose feature is off. */
+export function assertEnabled(uses, enabled) {
+    for (const u of uses) {
+        if (u.used && !enabled.includes(u.id))
+            throw new ExperimentalGateError(u.what, u.id);
+    }
+}
+/**
+ * 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 function experimentalIdForConfigKey(key, value) {
+    switch (key) {
+        case "slack_channel":
+        case "slack_allow":
+            return "slack";
+        case "slack_listen":
+            return value === "true" ? "slack" : undefined;
+        case "context_handoff":
+            return value === "true" ? "context-handoff" : undefined;
+        case "goal_mode":
+            return value === "implicit" ? "implicit" : undefined;
+        default:
+            return undefined;
+    }
+}
+/** Is an env value one of the truthy spellings resolveContextHandoff accepts? */
+function truthy(raw) {
+    return ["1", "true", "on", "yes"].includes((raw ?? "").trim().toLowerCase());
+}
+/**
+ * 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 function ignoredSettingLines(opts) {
+    const lines = [];
+    for (const [key, value] of opts.entries) {
+        const id = experimentalIdForConfigKey(key, value);
+        if (id && !opts.enabled.includes(id)) {
+            lines.push(`mnemom agent: ignoring launcher.toml ${gatedMessage(key, id)}`);
+        }
+    }
+    if (truthy(opts.env.MNEMOM_AGENT_CONTEXT_HANDOFF) && !opts.enabled.includes("context-handoff")) {
+        lines.push(`mnemom agent: ignoring ${gatedMessage("MNEMOM_AGENT_CONTEXT_HANDOFF", "context-handoff")}`);
+    }
+    return lines;
+}
+/** The features an existing launcher.toml already uses (the one-time migration). */
+export function featuresInUse(entries) {
+    return normalize(entries.flatMap(([k, v]) => {
+        const id = experimentalIdForConfigKey(k, v);
+        return id ? [id] : [];
+    }));
+}
+/** One-time notice for users who had implicit goal alignment by default (no goal_mode set). */
+export const IMPLICIT_NOW_OFF_NOTICE = "mnemom: implicit goal alignment is now experimental and OFF by default (it used to be on). " +
+    "Turn it back on with `mnemom experimental enable implicit`, or seal a goal per launch with --goal.\n";
+/**
+ * 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 function migrateExperimental(deps) {
+    try {
+        if (deps.stored() !== undefined)
+            return null;
+        const entries = deps.launcherEntries();
+        const ids = featuresInUse(entries);
+        deps.persist(ids);
+        if (ids.length > 0) {
+            deps.writeErr(`mnemom: ${ids.join(", ")} ${ids.length === 1 ? "is" : "are"} now experimental and kept on because your launcher.toml uses ${ids.length === 1 ? "it" : "them"} — see \`mnemom experimental list\`.\n`);
+        }
+        // Implicit was the unconfigured DEFAULT, so most users relied on it without a
+        // goal_mode entry. Don't let it switch off silently for them: say so once.
+        const optedOut = entries.some(([k, v]) => k === "goal_mode" && v === "off");
+        if (!ids.includes("implicit") && !optedOut)
+            deps.writeErr(IMPLICIT_NOW_OFF_NOTICE);
+        return ids;
+    }
+    catch {
+        return null;
+    }
+}
+/** The feature a launcher.toml key belongs to at all (for marking `mnemom agent config list`). */
+export function configKeyFeature(key) {
+    if (key === "slack_channel" || key === "slack_listen" || key === "slack_allow")
+        return "slack";
+    if (key === "context_handoff")
+        return "context-handoff";
+    if (key === "goal_mode")
+        return "implicit";
+    return 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 function configKeyMark(key, value, enabled) {
+    const id = value === undefined ? configKeyFeature(key) : experimentalIdForConfigKey(key, value);
+    return id && !enabled.includes(id) ? " (experimental, off)" : "";
+}
+/** `null` when `id` is on, else the gated-use message. */
+export function gateCheck(what, id, enabled) {
+    return enabled.includes(id) ? null : gatedMessage(what, id);
+}
+/**
+ * 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 function reportCliError(error) {
+    if (error instanceof ExperimentalGateError)
+        return { args: [error.message], code: 2 };
+    return { args: ["Error:", error instanceof Error ? error.message : error], code: 1 };
+}

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

@@ -15,6 +15,7 @@
  * resolvers in lib/code.ts keep the built-in default as the final fallback);
  * the caller folds the plain-value settings under the CLI flags.
  */
+import type { ExperimentalId } from "./experimental.js";
 import { type ContextProfile, type GoalModeDefault, type LaunchShape } from "./agent.js";
 /** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
 export declare const LAUNCHER_CONFIG_PATH: string;
@@ -98,3 +99,11 @@ export declare function writeLauncherConfig(cfg: LauncherConfig, path?: string):
  * (see resolveLaunchShape): terminal→"0", remote-control→"1", server→"server".
  */
 export declare function applyConfigToEnv(cfg: LauncherConfig, env?: NodeJS.ProcessEnv): void;
+/** The set keys of `cfg` as `[key, value]` pairs (CONFIG_KEYS order, values stringified). */
+export declare function launcherEntries(cfg: LauncherConfig): Array<[string, string]>;
+/**
+ * `cfg` without the settings of experimental features that are off (a copy; `cfg` is
+ * untouched): `slack_*` while `slack` is off, `context_handoff` while `context-handoff` is
+ * off, and `goal_mode = implicit` while `implicit` is off (`goal_mode = off` is kept).
+ */
+export declare function withoutDisabledExperimental(cfg: LauncherConfig, enabled: readonly ExperimentalId[]): LauncherConfig;

package/dist/lib/launcher-config.js

@@ -402,3 +402,28 @@ export function applyConfigToEnv(cfg, env = process.env) {
         env.MNEMOM_AGENT_CONTEXT_PROFILE = cfg.contextProfile;
     }
 }
+/** The set keys of `cfg` as `[key, value]` pairs (CONFIG_KEYS order, values stringified). */
+export function launcherEntries(cfg) {
+    return CONFIG_KEYS.flatMap((spec) => {
+        const v = spec.get(cfg);
+        return v === undefined ? [] : [[spec.key, String(v)]];
+    });
+}
+/**
+ * `cfg` without the settings of experimental features that are off (a copy; `cfg` is
+ * untouched): `slack_*` while `slack` is off, `context_handoff` while `context-handoff` is
+ * off, and `goal_mode = implicit` while `implicit` is off (`goal_mode = off` is kept).
+ */
+export function withoutDisabledExperimental(cfg, enabled) {
+    const out = { ...cfg };
+    if (!enabled.includes("slack")) {
+        delete out.slackChannel;
+        delete out.slackListen;
+        delete out.slackAllow;
+    }
+    if (!enabled.includes("context-handoff"))
+        delete out.contextHandoff;
+    if (!enabled.includes("implicit") && out.goalMode === "implicit")
+        delete out.goalMode;
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.3-next.5",
+  "version": "0.17.3-next.6",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {