@aragon-agent/cli 0.5.0 → 0.5.2

package/dist/ui/overlays/QuestionOverlay.js

@@ -0,0 +1,193 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * QuestionOverlay — the keyboard-driven multiple-choice wizard `ask_user`
+ * renders (plan-mode §6.5).
+ *
+ * `OverlayFrame` MODE B (self-managed): the content is a small state machine,
+ * not a list of rows, and slicing it by element would be meaningless.
+ *
+ * THE SINGLE HIGHEST-VALUE DECISION HERE is that the recommended option is the
+ * initial highlight for every question, so `Enter Enter Enter` is a correct,
+ * deliberate "use your judgement" path rather than an accident.
+ *
+ * `Esc` IS NOT HANDLED HERE. `App` owns it, and the bridge's `settle()` is the
+ * only place a human request is ever answered. `ConfirmDialog` does the
+ * opposite — both it and `App` call `resolve` — which is harmless there only by
+ * accident of promise semantics, and is not a pattern to copy (R-P12).
+ */
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+/** Which option index each question starts on: the recommended one. */
+function initialCursors(questions) {
+    return questions.map((q) => Math.max(0, q.options.findIndex((o) => o.recommended)));
+}
+function initialSelections(questions) {
+    return questions.map((q) => {
+        const recommended = q.options.findIndex((o) => o.recommended);
+        return new Set(recommended >= 0 ? [recommended] : [0]);
+    });
+}
+export function QuestionOverlay({ questions, maxRows, cols, theme, caps, onSubmit, }) {
+    const glyphs = pickGlyphs(caps);
+    const [step, setStep] = useState(0);
+    const [phase, setPhase] = useState('choosing');
+    const [cursors, setCursors] = useState(() => initialCursors(questions));
+    const [selections, setSelections] = useState(() => initialSelections(questions));
+    const [customs, setCustoms] = useState(() => questions.map(() => ''));
+    const [draft, setDraft] = useState('');
+    const question = questions[Math.min(step, questions.length - 1)];
+    const cursor = cursors[step] ?? 0;
+    const setCursorAt = (index, value) => setCursors((prev) => prev.map((c, i) => (i === index ? value : c)));
+    const setCustomAt = (index, value) => setCustoms((prev) => prev.map((c, i) => (i === index ? value : c)));
+    const toggleAt = (index, option) => setSelections((prev) => prev.map((set, i) => {
+        if (i !== index)
+            return set;
+        const next = new Set(set);
+        if (next.has(option))
+            next.delete(option);
+        else
+            next.add(option);
+        return next;
+    }));
+    const chooseAt = (index, option) => setSelections((prev) => prev.map((set, i) => (i === index ? new Set([option]) : set)));
+    const buildAnswers = () => questions.map((q, i) => {
+        const chosen = [...(selections[i] ?? new Set())].sort((a, b) => a - b);
+        const labels = chosen.map((index) => q.options[index]?.label ?? '').filter((l) => l.length > 0);
+        const pickedOther = chosen.some((index) => q.options[index]?.isOther);
+        return {
+            id: q.id,
+            question: q.question,
+            selected: labels,
+            custom: pickedOther && (customs[i] ?? '').length > 0 ? customs[i] : null,
+        };
+    });
+    const advance = () => {
+        if (step + 1 >= questions.length)
+            setPhase('review');
+        else {
+            setStep(step + 1);
+            setPhase('choosing');
+        }
+    };
+    const goBack = () => {
+        if (step === 0)
+            return; // No-op on the first question, by design.
+        setStep(step - 1);
+        setPhase('choosing');
+    };
+    useInput((input, key) => {
+        // App owns Esc for both new overlays (R-P12). Swallow it here so the
+        // free-text editor below cannot eat the raw escape byte as a character.
+        if (key.escape)
+            return;
+        if (phase === 'review') {
+            if (key.return) {
+                onSubmit(buildAnswers());
+                return;
+            }
+            if (key.leftArrow) {
+                setStep(questions.length - 1);
+                setPhase('choosing');
+            }
+            return;
+        }
+        if (phase === 'typingOther') {
+            if (key.return) {
+                // An empty commit falls back to the recommended option rather than
+                // recording a blank answer: the user pressed Enter, which everywhere
+                // else in this wizard means "accept the sensible default".
+                if (draft.trim().length === 0) {
+                    const recommended = Math.max(0, question.options.findIndex((o) => o.recommended));
+                    chooseAt(step, recommended);
+                    setCursorAt(step, recommended);
+                    setCustomAt(step, '');
+                }
+                else {
+                    setCustomAt(step, draft.trim());
+                }
+                setDraft('');
+                setPhase('choosing');
+                advance();
+                return;
+            }
+            if (key.leftArrow) {
+                setDraft('');
+                setPhase('choosing');
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setDraft(draft.slice(0, -1));
+                return;
+            }
+            if (input && !key.ctrl && !key.meta && !key.tab)
+                setDraft(draft + input);
+            return;
+        }
+        // phase === 'choosing'
+        if (key.upArrow) {
+            setCursorAt(step, (cursor - 1 + question.options.length) % question.options.length);
+            return;
+        }
+        if (key.downArrow) {
+            setCursorAt(step, (cursor + 1) % question.options.length);
+            return;
+        }
+        if (key.leftArrow) {
+            goBack();
+            return;
+        }
+        if (input === ' ' && question.allowMultiple) {
+            toggleAt(step, cursor);
+            return;
+        }
+        if (key.return) {
+            if (question.options[cursor]?.isOther) {
+                chooseAt(step, cursor);
+                setDraft(customs[step] ?? '');
+                setPhase('typingOther');
+                return;
+            }
+            if (!question.allowMultiple)
+                chooseAt(step, cursor);
+            else if (!(selections[step] ?? new Set()).has(cursor))
+                toggleAt(step, cursor);
+            advance();
+        }
+    });
+    const title = phase === 'review' ? 'Review your answers' : 'Clarify the request';
+    const position = phase === 'review' ? '' : `  ${step + 1}/${questions.length}`;
+    const hint = phase === 'typingOther'
+        ? `type your answer ${glyphs.midDot} ${glyphs.enterKey} commit ${glyphs.midDot} ${glyphs.arrowLeft} back ${glyphs.midDot} esc cancel`
+        : phase === 'review'
+            ? `${glyphs.enterKey} submit ${glyphs.midDot} ${glyphs.arrowLeft} back ${glyphs.midDot} esc cancel`
+            : `${glyphs.arrowUp}${glyphs.arrowDown} choose ${glyphs.midDot} ${glyphs.enterKey} next${question.allowMultiple ? ` ${glyphs.midDot} space toggle` : ''} ${glyphs.midDot} ${glyphs.arrowLeft} back ${glyphs.midDot} esc cancel`;
+    return (_jsx(OverlayFrame, { title: `${title}${position}`, hint: hint, maxRows: maxRows, cols: cols, theme: theme, caps: caps, children: phase === 'review' ? (_jsx(ReviewBody, { questions: questions, answers: buildAnswers(), theme: theme })) : (_jsx(QuestionBody, { question: question, cursor: cursor, selected: selections[step] ?? new Set(), typing: phase === 'typingOther', draft: draft, theme: theme, caps: caps })) }));
+}
+/**
+ * ONE QUESTION PER SCREEN, not all of them at once. Three questions x four
+ * options x a description line is 20+ rows against a ~15-row viewport on a
+ * 24-row terminal.
+ */
+function QuestionBody({ question, cursor, selected, typing, draft, theme, caps, }) {
+    const glyphs = pickGlyphs(caps);
+    const markOn = question.allowMultiple ? glyphs.boxChecked : glyphs.keyOn;
+    const markOff = question.allowMultiple ? glyphs.boxEmpty : glyphs.keyOff;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { wrap: "truncate", color: theme.accent, bold: true, children: question.header }), _jsx(Text, { wrap: "truncate", color: theme.assistant, children: question.question }), _jsx(Text, { children: " " }), question.options.map((option, i) => {
+                const active = i === cursor;
+                const on = selected.has(i);
+                return (_jsxs(Text, { wrap: "truncate", children: [_jsxs(Text, { color: active ? theme.primary : theme.muted, children: [active ? glyphs.caret : ' ', ' '] }), _jsxs(Text, { color: on ? theme.primary : theme.muted, children: [on ? markOn : markOff, " "] }), _jsx(Text, { color: active ? theme.assistant : undefined, bold: active, children: option.isOther ? `${option.label}${glyphs.ellipsis}` : option.label }), option.description.length > 0 && (_jsxs(Text, { color: theme.muted, children: ['  ', option.description] })), option.recommended && (_jsxs(Text, { backgroundColor: theme.chip.bg, color: theme.chip.fg, children: [' ', "RECOMMENDED", ' '] }))] }, `${question.id}-${i}`));
+            }), typing && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsxs(Text, { wrap: "truncate", children: [_jsxs(Text, { color: theme.primary, bold: true, children: [glyphs.caret, ' '] }), draft.length > 0 ? (_jsx(Text, { children: draft })) : (_jsx(Text, { color: theme.muted, children: "type your own answer" })), _jsx(Text, { inverse: true, children: " " })] })] }))] }));
+}
+/**
+ * The review step exists because a wizard that fires on the last `Enter` with no
+ * confirmation makes a mis-keyed answer unrecoverable.
+ */
+function ReviewBody({ questions, answers, theme, }) {
+    return (_jsx(Box, { flexDirection: "column", children: questions.map((q, i) => {
+            const answer = answers[i];
+            const value = answer?.custom ?? answer?.selected.join(', ') ?? '';
+            return (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { color: theme.accent, children: q.header.padEnd(14) }), _jsx(Text, { color: theme.assistant, children: value })] }, q.id));
+        }) }));
+}

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

@@ -9,6 +9,7 @@
  */
 import React from 'react';
 import type { ThinkingLevel } from '@aragon-agent/core';
+import { type LogLevelName } from '../../logging/levels.js';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
 export interface SettingsValues {
@@ -18,6 +19,12 @@ export interface SettingsValues {
     thinkingLevel: ThinkingLevel;
     maxTokens: string;
     apiKey: string;
+    /**
+     * Only the LEVEL is editable here. The rest of `LogConfig` — and above all
+     * `redactSecrets` — stays command-line-only, so the one switch that can put
+     * credentials on disk cannot be flipped by a stray arrow key.
+     */
+    logLevel: LogLevelName;
 }
 interface SettingsScreenProps {
     initial: SettingsValues;

package/dist/ui/overlays/SettingsScreen.js

@@ -11,6 +11,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
 import { Text, useInput } from 'ink';
 import { ADAPTER_PROVIDERS, THINKING_LEVELS, maskSecret } from '../../config/schema.js';
+import { LOG_LEVEL_NAMES } from '../../logging/levels.js';
 import { pickGlyphs } from '../glyphs.js';
 import { OverlayFrame } from '../layout/OverlayFrame.js';
 const FIELDS = [
@@ -20,6 +21,7 @@ const FIELDS = [
     { key: 'thinkingLevel', label: 'Thinking', kind: 'enum', options: THINKING_LEVELS },
     { key: 'maxTokens', label: 'Max tokens', kind: 'text' },
     { key: 'apiKey', label: 'API key', kind: 'secret' },
+    { key: 'logLevel', label: 'Log level', kind: 'enum', options: LOG_LEVEL_NAMES },
 ];
 export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }) {
     const [values, setValues] = useState(initial);
@@ -51,7 +53,12 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
             setIndex((i) => (i - 1 + FIELDS.length) % FIELDS.length);
             return;
         }
-        if (key.downArrow || key.tab) {
+        // `&& !key.shift` is a real key collision, not a style choice: Shift+Tab is
+        // the global mode toggle, and without the guard it would also advance the
+        // field cursor here — the user changes mode and their selection jumps
+        // (AC-P4). The mode toggle itself is a no-op while an overlay is open, so
+        // this branch simply has to stay out of the way.
+        if (key.downArrow || (key.tab && !key.shift)) {
             setIndex((i) => (i + 1) % FIELDS.length);
             return;
         }

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/use-startup-notices.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The two things the user needs to be told about that happened BEFORE the frame
+ * existed, and the one that can happen at any moment afterwards.
+ *
+ * Both arrive as toasts, and that is not a style choice: with the TUI mounted, a
+ * toast is the only legal user-visible channel. Any direct write to stdout or
+ * stderr shifts the fixed frame by a row and breaks its line accounting for good
+ * (invariant I-4).
+ *
+ * Lives outside `App.tsx` because that file is already at its size ceiling, and
+ * because these two effects share one job — surfacing a condition the user could
+ * not otherwise see — rather than belonging to the view.
+ */
+import type { ViewAction } from '../agent/reducer.js';
+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;
+    /** Persist `mouseNoticeSeen`. Called once, after the notice is dispatched. */
+    onSeen: () => void;
+}
+export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions): void;

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

@@ -0,0 +1,64 @@
+/**
+ * The two things the user needs to be told about that happened BEFORE the frame
+ * existed, and the one that can happen at any moment afterwards.
+ *
+ * Both arrive as toasts, and that is not a style choice: with the TUI mounted, a
+ * toast is the only legal user-visible channel. Any direct write to stdout or
+ * stderr shifts the fixed frame by a row and breaks its line accounting for good
+ * (invariant I-4).
+ *
+ * Lives outside `App.tsx` because that file is already at its size ceiling, and
+ * because these two effects share one job — surfacing a condition the user could
+ * not otherwise see — rather than belonging to the view.
+ */
+import { useEffect, useRef } from 'react';
+import { readConfigFile } from '../config/store.js';
+import { getLogger } from '../logging/logger.js';
+/**
+ * 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.
+    useEffect(() => {
+        getLogger().onFailure((reason) => dispatch({ type: 'pushToast', level: 'warn', text: `Logging stopped: ${reason}` }));
+    }, [dispatch]);
+    // `main()` already wrote this to stderr, but entering the alternate screen
+    // wipes it — so full-screen users would be left with the very failure the
+    // message exists to prevent: every setting back at its default, and nothing
+    // anywhere connecting that to the comma they typed into config.json.
+    useEffect(() => {
+        const { parseError } = readConfigFile();
+        if (!parseError)
+            return;
+        dispatch({
+            type: 'pushToast',
+            level: 'warn',
+            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 (readConfigFile().config?.mouseNoticeSeen)
+            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.0",
+  "version": "0.5.2",
   "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",
@@ -32,6 +32,7 @@
   },
   "files": [
     "dist",
+    "runtime",
     "skills",
     "README.md",
     "CHANGELOG.md"
@@ -50,7 +51,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.0",
+    "@aragon-agent/core": "^0.2.2",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",