@aragon-agent/cli 0.6.35 → 0.6.37

package/dist/ui/overlays/prompt-library-state.js

@@ -0,0 +1,335 @@
+/**
+ * The prompt manager's state machine and view models (quick-prompt-library §4.4).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`. Every sentence the
+ * user reads comes from `prompts/copy.ts`; nothing in this file may hold a literal
+ * non-ASCII byte.
+ *
+ * WHY A PURE REDUCER AND NOT `useState` INSIDE THE COMPONENT: the page stack has two
+ * transitions that are easy to get wrong and impossible to see on screen - "the
+ * second Esc discards, the first does not" and "the intent is consumed exactly
+ * once" - and both are assertions, not screenshots. Everything below can be driven
+ * from a test with no Ink mounted.
+ */
+import { PROMPT_LIMITS } from '../../prompts/limits.js';
+import { parsePromptTags, validatePromptDraft } from '../../prompts/store.js';
+// The list's read-only preview is the ONE place `wrapToRows` belongs: it is a prose
+// wrapper, so it would destroy the caret-to-cell mapping in an editable field
+// (D-11), and there is no caret here.
+import { wrapToRows } from '../layout/wrap-rows.js';
+/** The six rows `Tab` cycles on the editor page, in visual order. */
+export const PROMPT_EDITOR_FIELDS = [
+    'title', 'content', 'description', 'tags', 'save', 'cancel',
+];
+/** A new, empty draft. `id: null` is what makes `Save` a create rather than an update. */
+export const EMPTY_PROMPT_DRAFT = {
+    id: null,
+    title: '',
+    content: '',
+    description: '',
+    tags: '',
+    favorite: false,
+};
+export const INITIAL_PROMPT_LIBRARY_STATE = {
+    page: 'list',
+    index: 0,
+    focusId: null,
+    draft: EMPTY_PROMPT_DRAFT,
+    baseline: null,
+    escArmed: false,
+    pendingDeleteId: null,
+    error: null,
+    errorField: null,
+    consumedIntentNonce: 0,
+};
+/** The editable projection of a stored entry. */
+export function draftFromEntry(entry) {
+    return {
+        id: entry.id,
+        title: entry.title,
+        content: entry.content,
+        description: entry.description ?? '',
+        tags: (entry.tags ?? []).join(' '),
+        favorite: entry.favorite === true,
+    };
+}
+/** A create draft seeded from a command (`/prompts add title :: body`). */
+export function seededDraft(seed) {
+    return {
+        ...EMPTY_PROMPT_DRAFT,
+        title: seed?.title ?? '',
+        content: seed?.content ?? '',
+    };
+}
+/** Structural equality is enough: every field is a string or a boolean. */
+export function draftIsDirty(draft, baseline) {
+    if (baseline === null) {
+        return draft.title.length > 0 || draft.content.length > 0
+            || draft.description.length > 0 || draft.tags.length > 0;
+    }
+    return draft.title !== baseline.title || draft.content !== baseline.content
+        || draft.description !== baseline.description || draft.tags !== baseline.tags
+        || draft.favorite !== baseline.favorite;
+}
+/**
+ * Validate a draft and turn it into what the store accepts (D-12).
+ *
+ * THE VALIDATOR IS `store.ts`'S, not a second copy here: the sentence the editor
+ * shows and the rule the write applies have to be the same rule, or a user can be
+ * told a title is fine by the form and refused by the store.
+ */
+export function finishPromptEditor(draft) {
+    return validatePromptDraft({
+        title: draft.title,
+        content: draft.content,
+        description: draft.description,
+        tags: parsePromptTags(draft.tags),
+        favorite: draft.favorite,
+    });
+}
+/** Index of the first focusable row, for a refusal that named a field. */
+export function fieldIndex(field) {
+    if (field === null)
+        return 0;
+    const at = PROMPT_EDITOR_FIELDS.indexOf(field);
+    return at < 0 ? 0 : at;
+}
+function enterEditor(state, draft, baseline) {
+    return {
+        ...state,
+        page: 'editor',
+        draft,
+        baseline,
+        escArmed: false,
+        error: null,
+        errorField: null,
+    };
+}
+/**
+ * The reducer.
+ *
+ * `init` is the ONLY action that can jump straight to the editor or the delete page:
+ * that is what makes `/prompts edit 2` land where it should (D-21). The intent's
+ * nonce is stored as `consumedIntentNonce` by the component before dispatching, so a
+ * replayed intent is a no-op at the component, not a second edit here.
+ */
+export function promptLibraryReducer(state, action, library) {
+    switch (action.type) {
+        case 'init': {
+            if (action.nonce <= state.consumedIntentNonce)
+                return state;
+            const consumed = { ...state, consumedIntentNonce: action.nonce };
+            const entry = action.entry;
+            if (entry.kind === 'create') {
+                return enterEditor(consumed, seededDraft(entry.seed), null);
+            }
+            if (entry.kind === 'edit') {
+                const found = action.library.prompts.find((prompt) => prompt.id === entry.id);
+                if (!found)
+                    return { ...consumed, page: 'list', focusId: null };
+                const draft = draftFromEntry(found);
+                return enterEditor(consumed, draft, { ...draft });
+            }
+            if (entry.kind === 'delete') {
+                const found = action.library.prompts.find((prompt) => prompt.id === entry.id);
+                if (!found)
+                    return { ...consumed, page: 'list', focusId: null };
+                return { ...consumed, page: 'delete', pendingDeleteId: entry.id };
+            }
+            return { ...consumed, page: 'list', focusId: entry.focusId ?? null, index: 0 };
+        }
+        case 'list':
+            return {
+                ...state,
+                page: 'list',
+                focusId: action.focusId ?? state.focusId,
+                escArmed: false,
+                pendingDeleteId: null,
+                error: null,
+                errorField: null,
+            };
+        case 'focus':
+            return { ...state, index: Math.max(0, Math.floor(action.index)) };
+        case 'create':
+            return enterEditor(state, seededDraft(action.seed), null);
+        case 'edit': {
+            const found = action.library.prompts.find((prompt) => prompt.id === action.id);
+            if (!found)
+                return { ...state, page: 'list', error: 'not_found' };
+            const draft = draftFromEntry(found);
+            return enterEditor(state, draft, { ...draft });
+        }
+        case 'delete':
+            return { ...state, page: 'delete', pendingDeleteId: action.id };
+        case 'draft':
+            return { ...state, draft: { ...state.draft, ...action.patch }, escArmed: false };
+        case 'commit':
+            return {
+                ...state,
+                page: 'list',
+                focusId: action.id,
+                baseline: null,
+                escArmed: false,
+                error: null,
+                errorField: null,
+                draft: EMPTY_PROMPT_DRAFT,
+            };
+        case 'failed':
+            return { ...state, error: action.code, errorField: action.field ?? null };
+        case 'esc': {
+            if (state.page !== 'editor')
+                return { ...state, page: 'list', pendingDeleteId: null };
+            // A CLEAN EDITOR CLOSES ON THE FIRST Esc. A dirty one asks once, and the answer
+            // has to be a second Esc rather than a modal: losing a body typed into a
+            // multi-line field because one key was pressed is the failure this guards.
+            if (!draftIsDirty(state.draft, state.baseline)) {
+                return { ...state, page: 'list', baseline: null, draft: EMPTY_PROMPT_DRAFT };
+            }
+            if (state.escArmed) {
+                return {
+                    ...state, page: 'list', baseline: null, escArmed: false, draft: EMPTY_PROMPT_DRAFT,
+                };
+            }
+            return { ...state, escArmed: true };
+        }
+        case 'cancelled':
+            return { ...state, page: 'list', baseline: null, escArmed: false, draft: EMPTY_PROMPT_DRAFT };
+    }
+}
+/** `1.2k` for anything a fixed-width column cannot show in full. */
+export function formatCount(count) {
+    if (count < 1000)
+        return String(count);
+    return `${(count / 1000).toFixed(1)}k`;
+}
+/** `3d ago` / `2h ago` / `just now`. Deliberately coarse: it is a hint, not a clock. */
+export function formatAgo(timestamp, now) {
+    if (timestamp === undefined || timestamp <= 0)
+        return 'never';
+    const seconds = Math.max(0, Math.floor((now - timestamp) / 1000));
+    if (seconds < 60)
+        return 'just now';
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.floor(hours / 24)}d ago`;
+}
+/**
+ * The list, one row per entry, in the library's own order.
+ *
+ * DUPLICATE TITLES GET AN ID PREFIX (I-2), exactly as `kit-picker-state.ts` does for
+ * duplicate kit names: two rows reading the same words make `Enter` a coin flip.
+ */
+export function libraryRows(library) {
+    const seen = new Map();
+    for (const prompt of library.prompts) {
+        seen.set(prompt.title, (seen.get(prompt.title) ?? 0) + 1);
+    }
+    return library.prompts.map((prompt) => {
+        const duplicate = (seen.get(prompt.title) ?? 0) > 1;
+        const identity = duplicate ? `#${prompt.id.slice(0, 8)} ` : '';
+        const marks = [];
+        if (prompt.favorite === true)
+            marks.push('[fav]');
+        const tags = prompt.tags ?? [];
+        for (const tag of tags.slice(0, 2))
+            marks.push(`#${tag}`);
+        if (tags.length > 2)
+            marks.push(`+#${tags.length - 2}`);
+        marks.push(`${formatCount([...prompt.content].length)}c`);
+        if (prompt.useCount > 0)
+            marks.push(`${formatCount(prompt.useCount)}x`);
+        return {
+            id: prompt.id,
+            label: `${identity}${prompt.title}  ${marks.join(' ')}`,
+            markers: {
+                favorite: prompt.favorite === true,
+                hasTags: tags.length > 0,
+                uses: prompt.useCount,
+            },
+            chars: [...prompt.content].length,
+        };
+    });
+}
+/**
+ * The detail block under the list: at most `detailMaxLines` rows, fixed shape.
+ *
+ * FIXED, because `OverlayFrame`'s window is shared with the list (D-16): a body that
+ * participated in row height would squeeze six prompts into two visible rows. The
+ * full text has exactly one home, and it is the editor.
+ */
+export function libraryDetail(row, library, cols, now = Date.now()) {
+    if (!row)
+        return [];
+    const prompt = library.prompts.find((entry) => entry.id === row.id);
+    if (!prompt)
+        return [];
+    const tags = (prompt.tags ?? []).map((tag) => `#${tag}`).join(' ');
+    const facts = [
+        `${formatCount(row.chars)} chars`,
+        `${prompt.useCount} uses`,
+        formatAgo(prompt.lastUsedAt, now),
+        prompt.favorite === true ? '[fav]' : '',
+    ].filter(Boolean).join('  ');
+    const body = prompt.content.split('\n').slice(0, PROMPT_LIMITS.detailPreviewLines).join('\n');
+    const preview = wrapToRows(body, Math.max(8, cols - 8))
+        .slice(0, PROMPT_LIMITS.detailPreviewLines);
+    return [prompt.title, ...(tags.length > 0 ? [tags] : []), facts, ...preview]
+        .slice(0, PROMPT_LIMITS.detailMaxLines);
+}
+/**
+ * The list page's footer.
+ *
+ * THE LAST CLAUSE IS ALWAYS THE WAY OUT (§9.5): a narrow terminal clips from the
+ * left, so the reader always keeps `Esc close`. The reorder keys are named here
+ * rather than in the row above it because they are the one affordance a user cannot
+ * discover by pressing a key they already know.
+ */
+export function libraryHint(state, count) {
+    if (state.page === 'delete')
+        return 'Enter delete | Esc cancel';
+    if (state.page === 'editor')
+        return editorHint(state);
+    if (count === 0)
+        return 'a create your first prompt | Esc close';
+    return 'Enter edit | a new | d delete | f favorite | ^up/^dn reorder | Esc close';
+}
+function editorHint(state) {
+    if (state.escArmed)
+        return 'Esc again discards the draft | Tab next field';
+    return 'Tab next field | Ctrl+S save | Esc close';
+}
+/** The delete page's four lines: what it is, how big, and what it costs. */
+export function deleteDetail(library, id) {
+    const prompt = library.prompts.find((entry) => entry.id === id);
+    if (!prompt)
+        return [];
+    return [
+        prompt.title,
+        `${[...prompt.content].length} chars, ${prompt.content.split('\n').length} lines`,
+        'This cannot be undone.',
+        'Enter or y deletes it; Esc or n keeps it.',
+    ];
+}
+/**
+ * The draft as the store accepts it.
+ *
+ * THE TAGS FIELD IS PARSED HERE, ONCE, and nowhere else: the editor edits a raw
+ * string, the store validates a `string[]`, and a second parser between them is how
+ * `a,b` and `a b` come to mean different things depending on which surface saved it.
+ */
+export function draftToInput(draft) {
+    const input = {
+        title: draft.title,
+        content: draft.content,
+        tags: parsePromptTags(draft.tags),
+        favorite: draft.favorite,
+    };
+    const description = draft.description.trim();
+    if (description.length > 0)
+        input.description = description;
+    return input;
+}

package/dist/ui/overlays/prompt-picker-state.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The prompt picker's view model (quick-prompt-library §4.5).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THE ROWS ARE COMPUTED OUTSIDE THE COMPONENT for the reason `kit-picker-state.ts`
+ * records one surface over: the same library is rendered by two overlays and by
+ * `/prompts list`, and three independent row builders is how "the manager says four
+ * entries and the picker says five" becomes possible without a single failing test.
+ */
+import type { PromptLibrary, PromptSortView } from '../../prompts/types.js';
+export interface PromptPickerRow {
+    id: string;
+    /** 1-based position in the CURRENT view, i.e. the number `1`-`9` addresses. */
+    index: number;
+    title: string;
+    tags: string[];
+    favorite: boolean;
+}
+export interface PromptPickerInput {
+    library: PromptLibrary;
+    query: string;
+    view: PromptSortView;
+}
+/**
+ * Filter the library and number the result.
+ *
+ * THE VIEW IS APPLIED FIRST, THEN THE FILTER: searching inside `recent` must return
+ * the recent order, not the manual one. Reversing the two would make `Ctrl+S` appear
+ * to do nothing whenever a query is active - which is exactly when the user is
+ * looking at the footer to see whether it worked.
+ */
+export declare function pickerRows(input: PromptPickerInput): PromptPickerRow[];
+/**
+ * The block under the list: at most four rows, and never the whole body.
+ *
+ * The picker exists to CHOOSE. The full text belongs to the editor, and printing it
+ * here would push the chosen row off the frame that has to show it.
+ */
+export declare function pickerDetail(row: PromptPickerRow | undefined, library: PromptLibrary, now?: number): string[];
+/**
+ * The empty-library guidance (AC-23).
+ *
+ * IT NAMES TWO WAYS OUT, because the picker is reachable from two directions: the
+ * user who typed `/prompts` on an empty library can press `a` here, and the user who
+ * does not want to type can press `Ctrl+P` later. Naming only one of them leaves the
+ * other audience pressing a key that does nothing.
+ */
+export declare const NO_PROMPTS_HINT = "No prompts yet. Press Ctrl+P to create one, or a to add one here.";
+/**
+ * The footer, ordered by WHICH PATH SURVIVES ON THE WORST TERMINAL (§9.11).
+ *
+ * `Enter fill` comes before `^Enter fill & send` because a terminal without keyboard
+ * enhancement delivers `Ctrl+Enter` as a plain `Enter`: the reader who works left to
+ * right must meet the path that always works first. `tab manage` sits after the two
+ * fill actions for the same reason - it is navigation, not the point of the screen.
+ */
+export declare function pickerHint(input: {
+    count: number;
+    query: string;
+    view: PromptSortView;
+}): string;
+/**
+ * The `1`-`9` shortcut, or `null`.
+ *
+ * A DIGIT IS ONLY A SHORTCUT WHILE THE QUERY IS EMPTY. Otherwise `3` is the third
+ * character of what the user is searching for, and stealing it would make numeric
+ * queries impossible to type - so the guard is the emptiness of the query, not the
+ * shape of the key.
+ */
+export declare function pickerDigitTarget(rows: readonly PromptPickerRow[], input: string): string | null;

package/dist/ui/overlays/prompt-picker-state.js

@@ -0,0 +1,98 @@
+/**
+ * The prompt picker's view model (quick-prompt-library §4.5).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THE ROWS ARE COMPUTED OUTSIDE THE COMPONENT for the reason `kit-picker-state.ts`
+ * records one surface over: the same library is rendered by two overlays and by
+ * `/prompts list`, and three independent row builders is how "the manager says four
+ * entries and the picker says five" becomes possible without a single failing test.
+ */
+import { PROMPT_PICKER_LIMITS } from '../../prompts/limits.js';
+import { searchPrompts, viewOrder } from '../../prompts/search.js';
+import { formatAgo, formatCount } from './prompt-library-state.js';
+/**
+ * Filter the library and number the result.
+ *
+ * THE VIEW IS APPLIED FIRST, THEN THE FILTER: searching inside `recent` must return
+ * the recent order, not the manual one. Reversing the two would make `Ctrl+S` appear
+ * to do nothing whenever a query is active - which is exactly when the user is
+ * looking at the footer to see whether it worked.
+ */
+export function pickerRows(input) {
+    const ordered = viewOrder(input.library.prompts, input.view);
+    return searchPrompts(ordered, input.query).map(({ prompt }, at) => ({
+        id: prompt.id,
+        index: at + 1,
+        title: prompt.title,
+        tags: prompt.tags ?? [],
+        favorite: prompt.favorite === true,
+    }));
+}
+/**
+ * The block under the list: at most four rows, and never the whole body.
+ *
+ * The picker exists to CHOOSE. The full text belongs to the editor, and printing it
+ * here would push the chosen row off the frame that has to show it.
+ */
+export function pickerDetail(row, library, now = Date.now()) {
+    if (!row)
+        return [];
+    const prompt = library.prompts.find((entry) => entry.id === row.id);
+    if (!prompt)
+        return [];
+    const lines = [
+        `${formatCount([...prompt.content].length)} chars, `
+            + `${prompt.content.split('\n').length} lines, ${formatAgo(prompt.lastUsedAt, now)}`,
+    ];
+    if ((prompt.tags ?? []).length > 0)
+        lines.push((prompt.tags ?? []).map((t) => `#${t}`).join(' '));
+    const firstLine = prompt.content.split('\n')[0] ?? '';
+    if (firstLine.length > 0)
+        lines.push(firstLine);
+    if (prompt.description !== undefined)
+        lines.push(prompt.description);
+    return lines.slice(0, PROMPT_PICKER_LIMITS.detailMaxLines);
+}
+/**
+ * The empty-library guidance (AC-23).
+ *
+ * IT NAMES TWO WAYS OUT, because the picker is reachable from two directions: the
+ * user who typed `/prompts` on an empty library can press `a` here, and the user who
+ * does not want to type can press `Ctrl+P` later. Naming only one of them leaves the
+ * other audience pressing a key that does nothing.
+ */
+export const NO_PROMPTS_HINT = 'No prompts yet. Press Ctrl+P to create one, or a to add one here.';
+/**
+ * The footer, ordered by WHICH PATH SURVIVES ON THE WORST TERMINAL (§9.11).
+ *
+ * `Enter fill` comes before `^Enter fill & send` because a terminal without keyboard
+ * enhancement delivers `Ctrl+Enter` as a plain `Enter`: the reader who works left to
+ * right must meet the path that always works first. `tab manage` sits after the two
+ * fill actions for the same reason - it is navigation, not the point of the screen.
+ */
+export function pickerHint(input) {
+    if (input.count === 0) {
+        return input.query.length > 0
+            ? 'No match | Backspace to widen | Esc close'
+            : `${NO_PROMPTS_HINT} Esc close`;
+    }
+    return 'Enter fill | ^Enter fill & send | 1-9 pick | '
+        + `^S sort: ${input.view} | tab manage | Esc close`;
+}
+/**
+ * The `1`-`9` shortcut, or `null`.
+ *
+ * A DIGIT IS ONLY A SHORTCUT WHILE THE QUERY IS EMPTY. Otherwise `3` is the third
+ * character of what the user is searching for, and stealing it would make numeric
+ * queries impossible to type - so the guard is the emptiness of the query, not the
+ * shape of the key.
+ */
+export function pickerDigitTarget(rows, input) {
+    if (input.length !== 1)
+        return null;
+    const digit = input.charCodeAt(0) - 48;
+    if (digit < 1 || digit > PROMPT_PICKER_LIMITS.quickDigits)
+        return null;
+    return rows[digit - 1]?.id ?? null;
+}

package/dist/ui/scrollback/band.js

@@ -109,7 +109,20 @@ export function buildLiveBand(input) {
         // now gets the pool too. The branch stays as the named expression of the older policy.
         : Math.max(0, remaining - teamRows - railReserved);
     const bandRows = fill ? remaining : Math.max(railReserved, teamRows + previewRows);
-    const railRows = railVisible ? bandRows : 0;
+    // THE RAIL NO LONGER OWNS THE BAND'S FULL HEIGHT WHEN A ROSTER IS DRAWN
+    // (tui-subagent-panel §4.1.2 / D-3). The roster is now a FULL-WIDTH slot below
+    // the rail's row region, so the two no longer overlap: the rail gets exactly the
+    // rows the roster does not take. With no roster this is `bandRows`, i.e.
+    // byte-identical to the previous behaviour (I-6).
+    //
+    // I-6a, WHY THIS CANNOT STARVE THE RAIL: `teamRows <= teamCeiling =
+    // min(teamRowsNatural, remaining - panelMinRows - 1)` (step 2 above) and in
+    // `fill` mode `bandRows === remaining`, so `railRows >= panelMinRows + 1 = 4`.
+    // Four satisfies both `TODO_LIMITS.panelMinRows(3)` (the rail stays mounted) and
+    // `SCROLLBACK_LIMITS.railBandMinRows(4)` (the band still reports
+    // `reason === 'visible'`). The price of a screen-right clock is a SHORTER rail
+    // during a dispatch, never a missing one - see §4.1.4's worked example.
+    const railRows = railVisible ? Math.max(0, bandRows - teamRows) : 0;
     const railColsOut = railVisible ? railCols : 0;
     return {
         reason,

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

@@ -76,6 +76,15 @@ export declare function isSettledStatus(status: ChildStatus): boolean;
  * glyph for the spinner when it may animate.
  */
 export declare function statusGlyph(status: ChildStatus, glyphs: Glyphs): string;
+/**
+ * The widest marker this terminal's tier can produce (1 in Unicode, 4 in ASCII).
+ *
+ * EXPORTED (tui-subagent-panel §4.2.1): the panel row's geometry has to know how
+ * many columns the marker cell spends before it can divide the rest, and the cell
+ * width is a property of the TIER rather than of a status. `statusMarkerCell`
+ * keeps using it, so the padder and the measurer can never disagree.
+ */
+export declare function statusMarkerWidth(glyphs: Glyphs): number;
 /**
  * The marker padded to the tier's widest one, for the leading cell of a row.
  *
@@ -139,3 +148,19 @@ export declare function outcomePhrase(counts: RosterCounts): string;
  * normalisation depend on it staying there.
  */
 export declare function isLiveTeamCard(entry: Entry): boolean;
+/**
+ * The MOST RECENT dispatch card in the transcript, live or settled.
+ *
+ * ONE PREDICATE, TWO CONSUMERS (tui-subagent-panel §6.4): the `/agents` command
+ * and `App`'s `Ctrl+B` branch both have to answer "is there anything to show?"
+ * before opening the board, and the board itself falls back to this entry when a
+ * dispatch has already ended and `state.team` is `null` (`resolveBoardSource`).
+ * Asking the question in one place is what stops the key and the command from
+ * disagreeing about whether the board exists.
+ *
+ * Scans BACKWARDS and returns the first match: the newest card is the last one in
+ * `entries`, and a dispatch-heavy session can hold hundreds of them.
+ */
+export declare function lastTeamEntry(entries: readonly Entry[]): Extract<Entry, {
+    kind: 'team';
+}> | null;

package/dist/ui/team-status.js

@@ -92,8 +92,15 @@ export function statusGlyph(status, glyphs) {
             return glyphs.warn;
     }
 }
-/** The widest marker this terminal's tier can produce (1 in Unicode, 4 in ASCII). */
-function markerWidth(glyphs) {
+/**
+ * The widest marker this terminal's tier can produce (1 in Unicode, 4 in ASCII).
+ *
+ * EXPORTED (tui-subagent-panel §4.2.1): the panel row's geometry has to know how
+ * many columns the marker cell spends before it can divide the rest, and the cell
+ * width is a property of the TIER rather than of a status. `statusMarkerCell`
+ * keeps using it, so the padder and the measurer can never disagree.
+ */
+export function statusMarkerWidth(glyphs) {
     return Math.max(glyphs.toolPending.length, glyphs.spinnerStill.length, glyphs.toolDone.length, glyphs.toolError.length, glyphs.warn.length);
 }
 /**
@@ -106,7 +113,7 @@ function markerWidth(glyphs) {
  * padding is a no-op there.
  */
 export function statusMarkerCell(status, glyphs) {
-    return statusGlyph(status, glyphs).padEnd(markerWidth(glyphs));
+    return statusGlyph(status, glyphs).padEnd(statusMarkerWidth(glyphs));
 }
 /**
  * The colour of a status. One reading for the roster row, the card row and the
@@ -222,3 +229,24 @@ export function outcomePhrase(counts) {
 export function isLiveTeamCard(entry) {
     return entry.kind === 'team' && entry.active === true;
 }
+/**
+ * The MOST RECENT dispatch card in the transcript, live or settled.
+ *
+ * ONE PREDICATE, TWO CONSUMERS (tui-subagent-panel §6.4): the `/agents` command
+ * and `App`'s `Ctrl+B` branch both have to answer "is there anything to show?"
+ * before opening the board, and the board itself falls back to this entry when a
+ * dispatch has already ended and `state.team` is `null` (`resolveBoardSource`).
+ * Asking the question in one place is what stops the key and the command from
+ * disagreeing about whether the board exists.
+ *
+ * Scans BACKWARDS and returns the first match: the newest card is the last one in
+ * `entries`, and a dispatch-heavy session can hold hundreds of them.
+ */
+export function lastTeamEntry(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry?.kind === 'team')
+            return entry;
+    }
+    return null;
+}

package/dist/ui/use-startup-notices.d.ts

@@ -109,4 +109,38 @@ export interface VtInputNoticeOptions {
      */
     onSeen: () => void;
 }
-export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions, retainNotice?: RetainNoticeOptions, vtInputNotice?: VtInputNoticeOptions, scrollModeNotice?: ScrollModeNoticeOptions): void;
+/**
+ * The one-shot prompt-key migration notice (quick-prompt-library D-20).
+ *
+ * IT EXISTS BECAUSE A KEY MOVED: `Ctrl+P` now opens the prompt library and the mode
+ * fallback is `Ctrl+N`. Every existing user is in the audience, so silence is not an
+ * option - and, exactly like the two notices above, the gate is a VERSION so a later
+ * rewording can reach the people who learned the first one.
+ */
+export interface PromptKeyNoticeOptions {
+    /** Record that `PROMPT_KEY_NOTICE_VERSION` was shown (`state.json`). */
+    onSeen: () => void;
+}
+/**
+ * The revision of the prompt-key notice a user must have seen for it to stay quiet
+ * (`state.json::promptKeyNoticeVersion`, `0` when absent). BUMP IT WHENEVER THE ADVICE
+ * CHANGES, never for a rewording.
+ */
+export declare const PROMPT_KEY_NOTICE_VERSION = 1;
+/**
+ * The startup notices, as ONE options object.
+ *
+ * SIX NOTICES, TWO PARAMETERS. This hook used to take five POSITIONAL arguments and
+ * this feature would have made it six, which `CLAUDE.md` forbids outright ("函数形参不超过
+ * 5 个") and which has no good answer anyway: a sixth positional boolean-shaped
+ * argument is unreadable at the call site and un-diffable in review. The object also
+ * makes an older caller that passes nothing byte-identical to today.
+ */
+export interface StartupNoticeOptions {
+    mouse?: MouseNoticeOptions;
+    retain?: RetainNoticeOptions;
+    vtInput?: VtInputNoticeOptions;
+    scrollMode?: ScrollModeNoticeOptions;
+    promptKeys?: PromptKeyNoticeOptions;
+}
+export declare function useStartupNotices(dispatch: (action: ViewAction) => void, options: StartupNoticeOptions): void;