@mnemom/mnemom 0.17.5 → 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

@@ -31,6 +31,7 @@ import { randomUUID } from "node:crypto";
 import { tmpdir, homedir, hostname, userInfo } from "node:os";
 import { basename, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { statuslineLaunch } from "../lib/statusline.js";
 import { getApiUrl, getGatewayUrl, MNEMOM_DIR } from "../lib/config.js";
 import { createApiKey, getAgentByName } from "../lib/api.js";
 import { MNEMOM_KEY_STORE_FIELD, resolveAgentAuth, resolveSubscriptionMnemomKey, subscriptionChildEnv, subscriptionShape, } from "../lib/subscription-login.js";
@@ -44,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. */
@@ -64,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;
@@ -158,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);
@@ -211,6 +254,7 @@ export async function agentCommand(scenarioArg, options = {}) {
             yolo,
             cli: planCli,
             contextProfile,
+            compactAt,
             sessionConfig,
             experimental,
         });
@@ -226,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.");
         }
@@ -388,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).`);
@@ -417,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
@@ -650,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] } : {}),
     }, {
@@ -978,6 +1016,21 @@ function launchTerminal(ctx) {
     applyGatewayHintHeaders(childEnv);
     if (ctx.options.slack)
         args.push(...slackChannelArgs(sessionName));
+    // The status-bar savings counter (lib/statusline.ts). Claude Code only; the
+    // user's own statusLine keeps running in front of it.
+    if (ctx.cli.name === "claude") {
+        const sl = statuslineLaunch({
+            passthrough: ctx.options.passthrough ?? [],
+            env: childEnv,
+            cwd: process.cwd(),
+            node: process.execPath,
+            bin: join(dirname(fileURLToPath(import.meta.url)), "..", "lib", "statusline-bin.js"),
+        });
+        if (sl) {
+            args.push(...sl.args);
+            Object.assign(childEnv, sl.env);
+        }
+    }
     if (ctx.contextHint) {
         seedContextHintFlag(childEnv);
         childEnv.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
@@ -1511,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;
 /**