@aragon-agent/cli 0.6.4 → 0.6.7

package/dist/agent/reducer.js

@@ -11,11 +11,25 @@
  *     synthesizes a generic error notice (a swallowed throw is never a no-op).
  */
 import process from 'node:process';
-import { occupiedTokens } from '../compaction/pressure.js';
-import { computeCost } from './usage.js';
+import { emptyContextUsage } from '../compaction/meter.js';
+import { addUsage, computeCost } from './usage.js';
 import { ENTRY_LIMITS, appendBounded, entryRetain, trimEntries } from './entry-limits.js';
 /** Default auto-dismiss window for a toast. */
 export const DEFAULT_TOAST_TTL_MS = 2500;
+/**
+ * The zero session total.
+ *
+ * ONE LITERAL FOR TWO SITES (`initialViewState` and `resetConversation`). They
+ * used to spell the object out twice, which is how `cacheReadTokens` would have
+ * been added to one of them and not the other.
+ */
+const EMPTY_USAGE_TOTAL = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    costUsd: 0,
+};
 /**
  * The initial view state, optionally seeded from config.
  *
@@ -33,8 +47,8 @@ export function initialViewState(seed = {}) {
     return {
         entries: [],
         status: 'idle',
-        usageTotal: { inputTokens: 0, outputTokens: 0, costUsd: 0 },
-        contextTokens: 0,
+        usageTotal: EMPTY_USAGE_TOTAL,
+        context: emptyContextUsage(),
         overlay: null,
         thinkingVisible: seed.thinkingVisible ?? false,
         toasts: [],
@@ -48,7 +62,6 @@ export function initialViewState(seed = {}) {
         retry: null,
         fast: null,
         compaction: null,
-        contextTokensEstimated: false,
         seq: 0,
         teamEntryId: undefined,
         todoEntryId: undefined,
@@ -610,22 +623,12 @@ export function viewReducer(state, action) {
                 ...state,
                 streamingId: undefined,
                 turnProduced: true,
-                // ONE FUNCTION, SHARED WITH THE COMPACTION TRIGGER (§3.4.1 / R-11 /
-                // AC-3). The old expression — `inputTokens + outputTokens` — silently
-                // UNDER-reports for anyone behind a caching gateway, because Anthropic
-                // reports `input_tokens` EXCLUDING cached tokens and puts them in two
-                // separate fields. That was a live defect in the number this gauge shows;
-                // it becomes a much worse one the moment a trigger fires on a different
-                // number from the one the user is watching.
-                contextTokens: occupiedTokens(action.usage),
-                // A MEASUREMENT SUPERSEDES A DERIVATION (§6.2). `compactionEnd` writes an
-                // estimate so the bar falls immediately; this is where it stops being one.
-                contextTokensEstimated: false,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
+                // `contextTokens` IS NOT WRITTEN HERE ANY MORE (I-1). The occupancy this
+                // turn produced reaches the view through `ContextMeter`, which subscribes
+                // to the same `turn_end` and publishes the measured pressure - window,
+                // percentage and approximation markers included, none of which this
+                // branch ever had. Two branches writing one number is what P0-1 was.
+                usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta),
                 // The turn produced an answer, so whatever it had to retry, it recovered.
                 ...settleRetryCard(state, entries, 'recovered'),
             };
@@ -763,8 +766,13 @@ export function viewReducer(state, action) {
                 droppedEntries: 0,
                 streamingId: undefined,
                 expandedToolIds: {},
-                contextTokens: 0,
-                usageTotal: { inputTokens: 0, outputTokens: 0, costUsd: 0 },
+                // `context` IS DELIBERATELY UNTOUCHED (I-1). `builtins.ts` calls
+                // `controller.clearMessages()` BEFORE dispatching this, and that marks
+                // the meter dirty and schedules a publication; zeroing here would make
+                // the final state `0` rather than the meter's real answer - which for an
+                // emptied conversation is the system prompt's own couple of percent, not
+                // nothing. `usageTotal` DOES reset: that is session spend, not occupancy.
+                usageTotal: EMPTY_USAGE_TOTAL,
                 teamEntryId: undefined,
                 // `/reset` clears `messages`, so the belief is gone and the list goes
                 // with it — the other half of I-2. `controller.clearMessages()` clears
@@ -774,10 +782,6 @@ export function viewReducer(state, action) {
                 retryEntryId: undefined,
                 retry: null,
                 compactionEntryId: undefined,
-                // `contextTokens` is zeroed above, so the flag that says it is a
-                // DERIVATION has to go with it — otherwise a fresh conversation renders
-                // `~0%` and the tilde is a lie about a number that is simply zero.
-                contextTokensEstimated: false,
             };
         case 'setOverlay':
             return { ...state, overlay: action.overlay };
@@ -860,18 +864,11 @@ export function viewReducer(state, action) {
         }
         case 'teamUsage':
             // `usageTotal` AND NOTHING ELSE (§3.9 / AC-15). In particular NOT
-            // `contextTokens`: that gauge shows the LEAD's context occupancy against
+            // `context`: that gauge shows the LEAD's context occupancy against
             // the model's window, and folding five children into it would read 180%
             // on a perfectly healthy session. Child spend is real money and has to
             // appear in the cost readout; it is not the lead's context.
-            return {
-                ...state,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
-            };
+            return { ...state, usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta) };
         case 'teamEnd': {
             const { outcome } = action;
             const entries = state.teamEntryId
@@ -991,17 +988,10 @@ export function viewReducer(state, action) {
         }
         case 'fastUsage':
             // `usageTotal` AND NOTHING ELSE, exactly as `teamUsage` (§3.6 / AC-18). In
-            // particular NOT `contextTokens`: that gauge shows the LEAD's context
+            // particular NOT `context`: that gauge shows the LEAD's context
             // occupancy against the lead model's window, and a review is a separate
             // conversation with a different model entirely.
-            return {
-                ...state,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
-            };
+            return { ...state, usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta) };
         case 'fastTier':
             return { ...state, fast: action.snapshot };
         // --- Context compaction (context-auto-compaction §5.5) ----------------
@@ -1128,40 +1118,41 @@ export function viewReducer(state, action) {
         }
         case 'compactionUsage':
             // `usageTotal` AND NOTHING ELSE, exactly as `teamUsage` and `fastUsage`. In
-            // particular NOT `contextTokens`: that gauge shows the LEAD's context
+            // particular NOT `context`: that gauge shows the LEAD's context
             // occupancy against the lead model's window, and a summarization is a
             // separate conversation with a possibly different model entirely.
-            return {
-                ...state,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
-            };
+            return { ...state, usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta) };
         case 'compactionSnapshot':
             return { ...state, compaction: action.snapshot };
         /**
-         * THE GAUGE MUST FALL IMMEDIATELY (§6.2 / AC-5).
+         * THE ONE WRITER OF `state.context` (I-1).
          *
-         * `contextTokens` is otherwise only written at `turnEnd`, so a compaction
-         * that took the session from 92 % to 24 % would leave the bar at 92 % until
-         * the next turn completes — and the user would reasonably conclude that
-         * nothing happened. This is a small change and it is the difference between
-         * the feature feeling real and feeling broken.
+         * THE IDENTITY SHORT-CIRCUIT BELOW IS LOAD-BEARING, NOT A MICRO-OPTIMISATION
+         * (§5.2 / R-3). The meter publishes on a 400 ms tick throughout a turn and
+         * most of those ticks measure the same number - the history did not change
+         * between two tool calls of the same size, or the percentage rounded to the
+         * same integer. Returning the SAME state object lets React skip the whole
+         * subtree; returning a fresh one would make a permanently visible row into a
+         * 2.5 Hz re-render source and walk the render governor up its ladder for no
+         * visible change at all.
          *
-         * The value arrives ALREADY CALIBRATED from `App` (§6.2 / P1-11): it replaces
-         * a MEASUREMENT that included the tool schemas, and core's raw estimator
-         * never counts them, so writing the raw figure would make the bar fall too
-         * far and then visibly climb again on the next `turn_end` for no reason the
-         * user can see.
+         * `ContextUsageSnapshot` carries no timestamp for exactly this reason: a
+         * field that moves every tick would make this comparison never hold.
          */
-        case 'contextTokensEstimated':
-            return {
-                ...state,
-                contextTokens: Math.max(0, Math.round(action.tokens)),
-                contextTokensEstimated: true,
-            };
+        case 'contextUsage': {
+            const prev = state.context;
+            const next = action.snapshot;
+            if (prev.occupied === next.occupied &&
+                prev.window === next.window &&
+                prev.pct === next.pct &&
+                prev.source === next.source &&
+                prev.deltaTokens === next.deltaTokens &&
+                prev.windowKnown === next.windowKnown &&
+                prev.windowOverridden === next.windowOverridden) {
+                return state;
+            }
+            return { ...state, context: next };
+        }
         // --- API retry (llm-api-retry-backoff §6.4) ---------------------------
         case 'retryScheduled': {
             const snapshot = {

package/dist/agent/usage.d.ts

@@ -3,8 +3,42 @@
  * (which is expressed in USD per 1M tokens). See spec §6.2 status bar.
  */
 import type { ModelCost, TokenUsage } from '@aragon-agent/core';
+import type { UsageTotal } from './reducer.js';
 /** Compute the USD cost of a single `TokenUsage` given a model's cost table. */
 export declare function computeCost(usage: TokenUsage, cost?: ModelCost): number;
+/**
+ * Fold one `TokenUsage` into a running session total
+ * (context-usage-gauge-accuracy §3.6 / W5).
+ *
+ * THE ONE ADDITION SITE, and collapsing four hand-written copies into it is the
+ * point rather than a tidy-up. The reducer had the same three lines in four
+ * branches - `turnEnd`, `teamUsage`, `fastUsage`, `compactionUsage` - and all
+ * four silently omitted the cache terms, so the status bar's `^` read LOWER than
+ * the `$` beside it on any session behind a caching gateway. A fifth source
+ * added later would have made the identical omission; now it cannot.
+ *
+ * `costDelta` IS PRECOMPUTED BY THE CALLER, exactly as the four branches already
+ * required: the summarizer and the fast tier may be different models with
+ * different price tables, and a reducer that priced its own would have to know
+ * about three of them.
+ */
+export declare function addUsage(total: UsageTotal, usage: TokenUsage, costDelta: number): UsageTotal;
+/**
+ * The number the status bar's `^` shows: the PROMPT side of the session total.
+ *
+ * DELIBERATELY THE SAME TERMS AS `occupiedTokens` MINUS `outputTokens`
+ * (`compaction/pressure.ts`). Anthropic reports `input_tokens` EXCLUDING cached
+ * tokens and puts them in two separate fields, so `inputTokens` alone
+ * under-reports for anyone behind a caching gateway - while `computeCost` above
+ * has always priced all three. That is the "three units on one row" defect
+ * (P1-3): the percentage counted cache, the dollars counted cache, and the arrow
+ * did not.
+ *
+ * `$` IS STILL NOT THE SAME TOTAL, and the distinction is worth keeping straight
+ * (RV-14): `computeCost` also prices OUTPUT tokens. What this function asserts is
+ * narrower and exact - both cache terms are counted, on both sides.
+ */
+export declare function promptTokensOf(total: UsageTotal): number;
 /** Format a USD amount for the status bar (`$0.0000`, or `$1.23` when large). */
 export declare function formatCost(usd: number): string;
 /** Format a token count compactly (`1.2k`, `3.4M`). */

package/dist/agent/usage.js

@@ -12,6 +12,49 @@ export function computeCost(usage, cost) {
         perM(usage.cacheReadTokens ?? 0, cost.cacheRead) +
         perM(usage.cacheWriteTokens ?? 0, cost.cacheWrite));
 }
+/**
+ * Fold one `TokenUsage` into a running session total
+ * (context-usage-gauge-accuracy §3.6 / W5).
+ *
+ * THE ONE ADDITION SITE, and collapsing four hand-written copies into it is the
+ * point rather than a tidy-up. The reducer had the same three lines in four
+ * branches - `turnEnd`, `teamUsage`, `fastUsage`, `compactionUsage` - and all
+ * four silently omitted the cache terms, so the status bar's `^` read LOWER than
+ * the `$` beside it on any session behind a caching gateway. A fifth source
+ * added later would have made the identical omission; now it cannot.
+ *
+ * `costDelta` IS PRECOMPUTED BY THE CALLER, exactly as the four branches already
+ * required: the summarizer and the fast tier may be different models with
+ * different price tables, and a reducer that priced its own would have to know
+ * about three of them.
+ */
+export function addUsage(total, usage, costDelta) {
+    return {
+        inputTokens: total.inputTokens + usage.inputTokens,
+        outputTokens: total.outputTokens + usage.outputTokens,
+        cacheReadTokens: total.cacheReadTokens + (usage.cacheReadTokens ?? 0),
+        cacheWriteTokens: total.cacheWriteTokens + (usage.cacheWriteTokens ?? 0),
+        costUsd: total.costUsd + costDelta,
+    };
+}
+/**
+ * The number the status bar's `^` shows: the PROMPT side of the session total.
+ *
+ * DELIBERATELY THE SAME TERMS AS `occupiedTokens` MINUS `outputTokens`
+ * (`compaction/pressure.ts`). Anthropic reports `input_tokens` EXCLUDING cached
+ * tokens and puts them in two separate fields, so `inputTokens` alone
+ * under-reports for anyone behind a caching gateway - while `computeCost` above
+ * has always priced all three. That is the "three units on one row" defect
+ * (P1-3): the percentage counted cache, the dollars counted cache, and the arrow
+ * did not.
+ *
+ * `$` IS STILL NOT THE SAME TOTAL, and the distinction is worth keeping straight
+ * (RV-14): `computeCost` also prices OUTPUT tokens. What this function asserts is
+ * narrower and exact - both cache terms are counted, on both sides.
+ */
+export function promptTokensOf(total) {
+    return total.inputTokens + total.cacheReadTokens + total.cacheWriteTokens;
+}
 /** Format a USD amount for the status bar (`$0.0000`, or `$1.23` when large). */
 export function formatCost(usd) {
     if (usd <= 0)

package/dist/cli.js

@@ -27,7 +27,7 @@ import { COMPACTION_CONFIG_SET_KEYS, FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS,
 import { attachAgentEvents, attachTeamEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
 import { getLogger } from './logging/logger.js';
 import { runLogsCommand } from './logging/cli-commands.js';
-import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SCROLL_RESUME_MS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
+import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampContextWindow, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, isAutoToken, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SCROLL_RESUME_MS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
 import { makeGetApiKey } from './config/load.js';
 import { AgentController, DENY_ALL_APPROVAL } from './agent/controller.js';
 import { runSkillsCommand } from './skills/cli-commands.js';
@@ -153,6 +153,11 @@ function toFlags(opts) {
         fastModel: opts.fastModel,
         fastProvider: opts.fastProvider,
         fastReview: opts.fastReview,
+        // …and again for `--fast-delegate` / `--no-fast-delegate`, one feature
+        // later — NINE features, one trap. It is `fast.delegate`'s only channel:
+        // there is no `ARAGON_FAST_DELEGATE`, so missing this line leaves a wrapper
+        // with no way at all to say "do not delegate on this run".
+        fastDelegate: opts.fastDelegate,
         // `--verbose` is just a shorthand for `--log-level debug`; an explicit
         // `--log-level` still wins, so the two can be combined without surprise.
         logLevel: opts.logLevel ?? (opts.verbose ? 'debug' : undefined),
@@ -924,6 +929,11 @@ const CONFIG_SET_KEYS = new Set([
     'baseUrl',
     'thinkingLevel',
     'maxTokens',
+    // context-usage-gauge-accuracy §3.6. Listed here AND given its own branch in
+    // `runConfigSet` below - a key present here but absent there falls through
+    // every case, writes nothing, and still prints `Set contextWindow = 1000000`
+    // (P1-2).
+    'contextWindow',
     'theme',
     'confirmTools',
     'toolTimeoutMs',
@@ -1020,6 +1030,30 @@ function runConfigSetMaxTokens(value) {
     const merged = updatePersistedConfig({ maxTokens: stored });
     process.stdout.write(`Set maxTokens = ${merged.maxTokens ?? 'auto'}\n`);
 }
+/**
+ * `aragon config set contextWindow <n|auto>`.
+ *
+ * ITS OWN BRANCH, AHEAD OF THE SWITCH, for the reason `maxTokens` has one: it
+ * must echo the STORED value rather than the typed one, so
+ * `config set contextWindow 99999999` reports the clamped 5000000 instead of a
+ * number that was never written. It also REJECTS nonsense rather than clamping
+ * it - a non-numeric argument here is almost always a typo for a number, and
+ * storing AUTO for `20O000` would quietly discard the user's intent.
+ */
+function runConfigSetContextWindow(value) {
+    const trimmed = value.trim();
+    const auto = isAutoToken(trimmed);
+    if (!auto && !/^\d+$/.test(trimmed)) {
+        process.stderr.write(`Invalid contextWindow "${value}". Use a number of tokens or "auto".\n`);
+        process.exitCode = 2;
+        return;
+    }
+    // `null` GOES IN UNCLAMPED (RV-12). Running AUTO through the clamp yields
+    // 8000 and removes "auto" from the config permanently.
+    const stored = auto ? null : clampContextWindow(trimmed, null);
+    const merged = updatePersistedConfig({ contextWindow: stored });
+    process.stdout.write(`Set contextWindow = ${merged.contextWindow ?? 'auto'}\n`);
+}
 function runConfigSet(key, value) {
     if (!CONFIG_SET_KEYS.has(key)) {
         process.stderr.write(`Unknown config key "${key}". Known keys: ${[...CONFIG_SET_KEYS].join(', ')}.\n`);
@@ -1040,6 +1074,11 @@ function runConfigSet(key, value) {
         runConfigSetMaxTokens(value);
         return;
     }
+    // The second tri-state key, and it needs its own branch for the same reason.
+    if (key === 'contextWindow') {
+        runConfigSetContextWindow(value);
+        return;
+    }
     const teamPatch = applyTeamConfigSet(key, value);
     if (teamPatch) {
         // The written value is echoed from the CLAMPED result rather than from the
@@ -1491,6 +1530,14 @@ function buildProgram() {
         .option('--fast-model <id>', 'The fast model id (implies nothing about --fast)')
         .option('--fast-provider <id>', 'Provider for the fast model (default: the main provider)')
         .option('--fast-review <n|off>', 'Turns between automatic fast reviews, or "off"')
+        // BOTH FORMS, POSITIVE FIRST, and here it matters more than anywhere above:
+        // `fast.delegate` is PERSISTED and defaults to TRUE, so declaring only
+        // `--no-fast-delegate` would make commander default `opts.fastDelegate` to
+        // `true` and force `delegate: true` on EVERY run that passed no flag at all
+        // — silently overwriting a user's stored `false`. Same polarity, same trap
+        // and same fix as `--update` / `--compaction`.
+        .option('--fast-delegate', 'Let the fast tier take mechanical sub-steps (the default)')
+        .option('--no-fast-delegate', 'Run every sub-step on the main model')
         // BOTH FORMS, positive first, for the reason recorded seven times above —
         // and this is the pair whose omission would be worst. `update.mode` is
         // PERSISTED and defaults to `'auto'`, so a lone `--no-update` would make

package/dist/commands/builtins.js

@@ -17,6 +17,7 @@ import { getLogger } from '../logging/logger.js';
 import { copyText } from '../ui/clipboard.js';
 import { perfCommand } from './perf.js';
 import { runCompactCommand } from '../compaction/command.js';
+import { runContextCommand } from '../compaction/context-command.js';
 /**
  * `/fast status` — THE GUARANTEED REPORTING SURFACE for the tier (§4.4 / R-8).
  *
@@ -809,6 +810,14 @@ const COMMANDS = [
         description: 'Context compaction: status | on | off | threshold <n> | keep <n> | <instructions>',
         run: (ctx) => runCompactCommand(ctx),
     },
+    {
+        // REGISTRATION ONLY, for the reason `/compact` records one entry up: this
+        // file is past the 1000-line guideline and the report has five sections.
+        // The body is in `compaction/context-command.ts`.
+        name: 'context',
+        description: 'Show context occupancy, the window it is measured against, and session spend',
+        run: (ctx) => runContextCommand(ctx),
+    },
     {
         name: 'expand',
         // DELIBERATELY LEFT TOOL-ONLY, and the asymmetry with Ctrl+O is a decision

package/dist/compaction/compactor.d.ts

@@ -12,6 +12,7 @@
 import { type Message, type ModelInfo, type ModelRef, type TokenUsage, type AssistantMessage, type CompactionContext, type CompactionOutcome, type CompactionProbe, type ContextManager, type LLMRequest } from '@aragon-agent/core';
 import type { CliConfig } from '../config/schema.js';
 import type { NoticeLevel } from '../agent/reducer.js';
+import { ContextMeter } from './meter.js';
 import type { CompactionEvent, Pressure } from './types.js';
 export interface CompactorDeps {
     /** Read LIVE on every call — the controller replaces the object on mutation. */
@@ -42,6 +43,24 @@ export interface CompactorDeps {
     complete: (providerId: string, request: LLMRequest) => Promise<AssistantMessage>;
     emit: (event: CompactionEvent) => void;
     notify: (level: NoticeLevel, text: string) => void;
+    /**
+     * The ONE owner of occupancy measurement (context-usage-gauge-accuracy W1).
+     *
+     * THE COMPACTOR NO LONGER MEASURES. It used to hold `estimateOffset`,
+     * `measuredPrefixLength` and `lastPressure` itself, which locked the only
+     * measuring code in the process behind `compaction.enabled` - and a session
+     * that turned compaction OFF is exactly the one whose gauge then had a single
+     * sample per turn and nothing else. Reading a meter the controller owns makes
+     * "the trigger and the gauge read one number" a STRUCTURAL fact rather than a
+     * discipline (§3.3).
+     *
+     * OPTIONAL SO EVERY EXISTING CONSTRUCTION SITE COMPILES (R-1), and lazily
+     * replaced by a private one built from the deps already here. PRODUCTION MUST
+     * INJECT: `context-gauge-wiring.test.ts` asserts one instance per process
+     * (`controller.getContextMeter()` is the same object the wiring forwards), and
+     * two meters in one session means two answers to one question.
+     */
+    meter?: ContextMeter;
     /**
      * Publish the occupancy this checkpoint measured (hardening §3.2.4 / DH-15).
      *
@@ -96,18 +115,15 @@ export declare class Compactor implements ContextManager {
     private selfDisabledReason;
     private pendingManual;
     private generation;
-    /** Calibration for every ESTIMATED figure (D-23). Recomputed on every turn_end. */
-    private estimateOffset;
-    /** The last pressure computed, so the status bar and `/compact status` agree. */
-    private lastPressure;
     /**
-     * The history LENGTH the measurement in `lastUsage` covered (hardening W1).
+     * The fallback meter, built on first use when no host injected one (R-1).
      *
-     * `undefined` DISABLES THE DELTA and reproduces round 1's arithmetic exactly.
-     * Every host-side mutation that is not an append must clear it - see
-     * `invalidateMeasurement`.
+     * `estimateOffset`, `measuredPrefixLength` and `lastPressure` used to be
+     * FIELDS HERE. They moved to `ContextMeter` wholesale
+     * (context-usage-gauge-accuracy W1), because keeping them here is what put the
+     * only measurement in the process behind `compaction.enabled`.
      */
-    private measuredPrefixLength;
+    private ownMeter;
     /**
      * The messages the last splice dropped, held ONLY until the wiring collects
      * them for the archive (W4 / RV-3).
@@ -129,21 +145,17 @@ export declare class Compactor implements ContextManager {
     /** `agent_start` — the per-run cap resets, the session totals do not. */
     onRunStart(): void;
     /**
-     * `turn_end` — recompute the calibration offset (D-23).
+     * `turn_end` - recompute the calibration offset (D-23).
      *
-     * RE-MEASURED EVERY TURN, not once, so it tracks a toolset that changed
-     * mid-session (`/tools`, a skill that registers one).
-     */
-    onTurnEnd(usage: TokenUsage, messages: readonly Message[], systemPrompt: string): void;
-    /**
-     * Any host-side history mutation that is NOT an append (hardening §3.2.3).
+     * A THIN FORWARDER since context-usage-gauge-accuracy W1. The meter subscribes
+     * to `turn_end` itself, so BOTH PATHS MUST BE IDEMPOTENT: this one recomputes
+     * exactly what the other one did from the same inputs, which it is.
      *
-     * `/clear`, `/resume`, and the splice itself: after any of them a recorded
-     * index means nothing, and the delta would be measured against the wrong
-     * array. `estimateAppendedTokens` bounds-checks as well, so a MISSED call here
-     * costs accuracy - the number degrades to round 1's - and never correctness.
+     * `messages` / `systemPrompt` stay in the signature and are ignored: the meter
+     * reads them from its own lazy deps, and every existing caller and test keeps
+     * compiling.
      */
-    invalidateMeasurement(): void;
+    onTurnEnd(usage: TokenUsage, _messages: readonly Message[], _systemPrompt: string): void;
     /**
      * The dropped messages, released as they are returned (W4 / RV-3).
      *
@@ -255,15 +267,29 @@ export declare class Compactor implements ContextManager {
     private noteNoProgress;
     private finish;
     /**
-     * The pressure the trigger and the gauge both read.
+     * The pressure the trigger and the gauge both read - MEASURED NOW.
      *
-     * CACHED on every evaluation, so `/compact status` reports the same number the
-     * last decision used rather than recomputing one that has since moved.
+     * A FORWARDER since W1: the decision point supplies its own authoritative
+     * `lastUsage` (the probe's), and the meter owns everything else. `messages` /
+     * `systemPrompt` stay in the signature and are ignored, because the meter
+     * reads the LIVE history through its own deps - which is strictly better than
+     * a caller that could pass `[]` and get a 0 % reading (the old default here).
      */
     measure(probe: Pick<CompactionProbe, 'lastUsage'> & {
         messages?: readonly Message[];
         systemPrompt?: string;
     }): Pressure;
+    /**
+     * The last pressure PUBLISHED. NEVER re-measured - `lastPublished`, not
+     * `current` (I-10 / RV-3).
+     *
+     * `finish()` below reads this for `tokensBefore`, which is the sole upstream of
+     * `tokensReclaimed`, the card's "reclaimed N tokens" and `/compact status`'s
+     * session total. All three want the occupancy BEFORE the splice. Point this at
+     * `meter.current()` and the moment the meter is dirty - which after a splice it
+     * always is - `tokensBefore` becomes the POST-compaction figure, `reclaimed`
+     * collapses to 0, and the card renders that with nothing logging a fault.
+     */
     lastMeasured(): Pressure | null;
     /** Written by the wiring once the engine has reported its verdict. */
     recordApplied(tokensBefore: number, tokensAfter: number): void;
@@ -295,6 +321,16 @@ export declare class Compactor implements ContextManager {
      * entire run, and the spend is on the card with the summarizer's own price.
      */
     resolveSummarizer(): SummarizerChoice | null;
+    /**
+     * The meter this compactor reads, injected or private (R-1).
+     *
+     * MEMOIZED, because a fresh meter on every call would have no `estimateOffset`
+     * and no cached pressure - `lastMeasured()` would answer `null` forever and
+     * `tokensReclaimed` would sit at 0. The fallback exists so the ten existing
+     * `compaction-*.test.ts` construction sites compile unchanged; production
+     * injects, and `context-gauge-wiring.test.ts` asserts the single instance.
+     */
+    private meter;
     private mainRef;
     private modelInfo;
     private effectiveMaxOutputTokens;