@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/ui/overlays/AgentsBoardOverlay.js

@@ -0,0 +1,183 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * AgentsBoardOverlay — the read-only detail board behind `Ctrl+B` / `/agents`
+ * (tui-subagent-panel §4.4 / §6.3).
+ *
+ * READ-ONLY IS THE SAFETY BOUNDARY (§2.2). Nothing here nudges, kills or re-dispatches
+ * a child, and no new `TeamEvent` member was introduced to feed it: a board that can
+ * only read can never kill a healthy child, which is the whole reason this is a
+ * second surface rather than a control panel.
+ *
+ * ONE SCREEN, CONTROLLED MODE. `OverlayFrame`'s controlled form already owns paging,
+ * the position indicator and the narrow-terminal degradation, and `helpRows` /
+ * `projectQueueRows` are the precedent. A second pane would mean a second horizontal
+ * budget inside Ink for a benefit the board's 2-up field rows already deliver.
+ *
+ * IT DOES NOT GO BLANK WHEN THE DISPATCH ENDS (D-9). `state.team` becomes `null` the
+ * frame the dispatch settles, and a reader would lose the child they were reading
+ * about at the exact moment they wanted the post-mortem. The last live snapshot is
+ * therefore FROZEN (a copy, held in a ref) and keeps rendering with a
+ * `dispatch ended` row; a board opened AFTER the dispatch has ended builds from the
+ * transcript's settled `team` entry instead (`resolveBoardSource`), which is where the
+ * `result` section earns its place - the error is the one fact that is never stripped.
+ *
+ * NO `ink-spinner` HERE (D-13): `spinner-census.test.ts` pins the exact list of files
+ * that mount an animated spinner, and this is a reading surface, not an animation.
+ * The panel is where motion belongs.
+ *
+ * AND NO MOTION PROP (v2 implementation note, appended to the spec's
+ * "implementation findings"). Because nothing here animates, a motion flag would be a
+ * prop with no consumer - and worse, the same census counts how many times `App.tsx`
+ * hands the RAW motion flag to a child and asserts the count is EXACTLY ONE, so passing
+ * it from the board's branch would break a shipped guard rail for no gain.
+ *
+ * ASCII ONLY: every symbol comes through `glyphs`.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { buildAgentBoardRows, resolveBoardSource, resolveSelection, } from '../layout/agents-board.js';
+/** `OverlayFrame`'s own breakpoint, mirrored so the chrome estimate cannot drift. */
+const FRAME_BORDERLESS_COLS = 48;
+/**
+ * Close a frozen live snapshot: the dispatch it described has ended.
+ *
+ * `durationMs` is derived from the LAST frame the snapshot was live, so the board's
+ * summary shows the dispatch's real total instead of a clock that keeps running against
+ * a dispatch nobody can see any more. When the snapshot never had a `startedAt` there is
+ * nothing to derive and the field stays absent - the LIVE-ONLY rule turns that into an
+ * empty clock cell rather than an invented number (§4.4.2).
+ */
+function settleFrozen(frozen) {
+    const { source, at } = frozen;
+    const total = source.startedAt === undefined ? undefined : Math.max(0, at - source.startedAt);
+    return {
+        ...source,
+        active: false,
+        ...(total !== undefined ? { durationMs: total } : {}),
+    };
+}
+/** Palette slot -> theme colour. One place, so a tone can never be spelled twice. */
+function toneColor(tone, theme) {
+    switch (tone) {
+        case 'accent':
+            return theme.accent;
+        case 'primary':
+            return theme.primary;
+        case 'muted':
+            return theme.muted;
+        case 'warn':
+            return theme.noticeWarn;
+        case 'error':
+            return theme.noticeError;
+        case 'done':
+            return theme.toolDone;
+        case 'hint':
+            return theme.hintFg;
+    }
+}
+export function AgentsBoardOverlay({ team, entries, cols, maxRows, scrollOffset, onScrollClamp, isActive, native, theme, caps, now, }) {
+    const glyphs = pickGlyphs(caps);
+    const at = now ?? Date.now();
+    const [selectedLabel, setSelectedLabel] = useState(null);
+    /**
+     * THE FROZEN SNAPSHOT (D-9), plus the clock reading it was frozen at.
+     *
+     * A ref rather than state on purpose: it is written from an effect that must not
+     * trigger a render of its own, and reading it during the render that FIRST sees
+     * `team === null` is what keeps the board from blinking empty for one frame. The
+     * timestamp is kept WITH the snapshot because a frozen live source still says
+     * `active: true` - it was live when it was copied - and a board that kept believing
+     * that would never show its `dispatch ended` row nor stop its clock.
+     */
+    const frozen = useRef(null);
+    const live = team === null ? null : resolveBoardSource({ team, entries });
+    useEffect(() => {
+        if (live !== null)
+            frozen.current = { source: live, at };
+    }, [live, at]);
+    // PRIORITY: live > frozen > the most recent settled entry (§4.4.5). The frozen copy
+    // only ever takes over on the frame the live snapshot disappears, and a NEW dispatch
+    // overwrites it on its own first frame, so the two paths cannot both be active.
+    //
+    // A FROZEN SOURCE IS SETTLED, and it is closed here rather than at the moment of
+    // copying: `active: false` is what draws `dispatch ended` (task AC-17), and taking
+    // `durationMs` from the freeze instant stops the clock at the dispatch's real end
+    // instead of letting it count up forever from a snapshot that no longer exists.
+    const frozenSource = frozen.current === null ? null : settleFrozen(frozen.current);
+    const source = live ?? frozenSource ?? resolveBoardSource({ team: null, entries });
+    const selected = source === null ? null : resolveSelection(source.runs, selectedLabel);
+    /**
+     * UP/DOWN MOVES THE CHILD CURSOR, and a change of child RESETS the scroll.
+     *
+     * `agents` deliberately does NOT join `App`'s row-scroll set (`help | plan | queue`):
+     * the same trade `settings` makes with its field cursor, where Up/Down is worth more
+     * as navigation than as a six-row scroll. `PgUp` / `PgDn` / the wheel still page the
+     * board through `App`'s `controlled` set, so no reading gesture is lost.
+     */
+    const move = useCallback((delta) => {
+        const runs = source?.runs ?? [];
+        if (runs.length === 0)
+            return;
+        const current = resolveSelection(runs, selectedLabel);
+        const index = current === null ? -1 : runs.findIndex((run) => run.label === current.label);
+        const next = runs[Math.min(runs.length - 1, Math.max(0, index + delta))];
+        if (next === undefined || next.label === current?.label)
+            return;
+        setSelectedLabel(next.label);
+        // The documented semantic of this port is "the offset should now be 0" (§6.3).
+        onScrollClamp(0);
+    }, [onScrollClamp, selectedLabel, source]);
+    useInput((_input, key) => {
+        if (!isActive)
+            return;
+        if (key.upArrow)
+            move(-1);
+        else if (key.downArrow)
+            move(1);
+    }, { isActive });
+    // THE FRAME'S CHROME IS NOT FREE (v2 implementation note). `cols` arrives as the
+    // overlay's FRAME width (`App`'s `viewCols`), and `OverlayFrame` spends 4 of those
+    // columns on its border plus `paddingX={1}` (2 in the narrow rail form, which drops
+    // the right border and the right padding). A board laid out against the frame width
+    // therefore has its LAST four columns eaten by Ink's truncation - which lands exactly
+    // on the right-anchored figures this board exists to align. `helpRows` gets away with
+    // it because its rows are prose; these are a table.
+    const contentCols = Math.max(1, cols - (cols >= FRAME_BORDERLESS_COLS ? 4 : 2));
+    const rows = source === null
+        ? [{
+                key: 'empty',
+                kind: 'hint',
+                text: 'No subagent dispatch yet.',
+                tone: 'muted',
+            }]
+        : buildAgentBoardRows({
+            source,
+            cols: contentCols,
+            now: at,
+            selectedLabel: selected?.label ?? null,
+            glyphs,
+            native,
+        });
+    // The `dispatch ended` banner is a ROW rather than a title swap: the title is the
+    // frame's own ("Agents"), and replacing it would hide which screen the reader is on.
+    const endedRow = source !== null && !source.active
+        ? [{
+                key: 'ended',
+                kind: 'hint',
+                text: `dispatch ended ${glyphs.midDot} Esc to close`,
+                tone: 'warn',
+            }]
+        : [];
+    const elements = [...endedRow, ...rows].map((row) => (_jsx(Text, { wrap: "truncate", color: toneColor(row.tone, theme), ...(row.kind === 'section' ? { bold: true } : {}), children: row.text }, row.key)));
+    // THE HINT SHRINKS WITH THE FRAME. `OverlayFrame` prints the hint as one unwrapped
+    // row, so a 41-column hint inside a 30-column frame makes the FRAME 41 wide - the
+    // board would overflow the terminal and take the overlay's border with it.
+    const hint = contentCols >= 60
+        ? `Esc close ${glyphs.midDot} Up/Down child ${glyphs.midDot} PgUp/PgDn scroll`
+        : contentCols >= 30
+            ? `Esc close ${glyphs.midDot} Up/Down child`
+            : 'Esc close';
+    return (_jsx(OverlayFrame, { title: "Agents", hint: hint, maxRows: maxRows, cols: cols, rows: elements, scrollOffset: scrollOffset, onScrollClamp: onScrollClamp, theme: theme, caps: caps }));
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Confirm dialog — Yes/No gate for `confirmTools` mode. Resolves the pending
+ * tool-execution promise (spec §3.6). `y` = approve; `n`/Enter/Esc = reject
+ * (Enter follows the safe default shown by the capital N in the "(y/N)" prompt,
+ * since this gates mutating tools like write_file/edit_file/bash).
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+export interface ConfirmState {
+    summary: string;
+    resolve: (approved: boolean) => void;
+}
+interface ConfirmDialogProps {
+    isActive?: boolean;
+    state: ConfirmState;
+    maxRows: number;
+    cols: number;
+    theme: Theme;
+    caps: TermCapabilities;
+    onClose: () => void;
+}
+/**
+ * Self-managed (mode B) and deliberately without a position indicator: five
+ * rows do not need scrolling, and `state.summary` may itself be multi-line, so
+ * element slicing would be meaningless here. The frame is used purely so the
+ * title and border match the other three overlays; the existing `useInput` is
+ * untouched.
+ */
+export declare function ConfirmDialog({ state, isActive, maxRows, cols, theme, caps, onClose, }: ConfirmDialogProps): React.ReactElement;
+export {};

package/dist/ui/overlays/ConfirmDialog.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Confirm dialog — Yes/No gate for `confirmTools` mode. Resolves the pending
+ * tool-execution promise (spec §3.6). `y` = approve; `n`/Enter/Esc = reject
+ * (Enter follows the safe default shown by the capital N in the "(y/N)" prompt,
+ * since this gates mutating tools like write_file/edit_file/bash).
+ */
+import { useState } from 'react';
+import { Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { wrapToRows } from '../layout/wrap-rows.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+/**
+ * Self-managed (mode B) and deliberately without a position indicator: five
+ * rows do not need scrolling, and `state.summary` may itself be multi-line, so
+ * element slicing would be meaningless here. The frame is used purely so the
+ * title and border match the other three overlays; the existing `useInput` is
+ * untouched.
+ */
+export function ConfirmDialog({ state, isActive = true, maxRows, cols, theme, caps, onClose, }) {
+    const glyphs = pickGlyphs(caps);
+    const [offset, setOffset] = useState(0);
+    useInput((input, key) => {
+        if (!isActive)
+            return;
+        if (key.pageUp || key.upArrow) {
+            setOffset(n => Math.max(0, n - 1));
+            return;
+        }
+        if (key.pageDown || key.downArrow) {
+            setOffset(n => n + 1);
+            return;
+        }
+        if (input === 'y' || input === 'Y') {
+            state.resolve(true);
+            onClose();
+        }
+        else if (input === 'n' || input === 'N' || key.return || key.escape) {
+            state.resolve(false);
+            onClose();
+        }
+    });
+    return (_jsx(OverlayFrame, { title: "Confirm action", hint: "y approve | n/Enter/Esc reject | PgDn", maxRows: maxRows, cols: cols, theme: theme, caps: caps, scrollOffset: offset, onScrollClamp: setOffset, rows: wrapToRows(state.summary, Math.max(1, cols - 4)).map((line, index) => _jsx(Text, { wrap: "truncate", color: theme.assistant, children: line || ' ' }, index)) }));
+}

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

@@ -0,0 +1,41 @@
+/**
+ * GovernanceBoardOverlay - the read-only `/gov board` overview
+ * (governance-mode section 10.5).
+ *
+ * ASCII ONLY: every symbol comes through `glyphs`.
+ *
+ * READ-ONLY IS THE SAFETY BOUNDARY, as for the Agents board: nothing here scores, rules
+ * or resolves anything. The only side effect is `e`, which asks the owner to copy the
+ * `board.md` path.
+ *
+ * `OverlayFrame` SELF-MANAGED MODE, with this file owning the window. The tab strip must
+ * stay put while the rows scroll, which the frame's controlled mode (it windows EVERY row
+ * it is given) cannot do; so the body is "one strip row + a window of rows" and the
+ * windowing is `sliceWindow` through `boardWindow`, the arithmetic the frame itself uses.
+ * `PgUp` / `PgDn` / the wheel arrive through `App`'s `controlled` overlay list as
+ * `scrollOffset`; Up/Down and Left/Right are this component's own keys, the same split the
+ * Agents board makes.
+ *
+ * NO `ink-spinner` and no motion prop (spinner-census): this is a reading surface.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import { type BoardTab, type GovernanceBoardData } from '../layout/governance-board.js';
+export interface GovernanceBoardOverlayProps {
+    /** The board's data, or null when there is no governed run to show. */
+    data: GovernanceBoardData | null;
+    /** The overlay's FRAME width (`App`'s `viewCols`). */
+    cols: number;
+    maxRows: number;
+    scrollOffset: number;
+    onScrollClamp: (offset: number) => void;
+    isActive: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+    /** `e`: copy the board file path. Absent = the key reports the path as unavailable. */
+    onCopyPath?: (path: string) => void;
+    onNotice?: (level: 'info' | 'warn', text: string) => void;
+    initialTab?: BoardTab;
+}
+export declare function GovernanceBoardOverlay({ data, cols, maxRows, scrollOffset, onScrollClamp, isActive, theme, caps, onCopyPath, onNotice, initialTab, }: GovernanceBoardOverlayProps): React.ReactElement;

package/dist/ui/overlays/GovernanceBoardOverlay.js

@@ -0,0 +1,76 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * GovernanceBoardOverlay - the read-only `/gov board` overview
+ * (governance-mode section 10.5).
+ *
+ * ASCII ONLY: every symbol comes through `glyphs`.
+ *
+ * READ-ONLY IS THE SAFETY BOUNDARY, as for the Agents board: nothing here scores, rules
+ * or resolves anything. The only side effect is `e`, which asks the owner to copy the
+ * `board.md` path.
+ *
+ * `OverlayFrame` SELF-MANAGED MODE, with this file owning the window. The tab strip must
+ * stay put while the rows scroll, which the frame's controlled mode (it windows EVERY row
+ * it is given) cannot do; so the body is "one strip row + a window of rows" and the
+ * windowing is `sliceWindow` through `boardWindow`, the arithmetic the frame itself uses.
+ * `PgUp` / `PgDn` / the wheel arrive through `App`'s `controlled` overlay list as
+ * `scrollOffset`; Up/Down and Left/Right are this component's own keys, the same split the
+ * Agents board makes.
+ *
+ * NO `ink-spinner` and no motion prop (spinner-census): this is a reading surface.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame, overlayBodyRows } from '../layout/OverlayFrame.js';
+import { boardBodyRows, boardHint, boardPosition, boardWindow, buildGovernanceBoardLayout, stepTab, } from '../layout/governance-board.js';
+import { cellWidth } from '../layout/cells.js';
+import { GovernanceLine } from '../GovernanceRun.js';
+import { BOARD_COPIED, BOARD_NO_PATH, BOARD_TITLE } from '../governance-copy.js';
+/** `OverlayFrame`'s own breakpoint, mirrored so the chrome estimate cannot drift. */
+const FRAME_BORDERLESS_COLS = 48;
+export function GovernanceBoardOverlay({ data, cols, maxRows, scrollOffset, onScrollClamp, isActive, theme, caps, onCopyPath, onNotice, initialTab = 'roster', }) {
+    const glyphs = pickGlyphs(caps);
+    const [tab, setTab] = useState(initialTab);
+    // The frame spends 4 of `cols` on its border + padding (2 in the narrow rail form), so a
+    // board planned against the frame width would lose its last four columns to truncation.
+    const contentCols = Math.max(1, cols - (cols >= FRAME_BORDERLESS_COLS ? 4 : 2));
+    const layout = buildGovernanceBoardLayout({ cols: contentCols, tab, data, glyphs });
+    const height = boardBodyRows(overlayBodyRows(maxRows, cols));
+    const window = boardWindow(layout.lines.length, scrollOffset, height);
+    const position = boardPosition(window, glyphs);
+    useEffect(() => {
+        if (window.clamped !== scrollOffset)
+            onScrollClamp(window.clamped);
+    }, [window.clamped, scrollOffset, onScrollClamp]);
+    // The offset the NEXT key press starts from. A held Down key delivers several presses
+    // before React re-renders; stepping from the rendered value would turn three presses
+    // into one row of movement.
+    const offsetRef = useRef(window.clamped);
+    offsetRef.current = window.clamped;
+    useInput((input, key) => {
+        if (!isActive)
+            return;
+        if (key.leftArrow || key.rightArrow) {
+            setTab((current) => stepTab(current, key.rightArrow ? 1 : -1));
+            offsetRef.current = 0;
+            onScrollClamp(0);
+            return;
+        }
+        if (key.upArrow || key.downArrow) {
+            offsetRef.current = Math.max(0, offsetRef.current + (key.upArrow ? -1 : 1));
+            onScrollClamp(offsetRef.current);
+        }
+        else if (input === 'e' || input === 'E') {
+            const path = data?.boardPath ?? null;
+            if (path === null || onCopyPath === undefined) {
+                onNotice?.('warn', BOARD_NO_PATH);
+                return;
+            }
+            onCopyPath(path);
+            onNotice?.('info', BOARD_COPIED);
+        }
+    }, { isActive });
+    const visible = layout.lines.slice(window.start, window.start + window.visible);
+    return (_jsxs(OverlayFrame, { title: BOARD_TITLE, hint: boardHint(contentCols, glyphs), maxRows: maxRows, cols: cols, theme: theme, caps: caps, children: [_jsxs(Box, { flexDirection: "row", height: 1, flexShrink: 0, children: [_jsx(Box, { flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(GovernanceLine, { segments: layout.tabStrip.segments, theme: theme }) }), position !== '' && (_jsx(Box, { width: cellWidth(position) + 1, flexShrink: 0, justifyContent: "flex-end", children: _jsx(Text, { color: theme.muted, children: position }) }))] }), visible.map((line) => (_jsx(GovernanceLine, { segments: line.segments, theme: theme }, line.key)))] }));
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Settings > Governance: eleven arrows-adjustable rows (governance-mode-v1-1 5, closing
+ * governance-mode IF-13).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THIS IS `TeamFanoutPage` WITH A DIFFERENT TABLE, ON PURPOSE. Every defence that page
+ * carries was paid for by a real defect, so each one is inherited verbatim:
+ *
+ *  - THE PAGE OWNS ONE PIECE OF STATE, its cursor. Every value comes from `props.view.rows`,
+ *    which `SettingsScreen` derives from the reducer; a second copy of the draft here could
+ *    disagree with the root page about what Ctrl+S is about to save.
+ *  - `Enter` TOGGLES THE SWITCH ROWS AND DOES NOTHING ON A NUMBER (R-P1-12). A stray Return
+ *    that silently changed a number is indistinguishable from a bug, and the arrow keys are
+ *    already the obvious control there.
+ *  - IT DOES NOT LISTEN FOR Ctrl+S, AND THE FOOTER SAYS SO (R-P1-13). `useRootSettingsInput`
+ *    gates its `useInput` on `state.page === 'root'`, so a subpage has no save listener at
+ *    all; a footer promising "Ctrl+S saves here" would be a lie the user acts on.
+ *
+ * THE RESTART NOTE IS THE ONE THING THIS PAGE ADDS. `enabled` is a REGISTRATION key: the tool
+ * array is fixed when the session is built, so flipping it here changes the file and the
+ * next launch, not this session. The note sits under that row so the consequence is read
+ * where the choice is made.
+ */
+import React from 'react';
+import { type ProfileFrameProps } from './ModelProfilePicker.js';
+import type { GovernanceSettingKey, GovernanceSettingRow } from './governance-settings.js';
+/** What the page may ask the screen to change. */
+export interface GovernanceSettingsAction {
+    type: 'governance-step';
+    key: GovernanceSettingKey;
+    delta: -1 | 1;
+}
+export interface GovernanceSettingsView {
+    /** Exactly eleven, in the fixed order the cursor indexes. */
+    rows: GovernanceSettingRow[];
+    error?: string;
+    /** Shown under the first row; `null` when the draft agrees with this session. */
+    restartNote: string | null;
+}
+interface GovernanceSettingsPageProps extends ProfileFrameProps {
+    view: GovernanceSettingsView;
+    dispatch: (action: GovernanceSettingsAction) => void;
+    /** Esc: back to the settings root. The draft is NOT discarded here. */
+    onBack: () => void;
+}
+export declare function GovernanceSettingsPage(props: GovernanceSettingsPageProps): React.ReactElement;
+export {};

package/dist/ui/overlays/GovernanceSettingsPage.js

@@ -0,0 +1,93 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Settings > Governance: eleven arrows-adjustable rows (governance-mode-v1-1 5, closing
+ * governance-mode IF-13).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THIS IS `TeamFanoutPage` WITH A DIFFERENT TABLE, ON PURPOSE. Every defence that page
+ * carries was paid for by a real defect, so each one is inherited verbatim:
+ *
+ *  - THE PAGE OWNS ONE PIECE OF STATE, its cursor. Every value comes from `props.view.rows`,
+ *    which `SettingsScreen` derives from the reducer; a second copy of the draft here could
+ *    disagree with the root page about what Ctrl+S is about to save.
+ *  - `Enter` TOGGLES THE SWITCH ROWS AND DOES NOTHING ON A NUMBER (R-P1-12). A stray Return
+ *    that silently changed a number is indistinguishable from a bug, and the arrow keys are
+ *    already the obvious control there.
+ *  - IT DOES NOT LISTEN FOR Ctrl+S, AND THE FOOTER SAYS SO (R-P1-13). `useRootSettingsInput`
+ *    gates its `useInput` on `state.page === 'root'`, so a subpage has no save listener at
+ *    all; a footer promising "Ctrl+S saves here" would be a lie the user acts on.
+ *
+ * THE RESTART NOTE IS THE ONE THING THIS PAGE ADDS. `enabled` is a REGISTRATION key: the tool
+ * array is fixed when the session is built, so flipping it here changes the file and the
+ * next launch, not this session. The note sits under that row so the consequence is read
+ * where the choice is made.
+ */
+import { useState } from 'react';
+import { Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { clipProfileText, useProfileScroll } from './ModelProfilePicker.js';
+/** Matches the root page's `padEnd(18)` rows so the value column lines up (measured). */
+const LABEL_PAD = 18;
+/** The rows `Enter` flips, and nothing else (R-P1-12). */
+const TOGGLE_KEYS = new Set([
+    'enabled',
+    'shiftTab',
+    'panel',
+    'confirmCharter',
+]);
+export function GovernanceSettingsPage(props) {
+    const [index, setIndex] = useState(0);
+    const rows = props.view.rows;
+    const count = Math.max(1, rows.length);
+    const cursor = Math.min(index, count - 1);
+    const focused = rows[cursor];
+    const note = props.view.restartNote;
+    // The note is one extra LINE after row 0, so every later row sits one line lower.
+    const offset = useProfileScroll(props, cursor + (note !== null && cursor > 0 ? 1 : 0));
+    const nudge = (delta) => {
+        if (focused)
+            props.dispatch({ type: 'governance-step', key: focused.key, delta });
+    };
+    const handleKey = (key) => {
+        if (key.escape) {
+            props.onBack();
+            return;
+        }
+        if (key.upArrow || (key.tab && key.shift)) {
+            setIndex((cursor - 1 + count) % count);
+            return;
+        }
+        if (key.downArrow || key.tab) {
+            setIndex((cursor + 1) % count);
+            return;
+        }
+        if (key.leftArrow || key.rightArrow) {
+            nudge(key.leftArrow ? -1 : 1);
+            return;
+        }
+        // `Enter` toggles the switch rows and does NOTHING on a numeric or choice row.
+        if (key.return && focused && TOGGLE_KEYS.has(focused.key))
+            nudge(1);
+    };
+    useInput((_input, key) => {
+        if (props.isActive === false)
+            return;
+        handleKey(key);
+    });
+    const glyphs = pickGlyphs(props.caps);
+    const body = [];
+    rows.forEach((row, at) => {
+        const line = `${row.label.padEnd(LABEL_PAD)}${row.value}`;
+        body.push(_jsx(Text, { wrap: "truncate", color: at === cursor ? props.theme.accent : props.theme.muted, children: `${at === cursor ? glyphs.caret : ' '} ${clipProfileText(line, props.cols - 8)}` }, row.key));
+        if (at === 0 && note !== null) {
+            body.push(_jsx(Text, { wrap: "truncate", color: props.theme.muted, children: `  ${clipProfileText(note, props.cols - 8)}` }, "restart-note"));
+        }
+    });
+    // The hint explains the FOCUSED row: the range and the reason are the point of the page.
+    if (focused) {
+        body.push(_jsx(Text, { wrap: "truncate", color: props.theme.muted, children: clipProfileText(focused.hint, props.cols - 8) }, "hint"));
+    }
+    return _jsx(OverlayFrame, { ...props, rows: body, scrollOffset: offset, title: props.view.error ?? 'Governance', hint: "Arrows adjust. Esc goes back; Ctrl+S on the main page saves." });
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Help overlay — keybindings and slash-command reference (spec §5.2 / §5.3).
+ *
+ * Emits a flat array of ONE-ROW elements for `OverlayFrame`'s controlled mode
+ * rather than a nested tree. This content is 29 rows tall against a 15-row
+ * viewport on a 30-row terminal; before v0.4.0 everything past `/clear` was
+ * clipped by `overflow: hidden` with no scrollbar, no indicator, and no way to
+ * reach it. Slicing is done by element, so every row must be exactly one row —
+ * hence the unconditional `wrap="truncate"`: the first keybinding description
+ * alone is 100 characters with its padding and would wrap on any normal
+ * terminal, silently desynchronising the position indicator (R-8).
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+/**
+ * The key column of every binding row, EXPORTED so the drawer's drift guard can read
+ * the real table instead of scraping this file with a regex
+ * (tui-shortcut-drawer-and-task-summary D-8 / AC-5).
+ *
+ * A SOURCE SCRAPE WOULD PASS ON A COMMENT: the regex has no way to tell a key row
+ * from a legend row from a line inside a block comment, and the guard's whole job is
+ * to notice a row someone forgot.
+ */
+export declare function allKeyRows(times: string): [string, string][];
+/** The slash-command table's key column, for the same guard (commands are not keys). */
+export declare function allCommandRows(): [string, string][];
+/** Build the overlay's rows. Exported so `app.test.tsx` can count them. */
+export declare function helpRows(theme: Theme, caps: TermCapabilities, native?: boolean): React.ReactElement[];