@aragon-agent/cli 0.5.1 → 0.5.3

package/dist/ui/layout/regions.js

@@ -0,0 +1,52 @@
+/**
+ * Wheel band hit-testing (mouse-wheel-region-routing §4.5) — pure, React-free.
+ *
+ * The requirement is stated in terms of REGIONS ("scrolling over the agent area
+ * scrolls the transcript; scrolling over the input box steps prompt history"),
+ * so the router needs to turn a reported terminal row into one of two bands.
+ *
+ * The boundary is MEASURED, never computed from `budget.ts`. That arithmetic
+ * describes the PLANNED chrome, but the real bottom chrome grows and shrinks at
+ * run time: the toast row comes and goes, the hint row is dropped below
+ * `HINT_MIN_ROWS`, and the autocomplete popup adds up to nine rows. Routing off
+ * the plan would put the boundary in the wrong place exactly when the popup is
+ * open — the moment precision matters most (D-5 / D-16).
+ */
+/**
+ * The "I do not know where the frame is" value.
+ *
+ * `App` writes it into the geometry ref on every render path that does NOT
+ * render the full-screen `AppShell` — the terminal-too-small placeholder and
+ * inline mode — so a stale measurement can never outlive the frame it
+ * described. There is deliberately no arithmetic fallback: an unmeasured frame
+ * routes to `'content'`, which is the band that cannot destroy anything, and
+ * one invisible frame after a resize is a better failure than a wrong band
+ * (§4.5, P1-5 / D-16).
+ */
+export const UNMEASURED_GEOMETRY = { top: 1, height: 0, bottom: 0 };
+/**
+ * Which band does terminal row `y` belong to?
+ *
+ * Fails toward `'content'`: the whole point of this feature is that a wheel
+ * notch must never edit the user's draft (I-3), so every degenerate input —
+ * nothing measured yet, a row outside the frame, a chrome measurement that
+ * swallowed the screen — resolves to the harmless direction.
+ */
+export function hitTestWheel(y, geometry) {
+    const { top, height } = geometry;
+    if (!Number.isFinite(height) || height <= 0)
+        return 'content';
+    if (!Number.isFinite(y))
+        return 'content';
+    // Clamp into the frame so the one undrawn bottom row — and any off-by-one
+    // from a terminal that reports 0-based rows — lands on a real band instead of
+    // being dropped.
+    const row = Math.min(Math.max(Math.floor(y), top), top + height - 1);
+    // I-6: at least one content row always survives. This clamp is a backstop
+    // that should never fire, and that is checkable rather than hopeful: the
+    // completion popup is capped at `viewportRows(rows) - 4`, so the measured
+    // chrome tops out at `rows - 6` against a frame of `rows - 1` — five content
+    // rows survive the worst case the layout can produce.
+    const bottom = Math.min(Math.max(Math.floor(geometry.bottom) || 0, 0), height - 1);
+    return row >= top + height - bottom ? 'composer' : 'content';
+}

package/dist/ui/layout/scroll-indicator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Scroll-thumb geometry (mouse-wheel-region-routing §4.8) — pure, React-free.
+ *
+ * Wheel scrolling without a position indicator is a half-finished affordance:
+ * the user learns THAT they moved but not HOW FAR or how much is left. The
+ * status bar's `↑N` answers neither.
+ *
+ * OFFSET COUNTS FROM THE BOTTOM, exactly as `scroll.ts` documents — `0` is
+ * pinned to the newest output and `overflow` is parked at the very top. The
+ * rows hidden ABOVE are therefore `overflow - offset`, and that inversion is
+ * precisely what gets done by accident, so it is computed here once and named.
+ */
+export interface ThumbRange {
+    /** 0-based row of the thumb's first row, within the viewport. */
+    start: number;
+    /** Thumb height in rows; always >= 1 when a range is returned. */
+    size: number;
+}
+/**
+ * Where the thumb sits, or `null` when the content fits and there is nothing to
+ * indicate.
+ *
+ * `size` never rounds to zero: a 10-row window over a 5000-row transcript still
+ * gets a one-row thumb, because an indicator that vanishes at exactly the
+ * moment the transcript is longest is worse than no indicator at all.
+ */
+export declare function thumbRange(viewportRows: number, contentRows: number, offsetFromBottom: number): ThumbRange | null;

package/dist/ui/layout/scroll-indicator.js

@@ -0,0 +1,35 @@
+/**
+ * Scroll-thumb geometry (mouse-wheel-region-routing §4.8) — pure, React-free.
+ *
+ * Wheel scrolling without a position indicator is a half-finished affordance:
+ * the user learns THAT they moved but not HOW FAR or how much is left. The
+ * status bar's `↑N` answers neither.
+ *
+ * OFFSET COUNTS FROM THE BOTTOM, exactly as `scroll.ts` documents — `0` is
+ * pinned to the newest output and `overflow` is parked at the very top. The
+ * rows hidden ABOVE are therefore `overflow - offset`, and that inversion is
+ * precisely what gets done by accident, so it is computed here once and named.
+ */
+/**
+ * Where the thumb sits, or `null` when the content fits and there is nothing to
+ * indicate.
+ *
+ * `size` never rounds to zero: a 10-row window over a 5000-row transcript still
+ * gets a one-row thumb, because an indicator that vanishes at exactly the
+ * moment the transcript is longest is worse than no indicator at all.
+ */
+export function thumbRange(viewportRows, contentRows, offsetFromBottom) {
+    const viewport = Math.floor(viewportRows);
+    const content = Math.floor(contentRows);
+    if (!Number.isFinite(viewport) || !Number.isFinite(content))
+        return null;
+    if (viewport <= 0 || content <= viewport)
+        return null;
+    const overflow = content - viewport;
+    const offset = Math.min(Math.max(Math.floor(offsetFromBottom) || 0, 0), overflow);
+    const size = Math.min(viewport, Math.max(1, Math.round((viewport * viewport) / content)));
+    const travel = viewport - size;
+    const hiddenAbove = overflow - offset;
+    const start = travel <= 0 ? 0 : Math.round((hiddenAbove / overflow) * travel);
+    return { start: Math.min(Math.max(start, 0), travel), size };
+}

package/dist/ui/layout/scroll.d.ts

@@ -26,3 +26,12 @@ export declare function clampScroll(offset: number, overflowLines: number): numb
 export declare function pageSize(viewportHeight: number): number;
 export declare function isPinnedToBottom(state: ScrollState): boolean;
 export declare function applyScroll(state: ScrollState, intent: ScrollIntent, metrics: ViewportMetrics): ScrollState;
+/**
+ * Fold `applyScroll` `times` times — one `setState`, one render, however fast
+ * the wheel spins (mouse-wheel-region-routing §5.5).
+ *
+ * Folding rather than multiplying is deliberate: `applyScroll` owns the
+ * downward bottom-snap and the clamp, and reimplementing either here would give
+ * the wheel a different notion of "pinned to the bottom" than the keyboard has.
+ */
+export declare function applyScrollTimes(state: ScrollState, intent: ScrollIntent, metrics: ViewportMetrics, times: number): ScrollState;

package/dist/ui/layout/scroll.js

@@ -74,3 +74,26 @@ export function applyScroll(state, intent, metrics) {
     }
     return { offset: clamped };
 }
+/**
+ * Upper bound on one folded burst. `repeat` arrives from the wheel router's
+ * coalescing window, and an unbounded fold is a free CPU-burn primitive for a
+ * high-resolution / free-spinning wheel (R-10).
+ */
+const MAX_SCROLL_REPEAT = 100;
+/**
+ * Fold `applyScroll` `times` times — one `setState`, one render, however fast
+ * the wheel spins (mouse-wheel-region-routing §5.5).
+ *
+ * Folding rather than multiplying is deliberate: `applyScroll` owns the
+ * downward bottom-snap and the clamp, and reimplementing either here would give
+ * the wheel a different notion of "pinned to the bottom" than the keyboard has.
+ */
+export function applyScrollTimes(state, intent, metrics, times) {
+    const n = Number.isFinite(times)
+        ? Math.min(MAX_SCROLL_REPEAT, Math.max(1, Math.floor(times)))
+        : 1;
+    let next = state;
+    for (let i = 0; i < n; i += 1)
+        next = applyScroll(next, intent, metrics);
+    return next;
+}

package/dist/ui/overlays/HelpOverlay.js

@@ -13,6 +13,8 @@ function keyRows(times) {
         ['Ctrl+T', 'Toggle thinking blocks'],
         ['PgUp / PgDn', 'Scroll a page (transcript, or this overlay)'],
         ['Shift+Up / Shift+Down', 'Scroll the transcript a line (full-screen mode)'],
+        ['Wheel', 'Scroll the transcript (over the input box: prompt history)'],
+        ['Shift+Wheel', 'Scroll the transcript a page'],
         ['Up / Down', 'Prompt history (empty input)'],
     ];
 }
@@ -23,6 +25,7 @@ const COMMANDS = [
     ['/plan [on|off|status]', 'Toggle plan mode (same as Shift+Tab)'],
     ['/theme <name>', 'auto | warm | cool | light'],
     ['/thinking <level>', 'Set thinking level'],
+    ['/team [on|off|max n]', 'Team subagents: status, switch, fan-out width'],
     ['/tools', 'List active tools'],
     ['/clear', 'Clear the visible transcript'],
     ['/reset', 'New conversation'],
@@ -51,6 +54,14 @@ const PLAN_ROWS = [
     ['submit_plan', 'The agent submits a plan: a approve, r revise, Esc dismiss'],
     ['--plan / --no-plan', 'Start a session in a given mode (also ARAGON_PLAN=1)'],
 ];
+const TEAM_ROWS = [
+    ['task', 'The tool the agent uses to run 2-5 subagents in parallel'],
+    ['/team', 'Status: on/off, max subagents, and the live roster'],
+    ['/team on | off', 'Switch team mode for this session (and save it)'],
+    ['/team max <n>', 'Fan-out width, 1-10 (5 by default)'],
+    ['--team / --no-team', 'Start a session with team mode on or off (also ARAGON_TEAM=0)'],
+    ['team_send / team_wait', 'How subagents message each other; 6 each, one every 15s'],
+];
 /** Build the overlay's rows. Exported so `app.test.tsx` can count them. */
 export function helpRows(theme, caps) {
     const glyphs = pickGlyphs(caps);
@@ -66,6 +77,9 @@ export function helpRows(theme, caps) {
     rows.push(section('Plan mode'));
     for (const [c, d] of PLAN_ROWS)
         rows.push(pair(c, d));
+    rows.push(section('Team subagents'));
+    for (const [c, d] of TEAM_ROWS)
+        rows.push(pair(c, d));
     rows.push(section('Skills'));
     for (const [c, d] of SKILL_ROWS)
         rows.push(pair(c, d));

package/dist/ui/screen.d.ts

@@ -15,11 +15,24 @@ export interface ScreenHandle {
     /** Leave the alternate screen. Idempotent — safe from every exit path. */
     restore(): void;
 }
+export interface AltScreenOptions {
+    /**
+     * TRUE MEANS "A MOUSE FILTER IS ALREADY INSTALLED", NOT "THE USER WANTS MOUSE
+     * SUPPORT" (invariant I-8).
+     *
+     * This module must never derive the value from config, env or platform.
+     * Enabling reporting without a filter in front of Ink does not degrade the
+     * feature — it types `[<0;12;5M` into the user's message on every click and
+     * every notch, which is strictly worse than the bug the feature fixes. The
+     * only caller is `cli.tsx::runInteractive`, and it passes `filter !== null`.
+     */
+    readonly mouse: boolean;
+}
 /**
  * Enter the alternate screen. A non-TTY stdout is a hard no-op (tests, pipes,
  * CI) — writing screen-control sequences into a redirected file corrupts it.
  */
-export declare function enterAltScreen(stdout: NodeJS.WriteStream | undefined): ScreenHandle;
+export declare function enterAltScreen(stdout: NodeJS.WriteStream | undefined, options?: AltScreenOptions): ScreenHandle;
 /**
  * Replay the session summary into the normal buffer after `restore()`, so the
  * conversation does not evaporate along with the alternate screen.

package/dist/ui/screen.js

@@ -17,6 +17,32 @@ const CURSOR_HOME = '\x1b[H';
 const CLEAR_VISIBLE = '\x1b[2J';
 /** Ink's log-update hides the cursor; a signal kill never gives it back. */
 const SHOW_CURSOR = '\x1b[?25h';
+/**
+ * `?1000` is NORMAL TRACKING (press / release), the minimum mode that reports
+ * wheel buttons; `?1006` selects SGR encoding so coordinates arrive as decimal
+ * text rather than raw bytes above 0x7F that `setEncoding('utf8')` would
+ * mangle. Motion tracking (`?1002` / `?1003`) is deliberately NOT enabled: it
+ * floods stdin on every pointer move and buys nothing this feature uses.
+ */
+const ENABLE_MOUSE = '\x1b[?1000h\x1b[?1006h';
+const DISABLE_MOUSE = '\x1b[?1006l\x1b[?1000l';
+/**
+ * Alternate scroll (DEC private mode 1007) is what turns a wheel notch into a
+ * burst of arrow keys, which `PromptInput` reads as prompt-history recall. With
+ * mouse reporting ON we do not touch it at all: 1007 is defined to translate
+ * the wheel only while no application is tracking the mouse, so `?1000h`
+ * already suppresses it and a second mutation of shared state buys nothing.
+ *
+ * With mouse reporting OFF we turn it off so the wheel is INERT rather than
+ * destructive — the fallback rung of the fail-safe ladder. But 1007 is GLOBAL
+ * TERMINAL STATE THIS APP DOES NOT OWN, so it is SAVED and RESTORED (XTSAVE /
+ * XTRESTORE) rather than force-set on the way out: a user who deliberately
+ * disabled alternate scroll in their terminal config must not have it switched
+ * back on by running `aragon --no-mouse` once. A terminal implementing neither
+ * sequence ignores both, so the fallback is no worse than writing nothing.
+ */
+const SAVE_ALT_SCROLL_OFF = '\x1b[?1007s\x1b[?1007l';
+const RESTORE_ALT_SCROLL = '\x1b[?1007r';
 const NOOP_HANDLE = { restore() { } };
 function safeWrite(stdout, data) {
     try {
@@ -30,17 +56,25 @@ function safeWrite(stdout, data) {
  * Enter the alternate screen. A non-TTY stdout is a hard no-op (tests, pipes,
  * CI) — writing screen-control sequences into a redirected file corrupts it.
  */
-export function enterAltScreen(stdout) {
+export function enterAltScreen(stdout, options = { mouse: false }) {
     if (!stdout || !stdout.isTTY || typeof stdout.write !== 'function')
         return NOOP_HANDLE;
-    safeWrite(stdout, ENTER_ALT + CLEAR_VISIBLE + CURSOR_HOME);
+    const mouse = options.mouse === true;
+    safeWrite(stdout, ENTER_ALT + CLEAR_VISIBLE + CURSOR_HOME + (mouse ? ENABLE_MOUSE : SAVE_ALT_SCROLL_OFF));
     let restored = false;
     return {
         restore() {
             if (restored)
                 return;
             restored = true;
-            safeWrite(stdout, SHOW_CURSOR + LEAVE_ALT);
+            // Mouse reporting is disabled BEFORE leaving the alternate screen (I-2).
+            // This handle is what all four exit paths converge on — `process.on
+            // ('exit')`, the crash handler's `setScreenRestore`, the signal
+            // terminator, and `waitUntilExit()` — which is why the sequences live
+            // here and not in `App.tsx`, a component that is on none of them.
+            // Leaving reporting on prints `[<0;12;5M` in the user's shell on every
+            // click, forever, until they run `reset`.
+            safeWrite(stdout, (mouse ? DISABLE_MOUSE : RESTORE_ALT_SCROLL) + SHOW_CURSOR + LEAVE_ALT);
         },
     };
 }

package/dist/ui/transcript-text.js

@@ -64,6 +64,26 @@ function renderEntry(entry, glyphs) {
             const duration = entry.durationMs === undefined ? '' : ` (${entry.durationMs}ms)`;
             return [`${TOOL_INDENT}${glyph} ${entry.label || entry.name}${args ? ` ${args}` : ''}${duration}`];
         }
+        case 'team': {
+            // Same rows as `TeamCard`, without colour (team-subagents §6.3). A
+            // dispatch is often the most expensive thing in a session, so leaving it
+            // out of the plain-text replay would make the exported transcript
+            // unaccountable for most of its own cost.
+            const ok = entry.runs.filter((r) => r.phase === 'done' && !r.error).length;
+            const failed = entry.runs.length - ok;
+            const head = entry.active || (entry.aborted && entry.durationMs === undefined)
+                ? 'interrupted'
+                : `${entry.durationMs ?? 0}ms (${ok} ok, ${failed} failed)`;
+            const lines = [
+                `${TOOL_INDENT}team ${entry.runs.length} subagents ${head}`,
+                ...entry.runs.map((run) => {
+                    const glyph = run.phase === 'done' && !run.error ? glyphs.toolDone : glyphs.toolError;
+                    const detail = run.error ? ` ${run.error}` : '';
+                    return `${TOOL_INDENT}${CONTINUATION_INDENT}${glyph} ${run.label} ${run.description}${detail}`;
+                }),
+            ];
+            return lines;
+        }
         case 'notice': {
             const glyph = entry.level === 'error'
                 ? glyphs.error

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

@@ -12,4 +12,14 @@
  * not otherwise see — rather than belonging to the view.
  */
 import type { ViewAction } from '../agent/reducer.js';
-export declare function useStartupNotices(dispatch: (action: ViewAction) => void): void;
+export interface MouseNoticeOptions {
+    /**
+     * Whether reporting is ACTUALLY in effect — i.e. a filter was installed, not
+     * merely that the config asked for one. A user on a terminal where R-1 fires
+     * must never be given advice about a mode that is not running.
+     */
+    enabled: boolean;
+    /** Record that it was shown (`state.json`). Called once, after dispatch. */
+    onSeen: () => void;
+}
+export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions): void;

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

@@ -11,10 +11,21 @@
  * because these two effects share one job — surfacing a condition the user could
  * not otherwise see — rather than belonging to the view.
  */
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 import { readConfigFile } from '../config/store.js';
+import { getMouseNoticeSeen } from '../config/ui-state.js';
 import { getLogger } from '../logging/logger.js';
-export function useStartupNotices(dispatch) {
+/**
+ * The §6.1 notice (mouse-wheel-region-routing). Shown at most once, ever.
+ *
+ * R-3 is the only part of wheel region routing that reaches users who never
+ * scroll, and it REMOVES a gesture — drag to select — that is used more often
+ * than the one being added. A README is consulted only after the belief
+ * "aragon broke copy/paste" has already formed.
+ */
+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 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.
@@ -35,4 +46,20 @@ export function useStartupNotices(dispatch) {
             text: `Using default settings: could not parse ${parseError}`,
         });
     }, [dispatch]);
+    // A `notice`, not a toast: it lands in the transcript and scrolls away
+    // instead of stealing a row. §6's argument against toasts is about per-notch
+    // chatter and does not extend to a one-shot.
+    const noticeRef = useRef(mouseNotice);
+    noticeRef.current = mouseNotice;
+    const mouseEnabled = mouseNotice?.enabled ?? false;
+    const mouseNoticeShown = useRef(false);
+    useEffect(() => {
+        if (!mouseEnabled || mouseNoticeShown.current)
+            return;
+        if (getMouseNoticeSeen())
+            return;
+        mouseNoticeShown.current = true;
+        dispatch({ type: 'notice', level: 'info', text: MOUSE_SELECTION_NOTICE });
+        noticeRef.current?.onSeen();
+    }, [mouseEnabled, dispatch]);
 }

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

@@ -0,0 +1,68 @@
+/**
+ * Wheel routing (mouse-wheel-region-routing §4.6 / §4.7).
+ *
+ * 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).
+ *
+ * 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:
+ *
+ *  - 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).
+ */
+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
+ * overlay. Declared here rather than in `App.tsx` because both the keyboard
+ * branch and the wheel branch need it and `App` imports this module; the other
+ * direction would be a cycle.
+ */
+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 {
+    /**
+     * Drop any accumulated-but-unflushed transcript scroll.
+     *
+     * Called by `App` from its existing `state.overlay` effect rather than from a
+     * second subscriber to the same transition. This is guard #2 of the pair that
+     * has to ship together (§14 condition 3); guard #1 is the overlay re-check
+     * inside the flush, and guard #3 is `ScrollViewport`'s I-9 mount-skip.
+     */
+    clearCoalescer: () => void;
+}
+export declare function useWheelRouting(options: WheelRoutingOptions): WheelRouting;

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

@@ -0,0 +1,139 @@
+/**
+ * Wheel routing (mouse-wheel-region-routing §4.6 / §4.7).
+ *
+ * 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).
+ *
+ * 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:
+ *
+ *  - 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).
+ */
+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
+ * branch and the wheel branch need it and `App` imports this module; the other
+ * direction would be a cycle.
+ */
+export const OVERLAY_PAGE = 8;
+/** Transcript rows per notch. The terminal's own convention. */
+const CONTENT_LINES_PER_NOTCH = 3;
+/** Overlay rows per notch. Overlay content is short; a page needs Shift. */
+const OVERLAY_LINES_PER_NOTCH = 3;
+/**
+ * Coalescing window for transcript scrolling — one `setState`, one render, no
+ * matter how fast the wheel spins (R-10). Deliberately tighter than the 33 ms
+ * streaming coalescer: this one is in the direct path of a hand gesture.
+ */
+const WHEEL_COALESCE_MS = 16;
+export function useWheelRouting(options) {
+    // Every mutable input reaches the subscription through this ref, so the
+    // effect below subscribes exactly once per `mouseSource` instead of tearing
+    // the listener down and rebuilding it on every parent render.
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const accumulator = useRef(null);
+    const timer = useRef(null);
+    const clearCoalescer = useCallback(() => {
+        if (timer.current) {
+            clearTimeout(timer.current);
+            timer.current = null;
+        }
+        accumulator.current = null;
+    }, []);
+    const flush = useCallback(() => {
+        if (timer.current) {
+            clearTimeout(timer.current);
+            timer.current = null;
+        }
+        const pending = accumulator.current;
+        accumulator.current = null;
+        if (!pending)
+            return;
+        // P1-3: THE DECISION BELONGS AT FLUSH TIME, not at event time, because the
+        // event-time decision is the one that goes stale. `App` swaps
+        // `ScrollViewport` out for an overlay, and 16 ms is more than wide enough
+        // for an agent-raised `confirm` or an `ask_user` to land inside the window
+        // — the intent would then be applied on a component that is not there, and
+        // the transcript would jump by itself when the overlay closed.
+        if (optionsRef.current.getOverlay())
+            return;
+        optionsRef.current.onScroll(pending.kind, pending.repeat);
+    }, []);
+    const accumulate = useCallback((kind, repeat) => {
+        // A fast up-then-down must never cancel itself into a no-op, so a change
+        // of direction (or of granularity) flushes what is already held.
+        if (accumulator.current && accumulator.current.kind !== kind)
+            flush();
+        const held = accumulator.current;
+        accumulator.current = { kind, repeat: (held?.repeat ?? 0) + repeat };
+        if (!timer.current) {
+            timer.current = setTimeout(flush, WHEEL_COALESCE_MS);
+            timer.current.unref?.();
+        }
+    }, [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
+        // 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;
+            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]);
+    const { mouseSource } = options;
+    useEffect(() => {
+        if (!mouseSource)
+            return undefined;
+        const unsubscribe = mouseSource.subscribe(route);
+        return () => {
+            unsubscribe();
+            clearCoalescer();
+        };
+    }, [mouseSource, route, clearCoalescer]);
+    return { clearCoalescer };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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",
@@ -51,7 +51,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.1",
+    "@aragon-agent/core": "^0.2.3",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",