@aragon-agent/cli 0.5.8 → 0.5.10

package/dist/ui/overlays/SettingsScreen.d.ts

@@ -9,6 +9,7 @@
  */
 import React from 'react';
 import { type ThinkingLevel } from '@aragon-agent/core';
+import { type FastConfig } from '../../config/schema.js';
 import { type LogLevelName } from '../../logging/levels.js';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
@@ -17,6 +18,22 @@ export interface SettingsValues {
     model: string;
     baseUrl: string;
     thinkingLevel: ThinkingLevel;
+    /**
+     * Whether the transcript draws the reasoning (agent-activity-presentation
+     * §4.3). `'on' | 'off'` rather than a boolean because this screen edits an
+     * enum row and reads it back as one; `App` converts at both ends.
+     */
+    showThinking: 'on' | 'off';
+    /**
+     * Whether a running tool card draws a live output tail
+     * (agent-activity-presentation-live §4.1). `'on' | 'off'` for the reason its
+     * neighbour records: this screen edits an enum row and reads it back as one.
+     *
+     * PERSIST-ONLY, unlike `showThinking`. The store is allocated in
+     * `AgentController`'s constructor and there is no setter, so this row takes
+     * effect on the next launch -- which is also what manual row 8 asks for.
+     */
+    liveToolOutput: 'on' | 'off';
     maxTokens: string;
     apiKey: string;
     /**
@@ -25,6 +42,21 @@ export interface SettingsValues {
      * credentials on disk cannot be flipped by a stray arrow key.
      */
     logLevel: LogLevelName;
+    /**
+     * The fast tier (fast-model-tier §4.5, extended by the hardening round §4.4).
+     *
+     * FIVE ROWS, and only the first is always meaningful — the other four
+     * describe a tier that may not be on. They are `string` rather than their
+     * config types because this screen edits TEXT: `fastReview` accepts a number
+     * or `off`, and a typo must change nothing rather than resolve to a default
+     * (the discipline `maxTokens` already follows here).
+     */
+    fastEnabled: 'on' | 'off';
+    fastModel: string;
+    fastProvider: string;
+    fastReview: string;
+    /** The session review budget. `fastReview` is the PACE, this is the TOTAL. */
+    fastReviewBudget: string;
 }
 interface SettingsScreenProps {
     initial: SettingsValues;
@@ -39,7 +71,56 @@ interface SettingsScreenProps {
     theme: Theme;
     caps: TermCapabilities;
     onSave: (values: SettingsValues) => void;
+    /**
+     * `API retries` READ-ONLY row (llm-api-retry-backoff §6.9), e.g. `10` or `off`.
+     *
+     * A STRING FROM `App`, NOT A `SettingsValues` FIELD, and that distinction is the
+     * whole design: `SettingsValues` is what Enter WRITES, and routing retry through
+     * it would mean nine more editable rows (or one row whose Enter silently
+     * rewrote a section it does not own). `/retry` is the discoverable control;
+     * this row exists so "is it on, and how many" is answerable without leaving the
+     * screen. Absent = omit the row entirely.
+     */
+    retrySummary?: string;
 }
+/**
+ * The derived, non-editable line under the five fast rows — the sibling of
+ * `effectiveCapLine`, and it exists for the same reason (§4.5).
+ *
+ * A SETTINGS SCREEN THAT LETS A USER SWITCH A TIER ON AND GIVES NO SIGNAL THAT
+ * IT CANNOT RESOLVE is the failure `effectiveCapLine` was added to fix for
+ * `maxTokens`, one screen later. `keyFor` is the same resolver the controller
+ * uses, so this line and the runtime cannot disagree.
+ *
+ * IT DOES NOT TAKE `fastReviewBudget` AND MUST NOT (§4.4 part 5): this line
+ * describes what the tier IS, not what it is allowed to spend.
+ */
+export declare function fastTierLine(values: Pick<SettingsValues, 'provider' | 'fastEnabled' | 'fastModel' | 'fastProvider' | 'fastReview'>, hasKey: (providerId: string) => boolean): string;
+/**
+ * The five editable fast rows, as a config patch (§4.5 / hardening §4.4).
+ *
+ * PURE AND EXPORTED so `App`'s save handler holds no parsing of its own, and so
+ * the round trip `fastSettingsFrom(config)` -> edit -> `readFastSettings` can be
+ * tested without a terminal.
+ *
+ * A TYPO IN `fastReview` CHANGES NOTHING — the `review` / `reviewEveryTurns`
+ * keys are simply omitted from the patch, so `clampFastConfig`'s merge keeps
+ * whatever was there. That is the `Max tokens` discipline this screen already
+ * follows, and the alternative (resolving a typo to the default) silently
+ * discards the cadence the user actually set. `fastReviewBudget` follows the
+ * same rule; an out-of-range NUMBER is passed through to `clampFastConfig`'s
+ * `REVIEW_SESSION_RANGE` rather than being validated a second time here, so a
+ * row edit and a hand-edited `config.json` land on the same value.
+ */
+export declare function readFastSettings(values: Pick<SettingsValues, 'fastEnabled' | 'fastModel' | 'fastProvider' | 'fastReview' | 'fastReviewBudget'>): Partial<FastConfig>;
+/**
+ * The inverse: seed the five rows from a resolved config.
+ *
+ * OMITTING A KEY HERE IS THE SILENT HALF OF ADDING A ROW (§4.4 part 4): the row
+ * renders empty, `readFastSettings` sees an unparseable value, and an untouched
+ * save writes the clamp's default over whatever the user had.
+ */
+export declare function fastSettingsFrom(fast: FastConfig): Pick<SettingsValues, 'fastEnabled' | 'fastModel' | 'fastProvider' | 'fastReview' | 'fastReviewBudget'>;
 /**
  * The cap this setting will ACTUALLY produce against the selected model.
  *
@@ -51,5 +132,5 @@ interface SettingsScreenProps {
  * "I set 64000 but answers still stop early" has no answer anywhere in the UI.
  */
 export declare function effectiveCapLine(values: Pick<SettingsValues, 'provider' | 'model' | 'maxTokens'>): string;
-export declare function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }: SettingsScreenProps): React.ReactElement;
+export declare function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, retrySummary, }: SettingsScreenProps): React.ReactElement;
 export {};

package/dist/ui/overlays/SettingsScreen.js

@@ -15,12 +15,137 @@ import { ADAPTER_PROVIDERS, THINKING_LEVELS, maskSecret, parseMaxTokensInput, }
 import { LOG_LEVEL_NAMES } from '../../logging/levels.js';
 import { pickGlyphs } from '../glyphs.js';
 import { OverlayFrame } from '../layout/OverlayFrame.js';
+const SHOW_THINKING_OPTIONS = ['off', 'on'];
+const LIVE_OUTPUT_OPTIONS = ['off', 'on'];
+const FAST_ENABLED_OPTIONS = ['off', 'on'];
+/**
+ * `(inherit)` IS THE EMPTY STRING, rendered as a word.
+ *
+ * An empty enum cell would read as "unset and therefore broken"; the truth is
+ * that an empty `fast.provider` INHERITS the main provider, which is the setting
+ * most users want and the one they should not have to type (§3.2 rule 2).
+ */
+const FAST_INHERIT_PROVIDER = '(inherit)';
+const FAST_PROVIDER_OPTIONS = [FAST_INHERIT_PROVIDER, ...ADAPTER_PROVIDERS];
+/**
+ * The derived, non-editable line under the five fast rows — the sibling of
+ * `effectiveCapLine`, and it exists for the same reason (§4.5).
+ *
+ * A SETTINGS SCREEN THAT LETS A USER SWITCH A TIER ON AND GIVES NO SIGNAL THAT
+ * IT CANNOT RESOLVE is the failure `effectiveCapLine` was added to fix for
+ * `maxTokens`, one screen later. `keyFor` is the same resolver the controller
+ * uses, so this line and the runtime cannot disagree.
+ *
+ * IT DOES NOT TAKE `fastReviewBudget` AND MUST NOT (§4.4 part 5): this line
+ * describes what the tier IS, not what it is allowed to spend.
+ */
+export function fastTierLine(values, hasKey) {
+    if (values.fastEnabled !== 'on')
+        return 'Fast tier: off';
+    const model = values.fastModel.trim();
+    if (model.length === 0)
+        return 'Fast tier: off  (fast.model is not set)';
+    const provider = values.fastProvider === FAST_INHERIT_PROVIDER || values.fastProvider.trim().length === 0
+        ? values.provider
+        : values.fastProvider;
+    if (!hasKey(provider)) {
+        return `Fast tier: ${provider}:${model}  (no API key for ${provider} - the tier will stay off)`;
+    }
+    const review = values.fastReview.trim().toLowerCase();
+    const cadence = review === 'off'
+        ? 'review off'
+        : /^\d+$/.test(review)
+            ? `review every ${review} turns`
+            : 'review every 5 turns';
+    return `Fast tier: ${provider}:${model}  (key set)  ${cadence}`;
+}
+/**
+ * The five editable fast rows, as a config patch (§4.5 / hardening §4.4).
+ *
+ * PURE AND EXPORTED so `App`'s save handler holds no parsing of its own, and so
+ * the round trip `fastSettingsFrom(config)` -> edit -> `readFastSettings` can be
+ * tested without a terminal.
+ *
+ * A TYPO IN `fastReview` CHANGES NOTHING — the `review` / `reviewEveryTurns`
+ * keys are simply omitted from the patch, so `clampFastConfig`'s merge keeps
+ * whatever was there. That is the `Max tokens` discipline this screen already
+ * follows, and the alternative (resolving a typo to the default) silently
+ * discards the cadence the user actually set. `fastReviewBudget` follows the
+ * same rule; an out-of-range NUMBER is passed through to `clampFastConfig`'s
+ * `REVIEW_SESSION_RANGE` rather than being validated a second time here, so a
+ * row edit and a hand-edited `config.json` land on the same value.
+ */
+export function readFastSettings(values) {
+    const review = values.fastReview.trim().toLowerCase();
+    const parsed = /^\d+$/.test(review) ? Number.parseInt(review, 10) : Number.NaN;
+    const budget = values.fastReviewBudget.trim();
+    const parsedBudget = /^\d+$/.test(budget) ? Number.parseInt(budget, 10) : Number.NaN;
+    return {
+        enabled: values.fastEnabled === 'on',
+        model: values.fastModel.trim(),
+        provider: values.fastProvider === FAST_INHERIT_PROVIDER ? '' : values.fastProvider.trim(),
+        ...(review === 'off' ? { review: false } : {}),
+        ...(Number.isFinite(parsed) && parsed > 0
+            ? { review: true, reviewEveryTurns: parsed }
+            : {}),
+        ...(Number.isFinite(parsedBudget) ? { reviewMaxPerSession: parsedBudget } : {}),
+    };
+}
+/**
+ * The inverse: seed the five rows from a resolved config.
+ *
+ * OMITTING A KEY HERE IS THE SILENT HALF OF ADDING A ROW (§4.4 part 4): the row
+ * renders empty, `readFastSettings` sees an unparseable value, and an untouched
+ * save writes the clamp's default over whatever the user had.
+ */
+export function fastSettingsFrom(fast) {
+    return {
+        fastEnabled: fast.enabled ? 'on' : 'off',
+        fastModel: fast.model,
+        fastProvider: fast.provider.trim().length > 0 ? fast.provider : FAST_INHERIT_PROVIDER,
+        fastReview: fast.review ? String(fast.reviewEveryTurns) : 'off',
+        fastReviewBudget: String(fast.reviewMaxPerSession),
+    };
+}
 const FIELDS = [
     { key: 'provider', label: 'Provider', kind: 'enum', options: ADAPTER_PROVIDERS },
     { key: 'model', label: 'Model', kind: 'text' },
     { key: 'baseUrl', label: 'Base URL', kind: 'text' },
     { key: 'thinkingLevel', label: 'Thinking', kind: 'enum', options: THINKING_LEVELS },
+    // Directly under `Thinking`, so the effort setting and the display setting are
+    // read together. `Show thinking` is 13 characters, inside the 18-column label
+    // budget `.padEnd(18)` enforces below and that IF-H7 records as silently
+    // overflowing.
+    { key: 'showThinking', label: 'Show thinking', kind: 'enum', options: SHOW_THINKING_OPTIONS },
+    // Beside `Show thinking`, because the two are the transcript's only display
+    // switches. `Live output` is 11 characters, inside the 18-column label budget
+    // `.padEnd(18)` enforces below and that IF-H7 records as silently overflowing.
+    { key: 'liveToolOutput', label: 'Live output', kind: 'enum', options: LIVE_OUTPUT_OPTIONS },
     { key: 'maxTokens', label: 'Max tokens', kind: 'text' },
+    // The fast tier sits AFTER `Max tokens` and BEFORE `API key`, because the key
+    // row is the one a user scrolls to deliberately and putting five rows past it
+    // would bury it (fast-model-tier §4.5). The rationale survives a fifth row;
+    // the count in it did not.
+    //
+    // `Fast review budget` is a `'text'` row, NOT a new numeric kind (D-H12):
+    // `SettingsRow.kind` is `'enum' | 'text' | 'secret'`, and `Max tokens` and
+    // `Fast review` are both bounded numbers already living as text plus an
+    // adapter parse. A fourth kind for one row would be a new interaction pattern
+    // in a screen whose whole design is that it edits text.
+    //
+    // ITS LABEL IS SHORT BECAUSE THE LABEL COLUMN IS A BUDGET, NOT A HINT SLOT.
+    // Labels render `.padEnd(18)` below, so one that reaches 18 does not truncate
+    // and does not wrap - it pushes ITS OWN value right (or butts against it at
+    // exactly 18) while every other row's value stays put, and the column stops
+    // being a column. So no `(1-500)` here: no other bounded row carries its range
+    // either (`Max tokens`, `Fast review`), `clampFastConfig` is the enforcement,
+    // and `/fast budget` states the range in the one place a user meets it - when
+    // it refuses a bad one. The name matches that command for the same reason.
+    { key: 'fastEnabled', label: 'Fast tier', kind: 'enum', options: FAST_ENABLED_OPTIONS },
+    { key: 'fastModel', label: 'Fast model', kind: 'text' },
+    { key: 'fastProvider', label: 'Fast provider', kind: 'enum', options: FAST_PROVIDER_OPTIONS },
+    { key: 'fastReview', label: 'Fast review', kind: 'text' },
+    { key: 'fastReviewBudget', label: 'Fast budget', kind: 'text' },
     { key: 'apiKey', label: 'API key', kind: 'secret' },
     { key: 'logLevel', label: 'Log level', kind: 'enum', options: LOG_LEVEL_NAMES },
 ];
@@ -52,7 +177,7 @@ export function effectiveCapLine(values) {
         return `Effective: ${resolution.value}  (auto)`;
     return `Effective: ${resolution.value}`;
 }
-export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }) {
+export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, retrySummary, }) {
     const [values, setValues] = useState(initial);
     const [index, setIndex] = useState(0);
     const glyphs = pickGlyphs(caps);
@@ -132,6 +257,15 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
         // setting, which is the one thing this field can never be.
         if (f.key === 'maxTokens' && raw.length === 0)
             return 'auto';
+        // `(not set)` and NOT `(same as main)`, which is the honest reading of §3.2
+        // rule 3: an empty `fast.model` does not inherit, it means the tier is
+        // unconfigured. `(same as main)` is a fact the derived line below states
+        // when the value literally equals the main model — never a placeholder.
+        if (f.key === 'fastModel' && raw.length === 0) {
+            return selected ? '(type a model id)' : '(not set)';
+        }
+        if (f.key === 'fastReview' && raw.length === 0)
+            return 'every 5 turns';
         return raw.length > 0 ? raw : selected ? '(type to set)' : '(none)';
     };
     // One element per row, each `wrap="truncate"` — the contract for OverlayFrame's
@@ -145,6 +279,18 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
     // controlled mode slices by ELEMENT, so a row that wraps desynchronises the
     // position indicator.
     rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: effectiveCapLine(values) }, "__effective"));
+    rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: fastTierLine(values, (id) => (apiKeys[id] ?? '').length > 0) }, "__fast"));
+    /**
+     * ONE ROW, NOT NINE (llm-api-retry-backoff §6.9).
+     *
+     * READ-ONLY, and deliberately so: the nine `retry.*` keys belong to `config set`
+     * and `config.json`, and a settings screen that exposed a jitter checkbox is a
+     * settings screen nobody reads. What a user needs HERE is the answer to "is it
+     * on, and how many" — the discoverable control is `/retry`, which this row names.
+     */
+    if (retrySummary) {
+        rows.push(_jsxs(Text, { wrap: "truncate", color: theme.muted, children: ['  ', 'API retries'.padEnd(18), retrySummary] }, "__retry"));
+    }
     rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: "Enter saves. Keys persist to the config file (0600)." }, "__save"));
     return (_jsx(OverlayFrame, { title: "Settings", hint: `${glyphs.arrowUp}${glyphs.arrowDown} field ${glyphs.midDot} ${glyphs.arrowLeft}${glyphs.arrowRight} change ${glyphs.midDot} Enter save ${glyphs.midDot} Esc close`, maxRows: maxRows, cols: cols, rows: rows, scrollOffset: scrollOffset, onScrollClamp: onScrollClamp, theme: theme, caps: caps }));
 }

package/dist/ui/transcript-text.js

@@ -7,6 +7,7 @@
  * simply print everything twice.
  */
 import { formatCost, formatDuration, formatTokens } from '../agent/usage.js';
+import { formatRetryLine } from '../agent/retry-view.js';
 const DEFAULT_MAX_ENTRIES = 200;
 const CONTINUATION_INDENT = '  ';
 const TOOL_INDENT = '  ';
@@ -84,6 +85,32 @@ function renderEntry(entry, glyphs) {
             ];
             return lines;
         }
+        case 'retry': {
+            // A turn that spent three minutes retrying is exactly the kind of cost an
+            // exported transcript is supposed to account for — the same argument the
+            // `team` case above makes in its own words. This file's `default: return []`
+            // means the addition is a CHOICE rather than a compile requirement, and it is
+            // worth making: without it a replay of a session that lost two minutes to a
+            // 529 shows a gap and no reason for it.
+            const glyph = entry.phase === 'exhausted' ? glyphs.error : glyphs.retry;
+            return [
+                `${TOOL_INDENT}${glyph} ${formatRetryLine(entry, glyphs, Date.now())}`,
+            ];
+        }
+        case 'fast': {
+            // Reviews are real spend and real advice, and an exported transcript that
+            // omitted them would be unaccountable for both — the argument the `team`
+            // and `retry` cases above each make in their own words.
+            const glyph = entry.status === 'failed' ? glyphs.toolError : glyphs.toolDone;
+            const duration = entry.durationMs === undefined ? '' : ` (${entry.durationMs}ms)`;
+            const head = `${TOOL_INDENT}${glyph} fast review #${entry.reviewIndex} ${entry.model} ` +
+                `turn ${entry.turn}${duration}`;
+            if (entry.status === 'advice' && entry.text) {
+                return [head, ...entry.text.split('\n').map((l) => `${TOOL_INDENT}${CONTINUATION_INDENT}${l}`)];
+            }
+            const detail = entry.detail ? `: ${entry.detail}` : '';
+            return [`${head} ${entry.status}${detail}`];
+        }
         case 'notice': {
             const glyph = entry.level === 'error'
                 ? glyphs.error

package/dist/ui/use-wheel-routing.d.ts

@@ -1,31 +1,26 @@
 /**
- * Wheel routing (mouse-wheel-region-routing §4.6 / §4.7).
+ * Wheel routing (wheel-scrolls-transcript-only §4.1).
  *
- * Subscribes to the mouse source, turns each wheel notch into a band via
- * `hitTestWheel`, and dispatches it to the transcript, an open overlay, or the
- * prompt-history stepper. Lives outside `App.tsx` because that file is exactly
- * at the 1000-line ceiling `CLAUDE.md` sets, and because the routing table is
- * the most testable part of this feature and does not want to be inside a
- * 1000-line component (D-13).
+ * Subscribes to the mouse source and dispatches every notch to THE ONE
+ * SCROLLABLE REGION ON SCREEN — the transcript, or the controlled overlay
+ * covering it. Lives outside `App.tsx` because the routing table is the most
+ * testable part of this feature and a table wants to be readable on its own,
+ * away from a large component (D-13).
  *
- * THE TWO BANDS HAVE DIFFERENT PHYSICS, and that is the requirement rather than
- * a tuning choice (§4.7). A physical notch produces ONE SGR report, whereas
- * alternate-scroll used to produce three arrow keys:
+ * THE POINTER ROW IS NOT CONSULTED, and that is the requirement rather than a
+ * simplification (§1). A wheel notch is a VIEWPORT gesture: the pointer in a
+ * TUI rests wherever the user last left it — in a chat-shaped app, next to the
+ * thing they type into — so routing by row meant the ordinary "scroll back to
+ * see what the agent just did" gesture landed on the composer and replaced the
+ * draft with an old prompt. Prompt history belongs to `↑` / `↓` alone (G1 / G3),
+ * which is the contract Claude Code, Codex and every full-screen terminal app
+ * the user brings muscle memory from already follow.
  *
- *  - transcript: 3 rows per notch, matching the terminal's own convention and
- *    the muscle memory users bring from every other full-screen app;
- *  - composer: exactly ONE history step per notch. Multiplying here would make
- *    a single flick jump three prompts back — unusable, and destructive when a
- *    draft is in play.
- *
- * Bursts are handled differently for the same reason: transcript events are
- * coalesced into one intent carrying `repeat`, composer events never are (they
- * are rate-limited by the human, and each must produce its own visible step).
+ * Every notch is coalesced into one intent carrying `repeat`, no matter how fast
+ * the wheel spins: one gesture, one `setState`, one render.
  */
-import { type MutableRefObject } from 'react';
 import type { Overlay } from '../agent/reducer.js';
 import type { MouseSource } from '../input/stdin-mouse-filter.js';
-import { type FrameGeometry } from './layout/regions.js';
 import type { ScrollIntent } from './layout/scroll.js';
 /**
  * Rows a PgUp/PgDn — and a Shift+wheel notch — moves inside a controlled
@@ -37,22 +32,11 @@ export declare const OVERLAY_PAGE = 8;
 export interface WheelRoutingOptions {
     /** Absent when mouse support is off, in inline mode, or on a non-TTY. */
     mouseSource?: MouseSource;
-    /** Live frame geometry, written by `AppShell`'s layout effect (§4.5). */
-    geometryRef: MutableRefObject<FrameGeometry>;
-    /**
-     * Test-only seam (§8.2): when set, the router reads this instead of the
-     * measured ref, so a routing test never depends on `measureElement` working
-     * under `ink-testing-library` — a dependency no other test in this package
-     * exercises, and one that would make a routing regression present as a
-     * measurement flake.
-     */
-    geometryOverride?: FrameGeometry;
     /** Read at EVENT time for the routing branch, and again at FLUSH time (P1-3). */
     getOverlay: () => Overlay | null;
     onScroll: (kind: ScrollIntent, repeat: number) => void;
     /** Signed row delta; the caller clamps at 0 the way the keyboard branch does. */
     onOverlayScroll: (delta: number) => void;
-    onHistoryStep: (dir: 'up' | 'down') => void;
 }
 export interface WheelRouting {
     /**

package/dist/ui/use-wheel-routing.js

@@ -1,29 +1,25 @@
 /**
- * Wheel routing (mouse-wheel-region-routing §4.6 / §4.7).
+ * Wheel routing (wheel-scrolls-transcript-only §4.1).
  *
- * Subscribes to the mouse source, turns each wheel notch into a band via
- * `hitTestWheel`, and dispatches it to the transcript, an open overlay, or the
- * prompt-history stepper. Lives outside `App.tsx` because that file is exactly
- * at the 1000-line ceiling `CLAUDE.md` sets, and because the routing table is
- * the most testable part of this feature and does not want to be inside a
- * 1000-line component (D-13).
+ * Subscribes to the mouse source and dispatches every notch to THE ONE
+ * SCROLLABLE REGION ON SCREEN — the transcript, or the controlled overlay
+ * covering it. Lives outside `App.tsx` because the routing table is the most
+ * testable part of this feature and a table wants to be readable on its own,
+ * away from a large component (D-13).
  *
- * THE TWO BANDS HAVE DIFFERENT PHYSICS, and that is the requirement rather than
- * a tuning choice (§4.7). A physical notch produces ONE SGR report, whereas
- * alternate-scroll used to produce three arrow keys:
+ * THE POINTER ROW IS NOT CONSULTED, and that is the requirement rather than a
+ * simplification (§1). A wheel notch is a VIEWPORT gesture: the pointer in a
+ * TUI rests wherever the user last left it — in a chat-shaped app, next to the
+ * thing they type into — so routing by row meant the ordinary "scroll back to
+ * see what the agent just did" gesture landed on the composer and replaced the
+ * draft with an old prompt. Prompt history belongs to `↑` / `↓` alone (G1 / G3),
+ * which is the contract Claude Code, Codex and every full-screen terminal app
+ * the user brings muscle memory from already follow.
  *
- *  - transcript: 3 rows per notch, matching the terminal's own convention and
- *    the muscle memory users bring from every other full-screen app;
- *  - composer: exactly ONE history step per notch. Multiplying here would make
- *    a single flick jump three prompts back — unusable, and destructive when a
- *    draft is in play.
- *
- * Bursts are handled differently for the same reason: transcript events are
- * coalesced into one intent carrying `repeat`, composer events never are (they
- * are rate-limited by the human, and each must produce its own visible step).
+ * Every notch is coalesced into one intent carrying `repeat`, no matter how fast
+ * the wheel spins: one gesture, one `setState`, one render.
  */
 import { useCallback, useEffect, useRef } from 'react';
-import { hitTestWheel } from './layout/regions.js';
 /**
  * Rows a PgUp/PgDn — and a Shift+wheel notch — moves inside a controlled
  * overlay. Declared here rather than in `App.tsx` because both the keyboard
@@ -89,42 +85,29 @@ export function useWheelRouting(options) {
     }, [flush]);
     const route = useCallback((event) => {
         const current = optionsRef.current;
-        const geometry = current.geometryOverride ?? current.geometryRef.current;
-        const band = hitTestWheel(event.y, geometry);
         const overlay = current.getOverlay();
-        // THE OVERLAY BRANCH IS EVALUATED FIRST AND RETURNS FOR EVERY BAND IT
+        // THE OVERLAY BRANCH IS EVALUATED FIRST AND RETURNS FOR EVERY OVERLAY IT
         // RECOGNIZES — the same two ordering rules the keyboard handler follows,
         // and for the same reason (R-P1-7).
         if (overlay) {
-            // The composer is inactive behind an overlay; stepping a hidden draft
-            // is worse than doing nothing.
-            if (band !== 'content')
-                return;
             // Modes A only. `model` / `confirm` / `question` own their own keys and
             // scrolling them would leave an inconsistent cursor (R-11).
             const controlled = overlay === 'help' || overlay === 'settings' || overlay === 'plan';
             if (!controlled)
                 return;
+            // D-3: the row is not consulted here either. Behind an overlay the
+            // composer is inactive and the overlay is the only scrollable thing on
+            // screen, so a notch anywhere scrolls it.
             const step = event.shift ? OVERLAY_PAGE : OVERLAY_LINES_PER_NOTCH;
             current.onOverlayScroll(event.dir === 'up' ? -step : step);
             return;
         }
-        if (band === 'composer') {
-            // §4.7: the accumulator flushes when the BAND changes, not only when
-            // the direction does. The composer path is never coalesced, so without
-            // this the transcript scroll that preceded the pointer moving down
-            // lands ~16 ms AFTER the history step it happened before — the two
-            // halves of one gesture, applied out of order.
-            flush();
-            current.onHistoryStep(event.dir);
-            return;
-        }
         if (event.shift) {
             accumulate(event.dir === 'up' ? 'pageUp' : 'pageDown', 1);
             return;
         }
         accumulate(event.dir === 'up' ? 'lineUp' : 'lineDown', CONTENT_LINES_PER_NOTCH);
-    }, [accumulate, flush]);
+    }, [accumulate]);
     const { mouseSource } = options;
     useEffect(() => {
         if (!mouseSource)

package/dist/update/classify-failure.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Turning a tail of npm output into a reason (cli-auto-update-hardening H2 /
+ * section 5.3).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * PURE, AND THE ONLY IMPORT IS A TYPE. The interesting half of H2 is not this
+ * table, it is the REPORTING rule that decides which of the resulting reasons
+ * may break the three-strike silence - and that lives in `types.ts` beside
+ * `shouldRenderUpdateLine`, as `IMMEDIATE_NOTICE_REASONS`.
+ *
+ * WHY THIS EXISTS AT ALL. The one line a user is ever allowed to see on the
+ * failure path reads `update failed <dot> npm i -g @aragon-agent/cli` for EVERY
+ * cause. For `EPERM` / `EBUSY` - the Windows self-replacement case, R-3 - that
+ * advice hits the same held handle and fails identically, so the single visible
+ * failure is also a wrong instruction.
+ */
+import type { UpdateReason } from './types.js';
+/**
+ * Classify an install failure from the bounded stderr tail `runNpmInstall`
+ * already returns.
+ *
+ * ONE PARAMETER, NOT TWO. An earlier draft took `exitCode` and never read it:
+ * npm exits `1` for every one of these, so the code carries no information the
+ * tail does not, and a parameter that no branch and no test consumes is a
+ * maintenance liability that reads like a promise (P2-2).
+ *
+ * An absent or unrecognised tail is `install-failed` - the pre-H2 behaviour, so
+ * a machine whose npm says something we have never seen degrades to exactly what
+ * it did before rather than to a confident wrong answer.
+ */
+export declare function classifyInstallFailure(tail: string | undefined): UpdateReason;

package/dist/update/classify-failure.js

@@ -0,0 +1,60 @@
+/**
+ * Turning a tail of npm output into a reason (cli-auto-update-hardening H2 /
+ * section 5.3).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * PURE, AND THE ONLY IMPORT IS A TYPE. The interesting half of H2 is not this
+ * table, it is the REPORTING rule that decides which of the resulting reasons
+ * may break the three-strike silence - and that lives in `types.ts` beside
+ * `shouldRenderUpdateLine`, as `IMMEDIATE_NOTICE_REASONS`.
+ *
+ * WHY THIS EXISTS AT ALL. The one line a user is ever allowed to see on the
+ * failure path reads `update failed <dot> npm i -g @aragon-agent/cli` for EVERY
+ * cause. For `EPERM` / `EBUSY` - the Windows self-replacement case, R-3 - that
+ * advice hits the same held handle and fails identically, so the single visible
+ * failure is also a wrong instruction.
+ */
+/**
+ * FIRST MATCH WINS, AND THE ORDER IS NOT ALPHABETICAL.
+ *
+ * `EPERM` is tested before `EACCES` because npm's Windows output frequently
+ * carries BOTH - the `EPERM` on the shim rename plus an `EACCES` from a retry -
+ * and the actionable one is the first. `network` is last because "proxy" and
+ * "network" appear inside unrelated npm advisory text often enough that an
+ * earlier position would swallow the three specific cases above it.
+ */
+const TABLE = [
+    [
+        /\bEPERM\b|\bEBUSY\b|\bETXTBSY\b|operation not permitted|resource busy or locked/i,
+        'blocked-by-os',
+    ],
+    [/\bEACCES\b|permission denied/i, 'not-writable'],
+    [/\bENOSPC\b|no space left/i, 'no-space'],
+    [
+        /\bENOTFOUND\b|\bEAI_AGAIN\b|\bECONNRESET\b|\bETIMEDOUT\b|network|proxy|tunneling socket/i,
+        'network',
+    ],
+];
+/**
+ * Classify an install failure from the bounded stderr tail `runNpmInstall`
+ * already returns.
+ *
+ * ONE PARAMETER, NOT TWO. An earlier draft took `exitCode` and never read it:
+ * npm exits `1` for every one of these, so the code carries no information the
+ * tail does not, and a parameter that no branch and no test consumes is a
+ * maintenance liability that reads like a promise (P2-2).
+ *
+ * An absent or unrecognised tail is `install-failed` - the pre-H2 behaviour, so
+ * a machine whose npm says something we have never seen degrades to exactly what
+ * it did before rather than to a confident wrong answer.
+ */
+export function classifyInstallFailure(tail) {
+    if (!tail)
+        return 'install-failed';
+    for (const [re, reason] of TABLE) {
+        if (re.test(tail))
+            return reason;
+    }
+    return 'install-failed';
+}