@mnemom/mnemom 0.17.4-next.6 → 0.17.4-next.7

package/README.md

@@ -129,6 +129,25 @@ mnemom agent config set context_handoff off  # back to the default
 This is experimental: it only ever ADDS the one tool (no gateway behavior changes for a
 session that leaves the setting off, and no change to Claude Code's own `/compact`).
 
+#### Compaction signal and intercept
+
+Every launch shape (terminal, `-- -p …` headless, `--remote-control`, `--server`) starts Claude
+Code with `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`, so its requests carry the
+`x-claude-code-request-class` / `x-claude-code-compaction` hint headers, which mark exactly
+which request is a compaction (a gateway that does not read them ignores them). A value you set yourself (even `0`) wins. The launcher
+never sets or changes your own auto-compaction settings (`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`,
+`CLAUDE_CODE_AUTO_COMPACT_WINDOW`, or `autoCompactWindow` in settings.json).
+
+**Experimental, off by default.** `--compaction-intercept` (after `mnemom experimental enable
+compaction-intercept`; standing default `mnemom agent config set compaction_intercept on`, or
+`MNEMOM_AGENT_COMPACTION_INTERCEPT=1`) sends `GATEWAY_USAGE_REAL_SIZE=on` and
+`GATEWAY_COMPACTION_INTERCEPT=on` in the per-session config header, asking the gateway to report
+the real context size (so Claude Code compacts at its own threshold) and to answer that
+compaction at once from its fold instead of a blocking model call. This needs the companion
+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.
+
 ## How It Works
 
 ```

package/dist/commands/agent-config.js

@@ -193,6 +193,9 @@ function deleteKey(cfg, key) {
         case "context_handoff":
             delete cfg.contextHandoff;
             break;
+        case "compaction_intercept":
+            delete cfg.compactionIntercept;
+            break;
         case "context_profile":
             delete cfg.contextProfile;
             break;

package/dist/commands/agent.d.ts

@@ -79,6 +79,13 @@ export interface AgentOptions {
      * ⇒ no header key, no MCP server — the launch is byte-identical to a build without this flag.
      */
     contextHandoff?: boolean;
+    /**
+     * EXPERIMENTAL, off by default (payload-bound fix): tells the gateway
+     * `GATEWAY_USAGE_REAL_SIZE=on` + `GATEWAY_COMPACTION_INTERCEPT=on` for this session only (real
+     * context size in usage, so Claude Code compacts at its OWN threshold; the compaction request
+     * answered at once from the gateway's fold). Absent/false ⇒ no header key.
+     */
+    compactionIntercept?: boolean;
     /**
      * Governed-agent provisioning: undefined = AUTO (provision-with-confirm when
      * interactive, warn-and-continue otherwise), true = force (`--setup`), false =
@@ -116,11 +123,30 @@ export declare function passthroughResumeId(passthrough: readonly string[]): str
  *   - `-- --resume <cc-session-id>` → the matching row that pinned that Claude Code session
  *     (else the newest matching row), reused without asking;
  *   - no `--resume` → "Resume previous session <name>? [Y/n]", default Y; Y reuses that row's
- *     conversation, n mints a new one. `--resume` is NOT added to Claude Code (the user often
- *     resumes inside it with /resume). No TTY: Y.
+ *     conversation, n mints a new one. No TTY: Y.
  * The ledger read is best-effort: a failure means a new id.
  */
-export declare function resolveLaunchConversationId(input: {
+export declare function resolveLaunchConversationId(input: LaunchContinuationInput): Promise<string>;
+/**
+ * Whether Claude Code still has the transcript of session `id`
+ * (`${CLAUDE_CONFIG_DIR:-~/.claude}/projects/<any project>/<id>.jsonl`; `--resume` finds it in any
+ * project). Claude Code exits on `--resume` of an id it has no transcript for, so a relaunch only
+ * resumes one that is there. Best-effort: an unreadable directory or a non-UUID id → false.
+ */
+export declare function ccSessionTranscriptExists(id: string, env: NodeJS.ProcessEnv): boolean;
+/**
+ * resolveLaunchConversationId, plus the Claude Code session to resume. A Y (or no-TTY) relaunch
+ * of an earlier implicit launch also resumes the CC session that launch pinned (`--resume <id>`),
+ * when the caller passed no session flag of their own: the gateway gives the conversation's main
+ * goal to ONE CC session id, and a fresh `--session-id` cannot reuse it (CC refuses an id already
+ * in use), so without the resume the relaunch would run on a new, empty thread. An n, a new
+ * conversation, or the caller's own `--resume` / `--session-id` / `--continue` resume nothing.
+ */
+export declare function resolveLaunchContinuation(input: LaunchContinuationInput): Promise<{
+    conversationId: string;
+    resumeCcSessionId: string | null;
+}>;
+interface LaunchContinuationInput {
     session: string;
     orgId: string;
     agent: string;
@@ -131,7 +157,9 @@ export declare function resolveLaunchConversationId(input: {
     interactive: boolean;
     records: () => SessionRecord[];
     askYesNo: (question: string, defaultYes: boolean) => Promise<boolean>;
-}): Promise<string>;
+    /** Whether Claude Code still has that session's transcript (ccSessionTranscriptExists). */
+    ccSessionExists: (ccSessionId: string) => boolean;
+}
 /**
  * Record this launch in ~/.mnemom/sessions.jsonl. The agent record id is
  * resolved best-effort (a lookup failure or an unknown slug records null); a
@@ -318,3 +346,4 @@ export declare function printPlan(ctx: {
     /** The experimental features on for this launch (the header's `experimental` array). */
     experimental?: readonly string[];
 }): void;
+export {};

package/dist/commands/agent.js

@@ -43,12 +43,14 @@ import { askInput, askSelect, askYesNo, isInteractive } from "../lib/prompt.js";
 import { authConfigured, chooseAuth, detectClaudeLogin, readClaudeLoginState, } from "../lib/login-detect.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, 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, GATEWAY_HINT_HEADERS_ENV, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.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 { 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. */
 const CODE_STORE = LAUNCHER_STORE_PATH;
 const say = (line = "") => console.error(line);
+/** The one-line launch note when the compaction intercept is ON. */
+const COMPACTION_INTERCEPT_NOTE = "mnemom agent: compaction intercept ON (experimental) — requested from the gateway (GATEWAY_USAGE_REAL_SIZE, GATEWAY_COMPACTION_INTERCEPT); a gateway without the companion support drops both keys and the session runs as before.";
 /**
  * The one-line launch note for a non-default context profile (`balanced`, the default, is
  * silent — nothing is sent). `off` keeps the wording `--no-context` has always printed.
@@ -149,11 +151,20 @@ export async function agentCommand(scenarioArg, options = {}) {
         say("mnemom agent: context handoff is not available with subscription login yet — launching without it.");
         contextHandoff = false;
     }
+    const compactionIntercept = resolveCompactionIntercept({
+        compactionIntercept: options.compactionIntercept,
+        env,
+    });
     const experimental = options.experimental ?? [];
-    const sessionConfig = buildSessionConfig({ profile: contextProfile, contextHandoff });
+    const sessionConfig = buildSessionConfig({
+        profile: contextProfile,
+        contextHandoff,
+        compactionIntercept,
+    });
     const sessionConfigB64 = buildSessionConfigB64({
         profile: contextProfile,
         contextHandoff,
+        compactionIntercept,
         experimental,
     });
     const expNotice = experimentalNotice(experimental);
@@ -212,6 +223,8 @@ export async function agentCommand(scenarioArg, options = {}) {
         if (contextHandoff) {
             say("mnemom agent: context handoff ON (experimental) — the `handoff` MCP tool would be registered.");
         }
+        if (compactionIntercept)
+            say(COMPACTION_INTERCEPT_NOTE);
         return;
     }
     // Real launch: make sure we actually have a CLI to run. If we couldn't find it,
@@ -330,7 +343,7 @@ export async function agentCommand(scenarioArg, options = {}) {
     // so the goal the gateway inferred there is still the one it steers by. Resolved here, after
     // sign-in and the agent refresh, because a resume needs the org, agent and gateway host to
     // match the earlier launch.
-    const conversationId = await resolveLaunchConversationId({
+    const continuation = await resolveLaunchContinuation({
         session: scenario,
         orgId: account.orgId,
         agent,
@@ -341,7 +354,19 @@ export async function agentCommand(scenarioArg, options = {}) {
         interactive: isInteractive(),
         records: () => readSessionRecords({ dir: MNEMOM_DIR }),
         askYesNo: (q, d) => askYesNo(q, d),
+        ccSessionExists: (id) => ccSessionTranscriptExists(id, process.env),
     });
+    const conversationId = continuation.conversationId;
+    // A relaunch that continues an earlier conversation resumes that Claude Code session, so the
+    // same CC session id keeps owning the conversation's main goal on the gateway (a fresh
+    // --session-id would land on a new, empty m.<sha16> thread). The server shape hosts many
+    // sessions and pins none.
+    if (continuation.resumeCcSessionId && shape !== "server") {
+        options = {
+            ...options,
+            passthrough: [...(options.passthrough ?? []), "--resume", continuation.resumeCcSessionId],
+        };
+    }
     // ── local session ledger (~/.mnemom/sessions.jsonl) ── one line per real
     // launch so `mnemom agent sessions` / `show` can find this conversation later.
     // Written after provisioning so a freshly claimed agent's id resolves. Holds
@@ -389,6 +414,8 @@ export async function agentCommand(scenarioArg, options = {}) {
         say(expNotice);
     say(goalAlignmentLine(goalAlignmentMode(envelope, goalMode)));
     sayContextProfile(contextProfile);
+    if (compactionIntercept)
+        say(COMPACTION_INTERCEPT_NOTE);
     // ── handoff MCP tool (MNE-7564) ── OFF by default: absent/false ⇒ handoffMcpConfigPath stays
     // undefined and buildCliArgs/spawnRcCli are byte-identical to a build without this flag. ON:
     // the config is written to a 0600 temp file and referenced by PATH only — never inlined into
@@ -489,21 +516,62 @@ export function passthroughResumeId(passthrough) {
  *   - `-- --resume <cc-session-id>` → the matching row that pinned that Claude Code session
  *     (else the newest matching row), reused without asking;
  *   - no `--resume` → "Resume previous session <name>? [Y/n]", default Y; Y reuses that row's
- *     conversation, n mints a new one. `--resume` is NOT added to Claude Code (the user often
- *     resumes inside it with /resume). No TTY: Y.
+ *     conversation, n mints a new one. No TTY: Y.
  * The ledger read is best-effort: a failure means a new id.
  */
 export async function resolveLaunchConversationId(input) {
-    if ((input.explicit ?? "").trim())
-        return resolveConversationId(input.explicit);
+    return (await resolveLaunchContinuation(input)).conversationId;
+}
+/**
+ * Whether the caller's passthrough already chooses the Claude Code session (`--session-id`,
+ * `--resume` / `-r`, `--continue` / `-c`, `--fork-session`): exactly when pickCcSessionId would
+ * NOT mint one, so the two never disagree about which flags count.
+ */
+function choosesCcSession(passthrough) {
+    return !pickCcSessionId([...passthrough], () => "").inject;
+}
+const CC_SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Whether Claude Code still has the transcript of session `id`
+ * (`${CLAUDE_CONFIG_DIR:-~/.claude}/projects/<any project>/<id>.jsonl`; `--resume` finds it in any
+ * project). Claude Code exits on `--resume` of an id it has no transcript for, so a relaunch only
+ * resumes one that is there. Best-effort: an unreadable directory or a non-UUID id → false.
+ */
+export function ccSessionTranscriptExists(id, env) {
+    if (!CC_SESSION_ID_RE.test(id))
+        return false;
+    const projects = join((env.CLAUDE_CONFIG_DIR ?? "").trim() || join(homedir(), ".claude"), "projects");
+    try {
+        return readdirSync(projects).some((d) => existsSync(join(projects, d, `${id}.jsonl`)));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * resolveLaunchConversationId, plus the Claude Code session to resume. A Y (or no-TTY) relaunch
+ * of an earlier implicit launch also resumes the CC session that launch pinned (`--resume <id>`),
+ * when the caller passed no session flag of their own: the gateway gives the conversation's main
+ * goal to ONE CC session id, and a fresh `--session-id` cannot reuse it (CC refuses an id already
+ * in use), so without the resume the relaunch would run on a new, empty thread. An n, a new
+ * conversation, or the caller's own `--resume` / `--session-id` / `--continue` resume nothing.
+ */
+export async function resolveLaunchContinuation(input) {
+    const fresh = () => ({
+        conversationId: resolveConversationId(undefined),
+        resumeCcSessionId: null,
+    });
+    if ((input.explicit ?? "").trim()) {
+        return { conversationId: resolveConversationId(input.explicit), resumeCcSessionId: null };
+    }
     if (!input.implicit)
-        return resolveConversationId(undefined);
+        return fresh();
     let records;
     try {
         records = input.records();
     }
     catch {
-        return resolveConversationId(undefined);
+        return fresh();
     }
     const found = findResumeCandidate(records, {
         session: input.session,
@@ -513,15 +581,24 @@ export async function resolveLaunchConversationId(input) {
         resumeId: passthroughResumeId(input.passthrough),
     });
     if (!found)
-        return resolveConversationId(undefined);
+        return fresh();
     const conv = found.record.conversation_id;
     if (found.source === "session_name" && input.interactive) {
         const yes = await input.askYesNo(`Resume previous session ${input.session}?`, true);
         if (!yes)
-            return resolveConversationId(undefined);
+            return fresh();
     }
     say(`mnemom agent: continuing conversation ${conv} from the earlier '${found.record.session}' launch (${found.record.started_at}), so its goal carries over.`);
-    return resolveConversationId(conv);
+    const cc = found.record.cc_session_id?.trim() ?? "";
+    let resumeCcSessionId = null;
+    if (found.source === "session_name" && cc && !choosesCcSession(input.passthrough)) {
+        if (input.ccSessionExists(cc))
+            resumeCcSessionId = cc;
+        else {
+            say(`mnemom agent: Claude Code no longer has session ${cc}, so this launch starts a new one (its goal starts empty on the gateway).`);
+        }
+    }
+    return { conversationId: resolveConversationId(conv), resumeCcSessionId };
 }
 /**
  * Record this launch in ~/.mnemom/sessions.jsonl. The agent record id is
@@ -868,7 +945,11 @@ function launchTerminal(ctx) {
     applyToolSearchDefault(childEnv);
     const sessionName = passthroughName(ctx.options.passthrough ?? []) ?? sessionDisplayName(ctx.agent, ctx.scenario);
     childEnv[SESSION_NAME_ENV] = sessionName;
-    childEnv[GATEWAY_HINT_HEADERS_ENV] = "1";
+    // Exact compaction signal for the gateway (x-claude-code-request-class: compaction), on every
+    // terminal launch — interactive and `-p` passthrough alike; a user's own value wins. The
+    // user's CLAUDE_AUTOCOMPACT_PCT_OVERRIDE / CLAUDE_CODE_AUTO_COMPACT_WINDOW ride through
+    // untouched in the copied env (USER_AUTOCOMPACT_ENV).
+    applyGatewayHintHeaders(childEnv);
     if (ctx.options.slack)
         args.push(...slackChannelArgs(sessionName));
     if (ctx.contextHint) {
@@ -1112,6 +1193,11 @@ function spawnRcCli(ctx) {
     childEnv.https_proxy = `http://127.0.0.1:${ctx.port}`;
     childEnv.NODE_EXTRA_CA_CERTS = ctx.ca;
     childEnv[SESSION_NAME_ENV] = rcName;
+    // Same exact compaction signal as the terminal shape. Not an ANTHROPIC_* var, so the RC gate
+    // ignores it (like HTTPS_PROXY above); the proxy forwards every non-hop request header, so the
+    // x-claude-code-* hints reach the gateway. The user's own autocompact env is not on the strip
+    // list and rides through untouched.
+    applyGatewayHintHeaders(childEnv);
     // Under RC Claude Code sees a first-party host (the proxy, not ANTHROPIC_BASE_URL, routes to the
     // gateway), so tool search is already on by default; setting it anyway keeps every launch shape
     // on the same switch. A user value is kept.

package/dist/index.js

@@ -173,6 +173,8 @@ const agentCmd = program
 }))
     .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")
+    .addOption(new Option("--compaction-intercept", "EXPERIMENTAL (`mnemom experimental enable compaction-intercept`): tell the gateway to report the real context size (Claude Code compacts at its own threshold) and answer the compaction at once from its fold, for this session").hideHelp(hiddenUnless("compaction-intercept")))
+    .option("--no-compaction-intercept", "Keep the compaction intercept off for this launch even when launcher.toml (compaction_intercept = true) or MNEMOM_AGENT_COMPACTION_INTERCEPT turns it on")
     .option("--dry-run", "Print the resolved launch plan and exit — no key read, no spawn")
     .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) => {
@@ -216,6 +218,11 @@ const agentCmd = program
                 used: opts.contextHandoff === true,
             },
             { what: "--implicit", id: "implicit", used: opts.implicit === true },
+            {
+                what: "--compaction-intercept",
+                id: "compaction-intercept",
+                used: opts.compactionIntercept === true,
+            },
         ], experimental);
         if (opts.gateway)
             process.env.MNEMOM_AGENT_GATEWAY = opts.gateway;
@@ -301,6 +308,10 @@ const agentCmd = program
             contextProfile: opts.contextProfile,
             // 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.
+            compactionIntercept: experimental.includes("compaction-intercept")
+                ? opts.compactionIntercept
+                : false,
             experimental,
             setup: opts.setup,
             keySource: cfg.keySource,

package/dist/lib/agent.d.ts

@@ -228,15 +228,6 @@ export declare function resolveWindowModel(input: {
     env: Record<string, string | undefined>;
     settings: () => CcSettingsView[];
 }): WindowModel;
-/**
- * Claude Code's opt-in for its gateway hint headers (`x-claude-code-request-class`,
- * `x-claude-code-agent-type`, `x-claude-code-prompt-id`). CC sends them to api.anthropic.com on
- * its own, so a Remote Control launch (rc-proxy in front of api.anthropic.com) already carries
- * them; with `ANTHROPIC_BASE_URL` pointing at the gateway door (the terminal shape) CC sends them
- * only when this is "1". The gateway reads them to keep away summaries, titles, compaction and
- * teammates off the main implicit goal.
- */
-export declare const GATEWAY_HINT_HEADERS_ENV = "CLAUDE_CODE_GATEWAY_HINT_HEADERS";
 /** The session display name: "<agent>-<scenario>" (sanitised), else the agent slug. */
 export declare function sessionDisplayName(agent: string, scenario: string): string;
 /** A caller's own `--name <x>` in the passthrough args, if any (last one wins). */
@@ -322,6 +313,42 @@ export type ContextProfile = (typeof CONTEXT_PROFILES)[number];
  * header without the tool.
  */
 export declare const CONTEXT_HANDOFF_KEY = "CONTEXT_HANDOFF_ENABLED";
+/**
+ * The two gateway env keys the `compaction_intercept` setting turns on for a single session
+ * (payload-bound fix; both default OFF on the gateway, both read from the per-session overlay):
+ *   - `GATEWAY_USAGE_REAL_SIZE` — report the size of the body the client actually sent (the
+ *     REAL, unfolded context) in the last `usage.iterations` entry, so Claude Code's own
+ *     auto-compact threshold (its 1M default, or the user's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` /
+ *     `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`).
+ */
+export declare const USAGE_REAL_SIZE_KEY = "GATEWAY_USAGE_REAL_SIZE";
+export declare const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
+/**
+ * Claude Code's opt-in for its gateway hint headers (`x-claude-code-request-class: main |
+ * compaction`, `x-claude-code-compaction: auto | manual | reactive`,
+ * `x-claude-code-context-compacted` on the next turn, `x-claude-code-prompt-id`). Off by default
+ * in the client; the launcher turns it on for EVERY launch shape (terminal, `-p` passthrough,
+ * Remote Control interactive and server) so the gateway gets an exact compaction signal instead
+ * of relying on the body rule alone. Headers only — no behaviour change in the client. The
+ * gateway also reads them to keep summaries, titles, compaction and teammates off the main
+ * implicit goal.
+ */
+export declare const GATEWAY_HINT_HEADERS_ENV = "CLAUDE_CODE_GATEWAY_HINT_HEADERS";
+/**
+ * Claude Code's own auto-compaction knobs (env). The launcher NEVER sets, changes or strips
+ * them: whatever the user configured is what the client honours (the `autoCompactWindow`
+ * settings.json key is likewise never touched — the launcher writes no settings file).
+ */
+export declare const USER_AUTOCOMPACT_ENV: readonly ["CLAUDE_AUTOCOMPACT_PCT_OVERRIDE", "CLAUDE_CODE_AUTO_COMPACT_WINDOW"];
+/**
+ * Turn Claude Code's gateway hint headers on in a child env, unless the user already set
+ * `CLAUDE_CODE_GATEWAY_HINT_HEADERS` themselves (any non-blank value, `0` included, wins).
+ * Mutates and returns `childEnv`. Touches no other key.
+ */
+export declare function applyGatewayHintHeaders(childEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /**
  * The `x-mnemom-goal-mode` header value for `--implicit`, or null when the flag
  * is absent: `implicit[; max_turns=N][; budget_usd=X][; stall_turns=N]` — the
@@ -456,13 +483,15 @@ export declare function resolveContextProfile(opts: {
  * The decoded per-session env overlay for this launch — the `config` object of the
  * `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. Empty
- * for `balanced` with handoff off — the common case, where no header is sent at all.
+ * 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.
  */
 export declare function buildSessionConfig(opts: {
     profile: ContextProfile;
     contextHandoff: boolean;
+    compactionIntercept?: boolean;
 }): Record<string, string>;
 /**
  * The `x-mnemom-session-config` payload: `{ v: 1, config, experimental? }`. The active
@@ -472,6 +501,7 @@ export declare function buildSessionConfig(opts: {
 export declare function buildSessionConfigPayload(opts: {
     profile: ContextProfile;
     contextHandoff: boolean;
+    compactionIntercept?: boolean;
     experimental?: readonly string[];
 }): {
     v: 1;
@@ -484,6 +514,8 @@ export declare function buildSessionConfigPayload(opts: {
  * byte-identical to a launch before profiles existed). Two 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);
  *   - `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
@@ -493,6 +525,7 @@ export declare function buildSessionConfigPayload(opts: {
 export declare function buildSessionConfigB64(opts: {
     profile: ContextProfile;
     contextHandoff: boolean;
+    compactionIntercept?: boolean;
     experimental?: readonly string[];
 }): string | undefined;
 /**
@@ -507,6 +540,17 @@ export declare function resolveContextHandoff(opts: {
     contextHandoff?: boolean;
     env?: NodeJS.ProcessEnv;
 }): boolean;
+/**
+ * Is the compaction intercept (`GATEWAY_USAGE_REAL_SIZE` + `GATEWAY_COMPACTION_INTERCEPT` in the
+ * session-config header) ON for this launch? OFF by default, same shape as
+ * `resolveContextHandoff`: an explicit `--compaction-intercept` / `--no-compaction-intercept`
+ * wins, else `MNEMOM_AGENT_COMPACTION_INTERCEPT` (which `applyConfigToEnv` sets from the
+ * `compaction_intercept` config key), else OFF.
+ */
+export declare function resolveCompactionIntercept(opts: {
+    compactionIntercept?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): boolean;
 /** The name the `handoff` MCP tool server is registered under in `--mcp-config`. */
 export declare const HANDOFF_MCP_SERVER_NAME = "mnemom-handoff";
 /**

package/dist/lib/agent.js

@@ -301,15 +301,6 @@ export function resolveWindowModel(input) {
         return { model: explicit, reason: "unsupported" };
     return { model: `${base}${ONE_M_SUFFIX}`, reason: "one-m", from: base };
 }
-/**
- * Claude Code's opt-in for its gateway hint headers (`x-claude-code-request-class`,
- * `x-claude-code-agent-type`, `x-claude-code-prompt-id`). CC sends them to api.anthropic.com on
- * its own, so a Remote Control launch (rc-proxy in front of api.anthropic.com) already carries
- * them; with `ANTHROPIC_BASE_URL` pointing at the gateway door (the terminal shape) CC sends them
- * only when this is "1". The gateway reads them to keep away summaries, titles, compaction and
- * teammates off the main implicit goal.
- */
-export const GATEWAY_HINT_HEADERS_ENV = "CLAUDE_CODE_GATEWAY_HINT_HEADERS";
 /** The session display name: "<agent>-<scenario>" (sanitised), else the agent slug. */
 export function sessionDisplayName(agent, scenario) {
     return sanitizeAgentName(`${agent}-${scenario}`) || agent;
@@ -489,6 +480,50 @@ const CONTEXT_PROFILE_CONFIG = {
  * header without the tool.
  */
 export const CONTEXT_HANDOFF_KEY = "CONTEXT_HANDOFF_ENABLED";
+/**
+ * The two gateway env keys the `compaction_intercept` setting turns on for a single session
+ * (payload-bound fix; both default OFF on the gateway, both read from the per-session overlay):
+ *   - `GATEWAY_USAGE_REAL_SIZE` — report the size of the body the client actually sent (the
+ *     REAL, unfolded context) in the last `usage.iterations` entry, so Claude Code's own
+ *     auto-compact threshold (its 1M default, or the user's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` /
+ *     `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`).
+ */
+export const USAGE_REAL_SIZE_KEY = "GATEWAY_USAGE_REAL_SIZE";
+export const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
+/**
+ * Claude Code's opt-in for its gateway hint headers (`x-claude-code-request-class: main |
+ * compaction`, `x-claude-code-compaction: auto | manual | reactive`,
+ * `x-claude-code-context-compacted` on the next turn, `x-claude-code-prompt-id`). Off by default
+ * in the client; the launcher turns it on for EVERY launch shape (terminal, `-p` passthrough,
+ * Remote Control interactive and server) so the gateway gets an exact compaction signal instead
+ * of relying on the body rule alone. Headers only — no behaviour change in the client. The
+ * gateway also reads them to keep summaries, titles, compaction and teammates off the main
+ * implicit goal.
+ */
+export const GATEWAY_HINT_HEADERS_ENV = "CLAUDE_CODE_GATEWAY_HINT_HEADERS";
+/**
+ * Claude Code's own auto-compaction knobs (env). The launcher NEVER sets, changes or strips
+ * them: whatever the user configured is what the client honours (the `autoCompactWindow`
+ * settings.json key is likewise never touched — the launcher writes no settings file).
+ */
+export const USER_AUTOCOMPACT_ENV = [
+    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE",
+    "CLAUDE_CODE_AUTO_COMPACT_WINDOW",
+];
+/**
+ * Turn Claude Code's gateway hint headers on in a child env, unless the user already set
+ * `CLAUDE_CODE_GATEWAY_HINT_HEADERS` themselves (any non-blank value, `0` included, wins).
+ * Mutates and returns `childEnv`. Touches no other key.
+ */
+export function applyGatewayHintHeaders(childEnv) {
+    if ((childEnv[GATEWAY_HINT_HEADERS_ENV] ?? "").trim() === "") {
+        childEnv[GATEWAY_HINT_HEADERS_ENV] = "1";
+    }
+    return childEnv;
+}
 const SEALED_ONLY_FLAGS = "--goal/--requirement/--allow/--forbid/--goal-id";
 /**
  * `--implicit` and a sealed contract are mutually exclusive: on the gateway a
@@ -732,8 +767,9 @@ export function resolveContextProfile(opts) {
  * The decoded per-session env overlay for this launch — the `config` object of the
  * `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. Empty
- * for `balanced` with handoff off — the common case, where no header is sent at all.
+ * 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.
  */
 export function buildSessionConfig(opts) {
@@ -742,6 +778,10 @@ export function buildSessionConfig(opts) {
         config[k] = v;
     if (opts.contextHandoff)
         config[CONTEXT_HANDOFF_KEY] = "true";
+    if (opts.compactionIntercept) {
+        config[USAGE_REAL_SIZE_KEY] = "on";
+        config[COMPACTION_INTERCEPT_KEY] = "on";
+    }
     return config;
 }
 /**
@@ -764,6 +804,8 @@ export function buildSessionConfigPayload(opts) {
  * byte-identical to a launch before profiles existed). Two 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);
  *   - `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
@@ -792,6 +834,21 @@ export function resolveContextHandoff(opts) {
         return false;
     return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
 }
+/**
+ * Is the compaction intercept (`GATEWAY_USAGE_REAL_SIZE` + `GATEWAY_COMPACTION_INTERCEPT` in the
+ * session-config header) ON for this launch? OFF by default, same shape as
+ * `resolveContextHandoff`: an explicit `--compaction-intercept` / `--no-compaction-intercept`
+ * wins, else `MNEMOM_AGENT_COMPACTION_INTERCEPT` (which `applyConfigToEnv` sets from the
+ * `compaction_intercept` config key), else OFF.
+ */
+export function resolveCompactionIntercept(opts) {
+    if (opts.compactionIntercept !== undefined)
+        return opts.compactionIntercept;
+    const raw = (opts.env?.MNEMOM_AGENT_COMPACTION_INTERCEPT ?? "").trim().toLowerCase();
+    if (raw === "")
+        return false;
+    return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
 /** The name the `handoff` MCP tool server is registered under in `--mcp-config`. */
 export const HANDOFF_MCP_SERVER_NAME = "mnemom-handoff";
 /**

package/dist/lib/experimental.d.ts

@@ -12,7 +12,7 @@
  * 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 type ExperimentalId = "context-handoff" | "slack" | "implicit" | "compaction-intercept";
 export interface ExperimentalFeature {
     id: ExperimentalId;
     summary: string;
@@ -73,7 +73,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]`) and MNEMOM_AGENT_CONTEXT_HANDOFF.
+ * is off: launcher.toml keys (`entries` as `[key, value]`), MNEMOM_AGENT_CONTEXT_HANDOFF and
+ * MNEMOM_AGENT_COMPACTION_INTERCEPT.
  */
 export declare function ignoredSettingLines(opts: {
     entries: ReadonlyArray<[string, string]>;

package/dist/lib/experimental.js

@@ -46,6 +46,17 @@ export const EXPERIMENTAL_FEATURES = [
             env: [],
         },
     },
+    {
+        id: "compaction-intercept",
+        summary: "Have the gateway report the real context size (so Claude Code compacts at its own threshold) and answer the compaction at once from its fold",
+        since: "0.17.4",
+        gates: {
+            flags: ["--compaction-intercept"],
+            configKeys: ["compaction_intercept"],
+            commands: [],
+            env: ["MNEMOM_AGENT_COMPACTION_INTERCEPT"],
+        },
+    },
 ];
 export const EXPERIMENTAL_IDS = EXPERIMENTAL_FEATURES.map((f) => f.id);
 export const EXPERIMENTAL_ENV = "MNEMOM_EXPERIMENTAL";
@@ -127,19 +138,22 @@ export function experimentalIdForConfigKey(key, value) {
             return value === "true" ? "slack" : undefined;
         case "context_handoff":
             return value === "true" ? "context-handoff" : undefined;
+        case "compaction_intercept":
+            return value === "true" ? "compaction-intercept" : undefined;
         case "goal_mode":
             return value === "implicit" ? "implicit" : undefined;
         default:
             return undefined;
     }
 }
-/** Is an env value one of the truthy spellings resolveContextHandoff accepts? */
+/** Is an env value one of the truthy spellings resolveContextHandoff / resolveCompactionIntercept accept? */
 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.
+ * is off: launcher.toml keys (`entries` as `[key, value]`), MNEMOM_AGENT_CONTEXT_HANDOFF and
+ * MNEMOM_AGENT_COMPACTION_INTERCEPT.
  */
 export function ignoredSettingLines(opts) {
     const lines = [];
@@ -152,6 +166,10 @@ export function ignoredSettingLines(opts) {
     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")}`);
     }
+    if (truthy(opts.env.MNEMOM_AGENT_COMPACTION_INTERCEPT) &&
+        !opts.enabled.includes("compaction-intercept")) {
+        lines.push(`mnemom agent: ignoring ${gatedMessage("MNEMOM_AGENT_COMPACTION_INTERCEPT", "compaction-intercept")}`);
+    }
     return lines;
 }
 /** The features an existing launcher.toml already uses (the one-time migration). */
@@ -199,6 +217,8 @@ export function configKeyFeature(key) {
         return "slack";
     if (key === "context_handoff")
         return "context-handoff";
+    if (key === "compaction_intercept")
+        return "compaction-intercept";
     if (key === "goal_mode")
         return "implicit";
     return undefined;

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

@@ -49,6 +49,12 @@ export interface LauncherConfig {
      * every launch. Off means byte-identical to a launch with no MNE-7564 change at all.
      */
     contextHandoff?: boolean;
+    /**
+     * Compaction-intercept default (EXPERIMENTAL, off when unset): `true` sends
+     * `GATEWAY_USAGE_REAL_SIZE: "on"` + `GATEWAY_COMPACTION_INTERCEPT: "on"` in the per-session
+     * config header for every launch. Off means no header key at all.
+     */
+    compactionIntercept?: boolean;
     /**
      * How the gateway folds each session's context (`balanced` when unset): `off` leaves
      * compaction to the coding agent, `balanced` keeps more earlier work verbatim, `aggressive`
@@ -107,6 +113,6 @@ 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, and `goal_mode = implicit` while `implicit` is off (`goal_mode = off` is kept).
+ * off, `compaction_intercept` 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

@@ -197,6 +197,14 @@ export const CONFIG_KEYS = [
             c.contextHandoff = coerceBool("context_handoff", v);
         },
     },
+    {
+        key: "compaction_intercept",
+        describe: "EXPERIMENTAL: tell the gateway GATEWAY_USAGE_REAL_SIZE=on + GATEWAY_COMPACTION_INTERCEPT=on (off by default)",
+        get: (c) => c.compactionIntercept,
+        set: (c, v) => {
+            c.compactionIntercept = coerceBool("compaction_intercept", v);
+        },
+    },
     {
         key: "context_profile",
         describe: `How the gateway folds each session's context (${CONTEXT_PROFILES.join("|")}; balanced by default)`,
@@ -285,6 +293,8 @@ export function parseLauncherConfig(text) {
         cfg.slackChannel = coerceNonEmpty("slack_channel", str(raw.slack_channel) ?? "");
     if (raw.context_handoff !== undefined)
         cfg.contextHandoff = coerceBool("context_handoff", str(raw.context_handoff) ?? "");
+    if (raw.compaction_intercept !== undefined)
+        cfg.compactionIntercept = coerceBool("compaction_intercept", str(raw.compaction_intercept) ?? "");
     if (raw.context_profile !== undefined)
         cfg.contextProfile = parseContextProfile(str(raw.context_profile) ?? "", "context_profile");
     const g = raw.guardrails;
@@ -357,6 +367,8 @@ export function serializeLauncherConfig(cfg) {
         doc.slack_allow = cfg.slackAllow;
     if (cfg.contextHandoff !== undefined)
         doc.context_handoff = cfg.contextHandoff;
+    if (cfg.compactionIntercept !== undefined)
+        doc.compaction_intercept = cfg.compactionIntercept;
     if (cfg.contextProfile !== undefined)
         doc.context_profile = cfg.contextProfile;
     const g = cfg.guardrails;
@@ -414,6 +426,10 @@ export function applyConfigToEnv(cfg, env = process.env) {
     if (cfg.contextHandoff !== undefined && !(env.MNEMOM_AGENT_CONTEXT_HANDOFF ?? "").trim()) {
         env.MNEMOM_AGENT_CONTEXT_HANDOFF = cfg.contextHandoff ? "1" : "0";
     }
+    if (cfg.compactionIntercept !== undefined &&
+        !(env.MNEMOM_AGENT_COMPACTION_INTERCEPT ?? "").trim()) {
+        env.MNEMOM_AGENT_COMPACTION_INTERCEPT = cfg.compactionIntercept ? "1" : "0";
+    }
     if (cfg.contextProfile !== undefined && !(env.MNEMOM_AGENT_CONTEXT_PROFILE ?? "").trim()) {
         env.MNEMOM_AGENT_CONTEXT_PROFILE = cfg.contextProfile;
     }
@@ -428,7 +444,7 @@ 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, and `goal_mode = implicit` while `implicit` is off (`goal_mode = off` is kept).
+ * off, `compaction_intercept` 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 };
@@ -439,6 +455,8 @@ export function withoutDisabledExperimental(cfg, enabled) {
     }
     if (!enabled.includes("context-handoff"))
         delete out.contextHandoff;
+    if (!enabled.includes("compaction-intercept"))
+        delete out.compactionIntercept;
     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.4-next.6",
+  "version": "0.17.4-next.7",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {