@aragon-agent/cli 0.6.31 → 0.6.32

package/dist/ui/ScrollbackShell.d.ts

@@ -8,21 +8,47 @@
  * screenful per frame). Everything settled has already been printed into the
  * terminal's own scrollback above it.
  *
- * Top to bottom: [overlay | streaming preview] -> composer -> status (-> details).
+ * Top to bottom: [overlay | panel band][composer][status][details].
+ *
+ * THE PANEL BAND IS THE PART NATIVE MODE WAS MISSING
+ * (release-gate-and-native-panels §6.1). A fixed frame can put a rail beside the
+ * transcript; without one the rail and the roster simply had nowhere to go, so the
+ * default mode showed neither. The band is a row pool inside the live region:
+ *
+ *   +---------------------------------------------+-----------------+
+ *   | team roster      (height = band.teamRows)    | TODO rail       |
+ *   +---------------------------------------------+ (height =       |
+ *   | unfinished tail  (height = band.previewRows) |  band.railRows) |
+ *   +---------------------------------------------+-----------------+
+ *
+ * Every box in it has an explicit `height` and `width` plus `overflow="hidden"`, and
+ * that is a correctness requirement rather than tidiness: a box that grows with its
+ * content would make the region taller than `budget.liveRows`, and a frame as tall as
+ * the terminal makes Ink erase the user's scrollback (I-4).
+ *
+ * `liveTailLines` STAYS. It is the plain-text fallback for the frames where the real
+ * tail is not mounted (and the floor of the measurement path); `tail` wins when both
+ * are given, so the two can never be drawn on top of each other.
  */
 import React from 'react';
 import type { Theme } from './theme.js';
 import type { ScrollbackBudget } from './scrollback/budget.js';
 export interface ScrollbackShellProps {
     budget: ScrollbackBudget;
-    /** Shown instead of the preview when an overlay is open. */
+    /** Shown instead of the band when an overlay is open. */
     overlay: React.ReactNode | null;
-    /** Plain preview rows, bottom-aligned just above the composer. */
+    /** Plain preview rows: the fallback when `tail` is absent (and what `/perf` counts). */
     liveTailLines: readonly string[];
+    /** Real components for the unfinished tail (`LiveTail`). */
+    tail?: React.ReactNode;
+    /** The subagent roster, drawn at the top of the band's left column. */
+    team?: React.ReactNode;
+    /** The TODO rail, drawn as the band's right-hand column. */
+    rail?: React.ReactNode;
     composer: React.ReactNode;
     status: React.ReactNode;
     details?: React.ReactNode;
     placeholder: React.ReactNode;
     theme: Theme;
 }
-export declare function ScrollbackShell({ budget, overlay, liveTailLines, composer, status, details, placeholder, theme, }: ScrollbackShellProps): React.ReactElement;
+export declare function ScrollbackShell({ budget, overlay, liveTailLines, tail, team, rail, composer, status, details, placeholder, theme, }: ScrollbackShellProps): React.ReactElement;

package/dist/ui/ScrollbackShell.js

@@ -1,10 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
-export function ScrollbackShell({ budget, overlay, liveTailLines, composer, status, details, placeholder, theme, }) {
+export function ScrollbackShell({ budget, overlay, liveTailLines, tail, team, rail, composer, status, details, placeholder, theme, }) {
     const width = budget.contentCols;
     if (budget.inactive) {
         return (_jsx(Box, { flexDirection: "column", height: budget.liveRows, width: width, overflow: "hidden", flexShrink: 0, children: budget.liveRows > 0 ? placeholder : null }));
     }
-    const tail = liveTailLines.slice(-budget.liveTailRows);
-    return (_jsxs(Box, { flexDirection: "column", height: budget.liveRows, width: width, overflow: "hidden", flexShrink: 0, children: [budget.overlayRows > 0 && (_jsx(Box, { flexDirection: "column", height: budget.overlayRows, flexShrink: 0, overflow: "hidden", children: overlay })), budget.liveTailRows > 0 && (_jsx(Box, { flexDirection: "column", height: budget.liveTailRows, flexShrink: 0, justifyContent: "flex-end", overflow: "hidden", children: tail.map((line, index) => (_jsx(Text, { wrap: "truncate", color: theme.muted, children: line }, index))) })), _jsx(Box, { flexDirection: "column", height: budget.composerSlotRows, justifyContent: "flex-end", flexShrink: 0, overflow: "hidden", children: composer }), _jsx(Box, { height: budget.statusRows > 0 ? 1 : 0, flexShrink: 0, overflow: "hidden", children: status }), budget.statusRows === 2 && (_jsx(Box, { height: 1, flexShrink: 0, overflow: "hidden", children: details }))] }));
+    const band = budget.band;
+    const tailLines = liveTailLines.slice(-budget.liveTailRows);
+    // The overlay and the band are alternatives, not siblings: the band reports
+    // `bandRows = remaining` for an overlay frame, so drawing both would double the
+    // region's height and take the frame to the terminal height (the `ESC[3J` case).
+    const top = band.reason === 'overlay' ? (_jsx(Box, { flexDirection: "column", height: budget.overlayRows, flexShrink: 0, overflow: "hidden", children: overlay })) : band.bandRows > 0 ? (_jsxs(Box, { flexDirection: "row", height: band.bandRows, flexShrink: 0, overflow: "hidden", children: [_jsxs(Box, { flexDirection: "column", width: budget.previewCols, flexShrink: 0, overflow: "hidden", children: [band.teamRows > 0 && (_jsx(Box, { height: band.teamRows, flexShrink: 0, overflow: "hidden", children: team })), band.previewRows > 0 && (_jsx(Box, { flexDirection: "column", height: band.previewRows, flexShrink: 0, justifyContent: "flex-end", overflow: "hidden", children: tail ?? tailLines.map((line, index) => (_jsx(Text, { wrap: "truncate", color: theme.muted, children: line }, index))) }))] }), band.railRows > 0 && (_jsx(Box, { height: band.railRows, width: band.railCols, flexShrink: 0, overflow: "hidden", children: rail }))] })) : null;
+    return (_jsxs(Box, { flexDirection: "column", height: budget.liveRows, width: width, overflow: "hidden", flexShrink: 0, children: [top, _jsx(Box, { flexDirection: "column", height: budget.composerSlotRows, justifyContent: "flex-end", flexShrink: 0, overflow: "hidden", children: composer }), _jsx(Box, { height: budget.statusRows > 0 ? 1 : 0, flexShrink: 0, overflow: "hidden", children: status }), budget.statusRows === 2 && (_jsx(Box, { height: 1, flexShrink: 0, overflow: "hidden", children: details }))] }));
 }

package/dist/ui/StatusBar.d.ts

@@ -19,6 +19,11 @@ export interface StatusBarProps {
         name: string;
         toolCallId: string;
     } | null;
+    /** A bounded wait in flight; replaces the `Running job_wait` label (§4.9). */
+    wait?: {
+        jobId: string;
+        upToSeconds: number;
+    };
     runOutcome?: "none" | "ended" | "interrupted" | "failed";
     reducedMotion?: boolean;
     waitingForConfirmation?: boolean;

package/dist/ui/StatusBar.js

@@ -27,6 +27,7 @@ export function StatusBar(props) {
         context: props.context, usageTotal: props.usageTotal,
         thinkingLevel: props.thinkingLevel, elapsedMs: props.elapsedMs, tokPerSec: props.tokPerSec,
         activeTool: props.activeTool, runOutcome: props.runOutcome, spinner: glyph,
+        ...(props.wait ? { wait: props.wait } : {}),
         speedKnown: props.speedKnown, feedback: props.feedback, escapeAction: props.escapeAction,
         interruptPhase: props.interruptPhase,
         waitingForConfirmation: props.waitingForConfirmation, stopping: props.stopping,

package/dist/ui/Transcript.d.ts

@@ -26,6 +26,20 @@ interface TranscriptProps {
     theme: Theme;
     caps: TermCapabilities;
 }
+/**
+ * The value `EntryView` should receive for `nowSec` on THIS entry.
+ *
+ * `undefined` for everything that is not a running tool, which is what keeps
+ * every other card's memo boundary intact — `undefined === undefined` in the
+ * comparator, on every frame, forever.
+ *
+ * EXPORTED for `ui/scrollback/LiveTail.tsx` (release-gate-and-native-panels §6.5), and
+ * that is the whole of this feature's change to this file: the live region mounts the
+ * same `EntryView` the transcript does, so it must feed it the same per-entry clock.
+ * A copy of this rule in the band would be a second answer to "does this card tick?"
+ * and the two would disagree the first time a consumer is added.
+ */
+export declare function nowSecFor(entry: Entry, nowSec: number | undefined): number | undefined;
 export interface EntryViewProps {
     entry: Entry;
     /** Previous entry in the list; `undefined` for the first item. */

package/dist/ui/Transcript.js

@@ -27,8 +27,14 @@ import { advanceTailRows } from './layout/follow-state.js';
  * `undefined` for everything that is not a running tool, which is what keeps
  * every other card's memo boundary intact — `undefined === undefined` in the
  * comparator, on every frame, forever.
+ *
+ * EXPORTED for `ui/scrollback/LiveTail.tsx` (release-gate-and-native-panels §6.5), and
+ * that is the whole of this feature's change to this file: the live region mounts the
+ * same `EntryView` the transcript does, so it must feed it the same per-entry clock.
+ * A copy of this rule in the band would be a second answer to "does this card tick?"
+ * and the two would disagree the first time a consumer is added.
  */
-function nowSecFor(entry, nowSec) {
+export function nowSecFor(entry, nowSec) {
     if (entry.kind === 'tool' && entry.status === 'running')
         return nowSec;
     // THE LIVE COMPACTION CARD IS THE SECOND CONSUMER (hardening W5). It is at most
@@ -36,6 +42,12 @@ function nowSecFor(entry, nowSec) {
     // function protects is unchanged for every other card, forever.
     if (entry.kind === 'compaction' && entry.live)
         return nowSec;
+    // THE THIRD CONSUMER IS A LIVE JOB (long-task-jobs D-8), and it is the reason
+    // this stays a single 1 Hz clock: a task's elapsed time and its `no output`
+    // badge both have to move, and a per-card `setInterval` would be one timer per
+    // job. `terminal` entries are excluded so a settled record never re-renders.
+    if (entry.kind === 'service' && !entry.terminal)
+        return nowSec;
     return undefined;
 }
 function noticeColor(level, theme) {
@@ -113,7 +125,7 @@ function EntryViewImpl({ entry, prev, expanded, thinkingVisible, reducedMotion,
                     ? Math.max(0, nowSec * 1000 - entry.startedAt)
                     : undefined, live: entry.live, expanded: expanded, reducedMotion: reducedMotion, theme: theme, caps: caps }));
         case 'service':
-            return frame(serviceGlyph(entry, glyphs), serviceCardColor(entry, theme), _jsx(ServiceCard, { serviceId: entry.serviceId, command: entry.command, status: entry.status, url: entry.url, port: entry.port, exitCode: entry.exitCode, startedAt: entry.startedAt, readyAt: entry.readyAt, endedAt: entry.endedAt, rows: entry.rows, terminal: entry.terminal, killIncomplete: entry.killIncomplete, expanded: expanded, reducedMotion: reducedMotion, theme: theme, caps: caps }));
+            return frame(serviceGlyph(entry, glyphs), serviceCardColor(entry, theme), _jsx(ServiceCard, { serviceId: entry.serviceId, jobKind: entry.jobKind, command: entry.command, status: entry.status, url: entry.url, port: entry.port, exitCode: entry.exitCode, startedAt: entry.startedAt, readyAt: entry.readyAt, endedAt: entry.endedAt, rows: entry.rows, terminal: entry.terminal, killIncomplete: entry.killIncomplete, progress: entry.progress, stalled: entry.stalled, lastOutputAt: entry.lastOutputAt, nowSec: nowSec, expanded: expanded, reducedMotion: reducedMotion, theme: theme, caps: caps }));
         case 'notice':
             return frame(noticeSymbol(entry.level, theme), noticeColor(entry.level, theme), _jsx(Text, { color: noticeColor(entry.level, theme), children: entry.text }));
         default:

package/dist/ui/entries/ServiceCard.d.ts

@@ -23,9 +23,11 @@ import React from 'react';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
 import { pickGlyphs } from '../glyphs.js';
-import type { ServiceStatus } from '../../proc/types.js';
+import type { JobKind, ServiceStatus } from '../../proc/types.js';
 export interface ServiceCardProps {
     serviceId: string;
+    /** `service` or `task`: NOUN ONLY, never a rename of the entry kind (I-2). */
+    jobKind?: JobKind;
     command: string;
     status: ServiceStatus;
     url?: string;
@@ -39,6 +41,20 @@ export interface ServiceCardProps {
     terminal?: boolean;
     killIncomplete?: boolean;
     expanded?: boolean;
+    /** The extracted progress line, one row, already clipped by the supervisor. */
+    progress?: string;
+    /** Silence past `jobs.stallSeconds` - a muted badge, never an action. */
+    stalled?: boolean;
+    /** When output last arrived; with `nowSec` it renders `no output 6m02s`. */
+    lastOutputAt?: number;
+    /**
+     * The transcript's 1 Hz clock (D-8).
+     *
+     * ONE CLOCK FOR EVERYTHING. A per-card `setInterval` would be one timer per job,
+     * and the transcript's comparator already includes `nowSec`, so the live elapsed
+     * figure and the `no output` figure update for free.
+     */
+    nowSec?: number;
     /** Accepted for comparator consistency; this card never animates (D-14). */
     reducedMotion?: boolean;
     theme: Theme;

package/dist/ui/entries/ServiceCard.js

@@ -81,8 +81,19 @@ function statusClause(props, dot) {
         const took = readyAt === undefined ? '' : `${dot}${formatDuration(readyAt - startedAt)}`;
         return `ready${took}`;
     }
-    if (status === 'running')
-        return 'running';
+    // A LIVE JOB SHOWS ITS ELAPSED TIME (D-8), because a task's whole story is
+    // "how long has this been going". The number comes from the transcript's 1 Hz
+    // `nowSec`; without it the card falls back to the spawn time and reads `0ms`,
+    // which is honest about never having been ticked rather than wrong about it.
+    if (status === 'running') {
+        // NO CLOCK, NO FIGURE. Falling back to `startedAt` would print `0ms` on every
+        // settled frame, which reads as "it just started" - a wrong number rather than
+        // an absent one.
+        if (props.nowSec === undefined)
+            return 'running';
+        const elapsed = Math.max(0, props.nowSec * 1000 - startedAt);
+        return `running${dot}${formatDuration(elapsed)}`;
+    }
     if (status === 'starting')
         return 'starting';
     const lived = endedAt === undefined ? '' : `${dot}${formatDuration(endedAt - startedAt)}`;
@@ -92,20 +103,44 @@ function statusClause(props, dot) {
         return `failed${lived}`;
     return `exited${exitCode === null ? '' : ` code ${exitCode}`}${lived}`;
 }
+/**
+ * The progress row, or `undefined` when there is nothing to draw.
+ *
+ * STALLED OUTRANKS PROGRESS: "no output for 6m" is the more urgent of the two
+ * facts, and drawing both would cost a second row the height estimator does not
+ * know about. The `no output` figure needs `nowSec`; without it the badge is
+ * omitted rather than printed with a wrong number.
+ */
+function progressRow(props) {
+    if (props.stalled === true) {
+        if (props.nowSec === undefined || props.lastOutputAt === undefined) {
+            return { text: 'no output', stalled: true };
+        }
+        const quiet = Math.max(0, props.nowSec * 1000 - props.lastOutputAt);
+        return { text: `no output ${formatDuration(quiet)}`, stalled: true };
+    }
+    if (props.progress)
+        return { text: props.progress, stalled: false };
+    return undefined;
+}
 function ServiceCardImpl(props) {
     const { serviceId, command, url, rows, expanded, terminal, theme, caps } = props;
     const glyphs = pickGlyphs(caps);
     const color = serviceCardColor(props, theme);
     const dot = `  ${glyphs.midDot}  `;
     const clause = statusClause(props, dot);
+    // THE NOUN, NOT THE KIND: `task t1` and `service s1` are the same component
+    // drawing two kinds of job, and every id keeps its existing prefix (I-2).
+    const noun = props.jobKind === 'task' ? 'task' : 'service';
     // THE TERMINAL RECORD IS ONE ROW, ALWAYS. It is a SECOND event at a SECOND
     // time — the only thing `<Static>` permits once the live card is printed — so
     // it names what happened and nothing else (D-11).
     if (terminal) {
-        return (_jsx(Box, { flexDirection: "row", children: _jsxs(Text, { color: color, wrap: "truncate", children: ["service ", serviceId, " ", clause, props.killIncomplete ? ' (may have left a detached child)' : ''] }) }));
+        return (_jsx(Box, { flexDirection: "row", children: _jsxs(Text, { color: color, wrap: "truncate", children: [noun, " ", serviceId, " ", clause, props.killIncomplete ? ' (may have left a detached child)' : ''] }) }));
     }
     const shown = rows.slice(-(expanded ? EXPANDED_TAIL_ROWS : COLLAPSED_TAIL_ROWS));
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: theme.accent, bold: true, children: ["service ", serviceId] }), _jsxs(Text, { color: theme.muted, wrap: "truncate", children: ['  ', command] }), _jsxs(Text, { color: color, wrap: "truncate", children: [dot, clause] })] }), url !== undefined && (_jsxs(Box, { flexDirection: "row", flexShrink: 0, paddingLeft: 1, children: [_jsx(Text, { color: theme.primary, children: url }), _jsxs(Text, { color: theme.muted, children: [dot, "ctrl+c stop", dot, "ctrl+o log"] })] })), shown.length > 0 && (_jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, ...railBorderProps(glyphs.railVertical, theme.border), children: shown.map((line, index) => (_jsx(Text, { color: theme.muted, wrap: "truncate", children: line }, index))) }))] }));
+    const progress = progressRow(props);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: theme.accent, bold: true, children: [noun, " ", serviceId] }), _jsxs(Text, { color: theme.muted, wrap: "truncate", children: ['  ', command] }), _jsxs(Text, { color: color, wrap: "truncate", children: [dot, clause] })] }), progress !== undefined && (_jsx(Box, { flexDirection: "row", flexShrink: 0, paddingLeft: 1, children: _jsx(Text, { color: progress.stalled ? theme.noticeWarn : theme.muted, wrap: "truncate", children: progress.stalled ? progress.text : `[progress] ${progress.text}` }) })), url !== undefined && (_jsxs(Box, { flexDirection: "row", flexShrink: 0, paddingLeft: 1, children: [_jsx(Text, { color: theme.primary, children: url }), _jsxs(Text, { color: theme.muted, children: [dot, "ctrl+c stop", dot, "ctrl+o log"] })] })), shown.length > 0 && (_jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, ...railBorderProps(glyphs.railVertical, theme.border), children: shown.map((line, index) => (_jsx(Text, { color: theme.muted, wrap: "truncate", children: line }, index))) }))] }));
 }
 /**
  * `React.memo` with the DEFAULT comparator (tui-render-performance L2 / R3).

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

@@ -15,6 +15,18 @@ export interface StatusLayoutInput {
         name: string;
         toolCallId: string;
     } | null;
+    /**
+     * A bounded wait in flight (long-task-jobs §4.9).
+     *
+     * PRESENT ONLY WHILE `job_wait` IS THE ACTIVE TOOL, and it REPLACES the
+     * `Running job_wait` label rather than joining it: "Waiting on t3 (up to 30s)"
+     * is the state the user asked about (what, and how long at most), while the
+     * tool name is an implementation detail of how the runtime is waiting.
+     */
+    wait?: {
+        jobId: string;
+        upToSeconds: number;
+    };
     runOutcome?: 'none' | 'ended' | 'interrupted' | 'failed';
     spinner?: string;
     waitingForConfirmation?: boolean;
@@ -77,7 +89,7 @@ export interface StatusLinePlan {
 export declare function cleanStatusText(text: string): string;
 export declare function statusField(id: string, text: string, tone?: StatusField['tone']): StatusField;
 export declare function statusLinePlan(fields: readonly StatusField[], separator?: string): StatusLinePlan;
-export declare function phaseLabels(input: Pick<StatusLayoutInput, 'phase' | 'activeTool' | 'runOutcome' | 'waitingForConfirmation' | 'stopping' | 'compacting' | 'retryActive'>): readonly [string, string];
+export declare function phaseLabels(input: Pick<StatusLayoutInput, 'phase' | 'activeTool' | 'runOutcome' | 'waitingForConfirmation' | 'stopping' | 'compacting' | 'retryActive' | 'wait'>): readonly [string, string];
 export declare function validContext(context: ContextUsageSnapshot): boolean;
 export declare function shortDuration(ms: number): string;
 /** Every field survives each width rung; only the redraw carrier is outside this plan. */

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

@@ -25,6 +25,16 @@ export function phaseLabels(input) {
         return copy.compacting;
     if (input.retryActive)
         return copy.retrying;
+    // A WAIT OUTRANKS THE TOOL NAME (long-task-jobs AC-28): `Running job_wait`
+    // answers "which tool", `Waiting on t3 (up to 30s)` answers "what am I waiting
+    // for and how long may it take", which is the question a user staring at a
+    // quiet terminal actually has. Both forms carry it - the short rung is
+    // truncated by width, not reworded.
+    if (input.wait) {
+        const label = `Waiting on ${cleanStatusText(input.wait.jobId)} ` +
+            `(up to ${Math.max(0, Math.round(input.wait.upToSeconds))}s)`;
+        return [label, label];
+    }
     if (input.activeTool)
         return [copy.tool[0], copy.tool[1] + ' ' + cleanStatusText(input.activeTool.name)];
     if (input.phase === 'idle' && input.runOutcome && input.runOutcome !== 'none')

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

@@ -218,6 +218,13 @@ const TOOL_LIVE_TAIL_ROWS = 8;
 const SERVICE_COLLAPSED_TAIL_ROWS = 2;
 /** Tail rows an EXPANDED `ServiceCard` draws; the snapshot cap (8). */
 const SERVICE_EXPANDED_TAIL_ROWS = 8;
+/**
+ * The progress row the live `ServiceCard` draws when `progress` or `stalled` is
+ * set (long-task-jobs §4.9), duplicated as the number `1` for the same reason as
+ * the two constants above: `virtual-window.ts` counts lines, `ServiceCard.tsx`
+ * draws them, and the pairing is kept by a test (AC-27) rather than by an import.
+ */
+const SERVICE_PROGRESS_ROWS = 1;
 /**
  * Pure UPPER-BOUND estimate of an entry's height, used until a real measurement
  * exists.
@@ -358,7 +365,13 @@ export function estimateEntryRows(entry, cols, density, expanded, thinkingVisibl
             const tail = expanded
                 ? Math.min(entry.rows.length, SERVICE_EXPANDED_TAIL_ROWS)
                 : Math.min(entry.rows.length, SERVICE_COLLAPSED_TAIL_ROWS);
-            return separation + 1 + url + tail;
+            // THE PROGRESS ROW IS ONE MORE LINE (long-task-jobs AC-27), and it is only
+            // ever one because `ServiceCard` draws it with `wrap="truncate"` and the
+            // supervisor clips it to `PROC_LIMITS.waitProgressChars`. A `stalled` badge
+            // REPLACES it rather than adding to it - the two can never both be drawn,
+            // so this stays a single term.
+            const progress = entry.progress || entry.stalled ? SERVICE_PROGRESS_ROWS : 0;
+            return separation + 1 + progress + url + tail;
         }
         default:
             return separation + 1;

package/dist/ui/run-status-row.d.ts

@@ -17,6 +17,18 @@ export interface RunActivity {
     runningTool?: string;
     /** A context compaction is in flight; outranks the tool name and the phrase. */
     compacting?: boolean;
+    /**
+     * A BOUNDED WAIT IS IN FLIGHT (long-task-jobs §4.9).
+     *
+     * `Running job_wait` is a TOOL NAME; `Waiting on t3 (up to 30s)` is a STATE, and
+     * the state is what answers the user's two questions - what is it waiting for,
+     * and how long may that take. No countdown: a ticking number would need its own
+     * re-render, and the sentence is already complete.
+     */
+    wait?: {
+        jobId: string;
+        upToSeconds: number;
+    };
 }
 export interface RunRowPlanInput {
     /** Width of the row's container (the composer's content columns). */

package/dist/ui/screen.d.ts

@@ -74,6 +74,15 @@ export declare function enterAltScreen(stdout: NodeJS.WriteStream | undefined, o
 export interface NativeScreenOptions {
     /** Same discipline as `AltScreenOptions.bracketedPaste`: a filter that consumes it exists. */
     readonly bracketedPaste?: boolean;
+    /**
+     * Line feeds to write BEFORE anything else, so the first batch starts from the
+     * bottom row of the screen (tui-bottom-anchored-live-region D4 rung 2).
+     *
+     * `cli.tsx` passes `rows - 1` when the cursor probe could not measure the
+     * position, and `0` when it did. Filling on a measured terminal would undo the
+     * measurement — and cost the page-flip this feature exists to avoid.
+     */
+    readonly anchorFillRows?: number;
 }
 /**
  * Native-scroll mode's counterpart of `enterAltScreen` (tui-native-terminal-scroll
@@ -81,10 +90,14 @@ export interface NativeScreenOptions {
  * the conversation lands in the terminal's own scrollback; there is no alternate
  * screen, no mouse reporting and no DEC 1007 save/restore.
  *
- * The only mode it touches is DEC 2004 (bracketed paste), which changes how input
- * is encoded and has nothing to do with scrolling. Returns the SAME `ScreenHandle`
- * shape, so the four idempotent restore paths in `cli.tsx` need not know which mode
- * is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
+ * The only modes it touches are DEC 2004 (bracketed paste), which changes how input
+ * is encoded and has nothing to do with scrolling, and — when the bottom anchor could
+ * not be measured — the one-off fill that puts the cursor on the last row. Returns the
+ * SAME `ScreenHandle` shape, so the four idempotent restore paths in `cli.tsx` need not
+ * know which mode is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
+ *
+ * ORDER IS LOAD-BEARING: the fill goes FIRST. Written after `?2004h` it would be the
+ * same bytes, but written after any content it would scroll that content away.
  */
 export declare function enterNativeScreen(stdout: NodeJS.WriteStream | undefined, options?: NativeScreenOptions): ScreenHandle;
 /**

package/dist/ui/screen.js

@@ -11,6 +11,7 @@
  * Hoisting it into `buildProgram()` / `parseAsync` would push `\x1b[?1049h`
  * into `aragon -p "…" > out.txt`, `aragon config set`, and `aragon --version`.
  */
+import { fillBytes } from './scrollback/writer-shapes.js';
 const ENTER_ALT = '\x1b[?1049h';
 const LEAVE_ALT = '\x1b[?1049l';
 const CURSOR_HOME = '\x1b[H';
@@ -187,17 +188,24 @@ export function enterAltScreen(stdout, options = { mouse: false }) {
  * the conversation lands in the terminal's own scrollback; there is no alternate
  * screen, no mouse reporting and no DEC 1007 save/restore.
  *
- * The only mode it touches is DEC 2004 (bracketed paste), which changes how input
- * is encoded and has nothing to do with scrolling. Returns the SAME `ScreenHandle`
- * shape, so the four idempotent restore paths in `cli.tsx` need not know which mode
- * is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
+ * The only modes it touches are DEC 2004 (bracketed paste), which changes how input
+ * is encoded and has nothing to do with scrolling, and — when the bottom anchor could
+ * not be measured — the one-off fill that puts the cursor on the last row. Returns the
+ * SAME `ScreenHandle` shape, so the four idempotent restore paths in `cli.tsx` need not
+ * know which mode is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
+ *
+ * ORDER IS LOAD-BEARING: the fill goes FIRST. Written after `?2004h` it would be the
+ * same bytes, but written after any content it would scroll that content away.
  */
 export function enterNativeScreen(stdout, options = {}) {
     if (!stdout || !stdout.isTTY || typeof stdout.write !== 'function')
         return NOOP_HANDLE;
     const bracketedPaste = options.bracketedPaste === true;
-    if (bracketedPaste)
-        safeWrite(stdout, ENABLE_BRACKETED_PASTE);
+    const fillRows = Math.max(0, Math.floor(options.anchorFillRows ?? 0));
+    const head = (fillRows > 0 ? fillBytes(fillRows) : '') +
+        (bracketedPaste ? ENABLE_BRACKETED_PASTE : '');
+    if (head.length > 0)
+        safeWrite(stdout, head);
     let restored = false;
     return {
         restore() {

package/dist/ui/scrollback/LiveTail.d.ts

@@ -0,0 +1,64 @@
+/**
+ * LiveTail - the band's UNFINISHED tail, rendered with the real entry components
+ * (release-gate-and-native-panels §6.5).
+ *
+ * WHY THIS FILE EXISTS. Native scroll mode cannot print an entry until it settles, so
+ * the live region used to show `buildLivePreview`'s plain-text projection - and for a
+ * running dispatch that projection is four grey rows saying `Team: 2/4 running`. That
+ * is the "simple look" the feature was opened for. A text-only region can never fix
+ * it, which is why the region's content type changed from `readonly string[]` to a
+ * fixed-height box that can hold components.
+ *
+ * IT RENDERS `EntryView` AND NOTHING ELSE. The mapping from an entry to its component
+ * (`assistant` / `tool` / `team` / `todo` / service cards, notice frames, the `null`
+ * cases) lives in `Transcript.tsx` exactly once, together with `EntryFrame`'s gutter,
+ * the separation rows, the per-entry `nowSecFor` clock and the memo comparator. A
+ * second enumeration here would be a copy that drifts: the band's cards would lose the
+ * left rail glyph and the transcript's would keep it, and the two halves of one screen
+ * would disagree about the same entry.
+ *
+ * `justifyContent="flex-end"` PLUS `overflow="hidden"` IS CORRECTNESS, NOT STYLE: when
+ * the content is taller than the budget the rows that get clipped are the OLDEST ones,
+ * so the newest line always sits against the composer - the same promise
+ * `scrollback/canvas.ts` makes about the live tail.
+ *
+ * BOUNDED: at most `SCROLLBACK_LIMITS.liveTailMaxEntries` component instances per frame
+ * (I-10). That is what keeps the per-frame cost the same order as the full-screen live
+ * tail; growing it makes the cost grow linearly because this box has no windowing.
+ */
+import React from 'react';
+import type { Entry } from '../../agent/reducer.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { DensityMode } from '../density.js';
+import type { Theme } from '../theme.js';
+export interface LiveTailProps {
+    /** `entries.slice(settledCount).filter(isExcluded === false)`: the same input as `buildLivePreview`. */
+    unsettled: readonly Entry[];
+    /** Render only the last N entries; the box clips the older ones from the top. */
+    maxEntries: number;
+    /** Fixed height: the root box's `height`. The content never decides it (I-4). */
+    rows: number;
+    /** `budget.previewCols` - the width left after the rail took its column (I-5). */
+    cols: number;
+    expandedToolIds: Record<string, true>;
+    thinkingVisible: boolean;
+    reducedMotion: boolean;
+    density: DensityMode;
+    nowSec?: number;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export interface TailEntry {
+    entry: Entry;
+    /** The entry before it in the FULL list: `EntryView` uses it to decide the separator. */
+    prev: Entry | undefined;
+}
+/**
+ * The last `maxEntries` entries, each with its predecessor.
+ *
+ * `prev` must come from the COMPLETE unsettled list rather than from the truncated
+ * slice, or the first rendered entry would look like the head of the conversation and
+ * drop the separation row the transcript shows above the same card.
+ */
+export declare function selectTailEntries(unsettled: readonly Entry[], maxEntries: number): readonly TailEntry[];
+export declare function LiveTail({ unsettled, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, }: LiveTailProps): React.ReactElement;

package/dist/ui/scrollback/LiveTail.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from 'ink';
+import { EntryView, nowSecFor } from '../Transcript.js';
+import { SCROLLBACK_LIMITS } from './limits.js';
+/**
+ * The last `maxEntries` entries, each with its predecessor.
+ *
+ * `prev` must come from the COMPLETE unsettled list rather than from the truncated
+ * slice, or the first rendered entry would look like the head of the conversation and
+ * drop the separation row the transcript shows above the same card.
+ */
+export function selectTailEntries(unsettled, maxEntries) {
+    const limit = Number.isFinite(maxEntries) ? Math.max(0, Math.floor(maxEntries)) : 0;
+    if (limit === 0)
+        return [];
+    const start = Math.max(0, unsettled.length - limit);
+    const selected = [];
+    for (let index = start; index < unsettled.length; index += 1) {
+        selected.push({ entry: unsettled[index], prev: index > 0 ? unsettled[index - 1] : undefined });
+    }
+    return selected;
+}
+export function LiveTail({ unsettled, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, }) {
+    const limited = Math.min(maxEntries, SCROLLBACK_LIMITS.liveTailMaxEntries);
+    const selected = selectTailEntries(unsettled, limited);
+    return (_jsx(Box, { flexDirection: "column", height: rows, width: cols, justifyContent: "flex-end", flexShrink: 0, overflow: "hidden", children: selected.map(({ entry, prev }) => (_jsx(EntryView, { entry: entry, prev: prev, expanded: expandedToolIds[entry.id] === true, thinkingVisible: thinkingVisible, reducedMotion: reducedMotion, density: density, nowSec: nowSecFor(entry, nowSec), theme: theme, caps: caps }, entry.id))) }));
+}

package/dist/ui/scrollback/band.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Height and column budget of the native-scroll PANEL BAND
+ * (release-gate-and-native-panels §6.2).
+ *
+ * Native scroll mode drops the fixed frame, so it used to drop the panels with it:
+ * the TODO rail lived in `AppShell`'s middle band and the subagent roster in the
+ * viewport footer, and neither is rendered once `ScrollbackShell` takes over. The
+ * band is the replacement - one row pool shared by the roster (`TeamPanel`), the
+ * streaming tail and the rail (`TodoPanel`), sitting directly above the composer.
+ *
+ * PURE: no Ink, no clock, no terminal, no config read. Every invariant below is
+ * therefore established BY CONSTRUCTION for all input combinations and can be
+ * enumerated by a property test (AC-9..AC-14, AC-31):
+ *
+ *  - `bandRows <= remaining` and therefore `liveRows <= rows - 1` (I-4). Ink writes
+ *    `clearTerminal` - which contains `ESC[3J`, erasing the user's scrollback - as
+ *    soon as a frame is as tall as the terminal; that one row is the difference
+ *    between a tidy region and data loss.
+ *  - `previewCols + railCols === contentCols`, always (AC-10). The rail is a column
+ *    INSIDE the region, so the preview loses exactly the columns the rail takes and
+ *    nothing else (I-5: printing keeps the full `contentCols`).
+ *  - `teamRows > 0` leaves room for the rail plus one preview row (AC-12).
+ *  - `previewRows <= previewCap`, so the structural caps
+ *    `maxLiveTailRows` / `liveTailRowShare` keep binding (I-10).
+ *
+ * THERE IS EXACTLY ONE CALL SITE: `buildScrollbackBudget` (I-8). This module is
+ * exported so it can be tested, not so a second caller can allocate rows of its own
+ * - `remaining` is computed there, and a second copy of it is a second authority.
+ */
+export type BandReason = 
+/** Both panels are on screen. */
+'visible'
+/** No active plan: no rail. Same name and meaning as `TodoRailLayout`'s `'empty'`. */
+ | 'empty'
+/** `cfg.todo.panel === false`. */
+ | 'disabled'
+/** An overlay is open: the band yields to it. */
+ | 'overlay'
+/** `todoRailWidth(contentCols) === 0` (terminal narrower than 76 columns). */
+ | 'narrow'
+/** The remaining rows cannot hold `panelMinRows` for the rail. */
+ | 'short';
+export interface LiveBandInput {
+    /**
+     * `buildFrameBudget().viewportRows + headerRows`: every row the band may use.
+     * Computed once by `buildScrollbackBudget`; callers must not re-derive it.
+     */
+    remaining: number;
+    /** `cols - 1`: width of the whole band. `previewCols` is derived from it. */
+    contentCols: number;
+    /** `todoRailWidth(contentCols)`; `layout/rail.ts` stays the width authority. */
+    railCols: number;
+    /** The existing two caps combined: `min(maxLiveTailRows, floor(rows * share))`. */
+    previewCap: number;
+    /** Plain-text rows `buildLivePreview` wants (the measuring authority is unchanged). */
+    previewWanted: number;
+    /** `state.todos.items.length` (0 = no active plan). */
+    itemCount: number;
+    /** `cfg.todo.panel`. */
+    panelEnabled: boolean;
+    overlayOpen: boolean;
+    /** `buildTeamPanelLayout().rowCount`; 0 when there is nothing to show. */
+    teamRowsNatural: number;
+    /** Hysteresis: the rail rows the previous frame already used. */
+    heldRailRows: number;
+    /** Hysteresis: the roster rows the previous frame already used. */
+    heldTeamRows: number;
+}
+export interface LiveBand {
+    reason: BandReason;
+    /** Band height: `teamRows + previewRows`, or `remaining` for an overlay. */
+    bandRows: number;
+    teamRows: number;
+    previewRows: number;
+    /** Row budget of the rail: the whole band (the rail spans it). 0 when hidden. */
+    railRows: number;
+    /** The input `railCols` when visible, 0 when hidden (`/perf` reads `rail=0x0`). */
+    railCols: number;
+    /** `max(0, contentCols - railCols)`; always sums with `railCols` to `contentCols`. */
+    previewCols: number;
+    /** Hysteresis output, fed back on the next frame. */
+    heldRailRows: number;
+    heldTeamRows: number;
+}
+/**
+ * Allocate the band. THE ORDER OF THE STEPS IS THE SPECIFICATION - reordering them
+ * changes the priority between "what this run is doing" (rail + roster) and "the
+ * words arriving right now" (preview), which is a product decision, not a detail.
+ *
+ * 0. Normalise every numeric input (`NaN` / `Infinity` / negatives become 0).
+ * 1. An open overlay takes the whole pool (the band would otherwise double-count it).
+ * 2. Seat the roster first, but never at the cost of the rail plus one preview row:
+ *    a dispatch is transient, the plan is the shape of the turn, both must fit.
+ * 3. Decide the rail's visibility, in the same reason order as `buildTodoRailLayout`.
+ * 4. RESERVE the rail's rows (`panelFullRows` floor - the 3-5 row compact form cannot
+ *    show which item is running, and the band reaches 6 rows far more often than the
+ *    full-screen rail does). A reservation, not the final value: see step 6.
+ * 5. The preview takes what is left, clamped by `previewCap`.
+ * 6. `bandRows = max(railReserved, teamRows + previewRows)`: with no unsettled
+ *    content `previewRows` is 0, yet the rail must still be there (the user is
+ *    reading a result and still needs the list).
+ * 7. Columns: the input `contentCols` is the only width authority.
+ * 8. Hand the late-arriving values (the hysteresis) back out for the next frame.
+ */
+export declare function buildLiveBand(input: LiveBandInput): LiveBand;