@aragon-agent/cli 0.6.43 → 0.6.44

package/dist/proc/kill-tree.d.ts

@@ -38,5 +38,23 @@ export declare function killTree(pid: number | undefined, signal?: NodeJS.Signal
  * The only kill primitive a signal handler, `process.on('exit')` or
  * `handleFatal` may reach (I-9). No escalation ladder and no logging: a reaper
  * that can block or throw is worse than one that misses a child.
+ *
+ * IT RETURNS WHETHER THE KILL WAS CONFIRMED, AND THAT IS NOT BOOKKEEPING. The
+ * Windows branch is a `taskkill` PROCESS, and `spawnSync`'s own `timeout` kills
+ * that process when the budget runs out. Measured on 2026-10-23: one
+ * `taskkill /t /f` of a shell plus its node child takes 1027-1058 ms on an IDLE
+ * machine (five samples), and a `taskkill` cut off at a 150 ms deadline leaves the
+ * tree ALIVE 1.5 s later (`ETIMEDOUT`, `status = null`, `signal = SIGTERM`). This
+ * function used to `catch {}` that result and return `void`, so the one caller
+ * that promises "no service outlives the CLI" could not tell a kill from a
+ * timeout - and a loaded host, where a single tree kill genuinely needs more than
+ * the old 2000 ms, silently leaked every child it was asked to reap.
+ *
+ * The budget therefore lives in `PROC_LIMITS.killTreeSyncTimeoutMs`, sized from
+ * that measurement rather than from optimism, and the answer comes back to the
+ * caller so `reapSync` can raise `killIncomplete` instead of pretending.
+ *
+ * POSIX reports `true` when a signal was DELIVERED, which is as much as a signal
+ * can ever confirm.
  */
-export declare function killTreeSync(pid: number | undefined): void;
+export declare function killTreeSync(pid: number | undefined): boolean;

package/dist/proc/kill-tree.js

@@ -24,6 +24,7 @@
  */
 import { spawn, spawnSync } from 'node:child_process';
 import process from 'node:process';
+import { PROC_LIMITS } from './limits.js';
 /** Is the pid still there? `signal 0` tests for existence without delivering. */
 export function isAlive(pid) {
     if (pid === undefined || !Number.isFinite(pid) || pid <= 0)
@@ -88,32 +89,58 @@ export function killTree(pid, signal = 'SIGKILL') {
  * The only kill primitive a signal handler, `process.on('exit')` or
  * `handleFatal` may reach (I-9). No escalation ladder and no logging: a reaper
  * that can block or throw is worse than one that misses a child.
+ *
+ * IT RETURNS WHETHER THE KILL WAS CONFIRMED, AND THAT IS NOT BOOKKEEPING. The
+ * Windows branch is a `taskkill` PROCESS, and `spawnSync`'s own `timeout` kills
+ * that process when the budget runs out. Measured on 2026-10-23: one
+ * `taskkill /t /f` of a shell plus its node child takes 1027-1058 ms on an IDLE
+ * machine (five samples), and a `taskkill` cut off at a 150 ms deadline leaves the
+ * tree ALIVE 1.5 s later (`ETIMEDOUT`, `status = null`, `signal = SIGTERM`). This
+ * function used to `catch {}` that result and return `void`, so the one caller
+ * that promises "no service outlives the CLI" could not tell a kill from a
+ * timeout - and a loaded host, where a single tree kill genuinely needs more than
+ * the old 2000 ms, silently leaked every child it was asked to reap.
+ *
+ * The budget therefore lives in `PROC_LIMITS.killTreeSyncTimeoutMs`, sized from
+ * that measurement rather than from optimism, and the answer comes back to the
+ * caller so `reapSync` can raise `killIncomplete` instead of pretending.
+ *
+ * POSIX reports `true` when a signal was DELIVERED, which is as much as a signal
+ * can ever confirm.
  */
 export function killTreeSync(pid) {
     if (pid === undefined || !Number.isFinite(pid) || pid <= 0)
-        return;
+        return false;
     if (process.platform === 'win32') {
+        let result;
         try {
-            spawnSync('taskkill', ['/pid', String(pid), '/t', '/f'], {
+            result = spawnSync('taskkill', ['/pid', String(pid), '/t', '/f'], {
                 windowsHide: true,
                 stdio: 'ignore',
-                timeout: 2000,
+                timeout: PROC_LIMITS.killTreeSyncTimeoutMs,
             });
         }
         catch {
-            /* ignore */
+            return false;
         }
-        return;
+        // `error` is set for a spawn failure AND for the budget expiring (`ETIMEDOUT`,
+        // with `signal = SIGTERM`), and neither is a kill.
+        if (result.error)
+            return false;
+        return result.status === 0;
     }
     try {
         process.kill(-pid, 'SIGKILL');
+        return true;
     }
     catch {
         try {
             process.kill(pid, 'SIGKILL');
+            return true;
         }
         catch {
             /* already gone */
+            return false;
         }
     }
 }

package/dist/proc/limits.d.ts

@@ -102,6 +102,25 @@ export declare const PROC_LIMITS: {
     readonly killVerifyMs: 2000;
     /** Liveness poll interval while waiting for a `SIGKILL` to land. */
     readonly killVerifyPollMs: 50;
+    /**
+     * How long ONE synchronous tree kill (`killTreeSync`) may take.
+     *
+     * MEASURED, NOT GUESSED. A `taskkill /pid <shell> /t /f` of a shell plus its
+     * node child takes 1027-1058 ms on the reference machine on an IDLE host (five
+     * samples, 2026-10-23), so the old 2000 ms was 1.9x the honest cost and the
+     * 2026-10-23 release run - where the whole suite took 340 s against the usual
+     * 200-240 s - is comfortably inside the range where a single tree kill exceeds
+     * it. Crossing it is not a slow kill, it is NO kill: `spawnSync` kills
+     * `taskkill` itself at the deadline and the tree keeps running (verified: a
+     * 150 ms budget left the child alive 1.5 s later, `ETIMEDOUT` / `status null`).
+     *
+     * 5000 ms is ~5x the measured cost. It is a CEILING and not a cost: a tree that
+     * dies in the usual second still returns in that second. The worst case is
+     * `maxJobs` (16) trees at the ceiling on an exit hook, which is why this is not
+     * any larger - the reaper prefers a reported miss to an exit that never ends,
+     * and the miss is now reported (`ProcRecord.killIncomplete`).
+     */
+    readonly killTreeSyncTimeoutMs: 5000;
     /** Below this many terminal columns the status chip degrades to `[N]`. */
     readonly statusCompactCols: 92;
     /**

package/dist/proc/limits.js

@@ -102,6 +102,25 @@ export const PROC_LIMITS = {
     killVerifyMs: 2000,
     /** Liveness poll interval while waiting for a `SIGKILL` to land. */
     killVerifyPollMs: 50,
+    /**
+     * How long ONE synchronous tree kill (`killTreeSync`) may take.
+     *
+     * MEASURED, NOT GUESSED. A `taskkill /pid <shell> /t /f` of a shell plus its
+     * node child takes 1027-1058 ms on the reference machine on an IDLE host (five
+     * samples, 2026-10-23), so the old 2000 ms was 1.9x the honest cost and the
+     * 2026-10-23 release run - where the whole suite took 340 s against the usual
+     * 200-240 s - is comfortably inside the range where a single tree kill exceeds
+     * it. Crossing it is not a slow kill, it is NO kill: `spawnSync` kills
+     * `taskkill` itself at the deadline and the tree keeps running (verified: a
+     * 150 ms budget left the child alive 1.5 s later, `ETIMEDOUT` / `status null`).
+     *
+     * 5000 ms is ~5x the measured cost. It is a CEILING and not a cost: a tree that
+     * dies in the usual second still returns in that second. The worst case is
+     * `maxJobs` (16) trees at the ceiling on an exit hook, which is why this is not
+     * any larger - the reaper prefers a reported miss to an exit that never ends,
+     * and the miss is now reported (`ProcRecord.killIncomplete`).
+     */
+    killTreeSyncTimeoutMs: 5000,
     /** Below this many terminal columns the status chip degrades to `[N]`. */
     statusCompactCols: 92,
     // --- long-task-jobs: bounded waiting, progress, notices, log mirror --------

package/dist/proc/supervisor.js

@@ -404,9 +404,16 @@ export class ProcSupervisor {
         for (const entry of this.services.values()) {
             if (isTerminalStatus(entry.record.status))
                 continue;
-            killTreeSync(entry.record.pid);
+            // THE ANSWER IS PART OF THE REAP (AC-42, 2026-10-23 release). A `taskkill`
+            // that outlived its budget is killed itself and the tree survives, so an
+            // unconfirmed kill has to reach the record the card and `bash_output` read -
+            // otherwise "stopped" is a claim nobody made good on. `killIncomplete` is
+            // that field (P2-6), and it is the reason the reaper may keep a bound at all.
+            const killed = killTreeSync(entry.record.pid);
             entry.record.status = 'stopped';
             entry.record.endedAt = Date.now();
+            if (!killed)
+                entry.record.killIncomplete = true;
             entry.watcher?.stop();
             if (entry.outputTimer)
                 clearTimeout(entry.outputTimer);

package/dist/tools/bounded-spawn.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A CHILD PROCESS WITH A DEADLINE (bug-diagnosis 0b33323c, release gate 2026-10-23).
+ *
+ * WHY THIS EXISTS. `search-tools.ts` used to await a bare `spawn('rg', ...)` whose
+ * promise settled on `'close'` and on nothing else. A child that never closes -
+ * a launcher shim blocked by a scanner, a wedged network drive, a filesystem that
+ * stopped answering - therefore left the tool pending FOREVER: the model's turn
+ * had no result to return, the Ink frame had no answer to draw, and the only thing
+ * that ever ended it was the test runner's wall clock
+ * (`tools.test.ts > grep finds a seeded pattern`, `Test timed out in 30000ms`,
+ * 2026-10-23 release). CLAUDE.md section 5 says exactly what is missing here: at
+ * an IO / subprocess boundary use a structured wrapper with a timeout, never a
+ * bare call.
+ *
+ * SETTLES ONCE, ALWAYS. Every way a child can end - exit, spawn failure, and OUR
+ * OWN deadline - resolves this promise, and the first of them wins. The deadline
+ * is the last resort, not a measuring instrument: a caller that has produced an
+ * answer is not interrupted by it (`clearTimeout` happens in `finish`).
+ *
+ * THE KILL IS A TREE KILL. `rg` on Windows is reached through a launcher
+ * (`shims/rg.exe`), and killing the launcher alone leaves the real search running
+ * forever - which would keep this fix from fixing anything. `killTree` is the one
+ * owner of that knowledge in this package and it never throws.
+ */
+/** What ended the child, which is the only thing the caller can act on. */
+export type DeadlineOutcome = 
+/** The child closed on its own; `exitCode` is real. */
+'exit'
+/** It outlived `deadlineMs`; it has been killed and `stdout` is what it managed. */
+ | 'deadline'
+/** It never started (`ENOENT` and friends). */
+ | 'unavailable';
+export interface DeadlineResult {
+    outcome: DeadlineOutcome;
+    /** `null` for `'deadline'` and `'unavailable'`: there was no exit status. */
+    exitCode: number | null;
+    /** Everything the child wrote to stdout before it settled. */
+    stdout: string;
+}
+export interface DeadlineOptions {
+    cwd: string;
+    /** Hard limit on the child's lifetime, in milliseconds. Must be > 0. */
+    deadlineMs: number;
+}
+/**
+ * Run `command` and settle within `deadlineMs`, whatever the child does.
+ *
+ * stderr is DROPPED rather than piped: nothing here reads it, and an undrained
+ * pipe is a second way to wedge a child (the buffer fills and it blocks on write).
+ * stdin is `ignore` for the same reason in reverse - a child that decides to read
+ * stdin must see EOF, not wait for a user who is not there.
+ *
+ * Never throws, never rejects: a caller that has to explain a failure gets
+ * `'unavailable'` or `'deadline'` instead of an exception it did not expect.
+ */
+export declare function runWithDeadline(command: string, args: string[], options: DeadlineOptions): Promise<DeadlineResult>;

package/dist/tools/bounded-spawn.js

@@ -0,0 +1,76 @@
+/**
+ * A CHILD PROCESS WITH A DEADLINE (bug-diagnosis 0b33323c, release gate 2026-10-23).
+ *
+ * WHY THIS EXISTS. `search-tools.ts` used to await a bare `spawn('rg', ...)` whose
+ * promise settled on `'close'` and on nothing else. A child that never closes -
+ * a launcher shim blocked by a scanner, a wedged network drive, a filesystem that
+ * stopped answering - therefore left the tool pending FOREVER: the model's turn
+ * had no result to return, the Ink frame had no answer to draw, and the only thing
+ * that ever ended it was the test runner's wall clock
+ * (`tools.test.ts > grep finds a seeded pattern`, `Test timed out in 30000ms`,
+ * 2026-10-23 release). CLAUDE.md section 5 says exactly what is missing here: at
+ * an IO / subprocess boundary use a structured wrapper with a timeout, never a
+ * bare call.
+ *
+ * SETTLES ONCE, ALWAYS. Every way a child can end - exit, spawn failure, and OUR
+ * OWN deadline - resolves this promise, and the first of them wins. The deadline
+ * is the last resort, not a measuring instrument: a caller that has produced an
+ * answer is not interrupted by it (`clearTimeout` happens in `finish`).
+ *
+ * THE KILL IS A TREE KILL. `rg` on Windows is reached through a launcher
+ * (`shims/rg.exe`), and killing the launcher alone leaves the real search running
+ * forever - which would keep this fix from fixing anything. `killTree` is the one
+ * owner of that knowledge in this package and it never throws.
+ */
+import { spawn } from 'node:child_process';
+import { killTree } from '../proc/kill-tree.js';
+/**
+ * Run `command` and settle within `deadlineMs`, whatever the child does.
+ *
+ * stderr is DROPPED rather than piped: nothing here reads it, and an undrained
+ * pipe is a second way to wedge a child (the buffer fills and it blocks on write).
+ * stdin is `ignore` for the same reason in reverse - a child that decides to read
+ * stdin must see EOF, not wait for a user who is not there.
+ *
+ * Never throws, never rejects: a caller that has to explain a failure gets
+ * `'unavailable'` or `'deadline'` instead of an exception it did not expect.
+ */
+export function runWithDeadline(command, args, options) {
+    return new Promise((settle) => {
+        let child;
+        try {
+            child = spawn(command, args, {
+                cwd: options.cwd,
+                stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true,
+            });
+        }
+        catch {
+            settle({ outcome: 'unavailable', exitCode: null, stdout: '' });
+            return;
+        }
+        let stdout = '';
+        let settled = false;
+        let timer;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            settle(result);
+        };
+        timer = setTimeout(() => {
+            // A pid is all `killTree` needs, and it is the only kill that reaches a
+            // grandchild. Partial output is still output: the caller decides whether a
+            // truncated answer is worth having.
+            killTree(child.pid);
+            finish({ outcome: 'deadline', exitCode: null, stdout });
+        }, options.deadlineMs);
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.on('error', () => finish({ outcome: 'unavailable', exitCode: null, stdout }));
+        child.on('close', (code) => finish({ outcome: 'exit', exitCode: code, stdout }));
+    });
+}

package/dist/tools/search-tools.js

@@ -5,13 +5,30 @@
  * prefers ripgrep when it is on PATH and falls back to a pure-JS scan otherwise;
  * both produce `path:line:text` output.
  */
-import { spawn } from 'node:child_process';
 import { promises as fs } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { glob as tinyGlob } from 'tinyglobby';
 import { defineTool, errorResult, textResult, } from '@aragon-agent/core';
+import { runWithDeadline } from './bounded-spawn.js';
 const MAX_GREP_MATCHES = 500;
 const MAX_FILE_BYTES = 5_000_000;
+/**
+ * How long `rg` may run before the search is abandoned and answered in-process.
+ *
+ * THE BUDGET IS NOT A GUESS ABOUT SPEED, IT IS THE ONLY WAY THIS TOOL ENDS WHEN
+ * `rg` WILL NOT. Measured on the reference machine (2026-10-23): `rg` over a
+ * two-file temp directory settles in 58-62 ms (five samples), so 15 s is ~250x
+ * the normal case - it cannot fire because a search is merely slow, only because
+ * the child is stuck (a launcher shim blocked by a scanner, a filesystem that
+ * stopped answering). Without it, the failing 2026-10-23 release run left this
+ * tool's promise pending until `tools.test.ts` hit its 30 s wall clock: a hung
+ * `rg` was indistinguishable from a hung agent turn, forever.
+ *
+ * WHEN IT FIRES the in-process scan below answers instead, which is the same
+ * fallback a host without `rg` already gets - so a stuck child degrades the
+ * search rather than the session.
+ */
+const GREP_SUBPROCESS_DEADLINE_MS = 15_000;
 // ---------------------------------------------------------------------------
 // glob
 // ---------------------------------------------------------------------------
@@ -109,51 +126,42 @@ export function makeGrep(deps) {
 }
 /**
  * Attempt ripgrep. Returns the matched lines, `[]` for a clean no-match, or
- * `null` when ripgrep is unavailable (so the caller falls back to JS).
+ * `null` when ripgrep cannot answer (so the caller falls back to JS).
+ *
+ * THE SUBPROCESS BUDGET IS PART OF THE CONTRACT (see `GREP_SUBPROCESS_DEADLINE_MS`
+ * and `tools/bounded-spawn.ts`). Every one of the three ways `rg` can fail now
+ * settles this promise: it exits, it never starts, or it outlives its deadline and
+ * the in-process scan takes over. What is gone is the fourth one - hanging here
+ * forever - which is what the release gate actually caught.
  */
-function tryRipgrep(params, searchRoot, cwd) {
-    return new Promise((resolvePromise) => {
-        const args = ['--no-heading', '--line-number', '--color', 'never', '--max-count', String(MAX_GREP_MATCHES)];
-        if (params.ignoreCase)
-            args.push('--ignore-case');
-        if (params.glob)
-            args.push('--glob', params.glob);
-        args.push('--regexp', params.pattern, searchRoot);
-        let child;
-        try {
-            child = spawn('rg', args, { cwd });
-        }
-        catch {
-            resolvePromise(null);
-            return;
-        }
-        let stdout = '';
-        let settled = false;
-        const done = (value) => {
-            if (!settled) {
-                settled = true;
-                resolvePromise(value);
-            }
-        };
-        child.on('error', () => done(null)); // ENOENT — rg not installed.
-        child.stdout?.on('data', (d) => {
-            stdout += d.toString();
-        });
-        child.on('close', (code) => {
-            // rg exits 0 with matches, 1 with no matches, 2 on error.
-            if (code === 0 || code === 1) {
-                const lines = stdout
-                    .split('\n')
-                    .filter((l) => l.trim().length > 0)
-                    .slice(0, MAX_GREP_MATCHES)
-                    .map((l) => normalizeRgLine(l, searchRoot, cwd));
-                done(lines);
-            }
-            else {
-                done(null);
-            }
-        });
+async function tryRipgrep(params, searchRoot, cwd) {
+    const args = [
+        '--no-heading',
+        '--line-number',
+        '--color',
+        'never',
+        '--max-count',
+        String(MAX_GREP_MATCHES),
+    ];
+    if (params.ignoreCase)
+        args.push('--ignore-case');
+    if (params.glob)
+        args.push('--glob', params.glob);
+    args.push('--regexp', params.pattern, searchRoot);
+    const run = await runWithDeadline('rg', args, {
+        cwd,
+        deadlineMs: GREP_SUBPROCESS_DEADLINE_MS,
     });
+    if (run.outcome !== 'exit')
+        return null;
+    // rg exits 0 with matches, 1 with no matches, 2 on error.
+    if (run.exitCode !== 0 && run.exitCode !== 1)
+        return null;
+    return run.stdout
+        .split('\n')
+        .filter((line) => line.trim().length > 0)
+        .slice(0, MAX_GREP_MATCHES)
+        .map((line) => normalizeRgLine(line, searchRoot, cwd));
 }
 function normalizeRgLine(line, searchRoot, cwd) {
     // ripgrep emits absolute or root-relative paths; normalize to cwd-relative.

package/dist/ui/ScrollbackShell.d.ts

@@ -11,7 +11,7 @@
  * off its `clearTerminal` branch (that branch fires at `outputHeight >= rows` and
  * contains `ESC[3J`, which erases the user's scrollback).
  *
- * Top to bottom: [header][overlay | panel band][composer][status][details].
+ * Top to bottom: [overlay | panel band][composer][identity][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
@@ -40,11 +40,39 @@
  * content would make the region taller than `budget.liveRows`, and a frame as tall as
  * the terminal makes Ink erase the user's scrollback.
  *
+ * THE IDENTITY ROW IS A BOTTOM SLOT, NOT THE FIRST ONE
+ * (tui-header-leaks-into-scrollback, plan A-prime). It is still `budget.headerRows` tall
+ * and still spent out of the region's pool - only its ORDER changed:
+ *  - position is not cosmetic here, it is the whole defect. The writer lays the canvas out
+ *    as `[gap][content][region]` and only CONTENT rows ever scroll out (`canvas.ts`), so
+ *    region row 0 is by construction the successor of the newest row in the terminal's
+ *    scrollback. A tall reply gives way at the top (`overflow-print.ts`: head printed,
+ *    tail on screen), so chrome parked on row 0 is read BETWEEN two rows of the SAME
+ *    answer: the user's report is the word mark, `provider:model`, `cwd`, the key and
+ *    `^G more` appearing in the middle of a finished reply.
+ *  - the bottom slots have no such property: nothing below the band is ever printed or
+ *    scrolled, so `[composer][identity][status][details]` stays outside the conversation
+ *    for a reply of any length. That band is also the one the writer protects on purpose
+ *    (I-B17: give way at the TOP, because the composer and the status line are the two
+ *    rows the human is interacting with).
+ *  - the two surrounding slots are NOT interchangeable. Above the composer would also
+ *    dodge the seam, but it would break the promise that the newest line hugs the input
+ *    box (`canvas.ts`, `tail-anchor.ts`); below the status group would split the
+ *    `[status][details]` pair, and "the status is the screen's last row" is its own
+ *    invariant (`tui-duplicate-status-row`); inside the band's row pool would change
+ *    `previewRows`, and no budget number may move for this fix.
+ *  - `app` mode (`layout/AppShell.tsx`) deliberately keeps its header on TOP, so the two
+ *    modes do NOT agree and must not be "unified": there the header sits above a viewport
+ *    that scrolls itself, so there is no print channel and no seam to leak into.
+ *  - `headerRows` is still produced by `buildScrollbackBudget` alone (still 1, still
+ *    subtracted from `remaining`), so `liveRows`, `bandRows`, `previewRows` and `railCols`
+ *    are unchanged: a row ORDER change, not a row BUDGET change.
+ *  - the row is still NOT printed into the scrollback: at `H = rows - 1` any printed row
+ *    is pushed off the screen by the next frame, so "print the header" would mean "the
+ *    header is never visible".
+ *
  * THE BAND'S PREVIEW BOX IS TOP-ALIGNED; THE OTHER SLOTS ARE FIXED
  * (D3 / D4 / I-F7; tui-first-reply-bottom-aligned, plan A-prime):
- *  - `header` is the fixed 1-row slot at the very top. It is NOT printed into the
- *    scrollback any more: at `H = rows - 1` any printed row is pushed off the screen by
- *    the next frame, so "print the header" would mean "the header is never visible".
  *  - the band's preview box is TOP-aligned unconditionally, which is why the alignment is
  *    no longer a function of `opener`. `opener` is a 12-row card in a 24-row column, so
  *    bottom-aligning it left 12 blank rows in the upper half of the screen - the original
@@ -71,9 +99,9 @@ import type { ScrollbackBudget } from './scrollback/budget.js';
 export interface ScrollbackShellProps {
     budget: ScrollbackBudget;
     /**
-     * REQUIRED: the one-row slot at the top of the region, `budget.headerRows` tall.
-     * Required rather than optional for the reason `budget` and `band` are - a frame
-     * that forgot it would render a header-less screen with nothing to catch it.
+     * REQUIRED: the identity row, `budget.headerRows` tall, drawn BETWEEN the composer and
+     * the status group. Required rather than optional for the reason `budget` and `band` are
+     * - a frame that forgot it would render a header-less screen with nothing to catch it.
      */
     header: React.ReactNode;
     /** Shown instead of the band when an overlay is open. */

package/dist/ui/ScrollbackShell.js

@@ -22,5 +22,5 @@ export function ScrollbackShell({ budget, header, overlay, liveTailLines, opener
     const top = band.reason === 'overlay' ? (_jsx(Box, { flexDirection: "column", height: budget.overlayRows, flexShrink: 0, overflow: "hidden", children: overlay })) : band.bandRows > 0 ? (
     // ROW REGION ABOVE, FULL-WIDTH ROSTER BELOW (tui-subagent-panel §4.1.2 / D-2).
     _jsxs(Box, { flexDirection: "column", height: band.bandRows, flexShrink: 0, overflow: "hidden", children: [_jsxs(Box, { flexDirection: "row", height: rowRegion, flexShrink: 0, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", width: budget.previewCols, height: rowRegion, flexShrink: 0, overflow: "hidden", children: band.previewRows > 0 && (_jsx(Box, { flexDirection: "column", height: band.previewRows, flexShrink: 0, justifyContent: "flex-start", overflow: "hidden", children: leftColumn ?? 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 }))] }), band.teamRows > 0 && (_jsx(Box, { width: width, height: band.teamRows, flexShrink: 0, overflow: "hidden", children: team }))] })) : null;
-    return (_jsxs(Box, { flexDirection: "column", height: budget.liveRows, width: width, overflow: "hidden", flexShrink: 0, children: [budget.headerRows > 0 && (_jsx(Box, { height: budget.headerRows, flexShrink: 0, overflow: "hidden", children: header })), 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 }))] }));
+    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 }), budget.headerRows > 0 && (_jsx(Box, { height: budget.headerRows, flexShrink: 0, overflow: "hidden", children: header })), _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/scrollback/LiveTail.d.ts

@@ -32,7 +32,9 @@
  * so a four-row first turn was pushed against the composer and every unused row sat ABOVE
  * the conversation. `tailAnchor` therefore sums the estimated height of exactly the
  * entries this frame renders and asks for `flex-start` while they fit - the conversation
- * is then written downwards from under the header, the way a terminal writes.
+ * is then written downwards from the region's top row, the way a terminal writes. (That row
+ * belongs to the band: `tui-header-leaks-into-scrollback` moved the identity row below the
+ * composer, so nothing sits between the newest printed row and the first row of the tail.)
  *
  * THE OVERFLOW FRAME STAYS `flex-end`, AND THAT IS THE OTHER HALF OF THE FIX.
  * `flex-start` PLUS `overflow="hidden"` clips the NEWEST rows (Ink's clip rectangle is

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

@@ -12,15 +12,20 @@
  * and every row it did not ask for became `gap` - blank rows ABOVE the content, which
  * is what the user reported as "the app starts halfway down the screen" and as "a big
  * blank between the result and the running card". The band now takes the whole pool
- * (`fill`), so the region is `[header][band][composer][status]` top to bottom and
+ * (`fill`), so the region is `[band][composer][identity][status]` top to bottom and
  * `gap` cannot exist: `resolveCanvasLayout` is given `frameRows === capacity` and
  * derives `gap = 0` (see the spec's §5.5 proof, which is why the writer needs no
  * change at all).
  *
  * The composer, popup and status rows come from the SAME `buildFrameBudget` the
  * full-screen layout uses, so the two modes cannot disagree about how tall the
- * editor is. What differs is the top: the header is a real slot here (D3), and the
- * row it occupies is spent from the region, not from the printed transcript.
+ * editor is. What differs is the top: the identity row is a real slot here (D3), and
+ * the row it occupies is spent from the region, not from the printed transcript.
+ * THE COUNT IS ALL THIS MODULE OWNS, NOT THE POSITION: since
+ * `tui-header-leaks-into-scrollback` the identity row is drawn between the composer and
+ * the status group (`ScrollbackShell.tsx`), because region row 0 is necessarily the
+ * successor of the newest printed row and chrome there lands inside the conversation.
+ * Moving it changed no number below: it is still 1 row, still taken out of `remaining`.
  *
  * THIS IS THE ONLY CALL SITE OF `buildLiveBand` (I-8). `remaining` is computed here
  * once and handed to the band; an `App` that computed its own copy would make
@@ -58,9 +63,10 @@ export interface ScrollbackBudget {
     /** Terminal below the 40x12 floor: the region is a one-row placeholder. */
     inactive: boolean;
     /**
-     * The header slot, a real row inside the region (D3). 0 on a degraded frame: the
-     * placeholder draws no header, and reporting 1 there would break the row identity
-     * (I-F4) on exactly the frames `/perf` is read to explain.
+     * The identity slot, a real row inside the region (D3), drawn between the composer and
+     * the status group. 0 on a degraded frame: the placeholder draws no header, and
+     * reporting 1 there would break the row identity (I-F4) on exactly the frames `/perf` is
+     * read to explain.
      */
     headerRows: number;
     statusRows: 0 | 1 | 2;

package/dist/ui/scrollback/budget.js

@@ -12,15 +12,20 @@
  * and every row it did not ask for became `gap` - blank rows ABOVE the content, which
  * is what the user reported as "the app starts halfway down the screen" and as "a big
  * blank between the result and the running card". The band now takes the whole pool
- * (`fill`), so the region is `[header][band][composer][status]` top to bottom and
+ * (`fill`), so the region is `[band][composer][identity][status]` top to bottom and
  * `gap` cannot exist: `resolveCanvasLayout` is given `frameRows === capacity` and
  * derives `gap = 0` (see the spec's §5.5 proof, which is why the writer needs no
  * change at all).
  *
  * The composer, popup and status rows come from the SAME `buildFrameBudget` the
  * full-screen layout uses, so the two modes cannot disagree about how tall the
- * editor is. What differs is the top: the header is a real slot here (D3), and the
- * row it occupies is spent from the region, not from the printed transcript.
+ * editor is. What differs is the top: the identity row is a real slot here (D3), and
+ * the row it occupies is spent from the region, not from the printed transcript.
+ * THE COUNT IS ALL THIS MODULE OWNS, NOT THE POSITION: since
+ * `tui-header-leaks-into-scrollback` the identity row is drawn between the composer and
+ * the status group (`ScrollbackShell.tsx`), because region row 0 is necessarily the
+ * successor of the newest printed row and chrome there lands inside the conversation.
+ * Moving it changed no number below: it is still 1 row, still taken out of `remaining`.
  *
  * THIS IS THE ONLY CALL SITE OF `buildLiveBand` (I-8). `remaining` is computed here
  * once and handed to the band; an `App` that computed its own copy would make
@@ -56,9 +61,11 @@ export function buildScrollbackBudget(input) {
     }
     // D1 · H = C. `frameRows` is `rows - 1` by construction (`layout/budget.ts`), so the
     // region ends exactly on the row above the writer's parked cursor.
+    // The identity row is drawn at the BOTTOM now; it is still one row and still deducted
+    // here, which is why `liveRows`, `bandRows` and `previewRows` did not move with it.
     const headerRows = 1;
     const liveRows = Math.max(1, base.frameRows);
-    // The whole pool: everything between the header and the status line. Two independent
+    // The whole pool: everything above the composer slot. Two independent
     // derivations put its floor at 1, so `max(0, ...)` is defensive only:
     //  1. `composerSlotRows = 2 + clampDraftRows(rows, draftRows)` and
     //     `draftMaxRows(rows) = max(1, min(6, floor(rows / 4)))`, so on the narrowest

package/dist/ui/scrollback/tail-anchor.d.ts

@@ -7,7 +7,9 @@
  * `justifyContent="flex-end"` therefore pushed those four rows against the composer and
  * left every unused row ABOVE the conversation - the "the first reply starts at the
  * bottom of the screen" report. The answer is conditional anchoring: top while the
- * content fits, so the conversation is written downwards from under the header.
+ * content fits, so the conversation is written downwards from the region's top row
+ * (`tui-header-leaks-into-scrollback` took the identity row off that row and put it
+ * below the composer, so the first line of the band is now the first line of the screen).
  *
  * WHY THE FALLBACK IS `bottom` AND NOT THE OTHER WAY ROUND. `flex-start` inside an
  * `overflow="hidden"` box clips the NEWEST rows (Ink's clip rectangle is the box's
@@ -26,7 +28,8 @@
  * parameters and a unit test can drive it with any table it likes.
  */
 import type { Entry } from '../../agent/reducer.js';
-/** `top` = content grows down from the header; `bottom` = newest row hugs the composer. */
+/** `top` = content grows down from the region's top row; `bottom` = newest row hugs the
+ *  composer. */
 export type TailAnchor = 'top' | 'bottom';
 /**
  * Which alignment the live tail should use for the entries it is about to render.

package/dist/ui/scrollback/tail-anchor.js

@@ -7,7 +7,9 @@
  * `justifyContent="flex-end"` therefore pushed those four rows against the composer and
  * left every unused row ABOVE the conversation - the "the first reply starts at the
  * bottom of the screen" report. The answer is conditional anchoring: top while the
- * content fits, so the conversation is written downwards from under the header.
+ * content fits, so the conversation is written downwards from the region's top row
+ * (`tui-header-leaks-into-scrollback` took the identity row off that row and put it
+ * below the composer, so the first line of the band is now the first line of the screen).
  *
  * WHY THE FALLBACK IS `bottom` AND NOT THE OTHER WAY ROUND. `flex-start` inside an
  * `overflow="hidden"` box clips the NEWEST rows (Ink's clip rectangle is the box's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.6.43",
+  "version": "0.6.44",
   "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.55",
+    "@aragon-agent/core": "^0.2.56",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",