@aragon-agent/cli 0.6.24 → 0.6.26

package/dist/ui/StatusBar.js

@@ -5,6 +5,7 @@ import { Box, Text } from 'ink';
 import { pickGlyphs } from './glyphs.js';
 import { liveSpinner } from './ActivityLine.js';
 import { planPrimaryStatusFields } from './layout/status-layout.js';
+import { planSessionChip } from './layout/session-chip.js';
 /** An invisible leading byte change forces Ink to repaint on Ctrl+L. */
 const redrawChar = (nonce) => nonce % 2 ? String.fromCharCode(0x00a0) : ' ';
 export function StatusBar(props) {
@@ -13,7 +14,15 @@ export function StatusBar(props) {
     const active = phase !== 'idle' || !!props.compactionActive?.inFlight;
     const glyph = pickGlyphs(props.caps).spinnerStill;
     const spinner = active ? liveSpinner(props.reducedMotion ?? false, props.caps) : null;
+    // THE CHIP IS PLANNED FIRST, and the plan then feeds the field budget: the two
+    // cannot disagree about how wide the terminal is if only one of them is asked.
+    const chip = planSessionChip({
+        columns: cols,
+        ...(props.sessionId ? { sessionId: props.sessionId } : {}),
+    });
+    const chipCells = chip.visible ? chip.cells + chip.gap : 0;
     const plan = planPrimaryStatusFields({
+        reserveRight: chipCells,
         columns: cols, phase, pendingCount: props.pendingSteering?.length ?? 0,
         context: props.context, usageTotal: props.usageTotal,
         thinkingLevel: props.thinkingLevel, elapsedMs: props.elapsedMs, tokPerSec: props.tokPerSec,
@@ -29,7 +38,7 @@ export function StatusBar(props) {
     const tones = { normal: props.theme.primary, muted: props.theme.muted,
         warning: props.theme.noticeWarn, error: props.theme.noticeError,
         accent: props.theme.accent };
-    return _jsxs(Box, { width: cols, height: 1, flexShrink: 0, flexDirection: "row", overflow: "hidden", children: [_jsx(Box, { width: 1, flexShrink: 0, children: _jsx(Text, { children: redrawChar(props.redrawNonce ?? 0) }) }), plan.fields.map((item, index) => _jsxs(React.Fragment, { children: [index > 0 && _jsx(Box, { width: plan.separatorCells, flexShrink: 0, children: _jsx(Text, { color: props.theme.muted, children: plan.separator }) }), _jsx(Box, { width: item.cells, flexShrink: 0, children: _jsx(Text, { color: tones[item.tone], wrap: "truncate", children: item.id === 'phase' && active
-                                ? _jsxs(_Fragment, { children: [spinner ?? glyph, item.text.slice(glyph.length)] })
-                                : item.text }) })] }, item.id))] });
+    return _jsxs(Box, { width: cols, height: 1, flexShrink: 0, flexDirection: "row", overflow: "hidden", children: [_jsx(Box, { width: 1, flexShrink: 0, children: _jsx(Text, { children: redrawChar(props.redrawNonce ?? 0) }) }), _jsx(Box, { width: Math.max(0, cols - 1 - chipCells), flexShrink: 0, flexDirection: "row", overflow: "hidden", children: plan.fields.map((item, index) => _jsxs(React.Fragment, { children: [index > 0 && _jsx(Box, { width: plan.separatorCells, flexShrink: 0, children: _jsx(Text, { color: props.theme.muted, children: plan.separator }) }), _jsx(Box, { width: item.cells, flexShrink: 0, children: _jsx(Text, { color: tones[item.tone], wrap: "truncate", children: item.id === 'phase' && active
+                                    ? _jsxs(_Fragment, { children: [spinner ?? glyph, item.text.slice(glyph.length)] })
+                                    : item.text }) })] }, item.id)) }), chip.visible && _jsx(Box, { width: chipCells, flexShrink: 0, justifyContent: "flex-end", overflow: "hidden", children: _jsx(Text, { color: props.theme.muted, wrap: "truncate", children: chip.text }) })] });
 }

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

@@ -14,10 +14,11 @@
  * kind — without it the card renders a hint that does nothing and expands an
  * older tool card instead (C-15 / P1-8 / AC-21).
  *
- * EVERY STRING DESCRIBES THE HISTORY, NEVER THE SCREEN (§6.4 / P2-9). `/clear`
- * empties the transcript view but not `messages`, so this card can legitimately
- * report "112 -> 9 messages" with nine visible rows above it. Nothing here says
- * "above" or "earlier in this transcript".
+ * EVERY STRING DESCRIBES THE HISTORY, NEVER THE SCREEN (§6.4 / P2-9).
+ * `/clear screen` empties the transcript view but not `messages`, so this card
+ * can legitimately report a message count the visible rows do not add up to.
+ * Nothing here says "above" or "earlier in this transcript". `/clear` itself is
+ * the conversation boundary now: it drops the history and this card with it.
  */
 import React from 'react';
 import type { Theme } from '../theme.js';

package/dist/ui/entries/CompactionCard.js

@@ -15,10 +15,11 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  * kind — without it the card renders a hint that does nothing and expands an
  * older tool card instead (C-15 / P1-8 / AC-21).
  *
- * EVERY STRING DESCRIBES THE HISTORY, NEVER THE SCREEN (§6.4 / P2-9). `/clear`
- * empties the transcript view but not `messages`, so this card can legitimately
- * report "112 -> 9 messages" with nine visible rows above it. Nothing here says
- * "above" or "earlier in this transcript".
+ * EVERY STRING DESCRIBES THE HISTORY, NEVER THE SCREEN (§6.4 / P2-9).
+ * `/clear screen` empties the transcript view but not `messages`, so this card
+ * can legitimately report a message count the visible rows do not add up to.
+ * Nothing here says "above" or "earlier in this transcript". `/clear` itself is
+ * the conversation boundary now: it drops the history and this card with it.
  */
 import React from 'react';
 import { Box, Text } from 'ink';

package/dist/ui/layout/header-hints.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The right-hand hint budget for the header row (tui-branch-terminal-shortcut 3.8).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THIS IS A PLANNER AND NOT ANOTHER TERNARY IN THE JSX (R-0-4): the header's
+ * right side used to be one hand-computed width constant (`detailCells = indexHint
+ * ? 32 : 18`). Adding a third affordance to that arithmetic produces either a
+ * clipped hint or a pushed-out word mark on a 72-column terminal, and NO TEST
+ * WOULD SEE IT - the only thing lost is trailing characters. `ui/layout/session-chip.ts`
+ * already set the precedent for the same problem: the chip has to participate in
+ * one width budget rather than be appended and hoped for.
+ *
+ * THE RULE IS ONE COMPARISON. `budget = columns - minLeftCells`, then take the
+ * first ladder rung whose `cells` fits. There is no second magic constant, and the
+ * threshold table in the spec is what that comparison WORKS OUT TO, not an extra
+ * branch.
+ *
+ * WHY `minLeftCells` IS 24: the word mark is 13 cells and `provider:model` + cwd +
+ * the key symbol need at least 11 more to stay readable. It is lower than
+ * `status-layout`'s 34 because the top-left half has a brand to lose while the
+ * bottom-left half has a phase that must not disappear.
+ */
+/**
+ * Bounds for the hint budget.
+ *
+ * WHY THEY LIVE IN THIS FILE (R-21, accepted): `CLAUDE.md`'s general rule is that
+ * structural bounds live in the subsystem's `limits.ts`, and `ui/layout/` has none
+ * - `budget.ts` keeps `HINT_MIN_ROWS` beside its own module for the same reason.
+ * This module has exactly one consumer. If `ui/layout/` ever grows a real
+ * `limits.ts`, these three constants should move there together; this comment is
+ * that future migration's note.
+ */
+export declare const HEADER_HINT_LIMITS: {
+    /** Cells the LEFT half of the header must keep (`AragonAgent` is 13 of them). */
+    readonly minLeftCells: 24;
+    /** Fixed spacing between two hint clauses. */
+    readonly gapCells: 2;
+};
+export type HeaderHintId = 'branch' | 'index' | 'detail';
+export interface HeaderHintClause {
+    id: HeaderHintId;
+    text: string;
+}
+export interface HeaderHintPlan {
+    /** Clauses left to right (including the overlay's `Details on/off` replacement). */
+    clauses: HeaderHintClause[];
+    /** The whole right-hand string, scroll chip included with its trailing spacing. */
+    text: string;
+    /** Total cells of the right column; `Header` uses it to size the left one. */
+    cells: number;
+    /** Cells taken by the scroll chip (0 when there is none). */
+    scrollCells: number;
+    /** True while an overlay owns the keyboard: only the detail word remains. */
+    detailsOnly: boolean;
+}
+/**
+ * Plan the right-hand hints.
+ *
+ * The four inputs are exactly the props `Header` already receives - the call site
+ * does not change, only the arithmetic behind it (spec 3.11 step 5).
+ */
+export declare function planHeaderHints(input: {
+    columns: number;
+    statusExpanded: boolean;
+    overlayOpen: boolean;
+    scrolledLines: number;
+}): HeaderHintPlan;

package/dist/ui/layout/header-hints.js

@@ -0,0 +1,138 @@
+/**
+ * The right-hand hint budget for the header row (tui-branch-terminal-shortcut 3.8).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THIS IS A PLANNER AND NOT ANOTHER TERNARY IN THE JSX (R-0-4): the header's
+ * right side used to be one hand-computed width constant (`detailCells = indexHint
+ * ? 32 : 18`). Adding a third affordance to that arithmetic produces either a
+ * clipped hint or a pushed-out word mark on a 72-column terminal, and NO TEST
+ * WOULD SEE IT - the only thing lost is trailing characters. `ui/layout/session-chip.ts`
+ * already set the precedent for the same problem: the chip has to participate in
+ * one width budget rather than be appended and hoped for.
+ *
+ * THE RULE IS ONE COMPARISON. `budget = columns - minLeftCells`, then take the
+ * first ladder rung whose `cells` fits. There is no second magic constant, and the
+ * threshold table in the spec is what that comparison WORKS OUT TO, not an extra
+ * branch.
+ *
+ * WHY `minLeftCells` IS 24: the word mark is 13 cells and `provider:model` + cwd +
+ * the key symbol need at least 11 more to stay readable. It is lower than
+ * `status-layout`'s 34 because the top-left half has a brand to lose while the
+ * bottom-left half has a phase that must not disappear.
+ */
+/**
+ * Bounds for the hint budget.
+ *
+ * WHY THEY LIVE IN THIS FILE (R-21, accepted): `CLAUDE.md`'s general rule is that
+ * structural bounds live in the subsystem's `limits.ts`, and `ui/layout/` has none
+ * - `budget.ts` keeps `HINT_MIN_ROWS` beside its own module for the same reason.
+ * This module has exactly one consumer. If `ui/layout/` ever grows a real
+ * `limits.ts`, these three constants should move there together; this comment is
+ * that future migration's note.
+ */
+export const HEADER_HINT_LIMITS = {
+    /** Cells the LEFT half of the header must keep (`AragonAgent` is 13 of them). */
+    minLeftCells: 24,
+    /** Fixed spacing between two hint clauses. */
+    gapCells: 2,
+};
+/** The verbatim clause text (spec 3.8, appendix A). */
+const BRANCH_CLAUSE = { collapsed: '^L branch', expanded: '^L new branch' };
+const INDEX_CLAUSE = { collapsed: '^I Index', expanded: '^I build index' };
+const DETAIL_CLAUSE = { collapsed: '^G more', expanded: '^G less' };
+/** L3 gives the key name and nothing else: discoverability at the last width. */
+const BRANCH_KEY_ONLY = '^L';
+/** Overlay wording, kept exactly as `Header.tsx` had it. */
+const DETAILS_ON = 'Details on';
+const DETAILS_OFF = 'Details off';
+/** Above this, the chip stops counting and saturates (`^9999+`), as it always has. */
+const SCROLL_CHIP_MAX = 9999;
+/**
+ * Plan the right-hand hints.
+ *
+ * The four inputs are exactly the props `Header` already receives - the call site
+ * does not change, only the arithmetic behind it (spec 3.11 step 5).
+ */
+export function planHeaderHints(input) {
+    // NORMALISED HERE, NOT TRUSTED (R-14). `Header` defaults to 80, but a test or a
+    // future caller may pass anything; `budget.ts::dimension()` already set the rule
+    // (non-finite or < 1 falls back, everything else floors) and this follows it.
+    const columns = normalizeDimension(input.columns, 80);
+    const scrolledLines = Math.max(0, Math.floor(normalizeDimension(input.scrolledLines, 0)));
+    const scrollCells = scrollChip(scrolledLines, input.overlayOpen);
+    if (input.overlayOpen) {
+        // THE OVERLAY OWNS THE KEYBOARD, so every key hint disappears (D-14's sibling
+        // rule, unchanged from the old JSX). The scroll chip stays: it is a position
+        // indicator, not an affordance.
+        const detail = input.statusExpanded ? DETAILS_ON : DETAILS_OFF;
+        return buildPlan([{ id: 'detail', text: detail }], scrollCells, true);
+    }
+    const ladder = ladderFor(input.statusExpanded);
+    const budget = columns - HEADER_HINT_LIMITS.minLeftCells;
+    for (const rung of ladder) {
+        const plan = buildPlan(rung, scrollCells, false);
+        if (plan.cells <= budget)
+            return plan;
+    }
+    // L4 IS UNCONDITIONAL: `^G` is the only entry in this table that may never be
+    // dropped - it is how a user who hid the status detail fields gets them back.
+    // A header narrower than the last rung still renders; the LEFT column is what
+    // shrinks (to zero), and `overflow="hidden"` keeps that from overflowing.
+    return buildPlan(ladder[ladder.length - 1] ?? [], scrollCells, false);
+}
+/** The four rungs, widest first. Built per call because the widths are text-derived. */
+function ladderFor(statusExpanded) {
+    const branch = {
+        id: 'branch',
+        text: statusExpanded ? BRANCH_CLAUSE.expanded : BRANCH_CLAUSE.collapsed,
+    };
+    const index = {
+        id: 'index',
+        text: statusExpanded ? INDEX_CLAUSE.expanded : INDEX_CLAUSE.collapsed,
+    };
+    const detail = {
+        id: 'detail',
+        text: statusExpanded ? DETAIL_CLAUSE.expanded : DETAIL_CLAUSE.collapsed,
+    };
+    return [
+        [branch, index, detail],
+        [branch, detail],
+        [{ id: 'branch', text: BRANCH_KEY_ONLY }, detail],
+        [detail],
+    ];
+}
+/**
+ * Compose the final string. The chip carries its OWN trailing spacing and is the
+ * only source of it (R-8): one space while an overlay is open, two otherwise -
+ * copied byte for byte from the expression the header already used.
+ */
+function buildPlan(clauses, scrollChipText, detailsOnly) {
+    const body = clauses.map((clause) => clause.text).join(' '.repeat(HEADER_HINT_LIMITS.gapCells));
+    const text = scrollChipText.length > 0 ? `${scrollChipText}${body}` : body;
+    return {
+        clauses,
+        text,
+        cells: text.length,
+        scrollCells: scrollChipText.length,
+        detailsOnly,
+    };
+}
+/**
+ * `^<n>` plus its trailing spacing, or `''`.
+ *
+ * THE SPACING IS PART OF THE CHIP, not something `Header` adds afterwards: with two
+ * sources of spacing a reviewer has to read two files to answer "how wide is the
+ * chip", and the overlay's single-space case lived in the JSX as a ternary nobody
+ * would think to check.
+ */
+function scrollChip(scrolledLines, overlayOpen) {
+    if (scrolledLines <= 0)
+        return '';
+    const label = scrolledLines > SCROLL_CHIP_MAX ? `^${SCROLL_CHIP_MAX}+` : `^${scrolledLines}`;
+    return label + (overlayOpen ? ' ' : '  ');
+}
+/** The `budget.ts::dimension()` rule, local because that helper is not exported. */
+function normalizeDimension(value, fallback) {
+    return Number.isFinite(value) && value >= 1 ? Math.floor(value) : fallback;
+}

package/dist/ui/layout/session-chip.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The session-id chip: pure width planning, no JSX
+ * (tui-session-id-resume §3.9 / D-11 / D-12).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY A PLANNER AND NOT A STYLED `<Text>`: the status bar is a cell-by-cell
+ * measured row with a six-rung degradation ladder (`status-layout.ts`), not a
+ * flex layout.
+ * Anything positioned "just to the right" pushes the left half over or covers
+ * `phase`, and `phase` is the field a user needs while a run is in flight. The
+ * chip therefore spends cells out of the SAME budget as every other field.
+ *
+ * THE ID IS NEVER TRUNCATED (D-12). A truncated id produces a `--resume` command
+ * that is guaranteed to fail, which is strictly worse than showing nothing: the
+ * rungs below are, in order, "drop the label" and only then "hide the whole
+ * chip", and `/session` reports the full id at any width.
+ */
+export declare const SESSION_CHIP_LIMITS: {
+    /** The same threshold `Header.tsx` uses for its `^I Index` hint. */
+    readonly labelMinCols: 72;
+    /** Blank cells between the last status field and the chip. */
+    readonly gapCells: 2;
+    /**
+     * The tightest rung's worst-case width for the fields on the LEFT, summed:
+     * phase glyph(1)+label(4)=5, sep 1 -> 6, deferred mode 'C>B' 3 -> 9,
+     * sep 1 -> 10, 'C'+'~999%' 6 -> 16, sep 1 -> 17, thinking code 1 -> 18,
+     * sep 1 -> 19, '>99M/s' 6 -> 25, sep 1 -> 26, '>999d' 5 -> 31.
+     *
+     * 34 IS A FLOOR ROUNDED UP, not a measurement: over-estimating hides the chip
+     * one column early, which is invisible; under-estimating lets the chip eat the
+     * phase field, which is not.
+     */
+    readonly minStatusCells: 34;
+};
+export interface SessionChipPlan {
+    visible: boolean;
+    text: string;
+    cells: number;
+    gap: number;
+}
+/**
+ * Plan the chip for `columns` and this session's id.
+ *
+ * Inputs are the same ones the status row already has, so the two plans cannot
+ * disagree about the terminal: `StatusBar` computes `chip` first and hands
+ * `chip.cells + chip.gap` to `planPrimaryStatusFields` as `reserveRight`.
+ */
+export declare function planSessionChip(input: {
+    columns: number;
+    sessionId?: string | null;
+}): SessionChipPlan;

package/dist/ui/layout/session-chip.js

@@ -0,0 +1,64 @@
+/**
+ * The session-id chip: pure width planning, no JSX
+ * (tui-session-id-resume §3.9 / D-11 / D-12).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY A PLANNER AND NOT A STYLED `<Text>`: the status bar is a cell-by-cell
+ * measured row with a six-rung degradation ladder (`status-layout.ts`), not a
+ * flex layout.
+ * Anything positioned "just to the right" pushes the left half over or covers
+ * `phase`, and `phase` is the field a user needs while a run is in flight. The
+ * chip therefore spends cells out of the SAME budget as every other field.
+ *
+ * THE ID IS NEVER TRUNCATED (D-12). A truncated id produces a `--resume` command
+ * that is guaranteed to fail, which is strictly worse than showing nothing: the
+ * rungs below are, in order, "drop the label" and only then "hide the whole
+ * chip", and `/session` reports the full id at any width.
+ */
+import stringWidth from 'string-width';
+export const SESSION_CHIP_LIMITS = {
+    /** The same threshold `Header.tsx` uses for its `^I Index` hint. */
+    labelMinCols: 72,
+    /** Blank cells between the last status field and the chip. */
+    gapCells: 2,
+    /**
+     * The tightest rung's worst-case width for the fields on the LEFT, summed:
+     * phase glyph(1)+label(4)=5, sep 1 -> 6, deferred mode 'C>B' 3 -> 9,
+     * sep 1 -> 10, 'C'+'~999%' 6 -> 16, sep 1 -> 17, thinking code 1 -> 18,
+     * sep 1 -> 19, '>99M/s' 6 -> 25, sep 1 -> 26, '>999d' 5 -> 31.
+     *
+     * 34 IS A FLOOR ROUNDED UP, not a measurement: over-estimating hides the chip
+     * one column early, which is invisible; under-estimating lets the chip eat the
+     * phase field, which is not.
+     */
+    minStatusCells: 34,
+};
+/** `{visible:false}` - the shape every caller can cheaply branch on. */
+const HIDDEN = { visible: false, text: '', cells: 0, gap: 0 };
+/**
+ * Plan the chip for `columns` and this session's id.
+ *
+ * Inputs are the same ones the status row already has, so the two plans cannot
+ * disagree about the terminal: `StatusBar` computes `chip` first and hands
+ * `chip.cells + chip.gap` to `planPrimaryStatusFields` as `reserveRight`.
+ */
+export function planSessionChip(input) {
+    // No identity (the default build, a test, or a host with no session) is the
+    // `undefined` case, and it must cost nothing: reserveRight stays 0 and the
+    // status row's output is byte-identical to the pre-feature build (I-6).
+    if (!input.sessionId)
+        return HIDDEN;
+    const columns = Number.isFinite(input.columns) ? Math.floor(input.columns) : 80;
+    const id = input.sessionId;
+    const gap = SESSION_CHIP_LIMITS.gapCells;
+    const fits = (text) => columns - 1 - gap - stringWidth(text) >= SESSION_CHIP_LIMITS.minStatusCells;
+    // Widest form first, then drop the label, then hide: the order is the decision.
+    const labelled = `id ${id}`;
+    if (columns >= SESSION_CHIP_LIMITS.labelMinCols && fits(labelled)) {
+        return { visible: true, text: labelled, cells: stringWidth(labelled), gap };
+    }
+    if (fits(id))
+        return { visible: true, text: id, cells: stringWidth(id), gap };
+    return HIDDEN;
+}

package/dist/ui/layout/status-layout.d.ts

@@ -44,6 +44,16 @@ export interface StatusLayoutInput {
         inFlight: boolean;
     };
     scrolledLines?: number;
+    /**
+     * Cells already spent at the RIGHT end of this same row
+     * (tui-session-id-resume 3.10 / I-6).
+     *
+     * The session-id chip is not a layer above this row: it takes its cells out of
+     * the SAME budget, because the row is measured rather than laid out and
+     * anything overlapping it eats `phase` first. ABSENT MEANS 0, which is what
+     * keeps every existing caller's plan byte-identical (I-6).
+     */
+    reserveRight?: number;
 }
 export interface StatusPrimaryInput extends StatusLayoutInput {
     feedback?: StatusFeedback;

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

@@ -113,7 +113,14 @@ function modeFieldText(mode, pendingMode, full) {
 }
 /** Every field survives each width rung; only the redraw carrier is outside this plan. */
 export function planPrimaryStatusFields(input) {
-    const budget = Math.max(0, (Number.isFinite(input.columns) ? Math.floor(input.columns) : 80) - 1);
+    const columns = Number.isFinite(input.columns) ? Math.floor(input.columns) : 80;
+    // GUARDED LIKE `columns` ABOVE, and for the same reason: `Math.max(0, NaN)`
+    // is `NaN`, which would make every `cells > budget` comparison false and
+    // silently pin this row at its widest rung - the opposite of reserving space.
+    const reserved = typeof input.reserveRight === 'number' && Number.isFinite(input.reserveRight)
+        ? Math.max(0, Math.floor(input.reserveRight))
+        : 0;
+    const budget = Math.max(0, columns - 1 - reserved);
     const labels = phaseLabels(input);
     const glyphText = cleanStatusText(input.spinner ?? '-');
     const glyph = stringWidth(glyphText) === 1 ? glyphText : '-';

package/dist/ui/overlays/HelpOverlay.js

@@ -21,7 +21,11 @@ function keyRows(times) {
         // with a draft x2 clears the input and x3 exits; an empty input
         // keeps the previous x2 exit.
         ['Ctrl+C', `Draft: ${times}2 clear input, ${times}3 exit. Empty: ${times}2 exit`],
-        ['Ctrl+L', 'Redraw the frame'],
+        // Ctrl+L IS THE BRANCH KEY NOW (tui-branch-terminal-shortcut D-1) and the
+        // redraw moved to Ctrl+R. Both rows are listed, because the migration is the
+        // one thing an existing user will press by muscle memory and be surprised by.
+        ['Ctrl+L', 'Open a new terminal on this session (the branch gets its own id)'],
+        ['Ctrl+R', 'Redraw the frame'],
         ['Ctrl+T', 'Show/hide thinking (off by default)'],
         ['Ctrl+I', 'Build the project index (bundled skill; asks first; needs keyboard enhancement)'],
         ['Ctrl+G', 'Expand/collapse status details; disabled while an overlay is open'],
@@ -68,11 +72,19 @@ const COMMANDS = [
         'Todo planning: status, switches, the rail, follow-through',
     ],
     ['/tools', 'List active tools'],
-    ['/clear', 'Clear the visible transcript and the todo panel'],
-    ['/reset', 'New conversation'],
+    // `/clear` IS NOT "CLEAR THE SCREEN" ANY MORE (clear-command-context-reset D-1).
+    // Two rows, not one, because the intentions differ: `/clear` starts a NEW
+    // CONVERSATION (interrupt the run, archive the old one, drop the history), while
+    // `/clear screen` only wipes what is on screen. A user who wants the second has
+    // to be able to see that it exists before reaching for the first.
+    ['/clear', 'Start a new conversation: archive, then clear context and transcript'],
+    ['/clear screen', 'Clear the visible transcript only; keeps the conversation'],
+    ['/reset', 'Alias of /clear'],
     ['/cwd [dir]', 'Show or change the tool working directory'],
-    ['/save [file]', 'Save the session to JSON'],
-    ['/resume [file]', 'Load a saved session'],
+    ['/save [file]', 'Export the session to JSON (a file you keep)'],
+    ['/resume [file]', 'Load a saved session; this session moves to a new id'],
+    ['/session [copy|pin]', 'Show this session id and file; copy the resume command; pin it'],
+    ['/branch', 'Same as Ctrl+L: branch into a new terminal'],
     ['/copy', 'Copy last answer; native completion confirmed, OSC 52 request unconfirmed'],
     ['/queue', 'Read every pending message in full; no replay or queue mutation'],
     ['/mouse [on|off]', 'Release the mouse to your terminal, or take it back'],

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

@@ -0,0 +1,23 @@
+import React from 'react';
+import { type ProfileFrameProps } from './ModelProfilePicker.js';
+import { type DiscoveryView } from './model-probe-view.js';
+interface ModelDiscoveryListProps extends ProfileFrameProps {
+    provider: string;
+    /** The draft's current model: the cursor starts on it when the list has it. */
+    currentModel: string;
+    view: DiscoveryView;
+    busy: boolean;
+    onChoose: (model: string) => void;
+    onRetry: () => void;
+    onBack: () => void;
+    onCancelProbe?: () => void;
+}
+/**
+ * The discovered-model page (model-profile-connection-test §3.5).
+ *
+ * Pure display plus input: it receives the discovery outcome and three intents and
+ * issues no request itself. No spinner - the census of animated sites is a closed
+ * list, and this overlay can be open while a run is in flight.
+ */
+export declare function ModelDiscoveryList(props: ModelDiscoveryListProps): React.ReactElement;
+export {};

package/dist/ui/overlays/ModelDiscoveryList.js

@@ -0,0 +1,161 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Text, useInput } from 'ink';
+import { PROBE_LIMITS } from '../../agent/model-probe-limits.js';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { stripPasteFrames } from '../paste-frames.js';
+import { stripEnterFrames } from '../enter-frames.js';
+import { clipProfileText, useProfileScroll } from './ModelProfilePicker.js';
+import { rankCandidates, windowLabel, clipName, LIST_ID_CHARS } from './model-probe-view.js';
+function matches(candidate, query) {
+    const needle = query.toLocaleLowerCase();
+    return candidate.id.toLocaleLowerCase().includes(needle)
+        || candidate.name.toLocaleLowerCase().includes(needle);
+}
+/** One row: id column, name column, window right-aligned inside the frame budget. */
+function listRowText(candidate, cols) {
+    const width = Math.max(20, cols - 8);
+    const label = windowLabel(candidate.contextWindow);
+    const idWidth = Math.max(10, Math.min(LIST_ID_CHARS, width - label.length - 14));
+    const nameWidth = Math.max(4, width - idWidth - label.length - 2);
+    const id = [...candidate.id].slice(0, idWidth).join('').padEnd(idWidth);
+    // `clipName` caps the NAME COLUMN itself, so a vendor that ships a paragraph in
+    // `name` cannot push the window label out of a wide frame either.
+    const name = [...clipName(candidate.name)].slice(0, nameWidth).join('').padEnd(nameWidth);
+    return clipProfileText(`${id} ${name} ${label}`, width);
+}
+/** What the page says when there is no row to select. */
+function emptyLines(busy, provider, view) {
+    if (busy)
+        return [`Discovering ${provider} models...`];
+    if (view.kind === 'discovery' && !view.outcome.ok) {
+        return [view.outcome.detail ?? 'The model list could not be fetched.',
+            'Fix: check the base URL and key, then press r to retry.'];
+    }
+    if (view.kind === 'discovery') {
+        return ['No models returned. Press r to retry, Esc to go back.',
+            'Test the connection for a precise reason.'];
+    }
+    return ['No models discovered yet. Press r to retry, Esc to go back.'];
+}
+function buildRows(props, view, glyphs) {
+    const rows = [];
+    if (view.searchable) {
+        rows.push(_jsxs(Text, { wrap: "truncate", color: props.theme.primary, children: [view.searching ? `${glyphs.caret} ` : '  ', "Search: ", view.query || '(/ to search)'] }, "search"));
+    }
+    if (view.shown.length === 0) {
+        const lines = view.query.length > 0
+            ? [`No model matches "${view.query}". Esc clears the search.`]
+            : emptyLines(props.busy, props.provider, props.view);
+        for (const line of lines) {
+            rows.push(_jsx(Text, { wrap: "truncate", color: props.theme.muted, children: line }, `empty-${rows.length}`));
+        }
+    }
+    view.shown.forEach((candidate, at) => {
+        const focused = at === view.cursor && !view.searching;
+        rows.push(_jsxs(Text, { wrap: "truncate", color: at === view.cursor ? props.theme.accent : props.theme.muted, children: [focused ? `${glyphs.caret} ` : '  ', listRowText(candidate, props.cols)] }, candidate.id));
+    });
+    if (view.truncated) {
+        const total = props.view.kind === 'discovery'
+            ? props.view.outcome.total ?? view.shown.length : view.shown.length;
+        rows.push(_jsx(Text, { wrap: "truncate", color: props.theme.muted, children: `Showing first ${PROBE_LIMITS.maxListedModels} of ${total}. Narrow with search.` }, "truncated"));
+    }
+    return rows;
+}
+/**
+ * The discovered-model page (model-profile-connection-test §3.5).
+ *
+ * Pure display plus input: it receives the discovery outcome and three intents and
+ * issues no request itself. No spinner - the census of animated sites is a closed
+ * list, and this overlay can be open while a run is in flight.
+ */
+export function ModelDiscoveryList(props) {
+    const [index, setIndex] = useState(0);
+    const [query, setQuery] = useState('');
+    const [searching, setSearching] = useState(false);
+    const glyphs = pickGlyphs(props.caps);
+    const candidates = props.view.kind === 'discovery'
+        ? props.view.outcome.models : [];
+    const ranked = rankCandidates(candidates, props.currentModel);
+    const shown = query.length > 0 ? ranked.filter((item) => matches(item, query)) : ranked;
+    const searchable = ranked.length > PROBE_LIMITS.searchThreshold;
+    const cursor = shown.length > 0 ? Math.min(index, shown.length - 1) : 0;
+    // The truncation notice is one row BELOW the last candidate, and `useProfileScroll`
+    // only guarantees the FOCUSED row is visible - the same blind spot that hid the
+    // editor's result rows (RV-P1-3). Standing on the last row therefore widens the
+    // window by one, or `Showing first 400 of ...` could never be read at all.
+    const truncatedNotice = props.view.kind === 'discovery' && props.view.outcome.truncated
+        && shown.length > 0;
+    const revealNotice = truncatedNotice && cursor >= shown.length - 1;
+    const offset = useProfileScroll(props, cursor + (searchable ? 1 : 0) + (revealNotice ? 1 : 0));
+    // Arrival, not every render: when the outcome lands, put the cursor on the model the
+    // draft already names, so "which one am I on" is answerable without scrolling.
+    const arrival = props.view.kind === 'discovery'
+        ? `${props.view.outcome.connectionId}|${ranked.length}` : 'none';
+    useEffect(() => {
+        const at = ranked.findIndex((item) => item.id === props.currentModel.trim());
+        setIndex(at > 0 ? at : 0);
+    }, [arrival]);
+    const move = (delta) => {
+        if (shown.length > 0)
+            setIndex((cursor + delta + shown.length) % shown.length);
+    };
+    useInput((input, key) => {
+        if (props.isActive === false)
+            return;
+        if (key.escape) {
+            if (searching) {
+                setSearching(false);
+                setQuery('');
+                setIndex(0);
+                return;
+            }
+            if (props.busy) {
+                props.onCancelProbe?.();
+                return;
+            }
+            props.onBack();
+            return;
+        }
+        if (key.upArrow || (key.tab && key.shift)) {
+            move(-1);
+            return;
+        }
+        if (key.downArrow || key.tab) {
+            move(1);
+            return;
+        }
+        if (key.return) {
+            const picked = shown[cursor];
+            if (picked)
+                props.onChoose(picked.id);
+            return;
+        }
+        if (searching) {
+            if (key.backspace || key.delete) {
+                setQuery((value) => [...value].slice(0, -1).join(''));
+                setIndex(0);
+            }
+            else if (input && !key.ctrl && !key.meta) {
+                setQuery((value) => value + stripPasteFrames(stripEnterFrames(input)));
+                setIndex(0);
+            }
+            return;
+        }
+        if (input === '/' && searchable) {
+            setSearching(true);
+            setIndex(0);
+            return;
+        }
+        // `r` retries ONLY outside the search state: sharing the key with the query would
+        // turn one typo into a network request (§3.5 / D-16).
+        if (!key.ctrl && !key.meta && input === 'r')
+            props.onRetry();
+    });
+    const hint = props.busy ? 'Esc cancel'
+        : searching ? 'Type search | Enter choose | Esc back'
+            : `Enter choose${searchable ? ' | / search' : ''} | r retry | Esc back`;
+    return _jsx(OverlayFrame, { ...props, scrollOffset: offset, hint: hint, rows: buildRows(props, { query, shown, cursor, searchable, searching,
+            truncated: truncatedNotice }, glyphs), title: `Models | ${props.provider} (${shown.length})` });
+}