@mnemom/mnemom 0.17.15 → 0.17.16

package/dist/commands/agent.js

@@ -31,7 +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 { MEASURED_ENV, statuslineLaunch } from "../lib/statusline.js";
 import { getApiUrl, getGatewayUrl, MNEMOM_DIR } from "../lib/config.js";
 import { createApiKey } from "../lib/api.js";
 import { MNEMOM_KEY_STORE_FIELD, resolveAgentAuth, resolveSubscriptionMnemomKey, subscriptionChildEnv, subscriptionShape, } from "../lib/subscription-login.js";
@@ -46,7 +46,7 @@ import { authConfigured, chooseAuth, detectClaudeLogin, readClaudeLoginState, }
 import { requireConsoleKey, readConsoleKey } from "../lib/console-key.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
 import { defaultAgentSlug, ensureClaimedServedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.js";
-import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, assertCompactAtCompatible, assertOffProfileCompatible, 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, resumeCommand, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
+import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, assertCompactAtCompatible, assertOffProfileCompatible, compactAtWindowWarning, describeCompactAt, launchWindow, resolveCompactAt, applyGatewayHintHeaders, resolveCompactionIntercept, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, resolveUsageSavings, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, resumeCommand, 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. */
@@ -176,7 +176,9 @@ export async function agentCommand(scenarioArg, options = {}) {
         budget: options.budget,
         maxTurns: options.maxTurns,
         stall: options.stall,
+        mode: options.mode,
         implicit: options.implicit,
+        leadDirected: options.leadDirected,
     });
     // ── implicit goal mode (no contract; the gateway infers the goal from the user's
     // messages) — the guardrail ceilings ride on the mode header instead ──
@@ -232,17 +234,24 @@ export async function agentCommand(scenarioArg, options = {}) {
         compactAt: options.compactAt,
     });
     const experimental = options.experimental ?? [];
+    // Decided from the REQUESTED CLI: the header is built before the executable is resolved.
+    const usageSavings = resolveUsageSavings({
+        experimental,
+        cliName: basename(requestedCli(options.cli, env)),
+    });
     const sessionConfig = buildSessionConfig({
         profile: contextProfile,
         contextHandoff,
         compactionIntercept,
         compactAt,
+        usageSavings,
     });
     let sessionConfigB64 = buildSessionConfigB64({
         profile: contextProfile,
         contextHandoff,
         compactionIntercept,
         compactAt,
+        usageSavings,
         experimental,
     });
     const expNotice = experimentalNotice(experimental);
@@ -269,7 +278,7 @@ export async function agentCommand(scenarioArg, options = {}) {
     if (options.dryRun) {
         const planCli = cli ?? {
             bin: "(not found — pass --cli <path> or `mnemom agent config set cli <path>`)",
-            name: basename((options.cli || env.MNEMOM_AGENT_CLI || "claude").trim()),
+            name: basename(requestedCli(options.cli, env)),
         };
         // A defaulted slug is `agent-<handle>` from the login (resolved for real after
         // sign-in, below). Signed in: show that name. Signed out, or no usable handle:
@@ -475,6 +484,7 @@ export async function agentCommand(scenarioArg, options = {}) {
                 contextHandoff,
                 compactionIntercept,
                 compactAt,
+                usageSavings,
                 experimental,
             });
         }
@@ -571,6 +581,7 @@ export async function agentCommand(scenarioArg, options = {}) {
             envelope,
             goalMode,
             sessionConfigB64,
+            usageSavings,
             options: launchOptions,
             yolo,
             contextHint,
@@ -923,6 +934,10 @@ function storeKey(key) {
         // best effort — the launch proceeds with the in-memory key either way
     }
 }
+/** The CLI asked for — `--cli`, else MNEMOM_AGENT_CLI, else "claude" — before any lookup. */
+export function requestedCli(cliOpt, env) {
+    return (cliOpt || env.MNEMOM_AGENT_CLI || "claude").trim();
+}
 /**
  * Resolve which coding-agent CLI to launch. `--cli` (or MNEMOM_AGENT_CLI) is a
  * name or a full path; default "claude". A value with a path separator is used
@@ -932,7 +947,7 @@ function storeKey(key) {
  * a non-claude executable is launched through it with a warning.
  */
 export function resolveCliBin(cliOpt, env) {
-    const requested = (cliOpt || env.MNEMOM_AGENT_CLI || "claude").trim();
+    const requested = requestedCli(cliOpt, env);
     const name = basename(requested);
     if (requested.includes("/")) {
         if (existsSync(requested))
@@ -985,7 +1000,7 @@ export /**
  * so they never retype it). A non-interactive session re-throws the clear,
  * actionable error rather than hanging on a prompt.
  */ async function promptForCliPath(cliOpt, env, origErr) {
-    const requested = (cliOpt || env.MNEMOM_AGENT_CLI || "claude").trim();
+    const requested = requestedCli(cliOpt, env);
     if (!isInteractive()) {
         throw origErr ?? new Error(`mnemom agent: coding-agent CLI '${requested}' not found.`);
     }
@@ -1121,7 +1136,9 @@ function launchTerminal(ctx) {
     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.
+    // user's own statusLine keeps running in front of it. Measured mode is this launch's
+    // decision alone: a value inherited from an outer `mnemom agent` session never rides along.
+    Reflect.deleteProperty(childEnv, MEASURED_ENV);
     if (ctx.cli.name === "claude") {
         const sl = statuslineLaunch({
             passthrough: ctx.options.passthrough ?? [],
@@ -1129,6 +1146,7 @@ function launchTerminal(ctx) {
             cwd: process.cwd(),
             node: process.execPath,
             bin: join(dirname(fileURLToPath(import.meta.url)), "..", "lib", "statusline-bin.js"),
+            measured: ctx.usageSavings,
         });
         if (sl) {
             args.push(...sl.args);

package/dist/index.js

@@ -150,7 +150,12 @@ const agentCmd = program
     .option("--budget <usd>", "Guardrail: spend ceiling in USD (positive number)")
     .option("--max-turns <n>", "Guardrail: turn ceiling (positive integer)")
     .option("--stall <n>", "Guardrail: consecutive no-write turns (positive integer)")
-    .addOption(new Option("--implicit", "EXPERIMENTAL (`mnemom experimental enable implicit`): implicit goal alignment — the gateway infers the goal from your messages and revises it as you steer (the default while the feature is on; not combinable with --goal/--requirement/--allow/--forbid/--goal-id; the guardrail ceilings still apply)").hideHelp(hiddenUnless("implicit")))
+    .option("--mode <nudge|enforce>", "Sealed contract mode (MNE-8199; default nudge). Under enforce, a crossed turn/budget/time " +
+    "ceiling REFUSES the next request on this conversation until the owner raises it via a " +
+    "contract update — under nudge the ceiling only nudges, unchanged. Requires --goal.")
+    .option("--lead-directed", "Seal the standard lead-directed requirement: own-branch push and draft/ready PR creation, " +
+    "from a git worktree, on the lead's direction — not merging. Requires --goal; idempotent.")
+    .addOption(new Option("--implicit", "EXPERIMENTAL (`mnemom experimental enable implicit`): implicit goal alignment — the gateway infers the goal from your messages and revises it as you steer (the default while the feature is on; not combinable with --goal/--requirement/--allow/--forbid/--goal-id/--mode/--lead-directed; the guardrail ceilings still apply)").hideHelp(hiddenUnless("implicit")))
     .option("--no-implicit", "Turn implicit goal alignment OFF for this launch (overrides launcher.toml goal_mode = implicit)")
     .option("--conversation-id <id>", "x-mnemom-conversation-id (default: auto-generated)")
     .option("--cli <name|path>", "Coding-agent CLI to launch: a name or full path (default: claude)")
@@ -345,9 +350,11 @@ const agentCmd = program
             forbid: opts.forbid,
             goalId: opts.goalId,
             implicit,
+            leadDirected: opts.leadDirected,
             budget: opts.budget ?? (contractIntended ? numToStr(cfg.guardrails?.budgetUsd) : undefined),
             maxTurns: opts.maxTurns ?? (contractIntended ? numToStr(cfg.guardrails?.maxTurns) : undefined),
             stall: opts.stall ?? (contractIntended ? numToStr(cfg.guardrails?.stallTurns) : undefined),
+            mode: opts.mode,
             agent: parentOpts.agent ?? cfg.agent,
             conversationId: opts.conversationId,
             cli: opts.cli,
@@ -878,9 +885,21 @@ agentCmd
     .description("Show one session — the local launch record merged with the gateway's live goal state (sealed contract, latest verdict, guardrails). " +
     "`ref` is a session name (newest match wins) or a unique conversation-id prefix; omitted = the newest session")
     .option("--json", "Output the merged view as JSON (each section tagged with its source)")
+    .option("--follow", "After the snapshot, keep watching and print each new verdict as it lands (Ctrl-C to stop)")
+    .option("--follow-interval <seconds>", "Poll interval for --follow, in seconds (default 3; also settable via MNEMOM_AGENT_FOLLOW_INTERVAL)")
     .action(async (ref, opts) => {
     try {
-        await agentShowCommand(ref, { json: opts.json }, liveSessionDeps);
+        let followIntervalMs;
+        if (opts.followInterval !== undefined) {
+            const seconds = Number(opts.followInterval);
+            if (!Number.isFinite(seconds) || seconds <= 0) {
+                console.error("Error: --follow-interval must be a positive number of seconds.");
+                process.exit(1);
+                return;
+            }
+            followIntervalMs = seconds * 1000;
+        }
+        await agentShowCommand(ref, { json: opts.json, follow: opts.follow, followIntervalMs }, liveSessionDeps);
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);

package/dist/lib/agent.d.ts

@@ -39,6 +39,15 @@ export interface SealedContract {
     max_turns?: number;
     budget_usd?: number;
     stall_turns?: number;
+    /**
+     * `nudge` | `enforce` (MNE-8199, design D9/R9): under `enforce` a crossed turn/budget/time
+     * ceiling refuses the gateway's NEXT request on this conversation rather than only
+     * nudging. ALWAYS present once a contract is sealed (never omitted) — the gateway's
+     * `parseContractHeader` defaults an absent/invalid value to `"nudge"` unconditionally
+     * before hashing, so the CLI must set it here too (defaulting to `"nudge"`) or the sha
+     * printed here would disagree with the one the gateway seals (the MNE-7649 class of bug).
+     */
+    mode?: "nudge" | "enforce";
 }
 /** The raw contract/guardrail flags as commander hands them to the command. */
 export interface ContractFlags {
@@ -50,6 +59,8 @@ export interface ContractFlags {
     maxTurns?: string | number;
     budget?: string | number;
     stall?: string | number;
+    /** `--mode nudge|enforce` (MNE-8199) — validated and defaulted in `assembleContract`. */
+    mode?: string;
     /**
      * `--implicit`: goal alignment WITHOUT a sealed contract. No `x-mnemom-contract`
      * is sent; the gateway infers the goal from the user's own messages (revision 1
@@ -58,7 +69,26 @@ export interface ContractFlags {
      * of inside a contract. Cannot be combined with the sealed-contract flags.
      */
     implicit?: boolean;
+    /**
+     * `--lead-directed`: append `LEAD_DIRECTED_REQUIREMENT` to the sealed contract's
+     * `requirements` (MNE-8152, design `mnemom-agent-wave` D4). A lead-directed agent
+     * (e.g. an ADW lane lead) legitimately pushes its own branches and opens draft/ready
+     * PRs; under the sealed framing the judge reads only `goal`/`requirements`/fences, so
+     * without this line a push/PR step is flagged `violation` ("an effect of this step is
+     * not allowed by the requirements"). The mechanism is a requirement line, not a judge
+     * input — sealed mode takes no in-session steering, so the lead's direction must
+     * already be IN the seal. Idempotent: appended at most once, whether the flag is
+     * given once or the requirement text is already present (e.g. supplied verbatim via
+     * `--requirement`).
+     */
+    leadDirected?: boolean;
 }
+/**
+ * The standard requirement line `--lead-directed` seals: own-branch push and draft/ready
+ * PR creation, from a git worktree, on the lead's direction — merging is explicitly out.
+ * A single constant so every launch that opts in seals byte-identical wording (MNE-8152).
+ */
+export declare const LEAD_DIRECTED_REQUIREMENT: string;
 /** The three launch shapes the command supports (see commands/code.ts). */
 export type LaunchShape = "terminal" | "remote-control" | "server";
 /**
@@ -325,6 +355,15 @@ export declare const CONTEXT_SIZE_POLICY_KEY = "CONTEXT_RUNTIME_SIZE_POLICY";
  */
 export declare const USAGE_REAL_SIZE_KEY = "GATEWAY_USAGE_REAL_SIZE";
 export declare const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
+/**
+ * The gateway env key that has it measure each request's saving for a single session and put
+ * it in the client-facing usage (`mnemom_savings` in the read `usage.iterations` entry), where
+ * the status bar reads it from Claude Code's transcript. Default OFF on the gateway; sent `"on"`
+ * only while the `measured-savings` experimental feature is on and the launched CLI is Claude
+ * Code (`resolveUsageSavings`). Independent of folding, so every profile sends it — `off` too,
+ * where the measured saving is honestly $0.00.
+ */
+export declare const USAGE_SAVINGS_KEY = "GATEWAY_USAGE_SAVINGS";
 /**
  * The named presets for how the gateway folds a session's context (`--context-profile`,
  * launcher.toml `context_profile`, `MNEMOM_AGENT_CONTEXT_PROFILE`). Choosing NONE sends no fold
@@ -607,6 +646,7 @@ export declare function resolveContextProfile(opts: {
  * (`CONTEXT_RUNTIME_ENABLED: "false"` + real-size and intercept `"off"` for `off`; the three fold-tuning keys + size policy off for
  * `aggressive`; size policy off for `balanced`; size policy banded for `adaptive`; nothing when
  * no profile was chosen), then `CONTEXT_HANDOFF_ENABLED: "true"` when context handoff is ON, then
+ * `GATEWAY_USAGE_SAVINGS: "on"` when measured savings is ON (under every profile), then
  * `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>"`
@@ -623,6 +663,8 @@ export declare function buildSessionConfig(opts: {
     compactionIntercept?: boolean;
     /** `resolveCompactAt` output: `null` (or absent) ⇒ no target, send nothing new. */
     compactAt?: number | null;
+    /** `resolveUsageSavings` output: true ⇒ the gateway measures the session's saving. */
+    usageSavings?: boolean;
 }): Record<string, string>;
 /**
  * The `x-mnemom-session-config` payload: `{ v: 1, config, experimental? }`. The active
@@ -634,6 +676,7 @@ export declare function buildSessionConfigPayload(opts: {
     contextHandoff: boolean;
     compactionIntercept?: boolean;
     compactAt?: number | null;
+    usageSavings?: boolean;
     experimental?: readonly string[];
 }): {
     v: 1;
@@ -656,7 +699,8 @@ export declare function buildSessionConfigPayload(opts: {
  *   - `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
- *     per request (see `commands/agent.ts` handoff MCP wiring).
+ *     per request (see `commands/agent.ts` handoff MCP wiring);
+ *   - `usageSavings: true` → `GATEWAY_USAGE_SAVINGS: "on"` (`resolveUsageSavings`).
  * base64url so it survives the gateway's inbound strip.
  */
 export declare function buildSessionConfigB64(opts: {
@@ -664,6 +708,7 @@ export declare function buildSessionConfigB64(opts: {
     contextHandoff: boolean;
     compactionIntercept?: boolean;
     compactAt?: number | null;
+    usageSavings?: boolean;
     experimental?: readonly string[];
 }): string | undefined;
 /**
@@ -689,6 +734,16 @@ export declare function resolveCompactionIntercept(opts: {
     compactionIntercept?: boolean;
     env?: NodeJS.ProcessEnv;
 }): boolean;
+/**
+ * Does the gateway measure this launch's saving (`GATEWAY_USAGE_SAVINGS` in the header, and the
+ * status bar in measured mode)? Only with the `measured-savings` experimental feature on, and
+ * only for Claude Code — the one CLI whose status bar reads the measurement. No flag or
+ * launcher.toml key: `mnemom experimental enable measured-savings` is the switch.
+ */
+export declare function resolveUsageSavings(opts: {
+    experimental: readonly string[];
+    cliName: string;
+}): 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

@@ -25,6 +25,13 @@ import { join } from "node:path";
 import { getGatewayUrl } from "./config.js";
 /** The us-2/prod gateway host. The default door — never any other cell silently. */
 export const PROD_GATEWAY_HOST = "https://gateway.mnemom.ai";
+/**
+ * The standard requirement line `--lead-directed` seals: own-branch push and draft/ready
+ * PR creation, from a git worktree, on the lead's direction — merging is explicitly out.
+ * A single constant so every launch that opts in seals byte-identical wording (MNE-8152).
+ */
+export const LEAD_DIRECTED_REQUIREMENT = "On the lead's direction, this session may push its own branches and open draft or " +
+    "ready pull requests, from a git worktree, never the primary checkout; it may not merge them.";
 /**
  * Resolve the gateway HOST (scheme + host, no path). An explicit, non-empty
  * `MNEMOM_AGENT_GATEWAY` wins verbatim; otherwise the gateway of the cell the rest
@@ -381,7 +388,9 @@ export function contractFlagsPresent(flags) {
         hasText(flags.goalId) ||
         flags.maxTurns !== undefined ||
         flags.budget !== undefined ||
-        flags.stall !== undefined);
+        flags.stall !== undefined ||
+        hasText(flags.mode) ||
+        flags.leadDirected === true);
 }
 function hasText(v) {
     return typeof v === "string" && v.trim().length > 0;
@@ -413,11 +422,18 @@ export function assembleContract(flags) {
     const statement = (flags.goal ?? "").trim();
     if (!statement) {
         throw new Error("--goal is required when any contract flag " +
-            "(--requirement/--allow/--forbid/--goal-id/--budget/--max-turns/--stall) is given.");
+            "(--requirement/--allow/--forbid/--goal-id/--budget/--max-turns/--stall/--mode/--lead-directed) is given.");
+    }
+    const requirements = cleanList(flags.requirement);
+    // Idempotent: append the standard line only when it is not already present, whether
+    // because `--lead-directed` was given more than once or because the exact wording
+    // was already supplied verbatim via `--requirement`.
+    if (flags.leadDirected === true && !requirements.includes(LEAD_DIRECTED_REQUIREMENT)) {
+        requirements.push(LEAD_DIRECTED_REQUIREMENT);
     }
     const contract = {
         statement,
-        requirements: cleanList(flags.requirement),
+        requirements,
         allowed_paths: cleanList(flags.allow),
         forbidden_paths: cleanList(flags.forbid),
     };
@@ -442,6 +458,19 @@ export function assembleContract(flags) {
         }
         contract.stall_turns = Number(flags.stall);
     }
+    // MNE-8199: set only for the non-default "enforce" — the gateway's own canonicalHash
+    // folds `mode` into the hash the same way (see its doc comment): a contract that never
+    // named `--mode` must keep hashing identically to the byte-identical contract sealed
+    // before the field existed, or every live conversation logs `goal_contract_ignored_change`
+    // on deploy. Setting a defaulted "nudge" here unconditionally would instead make the SHA
+    // this prints disagree with the one the gateway actually seals for the exact same launch —
+    // the MNE-7649 class of bug, just reintroduced from the client side.
+    const rawMode = (flags.mode ?? "").trim();
+    if (rawMode && rawMode !== "nudge" && rawMode !== "enforce") {
+        throw new Error(`--mode must be "nudge" or "enforce" (got '${flags.mode}').`);
+    }
+    if (rawMode === "enforce")
+        contract.mode = "enforce";
     const canonical = canonicalJson(contract);
     return {
         contract,
@@ -487,6 +516,15 @@ export const CONTEXT_SIZE_POLICY_KEY = "CONTEXT_RUNTIME_SIZE_POLICY";
  */
 export const USAGE_REAL_SIZE_KEY = "GATEWAY_USAGE_REAL_SIZE";
 export const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
+/**
+ * The gateway env key that has it measure each request's saving for a single session and put
+ * it in the client-facing usage (`mnemom_savings` in the read `usage.iterations` entry), where
+ * the status bar reads it from Claude Code's transcript. Default OFF on the gateway; sent `"on"`
+ * only while the `measured-savings` experimental feature is on and the launched CLI is Claude
+ * Code (`resolveUsageSavings`). Independent of folding, so every profile sends it — `off` too,
+ * where the measured saving is honestly $0.00.
+ */
+export const USAGE_SAVINGS_KEY = "GATEWAY_USAGE_SAVINGS";
 /**
  * The named presets for how the gateway folds a session's context (`--context-profile`,
  * launcher.toml `context_profile`, `MNEMOM_AGENT_CONTEXT_PROFILE`). Choosing NONE sends no fold
@@ -747,7 +785,7 @@ export function applyGatewayHintHeaders(childEnv) {
     }
     return childEnv;
 }
-const SEALED_ONLY_FLAGS = "--goal/--requirement/--allow/--forbid/--goal-id";
+const SEALED_ONLY_FLAGS = "--goal/--requirement/--allow/--forbid/--goal-id/--mode/--lead-directed";
 /**
  * `--implicit` and a sealed contract are mutually exclusive: on the gateway a
  * sealed `x-mnemom-contract` always wins and would silently switch implicit mode
@@ -759,7 +797,9 @@ function assertImplicitCompatible(flags) {
         (flags.requirement?.length ?? 0) > 0 ||
         (flags.allow?.length ?? 0) > 0 ||
         (flags.forbid?.length ?? 0) > 0 ||
-        hasText(flags.goalId);
+        hasText(flags.goalId) ||
+        hasText(flags.mode) ||
+        flags.leadDirected === true;
     if (sealed) {
         throw new Error(`--implicit cannot be combined with ${SEALED_ONLY_FLAGS}: a sealed contract always wins on ` +
             "the gateway and would silently switch implicit mode off. Drop --implicit to seal a " +
@@ -997,6 +1037,7 @@ export function resolveContextProfile(opts) {
  * (`CONTEXT_RUNTIME_ENABLED: "false"` + real-size and intercept `"off"` for `off`; the three fold-tuning keys + size policy off for
  * `aggressive`; size policy off for `balanced`; size policy banded for `adaptive`; nothing when
  * no profile was chosen), then `CONTEXT_HANDOFF_ENABLED: "true"` when context handoff is ON, then
+ * `GATEWAY_USAGE_SAVINGS: "on"` when measured savings is ON (under every profile), then
  * `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>"`
@@ -1014,6 +1055,9 @@ export function buildSessionConfig(opts) {
     }
     if (opts.contextHandoff)
         config[CONTEXT_HANDOFF_KEY] = "true";
+    // Before the `off` return: measuring is not folding, so an off session sends it too.
+    if (opts.usageSavings)
+        config[USAGE_SAVINGS_KEY] = "on";
     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
@@ -1059,7 +1103,8 @@ export function buildSessionConfigPayload(opts) {
  *   - `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
- *     per request (see `commands/agent.ts` handoff MCP wiring).
+ *     per request (see `commands/agent.ts` handoff MCP wiring);
+ *   - `usageSavings: true` → `GATEWAY_USAGE_SAVINGS: "on"` (`resolveUsageSavings`).
  * base64url so it survives the gateway's inbound strip.
  */
 export function buildSessionConfigB64(opts) {
@@ -1099,6 +1144,15 @@ export function resolveCompactionIntercept(opts) {
         return false;
     return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
 }
+/**
+ * Does the gateway measure this launch's saving (`GATEWAY_USAGE_SAVINGS` in the header, and the
+ * status bar in measured mode)? Only with the `measured-savings` experimental feature on, and
+ * only for Claude Code — the one CLI whose status bar reads the measurement. No flag or
+ * launcher.toml key: `mnemom experimental enable measured-savings` is the switch.
+ */
+export function resolveUsageSavings(opts) {
+    return opts.experimental.includes("measured-savings") && opts.cliName === "claude";
+}
 /** The name the `handoff` MCP tool server is registered under in `--mcp-config`. */
 export const HANDOFF_MCP_SERVER_NAME = "mnemom-handoff";
 /**

package/dist/lib/api.d.ts

@@ -1289,6 +1289,22 @@ export interface AgentSessionGuardrails {
         };
     } | null;
 }
+/**
+ * One entry of the gateway's verdict trail (R10, MNE-8200) — up to the last 50 judged turns,
+ * oldest first (same order the gateway stores and returns them in). `request_id` is the request
+ * that produced this verdict, or null when the judge ran without one. `fence_breach` is `true`/
+ * `false` for a conclusive mechanical allowed/forbidden-paths check, `null` when the contract has
+ * no fences or the verdict predates the check. This shape is also what MNE-8234 mirrors — keep
+ * the field name and member shape stable.
+ */
+export interface AgentSessionVerdictTrailEntry {
+    request_id: string | null;
+    turn: number;
+    verdict: "aligned" | "drifting" | "violation";
+    reason: string;
+    fence_breach: boolean | null;
+    at: string;
+}
 /** `GET /v1/agent/sessions/{conversationId}` 200 body. Nulls mean "nothing stored" — absence is data. */
 export interface AgentSessionResponse {
     conversation_id: string;
@@ -1301,6 +1317,8 @@ export interface AgentSessionResponse {
     verdict: AgentSessionVerdict | null;
     turn: number | null;
     guardrails: AgentSessionGuardrails | null;
+    /** Absent on an older server (back-compat) — never shown then, never an empty-array assumption. */
+    verdict_trail?: AgentSessionVerdictTrailEntry[];
 }
 /**
  * The live goal state of one `mnemom agent` session, read through mnemom-api

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" | "compaction-intercept";
+export type ExperimentalId = "context-handoff" | "slack" | "implicit" | "compaction-intercept" | "measured-savings";
 /**
  * Is a `compact_at` / `MNEMOM_COMPACT_AT` value (trimmed, case-insensitive) an ARMED gateway
  * target, as opposed to "no target" (`""`, `"1m"`, `"off"`)? Deliberately duplicates

package/dist/lib/experimental.js

@@ -69,6 +69,18 @@ export const EXPERIMENTAL_FEATURES = [
             env: ["MNEMOM_AGENT_COMPACTION_INTERCEPT"],
         },
     },
+    {
+        // No flag, launcher.toml key or env of its own: `mnemom experimental enable` is the switch.
+        id: "measured-savings",
+        summary: "The status bar shows the saving the gateway measured on this session instead of the benchmark estimate",
+        since: "0.17.16",
+        gates: {
+            flags: [],
+            configKeys: [],
+            commands: [],
+            env: [],
+        },
+    },
 ];
 export const EXPERIMENTAL_IDS = EXPERIMENTAL_FEATURES.map((f) => f.id);
 export const EXPERIMENTAL_ENV = "MNEMOM_EXPERIMENTAL";

package/dist/lib/statusline-bin.js

@@ -4,13 +4,14 @@
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { INNER_ENV, render } from "./statusline.js";
+import { INNER_ENV, measuredMode, render } from "./statusline.js";
 const chunks = [];
 process.stdin.on("data", (c) => chunks.push(c));
 process.stdin.on("end", () => {
     const line = render(Buffer.concat(chunks).toString("utf8"), {
         stateDir: join(homedir(), ".mnemom", "statusline"),
         inner: process.env[INNER_ENV] || undefined,
+        measured: measuredMode(process.env),
     });
     process.stdout.write(`${line}\n`);
 });

package/dist/lib/statusline.d.ts

@@ -13,6 +13,15 @@
  * keeps each file's byte offset and each message id's contribution, and a tick reads at
  * most MAX_BYTES_PER_TICK of new bytes (a big resumed session catches up over ticks).
  *
+ * Measured mode (the `measured-savings` experimental feature; the launch sets
+ * MNEMOM_STATUSLINE_MEASURED=1): the gateway measures each request's saving — the stock
+ * request's input cost minus what it billed — and writes it into the response usage as
+ * `mnemom_savings` inside a `usage.iterations` entry, the one place Claude Code keeps an
+ * unknown usage key in its transcript. The counter sums those per message id
+ * ("mnemom saved $X this session", no "~": it is measured) and makes no claim before the
+ * first one arrives. Its state lives in its own file (<session>.measured.json), so the two
+ * modes never share a count.
+ *
  * A user's own statusLine is never replaced: the launch passes it in
  * MNEMOM_STATUSLINE_INNER, it runs with the same stdin, and our segment is appended.
  * Read-only on every transcript; no network. It lives outside lib/first-run because it runs
@@ -24,6 +33,8 @@ export declare const MAX_BYTES_PER_TICK: number;
 export declare const INNER_ENV = "MNEMOM_STATUSLINE_INNER";
 /** Set to 1 to launch without the counter. */
 export declare const NO_STATUSLINE_ENV = "MNEMOM_AGENT_NO_STATUSLINE";
+/** The launcher sets this to 1 when the gateway measures the session's saving. */
+export declare const MEASURED_ENV = "MNEMOM_STATUSLINE_MEASURED";
 export declare const INNER_TIMEOUT_MS = 2000;
 export interface SessionState {
     v: 1;
@@ -35,6 +46,17 @@ export interface SessionState {
     saved: number;
 }
 export declare function freshState(): SessionState;
+/** Measured mode's state (<session>.measured.json). */
+export interface MeasuredState {
+    v: 1;
+    files: Record<string, number>;
+    /** Per message id: the gateway's measured saving (USD). A re-written id replaces its old share. */
+    ids: Record<string, number>;
+    saved: number;
+    /** Has any record carried a measurement yet? Until then the segment makes no claim. */
+    seen: boolean;
+}
+export declare function freshMeasuredState(): MeasuredState;
 /** The main transcript, then its subagent transcripts (sorted). */
 export declare function sessionFiles(transcriptPath: string): string[];
 /**
@@ -47,17 +69,38 @@ export declare function readNewLines(path: string, offset: number, maxBytes: num
 } | null;
 /** Read what is new in the session's files into `st`. A file that shrank resets the count. */
 export declare function update(st: SessionState, files: string[], maxBytes?: number): SessionState;
+/** A `usage.iterations` entry's measured saving (`mnemom_savings` v1), or null. */
+export declare function measuredSaving(entry: unknown): number | null;
+/**
+ * One transcript line → the gateway's measured saving for its request, or null (not an
+ * assistant record, or no measurement in its `message.usage.iterations`). `id` is the message
+ * id (or record uuid); null when the record carries neither. Claude Code writes one record per
+ * content block, all with the same id and usage, so the id is what dedupes them.
+ */
+export declare function parseMeasuredLine(line: Buffer): {
+    id: string | null;
+    saved: number;
+} | null;
+/** Measured mode's `update`: sums each request's measured saving, replace-by-id. */
+export declare function updateMeasured(st: MeasuredState, files: string[], maxBytes?: number): MeasuredState;
 /** The segment, rounded DOWN to the cent and never below $0.00. */
 export declare function segment(saved: number): string;
+/** Measured mode's segment: no claim until the gateway has measured something; no "~". */
+export declare function measuredSegment(st: MeasuredState): string;
 export declare function loadState(path: string): SessionState;
-export declare function saveState(path: string, st: SessionState): void;
+export declare function loadMeasuredState(path: string): MeasuredState;
+export declare function saveState(path: string, st: SessionState | MeasuredState): void;
 /** Run the user's own statusLine command with the same stdin; its first line, or "". */
 export declare function runInner(command: string, input: string): string;
 export interface RenderDeps {
     stateDir: string;
     inner?: string;
+    /** Measured mode (`measuredMode`): the gateway's measured saving, not the estimate. */
+    measured?: boolean;
     runInner?: (command: string, input: string) => string;
 }
+/** Is the counter in measured mode? The launch's MEASURED_ENV, exactly "1". */
+export declare function measuredMode(env: NodeJS.ProcessEnv): boolean;
 /** Claude Code's status JSON → the one status line. Never throws. */
 export declare function render(stdin: string, deps: RenderDeps): string;
 export interface UserStatusLine {
@@ -72,6 +115,7 @@ export declare function userStatusLine(cwd: string, configDir: string): UserStat
 /**
  * Launch args + env that add the counter, or null when it should stay off: the opt-out
  * env, or the user passing their own --settings (two would fight over precedence).
+ * `measured` puts the counter in measured mode (MEASURED_ENV).
  */
 export declare function statuslineLaunch(o: {
     passthrough: readonly string[];
@@ -80,6 +124,7 @@ export declare function statuslineLaunch(o: {
     home?: string;
     node: string;
     bin: string;
+    measured?: boolean;
 }): {
     args: string[];
     env: Record<string, string>;