@aragon-agent/cli 0.6.34 → 0.6.36

package/dist/ui/scrollback/use-scrollback-view.js

@@ -52,6 +52,7 @@
  */
 import { useCallback, useEffect, useLayoutEffect, useMemo, useReducer, useRef } from 'react';
 import { estimateEntryRows } from '../layout/virtual-window.js';
+import { isLiveTeamCard } from '../team-status.js';
 import { buildScrollbackBudget } from './budget.js';
 import { buildLivePreview } from './live-preview.js';
 import { SCROLLBACK_LIMITS } from './limits.js';
@@ -554,6 +555,12 @@ export function useScrollbackView(args) {
         if (index < 0)
             return false;
         const entry = list[index];
+        // A LIVE DISPATCH CARD IS REFUSED, NOT PRINTED (tui-subagent-double-roster A-2').
+        // `Ctrl+O` arrives mid-dispatch, `EntryView` suppresses this card, and a copy
+        // printed here would be a FROZEN SNAPSHOT of a card the roster is still rewriting -
+        // permanently in the scrollback, because printed is forever.
+        if (isLiveTeamCard(entry))
+            return false;
         // THE COPY IS RENDERED IN A MICROTASK, NOT IN THE KEY HANDLER THAT ASKED FOR IT.
         // `Ctrl+O` arrives on the stdin stream, and an offscreen render issued from there is
         // SCHEDULED rather than flushed - the reconciler sees a pending update, the frame the

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

@@ -0,0 +1,166 @@
+/**
+ * Team status — the ONE authority that answers "what state is this child in, and
+ * how is that drawn / counted / timed" (tui-subagent-double-roster A-1).
+ *
+ * WHY THIS FILE EXISTS. The phase -> glyph / colour / count question used to be
+ * answered by nine copies in seven files, and they disagreed. The transcript card
+ * asked `isOk(run) ? toolDone : toolError`, so six of the eight phases - every
+ * child that was still working - were painted with the FAILURE glyph, and an
+ * aborted child was counted as a failed one forever. That is not a palette
+ * mistake, it is a judgement implemented in the wrong number of places.
+ *
+ * THE VOCABULARY IS THE DOMAIN'S (analysis A-1' item 3). `ChildStatus` reuses
+ * `SubagentPhase`'s own words - `queued` / `running` / `done` / `failed` /
+ * `aborted` - and never invents a second dictionary (`pending` was proposed and
+ * rejected: `SubagentPhase` does not have it, and two words for one state is how
+ * the tenth copy gets written).
+ *
+ * FIVE STATES, NOT FOUR (A-1' item 2). `aborted` is NOT a failure. The runtime
+ * distinguishes them on purpose (`Runtime.settlePhase`: aborted first, then the
+ * timeout, then the error), and a user pressing Esc must not read their own
+ * action back as "3 failed". So `aborted` takes `glyphs.warn` and
+ * `theme.noticeWarn`, which collide with neither the done tick nor the failed
+ * cross in either glyph tier.
+ *
+ * ASCII ONLY: `src/ui/**` is inside `glyphs.test.ts`'s static scan, so every
+ * symbol here is injected through `pickGlyphs(caps)`.
+ */
+import type { Entry } from '../agent/reducer.js';
+import type { SubagentRun } from '../team/types.js';
+import type { Glyphs } from './glyphs.js';
+import type { Theme } from './theme.js';
+/**
+ * The five readings a child can have on screen. A TOTAL mapping of
+ * `SubagentPhase`, which is why `childStatus` needs no guard clauses: `starting`,
+ * `thinking`, `tool` and `waiting` are all "this child is working right now", and
+ * the per-row activity column is what tells them apart.
+ */
+export type ChildStatus = 'queued' | 'running' | 'done' | 'failed' | 'aborted';
+/**
+ * The status of one child.
+ *
+ * A LOOKUP TABLE RATHER THAN A SWITCH, because the mapping is the whole content
+ * of this function: a `Record` keyed by the phase union is exhaustive at compile
+ * time (a new phase is a missing-key error) and cannot drift from the type.
+ */
+export declare function childStatus(run: SubagentRun): ChildStatus;
+/** Per-status totals of a roster. `total` is the roster size, not the sum. */
+export interface RosterCounts {
+    queued: number;
+    running: number;
+    done: number;
+    failed: number;
+    aborted: number;
+    total: number;
+}
+/**
+ * Count a roster once, by status.
+ *
+ * THE HEADER, THE CARD HEADLINE AND THE STATUS CHIP ALL READ THIS. Before it
+ * existed the header filtered `phase !== 'queued' && ...` for "running" and the
+ * card subtracted `runs.length - isOk(runs)`, so the same dispatch reported
+ * `0 running` above two rows reading `queued` and `1 failed` for a child that had
+ * never started.
+ */
+export declare function rosterCounts(runs: readonly SubagentRun[]): RosterCounts;
+/** True while the child is doing something - the only state that animates. */
+export declare function isRunningStatus(status: ChildStatus): boolean;
+/** True once the child's outcome is final, whatever it is. */
+export declare function isSettledStatus(status: ChildStatus): boolean;
+/**
+ * The static marker for a status.
+ *
+ * `running` gets `spinnerStill` because the animated `<Spinner>` is the caller's
+ * job: it needs `reducedMotion` and `caps.unicode`, and a component that owns its
+ * own `ink-spinner` is what `spinner-census.test.ts` counts. The caller swaps this
+ * 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.
+ *
+ * THE PADDING IS NOT COSMETIC (A-1'a): the ASCII tier spells `[ok]` (4), `[x]` (3)
+ * and `!` (1), so an unpadded marker cell starts every label at a different
+ * column and the roster stops reading as a table. `TodoPanel` pads its marker cell
+ * for the same reason. The Unicode tier's markers are all one cell wide, so the
+ * padding is a no-op there.
+ */
+export declare function statusMarkerCell(status: ChildStatus, glyphs: Glyphs): string;
+/**
+ * The colour of a status. One reading for the roster row, the card row and the
+ * card's rail marker.
+ *
+ * `aborted` deliberately does NOT share `toolError` with `failed`: an abort is the
+ * user's own Esc, and the analysis found that painting it red made a cancelled
+ * dispatch permanently unreadable in the history.
+ */
+export declare function statusColor(status: ChildStatus, theme: Theme): string | undefined;
+/**
+ * How long this child has been (or was) working, in ms.
+ *
+ * `endedAt ?? now`, NOT `endedAt ?? 0`. The transcript card used the latter, which
+ * made every RUNNING child read `0ms` while the roster beside it read `1m05s` for
+ * the same child - the pair of contradictory readouts the reporter screenshotted.
+ */
+export declare function childElapsedMs(run: SubagentRun, now: number): number;
+/**
+ * The roster header's count section, e.g. `2 running · 0 done · 1 queued`.
+ *
+ * `queued` IS COUNTED (the old `isRunning` excluded it, so a fresh dispatch
+ * announced `0 running · 0 done` above five rows that each said `queued`), and a
+ * non-zero bucket is always named even when nothing is running - a roster whose
+ * children are all `aborted` must say so rather than `0 running · 0 done`.
+ *
+ * WIDTH LADDER: narrow terminals drop the least urgent clause first, in the order
+ * `done`, `aborted`, `failed`, `queued`; `running` is never dropped. The order is
+ * a product decision, not a detail: while a dispatch is live, what is happening
+ * now outranks what has already finished, and the per-row activity column carries
+ * the finished children's own facts anyway.
+ */
+export declare function rosterHeadline(counts: RosterCounts, glyphs: Glyphs, cols: number): string;
+/**
+ * The settled card's outcome buckets, e.g. `2 ok, 1 aborted, 1 failed`.
+ *
+ * `ok` is always shown (it is the denominator a reader compares against) and a
+ * zero bucket is omitted, so a clean dispatch still reads `3 ok` and a failed one
+ * no longer claims that a cancelled child failed.
+ */
+export declare function outcomePhrase(counts: RosterCounts): string;
+/**
+ * Whether this entry is the transcript card of a dispatch that is STILL RUNNING,
+ * i.e. the second live surface the reporter saw beside the roster.
+ *
+ * ONE PREDICATE, FOUR CONSUMERS (analysis A-2'): the transcript's `case 'team'`
+ * and `estimateEntryRows` (so the virtual window and the frame agree), the tail
+ * window and `LiveTail` (so the pump's print plan and the box agree), and the
+ * `Ctrl+O` finder plus `reprintExpanded` (so a keypress cannot print a stale
+ * snapshot of a card that is still being rewritten). `state.entries` is NEVER
+ * filtered: the entry's lifecycle and `session/persist.ts`'s `interrupted`
+ * 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

@@ -0,0 +1,252 @@
+/**
+ * Team status — the ONE authority that answers "what state is this child in, and
+ * how is that drawn / counted / timed" (tui-subagent-double-roster A-1).
+ *
+ * WHY THIS FILE EXISTS. The phase -> glyph / colour / count question used to be
+ * answered by nine copies in seven files, and they disagreed. The transcript card
+ * asked `isOk(run) ? toolDone : toolError`, so six of the eight phases - every
+ * child that was still working - were painted with the FAILURE glyph, and an
+ * aborted child was counted as a failed one forever. That is not a palette
+ * mistake, it is a judgement implemented in the wrong number of places.
+ *
+ * THE VOCABULARY IS THE DOMAIN'S (analysis A-1' item 3). `ChildStatus` reuses
+ * `SubagentPhase`'s own words - `queued` / `running` / `done` / `failed` /
+ * `aborted` - and never invents a second dictionary (`pending` was proposed and
+ * rejected: `SubagentPhase` does not have it, and two words for one state is how
+ * the tenth copy gets written).
+ *
+ * FIVE STATES, NOT FOUR (A-1' item 2). `aborted` is NOT a failure. The runtime
+ * distinguishes them on purpose (`Runtime.settlePhase`: aborted first, then the
+ * timeout, then the error), and a user pressing Esc must not read their own
+ * action back as "3 failed". So `aborted` takes `glyphs.warn` and
+ * `theme.noticeWarn`, which collide with neither the done tick nor the failed
+ * cross in either glyph tier.
+ *
+ * ASCII ONLY: `src/ui/**` is inside `glyphs.test.ts`'s static scan, so every
+ * symbol here is injected through `pickGlyphs(caps)`.
+ */
+const STATUS_BY_PHASE = {
+    queued: 'queued',
+    starting: 'running',
+    thinking: 'running',
+    tool: 'running',
+    waiting: 'running',
+    done: 'done',
+    failed: 'failed',
+    aborted: 'aborted',
+};
+/**
+ * The status of one child.
+ *
+ * A LOOKUP TABLE RATHER THAN A SWITCH, because the mapping is the whole content
+ * of this function: a `Record` keyed by the phase union is exhaustive at compile
+ * time (a new phase is a missing-key error) and cannot drift from the type.
+ */
+export function childStatus(run) {
+    return STATUS_BY_PHASE[run.phase];
+}
+/**
+ * Count a roster once, by status.
+ *
+ * THE HEADER, THE CARD HEADLINE AND THE STATUS CHIP ALL READ THIS. Before it
+ * existed the header filtered `phase !== 'queued' && ...` for "running" and the
+ * card subtracted `runs.length - isOk(runs)`, so the same dispatch reported
+ * `0 running` above two rows reading `queued` and `1 failed` for a child that had
+ * never started.
+ */
+export function rosterCounts(runs) {
+    const counts = {
+        queued: 0, running: 0, done: 0, failed: 0, aborted: 0, total: runs.length,
+    };
+    for (const run of runs)
+        counts[childStatus(run)] += 1;
+    return counts;
+}
+/** True while the child is doing something - the only state that animates. */
+export function isRunningStatus(status) {
+    return status === 'running';
+}
+/** True once the child's outcome is final, whatever it is. */
+export function isSettledStatus(status) {
+    return status === 'done' || status === 'failed' || status === 'aborted';
+}
+/**
+ * The static marker for a status.
+ *
+ * `running` gets `spinnerStill` because the animated `<Spinner>` is the caller's
+ * job: it needs `reducedMotion` and `caps.unicode`, and a component that owns its
+ * own `ink-spinner` is what `spinner-census.test.ts` counts. The caller swaps this
+ * glyph for the spinner when it may animate.
+ */
+export function statusGlyph(status, glyphs) {
+    switch (status) {
+        case 'queued':
+            return glyphs.toolPending;
+        case 'running':
+            return glyphs.spinnerStill;
+        case 'done':
+            return glyphs.toolDone;
+        case 'failed':
+            return glyphs.toolError;
+        case 'aborted':
+            return glyphs.warn;
+    }
+}
+/**
+ * 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);
+}
+/**
+ * The marker padded to the tier's widest one, for the leading cell of a row.
+ *
+ * THE PADDING IS NOT COSMETIC (A-1'a): the ASCII tier spells `[ok]` (4), `[x]` (3)
+ * and `!` (1), so an unpadded marker cell starts every label at a different
+ * column and the roster stops reading as a table. `TodoPanel` pads its marker cell
+ * for the same reason. The Unicode tier's markers are all one cell wide, so the
+ * padding is a no-op there.
+ */
+export function statusMarkerCell(status, glyphs) {
+    return statusGlyph(status, glyphs).padEnd(statusMarkerWidth(glyphs));
+}
+/**
+ * The colour of a status. One reading for the roster row, the card row and the
+ * card's rail marker.
+ *
+ * `aborted` deliberately does NOT share `toolError` with `failed`: an abort is the
+ * user's own Esc, and the analysis found that painting it red made a cancelled
+ * dispatch permanently unreadable in the history.
+ */
+export function statusColor(status, theme) {
+    switch (status) {
+        case 'queued':
+            return theme.toolPending;
+        case 'running':
+            return theme.toolRunning;
+        case 'done':
+            return theme.toolDone;
+        case 'failed':
+            return theme.toolError;
+        case 'aborted':
+            return theme.noticeWarn;
+    }
+}
+/**
+ * How long this child has been (or was) working, in ms.
+ *
+ * `endedAt ?? now`, NOT `endedAt ?? 0`. The transcript card used the latter, which
+ * made every RUNNING child read `0ms` while the roster beside it read `1m05s` for
+ * the same child - the pair of contradictory readouts the reporter screenshotted.
+ */
+export function childElapsedMs(run, now) {
+    if (run.startedAt === undefined)
+        return 0;
+    return Math.max(0, (run.endedAt ?? now) - run.startedAt);
+}
+/**
+ * Columns the roster header spends on `team` (plus its marker) and on the
+ * incoming-message badge, so the count clauses are planned against what is left.
+ */
+const HEADER_RESERVED_COLS = 16;
+const HEADER_MIN_CLAUSE_COLS = 12;
+function joinClauses(clauses, glyphs) {
+    return clauses.map((clause) => clause.text).join(` ${glyphs.midDot} `);
+}
+/** Drop the clause that can be spared first, keeping display order intact. */
+function dropLowestPriority(clauses) {
+    let victim = 0;
+    for (let index = 1; index < clauses.length; index += 1) {
+        if (clauses[index].priority < clauses[victim].priority)
+            victim = index;
+    }
+    return clauses.filter((_, index) => index !== victim);
+}
+/**
+ * The roster header's count section, e.g. `2 running · 0 done · 1 queued`.
+ *
+ * `queued` IS COUNTED (the old `isRunning` excluded it, so a fresh dispatch
+ * announced `0 running · 0 done` above five rows that each said `queued`), and a
+ * non-zero bucket is always named even when nothing is running - a roster whose
+ * children are all `aborted` must say so rather than `0 running · 0 done`.
+ *
+ * WIDTH LADDER: narrow terminals drop the least urgent clause first, in the order
+ * `done`, `aborted`, `failed`, `queued`; `running` is never dropped. The order is
+ * a product decision, not a detail: while a dispatch is live, what is happening
+ * now outranks what has already finished, and the per-row activity column carries
+ * the finished children's own facts anyway.
+ */
+export function rosterHeadline(counts, glyphs, cols) {
+    const clauses = [
+        { priority: 5, text: `${counts.running} running` },
+        { priority: 1, text: `${counts.done} done` },
+    ];
+    if (counts.queued > 0)
+        clauses.push({ priority: 4, text: `${counts.queued} queued` });
+    if (counts.failed > 0)
+        clauses.push({ priority: 3, text: `${counts.failed} failed` });
+    if (counts.aborted > 0)
+        clauses.push({ priority: 2, text: `${counts.aborted} aborted` });
+    const budget = Math.max(HEADER_MIN_CLAUSE_COLS, cols - HEADER_RESERVED_COLS);
+    let kept = clauses;
+    while (kept.length > 1 && joinClauses(kept, glyphs).length > budget) {
+        kept = dropLowestPriority(kept);
+    }
+    return joinClauses(kept, glyphs);
+}
+/**
+ * The settled card's outcome buckets, e.g. `2 ok, 1 aborted, 1 failed`.
+ *
+ * `ok` is always shown (it is the denominator a reader compares against) and a
+ * zero bucket is omitted, so a clean dispatch still reads `3 ok` and a failed one
+ * no longer claims that a cancelled child failed.
+ */
+export function outcomePhrase(counts) {
+    const parts = [`${counts.done} ok`];
+    if (counts.aborted > 0)
+        parts.push(`${counts.aborted} aborted`);
+    if (counts.failed > 0)
+        parts.push(`${counts.failed} failed`);
+    return parts.join(', ');
+}
+/**
+ * Whether this entry is the transcript card of a dispatch that is STILL RUNNING,
+ * i.e. the second live surface the reporter saw beside the roster.
+ *
+ * ONE PREDICATE, FOUR CONSUMERS (analysis A-2'): the transcript's `case 'team'`
+ * and `estimateEntryRows` (so the virtual window and the frame agree), the tail
+ * window and `LiveTail` (so the pump's print plan and the box agree), and the
+ * `Ctrl+O` finder plus `reprintExpanded` (so a keypress cannot print a stale
+ * snapshot of a card that is still being rewritten). `state.entries` is NEVER
+ * filtered: the entry's lifecycle and `session/persist.ts`'s `interrupted`
+ * normalisation depend on it staying there.
+ */
+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/transcript-text.js

@@ -1,5 +1,6 @@
 import { formatCost, formatDuration, formatTokens, promptTokensOf } from '../agent/usage.js';
 import { formatRetryLine } from '../agent/retry-view.js';
+import { childStatus, outcomePhrase, rosterCounts, statusMarkerCell } from './team-status.js';
 import { expandTabs } from './display-tab.js';
 const DEFAULT_MAX_ENTRIES = 200;
 const CONTINUATION_INDENT = '  ';
@@ -101,15 +102,23 @@ function renderEntry(entry, glyphs) {
             // dispatch is often the most expensive thing in a session, so leaving it
             // out of the plain-text replay would make the exported transcript
             // unaccountable for most of its own cost.
-            const ok = entry.runs.filter((r) => r.phase === 'done' && !r.error).length;
-            const failed = entry.runs.length - ok;
+            // ONE COUNTING AUTHORITY (`team-status.ts`), so the replay cannot disagree with
+            // the card it replays: `runs.length - ok` counted a cancelled child as a failed
+            // one, and a still-working one as a failure (tui-subagent-double-roster E3/E8).
+            // A cancellation therefore gets its own bucket instead of inflating `failed`.
+            const counts = rosterCounts(entry.runs);
             const head = entry.active || (entry.aborted && entry.durationMs === undefined)
                 ? 'interrupted'
-                : `${entry.durationMs ?? 0}ms (${ok} ok, ${failed} failed)`;
+                : `${entry.durationMs ?? 0}ms (${outcomePhrase(counts)})`;
             const lines = [
                 `${TOOL_INDENT}team ${entry.runs.length} subagents ${head}`,
                 ...entry.runs.map((run) => {
-                    const glyph = run.phase === 'done' && !run.error ? glyphs.toolDone : glyphs.toolError;
+                    // The same five-state judgement the card uses: only a real failure takes
+                    // the cross, a cancelled child takes the warning and a running one the
+                    // running marker. `statusMarkerCell`, NOT the bare glyph: the ASCII tier
+                    // spells `[ok]`, `[x]` and `!` at three widths, and a replay whose label
+                    // column shifts from row to row is unreadable.
+                    const glyph = statusMarkerCell(childStatus(run), glyphs);
                     const detail = run.error ? ` ${run.error}` : '';
                     return `${TOOL_INDENT}${CONTINUATION_INDENT}${glyph} ${run.label} ${run.description}${detail}`;
                 }),

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;

package/dist/ui/use-startup-notices.js

@@ -14,7 +14,8 @@
 import { useEffect, useRef } from 'react';
 import { MODE_TOGGLE_KEYS } from '../agent/agent-mode.js';
 import { readConfigFile } from '../config/store.js';
-import { getMouseNoticeVersion, getScrollModeNoticeVersion, getVtInputNoticeVersion, } from '../config/ui-state.js';
+import { getMouseNoticeVersion, getPromptKeyNoticeVersion, getScrollModeNoticeVersion, getVtInputNoticeVersion, } from '../config/ui-state.js';
+import { PROMPT_KEY_NOTICE_COPY } from '../prompts/copy.js';
 import { getLogger } from '../logging/logger.js';
 /**
  * The revision of the mouse notice a user must have seen for it to stay quiet
@@ -103,7 +104,14 @@ export function scrollModeNoticeText() {
     return ('Scrolling now uses your terminal: wheel, scrollbar, selection and search all work as ' +
         'usual. Prefer the old full-screen view? Run: aragon config set scrollMode app');
 }
-export function useStartupNotices(dispatch, mouseNotice, retainNotice, vtInputNotice, scrollModeNotice) {
+/**
+ * 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 const PROMPT_KEY_NOTICE_VERSION = 1;
+export function useStartupNotices(dispatch, options) {
+    const { mouse: mouseNotice, retain: retainNotice, vtInput: vtInputNotice, scrollMode: scrollModeNotice, promptKeys: promptKeyNotice, } = options;
     // The sink gives up after repeated write failures (a read-only log directory,
     // a full disk). Silently logging nothing is exactly the state a user must not
     // discover later, from an empty file, while trying to explain a bug.
@@ -193,6 +201,25 @@ export function useStartupNotices(dispatch, mouseNotice, retainNotice, vtInputNo
         dispatch({ type: 'notice', level: 'info', text: scrollModeNoticeText() });
         scrollNoticeRef.current?.onSeen();
     }, [scrollNoticeWanted, dispatch]);
+    // THE PROMPT-KEY MIGRATION (quick-prompt-library D-20). A durable `notice` and not
+    // a toast, for the reason every "you must learn a key" message in this file is one:
+    // a toast expires, and the whole mitigation for a moved key is that the sentence is
+    // READ. It queues LAST because it explains a key rather than making one work.
+    const promptNoticeRef = useRef(promptKeyNotice);
+    promptNoticeRef.current = promptKeyNotice;
+    const promptKeyWanted = promptKeyNotice !== undefined;
+    const promptKeyShown = useRef(false);
+    useEffect(() => {
+        if (!promptKeyWanted || promptKeyShown.current)
+            return;
+        // `>=`, not `!==`: a state file written by a NEWER build has already told this
+        // user everything the text below says.
+        if (getPromptKeyNoticeVersion() >= PROMPT_KEY_NOTICE_VERSION)
+            return;
+        promptKeyShown.current = true;
+        dispatch({ type: 'notice', level: 'info', text: PROMPT_KEY_NOTICE_COPY });
+        promptNoticeRef.current?.onSeen();
+    }, [promptKeyWanted, dispatch]);
     // A `warn` notice rather than a toast: it is about a value the user typed, so
     // it belongs in the transcript where it can be scrolled back to, not in a row
     // that expires. DEPENDS ON THE TWO SCALARS, never on the options object —

package/dist/ui/use-wheel-routing.js

@@ -109,8 +109,16 @@ export function useWheelRouting(options) {
         if (overlay) {
             // Modes A only. `model` / `confirm` / `question` own their own keys and
             // scrolling them would leave an inconsistent cursor (R-11).
-            const controlled = overlay === 'help' || overlay === 'settings'
-                || overlay === 'plan' || overlay === 'queue';
+            const controlled = overlay === 'help' || overlay === 'settings' || overlay === 'plan'
+                || overlay === 'queue' || overlay === 'kit'
+                // The prompt surfaces (quick-prompt-library appendix B-2). Missing this line
+                // makes the wheel fall through to the transcript BEHIND an open overlay,
+                // which reads as a frozen list and a jumping transcript at the same time.
+                || overlay === 'prompts' || overlay === 'prompt-pick'
+                // The Agents board (tui-subagent-panel §6.5). Missing this line makes the
+                // wheel fall through to the transcript BEHIND the open board, which reads
+                // as a frozen list and a jumping transcript at the same time.
+                || overlay === 'agents';
             if (!controlled)
                 return;
             // D-3: the row is not consulted here either. Behind an overlay the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.6.34",
+  "version": "0.6.36",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -56,7 +56,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.46",
+    "@aragon-agent/core": "^0.2.48",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",