@aragon-agent/tui 0.0.0-stage → 0.0.1

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.d.ts

@@ -0,0 +1,9 @@
+import { type ActionHintInput } from '../interaction-hints.js';
+import { type StatusLinePlan, type StatusPrimaryInput } from './status-layout.js';
+export interface StatusDetailInput {
+    status: StatusPrimaryInput;
+    hints: ActionHintInput;
+    model: string;
+    provider: string;
+}
+export declare function planStatusDetail(input: StatusDetailInput): StatusLinePlan;

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

@@ -0,0 +1,79 @@
+import { formatCost, formatTokens, promptTokensOf } from '../../model/agent/usage.js';
+import { actionCandidates, clipStatusText, escapeClause } from '../interaction-hints.js';
+import { isGovernedModeValue, modeWord } from '../governance-status.js';
+import { statusField, statusLinePlan, validContext } from './status-layout.js';
+/**
+ * Uppercase mode word for the details row, mirroring the primary row's field:
+ * same vocabulary (`MODE_LABEL`), same `CUR>PENDING` deferred-switch shape.
+ */
+function detailModeText(mode, pendingMode) {
+    const word = (value) => modeWord(value, true) ?? value.toUpperCase();
+    if (pendingMode)
+        return `${word(mode || 'build')}>${word(pendingMode)}`;
+    return word(mode || 'build');
+}
+export function planStatusDetail(input) {
+    const { status, hints } = 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')] : []),
+        // 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)
+            fields.push(candidate);
+    };
+    if (status.feedback) {
+        const remaining = budget - statusLinePlan(reserved).cells - (reserved.length ? 3 : 0);
+        const text = clipStatusText(status.feedback.text, Math.max(0, remaining));
+        if (text)
+            add(statusField('feedback', text, status.feedback.level === 'error' ? 'error'
+                : status.feedback.level === 'warn' ? 'warning' : 'normal'));
+    }
+    for (const [index, action] of actionCandidates(hints).entries())
+        add(statusField('action-' + index, action));
+    if (status.pendingCount > 0)
+        add(statusField('queue', 'Q' + status.pendingCount));
+    if (status.servicesActive?.live)
+        add(statusField('services', 'Svc' + status.servicesActive.live));
+    if (status.mode || status.pendingMode)
+        add(statusField('mode', detailModeText(status.mode, status.pendingMode), isGovernedModeValue(status.mode) || isGovernedModeValue(status.pendingMode) ? 'govern' : 'accent'));
+    if (validContext(status.context)) {
+        const approximate = status.context.source === 'estimate' || status.context.deltaTokens > 0 ? '~' : '';
+        add(statusField('context', 'Context ' + approximate + formatTokens(status.context.occupied)
+            + '/' + formatTokens(status.context.window) + ' tokens'));
+    }
+    else
+        add(statusField('context', 'Context ? /context'));
+    if (status.speedKnown)
+        add(statusField('average', 'Avg: main output / run time'));
+    add(statusField('usage', 'Session input ' + formatTokens(promptTokensOf(status.usageTotal))
+        + ' output ' + formatTokens(status.usageTotal.outputTokens)));
+    if (Number.isFinite(status.usageTotal.costUsd))
+        add(statusField('cost', 'Cost ' + formatCost(status.usageTotal.costUsd) + ' est'));
+    if (status.teamActive)
+        add(statusField('team', 'Team ' + status.teamActive.running + '/' + status.teamActive.total));
+    if (status.todoActive)
+        add(statusField('todo', 'Todo ' + status.todoActive.done + '/' + status.todoActive.total));
+    // AFTER `todo`, AND THE ORDER IS THE PRIORITY (D-12): `add()` only appends while
+    // the whole row still fits, so a later field is dropped FIRST. `Todo 3/7` is the
+    // more important of the two numbers, so it goes first and survives the narrower
+    // terminal; `Accept 2/5` degrades before it.
+    if (status.acceptanceActive) {
+        const acceptance = status.acceptanceActive;
+        add(statusField('acceptance', 'Accept ' + acceptance.checked + '/' + acceptance.total
+            + (acceptance.failed > 0 ? ' !' + acceptance.failed : ''), acceptance.failed > 0 ? 'error' : 'normal'));
+    }
+    add(statusField('model', input.provider + ':' + input.model));
+    if (status.fastActive)
+        add(statusField('fast', 'Fast' + (status.fastActive.inFlight ? ' active' : '')));
+    if (status.ecoRung)
+        add(statusField('eco', 'Eco'));
+    if (hints.updateAvailable)
+        add(statusField('update', '/update'));
+    return statusLinePlan([...fields, ...reserved]);
+}

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

@@ -0,0 +1,140 @@
+import type { UsageTotal } from '../../model/agent/reducer.js';
+import type { ContextUsageSnapshot } from '../../model/compaction/types.js';
+import type { EscapeAction, StatusFeedback } from '../status-feedback.js';
+export type RunPhase = 'idle' | 'starting' | 'waiting' | 'thinking' | 'generating' | 'preparing-tool' | 'tool';
+export interface StatusLayoutInput {
+    columns: number;
+    phase: RunPhase;
+    pendingCount: number;
+    context: ContextUsageSnapshot;
+    usageTotal: UsageTotal;
+    thinkingLevel: string;
+    elapsedMs: number;
+    tokPerSec: number;
+    activeTool?: {
+        name: string;
+        toolCallId: string;
+    } | null;
+    /**
+     * A bounded wait in flight (long-task-jobs §4.9).
+     *
+     * PRESENT ONLY WHILE `job_wait` IS THE ACTIVE TOOL, and it REPLACES the
+     * `Running job_wait` label rather than joining it: "Waiting on t3 (up to 30s)"
+     * is the state the user asked about (what, and how long at most), while the
+     * tool name is an implementation detail of how the runtime is waiting.
+     */
+    wait?: {
+        jobId: string;
+        upToSeconds: number;
+        elapsedSeconds?: number;
+    };
+    runOutcome?: 'none' | 'ended' | 'interrupted' | 'failed';
+    spinner?: string;
+    waitingForConfirmation?: boolean;
+    stopping?: boolean;
+    /**
+     * Auto-compaction paused itself after repeated no-progress attempts
+     * (context-compaction-never-fires C).
+     *
+     * A SEPARATE FIELD FROM `compacting`, and it renders as a SUFFIX on the context
+     * gauge rather than as a phase word: the fact belongs next to the percentage it
+     * explains ("Context 95% auto-paused"), and the phase slot must keep answering
+     * "is the agent running".
+     */
+    compactionPaused?: boolean;
+    compacting?: boolean;
+    retryActive?: {
+        attempt: number;
+        max: number;
+        secondsLeft: number;
+    };
+    /** Named on the primary row in EVERY mode - the §6.4 guarantee, restored. */
+    mode?: string;
+    pendingMode?: string | null;
+    servicesActive?: {
+        live: number;
+    };
+    /**
+     * Forced team mode is ARMED, with the fan-out count it was armed with
+     * (team-command-forced-dispatch §3.8 / D-9).
+     *
+     * THE ONLY PERSISTENTLY VISIBLE SIGNAL that `/team` happened. The directive is
+     * one turn, the prompt block is invisible, and the panel only appears while a
+     * dispatch runs - so without this chip the answer to "why is my agent
+     * dispatching?" is "remember what you typed". It is read at RENDER time from
+     * `controller.getForcedTeam()`, never mirrored into `ViewState`: a mirror is a
+     * second copy that can disagree, the exact defect §2.4 is about.
+     *
+     * ABSENT means "not armed" and keeps every existing caller's plan BYTE-
+     * IDENTICAL (the same discipline `reserveRight` records below).
+     */
+    forcedTeam?: {
+        count: number;
+    };
+    teamActive?: {
+        running: number;
+        total: number;
+    };
+    todoActive?: {
+        done: number;
+        total: number;
+    };
+    /**
+     * The acceptance counter (todo-acceptance-criteria §6.11).
+     *
+     * A FALLBACK, exactly like `todoActive`: present only when the rail is NOT already
+     * reporting the number, because printing `2/5` twice in one row is the defect
+     * RV-P2-4 records. Whether it is present is decided by `acceptanceChip()` in
+     * `ui/layout/todo-layout.ts`, which owns "what did the rail actually draw".
+     */
+    acceptanceActive?: {
+        checked: number;
+        total: number;
+        failed: number;
+    };
+    ecoRung?: number;
+    fastActive?: {
+        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;
+    escapeAction?: EscapeAction;
+    speedKnown: boolean;
+    interruptPhase?: 'ready' | 'armed' | 'stopping';
+}
+export interface StatusField {
+    id: string;
+    text: string;
+    cells: number;
+    /**
+     * 'accent' carries the mode word - the row's one always-on emphasis. 'govern' is the
+     * same slot while the posture is GOVERN / PLAN+GOVERN (`governAccent`, its own hue).
+     */
+    tone: 'normal' | 'muted' | 'warning' | 'error' | 'accent' | 'govern';
+}
+export interface StatusLinePlan {
+    fields: readonly StatusField[];
+    separator: string;
+    separatorCells: number;
+    cells: number;
+}
+export declare function cleanStatusText(text: string): string;
+export declare function statusField(id: string, text: string, tone?: StatusField['tone']): StatusField;
+export declare function statusLinePlan(fields: readonly StatusField[], separator?: string): StatusLinePlan;
+export declare function phaseLabels(input: Pick<StatusLayoutInput, 'phase' | 'activeTool' | 'runOutcome' | 'waitingForConfirmation' | 'stopping' | 'compacting' | 'retryActive' | 'wait'>): readonly [string, string];
+export declare function validContext(context: ContextUsageSnapshot): boolean;
+export declare function shortDuration(ms: number): string;
+/** Every field survives each width rung; only the redraw carrier is outside this plan. */
+export declare function planPrimaryStatusFields(input: StatusPrimaryInput): StatusLinePlan;