@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/compaction/meter.js

@@ -0,0 +1,428 @@
+/**
+ * `ContextMeter` - the ONE owner of "how full is the context right now"
+ * (context-usage-gauge-accuracy §3.2 / W1).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`). If this module is ever moved to a new tree, the
+ * scanner's hardcoded directory list must be widened IN THE SAME COMMIT - a
+ * scanner that silently stops scanning is worse than no scanner, and this
+ * package has paid for that edit eleven times (I-7).
+ *
+ * IT LIVES HERE BUT IT IS NOT PART OF COMPACTION, and that is deliberate. The
+ * whole point of this class is that occupancy is measurable when compaction is
+ * OFF: `AgentController` builds a `CompactionWiring` only when
+ * `compaction.enabled` is true, so a measurement owned by the compactor is
+ * unreachable for exactly the sessions that most need a working gauge. It sits
+ * in this directory because `pressure.ts` - the arithmetic it drives - already
+ * does, and because moving it would cost a scanner edit for no gain (R-10).
+ *
+ * THE STATE MACHINE IN ONE PARAGRAPH. Every mutation of the history marks the
+ * meter DIRTY; every read that finds it dirty re-measures SYNCHRONOUSLY. That
+ * ordering is what removes the subscription-order dependency in the APPEND
+ * direction: it does not matter whether this class or the compaction wiring
+ * hears `tool_execution_end` first, because whoever reads gets a number that
+ * includes the appended message either way (I-2). It does NOT remove the
+ * dependency in the REPLACE direction - a splice does not announce itself to a
+ * listener that has not run yet - which is why the splice marks this dirty from
+ * `CompactionWiring.settlePending`'s own synchronous code (I-9), and why
+ * `current()` carries a structural belt for a missed invalidation site.
+ */
+import { computeEstimateOffset, computePressure } from './pressure.js';
+/**
+ * How long a scheduled publish waits.
+ *
+ * IT MUST BE A DELAY, NOT ZERO, AND NOT A SYNCHRONOUS MEASUREMENT (I-3). The
+ * loop emits `tool_execution_end` BEFORE it pushes the `tool_result` message, so
+ * anything that measures inside that event measures a history missing the single
+ * largest message of the turn - silently, and every turn. A `setTimeout` is
+ * necessarily later than that synchronous push.
+ *
+ * 400 ms also caps the publish rate at 2.5 Hz, which together with the reducer's
+ * identity short-circuit keeps a permanently visible row from becoming a
+ * re-render source (R-3).
+ */
+export const CONTEXT_METER_TICK_MS = 400;
+/**
+ * The projection `ViewState` and `/context` read (§4.1).
+ *
+ * THE ONLY CONVERTER between `Pressure` and `ContextUsageSnapshot`. Two of them
+ * would eventually round the percentage differently, and "the status bar says 43
+ * and `/context` says 44" is the exact class of disagreement this whole feature
+ * exists to remove.
+ */
+export function toContextUsage(p) {
+    return {
+        occupied: p.occupied,
+        window: p.contextWindow,
+        // FROM `ratio`, NOT FROM A SECOND DIVISION. `computePressure` already
+        // clamped it to [0, 1] and already decided what a zero window means.
+        pct: Math.max(0, Math.min(100, Math.round(p.ratio * 100))),
+        source: p.source,
+        deltaTokens: p.deltaTokens,
+        windowKnown: p.windowKnown,
+        windowOverridden: p.windowOverridden,
+    };
+}
+/** The reading a meter with nothing measured yet reports. */
+export function emptyContextUsage() {
+    return {
+        occupied: 0,
+        window: 0,
+        pct: 0,
+        source: 'estimate',
+        deltaTokens: 0,
+        windowKnown: false,
+        windowOverridden: false,
+    };
+}
+export class ContextMeter {
+    deps;
+    listeners = new Set();
+    unsubscribe = null;
+    timer = null;
+    disposed = false;
+    /**
+     * The authoritative usage of the last completed turn.
+     *
+     * Its presence is what selects `computePressure`'s MEASURED branch, so
+     * dropping it is how every reset degrades to an estimate rather than to a
+     * number describing a history that no longer exists.
+     */
+    lastUsage;
+    /**
+     * The systematic difference between what `estimatePromptTokens` counts and
+     * what the provider bills (D-23) - chiefly the tool schemas.
+     *
+     * SURVIVES A SPLICE AND NOT A SESSION CHANGE (I-8). See `onHistorySpliced`.
+     */
+    estimateOffset;
+    /** `messages.length` at the `turn_end` that produced `lastUsage`. */
+    measuredPrefixLength;
+    /** The last pressure PUBLISHED. Never re-derived on read - see `lastPublished`. */
+    last = null;
+    /** Whether the history has changed since the last measurement. */
+    dirty = true;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    // =========================================================================
+    // Reading
+    // =========================================================================
+    /**
+     * Occupancy right now. FOR THE SCREEN.
+     *
+     * Re-measures synchronously when dirty (I-2), and publishes when it does - the
+     * gauge has to fall in the SAME FRAME as the compaction that caused it (AC-1),
+     * and the caller that triggers this re-measurement is `CompactionWiring`'s own
+     * synchronous `snapshot()` inside `settlePending`. Leaving the publish to the
+     * scheduled tick instead would be worse than slow: the tick fires only when
+     * `dirty`, and this call is what clears it.
+     *
+     * NEVER THROWS. A meter that can throw is a status bar that can take the
+     * process down.
+     */
+    current() {
+        // THE BELT (I-9), AND IT RUNS EVEN WHEN NOT DIRTY. The case it exists for is
+        // a splice that NOBODY announced, and in that case a missing `dirty` flag is
+        // precisely the symptom. `estimateAppendedTokens` bounds-checks too, but it
+        // only zeroes the DELTA and keeps the wrong measured base, so that belt does
+        // not cover this.
+        if (this.discardStalePrefix())
+            this.dirty = true;
+        if (!this.dirty && this.last)
+            return this.last;
+        return this.measureAndPublish(this.lastUsage);
+    }
+    /**
+     * The last pressure this meter PUBLISHED. FOR THE BOOKS. Never re-measures.
+     *
+     * `Compactor.lastMeasured()` forwards here and not to `current()`, and the
+     * distinction is load-bearing (I-10): `compactor.ts`'s `tokensBefore` is the
+     * sole upstream of `tokensReclaimed`, the card's "reclaimed N tokens" line and
+     * `/compact status`'s session total. It wants the occupancy BEFORE the splice.
+     * Wired to `current()` it would re-measure the already-spliced history, report
+     * `reclaimed 0`, and render that number without a single log line about it.
+     */
+    lastPublished() {
+        return this.last;
+    }
+    /** The published projection, or a zeroed one before the first measurement. */
+    currentUsage() {
+        return toContextUsage(this.current());
+    }
+    // =========================================================================
+    // Writing
+    // =========================================================================
+    /**
+     * Measure with the caller's own authoritative usage. FOR A DECISION POINT.
+     *
+     * `Compactor.shouldCompact` has a `CompactionProbe.lastUsage` the meter may
+     * not have seen yet, so it supplies it rather than trusting the field here.
+     */
+    measureWith(lastUsage) {
+        if (this.discardStalePrefix())
+            this.dirty = true;
+        return this.measureAndPublish(lastUsage);
+    }
+    /**
+     * `turn_end` - the one moment in the whole flow that is FULLY measured.
+     *
+     * The loop emits it BEFORE pushing the assistant message, so the history right
+     * now is exactly the history the reported `usage` was billed for: the offset
+     * and the prefix length describe the same array by construction, and
+     * `deltaTokens` is 0. Published immediately for that reason - there is no
+     * better number to wait for.
+     */
+    onTurnEnd(usage) {
+        const messages = this.deps.getMessages();
+        const systemPrompt = this.readSystemPrompt();
+        this.lastUsage = usage;
+        this.estimateOffset = computeEstimateOffset(usage, messages, systemPrompt);
+        this.measuredPrefixLength = messages.length;
+        this.measureAndPublish(usage);
+    }
+    /**
+     * A compaction spliced the history (I-8, the SHALLOW reset).
+     *
+     * `estimateOffset` IS KEPT, and that is the whole reason this method is not
+     * `onHistoryReplaced`. The offset describes "what this toolset costs on this
+     * model above what the estimator counts"; a splice changes neither the toolset
+     * nor the model, so it is still valid - and it is the only calibration the
+     * estimate branch has until the next `turn_end`. Dropping it makes the gauge
+     * fall several thousand tokens too far and then visibly climb back on the next
+     * turn, for no reason the user can see (I-5).
+     *
+     * IDEMPOTENT. Both `settlePending` (the authority, I-9) and this meter's own
+     * `compaction_end` handler reach it, and the second one must cost nothing.
+     */
+    onHistorySpliced() {
+        this.lastUsage = undefined;
+        this.measuredPrefixLength = undefined;
+        if (this.dirty)
+            return;
+        this.dirty = true;
+        this.scheduleTick();
+    }
+    /**
+     * The history came from somewhere else entirely (I-8, the DEEP reset):
+     * `/clear`, `/reset`, `/resume`.
+     *
+     * `estimateOffset` GOES TOO, unlike the shallow reset above. `/resume` can
+     * change the model in the same breath (`builtins.ts`'s restore path does), and
+     * an offset carried across that is a calibration constant applied to something
+     * it never calibrated. The first reading afterwards is therefore a bare
+     * estimate - biased LOW, and corrected by the very next `turn_end`. Biased low
+     * and self-correcting beats biased high and permanent.
+     */
+    onHistoryReplaced() {
+        this.lastUsage = undefined;
+        this.measuredPrefixLength = undefined;
+        this.estimateOffset = undefined;
+        this.dirty = true;
+        this.scheduleTick();
+    }
+    /**
+     * Only the DENOMINATOR moved (`/model`, a `contextWindow` edit).
+     *
+     * DELIBERATELY NOT A RESET. The measured base is still a true statement about
+     * the history, so throwing it away would trade a correct numerator for a whole
+     * history estimate and produce a visible jump on a common operation. The
+     * numerator's calibration is one turn stale until the next `turn_end`
+     * refreshes it, which is the trade this method names (RV-13).
+     */
+    onWindowChanged() {
+        this.dirty = true;
+        this.measureAndPublish(this.lastUsage);
+    }
+    /**
+     * Something was appended. Mark dirty, arrange a throttled publish, MEASURE
+     * NOTHING (I-3).
+     */
+    scheduleTick() {
+        this.dirty = true;
+        // NO SUBSCRIBERS, NO TIMER (I-11). `AgentController` is shared with
+        // `aragon exec`, where nothing reads this number; a headless run must not
+        // pay a timer per tool call, and a pending tick must never be able to hold
+        // the process open for an extra 400 ms. `current()` is unaffected - it
+        // measures on demand, so `wiring.snapshot()` and `/context` still work in a
+        // host with no UI.
+        if (this.listeners.size === 0)
+            return;
+        if (this.timer !== null || this.disposed)
+            return;
+        const handle = setTimeout(() => {
+            this.timer = null;
+            if (!this.dirty || this.disposed)
+                return;
+            this.measureAndPublish(this.lastUsage);
+        }, CONTEXT_METER_TICK_MS);
+        // The other half of I-11: an armed tick must not keep the event loop alive.
+        const unrefable = handle;
+        if (typeof unrefable.unref === 'function')
+            unrefable.unref();
+        this.timer = handle;
+    }
+    // =========================================================================
+    // Plumbing
+    // =========================================================================
+    /** Publish to this meter's own subscribers. Returns an unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Subscribe to the lead agent's stream. IDEMPOTENT.
+     *
+     * THIS TABLE IS NOT THE SOURCE OF COMPACTION CORRECTNESS (I-9). The splice is
+     * marked dirty by `CompactionWiring.settlePending` inside its own synchronous
+     * code, BEFORE it emits either event, so a reader is correct regardless of
+     * which listener the emitter reaches first. The `compaction_end` row below is
+     * a second, idempotent path that serves the manual `/compact` route and any
+     * future splicer.
+     */
+    attach(subscribe) {
+        if (this.unsubscribe)
+            return;
+        this.unsubscribe = subscribe((event) => this.onAgentEvent(event));
+    }
+    dispose() {
+        this.disposed = true;
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.listeners.clear();
+    }
+    // =========================================================================
+    // Internals
+    // =========================================================================
+    onAgentEvent(event) {
+        switch (event.type) {
+            case 'turn_end':
+                this.onTurnEnd(event.usage);
+                return;
+            case 'tool_execution_end':
+                // DELAYED, NEVER SYNCHRONOUS. See `CONTEXT_METER_TICK_MS` (I-3).
+                this.scheduleTick();
+                return;
+            case 'compaction_end':
+                // The engine's verdict. `applied` means the history really was replaced.
+                if (event.applied)
+                    this.onHistorySpliced();
+                else
+                    this.scheduleTick();
+                return;
+            case 'agent_end':
+                this.scheduleTick();
+                return;
+            default:
+                // `message_update` is a STREAM event and is deliberately ignored (N-2):
+                // the output tokens of an in-flight reply are not knowable until `done`,
+                // and guessing them would add a third approximation to a number that
+                // already carries two.
+                return;
+        }
+    }
+    /**
+     * The structural belt for a missed invalidation site (I-9).
+     *
+     * A recorded prefix that is LONGER than the history it indexes describes an
+     * array that no longer exists. Rather than merely zeroing the delta - which is
+     * what `estimateAppendedTokens` does, keeping the wrong measured base - this
+     * drops the base too and forces the estimate branch.
+     *
+     * THE COMPARISON IS STRICT, AND THAT BOUNDARY IS LOAD-BEARING (IF-1). The
+     * design document wrote `length <= measuredPrefixLength`, which is off by one:
+     * `turn_end` is emitted BEFORE the assistant message is pushed, so the instant
+     * `onTurnEnd` records the prefix the history is EXACTLY that long. An
+     * inclusive test therefore discards a measurement one statement after taking
+     * it - but only when this meter's listener runs before the compaction wiring's,
+     * because the wiring's `snapshot()` is what reads in that window. That is a
+     * silent, subscription-order-dependent fallback to the estimate branch on
+     * every single turn, which is the exact class of bug this feature exists to
+     * remove. A measurement taken at length N describes every history of length
+     * >= N; only a SHORTER one is impossible.
+     *
+     * Returns whether anything was discarded.
+     */
+    discardStalePrefix() {
+        if (this.measuredPrefixLength === undefined)
+            return false;
+        const length = this.deps.getMessages().length;
+        if (length >= this.measuredPrefixLength)
+            return false;
+        this.lastUsage = undefined;
+        this.measuredPrefixLength = undefined;
+        return true;
+    }
+    /**
+     * Measure, cache, clear the dirty flag, publish. The ONE write path.
+     *
+     * Every public mutator funnels through here so "what was published" and "what
+     * is cached" cannot drift, which is what makes `lastPublished()` a meaningful
+     * answer rather than a stale one.
+     */
+    measureAndPublish(lastUsage) {
+        const pressure = this.compute(lastUsage);
+        this.last = pressure;
+        this.dirty = false;
+        this.publish(pressure);
+        return pressure;
+    }
+    compute(lastUsage) {
+        const window = this.resolveWindow();
+        return computePressure({
+            ...(lastUsage ? { lastUsage } : {}),
+            messages: this.deps.getMessages(),
+            systemPrompt: this.readSystemPrompt(),
+            contextWindow: window.contextWindow,
+            windowKnown: window.windowKnown,
+            windowOverridden: window.windowOverridden,
+            ...(this.estimateOffset !== undefined ? { estimateOffset: this.estimateOffset } : {}),
+            ...(this.measuredPrefixLength !== undefined
+                ? { measuredPrefixLength: this.measuredPrefixLength }
+                : {}),
+        });
+    }
+    /**
+     * Where the denominator comes from, and whether it can be trusted.
+     *
+     * AN OVERRIDE MAKES THE WINDOW KNOWN (I-6): the user asserted it, so the `~`
+     * that means "this denominator is a guess" has no business staying on the
+     * percentage. `windowOverridden` travels separately so `/context` can still
+     * name the source - a hand-typed window that is wrong is exactly the case that
+     * most needs to be visible.
+     */
+    resolveWindow() {
+        const override = this.deps.getWindowOverride();
+        if (override !== null && Number.isFinite(override) && override > 0) {
+            return { contextWindow: override, windowKnown: true, windowOverridden: true };
+        }
+        return {
+            contextWindow: this.deps.getModelInfo().contextWindow,
+            windowKnown: this.deps.isWindowKnown(),
+            windowOverridden: false,
+        };
+    }
+    readSystemPrompt() {
+        return this.deps.getSystemPrompt();
+    }
+    publish(pressure) {
+        if (this.listeners.size === 0)
+            return;
+        const usage = toContextUsage(pressure);
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(usage);
+            }
+            catch {
+                // One bad subscriber must not take the run down with it - the rule
+                // `CompactionWiring.emit` and `TeamRuntime.emit` both already state.
+            }
+        }
+    }
+}

package/dist/compaction/pressure.d.ts

@@ -57,6 +57,12 @@ export interface PressureInput {
     contextWindow: number;
     /** False when the window is `buildRuntimeModel`'s 128k placeholder. */
     windowKnown: boolean;
+    /**
+     * Whether `contextWindow` came from the user's `contextWindow` override
+     * (context-usage-gauge-accuracy I-6). Defaults to `false`, so every existing
+     * construction site is unchanged and the arithmetic below is untouched.
+     */
+    windowOverridden?: boolean;
     /** Carried from the last `turn_end`; applied to every ESTIMATED figure. */
     estimateOffset?: number;
     /**

package/dist/compaction/pressure.js

@@ -138,6 +138,10 @@ export function computePressure(input) {
         headroom: Math.max(0, window - occupied),
         source,
         windowKnown: input.windowKnown,
+        // PURE PASS-THROUGH. This function's arithmetic is unchanged by
+        // context-usage-gauge-accuracy; the flag only travels with the number so
+        // `/context` can name the denominator's source (I-6).
+        windowOverridden: input.windowOverridden ?? false,
         ...(input.estimateOffset !== undefined ? { estimateOffset: input.estimateOffset } : {}),
         deltaTokens,
     };

package/dist/compaction/types.d.ts

@@ -60,6 +60,18 @@ export interface Pressure {
     source: PressureSource;
     /** False when the window came from `buildRuntimeModel`'s 128k placeholder. */
     windowKnown: boolean;
+    /**
+     * Whether the denominator came from the user's `contextWindow` override
+     * (context-usage-gauge-accuracy I-6).
+     *
+     * SEPARATE FROM `windowKnown` RATHER THAN FOLDED INTO IT. An override makes
+     * the window KNOWN - the user asserted it, so the `~` has no business staying
+     * on the percentage - but `/context` still has to be able to say WHO supplied
+     * the number. Collapsing the two into one boolean makes "found in the model
+     * table" and "typed by hand" indistinguishable in the report, and the second
+     * one being wrong is exactly the case that most needs to be visible.
+     */
+    windowOverridden: boolean;
     /**
      * `occupiedTokens(lastUsage) - estimateOf(the history that produced it)`,
      * clamped to `>= 0`, or `undefined` before the first `turn_end`.
@@ -89,6 +101,35 @@ export interface Pressure {
      */
     deltaTokens: number;
 }
+/**
+ * The ONE occupancy projection the status bar and `/context` read
+ * (context-usage-gauge-accuracy §4.1).
+ *
+ * DELIBERATELY CARRIES NO TIMESTAMP. Its only consumer is the reducer's identity
+ * short-circuit (§5.2), and a field that changes on every tick would make that
+ * short-circuit never hold - turning a permanently visible row into a 2.5 Hz
+ * re-render source and pushing the render governor up its ladder for nothing.
+ *
+ * `Pressure` is the compaction subsystem's shape and carries a headroom and a
+ * ratio the UI does not want; this is the projection of it that crosses into
+ * view state, and `toContextUsage` in `meter.ts` is the ONLY converter.
+ */
+export interface ContextUsageSnapshot {
+    /** Occupied tokens (measured, plus an estimate of anything appended since). */
+    occupied: number;
+    /** The denominator actually used. */
+    window: number;
+    /** `occupied / window` as a percentage, clamped to [0, 100] and rounded. */
+    pct: number;
+    /** Where the BASE came from. */
+    source: PressureSource;
+    /** How much of `occupied` is an estimate of appended messages; `> 0` means approximate. */
+    deltaTokens: number;
+    /** Whether the denominator is trustworthy (in the model table, or overridden). */
+    windowKnown: boolean;
+    /** Whether the denominator came from the user's `contextWindow` (I-6). */
+    windowOverridden: boolean;
+}
 /** One compaction, in whatever state it reached. Rendered by `CompactionCard`. */
 export interface CompactionRecord {
     /** 1-based within the session, so the card can name itself. */
@@ -143,7 +184,26 @@ export interface CompactionSnapshot {
     live: boolean;
     /** The summarizer's model id, or `''`. */
     model: string;
+    /**
+     * How many compactions ANNOUNCED themselves (quiet-noop §6.2 / D-5).
+     *
+     * COMPACTIONS THAT RAN, NOT CHECKPOINTS THAT FIRED. A `pressure` compaction
+     * that declines before calling a model or changing the history never advances
+     * this, which is what keeps the card's `#N` contiguous. `declined` below is
+     * the other half of the same total.
+     */
     compactions: number;
+    /**
+     * How many `pressure` checkpoints declined BEFORE committing to any work
+     * (quiet-noop D-9 / P1-2).
+     *
+     * OPTIONAL SO EVERY EXISTING CONSTRUCTION SITE STAYS UNTOUCHED, and rendered
+     * by `/compact status` only when non-zero — a healthy session must not read
+     * `(0 checkpoints declined)`. This is the one human surface that still speaks
+     * about a decline after the transcript went quiet, which is what keeps
+     * `context-auto-compaction` §6.5's "guaranteed reporting surface" promise true.
+     */
+    declined?: number;
     /** Sum of `(tokensBefore - tokensAfter)` over applied compactions. */
     tokensReclaimed: number;
     /** What compaction itself has spent this session. */
@@ -161,6 +221,23 @@ export interface CompactionSnapshot {
     generation: number;
     pressure: Pressure;
 }
+/**
+ * THE COMPACTION EVENT STREAM.
+ *
+ * `compaction_start` and `compaction_end` are emitted ONLY for compactions that
+ * COMMITTED TO WORK (quiet-noop §3.1): a `pressure` compaction that declines
+ * before calling a model or changing the history emits NEITHER, and is
+ * deliberately indistinguishable from a turn at which `shouldCompact` returned
+ * false. `manual` and `overflow` always emit both.
+ *
+ * The pair is still BALANCED: every `compaction_start` is followed by exactly
+ * one `compaction_end` (a `finally` in the engine guarantees the verdict, and
+ * `settlePending` synthesizes a skeleton record when the compactor's own has not
+ * arrived). Consumers that count PAIRS are unaffected; consumers that counted
+ * ATTEMPTS must read `/compact status` or the JSONL diagnostic log instead -
+ * CORE's own `compaction_start` / `compaction_end` pair still fires for every
+ * attempt, declined or not, and that is the stream the log subscribes to.
+ */
 export type CompactionEvent = {
     type: 'compaction_start';
     index: number;

package/dist/compaction/wiring.d.ts

@@ -25,11 +25,21 @@
  * methods delegate to a compactor that reads config LIVE - which is what lets
  * `/compact off`, `/compact threshold 0.8` and a settings-screen save take effect
  * mid-session without touching the `Agent`.
+ *
+ * DECLINED COMPACTIONS PRODUCE NO CLI EVENTS (quiet-noop §3.6). A `pressure`
+ * compaction that changed nothing, called nothing and spent nothing never emits
+ * `compaction_start`, so `onCompactorEvent` never opens a card and `settlePending`
+ * finds neither a held record nor a skeleton to synthesize. CORE still emits its
+ * own pair for every attempt, which is why `settlePending` still runs - it just
+ * refreshes the snapshot and returns. `onCompactorEvent`'s `if (!this.open)`
+ * guard is now unreachable for declines and stays for the abort race it was
+ * written for.
  */
 import { type AgentEvent, type ContextManager, type Message, type ModelInfo, type ModelRef, type ProviderRegistry, type ProviderRegistryOptions, type TokenUsage } from '@aragon-agent/core';
 import type { CliConfig } from '../config/schema.js';
 import type { NoticeLevel } from '../agent/reducer.js';
 import { type ChildContextManagerFactory } from './child.js';
+import { ContextMeter } from './meter.js';
 import type { CompactionEventListener, CompactionSnapshot } from './types.js';
 export interface CompactionWiringDeps {
     /** Read LIVE on every call - the controller replaces the object on mutation. */
@@ -45,6 +55,17 @@ export interface CompactionWiringDeps {
     getMessages: () => readonly Message[];
     getSystemPrompt: () => string;
     notify: (level: NoticeLevel, text: string) => void;
+    /**
+     * The controller's `ContextMeter`, forwarded to the compactor
+     * (context-usage-gauge-accuracy W1).
+     *
+     * OPTIONAL SO EVERY EXISTING CONSTRUCTION SITE COMPILES (R-1); production
+     * always injects, and `AgentController` owns the instance because it builds
+     * one UNCONDITIONALLY while this class only exists when `compaction.enabled`
+     * is true. That asymmetry is the whole point: occupancy has to be measurable
+     * in a session that turned compaction off.
+     */
+    meter?: ContextMeter;
     /**
      * How the summarizer's own registry is built. Defaults to `initProviders`.
      *
@@ -71,6 +92,8 @@ export declare class CompactionWiring {
     private readonly log;
     private readonly listeners;
     private readonly compactor;
+    /** The occupancy meter, injected or private (R-1). Forwarded to the compactor. */
+    private readonly meter;
     /** The compactor's OWN transport (D-10). Lazy - see `getRegistry()`. */
     private registry;
     private unsubscribe;
@@ -143,6 +166,20 @@ export declare class CompactionWiring {
      * `/clear`, `/resume`, and any future host-side rewrite. A recorded prefix
      * length indexes an array that no longer exists, so the delta must be
      * abandoned rather than applied to a different history.
+     *
+     * THE **DEEP** RESET (I-8). `/resume` can change the model in the same breath,
+     * so `estimateOffset` - a calibration for one toolset on one model - goes too.
+     * The SHALLOW reset is `settlePending`'s splice branch, and the two are not
+     * interchangeable: swapping them produces silent errors in OPPOSITE
+     * directions (a splice that drops the offset reads too low and climbs back; a
+     * resume that keeps it reads too high and never self-corrects).
+     *
+     * DUPLICATED BY `AgentController` ON PURPOSE. The controller calls
+     * `contextMeter.onHistoryReplaced()` directly at the same two sites, because
+     * this class does not exist at all when `compaction.enabled` is false - and
+     * that unconditional call is the only thing that keeps `/resume` re-measuring
+     * for such a session. A deep reset is idempotent, so both firing costs
+     * nothing; deleting the controller's copy "to de-duplicate" reintroduces P0-2.
      */
     onHistoryReplaced(): void;
     /**
@@ -192,6 +229,17 @@ export declare class CompactionWiring {
         ok: false;
         reason: string;
     }>;
+    /**
+     * The status a reader gets right now.
+     *
+     * IT READS `meter.current()`, WHICH RE-MEASURES WHEN DIRTY - and that is the
+     * fix for P0-1 (§3.3). This method is called one statement after
+     * `settlePending` marks the meter spliced, so the `snapshot` event emitted
+     * immediately after `compaction_end` carries the POST-compaction occupancy.
+     * The old body preferred `compactor.lastMeasured()`, i.e. the measurement that
+     * TRIGGERED this compaction, so the gauge fell and was bounced straight back
+     * to the pre-compaction figure inside the same synchronous emit loop.
+     */
     snapshot(): CompactionSnapshot;
     /**
      * `snapshot()` with the pressure argument substituted for the re-measurement.
@@ -205,6 +253,14 @@ export declare class CompactionWiring {
     /** The summarizer that would be used right now, for `/compact status`. */
     summarizerRef(): ModelRef | null;
     subscribe(listener: CompactionEventListener): () => void;
+    /**
+     * The main model, for the FALLBACK meter's deps only (R-1).
+     *
+     * Production injects a meter built by `AgentController`, which resolves the
+     * same ref from the same live config; this exists so a test that constructs a
+     * bare wiring still gets a working denominator.
+     */
+    private mainRef;
     /**
      * The transport one summarization call goes through - separate from the lead's,
      * and fail-fast (D-10).