@aragon-agent/cli 0.6.35 → 0.6.36

package/dist/ui/layout/team-row.js

@@ -0,0 +1,246 @@
+/**
+ * Panel row geometry — the ONE authority for how a subagent row is measured and
+ * what it says (tui-subagent-panel §4.2 / §6.1).
+ *
+ * WHY THIS FILE EXISTS. The roster used to place its right-hand columns by
+ * `flexGrow`, and a fixed-height parent box makes Yoga stretch the column to its
+ * widest CHILD instead of to the available width: on a 100-column terminal inside
+ * the band slot the row measured 48 (spec §0.1, cases 3/4), so `grep  22.1s` sat
+ * hard against the description and the right half of the row was blank. Flex
+ * cannot fix that, because the number it needs - "how wide is this terminal" - is
+ * not part of the layout it is given. So the widths are COMPUTED here, by a total
+ * pure function, and the component only places fixed-width boxes at the offsets
+ * this module names.
+ *
+ * THE FIVE CELLS, in drawing order:
+ *
+ *     marker(1+status+1) label(8) description(flex) gap(2) activity(n) clock(8)
+ *
+ * `description` is the ONLY flexible cell, and it is the one that absorbs every
+ * width pressure - the same degradation discipline `StatusBar` documents for its
+ * left cluster. The two right-hand cells are fixed and `flexShrink={0}`, so their
+ * absolute offsets follow from `rowWidth = parentWidth` and the sum of the fixed
+ * cells in front of them, and never from how a particular frame allocates slack.
+ *
+ * ASCII ONLY: `src/ui/**` is inside `glyphs.test.ts`'s static scan.
+ *
+ * THE ACTIVITY HELPERS LIVE HERE TOO (v2 implementation note, recorded in the
+ * spec's "implementation findings"). `teamRowCells` has to compose the activity
+ * text with the supervisor badge, which is what `activityWithBadge` already does;
+ * leaving those in `TeamPanel.tsx` would make this module and the component
+ * import each other. `TeamPanel` therefore RE-EXPORTS every symbol below, so the
+ * existing import sites (three test files) keep their import path unchanged.
+ */
+import { describeToolActivity, sanitizeActivity } from '../../team/activity.js';
+import { TEAM_LIMITS } from '../../team/limits.js';
+import { formatDuration } from '../../agent/usage.js';
+import { fitCells } from './cells.js';
+import { childElapsedMs, childStatus, statusMarkerCell, statusMarkerWidth } from '../team-status.js';
+/** The clock cell: wide enough for `125m07s` (7) with one column of headroom. */
+export const TEAM_CLOCK_CELLS = 8;
+/** `run.label.padEnd(8).slice(0,8)` — unchanged from the row this replaces. */
+export const TEAM_LABEL_CELLS = 8;
+/** The two spaces in front of the activity cell. */
+export const TEAM_GAP_CELLS = 2;
+/**
+ * The description column's floor: below this the row is unreadable, so the
+ * activity cell gives way instead (`activityDropCols`).
+ */
+export const TEAM_MIN_DESCRIPTION_CELLS = 12;
+/**
+ * The concession to code units vs terminal columns, inherited verbatim from the
+ * `WIDE_CHAR_ALLOWANCE` comment on the row this replaces: this budget is
+ * denominated in code units while the terminal is denominated in columns, and CJK
+ * and emoji occupy two columns per unit, so the budget is halved against the
+ * reserve rather than spent to the last cell. Erring small costs a few characters
+ * of prose; erring large costs the clock column.
+ */
+const WIDE_CHAR_ALLOWANCE = 2;
+/** The marker cell of the Unicode tier, used as the default by callers that pass no tier. */
+const DEFAULT_MARKER_CELLS = 3;
+function nonNegativeInt(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+/**
+ * How many characters the activity cell may spend at this width.
+ *
+ * `TEAM_LIMITS.activityChars` is a STORAGE ceiling; a terminal has a COLUMN
+ * budget, and the two are not the same number. Below
+ * `TEAM_LIMITS.activityDropCols` the cell gives way ENTIRELY (returns 0) rather
+ * than shrinking to its 12-character floor: at 40 columns those twelve characters
+ * would push the description below its own floor, and "who is doing what" outranks
+ * "what they are writing right now" exactly when there is room for one of them.
+ * That is a semantic change to a shipped assertion (`activityBudget(40)` used to
+ * return 12) and is recorded in the spec's §10 collateral table.
+ *
+ * `markerCells` defaults to the Unicode tier so the three existing single-argument
+ * call sites keep compiling; the panel passes the real tier's width.
+ */
+export function activityBudget(cols, markerCells = DEFAULT_MARKER_CELLS) {
+    if (!Number.isFinite(cols) || cols < TEAM_LIMITS.activityDropCols)
+        return 0;
+    const fixed = markerCells + TEAM_LABEL_CELLS + TEAM_GAP_CELLS + TEAM_CLOCK_CELLS
+        + TEAM_MIN_DESCRIPTION_CELLS;
+    const spare = Math.floor((cols - fixed) / WIDE_CHAR_ALLOWANCE);
+    return Math.max(TEAM_LIMITS.activityMinChars, Math.min(TEAM_LIMITS.activityChars, spare));
+}
+/**
+ * The row's cell widths. A TOTAL function: every cell is a non-negative integer
+ * and the five of them never sum past `cols`, for any `cols >= 0` and either
+ * glyph tier (I-3, `team-row-geometry.test.ts`'s property test).
+ *
+ * THE LADDER IS THE SPECIFICATION (§4.2.2), in the order the cells give way:
+ *   1. a wide enough terminal gets the business budget;
+ *   2. below `activityDropCols` the activity cell is 0;
+ *   3. description still negative -> the gap goes;
+ *   4. still negative -> the label shrinks to `max(3, cols - marker - clock)`;
+ *   5. still negative -> the clock shrinks (`cols < marker + 3 + clock`);
+ *   6. the residue (a terminal narrower than the marker itself) is clamped so the
+ *      sum stays inside `cols` — unreachable on a real device, where native mode
+ *      degrades to the placeholder below 40x12, but the function is total because
+ *      the property test runs `cols = 1..400`.
+ */
+export function teamRowGeometry(cols, glyphs) {
+    const width = nonNegativeInt(cols);
+    const markerCells = 1 + statusMarkerWidth(glyphs) + 1;
+    const cells = {
+        marker: Math.min(markerCells, width),
+        label: TEAM_LABEL_CELLS,
+        gap: TEAM_GAP_CELLS,
+        activity: activityBudget(width, markerCells),
+        clock: TEAM_CLOCK_CELLS,
+        minDescription: TEAM_MIN_DESCRIPTION_CELLS,
+    };
+    const sum = () => cells.marker + cells.label + cells.gap + cells.activity + cells.clock;
+    if (sum() > width)
+        cells.gap = 0;
+    if (sum() > width)
+        cells.label = Math.max(3, width - cells.marker - cells.clock);
+    if (sum() > width)
+        cells.clock = Math.max(0, Math.min(TEAM_CLOCK_CELLS, width - cells.marker - cells.label));
+    if (sum() > width)
+        cells.label = Math.max(0, Math.min(cells.label, width - cells.marker));
+    cells.minDescription = sum() >= width ? 0 : TEAM_MIN_DESCRIPTION_CELLS;
+    return cells;
+}
+/**
+ * The clock cell's text: this child's elapsed time, or empty when it never
+ * started (a `queued` row has no clock to show, and `0ms` would be a lie).
+ */
+export function teamClockText(run, at) {
+    return run.startedAt === undefined ? '' : formatDuration(childElapsedMs(run, at));
+}
+/** The past-tense word the supervisor badge and status line render. */
+export function interventionWord(action) {
+    switch (action) {
+        case 'nudge':
+            return 'nudged';
+        case 'replace':
+            return 'replaced';
+        case 'abandon':
+            return 'abandoned';
+        default:
+            return 'waited';
+    }
+}
+/**
+ * The row's supervisor badge (subagent-overseer-v2 AC-5): what the supervisor
+ * last did to THIS child and how long ago, e.g. `nudged 2m03s`.
+ *
+ * `lastIntervention.at` is ABSOLUTE epoch ms (R-P2-3), the same units as
+ * `startedAt`, so this is one subtraction - no second clock convention.
+ */
+export function overseerBadge(run, at) {
+    const last = run.lastIntervention;
+    if (last === undefined)
+        return '';
+    return `${interventionWord(last.action)} ${formatDuration(Math.max(0, at - last.at))}`;
+}
+/**
+ * The middle cell: what this child is doing right now, in a few words.
+ *
+ * Two width policies, answering different questions. `wide` decides WHICH FACT to
+ * show - a whole path or its basename, a whole command line or its program name -
+ * mirroring `StatusBar`'s `statusCompactCols` degradation rather than inventing a
+ * second threshold. `activityBudget(cols)` decides HOW MUCH OF IT FITS, and it is
+ * a continuous function of width rather than a threshold, because the failure it
+ * prevents - a row wider than the terminal - is continuous.
+ */
+export function activityLine(run, cols, markerCells) {
+    const wide = cols >= TEAM_LIMITS.activityWideCols;
+    const budget = activityBudget(cols, markerCells);
+    switch (run.phase) {
+        case 'queued':
+            return 'queued';
+        case 'starting':
+            // The one row that legitimately restarts its clock, saying why (P2-4):
+            // F-2 ranks the running group by `startedAt` and a retry re-stamps it.
+            return run.retries ? 'starting (retry)' : 'starting';
+        case 'thinking':
+            // Clamped AT RENDER, against this terminal's budget. `run.activity` was
+            // clamped at STORE against `activityChars`; that is a ceiling, not a fit.
+            return run.activity ? `writing: ${sanitizeActivity(run.activity, budget)}` : 'thinking';
+        case 'tool':
+        case 'waiting':
+            return run.lastTool
+                ? sanitizeActivity(describeToolActivity(run.lastTool, run.activityArgs, wide), budget)
+                : run.phase === 'waiting'
+                    ? 'waiting for mail'
+                    : 'tool';
+        case 'done':
+            // `compacted N` ON THE SETTLED ROW ONLY (hardening §3.4.4 / W3). A running
+            // row is already competing for `activityBudget(cols)` with the child's own
+            // prose, and a marker that displaces what the child is DOING right now
+            // buys nothing - the dispatch report carries the same fact for good.
+            return run.compactions
+                ? `done  ${run.turns} turns  compacted ${run.compactions}`
+                : `done  ${run.turns} turns`;
+        case 'failed':
+            return 'failed';
+        case 'aborted':
+            return 'aborted';
+    }
+}
+/**
+ * The activity cell WITH the badge composed in (AC-5 / risk table): the badge
+ * rides the SAME allocation the prose uses, so a row can never grow past its
+ * terminal; on a narrow terminal the badge degrades to the action word alone -
+ * the who-acted fact outranks the what-they-are-doing tail exactly when there is
+ * room for only one.
+ */
+export function activityWithBadge(run, cols, at, markerCells) {
+    const last = run.lastIntervention;
+    if (last === undefined)
+        return activityLine(run, cols, markerCells);
+    const badge = overseerBadge(run, at);
+    if (cols < TEAM_LIMITS.activityWideCols)
+        return interventionWord(last.action);
+    return sanitizeActivity(`${badge}; ${activityLine(run, cols, markerCells)}`, activityBudget(cols, markerCells));
+}
+/**
+ * The five text fragments of one row.
+ *
+ * The description is normalized here rather than in the component because
+ * truncation preserves explicit newlines and the band reserves exactly ONE row
+ * for a child: a description carrying a newline would make the row two rows tall
+ * and every row below it would land one row lower than `band.teamRows` allows.
+ */
+export function teamRowCells(run, cols, at, glyphs) {
+    const geometry = teamRowGeometry(cols, glyphs);
+    // THE TEXT IS CLAMPED TO THE SAME WIDTH THE GEOMETRY ALLOCATED, so a cell's content
+    // measures no more than its box. `activityWithBadge` already clamps to the business
+    // budget; this is the belt-and-braces that also covers the two cases the budget alone
+    // cannot express - a ZERO-width cell (below `activityDropCols`, where the answer is
+    // "no activity column at all", not "a nine-character word in a zero-column box") and
+    // a wide character straddling the edge.
+    const activity = geometry.activity === 0
+        ? ''
+        : fitCells(activityWithBadge(run, cols, at, geometry.marker), geometry.activity, glyphs.ellipsis);
+    return {
+        marker: statusMarkerCell(childStatus(run), glyphs),
+        label: run.label.padEnd(TEAM_LABEL_CELLS).slice(0, TEAM_LABEL_CELLS),
+        description: run.description.replace(/\s+/g, ' '),
+        activity,
+        clock: teamClockText(run, at),
+    };
+}

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

@@ -1,3 +1,4 @@
+import type { TodoSnapshot } from '../../todo/types.js';
 export interface TodoRailLayoutInput {
     cols: number;
     panelEnabled: boolean;
@@ -22,3 +23,40 @@ export interface TodoRailLayout {
  * never depends on menu occupancy or rail visibility, preventing feedback loops.
  */
 export declare function buildTodoRailLayout(input: TodoRailLayoutInput): TodoRailLayout;
+export interface AcceptanceChipInput {
+    snapshot: TodoSnapshot | null;
+    /** Rows the rail (in-band or full-screen) actually drew; 0 means it drew none. */
+    railRows: number;
+    width: number;
+}
+/**
+ * Does the acceptance count still need the status-bar chip
+ * (todo-acceptance-criteria §6.11)?
+ *
+ * HERE, NEXT TO `buildTodoRailLayout`, because it answers the same question from
+ * the same inputs: "what did the rail actually draw". Putting it in `App` - a
+ * 3,215-line registered oversize file - would give one fact a second owner, which
+ * is precisely what `scrollback/band.ts`'s "one number, one owner" rule exists to
+ * prevent (P1-8 / C-9).
+ *
+ * THE RULE IS ABOUT THE RAIL, NOT ABOUT THE SECTION: while the section is `visible`
+ * or `summary` the rail is already reporting the count, so a chip would repeat it in
+ * the same glance (RV-P2-4). Only two situations leave the count unreported - no rail
+ * at all, and the single `rows === 3 && footer` corner where the panel is up but the
+ * section could not be fitted.
+ */
+export declare function acceptanceChip(input: AcceptanceChipInput): {
+    checked: number;
+    total: number;
+    failed: number;
+} | null;
+/**
+ * Which rung the acceptance section reached in the rail, for `/perf`'s band line
+ * (§6.9.6).
+ *
+ * `n/a` means "this plan has no criteria", which is a different fact from `absent`
+ * ("the plan has criteria and the rail could not show them"). Both come from the
+ * same `buildPlanSections` call the rail rendered with, so the readout cannot
+ * disagree with the screen.
+ */
+export declare function acceptanceRung(input: AcceptanceChipInput): 'visible' | 'summary' | 'absent' | 'n/a';

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

@@ -1,4 +1,6 @@
 import { TODO_LIMITS } from '../../todo/limits.js';
+import { derivePlanPhase } from '../../todo/acceptance.js';
+import { buildPlanSections } from '../../todo/plan-sections.js';
 import { todoRailWidth } from './rail.js';
 /** Allocate columns and rows from the same team/menu projections as the renderers.
  * Invalid geometry becomes zero, excess team/menu rows are clamped. Menu capacity
@@ -25,3 +27,76 @@ export function buildTodoRailLayout(input) {
 function nonNegativeInt(value) {
     return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
 }
+/**
+ * Does the acceptance count still need the status-bar chip
+ * (todo-acceptance-criteria §6.11)?
+ *
+ * HERE, NEXT TO `buildTodoRailLayout`, because it answers the same question from
+ * the same inputs: "what did the rail actually draw". Putting it in `App` - a
+ * 3,215-line registered oversize file - would give one fact a second owner, which
+ * is precisely what `scrollback/band.ts`'s "one number, one owner" rule exists to
+ * prevent (P1-8 / C-9).
+ *
+ * THE RULE IS ABOUT THE RAIL, NOT ABOUT THE SECTION: while the section is `visible`
+ * or `summary` the rail is already reporting the count, so a chip would repeat it in
+ * the same glance (RV-P2-4). Only two situations leave the count unreported - no rail
+ * at all, and the single `rows === 3 && footer` corner where the panel is up but the
+ * section could not be fitted.
+ */
+export function acceptanceChip(input) {
+    const acceptance = input.snapshot?.acceptance;
+    if (!acceptance || acceptance.total === 0)
+        return null;
+    const chip = {
+        checked: acceptance.checkedCount,
+        total: acceptance.total,
+        failed: acceptance.failedCount,
+    };
+    if (input.railRows <= 0)
+        return chip;
+    return acceptanceSectionOf(input) === 'absent' ? chip : null;
+}
+/**
+ * Which rung the acceptance section reached in the rail, for `/perf`'s band line
+ * (§6.9.6).
+ *
+ * `n/a` means "this plan has no criteria", which is a different fact from `absent`
+ * ("the plan has criteria and the rail could not show them"). Both come from the
+ * same `buildPlanSections` call the rail rendered with, so the readout cannot
+ * disagree with the screen.
+ */
+export function acceptanceRung(input) {
+    const acceptance = input.snapshot?.acceptance;
+    if (!acceptance || acceptance.total === 0)
+        return 'n/a';
+    // No rail drawn at all: the section is not on screen, and saying `absent` is the
+    // one honest answer for that.
+    if (input.railRows <= 0)
+        return 'absent';
+    return acceptanceSectionOf(input) ?? 'absent';
+}
+/**
+ * The section's reason for a given rail, or `null` when the plan has no criteria.
+ *
+ * `showGauge` is assumed TRUE. That is the conservative direction for the ROW BUDGET -
+ * it can only make the rail look shorter - and it cannot change the REASON at all: the
+ * compact rung (rows < 6, where the real gauge is always off) ignores `available`
+ * entirely, and the full rung spends the difference on item rows. So this readout can
+ * never disagree with the rail about `visible` / `summary` / `absent`, and the chip
+ * therefore never duplicates a count the rail is already showing (RV-P2-4).
+ */
+function acceptanceSectionOf(input) {
+    const snapshot = input.snapshot;
+    const acceptance = snapshot?.acceptance;
+    if (!snapshot || !acceptance || acceptance.total === 0)
+        return null;
+    const sections = buildPlanSections({
+        rows: input.railRows,
+        width: input.width,
+        phase: derivePlanPhase(snapshot.items, acceptance.items),
+        todoCount: snapshot.items.length,
+        acceptanceCount: acceptance.total,
+        showGauge: true,
+    });
+    return sections.acceptance?.reason ?? null;
+}

package/dist/ui/layout/virtual-window.js

@@ -96,7 +96,17 @@ export function entryRevision(entry) {
                 .map((r) => r.phase[0])
                 .join('')}.${entry.runs.reduce((acc, r) => acc + r.toolCalls, 0)}`;
         case 'todo':
-            return `d${entry.live ? 1 : 0}.${entry.doneCount}.${entry.total}.${entry.items.length}`;
+            // REVISION MUST COVER EVERY FIELD THAT CAN CHANGE THE HEIGHT (§6.10.1). A
+            // criterion going `pending` -> `failed` changes NONE of `items.length`,
+            // `doneCount` or `total`, yet it adds an evidence row; without
+            // `checkedCount` and `failedCount` here the height cache would keep the old
+            // measurement and the cache would be silently wrong - textbook form of "add a
+            // field, forget the revision".
+            return `d${entry.live ? 1 : 0}.${entry.doneCount}.${entry.total}.${entry.items.length}`
+                + `.a${entry.acceptance
+                    ? `${entry.acceptance.items.length}.${entry.acceptance.checkedCount}` +
+                        `.${entry.acceptance.failedCount}`
+                    : '-'}`;
         /**
          * The retry card is ONE ROW IN EVERY PHASE, so its revision carries the phase
          * and the counter but deliberately NOT the countdown: `resumeAt` changes the
@@ -325,8 +335,18 @@ export function estimateEntryRows(entry, cols, density, expanded, thinkingVisibl
             if (isLiveTeamCard(entry))
                 return 0;
             return separation + 1 + entry.runs.length + (expanded ? entry.runs.length * 3 + 1 : 1);
-        case 'todo':
-            return separation + 1 + entry.items.length;
+        case 'todo': {
+            // THE ACCEPTANCE BLOCK'S ROWS, EXACTLY (§6.10.1): one title row plus one row
+            // per criterion plus one row per FAILED criterion's evidence. Exact because
+            // every one of those lines is `wrap="truncate"`; the moment one of them wraps,
+            // this stops being an equality and becomes an upper bound - and the failure
+            // mode is scroll drift, which nothing reports.
+            const acceptance = entry.acceptance;
+            const acceptanceRows = acceptance && acceptance.total > 0
+                ? 1 + acceptance.items.length + acceptance.failedCount
+                : 0;
+            return separation + 1 + entry.items.length + acceptanceRows;
+        }
         // ONE ROW, ALWAYS. The card is `wrap="truncate"` in every phase, so this is an
         // exact height rather than an upper bound.
         case 'retry':

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

@@ -0,0 +1,57 @@
+/**
+ * AgentsBoardOverlay — the read-only detail board behind `Ctrl+B` / `/agents`
+ * (tui-subagent-panel §4.4 / §6.3).
+ *
+ * READ-ONLY IS THE SAFETY BOUNDARY (§2.2). Nothing here nudges, kills or re-dispatches
+ * a child, and no new `TeamEvent` member was introduced to feed it: a board that can
+ * only read can never kill a healthy child, which is the whole reason this is a
+ * second surface rather than a control panel.
+ *
+ * ONE SCREEN, CONTROLLED MODE. `OverlayFrame`'s controlled form already owns paging,
+ * the position indicator and the narrow-terminal degradation, and `helpRows` /
+ * `projectQueueRows` are the precedent. A second pane would mean a second horizontal
+ * budget inside Ink for a benefit the board's 2-up field rows already deliver.
+ *
+ * IT DOES NOT GO BLANK WHEN THE DISPATCH ENDS (D-9). `state.team` becomes `null` the
+ * frame the dispatch settles, and a reader would lose the child they were reading
+ * about at the exact moment they wanted the post-mortem. The last live snapshot is
+ * therefore FROZEN (a copy, held in a ref) and keeps rendering with a
+ * `dispatch ended` row; a board opened AFTER the dispatch has ended builds from the
+ * transcript's settled `team` entry instead (`resolveBoardSource`), which is where the
+ * `result` section earns its place - the error is the one fact that is never stripped.
+ *
+ * NO `ink-spinner` HERE (D-13): `spinner-census.test.ts` pins the exact list of files
+ * that mount an animated spinner, and this is a reading surface, not an animation.
+ * The panel is where motion belongs.
+ *
+ * AND NO MOTION PROP (v2 implementation note, appended to the spec's
+ * "implementation findings"). Because nothing here animates, a motion flag would be a
+ * prop with no consumer - and worse, the same census counts how many times `App.tsx`
+ * hands the RAW motion flag to a child and asserts the count is EXACTLY ONE, so passing
+ * it from the board's branch would break a shipped guard rail for no gain.
+ *
+ * ASCII ONLY: every symbol comes through `glyphs`.
+ */
+import React from 'react';
+import type { Entry } from '../../agent/reducer.js';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { TeamSnapshot } from '../../team/types.js';
+export interface AgentsBoardOverlayProps {
+    /** The live snapshot; `null` once the dispatch has settled. */
+    team: TeamSnapshot | null;
+    /** The transcript, for the settled fallback (D-9 path 4). */
+    entries: readonly Entry[];
+    /** Overlay content width (`App`'s `viewCols`). */
+    cols: number;
+    maxRows: number;
+    scrollOffset: number;
+    onScrollClamp: (offset: number) => void;
+    isActive: boolean;
+    native: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+    /** Injectable clock, so the board's tests do not depend on wall time. */
+    now?: number;
+}
+export declare function AgentsBoardOverlay({ team, entries, cols, maxRows, scrollOffset, onScrollClamp, isActive, native, theme, caps, now, }: AgentsBoardOverlayProps): React.ReactElement;

package/dist/ui/overlays/AgentsBoardOverlay.js

@@ -0,0 +1,183 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * AgentsBoardOverlay — the read-only detail board behind `Ctrl+B` / `/agents`
+ * (tui-subagent-panel §4.4 / §6.3).
+ *
+ * READ-ONLY IS THE SAFETY BOUNDARY (§2.2). Nothing here nudges, kills or re-dispatches
+ * a child, and no new `TeamEvent` member was introduced to feed it: a board that can
+ * only read can never kill a healthy child, which is the whole reason this is a
+ * second surface rather than a control panel.
+ *
+ * ONE SCREEN, CONTROLLED MODE. `OverlayFrame`'s controlled form already owns paging,
+ * the position indicator and the narrow-terminal degradation, and `helpRows` /
+ * `projectQueueRows` are the precedent. A second pane would mean a second horizontal
+ * budget inside Ink for a benefit the board's 2-up field rows already deliver.
+ *
+ * IT DOES NOT GO BLANK WHEN THE DISPATCH ENDS (D-9). `state.team` becomes `null` the
+ * frame the dispatch settles, and a reader would lose the child they were reading
+ * about at the exact moment they wanted the post-mortem. The last live snapshot is
+ * therefore FROZEN (a copy, held in a ref) and keeps rendering with a
+ * `dispatch ended` row; a board opened AFTER the dispatch has ended builds from the
+ * transcript's settled `team` entry instead (`resolveBoardSource`), which is where the
+ * `result` section earns its place - the error is the one fact that is never stripped.
+ *
+ * NO `ink-spinner` HERE (D-13): `spinner-census.test.ts` pins the exact list of files
+ * that mount an animated spinner, and this is a reading surface, not an animation.
+ * The panel is where motion belongs.
+ *
+ * AND NO MOTION PROP (v2 implementation note, appended to the spec's
+ * "implementation findings"). Because nothing here animates, a motion flag would be a
+ * prop with no consumer - and worse, the same census counts how many times `App.tsx`
+ * hands the RAW motion flag to a child and asserts the count is EXACTLY ONE, so passing
+ * it from the board's branch would break a shipped guard rail for no gain.
+ *
+ * ASCII ONLY: every symbol comes through `glyphs`.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { buildAgentBoardRows, resolveBoardSource, resolveSelection, } from '../layout/agents-board.js';
+/** `OverlayFrame`'s own breakpoint, mirrored so the chrome estimate cannot drift. */
+const FRAME_BORDERLESS_COLS = 48;
+/**
+ * Close a frozen live snapshot: the dispatch it described has ended.
+ *
+ * `durationMs` is derived from the LAST frame the snapshot was live, so the board's
+ * summary shows the dispatch's real total instead of a clock that keeps running against
+ * a dispatch nobody can see any more. When the snapshot never had a `startedAt` there is
+ * nothing to derive and the field stays absent - the LIVE-ONLY rule turns that into an
+ * empty clock cell rather than an invented number (§4.4.2).
+ */
+function settleFrozen(frozen) {
+    const { source, at } = frozen;
+    const total = source.startedAt === undefined ? undefined : Math.max(0, at - source.startedAt);
+    return {
+        ...source,
+        active: false,
+        ...(total !== undefined ? { durationMs: total } : {}),
+    };
+}
+/** Palette slot -> theme colour. One place, so a tone can never be spelled twice. */
+function toneColor(tone, theme) {
+    switch (tone) {
+        case 'accent':
+            return theme.accent;
+        case 'primary':
+            return theme.primary;
+        case 'muted':
+            return theme.muted;
+        case 'warn':
+            return theme.noticeWarn;
+        case 'error':
+            return theme.noticeError;
+        case 'done':
+            return theme.toolDone;
+        case 'hint':
+            return theme.hintFg;
+    }
+}
+export function AgentsBoardOverlay({ team, entries, cols, maxRows, scrollOffset, onScrollClamp, isActive, native, theme, caps, now, }) {
+    const glyphs = pickGlyphs(caps);
+    const at = now ?? Date.now();
+    const [selectedLabel, setSelectedLabel] = useState(null);
+    /**
+     * THE FROZEN SNAPSHOT (D-9), plus the clock reading it was frozen at.
+     *
+     * A ref rather than state on purpose: it is written from an effect that must not
+     * trigger a render of its own, and reading it during the render that FIRST sees
+     * `team === null` is what keeps the board from blinking empty for one frame. The
+     * timestamp is kept WITH the snapshot because a frozen live source still says
+     * `active: true` - it was live when it was copied - and a board that kept believing
+     * that would never show its `dispatch ended` row nor stop its clock.
+     */
+    const frozen = useRef(null);
+    const live = team === null ? null : resolveBoardSource({ team, entries });
+    useEffect(() => {
+        if (live !== null)
+            frozen.current = { source: live, at };
+    }, [live, at]);
+    // PRIORITY: live > frozen > the most recent settled entry (§4.4.5). The frozen copy
+    // only ever takes over on the frame the live snapshot disappears, and a NEW dispatch
+    // overwrites it on its own first frame, so the two paths cannot both be active.
+    //
+    // A FROZEN SOURCE IS SETTLED, and it is closed here rather than at the moment of
+    // copying: `active: false` is what draws `dispatch ended` (task AC-17), and taking
+    // `durationMs` from the freeze instant stops the clock at the dispatch's real end
+    // instead of letting it count up forever from a snapshot that no longer exists.
+    const frozenSource = frozen.current === null ? null : settleFrozen(frozen.current);
+    const source = live ?? frozenSource ?? resolveBoardSource({ team: null, entries });
+    const selected = source === null ? null : resolveSelection(source.runs, selectedLabel);
+    /**
+     * UP/DOWN MOVES THE CHILD CURSOR, and a change of child RESETS the scroll.
+     *
+     * `agents` deliberately does NOT join `App`'s row-scroll set (`help | plan | queue`):
+     * the same trade `settings` makes with its field cursor, where Up/Down is worth more
+     * as navigation than as a six-row scroll. `PgUp` / `PgDn` / the wheel still page the
+     * board through `App`'s `controlled` set, so no reading gesture is lost.
+     */
+    const move = useCallback((delta) => {
+        const runs = source?.runs ?? [];
+        if (runs.length === 0)
+            return;
+        const current = resolveSelection(runs, selectedLabel);
+        const index = current === null ? -1 : runs.findIndex((run) => run.label === current.label);
+        const next = runs[Math.min(runs.length - 1, Math.max(0, index + delta))];
+        if (next === undefined || next.label === current?.label)
+            return;
+        setSelectedLabel(next.label);
+        // The documented semantic of this port is "the offset should now be 0" (§6.3).
+        onScrollClamp(0);
+    }, [onScrollClamp, selectedLabel, source]);
+    useInput((_input, key) => {
+        if (!isActive)
+            return;
+        if (key.upArrow)
+            move(-1);
+        else if (key.downArrow)
+            move(1);
+    }, { isActive });
+    // THE FRAME'S CHROME IS NOT FREE (v2 implementation note). `cols` arrives as the
+    // overlay's FRAME width (`App`'s `viewCols`), and `OverlayFrame` spends 4 of those
+    // columns on its border plus `paddingX={1}` (2 in the narrow rail form, which drops
+    // the right border and the right padding). A board laid out against the frame width
+    // therefore has its LAST four columns eaten by Ink's truncation - which lands exactly
+    // on the right-anchored figures this board exists to align. `helpRows` gets away with
+    // it because its rows are prose; these are a table.
+    const contentCols = Math.max(1, cols - (cols >= FRAME_BORDERLESS_COLS ? 4 : 2));
+    const rows = source === null
+        ? [{
+                key: 'empty',
+                kind: 'hint',
+                text: 'No subagent dispatch yet.',
+                tone: 'muted',
+            }]
+        : buildAgentBoardRows({
+            source,
+            cols: contentCols,
+            now: at,
+            selectedLabel: selected?.label ?? null,
+            glyphs,
+            native,
+        });
+    // The `dispatch ended` banner is a ROW rather than a title swap: the title is the
+    // frame's own ("Agents"), and replacing it would hide which screen the reader is on.
+    const endedRow = source !== null && !source.active
+        ? [{
+                key: 'ended',
+                kind: 'hint',
+                text: `dispatch ended ${glyphs.midDot} Esc to close`,
+                tone: 'warn',
+            }]
+        : [];
+    const elements = [...endedRow, ...rows].map((row) => (_jsx(Text, { wrap: "truncate", color: toneColor(row.tone, theme), ...(row.kind === 'section' ? { bold: true } : {}), children: row.text }, row.key)));
+    // THE HINT SHRINKS WITH THE FRAME. `OverlayFrame` prints the hint as one unwrapped
+    // row, so a 41-column hint inside a 30-column frame makes the FRAME 41 wide - the
+    // board would overflow the terminal and take the overlay's border with it.
+    const hint = contentCols >= 60
+        ? `Esc close ${glyphs.midDot} Up/Down child ${glyphs.midDot} PgUp/PgDn scroll`
+        : contentCols >= 30
+            ? `Esc close ${glyphs.midDot} Up/Down child`
+            : 'Esc close';
+    return (_jsx(OverlayFrame, { title: "Agents", hint: hint, maxRows: maxRows, cols: cols, rows: elements, scrollOffset: scrollOffset, onScrollClamp: onScrollClamp, theme: theme, caps: caps }));
+}