@aragon-agent/cli 0.6.15 → 0.6.16

package/README.md

@@ -433,7 +433,7 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | Key | Action |
 | --- | --- |
 | `Enter` | 空闲时发送，运行时加入队列；收到 Core 已纳入会话的接收凭据后才移除 Queue 提示 |
-| `Ctrl+J` / `Alt+Enter` / `Shift+Enter` | 插入换行。Ctrl+J 已通过输入链路测试；另外两种组合键需要宿主发送独立序列，Alt+Enter 可能被宿主拦截。参见 [终端设置](#terminal-setup-for-shiftenter) |
+| `Ctrl+J` / `Alt+Enter` / `Shift+Enter` | 插入换行。应用默认请求终端区分修饰键（Windows 用 win32-input-mode，macOS/Linux 用 kitty/modifyOtherKeys），Shift+Enter 在支持的终端开箱即用；不支持的终端用 Ctrl+J。参见 [终端设置](#terminal-setup-for-shiftenter) |
 | `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
 | `Ctrl+P` | The same toggle, over a channel no Windows console can swallow. Use it if `Shift+Tab` does nothing |
 | `Esc` | Close an overlay or popup; otherwise ask for interruption confirmation. While idle, cancel pending auto-continuation |
@@ -490,10 +490,13 @@ is what it used to do. Inline mode is unaffected either way.
 
 ## Terminal setup for Shift+Enter
 
-输入支持 `Ctrl+J`、`Alt+Enter` 和可独立编码的 `Shift+Enter` 换行。如果终端把
-Shift+Enter 与 Enter 都发送为 CR，应用无法区分；请用 `/terminal-setup` 查看绑定，
-让 Shift+Enter 发送 `\u001b[13;2u`。合并到已有终端配置，不要覆盖其他快捷键；
-终端拦截某个组合键时可使用另外两种方式。参考绑定如下：
+应用现在会主动请求终端区分修饰键：Windows 上推送 win32-input-mode（conhost 与
+Windows Terminal 均支持），macOS/Linux 上推送 kitty disambiguate 与
+`modifyOtherKeys=2`（iTerm2、kitty、ghostty、WezTerm、foot、Alacritty 实现其一），
+并在 stdin 过滤器里把新编码翻译回传统字节，Ink 的按键解析不受影响。上述推送不满足时
+（macOS Terminal.app、旧 Node 下的 conhost、或不支持任何协议的终端）Shift+Enter 仍与
+Enter 同为 CR，此时用 `Ctrl+J` 换行，或按 `/terminal-setup` 给终端加一条让
+Shift+Enter 发送 `\u001b[13;2u` 的绑定（合并进已有配置，不要覆盖其他快捷键）。参考绑定如下：
 
 - **Windows Terminal** — `settings.json` 的 `actions` 与 `keybindings` 分别定义动作和按键；完整示例见下文“输入、待处理队列与底部状态区”。
 - **VS Code integrated terminal** — `keybindings.json`:
@@ -507,10 +510,14 @@ Shift+Enter 与 Enter 都发送为 CR，应用无法区分；请用 `/terminal-s
 - **macOS Terminal.app / legacy conhost** — cannot rebind `Enter`; use
   `Ctrl+J` or `Alt+Enter`
 
-aragon deliberately does not push kitty keyboard mode or `modifyOtherKeys=2`
-onto the terminal itself: mode 2 re-encodes *every* modified key as CSI-u and
-would blind this app's (and Ink's) key parsing for the whole session. One
-user-side binding reaches the same result for the one key that needs it.
+The push and its translation ship as one unit: `input/win32-input-mode.ts` and
+`input/csiu-keys.ts` translate every enhanced encoding back to the legacy
+bytes before Ink parses them, so a translated stream is byte-identical to a
+pre-enhancement one (Enter family excepted: a modified Enter becomes the
+newline frame). Windows additionally requires Node >= 22.17 / >= 24.2 --
+older versions never turn on virtual-terminal input. Opt out with
+`aragon config set keyboardEnhancement false`, `--no-keyboard-enhancement`,
+or `ARAGON_KEYBOARD_ENHANCEMENT=0`.
 
 ## Queued messages while the agent runs
 
@@ -1353,7 +1360,8 @@ Context
 ```
 
 Two lines are worth reading closely. **`Window`** always names where the number
-came from — the model API, the model table, your own `contextWindow`, or the invented
+came from — the model API, the model table, your own `contextWindow`, a
+`model-windows.json` entry, or the invented
 placeholder — because those are indistinguishable everywhere else. And
 **`Compaction`** reports what is actually true of this session, including
 `off - not registered for this session (started with --no-compaction)`; it never
@@ -1361,8 +1369,9 @@ promises a threshold that nothing will act on.
 
 ### `contextWindow`
 
-Window resolution uses your explicit override first, then API metadata from the
-configured endpoint, then the built-in catalog (including known aliases and dated
+Window resolution uses your explicit override first, then per-model declarations
+in `model-windows.json`, then API metadata from the configured endpoint, then the
+built-in catalog (including known aliases and dated
 snapshots). Startup, connection changes, and subsequent prompts refresh discovery
 in the background, with a five-minute cache. OpenAI-compatible endpoints may expose
 `context_length` or `context_window`; Anthropic uses `max_input_tokens`; Google uses
@@ -1384,6 +1393,33 @@ Values are clamped to `[8000, 5000000]`; `auto` (the default) is stored as
 and `/context` still shows that it came from you, which is what makes a wrong
 value findable.
 
+#### `model-windows.json` — one window per model
+
+`contextWindow` describes ONE model: the active one. To pin several at once — a
+main model plus a fast tier plus a gateway alias — declare them by id in
+`~/.aragon-agent/model-windows.json`:
+
+```json
+{
+  "version": 1,
+  "windows": {
+    "kimi-k3": 1048576,
+    "glm-5.3": 1048576,
+    "glm-5.3-flash": 1048576
+  }
+}
+```
+
+A bare map without the wrapper works too. Keys are matched case-insensitively
+after stripping a `models/`-style prefix and a dated snapshot suffix, so
+`Kimi-K3-20260716` still resolves. Entries must be whole tokens between 1024 and
+1e9; at most 512 are kept. The file is read live (mtime-cached), never written
+by the CLI, and outranks API discovery and the catalog while still losing to the
+active model's `contextWindow` override. `/context` reports these windows as
+`from model-windows.json`, and a file that cannot be parsed is ignored with one
+log line rather than trusted. UTF-8 (with or without BOM) and UTF-16 saves are
+both accepted.
+
 ## Context compaction
 
 A long agentic run fills the model's context window. Before this existed, the
@@ -2150,6 +2186,8 @@ Everything AragonAgent keeps for you lives under one directory in your home:
 ~/.aragon-agent/                    (Windows: C:\Users\<you>\.aragon-agent\)
 ├── config.json                     settings + API keys (0600 on POSIX)
 ├── config.json.bak                 written by `aragon config edit` before it opens
+├── model-windows.json              per-model context windows you declare by hand;
+│                                   read live, never written by the CLI
 ├── prompt-history.jsonl            prompts you submitted, for ↑ recall (0600 on POSIX)
 ├── state.json                      UI bookkeeping: submit count, one-shot notices
 ├── update-state.json               auto-update: last check, pending restart, skipped version,
@@ -2366,7 +2404,9 @@ UTF-16 编辑和 ZWJ/组合字形仍有既有限制，本次修复保证视觉
 ## 输入、待处理队列与底部状态区
 
 Enter 在空闲时发送，运行时加入队列；启动阶段拒绝重复提交并保留草稿。
-Ctrl+J 换行；终端能发送独立序列时，Shift+Enter 与 Alt+Enter 也可换行。
+Ctrl+J 换行；应用默认推送键盘增强模式（Windows 用 win32-input-mode，其余平台用
+kitty disambiguate + modifyOtherKeys=2）并将新编码翻译回传统字节，因此 Shift+Enter
+与 Alt+Enter 在支持的终端开箱即用，Ctrl+J 始终可用。
 光标按完整字素移动，支持中文、组合字符和 emoji；输入最多占终端高度四分之一且不超过六行。
 括号粘贴保留换行，不触发发送。过滤器或粘贴支持关闭时，不保证未标记多行粘贴安全。
 过滤器不可用时 Delete 保守按 Backspace 处理，避免退格误删后文。
@@ -2375,14 +2415,14 @@ Ctrl+J 换行；终端能发送独立序列时，Shift+Enter 与 Alt+Enter 也
 原生剪贴板工具完成后显示确认，OSC 52 只表示请求已发送，终端可能拒绝。
 Shift+拖动或 `/mouse off` 后的选区由宿主管理，应用无法关闭宿主的自动复制。
 
-Queue 面板逐条显示待处理消息，数量在展开状态详情中按空间显示。只有 Core 已把消息纳入会话并发回接收凭据，
+Queue 面板逐条显示待处理消息，数量在展开状态详情中按空间显示。只有 Core 已把消息纳入会话并发回接收凭据，
 该条提示才会消失。中断时未接收消息显示暂停；`/queue` 可分页查看全部原文，Esc 关闭。
 `/clear` 不丢待处理消息；`/reset`、切换会话会明确报告取消数量；恢复保存的未发送历史不会自动重发。
 
-底部依次为固定输入框和一行核心状态；Ctrl+G 展开或收起第二行详情。五个核心字段按显示宽度缩写，始终保留。
-核心上下文显示当前主 Agent 的百分比；展开详情或 /context 可查看已用/上限 tokens；`~` 表示含估算，`?` 表示上限未知。
+底部依次为固定输入框和一行核心状态；Ctrl+G 展开或收起第二行详情。五个核心字段按显示宽度缩写，始终保留。
+核心上下文显示当前主 Agent 的百分比；展开详情或 /context 可查看已用/上限 tokens；`~` 表示含估算，`?` 表示上限未知。
 费用是含子代理、快速模型及压缩的会话估算 USD，恢复会话沿用累计，缺价格按零计，零值不保证免费。
-本轮均速只累计主 Agent 已报告的 output tokens，再除以本轮总耗时（含工具与等待）；排除辅助调用，并非瞬时生成速度。结束后保留耗时，速度显示 --。
+本轮均速只累计主 Agent 已报告的 output tokens，再除以本轮总耗时（含工具与等待）；排除辅助调用，并非瞬时生成速度。结束后保留耗时，速度显示 --。
 `/context` 提供统计范围和完整值。
 
 Windows Terminal：在设置 JSON **根级**添加 `"copyOnSelect": false`，把以下条目合并到已有数组：
@@ -2432,10 +2472,10 @@ VS Code 用户设置添加 `"terminal.integrated.copyOnSelection": false`，快
 
 配置库仍位于 `ARAGON_HOME` 指向目录中的 `config.json`，不写入会话文件。密钥按现有机制明文保存：POSIX 创建权限为 0600，Windows 依赖用户目录 ACL，不提供加密。`config get/list` 对方案密钥使用固定掩码；损坏或未来版本的配置段整体隐藏。既有 `config edit` 备份也包含凭据。关闭通用日志脱敏、使用短密钥或分享第三方 SDK 错误日志时，仍需自行检查日志内容。
 
-### 固定输入与状态详情人工验收
-
-在 Windows Terminal/PowerShell、VS Code 集成终端以及 macOS/Linux 终端分别检查
-40x12、80x24、120x40。保留草稿，连续输出思考、正文与工具日志至少 30 秒：
-输入上下边框不得移动；拖动消息滚动条不会隐藏输入。切换 Ctrl+G 仅改变一行，
-复制、队列、通知和更新不自动展开。验证补全、Unicode 草稿和光标在切换后保留，
-弹层期间 Ctrl+G 无效，小屏恢复后草稿与状态模式保留。自动化测试不能替代这些宿主观察。
+### 固定输入与状态详情人工验收
+
+在 Windows Terminal/PowerShell、VS Code 集成终端以及 macOS/Linux 终端分别检查
+40x12、80x24、120x40。保留草稿，连续输出思考、正文与工具日志至少 30 秒：
+输入上下边框不得移动；拖动消息滚动条不会隐藏输入。切换 Ctrl+G 仅改变一行，
+复制、队列、通知和更新不自动展开。验证补全、Unicode 草稿和光标在切换后保留，
+弹层期间 Ctrl+G 无效，小屏恢复后草稿与状态模式保留。自动化测试不能替代这些宿主观察。

package/dist/agent/controller.d.ts

@@ -15,6 +15,7 @@ import type { PromptOptions, PromptOutcome } from './prompt-options.js';
 import { ModelRegistry, type AgentEvent, type AgentTool, type Message, type ModelInfo, type ModelRef, type ProviderRegistry, type ThinkingLevel } from '@aragon-agent/core';
 import type { CliConfig, CompactionConfig, FastConfig, RetryConfig, TeamConfig, ThemeName, TodoConfig } from '../config/schema.js';
 import type { ModelRole } from '../config/model-profiles.js';
+import { ModelWindows } from '../config/model-windows.js';
 import { type ConfirmRequest } from '../tools/index.js';
 import type { ToolPermission } from '../exec/permission.js';
 import { type ToolOutputListener } from '../tools/tool-output-store.js';
@@ -102,6 +103,13 @@ export interface ControllerDeps {
      * once at construction and lost at the first `rebuildSystemPrompt()`.
      */
     appendSystemPrompt?: string;
+    /**
+     * The per-model window table from ~/.aragon-agent/model-windows.json.
+     * Injectable so tests can hand the controller a table without writing into
+     * the shared vitest home root (app-paths.ts TEST-ISOLATION CONTRACT);
+     * production leaves it absent and the constructor builds the real one.
+     */
+    modelWindows?: ModelWindows;
 }
 /** What `setAgentMode` actually adopted — see `AgentController.setAgentMode`. */
 export interface AgentModeState {
@@ -124,6 +132,8 @@ export declare class AgentController {
     private readonly agent;
     private readonly providerRegistry;
     private readonly modelRegistry;
+    /** Per-model user-declared context windows; see `config/model-windows.ts`. */
+    private readonly modelWindows;
     private modelMetadataEnabled;
     private modelMetadataGeneration;
     private modelMetadataAbort;

package/dist/agent/controller.js

@@ -7,6 +7,7 @@ import { clampCompactionConfig, clampFastConfig, clampRetryConfig, clampTeamConf
 import { resolveModelProfileState } from '../config/model-profile-resolution.js';
 import { makeGetApiKey } from '../config/load.js';
 import { updatePersistedConfig } from '../config/store.js';
+import { ModelWindows } from '../config/model-windows.js';
 import { createBuiltinTools } from '../tools/index.js';
 import { createFileChangeStore } from '../tools/file-change-store.js';
 import { createToolOutputStore, } from '../tools/tool-output-store.js';
@@ -53,6 +54,8 @@ export class AgentController {
     agent;
     providerRegistry;
     modelRegistry;
+    /** Per-model user-declared context windows; see `config/model-windows.ts`. */
+    modelWindows;
     modelMetadataEnabled = false;
     modelMetadataGeneration = 0;
     modelMetadataAbort = new AbortController();
@@ -275,6 +278,7 @@ export class AgentController {
         // reuses this very registry instance.
         this.providerRegistry = initProviders({ retryPolicy: toRetryPolicy(config.retry) });
         this.modelRegistry = new ModelRegistry(this.providerRegistry);
+        this.modelWindows = deps.modelWindows ?? new ModelWindows();
         this.skillsEnabled = config.skills.enabled;
         this.onSkillsChanged = deps.onSkillsChanged;
         this.skills = new SkillService({
@@ -1737,9 +1741,18 @@ export class AgentController {
         const found = this.modelRegistry.getModel(ref.providerId, ref.modelId);
         const baseUrl = ref.baseUrl ?? (ref.providerId === this.config.provider && ref.modelId === this.config.model
             ? this.config.baseUrl : undefined);
+        const userWindow = this.modelWindows.lookup(ref.modelId);
         return {
             ...(found ?? this.modelRegistry.buildRuntimeModel(ref.providerId, ref.modelId)),
             ...this.modelRegistry.getContextWindow(ref.providerId, ref.modelId, baseUrl),
+            // A USER-DECLARED WINDOW OUTRANKS EVERY TABLE (model-windows.json): the
+            // user asserted the number for exactly this id, while api/catalog are
+            // what this process managed to look up about it. It still LOSES to
+            // config.json's `contextWindow`, which `ContextMeter.resolveWindow`
+            // consults before it ever reaches here.
+            ...(userWindow !== undefined
+                ? { contextWindow: userWindow, contextWindowSource: 'user' }
+                : {}),
         };
     }
     /** Best-effort metadata lookup; never block typing or a model request. */

package/dist/cli.js

@@ -46,6 +46,7 @@ import { createFrameDiffer } from './ui/frame-differ.js';
 import { wrapStdoutForFrames } from './ui/stdout-frame-writer.js';
 import { setFrameStatsProvider } from './commands/perf.js';
 import { tryCreateStdinFilter } from './input/stdin-filter.js';
+import { enableKeyboardEnhancement, NOOP_KEYBOARD_ENHANCEMENT, } from './input/keyboard-enhancement.js';
 import { createScrollbarBridge } from './ui/scrollbar-controller.js';
 import { createPointerRouter } from './input/pointer-router.js';
 import { createFrameObserver } from './ui/frame-observer.js';
@@ -120,6 +121,10 @@ function toFlags(opts) {
         // `CliFlags`, AND a line here; `config.test.ts` is the regression pin that
         // exists because `--no-mouse` shipped inert once already.
         paste: opts.paste,
+        // Site three of three for `--keyboard-enhancement` /
+        // `--no-keyboard-enhancement`, for the reason `paste` one line up
+        // records: the key is persisted and defaults to true.
+        keyboardEnhancement: opts.keyboardEnhancement,
         skills: opts.skills,
         skill: opts.skill,
         skillsYes: opts.skillsYes,
@@ -465,8 +470,22 @@ function runInteractive(flags, extras = {}) {
     // advising the user about a mode they just disabled.
     const wantPaste = config.paste && !!process.stdin.isTTY;
     const pasteBridge = { notify: null };
+    // --- Keyboard enhancement (Shift+Enter newline). --------------------------
+    //
+    // THE THIRD STREAM GATE, AND THE SAME DISCIPLINE AS THE OTHER TWO. On
+    // win32 the enhancement rides the SAME `vtInputSupported` measurement
+    // the mouse does: Node < 22.17 / < 24.2 never turns on
+    // `ENABLE_VIRTUAL_TERMINAL_INPUT`, the win32-input-mode records cannot
+    // reach the process, and pushing `?9001h` there would be a mode nobody
+    // can observe -- the exact gap the mouse gate closes for `?1000h`.
+    // Elsewhere the push is kitty disambiguate + modifyOtherKeys, which a
+    // terminal that implements neither ignores (verified byte-identical on
+    // conhost), so no capability gate is possible or needed there.
+    const wantEnhancedKeys = config.keyboardEnhancement &&
+        !!process.stdin.isTTY &&
+        (process.platform !== 'win32' || vtInputSupported);
     const filter = process.stdin.isTTY
-        ? tryCreateStdinFilter(process.stdin, { mouse: wantMouse, paste: wantPaste }, (reason) => logger.warn('cli', 'stdin_filter_failed', { reason }), pasteBridge)
+        ? tryCreateStdinFilter(process.stdin, { mouse: wantMouse, paste: wantPaste, enhancedKeys: wantEnhancedKeys }, (reason) => logger.warn('cli', 'stdin_filter_failed', { reason }), pasteBridge)
         : null;
     /**
      * THE ONE EXPRESSION EVERY MOUSE SITE READS (I-11 / D-17).
@@ -478,6 +497,8 @@ function runInteractive(flags, extras = {}) {
     const mouseOn = wantMouse && filter !== null;
     /** Same discipline for DEC 2004: already decided here, never re-derived. */
     const pasteOn = wantPaste && filter !== null;
+    /** Same discipline: the translation runs only when a filter fronts Ink. */
+    const enhancedKeysOn = wantEnhancedKeys && filter !== null;
     const disposeStdinFilter = () => filter?.dispose();
     // --- Drag-select (tui-selection-and-scroll-follow §4.4). ------------------
     //
@@ -565,6 +586,16 @@ function runInteractive(flags, extras = {}) {
             ...(snapshot.droppedEntries ? { droppedEntries: snapshot.droppedEntries } : {}),
         }));
     };
+    // AFTER the filter, BEFORE the render: the enhanced encodings this mode
+    // turns on must never reach Ink un-translated, and the ordering invariant
+    // `stdin-filter.ts` states for `?1000h` / `?2004h` covers `?9001h`
+    // and the CSI-u pushes identically.
+    const keyboardEnhancement = enhancedKeysOn
+        ? enableKeyboardEnhancement(process.stdout, {
+            platform: process.platform,
+            vtInputSupported,
+        })
+        : NOOP_KEYBOARD_ENHANCEMENT;
     {
         // `mouse` here means "a mouse-parsing filter is installed", NOT "the user
         // wants mouse support" — see `AltScreenOptions`. `screen.ts` must never
@@ -581,7 +612,14 @@ function runInteractive(flags, extras = {}) {
             motion: mouseOn,
             bracketedPaste: pasteOn,
         });
-        const restore = () => screen?.restore();
+        // Input-encoding modes unwind FIRST, for the same reason the mouse
+        // reporting does inside `screen.restore()`: the terminal must stop
+        // sending enhanced encodings before anything else tears the reader
+        // down, or a keystroke taken in that instant survives into the shell.
+        const restore = () => {
+            keyboardEnhancement.restore();
+            screen?.restore();
+        };
         // Four idempotent restore paths (§4.4). The signal hook is NOT redundant:
         //   - `waitUntilExit().then()` is a microtask and may never be reached when
         //     the process is killed;
@@ -948,6 +986,9 @@ const CONFIG_SET_KEYS = new Set([
     // `mouse` records: a key present here but absent there falls through every
     // case, writes nothing, and still prints `Set paste = false`.
     'paste',
+    // Listed here AND cased in the switch below, for the reason the note above
+    // `paste` records.
+    'keyboardEnhancement',
     'scrollResumeMs',
     'historyEnabled',
     'planModeDefault',
@@ -1187,6 +1228,9 @@ function runConfigSetValue(key, value) {
         case 'paste':
             patch.paste = value === 'true' || value === '1';
             break;
+        case 'keyboardEnhancement':
+            patch.keyboardEnhancement = value === 'true' || value === '1';
+            break;
         // Clamped rather than rejected, for the same reason `planModeDefault` below
         // records: hardening only the READ path leaves a bad value on disk that
         // reverts to the default on every launch, which presents as "my setting
@@ -1451,6 +1495,9 @@ function buildProgram() {
         // silence, and silently overriding a stored `false` on every run.
         .option('--paste', 'Collapse large pastes into a placeholder (the default)')
         .option('--no-paste', 'Treat pasted bytes as keystrokes (pre-0.6.3 behavior)')
+        // Same persisted-defaults-true trap as `--paste` above.
+        .option('--keyboard-enhancement', 'Make Shift+Enter insert a newline (the default where the terminal can)')
+        .option('--no-keyboard-enhancement', 'Never push keyboard-enhancement modes (Shift+Enter then needs a terminal binding)')
         .option('--no-exit-transcript', 'Do not replay the session summary after exiting')
         .option('--plan', 'Start the session in PLAN mode (read-only research + review)')
         .option('--no-plan', 'Start the session in BUILD mode (overrides planModeDefault)')

package/dist/commands/builtins.js

@@ -1054,55 +1054,53 @@ const COMMANDS = [
     },
     {
         name: 'terminal-setup',
-        description: 'How to make Shift+Enter send a newline in your terminal',
+        description: 'How Shift+Enter sends a newline in your terminal',
         run: (ctx) => {
-            // READ-ONLY BY DESIGN (3.6): pushing kitty keyboard mode or
-            // modifyOtherKeys=2 would re-encode EVERY modified key as CSI-u and
-            // blind Ink's parser for the whole session. One user-side binding
-            // reaches the same result for the one key that needs it.
-            //
-            // Ctrl+J and Alt+Enter work with no setup at all; CSI-u terminals
-            // (kitty / WezTerm / foot with keyboard enhancement on) need none
-            // either. The lines below are for the terminals that send a plain
-            // CR for Shift+Enter and CAN be configured.
+            // THE APP NOW PUSHES THE MODES ITSELF (shift-enter-newline fix):
+            // win32-input-mode on Windows, kitty disambiguate + modifyOtherKeys=2
+            // elsewhere, each translated back to legacy bytes before Ink parses
+            // them. The lines below cover the terminals where pushing is not
+            // enough: macOS Terminal.app and conhost under an old Node publish no
+            // keyboard-enhancement protocol at all, and a terminal that ignores
+            // the push still sends a plain CR for Shift+Enter.
             const lines = [
                 'Shift+Enter newline - terminal setup',
                 '',
-                'Ctrl+J inserts a newline when delivered; Alt+Enter may be intercepted.',
-                'To get a dedicated Shift+Enter key, make the terminal send',
-                'the CSI-u sequence \\u001b[13;2u for it:',
+                'This app asks the terminal to report modified keys itself:',
+                '  Windows: win32-input-mode (conhost and Windows Terminal)',
+                '  macOS/Linux: kitty disambiguate + modifyOtherKeys (iTerm2,',
+                '    kitty, ghostty, WezTerm, foot, Alacritty)',
+                'A terminal that implements none of these sends a plain CR for',
+                'Shift+Enter, indistinguishable from Enter. There Ctrl+J inserts a',
+                'newline with no setup, and Alt+Enter may also work.',
+                '',
+                'If your terminal can be configured, make Shift+Enter send the',
+                'CSI-u sequence \\u001b[13;2u and it works even without the push:',
                 '',
                 '  Windows Terminal settings.json, merge root-level arrays:',
                 '    "copyOnSelect": false,',
                 '    "actions": [{ "id": "User.AragonNewline", "command":',
                 '      { "action": "sendInput", "input": "\\u001b[13;2u" } }],',
                 '    "keybindings": [{ "keys": "shift+enter", "id": "User.AragonNewline" }]',
-                '    PowerShell runs inside the terminal; configure this binding in',
-                '    Windows Terminal, not in the PowerShell profile. If both keys',
-                '    send CR, the application cannot distinguish Shift+Enter from Enter.',
                 '  VS Code terminal  keybindings.json:',
                 '    { "key": "shift+enter",',
                 '      "command": "workbench.action.terminal.sendSequence",',
                 '      "when": "terminalFocus",',
                 '      "args": { "text": "\\u001b[13;2u" } }',
-                '    User settings: "terminal.integrated.copyOnSelection": false',
                 '  iTerm2            Settings > Profiles > Keys > Key Mappings:',
                 '    Shift+Enter -> Send Escape Sequence: [13;2u',
                 '  kitty/WezTerm/foot  native once keyboard enhancement is on',
                 '    (kitty: map shift+enter send_text all \\u001b[13;2u)',
                 '  Alacritty         alacritty.toml, [keyboard] bindings:',
                 '    { key = "Enter", mods = "Shift", chars = "\\u001b[13;2u" }',
-                '  macOS Terminal.app / conhost  cannot rebind Enter; use Ctrl+J',
-                '    or Alt+Enter',
+                '  macOS Terminal.app / old conhost  cannot rebind Enter; use Ctrl+J',
                 '',
+                'Windows needs Node >= 22.17 (or >= 24.2): older versions never',
+                'turn on virtual-terminal input, so no report can arrive.',
+                'Opt out of the push entirely:',
+                '  aragon config set keyboardEnhancement false',
+                '  --no-keyboard-enhancement / ARAGON_KEYBOARD_ENHANCEMENT=0',
                 'This command only prints advice; it changes no terminal modes.',
-                'Host selections (Shift+drag or /mouse off) belong to the terminal.',
-                'App selections wait for Ctrl+C; only a native tool exit confirms copying.',
-                'SSH uses OSC 52: the terminal may deny it; sent does not mean confirmed.',
-                'Without the stdin filter, Delete falls back to Backspace.',
-                'Without paste support, multiline paste cannot be guaranteed safe.',
-                'IME confirmation has no composition signal in PTY bytes. If it emits CR,',
-                'edit externally and use bracketed paste; this host combination needs validation.',
             ];
             ctx.notify('info', lines.join('\n'));
         },

package/dist/compaction/context-command.js

@@ -74,7 +74,9 @@ function occupancyLine(usage) {
     return `${pct}   ${formatTokens(usage.occupied)} of ${formatTokens(usage.window)}   ${breakdown}`;
 }
 /**
- * Where the denominator came from. THREE SOURCES, ALL NAMED.
+ * Where the denominator came from. FOUR SOURCES, ALL NAMED - the fourth
+ * being the user's own model-windows.json, which exists precisely because
+ * the other three cannot know a gateway alias released last week.
  *
  * THE PLACEHOLDER BRANCH IS THE ONE THAT MATTERS. `buildRuntimeModel` returns a
  * flat 128000 for any model the static table has never seen - a custom
@@ -85,11 +87,20 @@ function occupancyLine(usage) {
  */
 function windowLine(usage) {
     if (usage.windowOverridden) {
-        return `${usage.window}   from contextWindow configuration (overrides API and model table)`;
+        return `${usage.window}   from contextWindow configuration (overrides API, model table, and model-windows.json)`;
     }
     if (!usage.windowKnown) {
         return (`UNKNOWN - no verified model limit; internal fallback budget ${usage.window}; ` +
-            'set contextWindow to correct it');
+            'set contextWindow or list the model in model-windows.json to correct it');
+    }
+    if (usage.windowSource === 'user') {
+        return `${usage.window}   from model-windows.json (your per-model table)`;
+    }
+    if (usage.windowSource === undefined) {
+        // A child agent can be windowKnown through the pricing-table heuristic
+        // without naming a source; claiming 'the model table' there would be an
+        // evidence-free assertion in the one report that exists to be checked.
+        return `${usage.window}   source unverified`;
     }
     return `${usage.window}   from ${usage.windowSource === 'api' ? 'the model API' : 'the model table'}`;
 }

package/dist/compaction/types.d.ts

@@ -65,7 +65,12 @@ export interface CompactionDecision {
     deltaTokens: number;
 }
 export interface Pressure {
-    windowSource?: 'api' | 'catalog' | 'fallback';
+    /**
+     * `user` means the CLI's model-windows.json supplied the denominator - a
+     * hand-typed window for a model no table knows. It outranks `api` and
+     * `catalog` in `getModelInfoFor` precisely because the user asserted it.
+     */
+    windowSource?: 'api' | 'catalog' | 'fallback' | 'user';
     occupied: number;
     contextWindow: number;
     /** `occupied / contextWindow`, clamped to [0, 1]. */

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(),