@aragon-agent/cli 0.6.38 → 0.6.39

package/dist/ui/layout/shortcut-panel-layout.js

@@ -0,0 +1,321 @@
+/**
+ * The shortcut drawer's geometry and row layout
+ * (tui-shortcut-drawer-and-task-summary §4.5).
+ *
+ * ASCII ONLY: `src/ui/**` is inside the glyph scanner's scope, so every symbol
+ * this module emits arrives as a `glyphs` field and is never spelled here.
+ *
+ * PURE AND TOTAL. No Ink, no clock, no terminal: the drawer component renders
+ * what this returns, `OverlayFrame` slices the window this function DERIVED, and
+ * `shortcut-panel-layout.test.ts` pins the arithmetic directly. That split is the
+ * whole defence against P0-1, which was not a rendering bug: v1 hand-fixed the key
+ * column at 21 cells, which left six cells for the keyword at 80 columns, so every
+ * keyword was truncated to `promp...` while a "does not overflow" assertion stayed
+ * green. The column is therefore DERIVED from the table, and a keyword that does
+ * not fit makes its row STACK rather than be cut.
+ *
+ * THERE IS EXACTLY ONE WINDOW AUTHORITY: `cursor`. v1 took both `cursor` and
+ * `scrollOffset`, which meant paging could leave the selected row - and the detail
+ * line that belongs to it - off screen. Paging now moves the CURSOR by a page and
+ * the window is the smallest one containing it.
+ */
+import stringWidth from 'string-width';
+import { fitCells, padCells, wrapCells } from './cells.js';
+import { sliceWindow } from './overlay-window.js';
+import { SHORTCUT_GROUPS, widestKeysCells } from '../shortcuts.js';
+export const SHORTCUT_PANEL_LIMITS = {
+    /** Below this the drawer is full width: a 30-cell bar on a 40-cell screen is noise. */
+    minSplitCols: 64,
+    /** Fraction of the terminal the drawer takes when it IS a drawer. */
+    widthFraction: 0.34,
+    minWidth: 30,
+    maxWidth: 46,
+    /** Rail (1 cell) + `paddingLeft` (1 cell) that `OverlayFrame` spends below 48 columns. */
+    railCells: 2,
+    /** Border (2 cells) + `paddingX` (2 cells) that `OverlayFrame` spends at or above 48. */
+    boxCells: 4,
+    /**
+     * The key column is DERIVED: `min(longestKeys, ceil(listCells * 0.55))`.
+     *
+     * A hard 21 is what turned `prompt library` into `promp...` at 80 columns. The
+     * share is a ceiling, not a target: a table of short keys gets a narrow key
+     * column and the leftover width goes to the keyword.
+     */
+    keyColumnShare: 0.55,
+    /** The keyword column must be at least this wide, or the row stacks. */
+    keywordMinCells: 8,
+    /** Hard ceiling for a keyword string; a longer one is a spec bug, not a width problem. */
+    keywordMaxCells: 10,
+    /** Gap between the key column and the keyword column. */
+    keyGapCells: 1,
+    /** Indent for the selected row's detail lines, and for a stacked keyword. */
+    detailIndent: 2,
+    /** Title + footer rows are chrome and are spent out of the row budget. */
+    chromeRows: 2,
+    /** The task section is capped so the key list always gets the majority of the panel. */
+    taskMaxRows: 2,
+    /**
+     * ABOVE THIS BODY HEIGHT THE GROUP HEADERS GET THEIR OWN ROWS.
+     *
+     * Below it they are dropped entirely - not compressed into `---- GROUP ----`
+     * separators, which was v2's rule and left FOUR entry rows visible on an
+     * 80x24 terminal (title + task + rule + five separators = 9 of 13 body rows).
+     * See `spec.md`'s `## 实施过程发现的方案缺陷` note 1: the ordering still runs
+     * COMPOSE -> RUN -> PANELS -> SESSION -> VIEW, and the requirement ("list every
+     * shortcut from top to bottom") is met by the entries themselves.
+     */
+    groupHeaderMinRows: 18,
+    /** The longest detail line the selected row may grow to. */
+    detailMaxRows: 2,
+};
+/**
+ * The drawer's width in columns.
+ *
+ * `cols < 64` is FULL WIDTH on purpose: at 40 columns a right-aligned 30-cell bar
+ * spends 10 of the user's columns on empty space. The clamp mirrors
+ * `rail.ts::todoRailWidth` (same shape, same reason).
+ */
+export function shortcutPanelWidth(cols) {
+    const width = Number.isFinite(cols) ? Math.floor(cols) : 80;
+    const safe = Math.max(0, width);
+    if (safe < SHORTCUT_PANEL_LIMITS.minSplitCols)
+        return safe;
+    const fraction = Math.round(safe * SHORTCUT_PANEL_LIMITS.widthFraction);
+    return Math.min(SHORTCUT_PANEL_LIMITS.maxWidth, Math.max(SHORTCUT_PANEL_LIMITS.minWidth, fraction));
+}
+/**
+ * Cells the drawer may draw on INSIDE its frame.
+ *
+ * THE FORM IS DECIDED BY THE TERMINAL, exactly as `OverlayFrame` decides it
+ * (`cols >= BORDERLESS_COLS`), so this function takes the same `cols` the frame
+ * receives. Passing the panel's own width instead would make a 46-cell drawer on
+ * a 200-column terminal fall back to the rail form for ever, because 46 < 48.
+ */
+export function shortcutPanelContentCells(cols) {
+    const width = shortcutPanelWidth(cols);
+    const chrome = Math.max(0, Math.floor(cols)) >= 48
+        ? SHORTCUT_PANEL_LIMITS.boxCells
+        : SHORTCUT_PANEL_LIMITS.railCells;
+    return Math.max(0, width - chrome);
+}
+/**
+ * Derive the two columns (P0-1).
+ *
+ * `stacked` is a GLOBAL flag only when the keyword column is too narrow for any
+ * keyword at all; otherwise stacking is decided per row, so one long binding
+ * (`Shift+Up / Shift+Down`, 20 cells) does not cost the other thirty rows a line.
+ */
+export function shortcutColumns(cols, entries, glyphs) {
+    const width = shortcutPanelWidth(cols);
+    const available = shortcutPanelContentCells(cols);
+    // The cursor glyph owns one cell on the selected row, so it comes out of the
+    // LIST's budget rather than out of the keyword's.
+    const cursorCells = stringWidth(glyphs.cursor) > 0 ? 1 : 0;
+    const listCells = Math.max(0, available - cursorCells);
+    const longest = widestKeysCells(entries);
+    const share = Math.ceil(listCells * SHORTCUT_PANEL_LIMITS.keyColumnShare);
+    const keyCells = Math.min(longest, Math.max(0, share));
+    const keywordCells = Math.max(0, listCells - keyCells - SHORTCUT_PANEL_LIMITS.keyGapCells);
+    return {
+        width,
+        available,
+        listCells,
+        keyCells,
+        keywordCells,
+        stacked: keywordCells < SHORTCUT_PANEL_LIMITS.keywordMinCells,
+    };
+}
+/** `12s ago` / `3m ago` / `1h ago`, without introducing a second clock. */
+function ageLabel(ageMs) {
+    if (ageMs === null || !Number.isFinite(ageMs) || ageMs < 0)
+        return '';
+    const seconds = Math.floor(ageMs / 1000);
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    return `${Math.floor(minutes / 60)}h ago`;
+}
+/** The task section's status line, or the reason there is none. */
+function taskStatusLine(task, glyphs) {
+    if (!task.enabled)
+        return 'task summary is off (config taskSummary.enabled)';
+    if (task.pending)
+        return 'summarizing' + ` ${glyphs.midDot} ` + 'r refresh';
+    if (task.text === null) {
+        const reason = task.reason === null ? '' : ` ${glyphs.midDot} ${task.reason}`;
+        return `no summary yet${reason} ${glyphs.midDot} r refresh`;
+    }
+    const age = ageLabel(task.ageMs);
+    const who = task.tone === 'fallback' ? 'fallback' : task.by;
+    const parts = [who, age].filter((part) => part.length > 0);
+    return `${parts.join(` ${glyphs.midDot} `)} ${glyphs.midDot} r refresh`;
+}
+/**
+ * The footer, built by DROPPING clauses from the right (never by re-wording).
+ *
+ * `Esc close` is never dropped: it is the one thing a user must be able to find on
+ * a terminal too narrow to explain anything else. The rest go in a fixed order so
+ * the footer is stable across resizes instead of shuffling.
+ */
+export function shortcutFooter(cols, glyphs, opts = { canRefresh: true }) {
+    const available = shortcutPanelContentCells(cols);
+    // SHORT SPELLINGS ON PURPOSE. The drawer is 30 cells wide at 80 columns and 46 at
+    // most, so a footer that spelled `Up/Down select · PgUp/PgDn page · d details ·
+    // r refresh · Esc close` (67 cells) would lose three clauses at EVERY width - the
+    // ladder would never be exercised, only its last rung. These forms fit four of the
+    // five at the maximum width and still keep the one that matters at the minimum.
+    const clauses = [
+        'Up/Dn',
+        'PgUp/PgDn',
+        'd details',
+        ...(opts.canRefresh ? ['r refresh'] : []),
+        'Esc close',
+    ];
+    // Drop order: the least essential clause first. `Esc close` is never dropped - on a
+    // terminal too narrow to explain anything else, that is the one key a user must be
+    // able to find.
+    const droppable = ['r refresh', 'Up/Dn', 'PgUp/PgDn', 'd details'];
+    const sep = ` ${glyphs.midDot} `;
+    let kept = [...clauses];
+    while (kept.length > 1 && stringWidth(kept.join(sep)) > available) {
+        const victim = droppable.find((clause) => kept.includes(clause));
+        if (victim === undefined)
+            break;
+        kept = kept.filter((clause) => clause !== victim);
+    }
+    return kept.join(sep);
+}
+/**
+ * Build every row the drawer can show, and derive the window from the cursor.
+ *
+ * @param input.cols Terminal columns (the frame receives the same number).
+ * @param input.rows Body rows inside the frame - `overlayBodyRows(maxRows, cols)`.
+ * @param input.cursor Index into `input.entries`; clamped, never trusted.
+ */
+export function buildShortcutRows(input) {
+    const { glyphs } = input;
+    const columns = shortcutColumns(input.cols, input.entries, glyphs);
+    const rows = [];
+    const push = (row) => { rows.push(row); };
+    const wrapped = (text, cells, maxRows) => wrapCells(text, cells, maxRows, glyphs.ellipsis).lines;
+    // --- title ---------------------------------------------------------------
+    // NO TITLE ROW (deviation from appendix A's sketch, recorded in `spec.md`'s
+    // implementation-issues note): `OverlayFrame` already draws `title` as chrome,
+    // and the `details on|off` marker rides there instead - one string on a row
+    // that is already paid for, rather than a whole body row spent on it.
+    // --- task section (at most `taskMaxRows`) --------------------------------
+    const statusText = () => fitCells(taskStatusLine(input.task, glyphs), columns.available, glyphs.ellipsis);
+    if (!input.task.enabled) {
+        push({ kind: 'task', text: statusText(), entryId: null, tone: 'dim' });
+    }
+    else if (input.task.text !== null) {
+        for (const line of wrapped(input.task.text, columns.available, 1)) {
+            push({
+                kind: 'task',
+                text: line,
+                entryId: null,
+                tone: input.task.tone === 'fallback' ? 'dim' : 'primary',
+            });
+        }
+        if (input.rows >= SHORTCUT_PANEL_LIMITS.groupHeaderMinRows) {
+            push({ kind: 'task', text: statusText(), entryId: null, tone: 'muted' });
+        }
+    }
+    else {
+        push({ kind: 'task', text: statusText(), entryId: null, tone: 'muted' });
+    }
+    // --- rule ----------------------------------------------------------------
+    if (input.rows >= SHORTCUT_PANEL_LIMITS.groupHeaderMinRows) {
+        push({
+            kind: 'rule',
+            text: glyphs.hrule.repeat(columns.available),
+            entryId: null,
+            tone: 'muted',
+        });
+    }
+    // --- entries -------------------------------------------------------------
+    const entries = input.entries;
+    const total = entries.length;
+    const cursor = total === 0 ? 0 : Math.min(total - 1, Math.max(0, Math.floor(input.cursor)));
+    /** Indent shared by the detail lines and a stacked keyword. */
+    const indent = ' '.repeat(SHORTCUT_PANEL_LIMITS.detailIndent);
+    let cursorRow = 0;
+    const groupHeaders = input.rows >= SHORTCUT_PANEL_LIMITS.groupHeaderMinRows;
+    let currentGroup = '';
+    entries.forEach((entry, index) => {
+        const selected = index === cursor;
+        if (groupHeaders && entry.group !== currentGroup) {
+            currentGroup = entry.group;
+            const title = SHORTCUT_GROUPS.find((group) => group.id === entry.group)?.title ?? '';
+            push({
+                kind: 'group',
+                text: fitCells(title, columns.available, glyphs.ellipsis),
+                entryId: null,
+                tone: 'accent',
+            });
+        }
+        const usable = input.entryAvailable ? input.entryAvailable(entry) : true;
+        const tone = usable ? (selected ? 'primary' : 'muted') : 'dim';
+        const lead = selected ? glyphs.cursor : ' ';
+        if (selected)
+            cursorRow = rows.length;
+        const keyRoom = columns.keyCells;
+        if (columns.stacked || stringWidth(entry.keys) > keyRoom) {
+            push({
+                kind: 'stacked',
+                text: fitCells(`${lead}${entry.keys}`, columns.listCells, glyphs.ellipsis),
+                entryId: entry.id,
+                tone,
+            });
+            push({
+                kind: 'keyword',
+                text: indent
+                    + fitCells(entry.keyword, Math.max(0, columns.available - SHORTCUT_PANEL_LIMITS.detailIndent), glyphs.ellipsis),
+                entryId: entry.id,
+                tone: 'muted',
+            });
+        }
+        else {
+            const keyCell = padCells(`${lead}${entry.keys}`, 1 + keyRoom);
+            const keyword = fitCells(entry.keyword, columns.keywordCells, glyphs.ellipsis);
+            push({
+                kind: 'entry',
+                text: `${keyCell}${' '.repeat(SHORTCUT_PANEL_LIMITS.keyGapCells)}${keyword}`,
+                entryId: entry.id,
+                tone,
+            });
+        }
+        if (!selected)
+            return;
+        // The detail line belongs to the selected row and is the reason the window is
+        // derived from the cursor rather than from an independent offset (P1-7).
+        const detailRoom = Math.max(0, columns.available - SHORTCUT_PANEL_LIMITS.detailIndent);
+        // THE UNAVAILABILITY SENTENCE COMES FIRST, not last: the detail line is capped at
+        // two rows, and a reason appended after a long explanation is the first thing the
+        // cap removes - leaving a dim row with no explanation, which is the one outcome
+        // this line exists to prevent.
+        const detail = usable
+            ? entry.detail
+            : `Unavailable now - ${input.unavailableReason ?? 'not in this mode'}. ${entry.detail}`;
+        for (const line of wrapped(detail, detailRoom, SHORTCUT_PANEL_LIMITS.detailMaxRows)) {
+            push({ kind: 'detail', text: `${indent}${line}`, entryId: entry.id, tone: 'dim' });
+        }
+    });
+    // --- the window ----------------------------------------------------------
+    const height = Math.max(1, Math.floor(Number.isFinite(input.rows) ? input.rows : 1));
+    // THE SMALLEST WINDOW CONTAINING THE CURSOR: the cursor sits on the last visible
+    // row while scrolling down and the window never starts past it.
+    const desired = Math.max(0, cursorRow - height + 1);
+    const window = sliceWindow(rows.length, desired, height);
+    return {
+        rows,
+        window,
+        cursorRow,
+        total: rows.length,
+        hint: shortcutFooter(input.cols, glyphs, {
+            canRefresh: input.task.enabled && !input.task.pending,
+        }),
+    };
+}

package/dist/ui/layout/status-detail-layout.js

@@ -17,7 +17,11 @@ export function planStatusDetail(input) {
     const budget = Math.max(0, Math.floor(status.columns) - 1);
     const escape = escapeClause({ ...hints, escapeAction: status.escapeAction });
     const reserved = [...(escape ? [statusField('escape', escape, 'warning')] : []),
-        statusField('toggle', hints.overlay ? 'Details on' : '^G less')];
+        // THE TOGGLE HINT NAMES A TWO-KEY PATH NOW (tui-shortcut-drawer-and-task-summary
+        // D-6). This row said `^G less` because `Ctrl+G` collapsed it directly; the key
+        // opens the drawer instead, and `d` inside the drawer is what collapses this row.
+        // Saying `^G less` would be a hint that does nothing.
+        statusField('toggle', hints.overlay ? 'Details on' : '^G then d')];
     const fields = [];
     const add = (candidate) => {
         if (statusLinePlan([...fields, candidate, ...reserved]).cells <= budget)

package/dist/ui/layout/task-summary-cell.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The task-summary cell's decisions (tui-shortcut-drawer-and-task-summary §6.3).
+ *
+ * ASCII ONLY: `src/ui/**` is inside the glyph scanner's scope.
+ *
+ * WHY THIS IS A SEPARATE MODULE FROM `header-left.ts`: the planner answers "how
+ * wide is the cell", this one answers "should there be a cell at all, and what is
+ * in it". The second question is the trigger rule (D-7) and it has to be testable
+ * without a renderer - `task-summary-app.test.tsx` pins "one call per session" by
+ * calling THIS function, not by counting renders.
+ *
+ * THE TRIGGER IS NARROW ON PURPOSE. A header label is an identity strip, not a
+ * live subtitle: refreshing it every turn would flicker, cost money, and teach the
+ * user to distrust the one thing on the row that is not a status field.
+ */
+/** Why no summary call was started. Every branch is a branch the tests can name. */
+export type TaskSummarySkipReason = 'already-set' | 'no-anchor' | 'not-user-initiated' | 'disabled' | 'pending';
+/**
+ * D-7's trigger rule.
+ *
+ * FIVE INPUTS, ONE ANSWER. `userInitiated` is the second guard on the same fact
+ * `submitMessage` already knows (`opts.userInitiated !== false`): an automatic
+ * continuation is not a new task, and paying for a label for it would spend the
+ * user's money to describe work they did not start.
+ */
+export declare function shouldSummarize(input: {
+    anchor: string;
+    hasSummary: boolean;
+    pending: boolean;
+    enabled: boolean;
+    userInitiated: boolean;
+}): {
+    start: true;
+} | {
+    start: false;
+    reason: TaskSummarySkipReason;
+};
+/**
+ * The drawer's `Task` section, flattened from the view state so the pure layout
+ * module never learns what a `ViewState` is.
+ */
+export declare function taskSectionFrom(input: {
+    view: {
+        text: string;
+        tone: 'model' | 'fallback';
+        reason: string | null;
+        by: string;
+        at: number;
+    } | null;
+    pending: boolean;
+    enabled: boolean;
+    now: number;
+}): {
+    text: string | null;
+    tone: 'model' | 'fallback' | null;
+    reason: string | null;
+    by: string;
+    ageMs: number | null;
+    enabled: boolean;
+    pending: boolean;
+};

package/dist/ui/layout/task-summary-cell.js

@@ -0,0 +1,65 @@
+/**
+ * The task-summary cell's decisions (tui-shortcut-drawer-and-task-summary §6.3).
+ *
+ * ASCII ONLY: `src/ui/**` is inside the glyph scanner's scope.
+ *
+ * WHY THIS IS A SEPARATE MODULE FROM `header-left.ts`: the planner answers "how
+ * wide is the cell", this one answers "should there be a cell at all, and what is
+ * in it". The second question is the trigger rule (D-7) and it has to be testable
+ * without a renderer - `task-summary-app.test.tsx` pins "one call per session" by
+ * calling THIS function, not by counting renders.
+ *
+ * THE TRIGGER IS NARROW ON PURPOSE. A header label is an identity strip, not a
+ * live subtitle: refreshing it every turn would flicker, cost money, and teach the
+ * user to distrust the one thing on the row that is not a status field.
+ */
+/**
+ * D-7's trigger rule.
+ *
+ * FIVE INPUTS, ONE ANSWER. `userInitiated` is the second guard on the same fact
+ * `submitMessage` already knows (`opts.userInitiated !== false`): an automatic
+ * continuation is not a new task, and paying for a label for it would spend the
+ * user's money to describe work they did not start.
+ */
+export function shouldSummarize(input) {
+    // ORDER IS THE DOCUMENTED PRECEDENCE: a prompt that is not a task cannot start
+    // one even when everything else says yes, and an OFF feature must report the
+    // switch rather than a downstream reason the user cannot act on.
+    if (!input.enabled)
+        return { start: false, reason: 'disabled' };
+    if (input.anchor.trim().length === 0)
+        return { start: false, reason: 'no-anchor' };
+    if (input.hasSummary)
+        return { start: false, reason: 'already-set' };
+    if (input.pending)
+        return { start: false, reason: 'pending' };
+    // ITS OWN REASON, not `no-anchor`: an automatic continuation HAS an anchor, it is
+    // simply not a new task, and a skip reason a maintainer cannot trust is worse than
+    // no reason at all (review fix RF-3).
+    if (!input.userInitiated)
+        return { start: false, reason: 'not-user-initiated' };
+    return { start: true };
+}
+/**
+ * The drawer's `Task` section, flattened from the view state so the pure layout
+ * module never learns what a `ViewState` is.
+ */
+export function taskSectionFrom(input) {
+    if (input.view === null) {
+        return {
+            text: null, tone: null, reason: null, by: '', ageMs: null,
+            enabled: input.enabled, pending: input.pending,
+        };
+    }
+    return {
+        text: input.view.text,
+        tone: input.view.tone,
+        reason: input.view.reason,
+        by: input.view.by,
+        // The age is computed from the view's own timestamp and the caller's clock,
+        // so the drawer never introduces a second one.
+        ageMs: input.now >= input.view.at ? input.now - input.view.at : null,
+        enabled: input.enabled,
+        pending: input.pending,
+    };
+}

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

@@ -13,5 +13,17 @@
 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[];

package/dist/ui/overlays/HelpOverlay.js

@@ -20,7 +20,16 @@ function keyRows(times, native = false) {
         .map(([key, description]) => key === 'PgUp / PgDn' ? [key, 'Page through an open overlay'] : [key, description])
         .concat([['Scroll', 'Use your terminal (wheel, Shift+PgUp, scrollbar, search)']]);
 }
-function allKeyRows(times) {
+/**
+ * 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 function allKeyRows(times) {
     return [
         ['Enter', 'Submit (idle) / queue steering (running); re-pins to the newest output'],
         ['Alt+Enter / Shift+Enter', 'Newline when supported; the host may intercept either binding'],
@@ -57,7 +66,15 @@ function allKeyRows(times) {
         // went - and because `^K` is only advertised in the expanded header row.
         ['Ctrl+K', 'Agent kits: pick a preset for this session (see /kit)'],
         ['Alt+K', 'Delete from the cursor to the end of the line (was Ctrl+K)'],
-        ['Ctrl+G', 'Expand/collapse status details; disabled while an overlay is open'],
+        // Ctrl+G OPENED THE STATUS DETAIL ROW UNTIL THE DRAWER TOOK THE KEY
+        // (tui-shortcut-drawer-and-task-summary D-6). The detail row did not disappear,
+        // it moved to `d` inside this panel, and saying so here is the only place a
+        // user's muscle memory can find out.
+        ['Ctrl+G', 'Keyboard drawer: every shortcut, with keywords (d = status details)'],
+        // Ctrl+O WAS MISSING FROM THIS TABLE ENTIRELY while it worked in the app, which
+        // is exactly the gap the drawer's reverse drift guard exists to force closed: a
+        // key that only exists in the code is a key only its author knows.
+        ['Ctrl+O', 'Expand the newest tool output (native mode reprints it as a block)'],
         // The board's key is listed HERE and in the team table below: the roster shows
         // `ctrl+b` only on a terminal wide enough for the hint cell, and a key a user can
         // only learn from a wide terminal is a key the rest never discover (AC-18).
@@ -92,6 +109,12 @@ function allKeyRows(times) {
 }
 const COMMANDS = [
     ['/help', 'Show this help'],
+    // THE DRAWER'S COMMAND-SIDE ENTRY (tui-shortcut-drawer-and-task-summary §4.7).
+    // Listed here as well as behind Ctrl+G, because a key is unreachable in a script
+    // and `/keys` is how a paste or a screen reader gets to the same list.
+    ['/keys [query]', 'List every shortcut in the drawer; a query pre-filters it'],
+    ['/task', 'Show the header task summary: what it says, where it came from'],
+    ['/task refresh', 'Regenerate the header task summary from the last prompt'],
     ['/model', 'Open the model picker'],
     ['/settings', 'Open the settings screen'],
     ['/plan [on|off|status]', 'Toggle plan mode (same as Shift+Tab)'],
@@ -172,6 +195,10 @@ const FAST_ROWS = [
     ['--fast / --no-fast', 'Start a session with the tier on or off (also ARAGON_FAST=1)'],
     ['<fast_review>', 'An automated second opinion from the fast model - advice, not the user'],
 ];
+/** The slash-command table's key column, for the same guard (commands are not keys). */
+export function allCommandRows() {
+    return COMMANDS;
+}
 /** Build the overlay's rows. Exported so `app.test.tsx` can count them. */
 export function helpRows(theme, caps, native = false) {
     const glyphs = pickGlyphs(caps);

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

@@ -0,0 +1,39 @@
+/**
+ * The keyboard drawer (tui-shortcut-drawer-and-task-summary §4.5).
+ *
+ * ASCII ONLY: `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * IT OWNS NO CHROME AND NO ARITHMETIC. `OverlayFrame` draws the frame, the
+ * window and the position indicator; `shortcut-panel-layout.ts` decides the
+ * columns, the rows and which window contains the cursor. This component adds two
+ * things and nothing else: its own key handling and the text-run colours. v1
+ * planned 260 lines that re-implemented the frame's windowing and clamping - a
+ * second source of truth for the one thing overlays have already been rewritten
+ * once to unify.
+ *
+ * IT DOES NOT REGISTER `Esc` AND DOES NOT TOUCH ANY `ctrl`/`meta` COMBINATION:
+ * `Esc` belongs to `App` (it closes every overlay and cancels the pending
+ * question/plan), and `Ctrl+G` is handled there too. Two listeners both acting on
+ * one byte is how a panel closes twice.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import { type ShortcutTaskSection } from '../layout/shortcut-panel-layout.js';
+export interface ShortcutPanelProps {
+    /** The terminal width, which is what `OverlayFrame` needs to pick its form. */
+    cols: number;
+    maxRows: number;
+    theme: Theme;
+    caps: TermCapabilities;
+    isActive: boolean;
+    native: boolean;
+    running: boolean;
+    /** `/keys <query>` pre-filter. */
+    query?: string;
+    task: ShortcutTaskSection;
+    detailsExpanded: boolean;
+    onToggleDetails(): void;
+    onRefresh(): void;
+}
+export declare function ShortcutPanel(props: ShortcutPanelProps): React.ReactElement;