@mnemom/mnemom 0.17.6-next.0 → 0.17.6-next.1

package/README.md

@@ -148,6 +148,47 @@ gateway support: a gateway without it drops both keys (they are echoed back in
 `x-mnemom-session-config-dropped`) and the session behaves exactly as with the setting off. `--no-compaction-intercept` turns it off for
 one launch.
 
+#### Compaction target (`--compact-at`)
+
+`--compact-at <n|200k|1m|off>` lets you play with WHEN the gateway pulls this session's own
+compaction point forward, instead of leaving it entirely to Claude Code's normal 1M-window
+schedule. **Unset, `1m`, or `off` all mean no target** — Claude Code runs its normal 1M window
+and the launcher sends nothing new (byte-identical to a launch without this setting at all). A
+token count below 1M (k/m suffixes OK, e.g. `200k` or `350000`, from 50k up to just under 1M)
+arms a gateway-side target for this session: the per-session config header carries
+`GATEWAY_USAGE_REAL_SIZE=on` + `GATEWAY_COMPACTION_INTERCEPT=on` (the two keys a target needs to
+arm — the same pair `--compaction-intercept` turns on) plus
+`GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS=<n>`. It never sends `GATEWAY_COMPACTION_REFOLD` — that
+costlier opt-in stays separate. It never touches Claude Code's own autocompact env or window.
+
+A target only works **below Claude Code's own compaction point for the window the session runs
+on**: 967k on a 1M window, 167k on a 200k window (Haiku, models with no 1M window, or
+`CLAUDE_CODE_DISABLE_1M_CONTEXT`). At or above that point the gateway ignores it and says
+nothing back, so the launcher prints a warning at launch (and in `--dry-run`) when it can tell
+the target will be ignored, and a note when it can't tell the window (a passthrough `-- --model`,
+a resume, or a CLI other than Claude Code).
+
+**Arming a target needs the same opt-in as `--compaction-intercept`** (`mnemom experimental
+enable compaction-intercept`) — a target arms the identical pair of gateway keys, so it needs
+the identical gate; the flag itself stays visible in `--help` (it's the knob you asked for), only
+actually _arming_ a target is gated. Passing `--no-compaction-intercept` together with an armed
+`--compact-at` is refused outright (they contradict: the target cannot arm without the intercept
+you just turned off).
+
+Set it per launch, as a standing default, or in the environment (flag > env > `launcher.toml` >
+default):
+
+```bash
+mnemom experimental enable compaction-intercept # one-time opt-in
+mnemom agent my-task --compact-at 200k          # this launch only
+mnemom agent config set compact_at 200k         # persists in ~/.mnemom/launcher.toml
+export MNEMOM_COMPACT_AT=200k                   # for every launch in this shell
+```
+
+`--dry-run` prints the resolved target (`compaction: gateway at 200k` or `compaction: Claude
+Code default (1M)`) and, when a target is set, the decoded session-config keys; the session
+ledger records the effective value.
+
 ## How It Works
 
 ```

package/dist/commands/agent-config.js

@@ -199,6 +199,9 @@ function deleteKey(cfg, key) {
         case "context_profile":
             delete cfg.contextProfile;
             break;
+        case "compact_at":
+            delete cfg.compactAt;
+            break;
         case "auth":
             delete cfg.auth;
             break;

package/dist/commands/agent.d.ts

@@ -70,6 +70,14 @@ export interface AgentOptions {
      * `balanced`. `--no-context` is `off`; combined with balanced|aggressive the launch refuses.
      */
     contextProfile?: ContextProfile;
+    /**
+     * The gateway compaction target this launch runs under (`--compact-at`), already parsed by
+     * commander's argParser: `undefined` = the flag was not given (fall back to
+     * `MNEMOM_COMPACT_AT` / default), `null` = an explicit `1m`/`off` (no target, same as
+     * default), a number = tokens. Below 1M it arms `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS` +
+     * the #2216 intercept/real-size keys for this session only; unset/null sends nothing new.
+     */
+    compactAt?: number | null;
     /** context-hint seed default: commander `--no-context-hint` sets this false. */
     contextHint?: boolean;
     /** Attach the Slack channel server (`--slack`; lib/slack-launch.ts). */
@@ -189,6 +197,8 @@ export declare function recordSessionLaunch(ctx: {
     ccSessionId?: string | null;
     /** The resolved context profile this launch runs under. */
     contextProfile: ContextProfile;
+    /** The resolved compaction target this launch runs under (`resolveCompactAt`). */
+    compactAt: number | null;
 }): Promise<void>;
 /** The real I/O behind a subscription launch's Mnemom key (lib/subscription-login.ts). */
 export declare function defaultMnemomKeyDeps(storePath?: string): MnemomKeyDeps;
@@ -344,6 +354,8 @@ export declare function printPlan(ctx: {
     cli: ResolvedCli;
     /** The resolved context profile (`resolveContextProfile`). */
     contextProfile: ContextProfile;
+    /** The resolved compaction target (`resolveCompactAt`); `null` = no target (default). */
+    compactAt: number | null;
     /** 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). */

package/dist/commands/agent.js

@@ -45,7 +45,7 @@ import { authConfigured, chooseAuth, detectClaudeLogin, readClaudeLoginState, }
 import { requireConsoleKey, readConsoleKey } from "../lib/console-key.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
 import { AgentIdentityMismatchError, defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.js";
-import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, applyGatewayHintHeaders, resolveCompactionIntercept, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
+import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, assertCompactAtCompatible, compactAtWindowWarning, describeCompactAt, launchWindow, resolveCompactAt, applyGatewayHintHeaders, resolveCompactionIntercept, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
 import { LAUNCHER_STORE_PATH, mergeStore } from "../lib/launcher-store.js";
 import { slackChannelArgs } from "../lib/slack-launch.js";
 /** The CLI's own provider-key store (zero 1Password): ~/.mnemom/launcher.json, 0600. */
@@ -65,6 +65,37 @@ function sayContextProfile(profile) {
         say("mnemom agent: context profile aggressive — the gateway folds earlier and keeps a tighter working set.");
     }
 }
+/**
+ * The one-line launch-banner note for the resolved compaction target (`resolveCompactAt`):
+ * printed on EVERY launch (dry-run and real), the same way `door`/`conversation` are — there is
+ * always a value (default or an explicit target), unlike the context-profile note above which
+ * is silent for the common case.
+ */
+function sayCompactAt(compactAt, window) {
+    say(`mnemom agent: compaction: ${describeCompactAt(compactAt)}`);
+    // A target at/above the window's own compaction point is ignored by the gateway, which never
+    // says so back — tell the user here instead of reporting it as if it took effect.
+    const warning = compactAtWindowWarning(compactAt, window);
+    if (warning)
+        say(warning);
+}
+/**
+ * The launch's window (resolveWindowModel) — Claude Code only: it is the adapter that reads the
+ * window off the model id. `null` for any other CLI (or none resolved).
+ */
+function windowModelFor(options, cli) {
+    return cli?.name === "claude"
+        ? resolveWindowModel({
+            explicit: options.model,
+            passthrough: options.passthrough ?? [],
+            env: process.env,
+            settings: () => readCcSettings({
+                cwd: process.cwd(),
+                configDir: (process.env.CLAUDE_CONFIG_DIR ?? "").trim() || join(homedir(), ".claude"),
+            }),
+        })
+        : null;
+}
 /** 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 the name;
@@ -159,16 +190,27 @@ export async function agentCommand(scenarioArg, options = {}) {
         compactionIntercept: options.compactionIntercept,
         env,
     });
+    // Compaction target: `--compact-at` (undefined ⇒ MNEMOM_COMPACT_AT, which
+    // applyConfigToEnv already folded the `compact_at` setting under), else null (no target —
+    // Claude Code's own 1M window, nothing new sent). See lib/agent.ts for the full contract.
+    const compactAt = resolveCompactAt({ compactAt: options.compactAt, env });
+    // An explicit --no-compaction-intercept (compactionIntercept === false, never the mere
+    // absence of --compaction-intercept) conflicts with an armed --compact-at: the target
+    // cannot arm without the intercept it just turned off. Refuse rather than silently pick
+    // a side.
+    assertCompactAtCompatible({ compactionIntercept: options.compactionIntercept, compactAt });
     const experimental = options.experimental ?? [];
     const sessionConfig = buildSessionConfig({
         profile: contextProfile,
         contextHandoff,
         compactionIntercept,
+        compactAt,
     });
     const sessionConfigB64 = buildSessionConfigB64({
         profile: contextProfile,
         contextHandoff,
         compactionIntercept,
+        compactAt,
         experimental,
     });
     const expNotice = experimentalNotice(experimental);
@@ -212,6 +254,7 @@ export async function agentCommand(scenarioArg, options = {}) {
             yolo,
             cli: planCli,
             contextProfile,
+            compactAt,
             sessionConfig,
             experimental,
         });
@@ -227,6 +270,7 @@ export async function agentCommand(scenarioArg, options = {}) {
             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.");
         }
         sayContextProfile(contextProfile);
+        sayCompactAt(compactAt, launchWindow(windowModelFor(options, cli)));
         if (contextHandoff) {
             say("mnemom agent: context handoff ON (experimental) — the `handoff` MCP tool would be registered.");
         }
@@ -389,17 +433,7 @@ export async function agentCommand(scenarioArg, options = {}) {
     // window suffix and supports 1M (resolveWindowModel); an explicit choice — the
     // CLAUDE_CODE_DISABLE_1M_CONTEXT opt-out, a passthrough `-- --model`, a suffixed id — is kept.
     // Claude Code only: it is the adapter that reads the window off the model id.
-    const win = cli.name === "claude"
-        ? resolveWindowModel({
-            explicit: options.model,
-            passthrough: options.passthrough ?? [],
-            env: process.env,
-            settings: () => readCcSettings({
-                cwd: process.cwd(),
-                configDir: (process.env.CLAUDE_CONFIG_DIR ?? "").trim() || join(homedir(), ".claude"),
-            }),
-        })
-        : null;
+    const win = windowModelFor(options, cli);
     const launchOptions = win?.reason === "one-m" ? { ...options, model: win.model } : options;
     if (win?.reason === "one-m") {
         say(`mnemom agent: model ${win.from} → ${win.model} (1M context window; set ${DISABLE_1M_ENV}=1, or pass the model as \`-- --model <id>\`, to keep the standard window).`);
@@ -418,12 +452,14 @@ export async function agentCommand(scenarioArg, options = {}) {
         goalMode,
         ccSessionId: cc.id,
         contextProfile,
+        compactAt,
     });
     logLaunch({ shape, door, agent, conversationId, cellNote, envelope, goalMode, cli });
     if (expNotice)
         say(expNotice);
     say(goalAlignmentLine(goalAlignmentMode(envelope, goalMode)));
     sayContextProfile(contextProfile);
+    sayCompactAt(compactAt, launchWindow(win));
     if (compactionIntercept)
         say(COMPACTION_INTERCEPT_NOTE);
     // ── handoff MCP tool (MNE-7564) ── OFF by default: absent/false ⇒ handoffMcpConfigPath stays
@@ -651,6 +687,7 @@ export async function recordSessionLaunch(ctx) {
         contract: toLedgerContract(ctx.envelope?.contract ?? null),
         goal_mode: goalAlignmentMode(ctx.envelope, ctx.goalMode),
         context_profile: ctx.contextProfile,
+        compact_at: ctx.compactAt,
         cc_session_id: ctx.ccSessionId ?? null,
         ...(ctx.options.experimental?.length ? { experimental: [...ctx.options.experimental] } : {}),
     }, {
@@ -1527,6 +1564,7 @@ export function printPlan(ctx) {
     L.push(`  conversation:  ${ctx.conversationId}`);
     L.push(`  yolo:          ${ctx.yolo ? "on (--dangerously-skip-permissions)" : "off"}`);
     L.push(`  context:       ${ctx.contextProfile}`);
+    L.push(`  compaction:    ${describeCompactAt(ctx.compactAt)}`);
     const overlay = Object.entries(ctx.sessionConfig);
     if (overlay.length > 0) {
         L.push(`  session config (${SESSION_CONFIG_HEADER}):`);

package/dist/index.js

@@ -33,7 +33,7 @@ import { applyConfigToEnv, launcherEntries, loadLauncherConfig, withoutDisabledE
 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 { parseCompactAt, parseContextProfile, resolveImplicit, } from "./lib/agent.js";
 import { wrapCommand } from "./commands/wrap.js";
 import { onboardCommand } from "./commands/onboard.js";
 import { skillsListCommand, skillsDescribeCommand } from "./commands/skills.js";
@@ -124,10 +124,24 @@ const collectRepeatable = (value, previous) => {
     previous.push(value);
     return previous;
 };
+/**
+ * `mnemom agent help [verb]`: a visible commander sub-verb (`list`, `sessions`, …) prints
+ * its own help; anything else — no verb, or an in-action verb like `setup`/`doctor`/
+ * `config` that the agent help itself documents — prints the agent help.
+ */
+function printAgentHelp(verb) {
+    const sub = verb
+        ? agentCmd
+            .createHelp()
+            .visibleCommands(agentCmd)
+            .find((c) => c.name() === verb || c.aliases().includes(verb))
+        : undefined;
+    (sub ?? agentCmd).outputHelp();
+}
 const agentCmd = program
     .command("agent [session] [passthrough...]")
     .description("Launch your governed agent (Claude Code in v1) through the Mnemom gateway — governed identity + optional sealed goal contract. Plain `mnemom agent` asks for a session name and an optional goal. " +
-    "Sub-verbs: `setup` provisions your governed agent; `doctor` preflights prerequisites; `config …` manages persistent settings (~/.mnemom/launcher.toml); `invite <token>` redeems a Mnemom Agent invitation; `list` / `claim` / `move` manage the agents in your orgs; `sessions` lists your past launches and `show [ref]` merges one with its live goal state.")
+    "Sub-verbs: `setup` provisions your governed agent; `doctor` preflights prerequisites; `config …` manages persistent settings (~/.mnemom/launcher.toml); `invite <token>` redeems a Mnemom Agent invitation; `list` / `claim` / `move` manage the agents in your orgs; `sessions` lists your past launches and `show [ref]` merges one with its live goal state; `help [verb]` prints help and never launches.")
     .option("--goal <statement>", "Contract goal statement (required if any contract flag is given)")
     .option("--requirement <text>", "Contract requirement (repeatable)", collectRepeatable, [])
     .option("--allow <glob>", "Allowed path/glob (repeatable)", collectRepeatable, [])
@@ -170,6 +184,22 @@ const agentCmd = program
     catch (e) {
         throw new InvalidArgumentError(e.message);
     }
+}))
+    .addOption(new Option("--compact-at <n|200k|1m|off>", 'Play with WHEN the gateway pulls this session\'s own compaction point forward, instead of leaving it to Claude Code\'s normal 1M-window schedule. A token count below 1M (k/m suffix OK, e.g. "200k") arms the gateway\'s compaction target for this session; unset, "1m" or "off" all mean no target — Claude Code runs its normal 1M window and nothing new is sent. Arming a target needs `mnemom experimental enable compaction-intercept` (the same opt-in --compaction-intercept uses — a target arms the identical gateway keys) and is refused if you also pass --no-compaction-intercept. Never touches Claude Code\'s own autocompact env/window. Also: config key compact_at, env MNEMOM_COMPACT_AT.').argParser((v) => {
+    // Validate with the same parser the other two surfaces (MNEMOM_COMPACT_AT, launcher.toml
+    // compact_at) use, but return the validated RAW string rather than parseCompactAt's
+    // `number | null` — commander's own option-value handling coerces a parseArg return of
+    // `null` to `''` for a mandatory-argument option (Command.js's `handleOptionValue`: any
+    // `val == null` after parseArg falls through to the "not normal" `val = ''` branch), which
+    // would turn "1m"/"off" into a lone empty string instead of "no target". The real
+    // `number | null` conversion happens once, right after commander hands back `opts.compactAt`.
+    try {
+        parseCompactAt(v, "--compact-at");
+    }
+    catch (e) {
+        throw new InvalidArgumentError(e.message);
+    }
+    return v;
 }))
     .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")
@@ -179,6 +209,13 @@ const agentCmd = program
     .option("--first-run", "Show the first-run look again: what Mnemom would have saved on your last 30 days of Claude Code (runs on this machine, read-only, nothing uploaded) — then exit")
     .action(async (scenario, passthrough, opts) => {
     try {
+        // `help` is reserved: `mnemom agent help [verb]` prints help and never launches
+        // (nor redeems an --invite). Without this, `help` was taken as a session name and
+        // the verb passed through to Claude Code as the opening prompt.
+        if (scenario === "help") {
+            printAgentHelp(passthrough[0]);
+            return;
+        }
         // Invitation redemption — `mnemom agent invite <token>` (sub-verb) or
         // `mnemom agent --invite <token> [session]` — composes with the launch in
         // runAgentInvocation (commands/code-invite.ts, unit-tested); everything below
@@ -195,6 +232,10 @@ const agentCmd = program
     }
     async function launchAgent(scenario) {
         const experimental = loadExperimentalState().enabled;
+        // The one place the flag's raw string becomes `number | null` (see the argParser's
+        // comment for why commander can't carry `null` through parseArg directly). Already
+        // validated by the argParser, so this never throws.
+        const compactAtFlag = opts.compactAt !== undefined ? parseCompactAt(opts.compactAt, "--compact-at") : undefined;
         // Sub-verb: `mnemom agent config …` manages persistent settings and never
         // launches. (A scenario literally named "config" is reserved for this.)
         if (scenario === "config") {
@@ -223,6 +264,14 @@ const agentCmd = program
                 id: "compaction-intercept",
                 used: opts.compactionIntercept === true,
             },
+            // --compact-at arms the SAME two gateway keys --compaction-intercept does
+            // (buildSessionConfig ORs them) — it needs the identical opt-in, not a free pass
+            // around it. `null`/unset ("1m"/"off"/no flag) is not a target, so it never gates.
+            {
+                what: "--compact-at",
+                id: "compaction-intercept",
+                used: typeof compactAtFlag === "number",
+            },
         ], experimental);
         if (opts.gateway)
             process.env.MNEMOM_AGENT_GATEWAY = opts.gateway;
@@ -306,6 +355,10 @@ const agentCmd = program
             slack: opts.slack ?? cfg.slackListen,
             context: opts.context,
             contextProfile: opts.contextProfile,
+            // Same gate: off ⇒ an explicit null (no target), so MNEMOM_COMPACT_AT cannot arm it —
+            // an armed --compact-at was already refused above, and ignoredSettingLines told the
+            // user the env value is ignored, so this is what makes that true.
+            compactAt: experimental.includes("compaction-intercept") ? compactAtFlag : null,
             // Off ⇒ an explicit false, so MNEMOM_AGENT_CONTEXT_HANDOFF cannot turn it on.
             contextHandoff: experimental.includes("context-handoff") ? opts.contextHandoff : false,
             // Same gate: off ⇒ an explicit false, so MNEMOM_AGENT_COMPACTION_INTERCEPT cannot turn it on.

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

@@ -81,6 +81,14 @@ export interface SessionRecord {
      * before profiles existed omit it (still `v: 1`).
      */
     context_profile?: ContextProfile;
+    /**
+     * The resolved gateway compaction target (`--compact-at` / `compact_at` /
+     * `MNEMOM_COMPACT_AT`): `null` means no target (Claude Code's own 1M window; the default,
+     * and what `1m`/`off` also resolve to), a number is the token count sent as
+     * `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS`. Optional: records written before this setting
+     * existed omit it (still `v: 1`).
+     */
+    compact_at?: number | null;
     /**
      * 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`).

package/dist/lib/agent.d.ts

@@ -322,10 +322,89 @@ export declare const CONTEXT_HANDOFF_KEY = "CONTEXT_HANDOFF_ENABLED";
  *     `CLAUDE_CODE_AUTO_COMPACT_WINDOW` / `autoCompactWindow`) fires as it would without the fold;
  *   - `GATEWAY_COMPACTION_INTERCEPT` — answer the client's compaction request at once from the
  *     gateway's own fold digest (no model call), so the compaction never blocks the user.
- * Sent together, value `"on"`, ONLY when the setting is on (see `resolveCompactionIntercept`).
+ * Sent together, value `"on"`, when the `compaction_intercept` setting is on
+ * (`resolveCompactionIntercept`) OR when `--compact-at` arms a target below 1M (below) — a
+ * target cannot be honored without both.
  */
 export declare const USAGE_REAL_SIZE_KEY = "GATEWAY_USAGE_REAL_SIZE";
 export declare const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
+export declare const GATEWAY_COMPACTION_UPLOAD_TARGET_KEY = "GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS";
+/** The lowest token count `--compact-at` / `compact_at` / `MNEMOM_COMPACT_AT` will accept. */
+export declare const COMPACT_AT_MIN_TOKENS = 50000;
+/**
+ * The parser's ceiling (exclusive): the largest window Claude Code runs. It is NOT where a target
+ * stops working — the gateway ignores a target at or above the compaction point of the window
+ * the session actually runs on (COMPACT_AT_TRIGGER_1M / COMPACT_AT_TRIGGER_200K, below), which
+ * `compactAtWindowWarning` tells the user about at launch.
+ */
+export declare const COMPACT_AT_MAX_TOKENS = 1000000;
+/**
+ * Claude Code's own compaction point on a 1M and on a 200k window — the gateway's
+ * `ALIGN_T_1M` / `ALIGN_T_200K` (gateway/src/compaction-align.ts). The gateway honours an upload
+ * target only BELOW the point of the window the request runs on (`target_over_threshold`
+ * otherwise), and says nothing back to the client when it ignores one.
+ */
+export declare const COMPACT_AT_TRIGGER_1M = 967000;
+export declare const COMPACT_AT_TRIGGER_200K = 167000;
+/** The context window a launch runs on, as far as the launcher can tell before spawning. */
+export type LaunchWindow = "1m" | "200k" | "unknown";
+/**
+ * `resolveWindowModel`'s answer as a window. `one-m` and a model already suffixed `[1m]` are
+ * 1M; the `CLAUDE_CODE_DISABLE_1M_CONTEXT` opt-out and a model with no 1M window are 200k (the
+ * request then carries no 1M beta, so the gateway uses its 200k point too). A passthrough
+ * `-- --model`, a resume, Claude Code's own default, any other suffix, and a non-Claude-Code CLI
+ * (`null`) are unknown.
+ */
+export declare function launchWindow(win: WindowModel | null): LaunchWindow;
+/**
+ * The launch warning for a target the gateway will (or may) ignore because it is at or above
+ * the compaction point of the window this launch runs on; `null` when the target can take
+ * effect (or there is no target). On an unknown window a target in `[167k, 967k)` works only
+ * if the session lands on a 1M window, so the line says so instead of staying silent.
+ */
+export declare function compactAtWindowWarning(compactAt: number | null, window: LaunchWindow): string | null;
+/**
+ * Parse a `--compact-at` / `compact_at` / `MNEMOM_COMPACT_AT` value. `source` names the
+ * surface in the error so a customer knows which setting to fix (same convention as
+ * `parseContextProfile`).
+ *
+ *   - "" (unset), "1m", "off" (trimmed, case-insensitive) → `null`: no gateway target —
+ *     Claude Code runs its normal 1M window and nothing new is sent.
+ *   - a bare integer, or one with a `k`/`m` suffix (`200k` → 200000, `0.5m` → 500000) →
+ *     that many tokens, when it is in `[COMPACT_AT_MIN_TOKENS, COMPACT_AT_MAX_TOKENS)`.
+ *   - anything else, or a number outside that range (use `1m`/`off` for the ceiling and
+ *     above, never a bare `1000000`) → throws with a human-readable message.
+ */
+export declare function parseCompactAt(raw: string, source: string): number | null;
+/**
+ * Which compaction target this launch runs under. Precedence, highest wins:
+ *   1. `opts.compactAt` — an already-parsed `--compact-at` flag value (`undefined` when the
+ *      flag was not given at all; `null` is a valid, explicit "no target" from `1m`/`off`).
+ *   2. `MNEMOM_COMPACT_AT` (which `applyConfigToEnv` sets from the `compact_at` launcher.toml
+ *      key, UNDER any real env var — so an operator's own env always wins over the file).
+ *   3. `null` — the default: no target, nothing new sent.
+ */
+export declare function resolveCompactAt(opts: {
+    compactAt?: number | null;
+    env?: NodeJS.ProcessEnv;
+}): number | null;
+/**
+ * `--no-compaction-intercept` is a deliberate, documented "keep the intercept off for this
+ * launch no matter what toml/env says" signal. A compaction target needs that SAME intercept
+ * to arm (`buildSessionConfig` ORs them), so pairing an explicit `--no-compaction-intercept`
+ * with an armed `--compact-at` is a contradiction — refuse rather than silently pick a side
+ * (either silently re-arming the intercept the user just turned off, or silently sending an
+ * inert upload-target the gateway can never act on). `compactionIntercept` here is the raw,
+ * pre-`resolveCompactionIntercept` flag value: `false` only when `--no-compaction-intercept`
+ * was explicitly passed (or the experimental gate forced it, which `compactAt` cannot reach
+ * past either — see index.ts's `assertEnabled`), never the mere absence of `--compaction-intercept`.
+ */
+export declare function assertCompactAtCompatible(opts: {
+    compactionIntercept?: boolean;
+    compactAt: number | null;
+}): void;
+/** The launch-banner line for the resolved compaction target (always printed). */
+export declare function describeCompactAt(compactAt: number | null): string;
 /**
  * Claude Code's opt-in for its gateway hint headers (`x-claude-code-request-class: main |
  * compaction`, `x-claude-code-compaction: auto | manual | reactive`,
@@ -484,14 +563,18 @@ export declare function resolveContextProfile(opts: {
  * `x-mnemom-session-config` payload, in wire order: the profile's keys first
  * (`CONTEXT_RUNTIME_ENABLED` for `off`; the three fold-tuning keys for `aggressive`; nothing
  * for `balanced`), then `CONTEXT_HANDOFF_ENABLED: "true"` when context handoff is ON, then
- * `GATEWAY_USAGE_REAL_SIZE: "on"` + `GATEWAY_COMPACTION_INTERCEPT: "on"` when the compaction
- * intercept is ON. Empty for `balanced` with both off — the common case, where no header is sent at all.
- * Exported so `--dry-run` can list exactly what the header carries.
+ * `GATEWAY_USAGE_REAL_SIZE: "on"` + `GATEWAY_COMPACTION_INTERCEPT: "on"` when EITHER the
+ * `compaction_intercept` setting is ON OR `--compact-at` arms a target below 1M (the target
+ * cannot be honored without the intercept), then `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS: "<N>"`
+ * when a target is set. Empty for `balanced` with everything off — the common case, where no
+ * header is sent at all. Exported so `--dry-run` can list exactly what the header carries.
  */
 export declare function buildSessionConfig(opts: {
     profile: ContextProfile;
     contextHandoff: boolean;
     compactionIntercept?: boolean;
+    /** `resolveCompactAt` output: `null` (or absent) ⇒ no target, send nothing new. */
+    compactAt?: number | null;
 }): Record<string, string>;
 /**
  * The `x-mnemom-session-config` payload: `{ v: 1, config, experimental? }`. The active
@@ -502,6 +585,7 @@ export declare function buildSessionConfigPayload(opts: {
     profile: ContextProfile;
     contextHandoff: boolean;
     compactionIntercept?: boolean;
+    compactAt?: number | null;
     experimental?: readonly string[];
 }): {
     v: 1;
@@ -510,12 +594,15 @@ export declare function buildSessionConfigPayload(opts: {
 } | 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,
- * byte-identical to a launch before profiles existed). Two independent overlays:
+ * nothing to override (the gateway's own defaults stand — `balanced` with everything else off,
+ * byte-identical to a launch before profiles existed). Independent overlays:
  *   - the context profile (`buildSessionConfig`): `off` → `CONTEXT_RUNTIME_ENABLED: "false"`,
  *     `aggressive` → the three fold-tuning keys, `balanced` → nothing;
  *   - `compactionIntercept: true` → `GATEWAY_USAGE_REAL_SIZE` + `GATEWAY_COMPACTION_INTERCEPT`
  *     `"on"` (the `compaction_intercept` setting);
+ *   - `compactAt: <N>` (`--compact-at`, below 1M) → the SAME two intercept keys plus
+ *     `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS: "<N>"`; unset, `1m` or `off` → nothing beyond
+ *     what `compactionIntercept` already sent (Claude Code's own 1M window, untouched);
  *   - `contextHandoff: true` → `CONTEXT_HANDOFF_ENABLED: "true"` (the `context_handoff`
  *     setting) — the SAME header the `handoff` MCP tool's own call to
  *     `/mnemom/context/handoff` must also send, since the gateway resolves the flag
@@ -526,6 +613,7 @@ export declare function buildSessionConfigB64(opts: {
     profile: ContextProfile;
     contextHandoff: boolean;
     compactionIntercept?: boolean;
+    compactAt?: number | null;
     experimental?: readonly string[];
 }): string | undefined;
 /**

package/dist/lib/agent.js

@@ -489,10 +489,175 @@ export const CONTEXT_HANDOFF_KEY = "CONTEXT_HANDOFF_ENABLED";
  *     `CLAUDE_CODE_AUTO_COMPACT_WINDOW` / `autoCompactWindow`) fires as it would without the fold;
  *   - `GATEWAY_COMPACTION_INTERCEPT` — answer the client's compaction request at once from the
  *     gateway's own fold digest (no model call), so the compaction never blocks the user.
- * Sent together, value `"on"`, ONLY when the setting is on (see `resolveCompactionIntercept`).
+ * Sent together, value `"on"`, when the `compaction_intercept` setting is on
+ * (`resolveCompactionIntercept`) OR when `--compact-at` arms a target below 1M (below) — a
+ * target cannot be honored without both.
  */
 export const USAGE_REAL_SIZE_KEY = "GATEWAY_USAGE_REAL_SIZE";
 export const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
+// ---------------------------------------------------------------------------
+// Compaction target (`--compact-at`, launcher.toml `compact_at`, MNEMOM_COMPACT_AT)
+// ---------------------------------------------------------------------------
+//
+// Lets an operator play with WHEN the gateway pulls this session's own client-visible
+// compaction point forward (GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS, #2251), instead of
+// leaving Claude Code to compact on its own 1M-window schedule. Unset / `1m` / `off` all
+// mean the SAME thing — no target — so a launch with nothing else configured sends no new
+// header keys at all and behaves exactly as it did before this setting existed: Claude
+// Code's own 1M window, no gateway-triggered compaction. A value strictly below 1,000,000
+// arms the compaction intercept (USAGE_REAL_SIZE_KEY + COMPACTION_INTERCEPT_KEY, above — the
+// same two keys `--compaction-intercept` arms, #2216, both required for the upload pull to be
+// honored instead of silently inert) plus the target itself. Refold (GATEWAY_COMPACTION_REFOLD)
+// is a SEPARATE, costlier opt-in (+9.5pts measured) — this setting never touches it. This never
+// sets a Claude Code autocompact env/window: Claude Code's own compaction math is untouched;
+// only what the GATEWAY reports back changes.
+export const GATEWAY_COMPACTION_UPLOAD_TARGET_KEY = "GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS";
+/** The lowest token count `--compact-at` / `compact_at` / `MNEMOM_COMPACT_AT` will accept. */
+export const COMPACT_AT_MIN_TOKENS = 50_000;
+/**
+ * The parser's ceiling (exclusive): the largest window Claude Code runs. It is NOT where a target
+ * stops working — the gateway ignores a target at or above the compaction point of the window
+ * the session actually runs on (COMPACT_AT_TRIGGER_1M / COMPACT_AT_TRIGGER_200K, below), which
+ * `compactAtWindowWarning` tells the user about at launch.
+ */
+export const COMPACT_AT_MAX_TOKENS = 1_000_000;
+/**
+ * Claude Code's own compaction point on a 1M and on a 200k window — the gateway's
+ * `ALIGN_T_1M` / `ALIGN_T_200K` (gateway/src/compaction-align.ts). The gateway honours an upload
+ * target only BELOW the point of the window the request runs on (`target_over_threshold`
+ * otherwise), and says nothing back to the client when it ignores one.
+ */
+export const COMPACT_AT_TRIGGER_1M = 967_000;
+export const COMPACT_AT_TRIGGER_200K = 167_000;
+/**
+ * `resolveWindowModel`'s answer as a window. `one-m` and a model already suffixed `[1m]` are
+ * 1M; the `CLAUDE_CODE_DISABLE_1M_CONTEXT` opt-out and a model with no 1M window are 200k (the
+ * request then carries no 1M beta, so the gateway uses its 200k point too). A passthrough
+ * `-- --model`, a resume, Claude Code's own default, any other suffix, and a non-Claude-Code CLI
+ * (`null`) are unknown.
+ */
+export function launchWindow(win) {
+    if (win === null)
+        return "unknown";
+    switch (win.reason) {
+        case "one-m":
+            return "1m";
+        case "suffixed":
+            return /\[1m\]\s*$/i.test(win.model ?? "") ? "1m" : "unknown";
+        case "opt-out":
+        case "unsupported":
+            return "200k";
+        default:
+            return "unknown";
+    }
+}
+/**
+ * The launch warning for a target the gateway will (or may) ignore because it is at or above
+ * the compaction point of the window this launch runs on; `null` when the target can take
+ * effect (or there is no target). On an unknown window a target in `[167k, 967k)` works only
+ * if the session lands on a 1M window, so the line says so instead of staying silent.
+ */
+export function compactAtWindowWarning(compactAt, window) {
+    if (compactAt === null)
+        return null;
+    const at = formatTokenCount(compactAt);
+    const t1m = formatTokenCount(COMPACT_AT_TRIGGER_1M);
+    const t200k = formatTokenCount(COMPACT_AT_TRIGGER_200K);
+    if (compactAt >= COMPACT_AT_TRIGGER_1M ||
+        (window === "200k" && compactAt >= COMPACT_AT_TRIGGER_200K)) {
+        const [w, t] = window === "200k" ? ["200k", t200k] : window === "1m" ? ["1M", t1m] : ["any", t1m];
+        return (`mnemom agent: warning: compaction target ${at} is at or above Claude Code's own compaction ` +
+            `point on ${w === "any" ? "any" : `this launch's ${w}`} window (${t}), so the gateway will ignore it. ` +
+            `Pick a value below ${t}.`);
+    }
+    if (window === "unknown" && compactAt >= COMPACT_AT_TRIGGER_200K) {
+        return (`mnemom agent: note: compaction target ${at} takes effect only on a 1M window (below ${t1m}); ` +
+            `if this session runs on a 200k window, the gateway's point is ${t200k} and it ignores the target.`);
+    }
+    return null;
+}
+/**
+ * Parse a `--compact-at` / `compact_at` / `MNEMOM_COMPACT_AT` value. `source` names the
+ * surface in the error so a customer knows which setting to fix (same convention as
+ * `parseContextProfile`).
+ *
+ *   - "" (unset), "1m", "off" (trimmed, case-insensitive) → `null`: no gateway target —
+ *     Claude Code runs its normal 1M window and nothing new is sent.
+ *   - a bare integer, or one with a `k`/`m` suffix (`200k` → 200000, `0.5m` → 500000) →
+ *     that many tokens, when it is in `[COMPACT_AT_MIN_TOKENS, COMPACT_AT_MAX_TOKENS)`.
+ *   - anything else, or a number outside that range (use `1m`/`off` for the ceiling and
+ *     above, never a bare `1000000`) → throws with a human-readable message.
+ */
+export function parseCompactAt(raw, source) {
+    const v = raw.trim().toLowerCase();
+    if (v === "" || v === "1m" || v === "off")
+        return null;
+    const m = /^(\d+(?:\.\d+)?)(k|m)?$/.exec(v);
+    if (!m) {
+        throw new Error(`${source} must be a token count (optionally with a k/m suffix), '1m', or 'off' (got '${raw}').`);
+    }
+    const mult = m[2] === "k" ? 1_000 : m[2] === "m" ? 1_000_000 : 1;
+    const tokens = Math.round(Number(m[1]) * mult);
+    if (!Number.isFinite(tokens) ||
+        tokens < COMPACT_AT_MIN_TOKENS ||
+        tokens >= COMPACT_AT_MAX_TOKENS) {
+        throw new Error(`${source} must be between ${COMPACT_AT_MIN_TOKENS} and ${COMPACT_AT_MAX_TOKENS - 1} tokens` +
+            ` (or '1m' / 'off' for no gateway compaction target); got '${raw}'.`);
+    }
+    return tokens;
+}
+/**
+ * Which compaction target this launch runs under. Precedence, highest wins:
+ *   1. `opts.compactAt` — an already-parsed `--compact-at` flag value (`undefined` when the
+ *      flag was not given at all; `null` is a valid, explicit "no target" from `1m`/`off`).
+ *   2. `MNEMOM_COMPACT_AT` (which `applyConfigToEnv` sets from the `compact_at` launcher.toml
+ *      key, UNDER any real env var — so an operator's own env always wins over the file).
+ *   3. `null` — the default: no target, nothing new sent.
+ */
+export function resolveCompactAt(opts) {
+    if (opts.compactAt !== undefined)
+        return opts.compactAt;
+    const raw = (opts.env?.MNEMOM_COMPACT_AT ?? "").trim();
+    if (raw === "")
+        return null;
+    return parseCompactAt(raw, "MNEMOM_COMPACT_AT");
+}
+/**
+ * `--no-compaction-intercept` is a deliberate, documented "keep the intercept off for this
+ * launch no matter what toml/env says" signal. A compaction target needs that SAME intercept
+ * to arm (`buildSessionConfig` ORs them), so pairing an explicit `--no-compaction-intercept`
+ * with an armed `--compact-at` is a contradiction — refuse rather than silently pick a side
+ * (either silently re-arming the intercept the user just turned off, or silently sending an
+ * inert upload-target the gateway can never act on). `compactionIntercept` here is the raw,
+ * pre-`resolveCompactionIntercept` flag value: `false` only when `--no-compaction-intercept`
+ * was explicitly passed (or the experimental gate forced it, which `compactAt` cannot reach
+ * past either — see index.ts's `assertEnabled`), never the mere absence of `--compaction-intercept`.
+ */
+export function assertCompactAtCompatible(opts) {
+    if (opts.compactionIntercept === false && opts.compactAt !== null) {
+        throw new Error("mnemom agent: --compact-at needs the compaction intercept to arm, but it is off for " +
+            "this launch (--no-compaction-intercept, or the compaction-intercept experimental " +
+            "feature is disabled). Drop --no-compaction-intercept (and run `mnemom experimental " +
+            "enable compaction-intercept`), or pass --compact-at off.");
+    }
+}
+/**
+ * `200000` → `"200k"`, anything not k-aligned → the bare digits. Every real caller only ever
+ * passes a `parseCompactAt`-validated value, which is bounded to
+ * `[COMPACT_AT_MIN_TOKENS, COMPACT_AT_MAX_TOKENS)` — i.e. `[50_000, 999_999]` — so there is no
+ * multiple of 1,000,000 to round to an `"Nm"` form; that case is intentionally not handled here.
+ */
+function formatTokenCount(tokens) {
+    if (tokens % 1_000 === 0)
+        return `${tokens / 1_000}k`;
+    return String(tokens);
+}
+/** The launch-banner line for the resolved compaction target (always printed). */
+export function describeCompactAt(compactAt) {
+    return compactAt === null
+        ? "Claude Code default (1M)"
+        : `gateway at ${formatTokenCount(compactAt)}`;
+}
 /**
  * Claude Code's opt-in for its gateway hint headers (`x-claude-code-request-class: main |
  * compaction`, `x-claude-code-compaction: auto | manual | reactive`,
@@ -768,9 +933,11 @@ export function resolveContextProfile(opts) {
  * `x-mnemom-session-config` payload, in wire order: the profile's keys first
  * (`CONTEXT_RUNTIME_ENABLED` for `off`; the three fold-tuning keys for `aggressive`; nothing
  * for `balanced`), then `CONTEXT_HANDOFF_ENABLED: "true"` when context handoff is ON, then
- * `GATEWAY_USAGE_REAL_SIZE: "on"` + `GATEWAY_COMPACTION_INTERCEPT: "on"` when the compaction
- * intercept is ON. Empty for `balanced` with both off — the common case, where no header is sent at all.
- * Exported so `--dry-run` can list exactly what the header carries.
+ * `GATEWAY_USAGE_REAL_SIZE: "on"` + `GATEWAY_COMPACTION_INTERCEPT: "on"` when EITHER the
+ * `compaction_intercept` setting is ON OR `--compact-at` arms a target below 1M (the target
+ * cannot be honored without the intercept), then `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS: "<N>"`
+ * when a target is set. Empty for `balanced` with everything off — the common case, where no
+ * header is sent at all. Exported so `--dry-run` can list exactly what the header carries.
  */
 export function buildSessionConfig(opts) {
     const config = {};
@@ -778,10 +945,17 @@ export function buildSessionConfig(opts) {
         config[k] = v;
     if (opts.contextHandoff)
         config[CONTEXT_HANDOFF_KEY] = "true";
-    if (opts.compactionIntercept) {
+    const hasCompactionTarget = opts.compactAt !== undefined && opts.compactAt !== null;
+    // A target needs the compaction intercept + real-size rewrite to arm (#2216) — without them
+    // the upload-target key is silently inert (compaction-align.ts: "armed only inside the
+    // intercept"). Deliberately NOT GATEWAY_COMPACTION_REFOLD — a separate, costlier opt-in.
+    if (opts.compactionIntercept || hasCompactionTarget) {
         config[USAGE_REAL_SIZE_KEY] = "on";
         config[COMPACTION_INTERCEPT_KEY] = "on";
     }
+    if (hasCompactionTarget) {
+        config[GATEWAY_COMPACTION_UPLOAD_TARGET_KEY] = String(opts.compactAt);
+    }
     return config;
 }
 /**
@@ -800,12 +974,15 @@ export function buildSessionConfigPayload(opts) {
 }
 /**
  * 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,
- * byte-identical to a launch before profiles existed). Two independent overlays:
+ * nothing to override (the gateway's own defaults stand — `balanced` with everything else off,
+ * byte-identical to a launch before profiles existed). Independent overlays:
  *   - the context profile (`buildSessionConfig`): `off` → `CONTEXT_RUNTIME_ENABLED: "false"`,
  *     `aggressive` → the three fold-tuning keys, `balanced` → nothing;
  *   - `compactionIntercept: true` → `GATEWAY_USAGE_REAL_SIZE` + `GATEWAY_COMPACTION_INTERCEPT`
  *     `"on"` (the `compaction_intercept` setting);
+ *   - `compactAt: <N>` (`--compact-at`, below 1M) → the SAME two intercept keys plus
+ *     `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS: "<N>"`; unset, `1m` or `off` → nothing beyond
+ *     what `compactionIntercept` already sent (Claude Code's own 1M window, untouched);
  *   - `contextHandoff: true` → `CONTEXT_HANDOFF_ENABLED: "true"` (the `context_handoff`
  *     setting) — the SAME header the `handoff` MCP tool's own call to
  *     `/mnemom/context/handoff` must also send, since the gateway resolves the flag

package/dist/lib/experimental.d.ts

@@ -13,6 +13,15 @@
  * modules are the thin drivers.
  */
 export type ExperimentalId = "context-handoff" | "slack" | "implicit" | "compaction-intercept";
+/**
+ * Is a `compact_at` / `MNEMOM_COMPACT_AT` value (trimmed, case-insensitive) an ARMED gateway
+ * target, as opposed to "no target" (`""`, `"1m"`, `"off"`)? Deliberately duplicates
+ * `parseCompactAt`'s no-target spellings rather than importing it, to keep this registry
+ * dependency-free (see the module doc); an unparseable value (bad k/m suffix, out of range)
+ * is treated as armed so the gate errs toward requiring the opt-in rather than toward silently
+ * admitting a value the real parser would reject anyway.
+ */
+export declare function compactAtArmed(raw: string | undefined): boolean;
 export interface ExperimentalFeature {
     id: ExperimentalId;
     summary: string;
@@ -73,8 +82,8 @@ export declare function assertEnabled(uses: ReadonlyArray<{
 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]`), MNEMOM_AGENT_CONTEXT_HANDOFF and
- * MNEMOM_AGENT_COMPACTION_INTERCEPT.
+ * is off: launcher.toml keys (`entries` as `[key, value]`), MNEMOM_AGENT_CONTEXT_HANDOFF,
+ * MNEMOM_AGENT_COMPACTION_INTERCEPT and MNEMOM_COMPACT_AT (an armed target only).
  */
 export declare function ignoredSettingLines(opts: {
     entries: ReadonlyArray<[string, string]>;

package/dist/lib/experimental.js

@@ -12,6 +12,18 @@
  * Everything here is pure or dependency-injected; index.ts and the command
  * modules are the thin drivers.
  */
+/**
+ * Is a `compact_at` / `MNEMOM_COMPACT_AT` value (trimmed, case-insensitive) an ARMED gateway
+ * target, as opposed to "no target" (`""`, `"1m"`, `"off"`)? Deliberately duplicates
+ * `parseCompactAt`'s no-target spellings rather than importing it, to keep this registry
+ * dependency-free (see the module doc); an unparseable value (bad k/m suffix, out of range)
+ * is treated as armed so the gate errs toward requiring the opt-in rather than toward silently
+ * admitting a value the real parser would reject anyway.
+ */
+export function compactAtArmed(raw) {
+    const v = (raw ?? "").trim().toLowerCase();
+    return v !== "" && v !== "1m" && v !== "off";
+}
 export const EXPERIMENTAL_FEATURES = [
     {
         id: "context-handoff",
@@ -140,6 +152,9 @@ export function experimentalIdForConfigKey(key, value) {
             return value === "true" ? "context-handoff" : undefined;
         case "compaction_intercept":
             return value === "true" ? "compaction-intercept" : undefined;
+        case "compact_at":
+            // Arms the SAME gateway keys compaction_intercept does — same gate.
+            return compactAtArmed(value) ? "compaction-intercept" : undefined;
         case "goal_mode":
             return value === "implicit" ? "implicit" : undefined;
         default:
@@ -152,8 +167,8 @@ function truthy(raw) {
 }
 /**
  * The stderr lines for experimental settings a launch ignores because their feature
- * is off: launcher.toml keys (`entries` as `[key, value]`), MNEMOM_AGENT_CONTEXT_HANDOFF and
- * MNEMOM_AGENT_COMPACTION_INTERCEPT.
+ * is off: launcher.toml keys (`entries` as `[key, value]`), MNEMOM_AGENT_CONTEXT_HANDOFF,
+ * MNEMOM_AGENT_COMPACTION_INTERCEPT and MNEMOM_COMPACT_AT (an armed target only).
  */
 export function ignoredSettingLines(opts) {
     const lines = [];
@@ -170,6 +185,10 @@ export function ignoredSettingLines(opts) {
         !opts.enabled.includes("compaction-intercept")) {
         lines.push(`mnemom agent: ignoring ${gatedMessage("MNEMOM_AGENT_COMPACTION_INTERCEPT", "compaction-intercept")}`);
     }
+    if (compactAtArmed(opts.env.MNEMOM_COMPACT_AT) &&
+        !opts.enabled.includes("compaction-intercept")) {
+        lines.push(`mnemom agent: ignoring ${gatedMessage("MNEMOM_COMPACT_AT", "compaction-intercept")}`);
+    }
     return lines;
 }
 /** The features an existing launcher.toml already uses (the one-time migration). */

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

@@ -16,7 +16,7 @@
  * the caller folds the plain-value settings under the CLI flags.
  */
 import { type AgentAuth } from "./subscription-login.js";
-import type { ExperimentalId } from "./experimental.js";
+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;
@@ -61,6 +61,12 @@ export interface LauncherConfig {
      * folds earlier with a tighter working set. `--context-profile` overrides it per launch.
      */
     contextProfile?: ContextProfile;
+    /**
+     * The gateway compaction target (`--compact-at`; unset means no target — Claude Code's own
+     * 1M window, nothing new sent). Stored as the validated raw string (e.g. "200k", "1m",
+     * "off", "350000"), parsed with `parseCompactAt` at the point of use.
+     */
+    compactAt?: string;
     guardrails?: {
         maxTurns?: number;
         budgetUsd?: number;
@@ -113,6 +119,9 @@ export declare function launcherEntries(cfg: LauncherConfig): Array<[string, str
 /**
  * `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, `compaction_intercept` while `compaction-intercept` is off, and `goal_mode = implicit` while `implicit` is off (`goal_mode = off` is kept).
+ * off, `compaction_intercept` (and an ARMED `compact_at` — it arms the same two gateway keys,
+ * so it needs the same opt-in; `compact_at = "off"`/`"1m"` carries no gated behaviour and is
+ * kept) while `compaction-intercept` 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

@@ -20,7 +20,8 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "
 import { dirname, join } from "node:path";
 import { parse as parseToml, stringify as stringifyToml, TomlError } from "smol-toml";
 import { MNEMOM_DIR } from "./config.js";
-import { CONTEXT_PROFILES, isPositiveInt, isPositiveNumber, parseContextProfile, } from "./agent.js";
+import { compactAtArmed } from "./experimental.js";
+import { CONTEXT_PROFILES, isPositiveInt, isPositiveNumber, parseCompactAt, parseContextProfile, } from "./agent.js";
 /** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
 export const LAUNCHER_CONFIG_PATH = join(MNEMOM_DIR, "launcher.toml");
 const LAUNCH_SHAPES = ["terminal", "remote-control", "server"];
@@ -67,6 +68,13 @@ function coerceNonEmpty(name, raw) {
         throw new Error(`${name} must be a non-empty string.`);
     return v;
 }
+function coerceCompactAt(raw) {
+    const v = raw.trim().toLowerCase();
+    // Validate against the same parser the flag/env use, but keep the human-chosen spelling
+    // ("200k" vs "200000") — resolveCompactAt re-parses it at launch time anyway.
+    parseCompactAt(v, "compact_at");
+    return v;
+}
 function coerceMemberIds(raw) {
     const ids = raw
         .split(/[\s,]+/)
@@ -213,6 +221,14 @@ export const CONFIG_KEYS = [
             c.contextProfile = parseContextProfile(v, "context_profile");
         },
     },
+    {
+        key: "compact_at",
+        describe: "Gateway compaction target: a token count (k/m suffix OK), '1m' or 'off' for none (default: none — Claude Code's own 1M window)",
+        get: (c) => c.compactAt,
+        set: (c, v) => {
+            c.compactAt = coerceCompactAt(v);
+        },
+    },
     {
         key: "guardrails.max_turns",
         describe: "Contract guardrail: turn ceiling (positive integer)",
@@ -297,6 +313,8 @@ export function parseLauncherConfig(text) {
         cfg.compactionIntercept = coerceBool("compaction_intercept", str(raw.compaction_intercept) ?? "");
     if (raw.context_profile !== undefined)
         cfg.contextProfile = parseContextProfile(str(raw.context_profile) ?? "", "context_profile");
+    if (raw.compact_at !== undefined)
+        cfg.compactAt = coerceCompactAt(str(raw.compact_at) ?? "");
     const g = raw.guardrails;
     if (g !== undefined) {
         if (typeof g !== "object" || g === null || Array.isArray(g)) {
@@ -371,6 +389,8 @@ export function serializeLauncherConfig(cfg) {
         doc.compaction_intercept = cfg.compactionIntercept;
     if (cfg.contextProfile !== undefined)
         doc.context_profile = cfg.contextProfile;
+    if (cfg.compactAt !== undefined)
+        doc.compact_at = cfg.compactAt;
     const g = cfg.guardrails;
     if (g && (g.maxTurns !== undefined || g.budgetUsd !== undefined || g.stallTurns !== undefined)) {
         const gr = {};
@@ -433,6 +453,9 @@ export function applyConfigToEnv(cfg, env = process.env) {
     if (cfg.contextProfile !== undefined && !(env.MNEMOM_AGENT_CONTEXT_PROFILE ?? "").trim()) {
         env.MNEMOM_AGENT_CONTEXT_PROFILE = cfg.contextProfile;
     }
+    if (cfg.compactAt !== undefined && !(env.MNEMOM_COMPACT_AT ?? "").trim()) {
+        env.MNEMOM_COMPACT_AT = cfg.compactAt;
+    }
 }
 /** The set keys of `cfg` as `[key, value]` pairs (CONFIG_KEYS order, values stringified). */
 export function launcherEntries(cfg) {
@@ -444,7 +467,10 @@ export function launcherEntries(cfg) {
 /**
  * `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, `compaction_intercept` while `compaction-intercept` is off, and `goal_mode = implicit` while `implicit` is off (`goal_mode = off` is kept).
+ * off, `compaction_intercept` (and an ARMED `compact_at` — it arms the same two gateway keys,
+ * so it needs the same opt-in; `compact_at = "off"`/`"1m"` carries no gated behaviour and is
+ * kept) while `compaction-intercept` is off, and `goal_mode = implicit` while `implicit` is
+ * off (`goal_mode = off` is kept).
  */
 export function withoutDisabledExperimental(cfg, enabled) {
     const out = { ...cfg };
@@ -455,8 +481,11 @@ export function withoutDisabledExperimental(cfg, enabled) {
     }
     if (!enabled.includes("context-handoff"))
         delete out.contextHandoff;
-    if (!enabled.includes("compaction-intercept"))
+    if (!enabled.includes("compaction-intercept")) {
         delete out.compactionIntercept;
+        if (compactAtArmed(out.compactAt))
+            delete out.compactAt;
+    }
     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.6-next.0",
+  "version": "0.17.6-next.1",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {