@aragon-agent/cli 0.5.3 → 0.5.6

package/dist/ui/TodoStrip.d.ts

@@ -0,0 +1,36 @@
+/**
+ * TodoStrip — the inline-mode plan surface (todo-plan-followthrough §3.7 / W2).
+ *
+ * ASCII ONLY: every glyph comes from `pickGlyphs`; a literal here bypasses the
+ * capability probe and shows mojibake on a legacy console. This file is inside
+ * the glyph scanner's scope because it is under `ui/`, NOT because of the
+ * `todo/` clause (C-4) — moving it would not move the guard rail with it.
+ *
+ * WHY A STRIP AND NOT THE RAIL. `decideRenderMode` picks inline for every pipe,
+ * every `CI=1`, every `TERM=dumb` and every terminal under 12 rows, and inline
+ * has no fixed frame to hang a column off (round 1's non-goal 4). Before this,
+ * such a session had the tool and a `todo 3/7` counter in the status bar, and no
+ * way at all to see WHICH step was running (OQ-1).
+ *
+ * WHY NOT IN THE STATUS BAR. The bar's left cluster is `flexShrink={0}` and its
+ * own comment records what happens when the row over-subscribes: Ink drops a
+ * character from EACH cluster and it renders `idl` / `? hel`. A variable-length
+ * step title cannot go there (C-7), which is what forces this into its own row.
+ *
+ * EXACTLY ONE RENDERED ROW, ALWAYS (AC-29). A strip that wrapped would push the
+ * composer down by an unpredictable number of rows on every keystroke, which is
+ * the worst possible behaviour for the mode with no frame to absorb it — hence
+ * `wrap="truncate"` inside a `flexGrow`/`flexShrink` box and no exceptions.
+ */
+import React from 'react';
+import type { Theme } from './theme.js';
+import type { TermCapabilities } from './capabilities.js';
+import type { TodoSnapshot } from '../todo/types.js';
+export interface TodoStripProps {
+    snapshot: TodoSnapshot;
+    /** Full terminal width; the strip spans the row in inline mode. */
+    cols: number;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export declare function TodoStrip({ snapshot, cols, theme, caps }: TodoStripProps): React.ReactElement;

package/dist/ui/TodoStrip.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { pickGlyphs } from './glyphs.js';
+import { TODO_LIMITS } from '../todo/limits.js';
+import { todoAnchorIndex } from '../todo/panel-rows.js';
+export function TodoStrip({ snapshot, cols, theme, caps }) {
+    const glyphs = pickGlyphs(caps);
+    // THE SAME FUNCTION THE RAIL USES (R-9 / AC-30). Two surfaces that each decide
+    // for themselves which step is "current" is two surfaces that disagree, and
+    // this one is on screen in exactly the mode where the rail is not, so the
+    // disagreement would never be seen side by side and never be reported.
+    const anchor = todoAnchorIndex(snapshot.items);
+    const item = snapshot.items[anchor];
+    const active = item?.status === 'in_progress';
+    // `activeForm` while in progress, `content` otherwise — `TodoPanel`'s rule.
+    const label = item ? (active ? item.activeForm : item.content) : '';
+    // The same degradation the status bar already applies, so the two counters can
+    // never disagree about how much room they need.
+    const counter = cols >= TODO_LIMITS.statusCompactCols
+        ? `todo ${snapshot.doneCount}/${snapshot.total}`
+        : `[${snapshot.doneCount}/${snapshot.total}]`;
+    const showDone = snapshot.doneCount > 0 && cols >= TODO_LIMITS.stripDoneCols;
+    return (
+    // `width` IS LOAD-BEARING, exactly as it is on `TodoPanel` and for a related
+    // reason. Inline mode has no fixed frame, so nothing upstream constrains
+    // this row: without an explicit width the flexible middle cell is sized by
+    // whatever the parent offers, and a long item overflows the terminal and
+    // WRAPS — the one thing this component exists not to do. Pinning it here
+    // makes the truncation deterministic and self-contained rather than a
+    // property of the tree above.
+    _jsxs(Box, { flexDirection: "row", width: cols, overflow: "hidden", children: [_jsx(Box, { flexShrink: 0, children: _jsx(Text, { wrap: "truncate", color: theme.accent, children: counter }) }), _jsx(Box, { flexShrink: 0, children: _jsxs(Text, { wrap: "truncate", color: theme.muted, children: [' ', glyphs.arrowRight, ' '] }) }), _jsx(Box, { flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(Text, { wrap: "truncate", color: active ? theme.primary : theme.muted, bold: active, children: label }) }), showDone && (_jsx(Box, { flexShrink: 0, children: _jsxs(Text, { wrap: "truncate", color: theme.muted, children: [' ', "+", snapshot.doneCount, " done"] }) }))] }));
+}

package/dist/ui/Transcript.js

@@ -20,13 +20,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useRef } from 'react';
 import { Box, Static, Text } from 'ink';
 import Spinner from 'ink-spinner';
-import { pickGlyphs } from './glyphs.js';
+import { pickGlyphs, toolGlyph } from './glyphs.js';
 import { separationRows } from './density.js';
 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';
+import { TodoCard, todoCardColor } from './entries/TodoCard.js';
 /** Keep the last K entries in the live region so a mutating tail stays hot. */
 const LIVE_TAIL = 1;
 /**
@@ -55,6 +56,13 @@ export function computeSettledCount(entries, expandedToolIds) {
         // session — the failure `session/persist.ts` normalizes away on load (P1-5).
         if (e.kind === 'team' && e.active)
             break;
+        // A live todo card is not settled either: it is rewritten on every
+        // `todoUpdate` for the whole turn, and `<Static>` cannot un-print what it has
+        // already drawn (C-5 / I-6). `session/persist.ts` forces `live: false` on
+        // load, which is the other half — a card that never settles is re-rendered
+        // on every frame for the rest of the session.
+        if (e.kind === 'todo' && e.live)
+            break;
         count = i + 1;
     }
     return count;
@@ -91,6 +99,8 @@ function EntryView({ entry, prev, expanded, thinkingVisible, reducedMotion, dens
             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 'todo':
+            return frame(toolGlyph(glyphs, 'todo_write'), todoCardColor(entry.doneCount, entry.total, entry.live, theme), _jsx(TodoCard, { items: entry.items, doneCount: entry.doneCount, total: entry.total, live: entry.live, interrupted: entry.interrupted, 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/TodoCard.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TodoCard — the transcript checklist entry (todo-plan-execution §6.2).
+ *
+ * ASCII ONLY: every glyph comes from `pickGlyphs`.
+ *
+ * ONE CARD PER USER TURN, REWRITTEN IN PLACE. The rail is EPHEMERAL and this is
+ * the HISTORY, exactly as `TeamPanel` and `TeamCard` divide the same work. It
+ * renders through the shared `EntryFrame` supplied by `EntryView`, so a plan
+ * reads as one more step in the transcript rather than a second kind of object.
+ *
+ * THE FULL LIST, NO WINDOWING (the transcript scrolls; the rail does not), and
+ * NEVER ANIMATED even while `live` — a resumed session would otherwise spin
+ * forever on a card whose run ended days ago.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { TodoItem } from '../../todo/types.js';
+export interface TodoCardProps {
+    items: TodoItem[];
+    doneCount: number;
+    total: number;
+    live: boolean;
+    /** Saved mid-run and resumed: the run behind this card died with the process. */
+    interrupted?: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+/** The card's aggregate colour: complete is done, anything else is in flight. */
+export declare function todoCardColor(doneCount: number, total: number, live: boolean, theme: Theme): string | undefined;
+export declare function TodoCard(props: TodoCardProps): React.ReactElement;

package/dist/ui/entries/TodoCard.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { railBorderProps } from '../layout/Gutter.js';
+/** The card's aggregate colour: complete is done, anything else is in flight. */
+export function todoCardColor(doneCount, total, live, theme) {
+    if (live)
+        return theme.toolRunning;
+    if (total > 0 && doneCount === total)
+        return theme.toolDone;
+    return theme.muted;
+}
+function marker(item, glyphs) {
+    if (item.status === 'completed')
+        return glyphs.todoDone;
+    if (item.status === 'in_progress')
+        return glyphs.todoActive;
+    return glyphs.todoPending;
+}
+function rowColor(item, theme) {
+    if (item.status === 'completed')
+        return theme.muted;
+    if (item.status === 'in_progress')
+        return theme.primary;
+    return theme.hintFg ?? theme.muted;
+}
+export function TodoCard(props) {
+    const { items, doneCount, total, live, interrupted, theme, caps } = props;
+    const glyphs = pickGlyphs(caps);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: theme.accent, bold: true, children: "Todos" }), _jsxs(Text, { color: todoCardColor(doneCount, total, live, theme), children: ['  ', doneCount, "/", total] }), interrupted && (
+                    // A resumed `2/7` would otherwise read as a run still in flight
+                    // (P2-6). Saying so plainly is the same fix `TeamCard` makes for a
+                    // dispatch that never got a duration.
+                    _jsxs(Text, { color: theme.muted, children: ['  ', "interrupted (session resumed)"] }))] }), _jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, ...railBorderProps(glyphs.railVertical, theme.border), children: items.map((item, index) => (_jsxs(Text, { wrap: "truncate", color: rowColor(item, theme), children: [marker(item, glyphs).padEnd(3), item.status === 'in_progress' ? item.activeForm : item.content] }, `${index}-${item.content}`))) })] }));
+}

package/dist/ui/glyphs.d.ts

@@ -96,6 +96,18 @@ export interface Glyphs {
      */
     teamAgent: string;
     teamMail: string;
+    /**
+     * Todo planning (todo-plan-execution §6.1). One marker per item state, plus
+     * the rail marker for the transcript card via `tool.todo_write`.
+     *
+     * THE ASCII TIER USES BRACKETED FORMS FOR THE TWO SETTLED STATES, because a
+     * bare single letter cannot distinguish "done" from "failed" on a monochrome
+     * terminal. The panel pads the marker cell to 3 columns, which is what makes
+     * the mixed widths line up without a per-tier branch.
+     */
+    todoPending: string;
+    todoActive: string;
+    todoDone: string;
     /**
      * Ink `borderStyle` name for every boxed region (composer, completion popup,
      * overlay frame).

package/dist/ui/glyphs.js

@@ -61,6 +61,9 @@ const UNICODE_GLYPHS = {
     boxStyle: 'round',
     teamAgent: '◆',
     teamMail: '✉',
+    todoPending: '○',
+    todoActive: '▸',
+    todoDone: '✔',
     tool: {
         read_file: '▤',
         write_file: '✎',
@@ -72,6 +75,7 @@ const UNICODE_GLYPHS = {
         ask_user: '?',
         submit_plan: '◈',
         task: '◆',
+        todo_write: '☰',
     },
     toolDefault: '•',
 };
@@ -118,6 +122,9 @@ const ASCII_GLYPHS = {
     boxStyle: 'classic',
     teamAgent: '*',
     teamMail: '@',
+    todoPending: '[ ]',
+    todoActive: '>',
+    todoDone: '[x]',
     tool: {
         read_file: '=',
         write_file: '+',
@@ -129,6 +136,7 @@ const ASCII_GLYPHS = {
         ask_user: '?',
         submit_plan: '#',
         task: '*',
+        todo_write: '=',
     },
     toolDefault: '*',
 };

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

@@ -28,6 +28,39 @@ export interface AppShellProps {
      * composer band boundary stale the instant a dispatch started.
      */
     team?: React.ReactNode;
+    /**
+     * The right-hand region of the MIDDLE band (todo-plan-execution §3.9), or
+     * nothing.
+     *
+     * NAMED FOR ITS POSITION, NOT ITS CONTENT (D-18): this file is a layout
+     * primitive and has no business knowing what a todo is. `team` above already
+     * leaks content vocabulary in here; there is no reason to repeat it.
+     *
+     * IT MUST NOT BE RENDERED INSIDE `bottomRef` (C-6 / I-4). That box is MEASURED
+     * and the wheel router reads the composer band boundary from it; a column
+     * added there would inflate the measurement and start routing transcript
+     * scrolls into prompt history.
+     *
+     * The INLINE branch does not include it at all — a structural guarantee rather
+     * than a promise that the caller passes `null` (non-goal 4).
+     */
+    rail?: React.ReactNode;
+    /**
+     * The one-row plan strip for INLINE mode (todo-plan-followthrough §3.7), or
+     * nothing.
+     *
+     * THE STRUCTURAL MIRROR OF `rail` ABOVE, in the opposite direction: the
+     * FULL-SCREEN branch does not reference it at all. The reason is the same one
+     * `rail`'s inline omission records — a prop that is merely SUPPOSED to be null
+     * in one mode becomes non-null eventually, and then the rail and the strip are
+     * both on screen showing the same list (I-6). Fullscreen has the rail; that is
+     * the whole design.
+     *
+     * It sits between `viewport` and `team`, i.e. OUTSIDE the measured box in the
+     * other branch — but inline has no measured box at all (`geometryRef` is set
+     * to `UNMEASURED_GEOMETRY` there), so there is nothing here to invalidate.
+     */
+    strip?: React.ReactNode;
     toast: React.ReactNode;
     composer: React.ReactNode;
     status: React.ReactNode;
@@ -40,4 +73,4 @@ export interface AppShellProps {
      */
     geometryRef?: React.MutableRefObject<FrameGeometry>;
 }
-export declare function AppShell({ mode, rows, cols, header, viewport, team, toast, composer, status, geometryRef, }: AppShellProps): React.ReactElement;
+export declare function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, toast, composer, status, geometryRef, }: AppShellProps): React.ReactElement;

package/dist/ui/layout/AppShell.js

@@ -14,7 +14,7 @@ import { useLayoutEffect, useRef } from 'react';
 import { Box, measureElement } from 'ink';
 import { frameHeight } from './frame.js';
 import { UNMEASURED_GEOMETRY } from './regions.js';
-export function AppShell({ mode, rows, cols, header, viewport, team, toast, composer, status, geometryRef, }) {
+export function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, 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
@@ -38,7 +38,7 @@ export function AppShell({ mode, rows, cols, header, viewport, team, toast, comp
         };
     });
     if (mode === 'inline') {
-        return (_jsxs(Box, { flexDirection: "column", children: [header, viewport, team, toast, composer, status] }));
+        return (_jsxs(Box, { flexDirection: "column", children: [header, viewport, strip, 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, { ref: bottomRef, flexDirection: "column", flexShrink: 0, children: [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 }), _jsxs(Box, { flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), rail] }), _jsxs(Box, { ref: bottomRef, flexDirection: "column", flexShrink: 0, children: [team, toast, composer, status] })] }));
 }

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

@@ -32,8 +32,20 @@ export interface ScrollViewportProps {
     onScrolledLinesChange?: (lines: number) => void;
     /** Reserve the right-edge scroll-position rail (mouse-wheel §4.8). */
     showScrollIndicator?: boolean;
+    /**
+     * The viewport's own width, when it is narrower than the terminal
+     * (todo-plan-execution §3.9 / C-7).
+     *
+     * This component is the ONLY one inside the viewport subtree that reads
+     * `stdout.columns` directly, and both places it uses the number — the terse
+     * hint threshold and the `MIN_INDICATOR_COLS` gate — are about how much room
+     * THIS BOX has, not how wide the terminal is. Once the todo rail takes a fifth
+     * of the frame those two stop being the same number. Optional so every
+     * existing caller (and every test) is unchanged.
+     */
+    cols?: number;
     theme: Theme;
     caps: TermCapabilities;
     children: React.ReactNode;
 }
-export declare function ScrollViewport({ intent, pinToBottomNonce, onScrolledLinesChange, showScrollIndicator, theme, caps, children, }: ScrollViewportProps): React.ReactElement;
+export declare function ScrollViewport({ intent, pinToBottomNonce, onScrolledLinesChange, showScrollIndicator, cols: colsProp, theme, caps, children, }: ScrollViewportProps): React.ReactElement;

package/dist/ui/layout/ScrollViewport.js

@@ -21,9 +21,9 @@ 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, showScrollIndicator = false, theme, caps, children, }) {
+export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesChange, showScrollIndicator = false, cols: colsProp, theme, caps, children, }) {
     const { stdout } = useStdout();
-    const cols = stdout?.columns ?? 80;
+    const cols = colsProp ?? stdout?.columns ?? 80;
     const glyphs = pickGlyphs(caps);
     const clipRef = useRef(null);
     const innerRef = useRef(null);

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

@@ -0,0 +1,56 @@
+/**
+ * Rail geometry (todo-plan-execution §3.9) — the ONE place that says how wide
+ * and how tall the todo rail is allowed to be.
+ *
+ * Pure and React-free, mirroring `budget.ts`, so `todo-rail.test.ts` can pin the
+ * arithmetic without mounting anything. Deliberately NOT part of `budget.ts`:
+ * that module answers "how many ROWS does the viewport get" and stays a function
+ * of `rows` alone; the rail spends COLUMNS.
+ *
+ * NAMED FOR ITS POSITION, NOT ITS CONTENT, like `AppShellProps.rail` (D-18):
+ * this is a layout primitive and `viewportRows` is its neighbour, not
+ * `TodoPanel`.
+ */
+/** Below this the marker + a two-word title do not fit and the column is noise. */
+export declare const TODO_RAIL_MIN_COLS = 18;
+/**
+ * Above this, 20% is being spent on whitespace: at 36 columns a step title
+ * already fits on one line, and the transcript is the surface that benefits from
+ * a 200-column terminal. A deliberate, revertible deviation from a literal
+ * reading of R-e; it only binds above 180 columns.
+ */
+export declare const TODO_RAIL_MAX_COLS = 36;
+/** Under 80 columns the transcript needs every column; no rail at all. */
+export declare const TODO_RAIL_MIN_TOTAL_COLS = 80;
+/** Below this rail width the 2-column index prefix is dropped for content. */
+export declare const TODO_RAIL_INDEX_MIN_COLS = 22;
+/**
+ * Two properties are pinned by tests, for the reason `budget.ts` records about
+ * the viewport being non-monotonic before anyone measured it:
+ *
+ *  - NON-DECREASING in `cols` across [40, 300]. A user dragging a window wider
+ *    must never see the rail get narrower.
+ *  - `cols - todoRailWidth(cols) >= 62` for every `cols >= 80`. Every existing
+ *    width heuristic inside the viewport (`TERSE_HINT_COLS` 42,
+ *    `MIN_INDICATOR_COLS` 50, the status bar's 60/72 steps) sits below that
+ *    floor, so no existing behaviour changes because a rail appeared (R-3).
+ */
+export declare function todoRailWidth(cols: number): number;
+/**
+ * How many rows the rail may actually draw.
+ *
+ * IT IS NOT `viewportBudget`, AND THE DIFFERENCE IS NOT COSMETIC (P1-3 / D-23).
+ * `viewportRows()` subtracts the STATIC chrome only, and says so; the live team
+ * roster is mounted inside `AppShell`'s measured bottom box, where it costs a
+ * header row, up to `TEAM_LIMITS.panelMaxRows` child rows, a `+N more` row and a
+ * mail row that `viewportBudget` knows nothing about. `ScrollViewport` is immune
+ * because it MEASURES itself; the rail does not measure - a second
+ * measure -> setState -> measure loop is exactly what §1.2 refuses - so it has
+ * to subtract.
+ *
+ * Ink clips overflow from the BOTTOM, so an over-request does not error: it
+ * silently eats the last row, which is the `+N below` marker - the one row whose
+ * absence is indistinguishable from "the list is short". That is why this is
+ * arithmetic rather than a shrug at `overflow: hidden`.
+ */
+export declare function todoRailRows(viewportBudget: number, teamActive: boolean): number;

package/dist/ui/layout/rail.js

@@ -0,0 +1,68 @@
+/**
+ * Rail geometry (todo-plan-execution §3.9) — the ONE place that says how wide
+ * and how tall the todo rail is allowed to be.
+ *
+ * Pure and React-free, mirroring `budget.ts`, so `todo-rail.test.ts` can pin the
+ * arithmetic without mounting anything. Deliberately NOT part of `budget.ts`:
+ * that module answers "how many ROWS does the viewport get" and stays a function
+ * of `rows` alone; the rail spends COLUMNS.
+ *
+ * NAMED FOR ITS POSITION, NOT ITS CONTENT, like `AppShellProps.rail` (D-18):
+ * this is a layout primitive and `viewportRows` is its neighbour, not
+ * `TodoPanel`.
+ */
+import { TODO_LIMITS } from '../../todo/limits.js';
+/** R-e, literally: the rail asks for a fifth of the terminal. */
+const RAIL_FRACTION = 0.2;
+/** Below this the marker + a two-word title do not fit and the column is noise. */
+export const TODO_RAIL_MIN_COLS = 18;
+/**
+ * Above this, 20% is being spent on whitespace: at 36 columns a step title
+ * already fits on one line, and the transcript is the surface that benefits from
+ * a 200-column terminal. A deliberate, revertible deviation from a literal
+ * reading of R-e; it only binds above 180 columns.
+ */
+export const TODO_RAIL_MAX_COLS = 36;
+/** Under 80 columns the transcript needs every column; no rail at all. */
+export const TODO_RAIL_MIN_TOTAL_COLS = 80;
+/** Below this rail width the 2-column index prefix is dropped for content. */
+export const TODO_RAIL_INDEX_MIN_COLS = 22;
+/**
+ * Two properties are pinned by tests, for the reason `budget.ts` records about
+ * the viewport being non-monotonic before anyone measured it:
+ *
+ *  - NON-DECREASING in `cols` across [40, 300]. A user dragging a window wider
+ *    must never see the rail get narrower.
+ *  - `cols - todoRailWidth(cols) >= 62` for every `cols >= 80`. Every existing
+ *    width heuristic inside the viewport (`TERSE_HINT_COLS` 42,
+ *    `MIN_INDICATOR_COLS` 50, the status bar's 60/72 steps) sits below that
+ *    floor, so no existing behaviour changes because a rail appeared (R-3).
+ */
+export function todoRailWidth(cols) {
+    if (!Number.isFinite(cols) || cols < TODO_RAIL_MIN_TOTAL_COLS)
+        return 0;
+    return Math.min(TODO_RAIL_MAX_COLS, Math.max(TODO_RAIL_MIN_COLS, Math.round(cols * RAIL_FRACTION)));
+}
+/**
+ * How many rows the rail may actually draw.
+ *
+ * IT IS NOT `viewportBudget`, AND THE DIFFERENCE IS NOT COSMETIC (P1-3 / D-23).
+ * `viewportRows()` subtracts the STATIC chrome only, and says so; the live team
+ * roster is mounted inside `AppShell`'s measured bottom box, where it costs a
+ * header row, up to `TEAM_LIMITS.panelMaxRows` child rows, a `+N more` row and a
+ * mail row that `viewportBudget` knows nothing about. `ScrollViewport` is immune
+ * because it MEASURES itself; the rail does not measure - a second
+ * measure -> setState -> measure loop is exactly what §1.2 refuses - so it has
+ * to subtract.
+ *
+ * Ink clips overflow from the BOTTOM, so an over-request does not error: it
+ * silently eats the last row, which is the `+N below` marker - the one row whose
+ * absence is indistinguishable from "the list is short". That is why this is
+ * arithmetic rather than a shrug at `overflow: hidden`.
+ */
+export function todoRailRows(viewportBudget, teamActive) {
+    if (!Number.isFinite(viewportBudget))
+        return 0;
+    const reserved = teamActive ? TODO_LIMITS.railReservedRows : 0;
+    return Math.max(0, viewportBudget - reserved);
+}

package/dist/ui/overlays/HelpOverlay.js

@@ -25,7 +25,12 @@ const COMMANDS = [
     ['/plan [on|off|status]', 'Toggle plan mode (same as Shift+Tab)'],
     ['/theme <name>', 'auto | warm | cool | light'],
     ['/thinking <level>', 'Set thinking level'],
+    ['/max-tokens [n|auto]', 'Output token cap; no argument reports the effective one'],
     ['/team [on|off|max n]', 'Team subagents: status, switch, fan-out width'],
+    [
+        '/todo [on|off|panel|follow|clear|continue]',
+        'Todo planning: status, switches, the rail, follow-through',
+    ],
     ['/tools', 'List active tools'],
     ['/clear', 'Clear the visible transcript'],
     ['/reset', 'New conversation'],

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

@@ -8,7 +8,7 @@
  * otherwise.
  */
 import React from 'react';
-import type { ThinkingLevel } from '@aragon-agent/core';
+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';
@@ -40,5 +40,16 @@ interface SettingsScreenProps {
     caps: TermCapabilities;
     onSave: (values: SettingsValues) => void;
 }
+/**
+ * The cap this setting will ACTUALLY produce against the selected model.
+ *
+ * Exported for the tests, and computed on every render rather than in an effect:
+ * `resolveOutputTokens` is pure, allocation-light and does no I/O — the ceiling
+ * lookup is a `Map.get` plus at most seven regex tests.
+ *
+ * Without this row the settings screen can only show what the user typed, and
+ * "I set 64000 but answers still stop early" has no answer anywhere in the UI.
+ */
+export declare function effectiveCapLine(values: Pick<SettingsValues, 'provider' | 'model' | 'maxTokens'>): string;
 export declare function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }: SettingsScreenProps): React.ReactElement;
 export {};

package/dist/ui/overlays/SettingsScreen.js

@@ -10,7 +10,8 @@ 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 { DEFAULT_MAX_OUTPUT_TOKENS, resolveOutputTokens, } from '@aragon-agent/core';
+import { ADAPTER_PROVIDERS, THINKING_LEVELS, maskSecret, parseMaxTokensInput, } from '../../config/schema.js';
 import { LOG_LEVEL_NAMES } from '../../logging/levels.js';
 import { pickGlyphs } from '../glyphs.js';
 import { OverlayFrame } from '../layout/OverlayFrame.js';
@@ -23,6 +24,34 @@ const FIELDS = [
     { key: 'apiKey', label: 'API key', kind: 'secret' },
     { key: 'logLevel', label: 'Log level', kind: 'enum', options: LOG_LEVEL_NAMES },
 ];
+/**
+ * The cap this setting will ACTUALLY produce against the selected model.
+ *
+ * Exported for the tests, and computed on every render rather than in an effect:
+ * `resolveOutputTokens` is pure, allocation-light and does no I/O — the ceiling
+ * lookup is a `Map.get` plus at most seven regex tests.
+ *
+ * Without this row the settings screen can only show what the user typed, and
+ * "I set 64000 but answers still stop early" has no answer anywhere in the UI.
+ */
+export function effectiveCapLine(values) {
+    const parsed = parseMaxTokensInput(values.maxTokens);
+    if (parsed.kind === 'invalid')
+        return 'Effective: -  (not a number; use a value or "auto")';
+    const requested = parsed.kind === 'value' ? parsed.value : undefined;
+    const resolution = resolveOutputTokens({
+        providerId: values.provider,
+        modelId: values.model,
+        ...(requested !== undefined ? { requested } : {}),
+    });
+    if (resolution.clampedBy === 'ceiling') {
+        const ambition = requested ?? DEFAULT_MAX_OUTPUT_TOKENS;
+        return `Effective: ${resolution.value}  (clamped from ${ambition} by the ${values.model} ceiling)`;
+    }
+    if (requested === undefined)
+        return `Effective: ${resolution.value}  (auto)`;
+    return `Effective: ${resolution.value}`;
+}
 export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }) {
     const [values, setValues] = useState(initial);
     const [index, setIndex] = useState(0);
@@ -99,6 +128,10 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
         }
         if (f.kind === 'enum')
             return raw;
+        // An empty cap field is AUTO, not "unset". `(none)` would read as a missing
+        // setting, which is the one thing this field can never be.
+        if (f.key === 'maxTokens' && raw.length === 0)
+            return 'auto';
         return raw.length > 0 ? raw : selected ? '(type to set)' : '(none)';
     };
     // One element per row, each `wrap="truncate"` — the contract for OverlayFrame's
@@ -108,6 +141,10 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
         const selected = i === index;
         return (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { color: selected ? theme.accent : theme.muted, children: selected ? `${glyphs.caret} ` : '  ' }), _jsx(Text, { color: selected ? theme.assistant : theme.muted, children: (f.key === 'apiKey' ? `API key (${values.provider})` : f.label).padEnd(18) }), _jsx(Text, { color: selected ? theme.primary : theme.muted, children: displayValue(f, selected) }), f.kind === 'enum' && selected && (_jsxs(Text, { color: theme.muted, children: [' (', glyphs.arrowLeft, "/", glyphs.arrowRight, ')'] }))] }, f.key));
     });
+    // One element, `wrap="truncate"`, pushed like every other row — OverlayFrame's
+    // controlled mode slices by ELEMENT, so a row that wraps desynchronises the
+    // position indicator.
+    rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: effectiveCapLine(values) }, "__effective"));
     rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: "Enter saves. Keys persist to the config file (0600)." }, "__save"));
     return (_jsx(OverlayFrame, { title: "Settings", hint: `${glyphs.arrowUp}${glyphs.arrowDown} field ${glyphs.midDot} ${glyphs.arrowLeft}${glyphs.arrowRight} change ${glyphs.midDot} Enter save ${glyphs.midDot} Esc close`, maxRows: maxRows, cols: cols, rows: rows, scrollOffset: scrollOffset, onScrollClamp: onScrollClamp, theme: theme, caps: caps }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.5.3",
+  "version": "0.5.6",
   "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",
@@ -46,12 +46,13 @@
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node scripts/prepend-shebang.mjs",
     "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
     "test": "vitest run",
     "start": "node dist/cli.js",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.3",
+    "@aragon-agent/core": "^0.2.6",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",