@aragon-agent/cli 0.6.4 → 0.6.8

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. */

package/dist/compaction/wiring.d.ts

@@ -39,6 +39,7 @@ import { type AgentEvent, type ContextManager, type Message, type ModelInfo, typ
 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. */
@@ -54,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`.
      *
@@ -80,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;
@@ -152,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;
     /**
@@ -201,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.
@@ -214,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).

package/dist/compaction/wiring.js

@@ -40,6 +40,7 @@ import { getLogger } from '../logging/logger.js';
 import { mintRunId, writeArchive } from './archive.js';
 import { createChildContextManager } from './child.js';
 import { Compactor } from './compactor.js';
+import { ContextMeter } from './meter.js';
 /**
  * One retry, not ten and not zero - the `fast/wiring.ts` argument unchanged
  * (D-10).
@@ -68,6 +69,7 @@ export function offCompactionSnapshot() {
             headroom: 0,
             source: 'estimate',
             windowKnown: false,
+            windowOverridden: false,
             deltaTokens: 0,
         },
     };
@@ -77,6 +79,8 @@ export class CompactionWiring {
     log = getLogger().child('compaction');
     listeners = new Set();
     compactor;
+    /** The occupancy meter, injected or private (R-1). Forwarded to the compactor. */
+    meter;
     /** The compactor's OWN transport (D-10). Lazy - see `getRegistry()`. */
     registry = null;
     unsubscribe = null;
@@ -125,6 +129,15 @@ export class CompactionWiring {
     constructor(deps) {
         this.deps = deps;
         this.enabled = deps.getConfig().compaction.enabled;
+        this.meter =
+            deps.meter ??
+                new ContextMeter({
+                    getMessages: deps.getMessages,
+                    getSystemPrompt: deps.getSystemPrompt,
+                    getModelInfo: () => deps.getModelInfoFor(this.mainRef()),
+                    isWindowKnown: () => deps.isPricedModel(this.mainRef()),
+                    getWindowOverride: () => deps.getConfig().contextWindow,
+                });
         this.compactor = new Compactor({
             getConfig: deps.getConfig,
             hasKey: deps.hasKey,
@@ -139,6 +152,9 @@ export class CompactionWiring {
             complete: (providerId, request) => this.getRegistry().complete(providerId, request),
             emit: (event) => this.onCompactorEvent(event),
             notify: deps.notify,
+            // ONE METER PER PROCESS. The compactor must not build its own fallback
+            // here, or the trigger would read a different number from the gauge.
+            meter: this.meter,
             // ONE NUMBER ON SCREEN AND IN THE TRIGGER (R-11 / DH-15). The checkpoint
             // has already measured; publishing THAT pressure rather than re-measuring
             // is what keeps the two from disagreeing by one turn's tool results.
@@ -205,9 +221,23 @@ export 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() {
-        this.compactor.invalidateMeasurement();
+        this.meter.onHistoryReplaced();
     }
     /**
      * The per-child manager factory, or `null` when children get none
@@ -314,13 +344,19 @@ export class CompactionWiring {
     // -----------------------------------------------------------------------
     // Status and events
     // -----------------------------------------------------------------------
+    /**
+     * 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() {
-        const pressure = this.compactor.lastMeasured() ??
-            this.compactor.measure({
-                messages: this.deps.getMessages(),
-                systemPrompt: this.deps.getSystemPrompt(),
-            });
-        return this.snapshotWith(pressure);
+        return this.snapshotWith(this.meter.current());
     }
     /**
      * `snapshot()` with the pressure argument substituted for the re-measurement.
@@ -362,6 +398,17 @@ export class CompactionWiring {
     // -----------------------------------------------------------------------
     // Internals
     // -----------------------------------------------------------------------
+    /**
+     * 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.
+     */
+    mainRef() {
+        const config = this.deps.getConfig();
+        return { providerId: config.provider, modelId: config.model };
+    }
     /**
      * The transport one summarization call goes through - separate from the lead's,
      * and fail-fast (D-10).
@@ -408,19 +455,16 @@ export class CompactionWiring {
             return;
         }
         if (event.type === 'turn_end') {
-            // The calibration offset, re-measured every turn (D-23). Read the history
-            // AFTER the turn's assistant message is pushed? No: `turn_end` is emitted
-            // BEFORE the push, so this is exactly the history the reported `usage`
-            // was measured against, which is what makes the difference meaningful.
-            this.compactor.onTurnEnd(event.usage, this.deps.getMessages(), this.deps.getSystemPrompt());
-            // The gauge and the trigger read one function (R-11 / AC-3), so the
-            // snapshot's pressure is refreshed from the same measurement the status bar
-            // is about to render.
-            this.compactor.measure({
-                lastUsage: event.usage,
-                messages: this.deps.getMessages(),
-                systemPrompt: this.deps.getSystemPrompt(),
-            });
+            // THE MEASUREMENT IS THE METER'S (context-usage-gauge-accuracy §3.3.4). It
+            // subscribes to `turn_end` on the same stream and recomputes the offset,
+            // the prefix length and the pressure there; the two calls that used to
+            // live here - `compactor.onTurnEnd(...)` and `compactor.measure(...)` -
+            // were both forwarders to it and doing the same work twice.
+            //
+            // THE SNAPSHOT EMIT STAYS. The other fields on it - `inFlight`, the
+            // session counts, the summarizer - are this class's own and still need
+            // refreshing on a turn boundary, and `snapshot()` picks up the meter's
+            // freshly published pressure for free.
             this.emit({ type: 'snapshot', snapshot: this.snapshot() });
             return;
         }
@@ -462,9 +506,13 @@ export class CompactionWiring {
             // A SILENT DECLINE (quiet-noop §3.6). No card - but the gauge and the chip
             // are still refreshed: `inFlight` has just gone false and `/compact status`
             // reads this same snapshot, which is where the `declined` count surfaces.
-            // `snapshot()` uses the CACHED pressure (`compactor.lastMeasured()`), so
-            // this costs no re-measurement, and guard 4 caps the number of declines per
-            // session at `stuckLimit`.
+            //
+            // `snapshot()` NOW GOES THROUGH `meter.current()`, so this path DOES pay a
+            // re-measurement when the history has moved since the last one (RV-11 -
+            // the previous sentence here claimed the opposite and was left stale by
+            // context-usage-gauge-accuracy). The cost is bounded the same way it always
+            // was: guard 4 caps declines per session at `stuckLimit`, and a re-measure
+            // on the measured branch walks one turn's worth of appended messages.
             this.emit({ type: 'snapshot', snapshot: this.snapshot() });
             return;
         }
@@ -478,10 +526,23 @@ export class CompactionWiring {
         };
         if (verdict.applied) {
             this.compactor.recordApplied(settled.tokensBefore, settled.tokensAfter);
-            // SITE 1 OF THE FOUR INVALIDATION SITES (hardening §3.2.3). The in-loop
-            // splice replaced the history, so every recorded index means nothing; the
-            // manual path settles through here too, so one call covers both.
-            this.compactor.invalidateMeasurement();
+            // SITE 1 OF THE FOUR INVALIDATION SITES (hardening §3.2.3), and THE LOAD-
+            // BEARING LINE OF THE P0-1 FIX (context-usage-gauge-accuracy I-9).
+            //
+            // ITS POSITION IS THE WHOLE ARGUMENT: it runs in this class's own
+            // synchronous code, BEFORE both `emit` calls below, so the `snapshot()`
+            // two statements down is guaranteed to see a dirty meter and re-measure -
+            // no matter which of the two agent-stream listeners the emitter reached
+            // first. Deleting it and relying on the meter's own `compaction_end`
+            // subscription instead moves correctness onto subscription ORDER, which is
+            // true in every unit test and false in production import order.
+            //
+            // THE **SHALLOW** RESET (I-8). A splice changes the history and nothing
+            // else, so `estimateOffset` - a calibration for this toolset on this model
+            // - is still valid and is the only thing keeping the post-compaction
+            // estimate honest (I-5). `onHistoryReplaced()` is the other depth and is
+            // NOT interchangeable with this one.
+            this.meter.onHistorySpliced();
             const path = this.archive(settled, dropped);
             if (path)
                 settled.archivePath = path;

package/dist/config/cli-commands.js

@@ -405,6 +405,11 @@ function maskConfig(config) {
 function displayOverride(key, value) {
     if (key === 'maxTokens' && value === null)
         return 'auto';
+    // The SECOND tri-state key, and it needs this for the same reason (§4.5):
+    // `contextWindow: null` is AUTO ("use the model table"), not "unset", and a
+    // bare `null` sends the user looking for a bug that is not there.
+    if (key === 'contextWindow' && value === null)
+        return 'auto';
     return undefined;
 }
 /** Resolve a flat or one-level-dotted key against the persisted config. */

package/dist/config/env.js

@@ -37,7 +37,7 @@ import process from 'node:process';
 import dotenv from 'dotenv';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
 import { clampLogLevel } from '../logging/levels.js';
-import { clampMaxTokens, clampTheme, clampThinkingLevel, isAutoToken, parseThresholdInput, } from './schema.js';
+import { clampContextWindow, clampMaxTokens, clampTheme, clampThinkingLevel, isAutoToken, parseThresholdInput, } from './schema.js';
 /**
  * Load a project `.env` from the given directory into `process.env` (existing
  * process env wins — dotenv never overrides already-set variables).
@@ -113,6 +113,20 @@ export function readEnvConfig() {
                 partial.maxTokens = clamped;
         }
     }
+    // `auto` / `0` mean AUTO (`null`); a number is clamped. Anything else is LEFT
+    // ABSENT rather than written as `null`, the rule `ARAGON_MAX_TOKENS` states one
+    // block up: a typo must not silently discard the number in the config file.
+    const contextWindow = process.env.ARAGON_CONTEXT_WINDOW?.trim();
+    if (contextWindow !== undefined && contextWindow.length > 0) {
+        if (isAutoToken(contextWindow)) {
+            partial.contextWindow = null;
+        }
+        else {
+            const clamped = clampContextWindow(contextWindow, null);
+            if (clamped !== null)
+                partial.contextWindow = clamped;
+        }
+    }
     if (process.env.ARAGON_THEME) {
         partial.theme = clampTheme(process.env.ARAGON_THEME.trim(), 'auto');
     }

package/dist/config/load.d.ts

@@ -185,6 +185,23 @@ export interface CliFlags {
      * to keep in step with `toFlags`.
      */
     fastReview?: string;
+    /**
+     * `--fast-delegate` ⇒ true, `--no-fast-delegate` ⇒ false, absent ⇒ undefined
+     * (web-use-tier-cooperation-and-control-closure §4.1.5).
+     *
+     * DECLARED AS A PAIR — MANDATORY, for the reason `--team`, `--todo-panel`,
+     * `--render-governor`, `--retry` and `--fast` each record in turn, and here
+     * with the SAME polarity as `--update`: `fast.delegate` is PERSISTED and
+     * defaults to `true`, so a lone `--no-fast-delegate` would make commander
+     * default `opts.fastDelegate` to `true` and silently overwrite a stored
+     * `false` on every run that passed no flag at all.
+     *
+     * It exists because it is the ONLY `fast.*` sub-switch with no channel a
+     * wrapper can reach: `--fast-review <n|off>` already covers `review` and
+     * `reviewEveryTurns`, and `enabled` / `model` / `provider` have both a flag
+     * and an environment variable.
+     */
+    fastDelegate?: boolean;
     /**
      * `--update` ⇒ true, `--no-update` ⇒ false, absent ⇒ undefined
      * (cli-auto-update §4.2).

package/dist/config/load.js

@@ -6,7 +6,7 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, parseThresholdInput, } from './schema.js';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, parseThresholdInput, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile } from './store.js';
 import { getConfigPath } from './app-paths.js';
@@ -250,6 +250,12 @@ function resolveFastConfig(flags, env, file) {
         ...(flags.fastProvider !== undefined && flags.fastProvider !== ''
             ? { provider: flags.fastProvider }
             : {}),
+        // `!== undefined`, for the reason stated on `flags.fast` above: commander
+        // materialises a lone `--no-fast-delegate` as `opts.fastDelegate = true`
+        // when the flag is absent, and `delegate` defaults to TRUE — so a truthiness
+        // check would force it on for every run that passed no flag at all,
+        // overwriting a stored `false` with nothing to show for it.
+        ...(flags.fastDelegate !== undefined ? { delegate: flags.fastDelegate } : {}),
         ...reviewPatch,
     });
 }
@@ -410,6 +416,42 @@ function resolveMaxTokens(flags, env, file) {
     }
     return DEFAULT_CONFIG.maxTokens ?? undefined;
 }
+/**
+ * Resolve the context-window override: env > file > default, where an EXPLICIT
+ * `null` at either layer means AUTO (context-usage-gauge-accuracy §3.6).
+ *
+ * IT CANNOT USE `pick()` FOR THE REASON `resolveMaxTokens` GIVES: `pick` skips
+ * `null`, and `null` is exactly the value being looked for. NO CLI FLAG feeds
+ * this - it is a per-installation correction for a model table entry, not a
+ * per-invocation choice, so `config set` and the environment variable are the
+ * two surfaces the design names.
+ */
+function resolveContextWindow(env, file) {
+    const layers = [
+        {
+            name: 'ARAGON_CONTEXT_WINDOW',
+            value: hasOwn(env, 'contextWindow') ? env.contextWindow : undefined,
+        },
+        {
+            name: 'config.json contextWindow',
+            value: hasOwn(file, 'contextWindow') ? file.contextWindow : undefined,
+        },
+    ];
+    for (const layer of layers) {
+        if (layer.value === undefined)
+            continue; // this layer said nothing
+        if (layer.value === null || isAutoToken(layer.value))
+            return null; // AUTO
+        const n = clampContextWindow(layer.value, null);
+        if (n !== null)
+            return n;
+        getLogger().warn('config', 'context_window_unusable', {
+            source: layer.name,
+            value: String(layer.value),
+        });
+    }
+    return DEFAULT_CONFIG.contextWindow;
+}
 /**
  * Resolve the effective config by merging all layers, then derive the runtime
  * (non-persisted) fields and enforce the timeout invariant.
@@ -445,6 +487,7 @@ export function loadConfig(flags = {}) {
     const liveToolOutput = pick(flags.liveToolOutput, env.partial.liveToolOutput, file.liveToolOutput) ??
         DEFAULT_CONFIG.liveToolOutput;
     const maxTokens = resolveMaxTokens(flags, env.partial, file);
+    const contextWindow = resolveContextWindow(env.partial, file);
     // `clampTheme` is also where the v0.3.0 `dark` name is migrated to `cool`,
     // so reading a legacy config file needs no extra step here (§4.5 / R-4).
     const theme = clampTheme(pick(flags.theme, env.partial.theme, file.theme), DEFAULT_CONFIG.theme);
@@ -534,6 +577,7 @@ export function loadConfig(flags = {}) {
         showThinking,
         liveToolOutput,
         maxTokens,
+        contextWindow,
         theme,
         reducedMotion,
         fullscreen: resolveFullscreen(flags, env.partial, file),

package/dist/config/schema.d.ts

@@ -78,6 +78,27 @@ export declare const DEFAULT_TRANSCRIPT_WINDOW = 1000;
 export declare const MIN_TRANSCRIPT_WINDOW = 50;
 export declare const MAX_TRANSCRIPT_WINDOW = 20000;
 export declare function clampTranscriptWindow(v: unknown, fallback: number): number;
+/**
+ * Bounds for a hand-supplied context window.
+ *
+ * The floor is roughly the smallest window any current model ships with; the
+ * ceiling is well above the largest, and both exist to keep a typo (a missing
+ * or an extra zero) from producing a gauge that is permanently red or
+ * permanently flat.
+ */
+export declare const MIN_CONTEXT_WINDOW = 8000;
+export declare const MAX_CONTEXT_WINDOW = 5000000;
+/**
+ * THE single gate for every `contextWindow` read AND write.
+ *
+ * TRI-STATE, AND `null` MUST PASS STRAIGHT THROUGH (RV-12). `null` means AUTO -
+ * take the model table's number, or the 128k placeholder. Clamping it into
+ * `[8000, ...]` yields 8000, which removes "auto" from the config permanently
+ * and presents to the user as an 8k denominator with a permanently red bar and
+ * no visible source. `maxTokens` above is the existing tri-state precedent and
+ * this deliberately copies its shape rather than inventing a second convention.
+ */
+export declare function clampContextWindow(v: unknown, fallback: number | null): number | null;
 /**
  * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
  *
@@ -692,6 +713,18 @@ export interface PersistedConfig {
      * `null`), which left the user no way to express "let the model decide".
      */
     maxTokens: number | null;
+    /**
+     * The context window to measure occupancy against, or `null` for AUTO
+     * (context-usage-gauge-accuracy §3.6).
+     *
+     * `null` MEANS AUTO - the model table's window, or `buildRuntimeModel`'s 128k
+     * placeholder for a model the table has never seen. It exists because that
+     * placeholder is a FABRICATED denominator: on a custom `baseUrl` or an
+     * unlisted model id the gauge is a percentage of a number nobody supplied, and
+     * before this key there was no way to correct it. Setting it also removes the
+     * `?` marker from the absolute pair (I-6).
+     */
+    contextWindow: number | null;
     theme: ThemeName;
     /** Replace spinners with a static glyph for calmer, low-motion output. */
     reducedMotion: boolean;
@@ -835,6 +868,17 @@ export interface CliConfig {
     liveToolOutput: boolean;
     /** The resolved cap, or `undefined` for AUTO (per-model ceiling, ≤ 64000). */
     maxTokens?: number;
+    /**
+     * The user's context-window override, or `null` for AUTO.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `showThinking` / `liveToolOutput` / `diffRender` each record above: the
+     * runtime reads `config.*`, where `config` is a `CliConfig`, so a key added to
+     * the persisted shape alone would round-trip through `config set`, appear in
+     * `config list` - and never reach `ContextMeter`. `ARAGON_CONTEXT_WINDOW`
+     * would parse and be discarded, with nothing failing.
+     */
+    contextWindow: number | null;
     theme: ThemeName;
     reducedMotion: boolean;
     /**

package/dist/config/schema.js

@@ -115,6 +115,39 @@ export function clampTranscriptWindow(v, fallback) {
     const n = coercePositiveInt(v, fallback);
     return Math.min(MAX_TRANSCRIPT_WINDOW, Math.max(MIN_TRANSCRIPT_WINDOW, n));
 }
+// ---------------------------------------------------------------------------
+// Context window override (context-usage-gauge-accuracy §3.6 / W5)
+// ---------------------------------------------------------------------------
+/**
+ * Bounds for a hand-supplied context window.
+ *
+ * The floor is roughly the smallest window any current model ships with; the
+ * ceiling is well above the largest, and both exist to keep a typo (a missing
+ * or an extra zero) from producing a gauge that is permanently red or
+ * permanently flat.
+ */
+export const MIN_CONTEXT_WINDOW = 8_000;
+export const MAX_CONTEXT_WINDOW = 5_000_000;
+/**
+ * THE single gate for every `contextWindow` read AND write.
+ *
+ * TRI-STATE, AND `null` MUST PASS STRAIGHT THROUGH (RV-12). `null` means AUTO -
+ * take the model table's number, or the 128k placeholder. Clamping it into
+ * `[8000, ...]` yields 8000, which removes "auto" from the config permanently
+ * and presents to the user as an 8k denominator with a permanently red bar and
+ * no visible source. `maxTokens` above is the existing tri-state precedent and
+ * this deliberately copies its shape rather than inventing a second convention.
+ */
+export function clampContextWindow(v, fallback) {
+    if (v === null)
+        return null;
+    if (v === undefined || v === '')
+        return fallback;
+    const n = typeof v === 'number' ? v : Number.parseInt(String(v), 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.min(MAX_CONTEXT_WINDOW, Math.max(MIN_CONTEXT_WINDOW, Math.floor(n)));
+}
 /**
  * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
  *
@@ -841,6 +874,9 @@ export const DEFAULT_CONFIG = {
     // The engine owns this number; spelling it here again is how the CLI and the
     // provider adapters end up disagreeing about what "the default" is.
     maxTokens: DEFAULT_MAX_OUTPUT_TOKENS,
+    // AUTO. The model table is right for every listed model, and a default number
+    // here would be the same fabricated denominator this key exists to correct.
+    contextWindow: null,
     theme: 'auto',
     reducedMotion: false,
     fullscreen: true,