@aragon-agent/cli 0.5.0 → 0.5.2

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;

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/layout/wrap-rows.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `wrapToRows` — the prose wrapper for `OverlayFrame`'s controlled (mode A)
+ * content (plan-mode §6.6).
+ *
+ * Mode A's contract is *one element per row, each already `wrap="truncate"`*,
+ * and `sliceWindow` counts ELEMENTS, not lines. Help and Settings satisfy that
+ * naturally because their content is a list of short rows. A plan is not: its
+ * summary runs to 600 characters and a step detail to 400, so handing either
+ * over as a single `<Text>` renders the whole paragraph as one truncated line —
+ * the single worst failure available to a plan review card, and one that also
+ * makes the frame's `1-14/22` position indicator a false statement.
+ *
+ * The repo had no wrapper before this (no `wrapText`, no `wordWrap`), so here is
+ * one: pure, no Ink, unit-tested.
+ */
+/**
+ * Break `text` into lines of at most `width` columns.
+ *
+ * Prefers spaces; hard-breaks any single token longer than `width` (a URL or a
+ * long path, which must not be dropped and cannot be wrapped politely).
+ * Existing newlines are honoured as paragraph breaks. Returns `[]` for empty
+ * input so callers can splice the result without an emptiness branch.
+ */
+export declare function wrapToRows(text: string, width: number): string[];

package/dist/ui/layout/wrap-rows.js

@@ -0,0 +1,74 @@
+/**
+ * `wrapToRows` — the prose wrapper for `OverlayFrame`'s controlled (mode A)
+ * content (plan-mode §6.6).
+ *
+ * Mode A's contract is *one element per row, each already `wrap="truncate"`*,
+ * and `sliceWindow` counts ELEMENTS, not lines. Help and Settings satisfy that
+ * naturally because their content is a list of short rows. A plan is not: its
+ * summary runs to 600 characters and a step detail to 400, so handing either
+ * over as a single `<Text>` renders the whole paragraph as one truncated line —
+ * the single worst failure available to a plan review card, and one that also
+ * makes the frame's `1-14/22` position indicator a false statement.
+ *
+ * The repo had no wrapper before this (no `wrapText`, no `wordWrap`), so here is
+ * one: pure, no Ink, unit-tested.
+ */
+/**
+ * Break `text` into lines of at most `width` columns.
+ *
+ * Prefers spaces; hard-breaks any single token longer than `width` (a URL or a
+ * long path, which must not be dropped and cannot be wrapped politely).
+ * Existing newlines are honoured as paragraph breaks. Returns `[]` for empty
+ * input so callers can splice the result without an emptiness branch.
+ */
+export function wrapToRows(text, width) {
+    if (typeof text !== 'string' || text.length === 0)
+        return [];
+    const limit = Math.max(1, Math.floor(width));
+    const rows = [];
+    for (const paragraph of text.split('\n')) {
+        if (paragraph.trim().length === 0) {
+            // A blank line in the source is a deliberate separator; keep it as a row
+            // rather than collapsing it, or the summary and the steps run together.
+            rows.push('');
+            continue;
+        }
+        rows.push(...wrapParagraph(paragraph, limit));
+    }
+    return rows;
+}
+function wrapParagraph(paragraph, limit) {
+    const rows = [];
+    let current = '';
+    for (const word of paragraph.split(/\s+/).filter((w) => w.length > 0)) {
+        if (word.length > limit) {
+            // Flush what we have, then chop the over-long token into full-width
+            // pieces. Its tail becomes the new `current` so the next word can still
+            // join it.
+            if (current.length > 0) {
+                rows.push(current);
+                current = '';
+            }
+            let rest = word;
+            while (rest.length > limit) {
+                rows.push(rest.slice(0, limit));
+                rest = rest.slice(limit);
+            }
+            current = rest;
+            continue;
+        }
+        if (current.length === 0) {
+            current = word;
+        }
+        else if (current.length + 1 + word.length <= limit) {
+            current = `${current} ${word}`;
+        }
+        else {
+            rows.push(current);
+            current = word;
+        }
+    }
+    if (current.length > 0)
+        rows.push(current);
+    return rows;
+}

package/dist/ui/overlays/HelpOverlay.js

@@ -7,11 +7,14 @@ function keyRows(times) {
         ['Enter', 'Submit (idle) / queue steering (running); re-pins to the newest output'],
         ['Alt+Enter / Shift+Enter', 'Insert newline'],
         ['Esc', 'Abort run / close overlay'],
+        ['Shift+Tab', 'Toggle plan mode (same as /plan)'],
         [`Ctrl+C ${times}2`, 'Exit'],
         ['Ctrl+L', 'Redraw the frame'],
         ['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)'],
     ];
 }
@@ -19,6 +22,7 @@ const COMMANDS = [
     ['/help', 'Show this help'],
     ['/model', 'Open the model picker'],
     ['/settings', 'Open the settings screen'],
+    ['/plan [on|off|status]', 'Toggle plan mode (same as Shift+Tab)'],
     ['/theme <name>', 'auto | warm | cool | light'],
     ['/thinking <level>', 'Set thinking level'],
     ['/tools', 'List active tools'],
@@ -41,6 +45,14 @@ const SKILL_ROWS = [
     ['/<skill-name> [args]', 'Run a skill directly ($ARGUMENTS / $1..$9)'],
     ['skill / skill_install', 'Tools the model uses to load and install skills'],
 ];
+const PLAN_ROWS = [
+    ['Shift+Tab / /plan', 'Switch between BUILD (do it now) and PLAN (research first)'],
+    ['In PLAN mode', 'write_file, edit_file, bash, skill_install and skill_create are refused'],
+    ['bash', 'Refused in full, including git status - use read_file / glob / grep'],
+    ['ask_user', 'The agent asks 1-5 multiple-choice questions; Enter takes the recommendation'],
+    ['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)'],
+];
 /** Build the overlay's rows. Exported so `app.test.tsx` can count them. */
 export function helpRows(theme, caps) {
     const glyphs = pickGlyphs(caps);
@@ -53,6 +65,9 @@ export function helpRows(theme, caps) {
     rows.push(section('Slash commands'));
     for (const [c, d] of COMMANDS)
         rows.push(pair(c, d));
+    rows.push(section('Plan mode'));
+    for (const [c, d] of PLAN_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/overlays/PlanReviewOverlay.d.ts

@@ -0,0 +1,50 @@
+/**
+ * PlanReviewOverlay — the reviewable card `submit_plan` renders (plan-mode §6.6).
+ *
+ * `OverlayFrame` MODE A (`rows`), because a 20-step plan must scroll and mode A
+ * is the only mode with a position indicator.
+ *
+ * MODE A SLICES BY ELEMENT, SO THE PROSE IS PRE-WRAPPED. `sliceWindow` counts
+ * elements, not lines, and each element must be exactly one row. The summary
+ * runs to 600 characters and a step detail to 400 — handing either over as a
+ * single `<Text>` would render the whole paragraph as one truncated line and
+ * make the frame's `1-14/22` a false statement. `wrapToRows` is what keeps the
+ * count honest.
+ *
+ * ACTIONS LIVE IN THE FRAME HINT, NOT IN `rows`. Mode A slices `rows`; an action
+ * row placed there would scroll off exactly when a long plan needs it most.
+ * Single-key actions also avoid a second selection cursor competing with the
+ * scroll cursor.
+ *
+ * `Esc` IS NOT HANDLED HERE, and neither is any resolution of the pending
+ * request: `App` owns Esc, and the bridge's `settle()` is the only place a human
+ * request is answered (R-P12). That holds in the revise sub-state too, which is
+ * why the way back from the feedback field is `<-` rather than `Esc` (R2-P1-2).
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { NormalizedPlan } from '../../tools/human-input.js';
+export type PlanVerdict = {
+    decision: 'approved' | 'revise';
+    feedback: string;
+};
+interface PlanReviewOverlayProps {
+    plan: NormalizedPlan;
+    maxRows: number;
+    cols: number;
+    scrollOffset: number;
+    onScrollClamp: (offset: number) => void;
+    theme: Theme;
+    caps: TermCapabilities;
+    onVerdict: (verdict: PlanVerdict) => void;
+}
+export declare function PlanReviewOverlay({ plan, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onVerdict, }: PlanReviewOverlayProps): React.ReactElement;
+/**
+ * Flatten the plan into one-row elements.
+ *
+ * Exported for `plan-mode.test.ts`, which asserts that a 600-character summary
+ * really does become many rows rather than one truncated line (P1-3).
+ */
+export declare function buildPlanRows(plan: NormalizedPlan, width: number, theme: Theme, bullet: string): React.ReactElement[];
+export {};

package/dist/ui/overlays/PlanReviewOverlay.js

@@ -0,0 +1,117 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * PlanReviewOverlay — the reviewable card `submit_plan` renders (plan-mode §6.6).
+ *
+ * `OverlayFrame` MODE A (`rows`), because a 20-step plan must scroll and mode A
+ * is the only mode with a position indicator.
+ *
+ * MODE A SLICES BY ELEMENT, SO THE PROSE IS PRE-WRAPPED. `sliceWindow` counts
+ * elements, not lines, and each element must be exactly one row. The summary
+ * runs to 600 characters and a step detail to 400 — handing either over as a
+ * single `<Text>` would render the whole paragraph as one truncated line and
+ * make the frame's `1-14/22` a false statement. `wrapToRows` is what keeps the
+ * count honest.
+ *
+ * ACTIONS LIVE IN THE FRAME HINT, NOT IN `rows`. Mode A slices `rows`; an action
+ * row placed there would scroll off exactly when a long plan needs it most.
+ * Single-key actions also avoid a second selection cursor competing with the
+ * scroll cursor.
+ *
+ * `Esc` IS NOT HANDLED HERE, and neither is any resolution of the pending
+ * request: `App` owns Esc, and the bridge's `settle()` is the only place a human
+ * request is answered (R-P12). That holds in the revise sub-state too, which is
+ * why the way back from the feedback field is `<-` rather than `Esc` (R2-P1-2).
+ */
+import { useState } from 'react';
+import { Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { wrapToRows } from '../layout/wrap-rows.js';
+/** The frame's border plus its one-column padding on each side. */
+const FRAME_CHROME_COLS = 4;
+export function PlanReviewOverlay({ plan, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onVerdict, }) {
+    const glyphs = pickGlyphs(caps);
+    const [feedback, setFeedback] = useState(null);
+    useInput((input, key) => {
+        if (key.escape)
+            return; // App owns dismiss.
+        if (feedback !== null) {
+            if (key.return) {
+                onVerdict({ decision: 'revise', feedback: feedback.trim() });
+                return;
+            }
+            // THE WAY BACK TO THE CARD, and the reason it is `<-` and not `Esc`:
+            // `App` owns Esc here and settles the pending request with it, so a second
+            // Esc consumer in this overlay would be the `ConfirmDialog` double-resolve
+            // pattern R-P12 exists to keep out. `QuestionOverlay` already spends `<-`
+            // on "back", so this costs no key ownership. Without it the field is a
+            // one-way door — it consumes printable input and Backspace, and the only
+            // other exit throws the whole review away (R2-P1-2).
+            if (key.leftArrow) {
+                setFeedback(null);
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setFeedback(feedback.slice(0, -1));
+                return;
+            }
+            if (input && !key.ctrl && !key.meta && !key.tab)
+                setFeedback(feedback + input);
+            return;
+        }
+        if (input === 'a' || input === 'A')
+            onVerdict({ decision: 'approved', feedback: '' });
+        else if (input === 'r' || input === 'R')
+            setFeedback('');
+    });
+    const width = Math.max(20, cols - FRAME_CHROME_COLS);
+    const rows = buildPlanRows(plan, width, theme, glyphs.bullet);
+    if (feedback !== null) {
+        // `esc dismiss`, NOT "esc back to the plan": `App` owns Esc for this overlay
+        // (R-P12) and settles the pending request with `null`, so Esc throws the
+        // whole review away from either sub-state. `<-` is the route back to the
+        // card, which is why it is named here too.
+        const feedbackHint = `${glyphs.enterKey} send ${glyphs.midDot} ${glyphs.arrowLeft} back ${glyphs.midDot} esc dismiss`;
+        return (_jsxs(OverlayFrame, { title: "What should change?", hint: feedbackHint, maxRows: maxRows, cols: cols, theme: theme, caps: caps, children: [_jsx(Text, { wrap: "truncate", color: theme.muted, children: "The agent revises the plan and submits it again." }), _jsxs(Text, { wrap: "truncate", children: [_jsxs(Text, { color: theme.primary, bold: true, children: [glyphs.caret, ' '] }), feedback.length > 0 ? (_jsx(Text, { children: feedback })) : (_jsx(Text, { color: theme.muted, children: "e.g. use the existing session store instead" })), _jsx(Text, { inverse: true, children: " " })] })] }));
+    }
+    return (_jsx(OverlayFrame, { title: "Review plan", hint: `a approve ${glyphs.midDot} r revise ${glyphs.midDot} esc dismiss ${glyphs.midDot} ${glyphs.arrowUp}${glyphs.arrowDown} scroll`, maxRows: maxRows, cols: cols, rows: rows, scrollOffset: scrollOffset, onScrollClamp: onScrollClamp, theme: theme, caps: caps }));
+}
+/**
+ * Flatten the plan into one-row elements.
+ *
+ * Exported for `plan-mode.test.ts`, which asserts that a 600-character summary
+ * really does become many rows rather than one truncated line (P1-3).
+ */
+export function buildPlanRows(plan, width, theme, bullet) {
+    const rows = [];
+    let key = 0;
+    const push = (node, color, bold) => {
+        rows.push(_jsx(Text, { wrap: "truncate", color: color, bold: bold, children: node }, `p${key++}`));
+    };
+    push(plan.title, theme.assistant, true);
+    for (const line of wrapToRows(plan.summary, width))
+        push(line || ' ', theme.muted);
+    push(' ');
+    push('Steps', theme.accent, true);
+    plan.steps.forEach((step, i) => {
+        const number = String(i + 1).padStart(2, ' ');
+        push(`${number}  ${step.title}`);
+        for (const line of wrapToRows(step.detail, Math.max(10, width - 4))) {
+            push(`    ${line}`, theme.muted);
+        }
+    });
+    const section = (label, items) => {
+        if (items.length === 0)
+            return;
+        push(' ');
+        push(label, theme.accent, true);
+        for (const item of items) {
+            for (const line of wrapToRows(`${bullet} ${item}`, width))
+                push(line, theme.muted);
+        }
+    };
+    section('Files', plan.filesTouched);
+    section('Risks', plan.risks);
+    section('Open questions', plan.openQuestions);
+    return rows;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * 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 React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { Answer, NormalizedQuestion } from '../../tools/human-input.js';
+interface QuestionOverlayProps {
+    questions: NormalizedQuestion[];
+    maxRows: number;
+    cols: number;
+    theme: Theme;
+    caps: TermCapabilities;
+    onSubmit: (answers: Answer[]) => void;
+}
+export declare function QuestionOverlay({ questions, maxRows, cols, theme, caps, onSubmit, }: QuestionOverlayProps): React.ReactElement;
+export {};