@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/compaction/compactor.js

@@ -17,7 +17,8 @@ import { attemptTailRelief, reliefSummary, tailBudgetTokens } from './tail-budge
 import { buildDigest, isPriorSummaryBlock } from './digest.js';
 import { buildAnchor, buildCompactedBlock, countProtectedPrefix, readGeneration, truncationBody, } from './summary-prompt.js';
 import { accumulateUsage, errorText, runSummarizeCall } from './summarize-call.js';
-import { computeEstimateOffset, computePressure, shouldCompactAt } from './pressure.js';
+import { computePressure, shouldCompactAt } from './pressure.js';
+import { ContextMeter } from './meter.js';
 export class Compactor {
     deps;
     log = getLogger().child('compaction');
@@ -26,6 +27,15 @@ export class Compactor {
     lastCompactionTurn = -Infinity;
     // --- Per-session state ---
     compactions = 0;
+    /**
+     * How many `compact()` calls returned WITHOUT announcing (quiet-noop D-9).
+     *
+     * A SESSION TOTAL, LIKE `compactions`, and reset by neither `onRunStart()` nor
+     * `clearSelfDisable()`: `/compact on` overrides a guard, it does not rewrite
+     * history. `/compact status` is its only reader, and it is the whole of what
+     * keeps a decline reportable once the transcript stops carrying one.
+     */
+    declined = 0;
     tokensReclaimed = 0;
     sessionUsage = { inputTokens: 0, outputTokens: 0 };
     pricingUnknown = false;
@@ -35,18 +45,15 @@ export class Compactor {
     selfDisabledReason;
     pendingManual = null;
     generation = 0;
-    /** Calibration for every ESTIMATED figure (D-23). Recomputed on every turn_end. */
-    estimateOffset;
-    /** The last pressure computed, so the status bar and `/compact status` agree. */
-    lastPressure = null;
     /**
-     * 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`.
      */
-    measuredPrefixLength;
+    ownMeter = null;
     /**
      * The messages the last splice dropped, held ONLY until the wiring collects
      * them for the archive (W4 / RV-3).
@@ -78,28 +85,34 @@ export class Compactor {
         this.lastCompactionTurn = -Infinity;
     }
     /**
-     * `turn_end` — recompute the calibration offset (D-23).
+     * `turn_end` - recompute the calibration offset (D-23).
+     *
+     * 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.
      *
-     * RE-MEASURED EVERY TURN, not once, so it tracks a toolset that changed
-     * mid-session (`/tools`, a skill that registers one).
+     * `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.
      */
-    onTurnEnd(usage, messages, systemPrompt) {
-        this.estimateOffset = computeEstimateOffset(usage, messages, systemPrompt);
-        // THE SAME ARRAY `computeEstimateOffset` JUST MEASURED, so the two numbers
-        // describe the same request by construction (hardening §3.2.3).
-        this.measuredPrefixLength = messages.length;
+    onTurnEnd(usage, _messages, _systemPrompt) {
+        this.meter().onTurnEnd(usage);
     }
-    /**
-     * Any host-side history mutation that is NOT an append (hardening §3.2.3).
+    /*
+     * `invalidateMeasurement()` IS GONE, DELIBERATELY (I-9 / RV-2 round two).
+     *
+     * It had exactly two production callers and their reset depths are now
+     * OPPOSITE: `CompactionWiring.onHistoryReplaced` (a `/clear`, `/reset` or
+     * `/resume`) must drop `estimateOffset`, while `settlePending`'s applied
+     * branch (a splice) must KEEP it - the toolset and the model are unchanged, so
+     * the calibration still holds and dropping it makes the gauge fall too far and
+     * climb back (I-5 / I-8). The two used to share a method only because the one
+     * field it cleared happened to be their intersection; that intersection no
+     * longer exists. Both call sites now name the depth they mean, on the meter.
      *
-     * `/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.
+     * Reinstating a forwarder here would hide "which caller gets which depth"
+     * behind a name that mentions neither, and BOTH wrong choices are silent.
      */
-    invalidateMeasurement() {
-        this.measuredPrefixLength = undefined;
-    }
     /**
      * The dropped messages, released as they are returned (W4 / RV-3).
      *
@@ -163,17 +176,13 @@ export class Compactor {
         const config = this.deps.getConfig().compaction;
         if (!config.enabled)
             return false;
-        // THE HISTORY IS PASSED IN, NEVER OMITTED (§3.4.2). Without it the estimate
-        // branch of `computePressure` measures an EMPTY array and reports 0 %, so a
-        // resumed 180 k-token session — where `lastUsage` is `undefined` by
-        // definition and this branch is the only one available — would never trigger.
-        // The measured branch reads `messages` only to estimate what was appended
-        // after the measurement (hardening §3.2.2); the slice is one turn wide.
-        const pressure = this.measure({
-            ...(probe.lastUsage ? { lastUsage: probe.lastUsage } : {}),
-            messages: this.deps.getMessages(),
-            systemPrompt: this.deps.getSystemPrompt(),
-        });
+        // THE METER READS THE LIVE HISTORY ITSELF (W1), so the estimate branch can no
+        // longer be handed an empty array by a caller that forgot - which used to be
+        // a 0 % reading on precisely the session that most needs a trigger, the
+        // resumed 180 k-token one where `lastUsage` is `undefined` by definition.
+        // The probe's own usage is still passed, because it is the authority for
+        // THIS checkpoint.
+        const pressure = this.meter().measureWith(probe.lastUsage);
         this.deps.onPressure?.(pressure);
         const manual = this.pendingManual !== null;
         // Guard 2 — the per-run cap. BOTH TRIGGERS, HARD. It is the bound that makes
@@ -218,22 +227,19 @@ export class Compactor {
         const uiTrigger = manual ? 'manual' : ctx.trigger;
         const config = this.deps.getConfig().compaction;
         const summarizer = this.resolveSummarizer();
+        // GUARDS 1 AND 2 COUNT *ATTEMPTS*, NOT ANNOUNCEMENTS, and they stay here
+        // (quiet-noop §3.3). A decline still consumed a checkpoint: it still has to
+        // serve the cooldown and it still has to be charged to the per-run cap, or a
+        // history that can never be compacted would re-attempt on every turn for the
+        // whole run. `inFlight` stays for the same reason - the chip reports what the
+        // compactor is DOING, not what it has decided to say.
         this.compactionsThisRun += 1;
         this.lastCompactionTurn = ctx.turnIndex;
-        this.compactions += 1;
         this.inFlight = true;
-        const index = this.compactions;
-        this.deps.emit({
-            type: 'compaction_start',
-            index,
-            trigger: uiTrigger,
-            model: summarizer?.ref.modelId ?? '',
-        });
         const started = Date.now();
         try {
             return await this.runCompaction({
                 ctx,
-                index,
                 uiTrigger,
                 config,
                 summarizer,
@@ -250,8 +256,56 @@ export class Compactor {
     // =========================================================================
     // Internals
     // =========================================================================
+    /**
+     * Open the card (quiet-noop §3.2).
+     *
+     * THE ONLY EMITTER OF `compaction_start`, AND THE ONLY PLACE `this.compactions`
+     * ADVANCES. A compaction that never reaches an announce point is a DECLINE: it
+     * changed nothing, called nothing and spent nothing, and it is deliberately
+     * indistinguishable - on every human surface except `/compact status`'s
+     * `declined` count (D-9) - from a turn at which `shouldCompact` returned false.
+     * `finish` is the other half of that rule.
+     *
+     * IT RETURNS THE ANNOUNCEMENT RATHER THAN STORING IT (P1-1), and the caller
+     * keeps it in a LOCAL for the lifetime of one `runCompaction` call - the same
+     * slot `index` occupied before this change. An instance field would have needed
+     * a no-re-entrancy argument, and the obvious one is WRONG: guard 1 lives in
+     * `shouldCompact`, while the idle `/compact` path calls `compact()` straight
+     * through `wiring.compactNow()` without consulting it. What actually keeps two
+     * compactions apart is that `command.ts` QUEUES instead of calling `compactNow`
+     * while the loop runs - a property of a different file, which is exactly why
+     * this one must not depend on it. A clobbered field would leave `finish` unable
+     * to settle the card it opened, and a card that never settles pins
+     * `Transcript`'s monotonic boundary for the rest of the session.
+     */
+    announce(trigger, summarizer) {
+        this.compactions += 1;
+        this.deps.emit({
+            type: 'compaction_start',
+            index: this.compactions,
+            trigger,
+            model: summarizer?.ref.modelId ?? '',
+        });
+        return { index: this.compactions };
+    }
     async runCompaction(args) {
         const { ctx, config, summarizer } = args;
+        // THE ANNOUNCEMENT IS A LOCAL, NEVER A FIELD (quiet-noop §3.2 / P1-1), and
+        // `??=` is what makes the eager path and the two commit points idempotent
+        // with respect to each other.
+        let announced = null;
+        const announce = (model) => {
+            announced ??= this.announce(args.uiTrigger, model);
+        };
+        // A REQUESTED compaction and a REACTIVE one announce BEFORE they know the
+        // answer, for two different reasons. `manual` is a user instruction, and its
+        // QUEUED form (`/compact` typed mid-run) has NO other reporting surface - a
+        // silent decline there would be a command that did nothing and said nothing.
+        // `overflow` runs after the provider has ALREADY refused the request; if it
+        // cannot recover, the card is the only place that says why the run is about
+        // to die. Both paths stay byte-identical to the round before this one.
+        if (args.uiTrigger !== 'pressure')
+            announce(summarizer);
         const before = ctx.messages;
         const protectedPrefix = countProtectedPrefix(before);
         // THE ONE LEVER THE GUARDS DO NOT HAVE (D-24). A tail that alone exceeds the
@@ -271,6 +325,12 @@ export class Compactor {
             // `plan === null` branch tries it before conceding.
             const reliefOnly = this.relieveInPlace(before, protectedPrefix, ctx.systemPrompt);
             if (reliefOnly) {
+                // COMMIT POINT A (quiet-noop §3.4). Relief changes the history the run
+                // continues from - a bounded, announced data loss - so it is announced
+                // even though no model was called. `null` summarizer for the same reason
+                // `finish` writes `model: ''` on a relief-only record: naming a model here
+                // would claim a call that never ran.
+                announce(null);
                 this.checkProgress(ctx, args.uiTrigger, reliefOnly.messages);
                 return this.finish({ ...args, tailRelief: reliefSummary(reliefOnly) }, {
                     action: 'replace',
@@ -282,17 +342,51 @@ export class Compactor {
                     mode: 'truncated',
                     messages: reliefOnly.messages,
                     reason: 'tail_relief_only',
-                }, { droppedMessages: 0 }, keepRecentTurns);
+                }, { droppedMessages: 0 }, keepRecentTurns, announced);
             }
             this.noteNoProgress(args.uiTrigger, 'nothing_to_drop');
-            return this.finish(args, { action: 'keep', reason: 'nothing_to_drop' }, null, keepRecentTurns);
+            return this.finish(args, { action: 'keep', reason: 'nothing_to_drop' }, null, keepRecentTurns, announced);
         }
         const anchor = buildAnchor(before);
         if (!anchor) {
             // A history with no `user` message at all cannot have a goal anchor, and
             // D-6 makes the anchor non-negotiable. Refusing is the honest outcome.
-            return this.finish(args, { action: 'keep', reason: 'no_anchor' }, null, keepRecentTurns);
+            //
+            // STRUCTURALLY UNREACHABLE, AND KEPT ANYWAY (quiet-noop E-23 / §3.4). This
+            // is reached only after `plan !== null`, and `planCompaction` returns a plan
+            // only when some cut leaves `countTurns >= keep` behind it - `countTurns`
+            // counts `user`-role messages and `keep` is at least 1, so a plan PROVES the
+            // one thing `buildAnchor` looks for. A provably dead guard is worth strictly
+            // more than the non-null assertion that would replace it. It stays ABOVE the
+            // commit point on purpose: if the plan/anchor relationship ever changes, the
+            // reason that appears is one decided before any work began, and silence is
+            // what it should get - but any new PRE-COMMIT decline must then either
+            // charge guard 4 (as `nothing_to_drop` does) or be proven unreachable in
+            // turn, because guard 4 is what bounds how long a silent decline can repeat.
+            return this.finish(args, { action: 'keep', reason: 'no_anchor' }, null, keepRecentTurns, announced);
         }
+        // COMMIT POINT B (quiet-noop §3.4). Everything below this line either spends
+        // money (`runLadder`), rewrites the history, or faults - and all three are the
+        // user's business.
+        //
+        // BEFORE `buildDigest`, NOT AFTER. A throw inside the digest renderer reaches
+        // the engine as `manager_threw`, and the engine settles the card from the
+        // verdict alone; with no card open, that fault would be invisible on every
+        // human surface. Announcing first costs one event on a path that is about to
+        // spend seconds and dollars.
+        //
+        // WHAT IT STILL DOES NOT COVER (recorded, not closed - quiet-noop §12 / IF-2).
+        // A throw in the SYNCHRONOUS region ABOVE this line - `countProtectedPrefix`,
+        // `planCompaction`, `relieveInPlace`, `buildAnchor` - also reaches the engine
+        // as `manager_threw`, and on `pressure` that fault now has no card, charges no
+        // guard (`noteNoProgress` is never reached) and does not advance `declined`
+        // (`finish` is never called) - so a host bug there would repeat at every
+        // checkpoint for a whole run in silence. `manager_timeout` cannot land there:
+        // that region holds no `await`, which is the property AC-Q12 pins. Closing it
+        // means hoisting the announcement out of this function, which is precisely
+        // what P1-1 decided against - so it is written down rather than fixed under
+        // another change's name.
+        announce(summarizer);
         const head = before.slice(protectedPrefix, plan.cutIndex);
         const priorBlock = before.slice(0, protectedPrefix).find((m) => isPriorSummaryBlock(m));
         // The prior block is carried into the DIGEST rather than the tail, so the
@@ -312,14 +406,14 @@ export class Compactor {
             ...(args.instructions ? { instructions: args.instructions } : {}),
         });
         if (ladder.kind === 'aborted') {
-            return this.finish(args, { action: 'keep', reason: 'aborted' }, null, keepRecentTurns);
+            return this.finish(args, { action: 'keep', reason: 'aborted' }, null, keepRecentTurns, announced);
         }
         if (ladder.kind === 'failed' && config.onFailure === 'stop') {
             // Rung 4. The run proceeds and will probably hit `context_overflow`, which
             // is what the user asked for by setting this.
             this.deps.notify('error', `Context compaction failed (${ladder.reason}) and compaction.onFailure is "stop". ` +
                 'The next request may exceed the context window. Try /compact again, or /clear, or /reset.');
-            return this.finish(args, { action: 'keep', reason: `summarize_failed: ${ladder.reason}` }, null, keepRecentTurns);
+            return this.finish(args, { action: 'keep', reason: `summarize_failed: ${ladder.reason}` }, null, keepRecentTurns, announced);
         }
         const truncated = ladder.kind === 'failed';
         const mode = truncated ? 'truncated' : 'summarized';
@@ -365,7 +459,7 @@ export class Compactor {
             messages,
             ...(truncated ? {} : { summary: ladder.text }),
             ...(truncated ? { reason: `truncated: ${ladder.reason}` } : {}),
-        }, { droppedMessages: plan.droppedMessages, summary: truncated ? undefined : ladder.text }, keepRecentTurns);
+        }, { droppedMessages: plan.droppedMessages, summary: truncated ? undefined : ladder.text }, keepRecentTurns, announced);
     }
     /** Tail relief against this session's window (hardening §3.3.3 / W2). */
     relieveInPlace(messages, from, systemPrompt) {
@@ -474,12 +568,17 @@ export class Compactor {
     checkProgress(ctx, uiTrigger, after) {
         const config = this.deps.getConfig().compaction;
         const info = this.modelInfo();
+        // THE OFFSET NOW LIVES ON THE METER (W1), and it is read from the last
+        // PUBLISHED pressure rather than re-derived: `Pressure.estimateOffset` is
+        // carried on every measurement, so this is the same number the field used to
+        // hold, without the compactor owning a second copy of it.
+        const estimateOffset = this.meter().lastPublished()?.estimateOffset;
         const projected = computePressure({
             messages: after,
             systemPrompt: ctx.systemPrompt,
             contextWindow: info.contextWindow,
             windowKnown: true,
-            ...(this.estimateOffset !== undefined ? { estimateOffset: this.estimateOffset } : {}),
+            ...(estimateOffset !== undefined ? { estimateOffset } : {}),
         });
         const target = config.threshold - COMPACTION_LIMITS.minReclaimRatio;
         const madeProgress = projected.ratio < target;
@@ -522,19 +621,59 @@ export class Compactor {
             `${this.deps.getConfig().compaction.keepRecentTurns} turns alone exceed the threshold. ` +
             'Lower compaction.keepRecentTurns, or use /clear or /reset.');
     }
-    finish(args, outcome, applied, keepRecentTurnsUsed) {
+    finish(args, outcome, applied, keepRecentTurnsUsed, announced) {
         const before = args.ctx.messages.length;
         const after = outcome.action === 'replace' ? outcome.messages.length : before;
-        const tokensBefore = this.lastPressure?.occupied ?? 0;
+        // THE OCCUPANCY BEFORE THE SPLICE (I-10). `lastMeasured()` is the pure cache
+        // read on purpose; anything that re-measures here reports 0 reclaimed.
+        const tokensBefore = this.lastMeasured()?.occupied ?? 0;
+        // `'relieved'` IS A CLI-ONLY WORD (RV-5 / DH-20). The port reports
+        // `'truncated'` for a relief-only compaction, which is accurate for the
+        // engine's narrower question; the card's `summarized N messages with
+        // <model>` line would otherwise render "summarized 0 messages with
+        // claude-haiku-4-5" for a compaction in which no model was called.
+        const mode = reliefOnly(outcome)
+            ? 'relieved'
+            : outcome.action === 'replace'
+                ? outcome.mode
+                : 'none';
+        // NO MODEL ON A RELIEF-ONLY RECORD, because no model was called. The card
+        // names the summarizer from this field, and naming one here would be the
+        // same claim `mode: 'relieved'` exists to stop making.
+        const model = reliefOnly(outcome) ? '' : args.summarizer?.ref.modelId ?? '';
+        const durationMs = Date.now() - args.started;
+        // THE ON-DISK RECORD OF EVERY ATTEMPT IS UNCHANGED (quiet-noop §9). This
+        // feature makes the TRANSCRIPT quiet, not the logs: a declined compaction is
+        // still one `compaction` line here, still one `compaction_start` /
+        // `compaction_end` pair from CORE in the JSONL sink, and still reflected in
+        // `/compact status`.
+        this.log.info('compaction', {
+            trigger: args.uiTrigger,
+            announced: announced !== null,
+            before,
+            after,
+            droppedMessages: applied?.droppedMessages ?? 0,
+            mode,
+            model,
+            durationMs,
+        });
+        // A SILENT DECLINE (quiet-noop §3.1). No card was opened, so there is nothing
+        // to settle and nothing to say IN THE TRANSCRIPT. Returning here is what makes
+        // a declined checkpoint indistinguishable from one at which `shouldCompact`
+        // said no.
+        //
+        // `declined` IS THE ONE THING THAT STILL SPEAKS (D-9). Quiet is the goal;
+        // invisible is not, and `/compact status` is a published guaranteed surface
+        // (`context-auto-compaction` §6.5). One integer here is what keeps that
+        // promise true while the card goes away.
+        if (!announced) {
+            this.declined += 1;
+            return outcome;
+        }
         const record = {
-            index: args.index,
+            index: announced.index,
             trigger: args.uiTrigger,
-            // `'relieved'` IS A CLI-ONLY WORD (RV-5 / DH-20). The port reports
-            // `'truncated'` for a relief-only compaction, which is accurate for the
-            // engine's narrower question; the card's `summarized N messages with
-            // <model>` line would otherwise render "summarized 0 messages with
-            // claude-haiku-4-5" for a compaction in which no model was called.
-            mode: reliefOnly(outcome) ? 'relieved' : outcome.action === 'replace' ? outcome.mode : 'none',
+            mode,
             // OPTIMISTIC AND CORRECTED BY THE WIRING (§3.2.1). Only the ENGINE knows
             // whether the splice passed the structural gate, and it says so on
             // `compaction_end`; the wiring rewrites this before the card settles.
@@ -546,23 +685,11 @@ export class Compactor {
             tokensBefore,
             tokensAfter: 0, // filled by the wiring from the engine's own estimator
             ...(applied?.summary ? { summary: applied.summary } : {}),
-            // NO MODEL ON A RELIEF-ONLY RECORD, because no model was called. The card
-            // names the summarizer from this field, and naming one here would be the
-            // same claim `mode: 'relieved'` exists to stop making.
-            model: reliefOnly(outcome) ? '' : args.summarizer?.ref.modelId ?? '',
-            durationMs: Date.now() - args.started,
+            model,
+            durationMs,
             ...(args.ctx.trigger === 'overflow' ? { keepRecentTurnsUsed } : {}),
             ...(args.tailRelief ? { tailRelief: args.tailRelief } : {}),
         };
-        this.log.info('compaction', {
-            trigger: args.uiTrigger,
-            before,
-            after,
-            droppedMessages: applied?.droppedMessages ?? 0,
-            mode: record.mode,
-            model: record.model,
-            durationMs: record.durationMs,
-        });
         this.deps.emit({ type: 'compaction_end', record });
         return outcome;
     }
@@ -570,32 +697,30 @@ export class Compactor {
     // Reporting helpers
     // =========================================================================
     /**
-     * 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) {
-        const info = this.modelInfo();
-        const pressure = computePressure({
-            ...(probe.lastUsage ? { lastUsage: probe.lastUsage } : {}),
-            messages: probe.messages ?? [],
-            systemPrompt: probe.systemPrompt ?? '',
-            contextWindow: info.contextWindow,
-            windowKnown: this.deps.isPricedModel({
-                providerId: this.mainRef().providerId,
-                modelId: this.mainRef().modelId,
-            }),
-            ...(this.estimateOffset !== undefined ? { estimateOffset: this.estimateOffset } : {}),
-            ...(this.measuredPrefixLength !== undefined
-                ? { measuredPrefixLength: this.measuredPrefixLength }
-                : {}),
-        });
-        this.lastPressure = pressure;
-        return pressure;
+        return this.meter().measureWith(probe.lastUsage);
     }
+    /**
+     * 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() {
-        return this.lastPressure;
+        return this.meter().lastPublished();
     }
     /** Written by the wiring once the engine has reported its verdict. */
     recordApplied(tokensBefore, tokensAfter) {
@@ -605,6 +730,7 @@ export class Compactor {
     sessionTotals() {
         return {
             compactions: this.compactions,
+            declined: this.declined,
             tokensReclaimed: this.tokensReclaimed,
             usage: this.sessionUsage,
             pricingUnknown: this.pricingUnknown,
@@ -647,6 +773,29 @@ export class Compactor {
             return null;
         return { ref, fromFastTier: false };
     }
+    /**
+     * 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.
+     */
+    meter() {
+        if (this.deps.meter)
+            return this.deps.meter;
+        if (!this.ownMeter) {
+            this.ownMeter = new ContextMeter({
+                getMessages: () => this.deps.getMessages(),
+                getSystemPrompt: () => this.deps.getSystemPrompt(),
+                getModelInfo: () => this.modelInfo(),
+                isWindowKnown: () => this.deps.isPricedModel(this.mainRef()),
+                getWindowOverride: () => this.deps.getConfig().contextWindow,
+            });
+        }
+        return this.ownMeter;
+    }
     mainRef() {
         const config = this.deps.getConfig();
         return {

package/dist/compaction/context-command.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The `/context` slash command (context-usage-gauge-accuracy §3.7 / W6).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope, and this
+ * text lands in a transcript `notice` - produced outside `src/ui/**`, where no
+ * terminal capabilities are available, so it must be safe on a legacy `cmd.exe`.
+ *
+ * IT LIVES HERE RATHER THAN IN `builtins.ts` FOR THE REASON `/compact` DOES
+ * (C-16 / P1-12): `CLAUDE.md` caps a source file at 1000 lines and `builtins.ts`
+ * is already past it. `builtins.ts` gets the registration and nothing else.
+ *
+ * THIS IS THE GUARANTEED REPORTING SURFACE FOR OCCUPANCY. The status bar drops
+ * readouts on a narrow terminal, the gauge is a bar and a rounded percentage,
+ * and neither can say WHERE the denominator came from or WHAT the session total
+ * includes. Every question a user asks after distrusting the bar is answered
+ * here, at any width, in any mode - which is also why the honesty rules below
+ * are not decoration.
+ */
+import type { CommandContext } from '../commands/registry.js';
+/**
+ * `/context` - occupancy, denominator, freshness, compaction, session spend.
+ *
+ * THE OCCUPANCY COMES FROM `controller.getContextUsage()` AND NOWHERE ELSE
+ * (RV-8). The obvious alternative, `getCompactionSnapshot().pressure`, returns
+ * `offCompactionSnapshot()`'s HARDCODED ZERO pressure whenever compaction was
+ * never registered - so a report built on it would read `0%` for exactly the
+ * sessions this whole feature exists to fix. `/compact status` gets away with
+ * reading it only because it returns early on that branch and never prints an
+ * occupancy line at all.
+ */
+export declare function formatContextReport(ctx: CommandContext): string;
+/** `/context` takes no arguments; anything after it is ignored. */
+export declare function runContextCommand(ctx: CommandContext): void;