@aragon-agent/cli 0.6.42 → 0.6.44

package/dist/team/runtime.js

@@ -361,6 +361,36 @@ export class TeamRuntime {
     // Dispatch
     // -------------------------------------------------------------------------
     async dispatch(specs, requested, signal) {
+        try {
+            return await this.runDispatch(specs, requested, signal);
+        }
+        catch (error) {
+            // A throw out of the dispatch body (a child that cannot be constructed) must not
+            // leave `busy` latched: every later `task` call, `/team` and busy-guarded command
+            // of the session would answer "a dispatch is already running". The success path
+            // tears down inline and never reaches this.
+            this.resetDispatchState();
+            throw error;
+        }
+    }
+    /** Idempotent: puts every per-dispatch field back where `dispatch()` found it. */
+    resetDispatchState() {
+        if (this.dispatchTimer)
+            clearTimeout(this.dispatchTimer);
+        this.dispatchTimer = null;
+        for (const handle of this.live)
+            handle.unsubscribe();
+        this.monitor?.dispose();
+        this.monitor = null;
+        this.supervision?.clearAll();
+        this.supervision = null;
+        this.overseer = null;
+        this.live = [];
+        this.bus = null;
+        this.snapshotState = null;
+        this.busy = false;
+    }
+    async runDispatch(specs, requested, signal) {
         this.counter += 1;
         const dispatchId = `d${this.counter}`;
         const config = this.deps.getConfig();
@@ -703,7 +733,9 @@ export class TeamRuntime {
             // where the replacement is actually built and driven. `attempt` resets so
             // the fresh body gets its own cold-start budget.
             if (verdict !== null && verdict.action === 'replace' && !this.aborted) {
-                this.replaceChild(dispatchId, handles, index, makeHandle, handle, verdict);
+                if (this.replaceChild(dispatchId, handles, index, makeHandle, handle, verdict) === null) {
+                    return;
+                }
                 attempt = 0;
                 continue;
             }
@@ -734,7 +766,8 @@ export class TeamRuntime {
                 this.monitor?.clear(run.label);
                 return;
             }
-            this.replaceChild(dispatchId, handles, index, makeHandle, handle, null);
+            if (this.replaceChild(dispatchId, handles, index, makeHandle, handle, null) === null)
+                return;
             await this.backoff(TEAM_LIMITS.retryBackoffMs);
             if (this.aborted) {
                 const fresh = handles[index];
@@ -778,12 +811,13 @@ export class TeamRuntime {
             trigger: 'postmortem',
         });
         if (decision.action === 'replace' && overseer.replacementsLeft(run.label)) {
-            this.replaceChild(ctx.dispatchId, ctx.handles, index, ctx.makeHandle, handle, {
+            const fresh = this.replaceChild(ctx.dispatchId, ctx.handles, index, ctx.makeHandle, handle, {
                 action: 'replace',
                 reason: decision.reason,
                 ...(decision.guidance !== undefined ? { guidance: decision.guidance } : {}),
             });
-            await this.runOne(ctx, index);
+            if (fresh !== null)
+                await this.runOne(ctx, index);
         }
     }
     /**
@@ -822,13 +856,35 @@ export class TeamRuntime {
                 }, handle.run),
             }
             : handle.spec;
-        const fresh = makeHandle(spec);
+        let fresh;
+        try {
+            fresh = makeHandle(spec);
+        }
+        catch (err) {
+            // The old body is already unsubscribed and aborted, so nothing will ever update
+            // its run again: left alone the panel shows it running forever. Settle IT.
+            const run = handle.run;
+            const reason = err instanceof Error ? err.message : String(err);
+            run.phase = 'failed';
+            run.error = `${run.error ? `${run.error}; ` : ''}could not build replacement: ${reason}`;
+            run.endedAt = run.endedAt ?? Date.now();
+            this.supervision?.clear(run.label);
+            this.monitor?.clear(run.label);
+            this.publish(dispatchId, run);
+            return null;
+        }
         // Provably {0,0} under the cold-start predicate above (no turn completed,
         // so no `turn_end` and no usage event). Carried anyway so that a future
         // relaxation of the predicate cannot silently under-report spend - the most
         // misleading failure this feature can produce.
         fresh.run.usage = carried;
         fresh.run.retries = retries;
+        // The files the discarded body already wrote are on disk whatever happens next,
+        // so the report and the conflict warning must keep seeing them (and a chained
+        // replacement must keep telling the next body about them). ONLY the ledger moves:
+        // `turns` / `toolCalls` are live controls (turn cap, cold-start retry predicate,
+        // supervisor digest) that describe the CURRENT body. Empty on a cold-start retry.
+        fresh.run.filesTouched = handle.run.filesTouched.slice(0, TEAM_LIMITS.filesTouchedMax);
         if (replacements > 0)
             fresh.run.replacements = replacements;
         if (interventions !== undefined)

package/dist/team/subagent.js

@@ -15,6 +15,7 @@ import { formatStreamError } from '../agent/reducer.js';
 import { buildSystemPrompt } from '../agent/system-prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
 import { createBuiltinTools, gatedToolTimeouts, } from '../tools/index.js';
+import { ledgerPathKey, normalizeLedgerPath } from './report.js';
 import { describeToolActivity, pickActivityArgs, sanitizeActivity } from './activity.js';
 import { TEAM_LIMITS, TEAM_SUBAGENT_TOOL_NAMES } from './limits.js';
 import { appendTimeline } from './timeline.js';
@@ -386,17 +387,26 @@ export function createSubagent(spec, deps, hooks) {
             textTail.length > 0 ? sanitizeActivity(textTail, TEAM_LIMITS.activityChars) : undefined;
         hooks.onUpdate({ ...run, filesTouched: [...run.filesTouched] });
     };
-    const noteFile = (toolName, args) => {
+    /**
+     * The path a write tool is ABOUT to touch, or `undefined` for every other tool.
+     * Staged on the start event and committed on the end event, because only the end
+     * event knows whether the write happened (`isError`). The string is the path alone,
+     * never the file body (P1-4 / P1-5).
+     */
+    const stagedWritePath = (toolName, args) => {
         if (toolName !== 'write_file' && toolName !== 'edit_file')
-            return;
+            return undefined;
         const path = args?.path;
-        if (typeof path !== 'string' || path.length === 0)
-            return;
-        if (run.filesTouched.includes(path))
+        return typeof path === 'string' && path.length > 0 ? path : undefined;
+    };
+    const noteFile = (path) => {
+        const normalized = normalizeLedgerPath(deps.getCwd(), path);
+        const key = ledgerPathKey(normalized);
+        if (run.filesTouched.some((known) => ledgerPathKey(known) === key))
             return;
         if (run.filesTouched.length >= TEAM_LIMITS.filesTouchedMax)
             return;
-        run.filesTouched.push(path);
+        run.filesTouched.push(normalized);
     };
     const unsubscribe = agent.subscribe((event) => {
         switch (event.type) {
@@ -476,18 +486,26 @@ export function createSubagent(spec, deps, hooks) {
                 // Recorded for the DURATION only; the entry itself is appended on the end
                 // event, when `ok` and `ms` are both known (§4.5.2).
                 pendingTool = { name: event.toolName, at: Date.now() };
+                const stagedPath = stagedWritePath(event.toolName, event.args);
+                if (stagedPath !== undefined)
+                    pendingTool.path = stagedPath;
                 run.phase = event.toolName === 'team_wait' ? 'waiting' : 'tool';
                 run.lastTool = event.toolName;
                 run.toolCalls += 1;
                 textTail = '';
                 run.activity = undefined; // prose is stale now
                 run.activityArgs = pickActivityArgs(event.args); // PICKED, not raw (P1-4)
-                noteFile(event.toolName, event.args);
                 break;
             case 'tool_execution_end': {
                 const endedAt = Date.now();
                 const startedAt = pendingTool?.at;
+                const writtenPath = pendingTool?.path;
                 pendingTool = null;
+                // The ledger records a write that HAPPENED: a refused (plan gate, --confirm,
+                // sandbox) or failed write is not a touched file, and the timeline below
+                // already reads `isError` for the same reason.
+                if (writtenPath !== undefined && event.isError !== true)
+                    noteFile(writtenPath);
                 // THE ARGUMENTS ARE GONE BY NOW, on purpose (P1-5): `activityArgs` is cleared a
                 // few lines below, and the timeline's text comes from `describeToolActivity` on
                 // the PICKED subset, so a `write_file` body can never reach the board.

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/App.js

@@ -55,6 +55,7 @@ import { advanceBudget, decideFollowThrough, emptyBudget, } from '../todo/follow
 // no policy. Imported beside the todo decision it shares one timer with.
 import { decideForcedDispatch, FORCED_NUDGE_NOTICE } from '../team/dispatch-gate.js';
 import { FORCED_NUDGE_GRACE_MS } from '../team/limits.js';
+import { priceTeamUsage } from '../team/model.js';
 import { useTerminalSize } from './layout/useTerminalSize.js';
 import { useHeightStore } from './use-height-store.js';
 import { useRenderGovernor } from './use-render-governor.js';
@@ -929,21 +930,34 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
                     // handler above records): this effect's dependency list never changes,
                     // so it closes over the `cfg` object of the render it mounted in, and
                     // `setModel` builds a NEW one.
-                    const live = controller.getConfig();
-                    // Every child runs the lead's own model (main-agent parity), so the
-                    // lead's live connection IS the tier that billed.
-                    const ref = { providerId: live.provider, modelId: live.model };
-                    // Unknown pricing contributes ZERO rather than a fabricated figure
-                    // (C-11 / RV-4); `/fast status` and the dispatch report say `unknown`.
-                    const costDelta = controller.isPricedModel(ref)
-                        ? computeCost(event.usage, controller.getModelInfoFor(ref).cost)
-                        : 0;
+                    //
+                    // PRICED AT THE MODEL THE CHILDREN RAN (`team.model`), through the same
+                    // resolution the dispatch report prices with: under `fast` / `profile` the
+                    // lead's table would over-report by up to an order of magnitude, and an
+                    // unpriced child model must read as unknown (ZERO here), not as the lead's.
+                    const costDelta = priceTeamUsage(controller.subagentModelResolution(), event.usage, {
+                        mainCost: controller.getModelInfo().cost,
+                        isPriced: (ref) => controller.isPricedModel(ref),
+                        costFor: (ref) => controller.getModelInfoFor(ref).cost,
+                    });
                     dispatch({ type: 'teamUsage', usage: event.usage, costDelta });
                     break;
                 }
-                case 'dispatch_end':
+                case 'dispatch_end': {
+                    // The supervisor's own calls never emit a usage event (they go through the fast
+                    // registry directly), so their spend reaches the readout HERE, once per
+                    // dispatch, at the fast tier's price - the same channel review spend uses.
+                    const spend = event.outcome.overseerUsage;
+                    if (spend !== undefined && (spend.inputTokens > 0 || spend.outputTokens > 0)) {
+                        const tier = controller.getFastStatus().tier;
+                        const costDelta = tier.ok && controller.isPricedModel(tier.ref)
+                            ? computeCost(spend, controller.getModelInfoFor(tier.ref).cost)
+                            : 0;
+                        dispatch({ type: 'fastUsage', usage: spend, costDelta });
+                    }
                     dispatch({ type: 'teamEnd', outcome: event.outcome });
                     break;
+                }
             }
         });
         return () => {

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;