bermudis-pi-goodies 0.13.0 → 0.13.2

package/README.md

@@ -23,7 +23,7 @@ extensions. One entry point, eleven independent features.
 After publishing the package to npm:
 
 ```bash
-pi install npm:bermudis-pi-goodies@0.13.0
+pi install npm:bermudis-pi-goodies@0.13.2
 ```
 
 Remove any old `bermudis-pi-goodies.ts` symlink before reloading Pi. Each
@@ -67,6 +67,44 @@ Failures degrade gracefully: the raw command stays visible as a heuristic
 hint, each distinct failure is logged once (naming the model), and repeated
 failures back off exponentially instead of hammering the provider.
 
+### Render-safety rules (why summaries only refresh running rows)
+
+These rules apply to pi's **regular** TUI mode (`tuiMode: "regular"`, the
+default — `TuiMainScreen`, the scrolling scrollback renderer). Pi also has a
+**fullscreen** mode (`TuiAltScreen`): no scrollback, a fixed `height`-line
+slice of the transcript diffed row-by-row, full clears only on first
+render/resize/image redraws. Neither escalation below exists there — a
+summary arrival re-rendering an old row is either invisible (scrolled off
+the slice) or a one-line rewrite. Check `~/.pi/agent/settings.json`
+`tuiMode` before reasoning about render escalation.
+
+Pi's regular-mode diff renderer answers two situations with
+`fullRender(true)` — clear screen, wipe scrollback, repaint everything —
+which reads as a full-screen flash:
+
+1. total rendered height dropping below the session high-water mark
+   (`clearOnShrink`), and
+2. any content change to a line **above the scrolled viewport**
+   (`firstChanged < prevViewportTop` — width-independent; on a long
+   transcript this is any row more than a screenful above the input box).
+
+clean-tui therefore follows two rules in its render paths:
+
+- **Height-neutral swaps:** text that may be replaced by a summary later is
+  capped at the same width as summaries (`BASH_BULLET_WIDTH`), so an
+  arriving summary never collapses a wrapped line (rule 1).
+- **Pending-only refresh:** when a summary lands, only rows whose tool is
+  still executing are re-rendered — those sit at the transcript tail, inside
+  the viewport, so the swap is a cheap differential update. Finished rows
+  (including replayed ones from before a `/resume`) keep the raw command
+  text for the rest of the session; the summary stays cached, and future
+  rows of the same command render it from the start (rule 2).
+
+To catch a flash red-handed, run `PI_DEBUG_REDRAW=1 pi`, reproduce, then
+`grep fullRender ~/.pi/agent/pi-debug.log` — every line is one screen wipe
+with its reason (`clearOnShrink`, `firstChanged < viewportTop`, resize, …).
+Note the log is append-only across sessions; check timestamps.
+
 ## Per-model thinking levels (retired in favor of Pi 0.84.3)
 
 This package previously shipped a `model-thinking` module with a `/levels`

package/clean-tui.ts

@@ -537,8 +537,19 @@ function requestSummary(cmd: string): void {
 }
 
 function invalidateRowsForCommand(cmd: string): void {
+  // Only rows that are STILL EXECUTING get refreshed when a summary lands.
+  // Executing rows sit at the transcript tail, inside pi's viewport, so the
+  // re-render is a cheap differential line update. Finished rows — including
+  // replayed ones from before a /resume — can sit far above the viewport on a
+  // long transcript, and pi's diff renderer answers any change above the
+  // viewport with fullRender(true): clear screen + scrollback wipe + full
+  // repaint, i.e. the "flicker while pi is working" seen on 0.11.x (fits any
+  // width; reproduced reasoning from tui-main-screen.js `firstChanged <
+  // prevViewportTop`). Finished rows simply keep the raw command text, which
+  // is more informative than the summary anyway; the summary stays cached
+  // and future rows of the same command render it from the start.
   for (const e of entries) {
-    if (e.args?.command === cmd) {
+    if (!e.result && e.args?.command === cmd) {
       const fn = invalidateById.get(e.toolCallId);
       if (fn) fn();
     }
@@ -621,15 +632,24 @@ function formatBashHeader(args: any, theme: any): string {
   if (isSummarizable(cmd) && summaryCache.has(cmd)) {
     return theme.fg("accent", summaryCache.get(cmd)!);
   }
-  return formatBashCommand(cmd, theme, 120);
+  // Cap must match BASH_BULLET_WIDTH, not exceed it: when a summary lands it
+  // replaces this text, and summaries are capped at SUMMARY_THRESHOLD_CHARS.
+  // A larger raw cap means the raw header can wrap where the summary won't,
+  // so the swap shrinks total line count mid-run — and pi-tui answers any
+  // drop below its high-water mark with a full clear-screen + scrollback wipe
+  // (clearOnShrink), i.e. a visible full-screen flash per summarized command
+  // (reproduced in panes narrower than ~124 cols; see clean-tui.test.ts
+  // "summary swap is height-neutral at 110 columns"). Equal caps keep the
+  // swap height-neutral wherever 80 columns fit.
+  return formatBashCommand(cmd, theme, BASH_BULLET_WIDTH);
 }
 
 function formatBashBullet(entry: Entry, theme: any): string {
   const cmd = entry.args.command || "...";
   const bullet = `${theme.fg("muted", "•")} `;
   // Failed calls get red text so a single failure is visible without
-  // poisoning the whole burst's background (see renderCall: box color now
-  // follows the leader's status only).
+  // poisoning the whole burst's background (see renderCall: the grouped box
+  // never takes the error color, whichever call failed).
   const accent = (s: string) => theme.fg(entry.isError ? "error" : "accent", s);
   if (isSummarizable(cmd) && summaryCache.has(cmd)) {
     return `  ${bullet}${accent(summaryCache.get(cmd)!)}`;
@@ -875,12 +895,17 @@ export default function cleanTui(pi: ExtensionAPI): void {
       const isGrouped = burst && burst.entries.length > 1;
       const isLeader =
         isGrouped && burst.entries[0].toolCallId === ctx.toolCallId;
-      // Box color follows the leader's own status. Aggregating any-pending/
-      // any-error over the whole burst paints 37 rows red for one failure;
-      // per-entry failures are marked on their own bullet instead
-      // (formatBashBullet).
-      const pending = !entry.result;
-      const isError = !!entry.isError;
+      // The burst box is shared by every call in the group, so its background
+      // never takes the error color — a failure (the leader included) is
+      // marked on its own bullet instead (formatBashBullet). "Follow the
+      // leader's status" (b80a14d) still painted the whole block red whenever
+      // the first call itself was the one that failed. Pending does
+      // aggregate: the box stays in its running state until every call in
+      // the burst has landed.
+      const pending = isGrouped
+        ? burst.entries.some((e) => !e.result)
+        : !entry.result;
+      const isError = isGrouped ? false : !!entry.isError;
 
       if (isGrouped && !isLeader) {
         // Refresh the leader's header/count. Single hop: a leader's renderCall

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bermudis-pi-goodies",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bermudi/agent-extensions.git",