@aragon-agent/cli 0.6.14 → 0.6.16

package/dist/compaction/wiring.js

@@ -1,40 +1,4 @@
-/**
- * `CompactionWiring` — the controller-side glue for context compaction
- * (context-auto-compaction §3.2.1 / §5.2).
- *
- * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
- *
- * CONSTRUCT BEFORE THE `Agent`, ATTACH AFTER IT (C-12 / D-19), and the split is
- * the whole reason this class has an `attach` method at all:
- *
- *   - The PORT has to be INSIDE the `Agent`'s constructor argument, because
- *     `AgentConfig.contextManager` has no setter and the loop reads it from the
- *     loop context.
- *   - The WIRING has to SUBSCRIBE to the `Agent`, because `compaction_end` is
- *     where the engine's `applied` verdict arrives and `agent_start` is what
- *     resets the per-run cap.
- *
- * `AgentController` cannot do both in one step: `new Agent({...})` runs before
- * every optional subsystem, precisely because `FastWiring`'s constructor
- * subscribes. So THIS CONSTRUCTOR MUST NOT SUBSCRIBE. A field assigned after the
- * `new Agent` call and spread into it conditionally produces a build where the
- * feature is registered, enabled, and SILENTLY ABSENT - the exact shape of
- * failure `controller.ts`'s `toolOutputs` comment documents.
- *
- * `manager()` returns a STABLE object for the controller's lifetime, whose two
- * 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 { shouldCompactAt } from './pressure.js';
 import { DEFAULT_RETRY_POLICY, estimatePromptTokens, initProviders, validateHistory, } from '@aragon-agent/core';
 import { getLogger } from '../logging/logger.js';
 import { mintRunId, writeArchive } from './archive.js';
@@ -126,6 +90,7 @@ export class CompactionWiring {
      * key, not an identity.
      */
     runId = mintRunId();
+    overflowNotified = false;
     constructor(deps) {
         this.deps = deps;
         this.enabled = deps.getConfig().compaction.enabled;
@@ -167,7 +132,14 @@ export class CompactionWiring {
         // setter and `contextManager` is never reassigned; the LIVE switch is inside
         // `shouldCompact`, not in the identity of this object.
         this.port = {
-            shouldCompact: (probe) => this.enabled && this.compactor.shouldCompact(probe),
+            shouldCompact: (probe) => {
+                if (!this.enabled)
+                    return false;
+                const allowed = this.compactor.shouldCompact(probe);
+                if (probe.trigger === 'overflow' && !allowed)
+                    this.notifyOverflow();
+                return allowed;
+            },
             compact: (ctx) => this.compactor.compact(ctx),
         };
     }
@@ -193,6 +165,7 @@ export class CompactionWiring {
     }
     dispose() {
         this.compactor.abort();
+        this.compactor.clearPendingManual();
         this.unsubscribe?.();
         this.unsubscribe = null;
         this.listeners.clear();
@@ -205,6 +178,8 @@ export class CompactionWiring {
     }
     setEnabled(enabled) {
         this.enabled = enabled;
+        if (!enabled)
+            this.compactor.abort();
         // Turning it back on is the user overriding guard 4, which is the only way
         // out of a self-disable short of a restart.
         if (enabled)
@@ -215,6 +190,8 @@ export class CompactionWiring {
     onConfigChanged(enabled) {
         if (enabled !== undefined && enabled !== this.enabled) {
             this.enabled = enabled;
+            if (!enabled)
+                this.compactor.abort();
             if (enabled)
                 this.compactor.clearSelfDisable();
         }
@@ -244,8 +221,19 @@ export class CompactionWiring {
      * 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.meter.onHistoryReplaced();
+    onHistoryReplaced(identity) {
+        this.compactor.onHistoryReplaced(identity);
+    }
+    getIdentity() { return this.compactor.getIdentity(); }
+    notifyOverflow() {
+        const p = this.meter.current();
+        if (this.overflowNotified || !Number.isFinite(p.occupied) || p.occupied < 0 ||
+            !Number.isFinite(p.contextWindow) || p.contextWindow <= 0 ||
+            shouldCompactAt(p, this.deps.getConfig().compaction.threshold))
+            return;
+        this.overflowNotified = true;
+        this.deps.notify('warn', 'Context limit reached before the configured compaction threshold. ' +
+            'Use /compact or correct contextWindow.');
     }
     /**
      * The per-child manager factory, or `null` when children get none
@@ -269,7 +257,7 @@ export class CompactionWiring {
             // SINK (AC-H12). It is real money on the summarizer's price table, and a
             // background repair inside a background worker is exactly the spend a
             // user would otherwise never see.
-            onUsage: (usage) => this.emit({ type: 'usage', usage }),
+            onUsage: (usage, billing) => this.emit({ type: 'usage', usage, ...billing }),
         });
     }
     // -----------------------------------------------------------------------
@@ -284,28 +272,13 @@ export class CompactionWiring {
     clearPendingManual() {
         this.compactor.clearPendingManual();
     }
-    /**
-     * The IDLE `/compact` path (§4.4 / D-25).
-     *
-     * IT VALIDATES BEFORE IT SPLICES, AND THAT IS NOT OPTIONAL (P1-7). When the
-     * agent is idle there is no loop, so §3.3 step 5 does not run — and the only
-     * way to replace the history is `Agent.replaceMessages`, which validates
-     * nothing. D-4 declares that gate unbypassable and R-2 calls an invalid splice
-     * the worst possible outcome, so this path mirrors the engine's steps 3-5
-     * exactly, INCLUDING the failure vocabulary: the card, the log and
-     * `/compact status` cannot tell the two paths apart.
-     *
-     * No watchdog handling is needed — `runLoopWithLifecycle`'s `finally` already
-     * called `watchdog.stop()`, so nothing is armed while idle.
-     *
-     * ITS CALLER MUST ADOPT `messages` — THE ARCHIVE IS ALREADY WRITTEN BY THE
-     * TIME THIS RETURNS (hardening RV-7). This path settles `applied: true` here,
-     * one statement before the caller splices, so the "never archive a live
-     * history" rule holds only because that caller applies unconditionally. That is
-     * a fact about one call site rather than an invariant, which is why it is
-     * written down where it can be checked.
-     */
+    /** Prepare, validate and synchronously adopt before publishing a successful verdict. */
     async compactNow(args) {
+        if (!this.enabled)
+            return { ok: false, reason: 'disabled' };
+        if (this.compactor.sessionTotals().inFlight)
+            return { ok: false, reason: 'already_running' };
+        this.compactor.onRunStart();
         this.compactor.queueManual(args.instructions);
         // BOTH SIDES FROM CORE'S OWN ESTIMATOR, exactly as the in-loop path gets them
         // from `compaction_end` (§5.1). There is no engine event here to supply them,
@@ -342,6 +315,19 @@ export class CompactionWiring {
             this.settlePending({ applied: false, reason, tokensBefore, tokensAfter: tokensBefore });
             return { ok: false, reason };
         }
+        if (args.signal.aborted || args.isCurrent?.() === false || !args.adopt) {
+            const reason = args.signal.aborted ? 'aborted' : 'stale_history';
+            this.settlePending({ applied: false, reason, tokensBefore, tokensAfter: tokensBefore });
+            return { ok: false, reason };
+        }
+        try {
+            args.adopt(outcome.messages);
+        }
+        catch (error) {
+            const reason = `adoption_failed: ${error instanceof Error ? error.message : String(error)}`;
+            this.settlePending({ applied: false, reason, tokensBefore, tokensAfter: tokensBefore });
+            return { ok: false, reason };
+        }
         this.settlePending({
             applied: true,
             tokensBefore,
@@ -387,6 +373,7 @@ export class CompactionWiring {
             ...(totals.declined > 0 ? { declined: totals.declined } : {}),
             tokensReclaimed: totals.tokensReclaimed,
             usage: totals.usage,
+            costUsd: totals.costUsd,
             pricingUnknown: totals.pricingUnknown,
             inFlight: totals.inFlight,
             selfDisabled: totals.selfDisabled,
@@ -460,9 +447,13 @@ export class CompactionWiring {
     onAgentEvent(event) {
         if (event.type === 'agent_start') {
             this.compactor.onRunStart();
+            this.overflowNotified = false;
             return;
         }
+        if (event.type === 'agent_end')
+            this.compactor.onRunEnd();
         if (event.type === 'turn_end') {
+            this.meter.onTurnEnd(event.usage);
             // 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
@@ -501,6 +492,7 @@ export class CompactionWiring {
         // engine cannot report `true` without a `replace` outcome, which means the
         // compactor's own record already exists — so its zeroed counts are never
         // rendered.
+        this.compactor.settleOperation(verdict);
         const record = this.pending ?? this.skeletonRecord();
         this.pending = null;
         this.open = null;
@@ -533,7 +525,6 @@ export class CompactionWiring {
             mode: verdict.applied ? record.mode : 'none',
         };
         if (verdict.applied) {
-            this.compactor.recordApplied(settled.tokensBefore, settled.tokensAfter);
             // 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).
             //
@@ -565,9 +556,8 @@ export class CompactionWiring {
      * archive a history that is still live" - and the two paths reach that verdict
      * at different moments relative to the splice. In loop, the ENGINE decides
      * after `validateHistory`, so this runs AFTER adoption. On the manual path the
-     * WIRING decides and `compactNow`'s caller adopts on the next statement, so
-     * this runs BEFORE adoption; `compactNow`'s doc comment carries that obligation
-     * for its one caller (RV-7).
+     * WIRING invokes the host adoption callback before settling, so both paths
+     * archive only histories that have actually been replaced.
      *
      * BEST-EFFORT AND SYNCHRONOUS-BUT-GUARDED. `writeArchive` never throws and
      * logs its own failure; a failed archive never affects the compaction, and it

package/dist/config/app-paths.d.ts

@@ -12,6 +12,7 @@
  *   ~/.aragon-agent/
  *   ├── config.json            persisted config (0600 on POSIX)
  *   ├── config.json.bak        `aragon config edit` pre-edit backup
+ *   ├── model-windows.json     per-model context windows, user-edited
  *   ├── prompt-history.jsonl   submitted prompts, append-only (0600 on POSIX)
  *   ├── state.json             UI bookkeeping scalars (0600 on POSIX)
  *   ├── update-state.json      auto-update coordination (0600 on POSIX)
@@ -72,6 +73,15 @@ export declare function getHomeRoot(): string;
 export declare function getConfigPath(): string;
 /** Written by `aragon config edit` before spawning the editor. */
 export declare function getConfigBackupPath(): string;
+/**
+ * `<home>/model-windows.json` — per-model context windows the user declares by
+ * hand for ids no table knows (`kimi-k3`, a gateway alias, a self-hosted model).
+ *
+ * READ-ONLY from the application's side: nothing ever writes or creates it, so
+ * a user's file cannot be clobbered by an upgrade and its absence is not an
+ * error. `config/model-windows.ts` owns the format and the lookup.
+ */
+export declare function getModelWindowsPath(): string;
 /**
  * `<home>/prompt-history.jsonl` — the prompts the user submitted, one JSON
  * object per line. Deliberately NOT under `logs/`: that directory is governed

package/dist/config/app-paths.js

@@ -12,6 +12,7 @@
  *   ~/.aragon-agent/
  *   ├── config.json            persisted config (0600 on POSIX)
  *   ├── config.json.bak        `aragon config edit` pre-edit backup
+ *   ├── model-windows.json     per-model context windows, user-edited
  *   ├── prompt-history.jsonl   submitted prompts, append-only (0600 on POSIX)
  *   ├── state.json             UI bookkeeping scalars (0600 on POSIX)
  *   ├── update-state.json      auto-update coordination (0600 on POSIX)
@@ -129,6 +130,17 @@ export function getConfigPath() {
 export function getConfigBackupPath() {
     return join(resolution.root, 'config.json.bak');
 }
+/**
+ * `<home>/model-windows.json` — per-model context windows the user declares by
+ * hand for ids no table knows (`kimi-k3`, a gateway alias, a self-hosted model).
+ *
+ * READ-ONLY from the application's side: nothing ever writes or creates it, so
+ * a user's file cannot be clobbered by an upgrade and its absence is not an
+ * error. `config/model-windows.ts` owns the format and the lookup.
+ */
+export function getModelWindowsPath() {
+    return join(resolution.root, 'model-windows.json');
+}
 /**
  * `<home>/prompt-history.jsonl` — the prompts the user submitted, one JSON
  * object per line. Deliberately NOT under `logs/`: that directory is governed

package/dist/config/env.d.ts

@@ -7,7 +7,8 @@
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
  *     ARAGON_SHOW_THINKING,
  *     ARAGON_MAX_TOKENS (a number, or `auto` / `0` for the per-model ceiling),
- *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PASTE, ARAGON_PLAN, ARAGON_TEAM,
+ *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PASTE, ARAGON_KEYBOARD_ENHANCEMENT,
+ *     ARAGON_PLAN, ARAGON_TEAM,
  *     ARAGON_TEAM_MAX, ARAGON_RETRY, ARAGON_RETRY_MAX, ARAGON_FAST,
  *     ARAGON_FAST_PROVIDER, ARAGON_FAST_MODEL, ARAGON_FAST_BASE_URL,
  *     ARAGON_LOG_LEVEL,

package/dist/config/env.js

@@ -7,7 +7,8 @@
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
  *     ARAGON_SHOW_THINKING,
  *     ARAGON_MAX_TOKENS (a number, or `auto` / `0` for the per-model ceiling),
- *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PASTE, ARAGON_PLAN, ARAGON_TEAM,
+ *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PASTE, ARAGON_KEYBOARD_ENHANCEMENT,
+ *     ARAGON_PLAN, ARAGON_TEAM,
  *     ARAGON_TEAM_MAX, ARAGON_RETRY, ARAGON_RETRY_MAX, ARAGON_FAST,
  *     ARAGON_FAST_PROVIDER, ARAGON_FAST_MODEL, ARAGON_FAST_BASE_URL,
  *     ARAGON_LOG_LEVEL,
@@ -151,6 +152,17 @@ export function readEnvConfig() {
     if (paste !== undefined && paste.length > 0) {
         partial.paste = paste === '1' || paste === 'true' || paste === 'on' || paste === 'yes';
     }
+    // ARAGON_KEYBOARD_ENHANCEMENT=0 stops the Shift+Enter mode push and its
+    // translation -- the one-env revert to pre-enhancement input handling.
+    // Parsed by the POSITIVE list, exactly as its three neighbours above are.
+    const keyboardEnhancement = process.env.ARAGON_KEYBOARD_ENHANCEMENT?.trim().toLowerCase();
+    if (keyboardEnhancement !== undefined && keyboardEnhancement.length > 0) {
+        partial.keyboardEnhancement =
+            keyboardEnhancement === '1' ||
+                keyboardEnhancement === 'true' ||
+                keyboardEnhancement === 'on' ||
+                keyboardEnhancement === 'yes';
+    }
     // ARAGON_SCROLL_RESUME_MS=<n> — idle delay before a paused viewport returns to
     // the newest line; `0` disables auto-resume. THE ONLY CHANNEL BESIDES THE
     // CONFIG FILE, because §6.1 gives this key no CLI flag on purpose. `load.ts`

package/dist/config/load.d.ts

@@ -59,6 +59,15 @@ export interface CliFlags {
      * `false` on every run that passed no flag at all.
      */
     paste?: boolean;
+    /**
+     * `--keyboard-enhancement` ⇒ true, `--no-keyboard-enhancement` ⇒ false,
+     * absent ⇒ undefined.
+     *
+     * DECLARED AS A PAIR and carried through `toFlags`, for the reason the
+     * `paste` note above records: the key is persisted and defaults to
+     * `true`, so a lone negative flag must not read as silence.
+     */
+    keyboardEnhancement?: boolean;
     /** `--no-skills` ⇒ false. Turns the whole skill subsystem off (§7.5). */
     skills?: boolean;
     /** `--skill <name>` ×N — force Level 2 injection for this run. */

package/dist/config/load.js

@@ -78,6 +78,19 @@ function resolvePaste(flags, env, file) {
         return file.paste;
     return DEFAULT_CONFIG.paste;
 }
+/**
+ * Keyboard enhancement: flag > env > file > default `true`. Shaped exactly
+ * like `resolvePaste` above, for the reason its own note gives.
+ */
+function resolveKeyboardEnhancement(flags, env, file) {
+    if (flags.keyboardEnhancement !== undefined)
+        return flags.keyboardEnhancement;
+    if (env.keyboardEnhancement !== undefined)
+        return env.keyboardEnhancement;
+    if (file.keyboardEnhancement !== undefined)
+        return file.keyboardEnhancement;
+    return DEFAULT_CONFIG.keyboardEnhancement;
+}
 /**
  * Idle scroll-resume delay: env › file › default 5000, clamped to [0, 120000].
  *
@@ -585,6 +598,7 @@ export function loadConfig(flags = {}, options = {}) {
         mouse: resolveMouse(flags, env.partial, file),
         mouseSelect: resolveMouseSelect(flags, env.partial, file),
         paste: resolvePaste(flags, env.partial, file),
+        keyboardEnhancement: resolveKeyboardEnhancement(flags, env.partial, file),
         scrollResumeMs: resolveScrollResumeMs(env.partial, file),
         // From `<home>/state.json`, not the config file — see `ui-state.ts`.
         submitCount: readSubmitCount(),

package/dist/config/model-windows.d.ts

@@ -0,0 +1,91 @@
+/**
+ * User-declared context windows, read from `~/.aragon-agent/model-windows.json`
+ * (path owned by `app-paths.ts`).
+ *
+ * WHY THIS FILE EXISTS. `ModelRegistry.getContextWindow` resolves a window from
+ * API discovery, the builtin model lists and the ten-entry catalog - and for
+ * every other id (a gateway alias, a self-hosted model, a release too new for
+ * the table) it returns the explicitly-untrusted 128k `fallback`. The gauge
+ * then renders `?` forever, by design: it refuses to divide by a guessed
+ * denominator. The one number that can make the denominator real is the user's
+ * own, and `config.json`'s `contextWindow` key can only hold ONE of it. This
+ * file is the per-model form of the same assertion.
+ *
+ * THE APPLICATION NEVER WRITES IT. A file the user owns by hand cannot be
+ * clobbered by an upgrade, and its absence is the ordinary case, not an error.
+ *
+ * ASCII ONLY: `src/config/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`).
+ */
+/** Structural bounds only; there is no policy surface to tune here. */
+export interface ModelWindowsLimits {
+    /** Entries beyond this many are dropped, in file order. */
+    readonly maxEntries: number;
+    /** Keys longer than this are dropped rather than trusted as ids. */
+    readonly maxKeyLength: number;
+    /** A window below the smallest real context (1k) is a typo, not a limit. */
+    readonly minWindow: number;
+    /** A window above 1e9 tokens is also a typo; no model ships that today. */
+    readonly maxWindow: number;
+}
+export declare const MODEL_WINDOWS_LIMITS: ModelWindowsLimits;
+/** Normalized model id -> declared window. Keys are stored ALREADY normalized. */
+export type ModelWindowTable = ReadonlyMap<string, number>;
+/**
+ * Same normalization core's `catalogModelId` applies, restated here because it
+ * is not part of Core's public surface and a second exporter would be a
+ * dependency on an internal. Keep the two in step: a date-stamped id
+ * (`kimi-k3-20260716`) and its bare form must resolve to one entry.
+ */
+export declare function normalizeModelKey(modelId: string): string;
+/** What a parse produced, and whether the FILE itself was at fault. */
+export interface ModelWindowsParse {
+    table: ModelWindowTable;
+    /**
+     * True only when the text could not be understood at all (bad JSON, wrong
+     * top-level type). A valid file with zero USABLE entries is `false`: the
+     * user wrote JSON, the values were the problem, and every dead value was
+     * already dropped rather than trusted.
+     */
+    malformed: boolean;
+}
+/**
+ * Parse already-decoded text into a table. NEVER THROWS - a hand-edited file
+ * is the rule here, not the exception, and a typo must cost the user one dead
+ * entry, not the session. Two accepted shapes:
+ *
+ *   { "version": 1, "windows": { "kimi-k3": 1048576 } }
+ *   { "kimi-k3": 1048576 }                        (bare map, same effect)
+ *
+ * The wrapper exists so the format can grow fields without a migration; the
+ * bare map is accepted because the first shape a user types is the simple one.
+ * A leading UTF-8 BOM is tolerated: `readFileSync(..., 'utf8')` does not strip
+ * it, `JSON.parse` cannot parse it, and Notepad writes it by default.
+ */
+export declare function parseModelWindowsResult(text: string): ModelWindowsParse;
+/** The table alone, for callers that do not care why it might be empty. */
+export declare function parseModelWindows(text: string): ModelWindowTable;
+/**
+ * mtime-cached lookup over the file.
+ *
+ * WHY A STAT PER LOOKUP RATHER THAN A LOAD AT STARTUP: `getModelInfoFor` is
+ * called on every measurement, and the meter's `refreshValidity` re-reads the
+ * window precisely so a moved denominator (a `/model` switch, a live config
+ * edit) re-measures without a relaunch. A user saving this file mid-session
+ * gets the same treatment - `statSync` is microseconds, and the read itself
+ * only happens when the stamp actually changes.
+ *
+ * THE STAMP IS mtimeMs+size, so a rewrite that lands in the SAME millisecond
+ * with the SAME byte count serves the previous table once. Squeezing that
+ * window shut would need a content hash per lookup, which is exactly the cost
+ * the stamp exists to avoid; the next differing write clears it regardless.
+ */
+export declare class ModelWindows {
+    private readonly path;
+    private table;
+    private stamp;
+    constructor(path?: string);
+    /** The declared window for `modelId`, or `undefined` when nobody declared one. */
+    lookup(modelId: string): number | undefined;
+    private refresh;
+}

package/dist/config/model-windows.js

@@ -0,0 +1,181 @@
+/**
+ * User-declared context windows, read from `~/.aragon-agent/model-windows.json`
+ * (path owned by `app-paths.ts`).
+ *
+ * WHY THIS FILE EXISTS. `ModelRegistry.getContextWindow` resolves a window from
+ * API discovery, the builtin model lists and the ten-entry catalog - and for
+ * every other id (a gateway alias, a self-hosted model, a release too new for
+ * the table) it returns the explicitly-untrusted 128k `fallback`. The gauge
+ * then renders `?` forever, by design: it refuses to divide by a guessed
+ * denominator. The one number that can make the denominator real is the user's
+ * own, and `config.json`'s `contextWindow` key can only hold ONE of it. This
+ * file is the per-model form of the same assertion.
+ *
+ * THE APPLICATION NEVER WRITES IT. A file the user owns by hand cannot be
+ * clobbered by an upgrade, and its absence is the ordinary case, not an error.
+ *
+ * ASCII ONLY: `src/config/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`).
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { getLogger } from '../logging/logger.js';
+import { getModelWindowsPath } from './app-paths.js';
+export const MODEL_WINDOWS_LIMITS = {
+    maxEntries: 512,
+    maxKeyLength: 200,
+    minWindow: 1_024,
+    maxWindow: 1_000_000_000,
+};
+/**
+ * Same normalization core's `catalogModelId` applies, restated here because it
+ * is not part of Core's public surface and a second exporter would be a
+ * dependency on an internal. Keep the two in step: a date-stamped id
+ * (`kimi-k3-20260716`) and its bare form must resolve to one entry.
+ */
+export function normalizeModelKey(modelId) {
+    return modelId.trim().toLowerCase()
+        .replace(/^(models|openai|anthropic|google)\//, '')
+        .replace(/-(?:\d{4}-\d{2}-\d{2}|\d{8})$/, '');
+}
+function isWindowValue(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) &&
+        value >= MODEL_WINDOWS_LIMITS.minWindow && value <= MODEL_WINDOWS_LIMITS.maxWindow;
+}
+/**
+ * Parse already-decoded text into a table. NEVER THROWS - a hand-edited file
+ * is the rule here, not the exception, and a typo must cost the user one dead
+ * entry, not the session. Two accepted shapes:
+ *
+ *   { "version": 1, "windows": { "kimi-k3": 1048576 } }
+ *   { "kimi-k3": 1048576 }                        (bare map, same effect)
+ *
+ * The wrapper exists so the format can grow fields without a migration; the
+ * bare map is accepted because the first shape a user types is the simple one.
+ * A leading UTF-8 BOM is tolerated: `readFileSync(..., 'utf8')` does not strip
+ * it, `JSON.parse` cannot parse it, and Notepad writes it by default.
+ */
+export function parseModelWindowsResult(text) {
+    const body = text.replace(/^\uFEFF/, '');
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return { table: new Map(), malformed: true };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { table: new Map(), malformed: true };
+    }
+    const record = parsed;
+    const source = record.windows !== undefined && record.windows !== null &&
+        typeof record.windows === 'object' && !Array.isArray(record.windows)
+        ? record.windows
+        : record;
+    const table = new Map();
+    for (const [rawKey, rawValue] of Object.entries(source)) {
+        const key = normalizeModelKey(rawKey);
+        if (key.length === 0 || key.length > MODEL_WINDOWS_LIMITS.maxKeyLength)
+            continue;
+        if (!isWindowValue(rawValue))
+            continue;
+        table.set(key, rawValue);
+        if (table.size >= MODEL_WINDOWS_LIMITS.maxEntries)
+            break;
+    }
+    return { table, malformed: false };
+}
+/** The table alone, for callers that do not care why it might be empty. */
+export function parseModelWindows(text) {
+    return parseModelWindowsResult(text).table;
+}
+/**
+ * Decode the raw bytes the way a Windows text editor may have saved them.
+ *
+ * `readFileSync(path, 'utf8')` alone fails THREE ways on this machine's most
+ * common editors: a UTF-8 BOM survives into the string and kills `JSON.parse`,
+ * and Notepad's "Unicode" saves are UTF-16LE (or BE), which decode as NUL-laden
+ * mojibake. All three are silent feature-death for exactly the user who just
+ * tried to configure it, so the sniff happens before any parse.
+ */
+function decodeModelWindowsFile(bytes) {
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) {
+        return bytes.subarray(2).toString('utf16le');
+    }
+    if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+        // Big-endian UTF-16: Node has no utf16be decoder, so swap pairs in place
+        // on a COPY and reuse the little-endian decoder.
+        const swapped = Buffer.from(bytes.subarray(2));
+        for (let i = 0; i + 1 < swapped.length; i += 2) {
+            const high = swapped[i];
+            swapped[i] = swapped[i + 1];
+            swapped[i + 1] = high;
+        }
+        return swapped.toString('utf16le');
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        return bytes.subarray(3).toString('utf8');
+    }
+    return bytes.toString('utf8');
+}
+/**
+ * mtime-cached lookup over the file.
+ *
+ * WHY A STAT PER LOOKUP RATHER THAN A LOAD AT STARTUP: `getModelInfoFor` is
+ * called on every measurement, and the meter's `refreshValidity` re-reads the
+ * window precisely so a moved denominator (a `/model` switch, a live config
+ * edit) re-measures without a relaunch. A user saving this file mid-session
+ * gets the same treatment - `statSync` is microseconds, and the read itself
+ * only happens when the stamp actually changes.
+ *
+ * THE STAMP IS mtimeMs+size, so a rewrite that lands in the SAME millisecond
+ * with the SAME byte count serves the previous table once. Squeezing that
+ * window shut would need a content hash per lookup, which is exactly the cost
+ * the stamp exists to avoid; the next differing write clears it regardless.
+ */
+export class ModelWindows {
+    path;
+    table = new Map();
+    stamp = null;
+    constructor(path = getModelWindowsPath()) {
+        this.path = path;
+    }
+    /** The declared window for `modelId`, or `undefined` when nobody declared one. */
+    lookup(modelId) {
+        this.refresh();
+        return this.table.get(normalizeModelKey(modelId));
+    }
+    refresh() {
+        let stamp;
+        try {
+            const stats = statSync(this.path);
+            stamp = { mtimeMs: stats.mtimeMs, size: stats.size };
+        }
+        catch (error) {
+            // A deleted file (ENOENT) is a decision: drop the entries. Any OTHER
+            // failure (EACCES, an antivirus lock) is transient, and blanking every
+            // declared window because a scanner held the file open for 50 ms would
+            // swing the gauge to `?` for a reason the user cannot see - keep the
+            // last good table and try again on the next lookup.
+            if (error.code === 'ENOENT') {
+                this.stamp = null;
+                this.table = new Map();
+            }
+            return;
+        }
+        if (stamp.mtimeMs === this.stamp?.mtimeMs && stamp.size === this.stamp.size)
+            return;
+        let bytes;
+        try {
+            bytes = readFileSync(this.path);
+        }
+        catch {
+            return; // Appeared in the stat, gone in the read: try again next lookup.
+        }
+        const result = parseModelWindowsResult(decodeModelWindowsFile(bytes));
+        if (result.malformed) {
+            getLogger().warn('config', 'model-windows.json could not be parsed; ignoring it until it is fixed', { path: this.path });
+        }
+        this.table = result.table;
+        this.stamp = stamp;
+    }
+}

package/dist/config/schema.d.ts

@@ -577,7 +577,7 @@ export interface CompactionConfig {
      * SESSION'S OWN MODEL, and the first compaction is a ~30 k-token call on it.
      */
     useFastTier: boolean;
-    /** What happens when summarization fails outright. See §3.7 rungs 3 / 4. */
+    /** Legacy truncate remains readable; all failures now preserve history. */
     onFailure: CompactionFailureMode;
     /**
      * Give `task` children their own compaction
@@ -786,6 +786,14 @@ export interface PersistedConfig {
      * asked for; a kill switch is what a bug report needs.
      */
     paste: boolean;
+    /**
+     * Ask the terminal to report modified keys distinctly so Shift+Enter can
+     * insert a newline (win32-input-mode on Windows, kitty disambiguate +
+     * modifyOtherKeys elsewhere). A KILL SWITCH in the exact sense `paste`
+     * above records: the encoding tables are structural and live in
+     * `input/win32-input-mode.ts` / `input/csiu-keys.ts`.
+     */
+    keyboardEnhancement: boolean;
     /** Idle ms before a paused viewport returns to the newest line; `0` disables. */
     scrollResumeMs: number;
     /** Start every session in PLAN mode (plan-mode §4.4). */
@@ -971,6 +979,15 @@ export interface CliConfig {
      * reach none of them.
      */
     paste: boolean;
+    /**
+     * Whether this session may push the keyboard-enhancement modes.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `paste` above records: `runInteractive` reads it -- where `config`
+     * is a `CliConfig` -- to decide the filter's `enhancedKeys` feature
+     * and the `enableKeyboardEnhancement` push.
+     */
+    keyboardEnhancement: boolean;
     /** Idle ms before a paused viewport returns to the newest line; `0` disables. */
     scrollResumeMs: number;
     /**