@aragon-agent/cli 0.6.37 → 0.6.38

package/dist/commands/perf.d.ts

@@ -157,6 +157,12 @@ export interface ScrollbackPerf {
     elidedEntries: number;
     guardHits: number;
     guardHitsOutsideResize: number;
+    /**
+     * Frames taller than the screen, drawn after giving way at their TOP (I-B17). They are
+     * no longer swallowed, so `guardHits` stopped being the whole story: a region that
+     * outgrew its terminal shows up here instead of there.
+     */
+    tallFramesTrimmed: number;
     clippedRows: number;
     fallbacks: number;
     resizes: number;
@@ -184,7 +190,7 @@ export interface ScrollbackPerf {
     anchorTop: number;
     /** Rows this session pushed into the terminal's own scrollback. */
     anchorScrollRows: number;
-    /** Times the geometry was dropped on purpose (column change, shrink, geometry lost). */
+    /** Times the geometry was dropped on purpose (column change, nothing left to pin). */
     anchorResets: number;
     /** Measurements accepted after the first: the re-probe count, not the resize count. */
     anchorReprobes: number;

package/dist/commands/perf.js

@@ -86,8 +86,8 @@ function formatScrollbackLine() {
             `diff ${stats.framesDiff}, full ${stats.framesFull}, repaint ${stats.repaints}  -  ` +
             `static rows ${stats.staticRowsWritten}  -  elided ${stats.elidedEntries}  -  ` +
             `guardHits ${stats.guardHits} (outside resize ${stats.guardHitsOutsideResize})  -  ` +
-            `clippedRows ${stats.clippedRows}  -  fallbacks ${stats.fallbacks}  -  ` +
-            `resizes ${stats.resizes}`,
+            `trimmed ${stats.tallFramesTrimmed}  -  clippedRows ${stats.clippedRows}  -  ` +
+            `fallbacks ${stats.fallbacks}  -  resizes ${stats.resizes}`,
     ];
 }
 function mb(bytes) {

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

@@ -78,8 +78,9 @@ export declare function screenCapacity(rows: number | undefined): number;
 export declare function clampSpaceBelow(spaceBelow: number, rows: number | undefined): number;
 /**
  * A terminal that grew adds rows BELOW the cursor, so the capacity grows by the
- * exact difference (D6). Shrinking is NOT handled here: it re-measures instead of
- * guessing (D5), so a smaller value would only hide a lost measurement.
+ * exact difference (D6). Shrinking is NOT handled here either: the writer keeps the
+ * rows the screen still has and re-pins them (I-B17) instead of guessing a smaller
+ * value, which would only hide a lost measurement (D5).
  */
 export declare function applyResizeGrowth(capacity: number, rowsPrev: number, rowsNow: number): number;
 /**

package/dist/ui/scrollback/canvas.js

@@ -48,8 +48,9 @@ export function clampSpaceBelow(spaceBelow, rows) {
 }
 /**
  * A terminal that grew adds rows BELOW the cursor, so the capacity grows by the
- * exact difference (D6). Shrinking is NOT handled here: it re-measures instead of
- * guessing (D5), so a smaller value would only hide a lost measurement.
+ * exact difference (D6). Shrinking is NOT handled here either: the writer keeps the
+ * rows the screen still has and re-pins them (I-B17) instead of guessing a smaller
+ * value, which would only hide a lost measurement (D5).
  */
 export function applyResizeGrowth(capacity, rowsPrev, rowsNow) {
     // No capacity to grow: a broken number must not become a canvas by arithmetic.

package/dist/ui/scrollback/scrollback-writer.d.ts

@@ -54,6 +54,16 @@
  *  - I-B15 · every batch starts by reconciling `top + capacity` with the live
  *    `rows - 1` (a resize event can arrive one frame late), and a column change
  *    resets before it writes.
+ *  - I-B17 · a SHRINK re-pins the canvas, it never drops it. The canvas keeps
+ *    `min(canvasRows, screenCapacity(rows))` rows — the screen keeps the rows nearest
+ *    the parked cursor, so the survivors are its SUFFIX — and its top moves down to
+ *    `capacity - kept`, which preserves LB-3. Dropping the cache instead made the next
+ *    batch a SEED, and a seed assumes nothing is below the cursor
+ *    (`writer-shapes.ts:60-64`); after a shrink that is false, so the batch overflowed
+ *    the screen and the previous frame — status row included — went into the
+ *    scrollback: the same row in two places. For the same reason a frame TALLER than
+ *    the screen gives way at its TOP instead of being swallowed whole: the composer
+ *    and the status line are the two rows a human is interacting with.
  *  - I-A9 · the writer never writes a probe byte; it only asks the host, which owns
  *    deferral, coalescing and the death switch.
  */
@@ -102,6 +112,8 @@ export interface ScrollbackWriterStats {
     guardHits: number;
     /** The subset NOT explained by a recent resize: the real defect signal. */
     guardHitsOutsideResize: number;
+    /** Frames taller than the screen, drawn after giving way at their TOP (I-B17). */
+    tallFramesTrimmed: number;
     clippedRows: number;
     elidedEntries: number;
     resizes: number;
@@ -116,7 +128,7 @@ export interface ScrollbackWriterStats {
     anchorGapRows: number;
     /** Rows this session pushed into the scrollback (the "is it scrolling" signal). */
     anchorScrollRows: number;
-    /** Times the geometry was dropped on purpose (column change, shrink, gap lost). */
+    /** Times the geometry was dropped on purpose (column change, nothing left to pin). */
     anchorResets: number;
     /** Measurements accepted AFTER the first one — the re-probe count (not resize events). */
     anchorReprobes: number;

package/dist/ui/scrollback/scrollback-writer.js

@@ -54,6 +54,16 @@
  *  - I-B15 · every batch starts by reconciling `top + capacity` with the live
  *    `rows - 1` (a resize event can arrive one frame late), and a column change
  *    resets before it writes.
+ *  - I-B17 · a SHRINK re-pins the canvas, it never drops it. The canvas keeps
+ *    `min(canvasRows, screenCapacity(rows))` rows — the screen keeps the rows nearest
+ *    the parked cursor, so the survivors are its SUFFIX — and its top moves down to
+ *    `capacity - kept`, which preserves LB-3. Dropping the cache instead made the next
+ *    batch a SEED, and a seed assumes nothing is below the cursor
+ *    (`writer-shapes.ts:60-64`); after a shrink that is false, so the batch overflowed
+ *    the screen and the previous frame — status row included — went into the
+ *    scrollback: the same row in two places. For the same reason a frame TALLER than
+ *    the screen gives way at its TOP instead of being swallowed whole: the composer
+ *    and the status line are the two rows a human is interacting with.
  *  - I-A9 · the writer never writes a probe byte; it only asks the host, which owns
  *    deferral, coalescing and the death switch.
  */
@@ -110,6 +120,7 @@ export function createScrollbackWriter(o) {
         fallbacks: 0, guardHits: 0, guardHitsOutsideResize: 0, clippedRows: 0, elidedEntries: 0,
         resizes: 0, repaints: 0, anchorSource: 'none', anchorCanvasRows: 0, anchorHeldRows: 0,
         anchorGapRows: 0, anchorScrollRows: 0, anchorResets: 0, anchorReprobes: 0,
+        tallFramesTrimmed: 0,
     };
     const liveCols = () => {
         const cols = o.cols();
@@ -205,6 +216,68 @@ export function createScrollbackWriter(o) {
         stats.bytesWritten += bytes.length;
         return bytes;
     };
+    /**
+     * Drop from the canvas cache the rows a shorter screen no longer has (I-B17).
+     *
+     * A shrink deletes rows ABOVE the parked cursor, so what survives is the canvas's
+     * SUFFIX: the gap goes first, then the oldest content rows. Trimming the cache is
+     * what lets the next batch be a DIFF against what is really on screen. Dropping the
+     * cache (`reset()`) made it a SEED instead, and a seed assumes nothing is below the
+     * cursor (`writer-shapes.ts:60-64`) — after a shrink that is false, so the batch
+     * overflowed and the previous frame, status row included, was pushed into the
+     * scrollback instead of being erased.
+     */
+    const trimCanvasCache = (capacity) => {
+        const lost = canvasRows - capacity;
+        if (lost <= 0)
+            return;
+        const lostFromGap = Math.min(lost, gapRows);
+        gapRows -= lostFromGap;
+        held = held.slice(Math.min(lost - lostFromGap, held.length));
+        prev = prev === null ? null : prev.slice(lost);
+        canvasRows = capacity;
+        // A drastic shrink can eat into the region itself (E2). `frameRows` is the height
+        // the next diff is aligned against, so it may never claim rows that are gone.
+        frameRows = Math.min(frameRows, Math.max(0, capacity - gapRows - held.length));
+    };
+    /**
+     * Re-pin a canvas the terminal just got SHORTER, instead of dropping it (I-B17).
+     *
+     * `top` moves DOWN (`capacity - kept`) because the rows the screen lost were the ones
+     * above the cursor: the parked row is still `rows - 1`, so LB-3 holds for the same
+     * reason it always did.
+     *
+     * `capacity < 1` keeps the old answer (E3): a terminal with no row above the parked one
+     * has no canvas left to address, and re-measuring is then the only honest move. Columns
+     * are deliberately NOT handled here: a width change re-flows the rows themselves, so
+     * the cache describes nothing and still resets (D5 / E4).
+     */
+    const repinShrunk = (rows) => {
+        const room = screenCapacity(rows);
+        // Only a MEASURED canvas may be re-pinned. `unknown` means nothing ever established
+        // that the cursor sits on the last row, and the arithmetic below starts from exactly
+        // that assumption; the append path erases nothing, so it stays the honest answer and
+        // keeps its bytes exactly as they were (I-B7).
+        const capacity = anchor.kind === 'pinned' ? Math.min(canvasRows, room) : 0;
+        if (capacity < 1) {
+            reset();
+            return;
+        }
+        trimCanvasCache(capacity);
+        anchor = { kind: 'pinned', top: room - capacity, capacity };
+        seedDownToTop = 0;
+        lastRows = rows;
+        // The re-draw this answers is the host's, deferred and coalesced (P0-2 / P0-3):
+        // `anchorDirty` is what lets a `repaint()` land while the feed is idle.
+        anchorDirty = true;
+        publishAnchorStats();
+        // Re-measure anyway (I-B14). Keeping the canvas is a bet that the parked row is still
+        // `rows - 1`, and only a measurement can confirm the terminal agrees; dropping the
+        // probe here would leave a wrong geometry with nothing left to correct it. A drag
+        // that fires dozens of resize events still costs one probe: the host coalesces them
+        // (P1-3 / E6), and `anchorReprobes` counts measurements, never requests.
+        requestProbe();
+    };
     /**
      * Bring `top + capacity` back in line with the live `rows - 1` BEFORE the batch
      * reads either of them (§6.11, [P0-2]).
@@ -235,7 +308,10 @@ export function createScrollbackWriter(o) {
             lastRows = rows;
             return;
         }
-        reset();
+        // The `resize` event can arrive a whole frame late, and on a terminal that never
+        // answers CPR it never arrives at all: this batch is then the last chance to keep
+        // the canvas instead of dropping it (I-B17, W6).
+        repinShrunk(rows);
     };
     const afterCanvasBatch = (layout, heldNext, frame, raw, cols, rows) => {
         prev = [...new Array(layout.gap).fill(''), ...heldNext, ...frame];
@@ -402,6 +478,23 @@ export function createScrollbackWriter(o) {
         canvasRows = lines.length;
         gapRows = 0;
     };
+    /**
+     * Give way at the TOP of a frame taller than the screen (I-B17 / W4).
+     *
+     * Such a frame cannot be addressed as ONE block, and swallowing it left the PREVIOUS
+     * frame on screen — which is how the status row came to be printed twice. The region's
+     * last rows are the composer and the status line, the two rows a human is interacting
+     * with, so the oldest rows go first and the next (shorter) frame restores the rest.
+     *
+     * BOTH entry points that draw a frame need this: `repaint()` replays the frame it kept,
+     * and that frame can predate a shrink that has since made the screen shorter.
+     */
+    const giveWayAtTop = (lines, rows) => {
+        if (lines.length + 1 <= rows)
+            return lines;
+        stats.tallFramesTrimmed += 1;
+        return lines.slice(lines.length - (rows - 1));
+    };
     const transform = (chunk) => {
         if (finalized)
             return '';
@@ -419,12 +512,7 @@ export function createScrollbackWriter(o) {
         }
         if (lines === null)
             return countFallback(!firstChunk);
-        if (lines.length + 1 > rows) {
-            // Unreachable by construction (I-S1); never erase on a guess.
-            reset();
-            return '';
-        }
-        return assemble(lines, rows, liveCols(), 'frame');
+        return assemble(giveWayAtTop(lines, rows), rows, liveCols(), 'frame');
     };
     const repaint = () => {
         repaintQueued = false;
@@ -437,7 +525,10 @@ export function createScrollbackWriter(o) {
         const rows = liveRows();
         if (rows === undefined || rows < 2)
             return '';
-        return assemble(prevRawFrame, rows, liveCols(), 'repaint');
+        // The kept frame may predate a shrink, so a replay gets the same top give-way as a
+        // live frame (W4): drawing it whole would overflow the new screen and push this
+        // session's own rows into the scrollback through the repaint door.
+        return assemble(giveWayAtTop(prevRawFrame, rows), rows, liveCols(), 'repaint');
     };
     const finalize = (summary) => {
         if (finalized)
@@ -478,8 +569,10 @@ export function createScrollbackWriter(o) {
             }
             if (rowsNow !== undefined && lastRows !== undefined) {
                 if (rowsNow < lastRows) {
-                    // The terminal deleted rows; they are gone and must not be redrawn.
-                    reset();
+                    // I-B17: the screen kept the rows nearest the cursor, so re-pin the canvas onto
+                    // them instead of dropping it. A reset made the next batch a seed over a screen
+                    // that is not empty, which is what left the old status row in the scrollback.
+                    repinShrunk(rowsNow);
                     return;
                 }
                 if (anchor.kind === 'pinned') {
@@ -503,6 +596,12 @@ export function createScrollbackWriter(o) {
                 return;
             const rows = liveRows();
             const capacity = screenCapacity(rows);
+            // I-B17: a measurement can arrive after the terminal got shorter without ever
+            // announcing it (`rows` is read live, the `resize` event is optional). The cache
+            // must then stop describing rows the screen has already dropped, or the reach
+            // below would hand the next batch an erase distance longer than the canvas left.
+            if (rows !== undefined)
+                trimCanvasCache(capacity);
             // I-B14: the report is "rows BELOW the cursor", and the canvas also still owns
             // `canvasRows` rows ABOVE it, so the reachable height is their sum. Keeping only
             // the first term collapses the canvas onto the parked row, and the next batch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.6.37",
+  "version": "0.6.38",
   "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.49",
+    "@aragon-agent/core": "^0.2.50",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",