@aragon-agent/cli 0.5.6 → 0.5.9

package/dist/ui/render-governor.js

@@ -0,0 +1,78 @@
+/**
+ * Adaptive render governor (tui-render-performance L4 / R7). Pure, React-free.
+ *
+ * Neither the streaming coalescer nor Ink adapts when a frame overruns its
+ * budget: the coalescer keeps its 33 ms timer, Ink keeps its 32 ms throttle, and
+ * the event loop saturates. Renders then queue behind each other on Node's
+ * single thread and KEYSTROKES QUEUE BEHIND THE RENDERS — which is what turns a
+ * slow frame into an unresponsive terminal.
+ *
+ * The ladder is the safety net under L1/L2/L3, not a substitute for them: it
+ * cannot make a frame cheaper, only rarer. Its job is to turn any residual
+ * pathology from a freeze into a visibly slower but still interactive UI.
+ *
+ * I-L4-1 — the governor changes only HOW OFTEN the view updates. Never what is
+ * dispatched, never the order, never the final state. `mergeDeltas` already
+ * guarantees that a longer window is simply a larger merge and that any
+ * non-delta action flushes the pending run first, so the same event sequence
+ * must produce the same final `ViewState` at every rung
+ * (`render-governor.test.ts`).
+ */
+/** Coalescing intervals, in ms. Rung 0 is the pre-feature `COALESCE_MS`. */
+export const GOVERNOR_LADDER = [33, 50, 80, 125, 200, 320];
+/** Step up when a commit costs more than this fraction of the current interval. */
+export const GOVERNOR_UP_RATIO = 0.7;
+/**
+ * Consecutive cheap frames required before stepping back down.
+ *
+ * Hysteresis, and it has to be asymmetric: stepping up on one expensive frame
+ * and down on one cheap one would oscillate through the whole ladder while a
+ * long answer streams past a couple of code blocks.
+ */
+export const GOVERNOR_DOWN_STREAK = 8;
+export function initialGovernor() {
+    return { rung: 0, cheapStreak: 0 };
+}
+/** Highest rung reachable under `maxIntervalMs`. Always at least 0. */
+function topRung(maxIntervalMs) {
+    let top = 0;
+    for (let i = 1; i < GOVERNOR_LADDER.length; i += 1) {
+        if (GOVERNOR_LADDER[i] <= maxIntervalMs)
+            top = i;
+    }
+    return top;
+}
+/**
+ * The coalescing interval for a state.
+ *
+ * Clamped to `maxIntervalMs` in BOTH directions: `maxRenderIntervalMs = 33`
+ * flattens the ladder to one rung, which is the documented way to get the
+ * pre-feature cadence without reaching for the kill switch.
+ */
+export function intervalOf(state, maxIntervalMs) {
+    const ceiling = Number.isFinite(maxIntervalMs) ? maxIntervalMs : GOVERNOR_LADDER[0];
+    const rung = Math.min(Math.max(0, Math.floor(state.rung)), topRung(ceiling));
+    return Math.min(ceiling, GOVERNOR_LADDER[rung] ?? GOVERNOR_LADDER[0]);
+}
+/**
+ * Fold one commit's cost into the ladder.
+ *
+ * `lastCommitMs` covers React reconciliation AND Ink's yoga layout, because Ink
+ * computes layout in `onRender`, which React runs before layout effects. It does
+ * NOT cover Ink's serialisation and the stdout write, which happen after. In
+ * practice layout dominates, and the ladder's job is DIRECTION, not accuracy.
+ */
+export function stepGovernor(state, lastCommitMs, maxIntervalMs) {
+    const top = topRung(Number.isFinite(maxIntervalMs) ? maxIntervalMs : GOVERNOR_LADDER[0]);
+    const rung = Math.min(Math.max(0, Math.floor(state.rung)), top);
+    const interval = intervalOf({ rung, cheapStreak: state.cheapStreak }, maxIntervalMs);
+    const cost = Number.isFinite(lastCommitMs) ? lastCommitMs : 0;
+    if (cost > interval * GOVERNOR_UP_RATIO) {
+        return { rung: Math.min(top, rung + 1), cheapStreak: 0 };
+    }
+    const streak = state.cheapStreak + 1;
+    if (streak >= GOVERNOR_DOWN_STREAK) {
+        return { rung: Math.max(0, rung - 1), cheapStreak: 0 };
+    }
+    return { rung, cheapStreak: streak };
+}

package/dist/ui/transcript-text.d.ts

@@ -22,6 +22,17 @@ export interface TranscriptTextOptions {
     elapsedMs: number;
     /** Entries beyond this count collapse into a single "… N omitted" line. */
     maxEntries?: number;
+    /**
+     * Entries the retain ring already removed from `ViewState`
+     * (tui-render-performance L1 / K-6).
+     *
+     * A DIFFERENT LOSS FROM `maxEntries`, and both have to be reported: that one
+     * omits the middle of a transcript this replay still holds in full, while this
+     * one names entries the process no longer has. A replay that silently starts
+     * mid-session is exactly the failure the retain ring would otherwise
+     * introduce.
+     */
+    droppedEntries?: number;
 }
 /** Render the whole session (summary line + entries) as plain text. */
 export declare function renderTranscriptText(entries: Entry[], opts: TranscriptTextOptions): string;

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
@@ -111,6 +138,11 @@ export function renderTranscriptText(entries, opts) {
     ].join(` ${g.midDot} `);
     const max = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
     const lines = [summary];
+    const dropped = opts.droppedEntries ?? 0;
+    if (dropped > 0) {
+        lines.push(`${g.ellipsis} ${dropped} earlier ${dropped === 1 ? 'entry' : 'entries'} dropped by ` +
+            `transcriptRetain ${g.midDot} raise it or /save sooner`);
+    }
     if (entries.length > max && max > 1) {
         const head = Math.ceil(max / 2);
         const tail = max - head;

package/dist/ui/use-height-store.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The transcript height cache (tui-render-performance L3).
+ *
+ * Virtualisation needs a height for entries it is NOT mounting. Measured
+ * heights are authoritative; entries that have never been on screen fall back to
+ * `estimateEntryRows`, and both are memoised on the same `heightKey` so a
+ * `cols` change or a content change invalidates them together (V-5).
+ *
+ * THE MAP LIVES IN A REF, NOT IN STATE, and the version counter is bumped at
+ * most once per frame through a microtask and ONLY when a value actually
+ * changed. K-2 is the failure this shape exists to prevent: a naive
+ * measure -> setState -> re-measure store never converges, and the symptom is a
+ * hung terminal rather than an error. In steady state — settled entries at a
+ * fixed width — this produces zero extra renders.
+ */
+import { type HeightKey } from './layout/virtual-window.js';
+export interface HeightStoreStats {
+    measured: number;
+    estimated: number;
+}
+export interface HeightStore {
+    /** Bumped at most once per frame, and only when a measurement changed. */
+    version: number;
+    /** Measured rows, else the memoised estimate, computing it once if needed. */
+    resolve: (key: HeightKey, estimate: () => number) => number;
+    /** Called from `MeasuredEntry`'s layout effect. Idempotent per (key, value). */
+    report: (key: HeightKey, rows: number) => void;
+    stats: () => HeightStoreStats;
+    clear: () => void;
+}
+export declare function useHeightStore(): HeightStore;

package/dist/ui/use-height-store.js

@@ -0,0 +1,76 @@
+/**
+ * The transcript height cache (tui-render-performance L3).
+ *
+ * Virtualisation needs a height for entries it is NOT mounting. Measured
+ * heights are authoritative; entries that have never been on screen fall back to
+ * `estimateEntryRows`, and both are memoised on the same `heightKey` so a
+ * `cols` change or a content change invalidates them together (V-5).
+ *
+ * THE MAP LIVES IN A REF, NOT IN STATE, and the version counter is bumped at
+ * most once per frame through a microtask and ONLY when a value actually
+ * changed. K-2 is the failure this shape exists to prevent: a naive
+ * measure -> setState -> re-measure store never converges, and the symptom is a
+ * hung terminal rather than an error. In steady state — settled entries at a
+ * fixed width — this produces zero extra renders.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { VIRTUAL_LIMITS } from './layout/virtual-window.js';
+/** Drop the oldest keys once a map passes the ceiling (insertion-ordered LRU). */
+function trim(map) {
+    while (map.size > VIRTUAL_LIMITS.heightEntries) {
+        const oldest = map.keys().next();
+        if (oldest.done)
+            break;
+        map.delete(oldest.value);
+    }
+}
+export function useHeightStore() {
+    const measured = useRef(new Map());
+    const estimated = useRef(new Map());
+    const [version, setVersion] = useState(0);
+    const scheduled = useRef(false);
+    const mounted = useRef(true);
+    useEffect(() => () => {
+        mounted.current = false;
+    }, []);
+    const report = useCallback((key, rows) => {
+        const value = Number.isFinite(rows) && rows > 0 ? Math.floor(rows) : 0;
+        if (value <= 0)
+            return;
+        if (measured.current.get(key) === value)
+            return;
+        measured.current.set(key, value);
+        trim(measured.current);
+        // An estimate that has been superseded is dead weight; dropping it here is
+        // what keeps `stats()` honest for `/perf`.
+        estimated.current.delete(key);
+        if (scheduled.current)
+            return;
+        scheduled.current = true;
+        queueMicrotask(() => {
+            scheduled.current = false;
+            if (mounted.current)
+                setVersion((v) => v + 1);
+        });
+    }, []);
+    const resolve = useCallback((key, estimate) => {
+        const hit = measured.current.get(key);
+        if (hit !== undefined)
+            return hit;
+        const cached = estimated.current.get(key);
+        if (cached !== undefined)
+            return cached;
+        const value = Math.max(1, Math.floor(estimate()));
+        estimated.current.set(key, value);
+        trim(estimated.current);
+        return value;
+    }, []);
+    const stats = useCallback(() => ({ measured: measured.current.size, estimated: estimated.current.size }), []);
+    const clear = useCallback(() => {
+        measured.current.clear();
+        estimated.current.clear();
+        if (mounted.current)
+            setVersion((v) => v + 1);
+    }, []);
+    return { version, resolve, report, stats, clear };
+}

package/dist/ui/use-render-governor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Commit-cost timing for the render governor (tui-render-performance L4).
+ *
+ * `performance.now()` is taken at the TOP of the `App` render body (this hook
+ * must therefore be called early, before any other work) and again in a layout
+ * effect. Ink computes yoga layout in `onRender`, which React runs BEFORE layout
+ * effects, so that span covers React reconciliation AND the Ink layout pass —
+ * the same mechanism `ScrollViewport.tsx:87-88` and `AppShell.tsx:100-102`
+ * already document and rely on.
+ *
+ * ONLY THE RUNG IS REACT STATE. The measured cost and the resolved interval live
+ * in refs: putting a millisecond count in state would re-render the whole tree
+ * on every frame to record how expensive rendering the whole tree was.
+ */
+export interface RenderGovernorOptions {
+    /** `false` pins rung 0 forever (`--no-render-governor`, `ARAGON_RENDER_GOVERNOR=0`). */
+    enabled: boolean;
+    /** Ceiling of the ladder; `33` flattens it. */
+    maxIntervalMs: number;
+}
+export interface RenderGovernorHandle {
+    /**
+     * The coalescing interval to arm the next flush timer with.
+     *
+     * A REF, read at `setTimeout` time. The coalescer's callbacks are `useCallback`d
+     * with stable deps and must stay that way (the controller subscription effect
+     * never re-runs), so a plain value would be pinned to the mount render.
+     */
+    intervalMs: {
+        current: number;
+    };
+    /** Rendered as the `eco` chip when > 0 (I-L4-2). */
+    rung: number;
+    /** Most recent commit cost in ms, for `/perf`. Not state. */
+    lastCommitMs: () => number;
+    /** `/perf reset` — back to rung 0. */
+    reset: () => void;
+}
+export declare function useRenderGovernor(opts: RenderGovernorOptions): RenderGovernorHandle;

package/dist/ui/use-render-governor.js

@@ -0,0 +1,57 @@
+/**
+ * Commit-cost timing for the render governor (tui-render-performance L4).
+ *
+ * `performance.now()` is taken at the TOP of the `App` render body (this hook
+ * must therefore be called early, before any other work) and again in a layout
+ * effect. Ink computes yoga layout in `onRender`, which React runs BEFORE layout
+ * effects, so that span covers React reconciliation AND the Ink layout pass —
+ * the same mechanism `ScrollViewport.tsx:87-88` and `AppShell.tsx:100-102`
+ * already document and rely on.
+ *
+ * ONLY THE RUNG IS REACT STATE. The measured cost and the resolved interval live
+ * in refs: putting a millisecond count in state would re-render the whole tree
+ * on every frame to record how expensive rendering the whole tree was.
+ */
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { performance } from 'node:perf_hooks';
+import { GOVERNOR_LADDER, initialGovernor, intervalOf, stepGovernor, } from './render-governor.js';
+export function useRenderGovernor(opts) {
+    const { enabled, maxIntervalMs } = opts;
+    const stateRef = useRef(initialGovernor());
+    const intervalMs = useRef(GOVERNOR_LADDER[0]);
+    const lastCommit = useRef(0);
+    const startedAt = useRef(0);
+    const mounted = useRef(true);
+    const [rung, setRung] = useState(0);
+    // Stamped during render, which is the whole point of calling this hook first.
+    startedAt.current = performance.now();
+    useEffect(() => () => {
+        mounted.current = false;
+    }, []);
+    useLayoutEffect(() => {
+        const cost = performance.now() - startedAt.current;
+        lastCommit.current = cost;
+        if (!enabled) {
+            stateRef.current = initialGovernor();
+            intervalMs.current = Math.min(maxIntervalMs, GOVERNOR_LADDER[0]);
+            if (rung !== 0)
+                setRung(0);
+            return;
+        }
+        const next = stepGovernor(stateRef.current, cost, maxIntervalMs);
+        stateRef.current = next;
+        intervalMs.current = intervalOf(next, maxIntervalMs);
+        // React bails out when the value is unchanged, so this is a no-op on every
+        // frame that did not move the ladder — which is almost all of them.
+        if (mounted.current && next.rung !== rung)
+            setRung(next.rung);
+    });
+    const reset = useCallback(() => {
+        stateRef.current = initialGovernor();
+        intervalMs.current = Math.min(maxIntervalMs, GOVERNOR_LADDER[0]);
+        if (mounted.current)
+            setRung(0);
+    }, [maxIntervalMs]);
+    const lastCommitMs = useCallback(() => lastCommit.current, []);
+    return { intervalMs, rung, lastCommitMs, reset };
+}

package/dist/ui/use-startup-notices.d.ts

@@ -12,6 +12,14 @@
  * not otherwise see — rather than belonging to the view.
  */
 import type { ViewAction } from '../agent/reducer.js';
+/**
+ * `{ requested, resolved }` when the raise happened, `undefined` otherwise —
+ * i.e. `cfg.transcriptRetainRequested` and `cfg.transcriptRetain`.
+ */
+export interface RetainNoticeOptions {
+    requested: number;
+    resolved: number;
+}
 export interface MouseNoticeOptions {
     /**
      * Whether reporting is ACTUALLY in effect — i.e. a filter was installed, not
@@ -22,4 +30,4 @@ export interface MouseNoticeOptions {
     /** Record that it was shown (`state.json`). Called once, after dispatch. */
     onSeen: () => void;
 }
-export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions): void;
+export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions, retainNotice?: RetainNoticeOptions): void;

package/dist/ui/use-startup-notices.js

@@ -25,7 +25,21 @@ import { getLogger } from '../logging/logger.js';
  */
 const MOUSE_SELECTION_NOTICE = 'Mouse wheel scrolls the transcript. Hold Shift to select text, ' +
     'or turn it off with `aragon config set mouse false`.';
-export function useStartupNotices(dispatch, mouseNotice) {
+/**
+ * The §5.1 notice (tui-render-performance). Shown once per run, and only when
+ * the user's own `transcriptRetain` was below `transcriptWindow`.
+ *
+ * The raise itself is not negotiable — retaining fewer entries than the horizon
+ * can scroll to makes part of that horizon permanently unreachable — but doing
+ * it in silence would leave a user staring at a `/perf` line that disagrees with
+ * the number in their own config file and no way to connect the two.
+ */
+function retainRaisedNotice(requested, resolved) {
+    return (`transcriptRetain ${requested} is below transcriptWindow ${resolved}; using ${resolved} ` +
+        'so the whole scroll horizon stays reachable. Lower transcriptWindow too if you meant ' +
+        'to cap memory.');
+}
+export function useStartupNotices(dispatch, mouseNotice, retainNotice) {
     // The sink gives up after repeated write failures (a read-only log directory,
     // a full disk). Silently logging nothing is exactly the state a user must not
     // discover later, from an empty file, while trying to explain a bug.
@@ -62,4 +76,24 @@ export function useStartupNotices(dispatch, mouseNotice) {
         dispatch({ type: 'notice', level: 'info', text: MOUSE_SELECTION_NOTICE });
         noticeRef.current?.onSeen();
     }, [mouseEnabled, dispatch]);
+    // A `warn` notice rather than a toast: it is about a value the user typed, so
+    // it belongs in the transcript where it can be scrolled back to, not in a row
+    // that expires. DEPENDS ON THE TWO SCALARS, never on the options object —
+    // `App` builds that literal during render, and depending on it would re-run
+    // this effect on every frame of the session.
+    const retainRequested = retainNotice?.requested;
+    const retainResolved = retainNotice?.resolved;
+    const retainNoticeShown = useRef(false);
+    useEffect(() => {
+        if (retainRequested === undefined || retainResolved === undefined)
+            return;
+        if (retainNoticeShown.current)
+            return;
+        retainNoticeShown.current = true;
+        dispatch({
+            type: 'notice',
+            level: 'warn',
+            text: retainRaisedNotice(retainRequested, retainResolved),
+        });
+    }, [retainRequested, retainResolved, dispatch]);
 }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.5.6",
+  "version": "0.5.9",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -52,7 +52,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.6",
+    "@aragon-agent/core": "^0.2.9",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",