@aragon-agent/cli 0.6.34 → 0.6.36

package/dist/ui/layout/agents-board.js

@@ -0,0 +1,389 @@
+/**
+ * The Agents board's row model — pure projection, no Ink (tui-subagent-panel §4.4 / §7).
+ *
+ * WHY A PURE MODULE AND NOT JSX. The board's whole value is that it shows EVERY fact
+ * about every child, and the two things that can go wrong with that are both
+ * properties of a list: a row wider than the overlay (which silently desynchronises
+ * `OverlayFrame`'s position indicator) and a row count that grows without a bound.
+ * Both are assertable here, against plain strings, without a terminal - which is the
+ * same reason `layout/team-panel.ts` and `layout/budget.ts` are separate modules.
+ *
+ * LIVE-ONLY RULE (§4.4.2, RV-P0-2). The board has two sources with DIFFERENT fields:
+ * a live `TeamSnapshot` (has `messageCount`, `startedAt`, the activity prose and the
+ * timeline) and a settled `kind: 'team'` entry (has `durationMs` and the runs, and
+ * nothing else - `agent/reducer.ts`'s entry member carries no `messageCount` and no
+ * `startedAt`). A section whose source is missing is OMITTED, never filled with a
+ * zero: `mail 0` would be a lie, and an empty section title tells the reader nothing.
+ * The one section that survives both sources is `result` (`summary` / `error` is
+ * never stripped), which is precisely the fact a user opens the board to find.
+ *
+ * ASCII ONLY: `src/ui/**` is inside `glyphs.test.ts`'s static scan, so every symbol
+ * (the ellipsis, the separator, the cursor) arrives through `glyphs`.
+ */
+import { TEAM_LIMITS } from '../../team/limits.js';
+import { childStatus, lastTeamEntry, rosterCounts, rosterHeadline, statusMarkerCell, } from '../team-status.js';
+import { formatDuration, formatTokens } from '../../agent/usage.js';
+import { sanitizeActivity } from '../../team/activity.js';
+import { activityWithBadge, teamRowGeometry } from './team-row.js';
+import { alignRightCells, fitCells, padCells, wrapCells } from './cells.js';
+/**
+ * The board's single source shape, resolved in ONE place.
+ *
+ * PRIORITY: live snapshot > (the component's frozen copy) > the most recent settled
+ * entry. This function answers the first and the third; the frozen copy belongs to
+ * the component because it only exists while a dispatch is being read (§4.4.5).
+ */
+export function resolveBoardSource(input) {
+    const { team } = input;
+    if (team !== null) {
+        return {
+            dispatchId: team.dispatchId,
+            active: team.active,
+            startedAt: team.startedAt,
+            requested: team.requested,
+            runs: team.runs,
+            messageCount: team.messageCount,
+        };
+    }
+    const entry = lastTeamEntry(input.entries);
+    if (entry === null)
+        return null;
+    return {
+        dispatchId: entry.dispatchId,
+        active: entry.active === true,
+        requested: entry.requested,
+        runs: entry.runs,
+        ...(entry.durationMs !== undefined ? { durationMs: entry.durationMs } : {}),
+    };
+}
+/**
+ * The child the board is showing, resolved from its LABEL every frame (D-8).
+ *
+ * Labels are the only stable handle: `panel-rows.ts` re-sorts the roster by phase, so
+ * an index would silently jump to a different child the moment one of them settles.
+ * Fallback order is "the first running child, else the first child", which is the
+ * one a reader opening the board mid-dispatch wants.
+ */
+export function resolveSelection(runs, label) {
+    const named = label === null ? undefined : runs.find((run) => run.label === label);
+    if (named !== undefined)
+        return named;
+    return runs.find((run) => childStatus(run) === 'running') ?? runs[0] ?? null;
+}
+/** Fixed label column of a `field` row, and the value column of its wide form. */
+const FIELD_LABEL_CELLS = 11;
+const FIELD_WIDE_VALUE_CELLS = 23;
+/** Rows of prose a `now` / `result` section may spend. */
+const NOW_MAX_ROWS = 6;
+const RESULT_MAX_ROWS = 12;
+/** Board width at which the field rows go 2-up, and the narrowest width that pads. */
+const BOARD_WIDE_COLS = 110;
+const BOARD_INLINE_COLS = 40;
+/**
+ * The board's rows, in the order a reader wants them: what the dispatch did, then who
+ * is in it, then everything about the selected child, then its history.
+ *
+ * Bounded by `TEAM_LIMITS.boardMaxRows`, and the truncation is ANNOUNCED rather than
+ * silent - a list that stops mid-fact with no notice reads as a rendering bug.
+ */
+export function buildAgentBoardRows(input) {
+    const { source, glyphs } = input;
+    const cols = normalizeCols(input.cols);
+    const rows = [];
+    const selected = resolveSelection(source.runs, input.selectedLabel);
+    appendSummary(rows, input, selected);
+    appendChildren(rows, input, selected, cols);
+    if (selected !== null) {
+        appendFacts(rows, input, selected, cols);
+        appendProse(rows, input, selected, cols);
+        appendTimeline(rows, input, selected, cols);
+    }
+    if (rows.length > TEAM_LIMITS.boardMaxRows) {
+        const kept = rows.slice(0, TEAM_LIMITS.boardMaxRows);
+        const dropped = rows.length - TEAM_LIMITS.boardMaxRows;
+        kept[kept.length - 1] = {
+            key: 'truncated',
+            kind: 'hint',
+            text: fitCells(`+${dropped} more rows`, cols, glyphs.ellipsis),
+            tone: 'hint',
+        };
+        return kept;
+    }
+    return rows;
+}
+function normalizeCols(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+/** A section title, then nothing else: callers add the body. */
+function pushSection(rows, title, cols, glyphs) {
+    rows.push({
+        key: `section:${title}`,
+        kind: 'section',
+        text: fitCells(title, cols, glyphs.ellipsis),
+        tone: 'accent',
+    });
+}
+function pushBlank(rows, key) {
+    rows.push({ key: `blank:${key}`, kind: 'blank', text: '', tone: 'muted' });
+}
+/**
+ * Two summary lines, each a left clause and a right-anchored figure.
+ *
+ * The right figure is `alignRightCells`-ed rather than flex-ended because the row is a
+ * STRING here: the board hands `OverlayFrame` one element per row, so a row has to be
+ * a single measured line or the position indicator desynchronises.
+ */
+function summaryRow(rows, key, left, right, cols, glyphs, tone) {
+    if (cols === 0)
+        return;
+    const rightCells = Math.min(right.length, Math.max(0, cols - 1));
+    const leftCells = Math.max(0, cols - rightCells - 1);
+    const body = `${padCells(fitCells(left, leftCells, glyphs.ellipsis), leftCells)} ${right.slice(0, rightCells)}`;
+    rows.push({
+        key,
+        kind: 'summary',
+        text: padCells(fitCells(body, cols, glyphs.ellipsis), cols),
+        tone,
+    });
+}
+function appendSummary(rows, input, selected) {
+    const { source, glyphs } = input;
+    const cols = normalizeCols(input.cols);
+    const counts = rosterCounts(source.runs);
+    // A settled entry has no `startedAt`, so only `durationMs` is honest there; a live
+    // one may have neither (a dispatch that has not been stamped yet).
+    const totalMs = source.active && source.startedAt !== undefined
+        ? Math.max(0, input.now - source.startedAt)
+        : source.durationMs;
+    const clock = totalMs === undefined ? '' : formatDuration(totalMs);
+    summaryRow(rows, 'summary:counts', rosterHeadline(counts, glyphs, cols), clock, cols, glyphs, 'primary');
+    const figures = [];
+    // THE LIVE-ONLY CLAUSE (I-15): no `messageCount` means no `mail` clause at all.
+    if (source.messageCount !== undefined)
+        figures.push(`mail ${source.messageCount}`);
+    const toolCalls = source.runs.reduce((sum, run) => sum + run.toolCalls, 0);
+    figures.push(`${toolCalls} tool calls`);
+    const usage = source.runs.reduce((acc, run) => ({
+        inputTokens: acc.inputTokens + run.usage.inputTokens,
+        outputTokens: acc.outputTokens + run.usage.outputTokens,
+    }), { inputTokens: 0, outputTokens: 0 });
+    figures.push(`${formatTokens(usage.inputTokens)} in / ${formatTokens(usage.outputTokens)} out`);
+    const children = `${source.runs.length} children`;
+    if (cols >= BOARD_INLINE_COLS) {
+        summaryRow(rows, 'summary:figures', figures.join(` ${glyphs.midDot} `), children, cols, glyphs, 'muted');
+    }
+    pushBlank(rows, 'summary');
+    if (selected === null)
+        pushSection(rows, 'no children', cols, glyphs);
+}
+/**
+ * Every child, not the panel's `panelMaxRows` five: the board is the place a reader
+ * goes to see the child the panel folded away behind `+N more`.
+ *
+ * EACH ROW REUSES THE PANEL'S GEOMETRY one cell narrower and prefixes a cursor, so the
+ * columns line up with the panel exactly - "the same table at a second zoom level"
+ * (§1) rather than a second layout to keep in step.
+ */
+function appendChildren(rows, input, selected, cols) {
+    const { glyphs, source } = input;
+    pushSection(rows, 'children', cols, glyphs);
+    const inner = Math.max(0, cols - 1);
+    const geometry = teamRowGeometry(inner, glyphs);
+    for (const run of source.runs) {
+        const isSelected = selected !== null && run.label === selected.label;
+        const marker = statusMarkerCell(childStatus(run), glyphs);
+        const label = run.label.padEnd(8).slice(0, 8);
+        const descriptionCells = Math.max(0, inner - geometry.marker - geometry.label - geometry.gap - geometry.activity - geometry.clock);
+        const description = fitCells(run.description.replace(/\s+/g, ' '), descriptionCells, glyphs.ellipsis);
+        // THE MARKER TIER IS PASSED THROUGH (R-10): the ASCII tier's marker cell is 6 columns,
+        // so a budget computed against the Unicode tier's 3 would promise two columns this row
+        // does not have. `fitCells` is the second gate; the first one has to be told the truth
+        // or the text is ellipsised where it did fit.
+        const activity = fitCells(activityWithBadge(run, inner, input.now, geometry.marker), geometry.activity, glyphs.ellipsis);
+        const clock = run.startedAt === undefined
+            ? ''
+            : formatDuration(Math.max(0, (run.endedAt ?? input.now) - run.startedAt));
+        const text = [
+            isSelected ? glyphs.cursor : ' ',
+            padCells(`${marker} `, geometry.marker),
+            padCells(label, geometry.label),
+            padCells(description, descriptionCells),
+            padCells(' '.repeat(geometry.gap), geometry.gap),
+            padCells(activity, geometry.activity),
+            alignRightCells(clock, geometry.clock, glyphs.ellipsis),
+        ].join('');
+        rows.push({
+            key: `child:${run.label}`,
+            kind: 'child',
+            text: padCells(fitCells(text, cols, glyphs.ellipsis), cols),
+            tone: isSelected ? 'primary' : 'muted',
+            ...(isSelected ? { selected: true } : {}),
+        });
+    }
+    pushBlank(rows, 'children');
+}
+/** The selected child's fixed-order fact list (§4.4.2's table, top to bottom). */
+function appendFacts(rows, input, run, cols) {
+    const { glyphs } = input;
+    pushSection(rows, `${run.label} ${glyphs.midDot} ${run.description}`.trim(), cols, glyphs);
+    const facts = factPairs(run, glyphs);
+    // Two facts per row when there is room, one otherwise; the pairing is done here
+    // rather than in the component so the row COUNT is assertable.
+    const step = cols >= BOARD_WIDE_COLS ? 2 : 1;
+    for (let index = 0; index < facts.length; index += step) {
+        const first = facts[index];
+        if (first === undefined)
+            continue;
+        const second = step === 2 ? facts[index + 1] : undefined;
+        rows.push({
+            key: `field:${first[0]}:${index}`,
+            kind: 'field',
+            text: second === undefined
+                ? fieldCells(first, cols, glyphs)
+                : fieldPairCells(first, second, cols, glyphs),
+            tone: 'primary',
+        });
+    }
+    pushBlank(rows, 'facts');
+}
+/** The width one field occupies in the 2-up form: its label plus its value column. */
+const FIELD_PAIR_CELLS = FIELD_LABEL_CELLS + FIELD_WIDE_VALUE_CELLS;
+/** One `label  value` field, padded so two of them stand in columns. */
+function fieldCells(pair, cols, glyphs) {
+    const width = Math.max(0, cols);
+    return [
+        padCells(fitCells(pair[0], FIELD_LABEL_CELLS - 1, glyphs.ellipsis), FIELD_LABEL_CELLS - 1),
+        ' ',
+        fitCells(pair[1], Math.max(0, width - FIELD_LABEL_CELLS), glyphs.ellipsis),
+    ].join('');
+}
+/**
+ * Two fields side by side, each with its own label and value column.
+ *
+ * BUILT FROM THE LEFT FIELD'S WIDTH, not from slicing a full-width row: a slice counts
+ * code units while a row is measured in cells, so a wide character in the first value
+ * could be cut in half and both columns would drift. `fieldCells` measures, so one space
+ * of gutter and a 34-cell left field are what fix the right field's offset.
+ */
+function fieldPairCells(first, second, cols, glyphs) {
+    const right = Math.max(0, cols - FIELD_PAIR_CELLS - 1);
+    return `${fieldCells(first, FIELD_PAIR_CELLS, glyphs)} ${fieldCells(second, right, glyphs)}`;
+}
+/**
+ * The facts, in a FIXED order, and with the zero-valued ones ABSENT.
+ *
+ * `supervisor` / `retries` / `compactions` / `truncated` only appear when they carry a
+ * fact; a row reading `supervisor  0` teaches a reader nothing and pushes the section
+ * a row down for every child that was never touched.
+ */
+export function factPairs(run, glyphs) {
+    const status = childStatus(run);
+    const state = status === 'running' ? `${status} ${glyphs.midDot} ${run.phase}` : status;
+    const pairs = [
+        ['state', state],
+        ['turns', String(run.turns)],
+        ['tools', String(run.toolCalls)],
+        ['tokens', `${formatTokens(run.usage.inputTokens)} / ${formatTokens(run.usage.outputTokens)}`],
+    ];
+    if (run.filesTouched.length > 0) {
+        const head = run.filesTouched.slice(0, 3).join(', ');
+        const more = run.filesTouched.length > 3 ? ` (+${run.filesTouched.length - 3})` : '';
+        pairs.push(['files', `${run.filesTouched.length} (${head}${more})`]);
+    }
+    pairs.push(['mail', `${run.messagesSent} sent ${glyphs.midDot} ${run.blockedWaits ?? 0} blocked`]);
+    if ((run.interventions ?? 0) > 0 || (run.replacements ?? 0) > 0) {
+        const looks = `${run.interventions ?? 0} looks`;
+        const replaced = (run.replacements ?? 0) > 0 ? ` ${glyphs.midDot} ${run.replacements} replaced` : '';
+        const last = run.lastIntervention === undefined
+            ? ''
+            : ` ${glyphs.midDot} ${run.lastIntervention.action}`;
+        pairs.push(['supervisor', `${looks}${replaced}${last}`]);
+    }
+    if (run.retry !== undefined) {
+        pairs.push(['retries', `retrying ${run.retry.attempt}/${run.retry.maxRetries}`]);
+    }
+    else if ((run.retries ?? 0) > 0) {
+        pairs.push(['retries', `${run.retries} cold start`]);
+    }
+    if ((run.compactions ?? 0) > 0)
+        pairs.push(['compactions', String(run.compactions)]);
+    if (run.truncated === true)
+        pairs.push(['truncated', 'stopped at turn cap']);
+    return pairs;
+}
+/**
+ * `now` and `result`: the two prose sections, both folded by DISPLAY WIDTH.
+ *
+ * LIVE-ONLY, and honestly so: `now` needs `run.activity`, which is stripped on the way
+ * out of the dispatch, so a settled board says one line instead of drawing an empty
+ * section (I-15). `result` survives both sources and is the section a reader opens the
+ * board for when a child failed.
+ */
+function appendProse(rows, input, run, cols) {
+    const { glyphs } = input;
+    pushSection(rows, 'now', cols, glyphs);
+    const now = run.activity === undefined
+        ? ''
+        : sanitizeActivity(run.activity, TEAM_LIMITS.timelineTextChars);
+    if (now.length === 0) {
+        pushUnavailable(rows, 'now', cols, glyphs);
+    }
+    else {
+        const wrapped = wrapCells(now, Math.max(0, cols - 2), NOW_MAX_ROWS, glyphs.ellipsis);
+        wrapped.lines.forEach((line, index) => {
+            rows.push({ key: `now:${index}`, kind: 'event', text: fitCells(`  ${line}`, cols, glyphs.ellipsis), tone: 'muted' });
+        });
+    }
+    pushSection(rows, 'result', cols, glyphs);
+    const result = run.error ?? run.summary ?? '';
+    if (result.length === 0) {
+        pushUnavailable(rows, 'result', cols, glyphs);
+        return;
+    }
+    const wrapped = wrapCells(result, Math.max(0, cols - 2), RESULT_MAX_ROWS, glyphs.ellipsis);
+    wrapped.lines.forEach((line, index) => {
+        rows.push({
+            key: `result:${index}`,
+            kind: 'event',
+            text: fitCells(`  ${line}`, cols, glyphs.ellipsis),
+            tone: run.error !== undefined ? 'error' : 'primary',
+        });
+    });
+}
+/**
+ * The one honest sentence that replaces a section whose source is gone (§4.4.2 rule 2).
+ *
+ * QUOTE-SAFE AND PATH-FREE: it names the reason ("live only") rather than apologising,
+ * because the fact that matters is that the reader is not being shown a stale copy.
+ */
+function pushUnavailable(rows, section, cols, glyphs) {
+    rows.push({
+        key: `unavailable:${section}`,
+        kind: 'hint',
+        text: fitCells('  live only - not available after the dispatch ended', cols, glyphs.ellipsis),
+        tone: 'hint',
+    });
+}
+/** The 24-event ring, oldest first, each prefixed with its offset from the start. */
+function appendTimeline(rows, input, run, cols) {
+    const { glyphs } = input;
+    pushSection(rows, 'timeline', cols, glyphs);
+    const timeline = run.timeline ?? [];
+    if (timeline.length === 0) {
+        pushUnavailable(rows, 'timeline', cols, glyphs);
+        return;
+    }
+    const start = run.startedAt ?? timeline[0]?.at ?? 0;
+    timeline.forEach((entry, index) => {
+        const offset = `+${formatDuration(Math.max(0, entry.at - start))}`;
+        const mark = entry.ok === undefined ? '' : entry.ok ? ' ok' : ' failed';
+        const took = entry.ms === undefined ? '' : ` ${formatDuration(entry.ms)}`;
+        const text = `  ${padCells(offset, 8)} ${entry.text}${took}${mark}`;
+        rows.push({
+            key: `event:${index}`,
+            kind: 'event',
+            text: fitCells(text, cols, glyphs.ellipsis),
+            tone: entry.ok === false ? 'warn' : 'muted',
+        });
+    });
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Display-width cell arithmetic (tui-subagent-panel §5 #1).
+ *
+ * EVERY FUNCTION HERE IS PURE AND TOTAL: no Ink, no clock, no terminal, and no
+ * input that throws. The panel row and the Agents board both need to place text
+ * in a FIXED number of terminal columns, and `padEnd` cannot do that: it counts
+ * code units while a terminal counts cells, so a CJK description padded with
+ * `padEnd` overflows its box by one column per wide character and pushes the
+ * next cell off the row. That is exactly the defect this round removes from the
+ * roster, one layer down.
+ *
+ * ASCII ONLY: `src/ui/**` is inside `glyphs.test.ts`'s static scan, so the
+ * ellipsis and any other symbol a caller wants must be passed IN (the board
+ * hands over `glyphs.ellipsis`), never spelled here.
+ */
+/** Display columns a string occupies, or 0 for a non-string (defensive at the edge only). */
+export declare function cellWidth(text: string): number;
+/**
+ * Cut `text` to at most `cells` display columns, marking the cut with `ellipsis`.
+ *
+ * THE ELLIPSIS IS PART OF THE BUDGET, not an extra column: a caller that asks for
+ * 8 cells gets a string that MEASURES 8, which is what makes a fixed-width cell
+ * a cell rather than a hope. When the budget cannot hold the ellipsis plus one
+ * character, the string is hard-cut instead - a marker wider than the cell it
+ * marks is the one outcome worse than no marker.
+ *
+ * Wide characters are never split: a surrogate pair or a double-width glyph that
+ * does not fit is dropped whole, so the result can measure one column less than
+ * asked but never one more.
+ */
+export declare function fitCells(text: string, cells: number, ellipsis?: string): string;
+/**
+ * Pad `text` to exactly `cells` columns (or leave it alone when it already
+ * measures at least that).
+ *
+ * NOT `padEnd`: see this file's header. A padded cell is what keeps the next
+ * column at a stable offset, which is the whole point of the panel's table.
+ */
+export declare function padCells(text: string, cells: number): string;
+/** `fitCells` then `padCells`: the result ALWAYS measures exactly `cells`. */
+export declare function alignRightCells(text: string, cells: number, ellipsis?: string): string;
+/** What one wrapped line is worth: the text, and whether lines were dropped. */
+export interface WrappedCells {
+    lines: string[];
+    /** Lines that did not fit under `maxRows`; 0 when everything fitted. */
+    dropped: number;
+}
+/**
+ * Fold `text` into at most `maxRows` lines of at most `cells` columns each.
+ *
+ * BREAKS AT SPACES, HARD-CUTS ONLY WHEN A SINGLE TOKEN CANNOT FIT: a word that is
+ * wider than the column is the one case where an honest over-long token beats a
+ * line of nothing, so it is cut rather than pushed to a line that still cannot
+ * hold it. The last allowed line, when text remains, carries the `(+N lines)`
+ * tail so the reader learns that the section was truncated instead of believing
+ * the prose ended mid-sentence.
+ *
+ * Pure and total: `cells <= 0` or `maxRows <= 0` yields no lines, and the caller
+ * decides what an empty section means (the board omits it).
+ */
+export declare function wrapCells(text: string, cells: number, maxRows: number, ellipsis?: string): WrappedCells;

package/dist/ui/layout/cells.js

@@ -0,0 +1,156 @@
+/**
+ * Display-width cell arithmetic (tui-subagent-panel §5 #1).
+ *
+ * EVERY FUNCTION HERE IS PURE AND TOTAL: no Ink, no clock, no terminal, and no
+ * input that throws. The panel row and the Agents board both need to place text
+ * in a FIXED number of terminal columns, and `padEnd` cannot do that: it counts
+ * code units while a terminal counts cells, so a CJK description padded with
+ * `padEnd` overflows its box by one column per wide character and pushes the
+ * next cell off the row. That is exactly the defect this round removes from the
+ * roster, one layer down.
+ *
+ * ASCII ONLY: `src/ui/**` is inside `glyphs.test.ts`'s static scan, so the
+ * ellipsis and any other symbol a caller wants must be passed IN (the board
+ * hands over `glyphs.ellipsis`), never spelled here.
+ */
+import stringWidth from 'string-width';
+/** Invalid geometry becomes zero, exactly like the layout modules' `nonNegativeInt`. */
+function nonNegativeInt(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+/** Display columns a string occupies, or 0 for a non-string (defensive at the edge only). */
+export function cellWidth(text) {
+    if (typeof text !== 'string' || text.length === 0)
+        return 0;
+    return stringWidth(text);
+}
+/**
+ * Cut `text` to at most `cells` display columns, marking the cut with `ellipsis`.
+ *
+ * THE ELLIPSIS IS PART OF THE BUDGET, not an extra column: a caller that asks for
+ * 8 cells gets a string that MEASURES 8, which is what makes a fixed-width cell
+ * a cell rather than a hope. When the budget cannot hold the ellipsis plus one
+ * character, the string is hard-cut instead - a marker wider than the cell it
+ * marks is the one outcome worse than no marker.
+ *
+ * Wide characters are never split: a surrogate pair or a double-width glyph that
+ * does not fit is dropped whole, so the result can measure one column less than
+ * asked but never one more.
+ */
+export function fitCells(text, cells, ellipsis = '...') {
+    const budget = nonNegativeInt(cells);
+    if (budget === 0)
+        return '';
+    if (cellWidth(text) <= budget)
+        return text;
+    const mark = cellWidth(ellipsis) < budget ? ellipsis : '';
+    const room = budget - cellWidth(mark);
+    let out = '';
+    let used = 0;
+    // `Array.from` iterates by CODE POINT, so a surrogate pair is one step and can
+    // never be cut in half by this loop.
+    for (const char of Array.from(text)) {
+        const width = cellWidth(char);
+        if (used + width > room)
+            break;
+        out += char;
+        used += width;
+    }
+    return `${out}${mark}`;
+}
+/**
+ * Pad `text` to exactly `cells` columns (or leave it alone when it already
+ * measures at least that).
+ *
+ * NOT `padEnd`: see this file's header. A padded cell is what keeps the next
+ * column at a stable offset, which is the whole point of the panel's table.
+ */
+export function padCells(text, cells) {
+    const budget = nonNegativeInt(cells);
+    const width = cellWidth(text);
+    if (width >= budget)
+        return text;
+    return `${text}${' '.repeat(budget - width)}`;
+}
+/** `fitCells` then `padCells`: the result ALWAYS measures exactly `cells`. */
+export function alignRightCells(text, cells, ellipsis = '...') {
+    const budget = nonNegativeInt(cells);
+    return padCells(fitCells(text, budget, ellipsis), budget);
+}
+/**
+ * Fold `text` into at most `maxRows` lines of at most `cells` columns each.
+ *
+ * BREAKS AT SPACES, HARD-CUTS ONLY WHEN A SINGLE TOKEN CANNOT FIT: a word that is
+ * wider than the column is the one case where an honest over-long token beats a
+ * line of nothing, so it is cut rather than pushed to a line that still cannot
+ * hold it. The last allowed line, when text remains, carries the `(+N lines)`
+ * tail so the reader learns that the section was truncated instead of believing
+ * the prose ended mid-sentence.
+ *
+ * Pure and total: `cells <= 0` or `maxRows <= 0` yields no lines, and the caller
+ * decides what an empty section means (the board omits it).
+ */
+export function wrapCells(text, cells, maxRows, ellipsis = '...') {
+    const width = nonNegativeInt(cells);
+    const limit = nonNegativeInt(maxRows);
+    const flat = (text ?? '').replace(/\s+/g, ' ').trim();
+    if (width === 0 || limit === 0 || flat.length === 0) {
+        return { lines: [], dropped: flat.length === 0 ? 0 : limit === 0 ? 1 : 0 };
+    }
+    const lines = [];
+    let rest = flat;
+    while (rest.length > 0) {
+        if (cellWidth(rest) <= width) {
+            lines.push(rest);
+            rest = '';
+            break;
+        }
+        const cut = breakCells(rest, width);
+        lines.push(cut.line);
+        rest = cut.rest;
+    }
+    if (lines.length <= limit)
+        return { lines, dropped: 0 };
+    const kept = lines.slice(0, limit);
+    const dropped = lines.length - limit;
+    const tail = `(+${dropped} lines)`;
+    // THE ANNOUNCEMENT IS RESERVED, not appended and then truncated away: a reader who
+    // sees prose stop mid-sentence with no marker reads it as the end of the fact, which
+    // is exactly the wrong conclusion. When the column is too narrow to hold the marker
+    // at all, the line is simply cut - the caller's section is unusable at that width.
+    const tailCells = cellWidth(tail) + 1;
+    const last = kept[limit - 1] ?? '';
+    kept[limit - 1] = tailCells < width
+        ? `${fitCells(last, width - tailCells, ellipsis)} ${tail}`
+        : fitCells(last, width, ellipsis);
+    return { lines: kept, dropped };
+}
+/**
+ * The longest prefix of `text` that fits `width` columns, preferring a space.
+ *
+ * Returns the consumed line and what is left, so the caller's loop is one
+ * assignment per iteration and the "one function does one thing" rule holds.
+ */
+function breakCells(text, width) {
+    let used = 0;
+    let taken = 0;
+    let lastSpace = -1;
+    for (const char of Array.from(text)) {
+        const charWidth = cellWidth(char);
+        if (used + charWidth > width)
+            break;
+        used += charWidth;
+        taken += char.length;
+        if (char === ' ')
+            lastSpace = taken;
+    }
+    // A single token wider than the column: hard-cut it rather than emit nothing.
+    if (taken === 0) {
+        const first = Array.from(text)[0] ?? '';
+        return { line: fitCells(first, width), rest: text.slice(first.length) };
+    }
+    if (lastSpace > 0) {
+        return { line: text.slice(0, lastSpace).trimEnd(), rest: text.slice(lastSpace).trimStart() };
+    }
+    return { line: text.slice(0, taken), rest: text.slice(taken).trimStart() };
+}

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

@@ -46,7 +46,7 @@ export declare const HEADER_HINT_LIMITS: {
      */
     readonly separatorCells: 2;
 };
-export type HeaderHintId = 'branch' | 'index' | 'detail';
+export type HeaderHintId = 'branch' | 'prompts' | 'index' | 'kit' | 'detail';
 export interface HeaderHintClause {
     id: HeaderHintId;
     text: string;
@@ -66,12 +66,32 @@ export interface HeaderHintPlan {
 /**
  * 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).
+ * The inputs are the props `Header` receives plus the two switches that decide which
+ * clauses exist at all - 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;
+    /**
+     * Whether the `^K switch kit` clause exists at all (default `true`).
+     *
+     * `App` ALWAYS PASSES TRUE, including for a user with no kits: the whole point
+     * of the requirement is discoverability of `ctrl+K`, and an empty library is
+     * exactly the state that needs it (the picker's own `No kits yet` row tells
+     * them where to create one). `false` exists for tests and for the future
+     * switch, and it degrades the six expanded rungs back into today's four.
+     */
+    kitHint?: boolean;
+    /**
+     * Whether the `^P prompts` clause exists at all (default `true`).
+     *
+     * `false` is the `prompts.hint` config key and the only reason the ladder is
+     * parameterised: a user who turned the header hint off must get exactly the row
+     * they had before this feature, which is what the unfiltered ladder below
+     * degenerates into.
+     */
+    promptsHint?: boolean;
 }): HeaderHintPlan;