@aragon-agent/cli 0.5.1 → 0.5.3

package/dist/ui/TeamPanel.d.ts

@@ -0,0 +1,57 @@
+/**
+ * TeamPanel — the live subagent roster (team-subagents §6.1).
+ *
+ * ASCII ONLY: every glyph comes from `pickGlyphs`; a literal here bypasses the
+ * capability probe and shows mojibake on a legacy console (`glyphs.ts` header).
+ *
+ * RENDERED ONLY WHILE A DISPATCH IS RUNNING (D-11). The requirement says "(dang
+ * you de shi hou)" — when there is one — and a permanent zero-row region would
+ * be furniture. `App` passes `null` the rest of the time and this component is
+ * not mounted at all, so a session that never delegates has zero rows and zero
+ * layout shift.
+ *
+ * IT MUST BE MOUNTED INSIDE `AppShell`'s MEASURED BOTTOM BOX (I-10). The wheel
+ * router reads the composer band boundary from `measureElement(bottomRef)`; a
+ * panel rendered outside it makes that boundary stale the moment a dispatch
+ * starts, and the wheel begins scrolling prompt history over the transcript.
+ */
+import React from 'react';
+import type { Theme } from './theme.js';
+import type { TermCapabilities } from './capabilities.js';
+import type { SubagentRun, TeamSnapshot } from '../team/types.js';
+export interface TeamPanelProps {
+    snapshot: TeamSnapshot;
+    /** Terminal rows, for the one-line collapse below `panelCollapseRows`. */
+    rows: number;
+    /**
+     * Terminal columns. REQUIRED, not optional (D-13): an optional width
+     * defaulting to narrow would silently produce the degraded form forever if a
+     * call site forgot it, where a required prop fails at compile time.
+     */
+    cols: number;
+    reducedMotion: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+    /** Injectable clock so the panel test does not depend on wall time. */
+    now?: number;
+}
+export declare function activityBudget(cols: number): number;
+/**
+ * The middle column: what this child is doing right now, in a few words.
+ *
+ * Two width policies, answering different questions. `wide` decides WHICH FACT
+ * to show - a whole path or its basename, a whole command line or its program
+ * name - mirroring `StatusBar`'s `statusCompactCols` degradation rather than
+ * inventing a second threshold. `activityBudget(cols)` decides HOW MUCH OF IT
+ * FITS, and it is a continuous function of width rather than a threshold,
+ * because the failure it prevents - a row wider than the terminal - is
+ * continuous.
+ *
+ * Exported for the same reason `buildSubagentTools` is: the width bound is the
+ * property this round has to keep, and asserting it through a rendered frame
+ * cannot distinguish "the arithmetic clamped it" from "Ink truncated it" - which
+ * is precisely the confusion that let v1's fixed-width column look fine at 100
+ * columns and break at 80.
+ */
+export declare function activityLine(run: SubagentRun, cols: number): string;
+export declare function TeamPanel({ snapshot, rows, cols, reducedMotion, theme, caps, now, }: TeamPanelProps): React.ReactElement;

package/dist/ui/TeamPanel.js

@@ -0,0 +1,134 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import Spinner from 'ink-spinner';
+import { pickGlyphs } from './glyphs.js';
+import { formatDuration } from '../agent/usage.js';
+import { describeToolActivity, sanitizeActivity } from '../team/activity.js';
+import { TEAM_LIMITS } from '../team/limits.js';
+import { selectPanelRows } from '../team/panel-rows.js';
+function isRunning(run) {
+    return run.phase === 'starting' || run.phase === 'thinking' || run.phase === 'tool' ||
+        run.phase === 'waiting';
+}
+function isSettled(run) {
+    return run.phase === 'done' || run.phase === 'failed' || run.phase === 'aborted';
+}
+function statusColor(run, theme) {
+    if (run.phase === 'failed' || run.phase === 'aborted')
+        return theme.toolError;
+    if (run.phase === 'done')
+        return theme.toolDone;
+    if (isRunning(run))
+        return theme.toolRunning;
+    return theme.muted;
+}
+/**
+ * How many characters the activity column may spend at this width (P0-1).
+ *
+ * `TEAM_LIMITS.activityChars` is a STORAGE ceiling; a terminal has a COLUMN
+ * budget, and the two are not the same number. The row is
+ *
+ *     marker(3) + label(8) + description(flex) + 2 + activity + 2 + elapsed(~6)
+ *
+ * and the comment on the description cell below promises that activity and
+ * elapsed never lose characters, i.e. that `description` absorbs ALL width
+ * pressure. A 64-character prose tail plus `writing: ` is 73, which on an
+ * 80-column terminal needs 94 columns before `description` gets one. The promise
+ * cannot be kept by wishing; the column has to be sized from `cols`.
+ *
+ * `WIDE_CHAR_ALLOWANCE` is the concession to there being no display-width helper
+ * in production code: this budget is denominated in code units while the
+ * terminal is denominated in columns, and CJK and emoji occupy two columns per
+ * unit, so the budget is halved against the reserve rather than spent to the
+ * last cell. Erring small costs a few characters of prose; erring large costs
+ * the elapsed column.
+ */
+const ROW_RESERVED_COLS = 3 + 8 + 2 + 2 + 8 + 12; // marker, label, gaps, elapsed, min description
+const WIDE_CHAR_ALLOWANCE = 2;
+export function activityBudget(cols) {
+    const spare = Math.floor((cols - ROW_RESERVED_COLS) / WIDE_CHAR_ALLOWANCE);
+    return Math.max(TEAM_LIMITS.activityMinChars, Math.min(TEAM_LIMITS.activityChars, spare));
+}
+/**
+ * The middle column: what this child is doing right now, in a few words.
+ *
+ * Two width policies, answering different questions. `wide` decides WHICH FACT
+ * to show - a whole path or its basename, a whole command line or its program
+ * name - mirroring `StatusBar`'s `statusCompactCols` degradation rather than
+ * inventing a second threshold. `activityBudget(cols)` decides HOW MUCH OF IT
+ * FITS, and it is a continuous function of width rather than a threshold,
+ * because the failure it prevents - a row wider than the terminal - is
+ * continuous.
+ *
+ * Exported for the same reason `buildSubagentTools` is: the width bound is the
+ * property this round has to keep, and asserting it through a rendered frame
+ * cannot distinguish "the arithmetic clamped it" from "Ink truncated it" - which
+ * is precisely the confusion that let v1's fixed-width column look fine at 100
+ * columns and break at 80.
+ */
+export function activityLine(run, cols) {
+    const wide = cols >= TEAM_LIMITS.activityWideCols;
+    const budget = activityBudget(cols);
+    switch (run.phase) {
+        case 'queued':
+            return 'queued';
+        case 'starting':
+            // The one row that legitimately restarts its clock, saying why (P2-4):
+            // F-2 ranks the running group by `startedAt` and a retry re-stamps it.
+            return run.retries ? 'starting (retry)' : 'starting';
+        case 'thinking':
+            // Clamped AT RENDER, against this terminal's budget. `run.activity` was
+            // clamped at STORE against `activityChars`; that is a ceiling, not a fit.
+            return run.activity ? `writing: ${sanitizeActivity(run.activity, budget)}` : 'thinking';
+        case 'tool':
+        case 'waiting':
+            return run.lastTool
+                ? sanitizeActivity(describeToolActivity(run.lastTool, run.activityArgs, wide), budget)
+                : run.phase === 'waiting'
+                    ? 'waiting for mail'
+                    : 'tool';
+        case 'done':
+            return `done  ${run.turns} turns`;
+        case 'failed':
+            return 'failed';
+        case 'aborted':
+            return 'aborted';
+    }
+}
+export function TeamPanel({ snapshot, rows, cols, reducedMotion, theme, caps, now, }) {
+    const glyphs = pickGlyphs(caps);
+    const at = now ?? Date.now();
+    const running = snapshot.runs.filter(isRunning).length;
+    const done = snapshot.runs.filter(isSettled).length;
+    const elapsed = formatDuration(Math.max(0, at - snapshot.startedAt));
+    const header = (_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Text, { wrap: "truncate", color: theme.accent, bold: true, children: [glyphs.teamAgent, " team", '  ', _jsxs(Text, { color: theme.muted, children: [running, " running ", glyphs.midDot, " ", done, " done ", glyphs.midDot, " ", elapsed] })] }), snapshot.messageCount > 0 && (_jsxs(Text, { wrap: "truncate", color: theme.muted, children: [glyphs.teamMail, " ", snapshot.messageCount] }))] }));
+    // Below 20 rows the roster is more expensive than the transcript it displaces,
+    // so the panel degrades to the one line that still answers "is something
+    // running, and for how long" (§6.4).
+    if (rows < TEAM_LIMITS.panelCollapseRows) {
+        return _jsx(Box, { flexDirection: "column", flexShrink: 0, children: header });
+    }
+    // RANKED, not sliced by array index (F-2). The slot pool hands out indices in
+    // order, so `slice(0, 5)` showed the five children that finished FIRST and hid
+    // everything still working behind `+N more` - at exactly the fan-out widths
+    // the requirement permits.
+    const { visible, hiddenTotal, hiddenRunning } = selectPanelRows(snapshot.runs, TEAM_LIMITS.panelMaxRows);
+    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [header, visible.map((run) => {
+                const color = statusColor(run, theme);
+                // One spinner per RUNNING row, and the row cap is 5 precisely because
+                // five is the documented maximum number of simultaneous spinners. Both
+                // `reducedMotion` and a non-Unicode terminal fall back to the same
+                // static marker, exactly as `AssistantEntry` and `ToolCard` already do.
+                const animate = isRunning(run) && !reducedMotion && caps.unicode;
+                return (_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: color, children: [' ', animate ? _jsx(Spinner, { type: "dots" }) : marker(run, glyphs), ' '] }), _jsx(Text, { color: theme.primary, children: run.label.padEnd(8).slice(0, 8) }), _jsx(Box, { flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(Text, { wrap: "truncate", color: theme.muted, children: run.description }) }), _jsx(Box, { flexShrink: 1, overflow: "hidden", children: _jsxs(Text, { wrap: "truncate", color: color, children: ['  ', activityLine(run, cols)] }) }), _jsxs(Text, { wrap: "truncate", color: theme.muted, children: ['  ', run.startedAt ? formatDuration(Math.max(0, (run.endedAt ?? at) - run.startedAt)) : ''] })] }, run.label));
+            }), hiddenTotal > 0 && (_jsxs(Text, { wrap: "truncate", color: theme.muted, children: ['  ', "+", hiddenTotal, " more", hiddenRunning > 0 ? ` (${hiddenRunning} running)` : ''] })), snapshot.lastMessage && (_jsxs(Text, { wrap: "truncate", color: theme.muted, children: [' ', glyphs.teamMail, " ", snapshot.lastMessage.from, " ", glyphs.arrowRight, " ", snapshot.lastMessage.to, ": ", snapshot.lastMessage.subject] }))] }));
+}
+function marker(run, glyphs) {
+    if (run.phase === 'done')
+        return glyphs.toolDone;
+    if (run.phase === 'failed' || run.phase === 'aborted')
+        return glyphs.toolError;
+    if (run.phase === 'queued')
+        return glyphs.toolPending;
+    return glyphs.spinnerStill;
+}

package/dist/ui/Transcript.js

@@ -26,6 +26,7 @@ import { EntryFrame } from './entries/EntryFrame.js';
 import { UserEntry } from './entries/UserEntry.js';
 import { AssistantEntry } from './entries/AssistantEntry.js';
 import { ToolCard, statusColor, toolEntryGlyph } from './entries/ToolCard.js';
+import { TeamCard, teamCardColor } from './entries/TeamCard.js';
 /** Keep the last K entries in the live region so a mutating tail stays hot. */
 const LIVE_TAIL = 1;
 /**
@@ -47,6 +48,13 @@ export function computeSettledCount(entries, expandedToolIds) {
             break;
         if (e.kind === 'tool' && e.status !== 'done' && e.status !== 'error')
             break;
+        // A live dispatch is not settled: its `runs` are rewritten on every
+        // `teamUpdate`, and `<Static>` cannot un-print what it has already drawn.
+        // The boundary is held MONOTONIC above, which is also why a `team` entry
+        // that never settles would be re-rendered on every frame for the rest of the
+        // session — the failure `session/persist.ts` normalizes away on load (P1-5).
+        if (e.kind === 'team' && e.active)
+            break;
         count = i + 1;
     }
     return count;
@@ -81,6 +89,8 @@ function EntryView({ entry, prev, expanded, thinkingVisible, reducedMotion, dens
         }
         case 'tool':
             return frame(toolEntryGlyph(entry.name, caps), statusColor(entry.status, theme), _jsx(ToolCard, { name: entry.name, label: entry.label, argsRaw: entry.argsRaw, args: entry.args, status: entry.status, preview: entry.preview, durationMs: entry.durationMs, isError: entry.isError, expanded: expanded, reducedMotion: reducedMotion, theme: theme, caps: caps }));
+        case 'team':
+            return frame(glyphs.teamAgent, teamCardColor(entry.runs, entry.active, entry.aborted, theme), _jsx(TeamCard, { requested: entry.requested, runs: entry.runs, aborted: entry.aborted, durationMs: entry.durationMs, active: entry.active, expanded: expanded, reducedMotion: reducedMotion, theme: theme, caps: caps }));
         case 'notice':
             return frame(noticeSymbol(entry.level, theme), noticeColor(entry.level, theme), _jsx(Text, { color: noticeColor(entry.level, theme), children: entry.text }));
         default:

package/dist/ui/entries/TeamCard.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TeamCard — the settled-dispatch transcript entry (team-subagents §6.3).
+ *
+ * ASCII ONLY: every glyph comes from `pickGlyphs`.
+ *
+ * The panel is EPHEMERAL and this card is the HISTORY. It renders like a
+ * `ToolCard` — same `EntryFrame` supplied by `EntryView`, same left rail for the
+ * expanded body — so a dispatch reads as one more step in the transcript rather
+ * than a second kind of object.
+ *
+ * `Ctrl+O` expands it to the per-agent summaries, which is why `App.tsx`'s
+ * Ctrl+O finder had to widen from `kind === 'tool'` to `tool || team`.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { SubagentRun } from '../../team/types.js';
+export interface TeamCardProps {
+    requested: number;
+    runs: SubagentRun[];
+    aborted: boolean;
+    durationMs?: number;
+    active: boolean;
+    expanded?: boolean;
+    reducedMotion?: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+/** The card's aggregate colour: any failure dominates. */
+export declare function teamCardColor(runs: SubagentRun[], active: boolean, aborted: boolean, theme: Theme): string | undefined;
+export declare function TeamCard(props: TeamCardProps): React.ReactElement;

package/dist/ui/entries/TeamCard.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import Spinner from 'ink-spinner';
+import { pickGlyphs } from '../glyphs.js';
+import { railBorderProps } from '../layout/Gutter.js';
+import { formatDuration } from '../../agent/usage.js';
+function isOk(run) {
+    return run.phase === 'done' && !run.error;
+}
+/** The card's aggregate colour: any failure dominates. */
+export function teamCardColor(runs, active, aborted, theme) {
+    if (active)
+        return theme.toolRunning;
+    if (aborted || runs.some((r) => !isOk(r)))
+        return theme.toolError;
+    return theme.toolDone;
+}
+export function TeamCard(props) {
+    const { requested, runs, aborted, durationMs, active, expanded, reducedMotion, theme, caps } = props;
+    const glyphs = pickGlyphs(caps);
+    const color = teamCardColor(runs, active, aborted, theme);
+    const ok = runs.filter(isOk).length;
+    const failed = runs.length - ok;
+    // A dispatch entry restored from `/resume` is settled and aborted but has no
+    // duration: nothing measured it, because the process it belonged to is gone.
+    // Saying so plainly beats rendering `0.0s (0 ok, 3 failed)`, which reads like
+    // a dispatch that ran and lost (§5.3 / P1-5).
+    const interrupted = !active && aborted && durationMs === undefined;
+    const settled = runs.filter((r) => r.phase === 'done' || r.phase === 'failed' || r.phase === 'aborted').length;
+    const headline = interrupted
+        ? 'interrupted (session resumed)'
+        : active
+            ? `${runs.length - settled} running`
+            : `${formatDuration(durationMs ?? 0)}  (${ok} ok, ${failed} failed)`;
+    const count = `${runs.length} ${runs.length === 1 ? 'subagent' : 'subagents'}`;
+    const dropped = requested > runs.length ? `  (${runs.length} of ${requested} requested)` : '';
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: theme.accent, bold: true, children: "team" }), _jsxs(Text, { color: theme.muted, children: [' ', count, dropped, '  '] }), active && !reducedMotion && caps.unicode ? (_jsxs(Text, { color: color, children: [_jsx(Spinner, { type: "dots" }), " ", headline] })) : (_jsxs(Text, { color: color, children: [active ? `${glyphs.spinnerStill} ` : '', headline] }))] }), _jsxs(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, ...railBorderProps(glyphs.railVertical, theme.border), children: [runs.map((run) => (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { color: isOk(run) ? theme.toolDone : theme.toolError, children: isOk(run) ? glyphs.toolDone : glyphs.toolError }), _jsxs(Text, { color: theme.primary, children: [" ", run.label.padEnd(8).slice(0, 8)] }), _jsxs(Text, { color: theme.muted, children: [' ', run.description, '  ', run.startedAt ? formatDuration(Math.max(0, (run.endedAt ?? 0) - run.startedAt)) : '', `  ${run.turns} turns`, run.filesTouched.length > 0 ? `  ${run.filesTouched.length} files` : '', run.error ? `  ${run.error}` : ''] })] }, run.label))), expanded &&
+                        runs.map((run) => (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { color: theme.accent, children: [run.label, " ", glyphs.midDot, " ", run.description] }), _jsx(Text, { color: theme.muted, children: run.summary ?? '(no summary)' })] }, `s-${run.label}`))), !expanded && !active && runs.length > 0 && (_jsxs(Text, { color: theme.muted, children: ["+", runs.length, " ", runs.length === 1 ? 'summary' : 'summaries', " (Ctrl+O)"] })), expanded && _jsx(Text, { color: theme.muted, children: "(Ctrl+O to collapse)" })] })] }));
+}

package/dist/ui/glyphs.d.ts

@@ -72,8 +72,30 @@ export interface Glyphs {
     railVertical: string;
     railBranch: string;
     railEnd: string;
+    /**
+     * Scroll-position indicator on the viewport's right edge (mouse-wheel §4.8).
+     *
+     * These are byte-for-byte identical to `railVertical` / `gaugeFull` in both
+     * tiers, and that is DELIBERATE (P2-2). This file's header mandates "add a
+     * field here instead" of a new exception, and semantic field names are what
+     * make the ASCII tier reviewable at a glance. Reusing `gaugeFull` would
+     * couple the scroll thumb to the context-window gauge, so that restyling one
+     * silently restyles the other — do not "deduplicate" them.
+     */
+    scrollTrack: string;
+    scrollThumb: string;
     /** Redaction dot for `maskSecret` in the settings screen (§4.1 tier B). */
     maskDot: string;
+    /**
+     * Team mode (team-subagents §6.1). The rail marker for a dispatch card and
+     * the prefix on the panel's incoming-message preview.
+     *
+     * They live HERE rather than in `TeamPanel` / `TeamCard` for the reason this
+     * file's header gives: a literal in a component bypasses `pickGlyphs` entirely
+     * and shows mojibake on a legacy console, whatever the capability probe said.
+     */
+    teamAgent: string;
+    teamMail: string;
     /**
      * Ink `borderStyle` name for every boxed region (composer, completion popup,
      * overlay frame).

package/dist/ui/glyphs.js

@@ -55,8 +55,12 @@ const UNICODE_GLYPHS = {
     railVertical: '│',
     railBranch: '├',
     railEnd: '╰',
+    scrollTrack: '│',
+    scrollThumb: '█',
     maskDot: '•',
     boxStyle: 'round',
+    teamAgent: '◆',
+    teamMail: '✉',
     tool: {
         read_file: '▤',
         write_file: '✎',
@@ -67,6 +71,7 @@ const UNICODE_GLYPHS = {
         list_dir: '▤',
         ask_user: '?',
         submit_plan: '◈',
+        task: '◆',
     },
     toolDefault: '•',
 };
@@ -107,8 +112,12 @@ const ASCII_GLYPHS = {
     railVertical: '|',
     railBranch: '|',
     railEnd: '\\',
+    scrollTrack: '|',
+    scrollThumb: '#',
     maskDot: '*',
     boxStyle: 'classic',
+    teamAgent: '*',
+    teamMail: '@',
     tool: {
         read_file: '=',
         write_file: '+',
@@ -119,6 +128,7 @@ const ASCII_GLYPHS = {
         list_dir: '=',
         ask_user: '?',
         submit_plan: '#',
+        task: '*',
     },
     toolDefault: '*',
 };

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

@@ -11,14 +11,33 @@
  */
 import React from 'react';
 import { type RenderMode } from './frame.js';
+import { type FrameGeometry } from './regions.js';
 export interface AppShellProps {
     mode: RenderMode;
     rows: number;
     cols: number;
     header: React.ReactNode;
     viewport: React.ReactNode;
+    /**
+     * The live subagent roster (team-subagents §6.1), or nothing.
+     *
+     * IT RENDERS INSIDE `bottomRef` IN THE FULL-SCREEN BRANCH, and it has to
+     * (I-10): `geometryRef.current.bottom` is MEASURED from that box, and the
+     * wheel router uses it to decide whether a notch belongs to the transcript or
+     * to prompt history. A panel rendered above the measured box would make the
+     * composer band boundary stale the instant a dispatch started.
+     */
+    team?: React.ReactNode;
     toast: React.ReactNode;
     composer: React.ReactNode;
     status: React.ReactNode;
+    /**
+     * Where the wheel router reads the composer band boundary from (mouse-wheel
+     * §4.5). Written in a LAYOUT EFFECT to a MUTABLE REF, never to state: the
+     * measurement happens on every commit, and routing it through `setState`
+     * would add a re-render to the streaming path for a value nothing renders
+     * (R-7).
+     */
+    geometryRef?: React.MutableRefObject<FrameGeometry>;
 }
-export declare function AppShell({ mode, rows, cols, header, viewport, toast, composer, status, }: AppShellProps): React.ReactElement;
+export declare function AppShell({ mode, rows, cols, header, viewport, team, toast, composer, status, geometryRef, }: AppShellProps): React.ReactElement;

package/dist/ui/layout/AppShell.js

@@ -1,9 +1,44 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { Box } from 'ink';
+/**
+ * AppShell (spec §4.3) — the frame that makes R2 true.
+ *
+ * In `fullscreen` the root box has a FIXED height of `frameHeight(rows)` and the
+ * middle viewport is the only `flexGrow` child, so the bottom chrome (toast /
+ * composer / status bar) is physically the last thing on the screen from the
+ * very first frame — empty session, long session, mid-scroll, overlay open.
+ *
+ * In `inline` the same children are emitted in the same order with no height
+ * constraint, i.e. byte-for-byte the v0.2.0 document-flow behavior.
+ */
+import { useLayoutEffect, useRef } from 'react';
+import { Box, measureElement } from 'ink';
 import { frameHeight } from './frame.js';
-export function AppShell({ mode, rows, cols, header, viewport, toast, composer, status, }) {
+import { UNMEASURED_GEOMETRY } from './regions.js';
+export function AppShell({ mode, rows, cols, header, viewport, team, toast, composer, status, geometryRef, }) {
+    const bottomRef = useRef(null);
+    // DECLARED ABOVE THE INLINE EARLY RETURN, and it has to stay there: React
+    // keys hooks by call order, and a hook that only runs in one mode changes
+    // that order between modes.
+    //
+    // Ink computes yoga layout in `onRender`, which React runs BEFORE layout
+    // effects, so this reflects the commit that just happened — the same
+    // mechanism `ScrollViewport` already relies on.
+    useLayoutEffect(() => {
+        if (!geometryRef)
+            return;
+        if (mode === 'inline' || !bottomRef.current) {
+            geometryRef.current = UNMEASURED_GEOMETRY;
+            return;
+        }
+        geometryRef.current = {
+            // 1 in the alternate screen — see the note on `FrameGeometry.top`.
+            top: 1,
+            height: frameHeight(rows),
+            bottom: measureElement(bottomRef.current).height,
+        };
+    });
     if (mode === 'inline') {
-        return (_jsxs(Box, { flexDirection: "column", children: [header, viewport, toast, composer, status] }));
+        return (_jsxs(Box, { flexDirection: "column", children: [header, viewport, team, toast, composer, status] }));
     }
-    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexShrink: 0, children: header }), _jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), _jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [toast, composer, status] })] }));
+    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexShrink: 0, children: header }), _jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), _jsxs(Box, { ref: bottomRef, flexDirection: "column", flexShrink: 0, children: [team, toast, composer, status] })] }));
 }

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

@@ -0,0 +1,31 @@
+/**
+ * ScrollIndicator (mouse-wheel-region-routing §4.8) — the one-column scroll
+ * position rail on the viewport's right edge.
+ *
+ * NAMING (P2-1): this is NOT `layout/Gutter.tsx`. That one is the two-column
+ * left rail every transcript entry sits in, and it carries an invariant of its
+ * own. Two components called a gutter, on opposite edges, for unrelated
+ * purposes, is how a codebase stops being able to say what it means.
+ *
+ * THE COLUMN IS RESERVED UNCONDITIONALLY, track glyph and all. Showing it only
+ * while scrolled would change the content width, re-wrap every line, change the
+ * content height, and feed that back into the measurement that decides whether
+ * to show it — a shimmer at the exact moment the user is reading. Constant
+ * width, no feedback loop (D-9); `width={1}` and `flexShrink={0}` hold the
+ * column even on the first frame, before anything has been measured.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { ThumbRange } from './scroll-indicator.js';
+/** Below this width a column of content is worth more than the affordance. */
+export declare const MIN_INDICATOR_COLS = 50;
+export interface ScrollIndicatorProps {
+    /** Viewport height in rows, as measured by `ScrollViewport`. */
+    rows: number;
+    /** `null` when the content fits — the rail is drawn as bare track. */
+    thumb: ThumbRange | null;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export declare function ScrollIndicator({ rows, thumb, theme, caps, }: ScrollIndicatorProps): React.ReactElement;

package/dist/ui/layout/ScrollIndicator.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+/** Below this width a column of content is worth more than the affordance. */
+export const MIN_INDICATOR_COLS = 50;
+export function ScrollIndicator({ rows, thumb, theme, caps, }) {
+    const glyphs = pickGlyphs(caps);
+    const count = Math.max(0, Math.floor(rows) || 0);
+    const cells = [];
+    for (let i = 0; i < count; i += 1) {
+        const onThumb = !!thumb && i >= thumb.start && i < thumb.start + thumb.size;
+        cells.push(_jsx(Text, { color: onThumb ? theme.primary : theme.border, children: onThumb ? glyphs.scrollThumb : glyphs.scrollTrack }, i));
+    }
+    return (_jsx(Box, { flexDirection: "column", flexShrink: 0, width: 1, children: cells }));
+}

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

@@ -17,17 +17,23 @@ import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
 import { type ScrollIntent } from './scroll.js';
 export interface ScrollViewportProps {
-    /** Scroll intent. `nonce` is monotonic so pressing the same key twice re-fires. */
+    /**
+     * Scroll intent. `nonce` is monotonic so pressing the same key twice re-fires.
+     * `repeat` folds a coalesced wheel burst into one state update (defaults 1).
+     */
     intent?: {
         kind: ScrollIntent;
         nonce: number;
+        repeat?: number;
     };
     /** Bumped by the parent to force a pin to the newest output (e.g. on submit). */
     pinToBottomNonce?: number;
     /** Derived display value for the status bar's `↑N`. Must be referentially stable. */
     onScrolledLinesChange?: (lines: number) => void;
+    /** Reserve the right-edge scroll-position rail (mouse-wheel §4.8). */
+    showScrollIndicator?: boolean;
     theme: Theme;
     caps: TermCapabilities;
     children: React.ReactNode;
 }
-export declare function ScrollViewport({ intent, pinToBottomNonce, onScrolledLinesChange, theme, caps, children, }: ScrollViewportProps): React.ReactElement;
+export declare function ScrollViewport({ intent, pinToBottomNonce, onScrolledLinesChange, showScrollIndicator, theme, caps, children, }: ScrollViewportProps): React.ReactElement;

package/dist/ui/layout/ScrollViewport.js

@@ -16,10 +16,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { Box, Text, measureElement, useStdout } from 'ink';
 import { pickGlyphs } from '../glyphs.js';
-import { applyScroll, clampScroll, } from './scroll.js';
+import { applyScrollTimes, clampScroll, } from './scroll.js';
+import { thumbRange } from './scroll-indicator.js';
+import { MIN_INDICATOR_COLS, ScrollIndicator } from './ScrollIndicator.js';
 /** Below this the full hint sentence wraps and eats a second viewport row. */
 const TERSE_HINT_COLS = 42;
-export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesChange, theme, caps, children, }) {
+export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesChange, showScrollIndicator = false, theme, caps, children, }) {
     const { stdout } = useStdout();
     const cols = stdout?.columns ?? 80;
     const glyphs = pickGlyphs(caps);
@@ -38,12 +40,26 @@ export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesCh
         const content = innerRef.current ? measureElement(innerRef.current).height : 0;
         setMetrics((prev) => (prev.viewport === viewport && prev.content === content ? prev : { viewport, content }));
     });
+    // I-9: seeded from the INCOMING nonce during the first render, so the effect
+    // below cannot apply an intent on the mount that first observes it. A
+    // `useEffect([nonce])` fires on mount as well as on change, and this
+    // component is unmounted whenever an overlay opens (`App.tsx` swaps it out) —
+    // without the guard, closing an overlay replays whatever wheel gesture was in
+    // flight when it opened, and the transcript jumps a page on its own. That is
+    // R-P1-7, which this codebase has already paid for once through the keyboard
+    // path; the overlay-swallowing rule in `App`'s key handler becomes a SECOND
+    // line of defence rather than the only one.
+    const lastAppliedNonce = useRef(intent?.nonce);
     const intentNonce = intent?.nonce ?? 0;
     useEffect(() => {
         const current = intentRef.current;
         if (!current)
             return;
-        setScroll((prev) => applyScroll(prev, current.kind, metricsRef.current));
+        if (current.nonce === lastAppliedNonce.current)
+            return;
+        lastAppliedNonce.current = current.nonce;
+        const repeat = current.repeat ?? 1;
+        setScroll((prev) => applyScrollTimes(prev, current.kind, metricsRef.current, repeat));
         // Keyed on the nonce alone: `intent` is a fresh object on every parent
         // render, so depending on it directly would re-scroll on every keystroke.
         // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -61,7 +77,11 @@ export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesCh
     // what "N new lines you have not scrolled down to" means.
     const hiddenBelow = offset;
     const showHint = hiddenBelow > 0;
-    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { ref: clipRef, flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(Box, { ref: innerRef, flexDirection: "column", flexShrink: 0, marginTop: -shiftUp, children: children }) }), showHint && (
+    // Suppressed below `MIN_INDICATOR_COLS`, where a column of content is worth
+    // more than the affordance. The routing never reads this flag, which is what
+    // keeps the indicator independently revertible (§13-Q3).
+    const indicatorVisible = showScrollIndicator && cols >= MIN_INDICATOR_COLS;
+    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsxs(Box, { flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { ref: clipRef, flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(Box, { ref: innerRef, flexDirection: "column", flexShrink: 0, marginTop: -shiftUp, children: children }) }), indicatorVisible && (_jsx(ScrollIndicator, { rows: metrics.viewport, thumb: thumbRange(metrics.viewport, metrics.content, offset), theme: theme, caps: caps }))] }), showHint && (
             // Not an overlay — Ink has no absolute positioning or z-index. This takes
             // the viewport's last row, trading one line of content for a hint that
             // cannot drift. Cheaper than stacking with negative margins.

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

@@ -0,0 +1,55 @@
+/**
+ * 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).
+ */
+export type WheelBand = 'content' | 'composer';
+export interface FrameGeometry {
+    /**
+     * 1-based row of the frame's first row. 1 in the alternate screen.
+     *
+     * This is DERIVED, not assumed, and it has a named dependency: it holds
+     * because the full-screen transcript renders no `<Static>`
+     * (`Transcript.tsx`), so Ink's `log-update` writes `frameHeight(rows) = rows-1`
+     * lines plus a newline into a `rows`-row buffer — nothing scrolls, and the
+     * frame sits at rows `1 … rows-1` with the cursor parked on the undrawn last
+     * row. Reintroducing `<Static>` into the full-screen path pushes the frame
+     * down the screen and silently biases every hit test; whoever does that has
+     * to change `top` here at the same time.
+     */
+    top: number;
+    /** Rows the frame occupies — `frameHeight(rows)`. */
+    height: number;
+    /** Measured rows of the bottom chrome (toast + composer + status). */
+    bottom: number;
+}
+/**
+ * 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 declare const UNMEASURED_GEOMETRY: FrameGeometry;
+/**
+ * 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 declare function hitTestWheel(y: number, geometry: FrameGeometry): WheelBand;