@astralyn/pi 0.84.2 → 0.84.3

package/docs/bundled/extensions/subagent.md

@@ -85,7 +85,7 @@ They apply only to future subagent runs and never change the parent session's `/
 - Parent abort, `/reload`, `/new`, `/resume`, `/fork`, and session shutdown abort active child sessions. Queued workers do not survive the call.
 - Parallel worker failures do not cancel other independent workers.
 - Transient provider errors auto-retry: the worker session retries retryable stream errors with backoff (visible as a live `Retrying (n/m) in Xs…` countdown), and a failure that produced no work (for example a preflight auth throw) is rerun at the task level up to two more times. Provider and task retries share one absolute-deadline state; at zero it reads `Retrying now…`, and parent abort/session shutdown interrupts backoff immediately. Runs with partial work behind them are never rerun.
-- Progress is rendered in Pi's native tool transcript. While a call is running, the native shell rebuilds the Subagent renderer once per second, independently of worker output and the main Working spinner. Silent single and parallel runs therefore keep advancing their own elapsed clocks in collapsed and expanded views, and queued retries keep counting down; the generic shell `Running…` row stays hidden to avoid duplicate progress. Once settled, the final duration is fixed and refresh stops.
+- Progress is rendered in Pi's native tool transcript. While a call is running, the Subagent renderer re-schedules its own repaint once per second, independently of worker output and the main Working spinner. Silent single and parallel runs therefore keep advancing their own elapsed clocks in collapsed and expanded views, and queued retries keep counting down. Once settled, the final duration is fixed and refresh stops.
 - The collapsed view stays lean in both phases: while running, one bounded intent line (for example `Verifying changes`) carries tool uses, the `ctx:` context watermark, cost, and elapsed time above the current tool marked with `›` and the live output tail; once settled, the sentence-aware result excerpt is followed by a single metrics line (`tok · $ · duration`, plus tool uses and `ctx:` for single runs) and the configured expand hint. Live lines never quote token totals — mid-run totals are cache-inflated. The call-level status dot belongs to the tool shell; run and activity rows only use `›`, `○`, `✓`, `×`, and `■`, and parallel run rows carry stable dim ordinals that match the expanded section numbers. `Ctrl+O` expands each run into a report cover sheet: a status line, a metrics line, a fixed two-line `Prompt` preview (`… continues, N more lines`, honest about the 1KB bound), an `Activity · last n of N` digest whose successful rows are quiet aligned one-liners, a `Working` tail while streaming, and the full `Report` (or `Error`, with `Report · partial` for salvaged output) rendered as Markdown. Expanded batches start with a numbered contents list whose numbers match the `── N · ✓ Agent` section headers.
 - Failed and aborted batch runs place their bounded reason on a separate error-colored line below the run headline instead of cutting it into the status row. Reasons are capped at 200 characters and keep their hanging indent when wrapped; successful settled excerpts prefer complete leading sentences within their 96-character budget. Rounded durations switch to minute form at 60 seconds without producing `1m 60s`.
 - Full child transcripts are not stored separately. Bounded run details remain in the parent tool result, so completed calls restore naturally in the parent session tree.

package/docs/bundled/tool-presentation.md

@@ -12,9 +12,9 @@ The `@astralyn/pi` package uses Pi's native tool transcript presentation rather
 │ final result line
 ```
 
-The dim result rail continues through every visual line; an empty output line renders as a bare `│`. Calls keep their status in the leading dot: warning while pending or running, green after success, and red after failure. For default-shell tools that are still running after two seconds, the shell adds a live result row such as `Running… (2.1s)` and removes it when the call settles. Tools with purpose-built progress UI can opt out through `rendersOwnProgress`; tools using `renderShell: "self"` continue to own their entire presentation.
+The dim result rail continues through every visual line; an empty output line renders as a bare `│`. Calls keep their status in the leading dot: warning while pending or running, green after success, and red after failure. For bash commands that are still running after two seconds, the shell adds a live result row such as `Running… (2.1s)` and removes it when the call settles. Other tools with live progress render it themselves; tools using `renderShell: "self"` continue to own their entire presentation.
 
-Time-driven renderers use `renderRefreshIntervalMs` separately from `rendersOwnProgress`. The former periodically rebuilds call/result components only during the partial lifecycle; the latter only hides the generic `Running…` row. The native shell shares the shortest needed interval, constrains explicit intervals to 250ms–60s, and stops refreshing on final result, abort, disposal, session replacement, chat rebuild, or shutdown. Renderers compute elapsed/countdown values from absolute timestamps or deadlines, so a delayed repaint never changes the underlying wall-clock meaning.
+Time-driven renderers schedule their own repaints: while a result is partial they arm a timer in renderer state and call the render context's `invalidate()`, clearing the timer on the first settled render. Renderers compute elapsed/countdown values from absolute timestamps or deadlines, so a delayed repaint never changes the underlying wall-clock meaning.
 
 ## Implementation boundary
 

package/docs/extensions.md

@@ -1996,10 +1996,6 @@ pi.registerTool({
   },
 
   // Optional: Custom rendering
-  // rendersOwnProgress suppresses only the shell's generic Running… row.
-  rendersOwnProgress: true,
-  // While the result is partial, rebuild renderCall/renderResult every second.
-  renderRefreshIntervalMs: 1000,
   renderCall(args, theme, context) { ... },
   renderResult(result, options, theme, context) { ... },
 });
@@ -2253,12 +2249,7 @@ By default, tool output is wrapped in Pi's native call/result shell, which owns
 
 Set `renderShell: "self"` when the tool should render its own shell instead of using the native shell. This is useful for tools that need complete control over framing or background behavior, for example large previews that must stay visually stable after the tool settles.
 
-Two independent options control live presentation:
-
-- `rendersOwnProgress: true` suppresses only the native shell's generic `Running… (Ns)` row. It does not schedule renderer updates.
-- `renderRefreshIntervalMs` periodically rebuilds `renderCall` and `renderResult` while the tool result is partial. It does not suppress generic progress.
-
-Use both when a tool renders its own elapsed time, retry countdown, or similar progress UI. Refresh intervals are rounded and constrained to 250–60,000ms. The shell may rebuild sooner when another native concern needs it, so the configured interval is the maximum refresh gap rather than an exclusive cadence. Refresh stops when the result settles or the row is disposed.
+For live progress UI (elapsed time, retry countdowns), schedule repaints from the renderer itself: store a timer handle in `context.state`, arm a `setTimeout` that calls `context.invalidate()` while `options.isPartial` is true, and clear it on the first settled render. `context.invalidate()` is a no-op after the row is disposed, so a trailing timeout is harmless.
 
 Derive displayed time from an absolute timestamp or deadline (`Date.now()`), not by decrementing a counter on every refresh. A refresh is only a repaint opportunity; event-loop stalls and machine sleep must not extend a wall-clock timeout.
 
@@ -2368,8 +2359,7 @@ Custom editors and `ctx.ui.custom()` components receive `keybindings: Keybinding
 - Use `Text` with padding `(0, 0)`. The native shell handles padding.
 - Use `\n` for multi-line content.
 - Handle `isPartial` for streaming progress.
-- Use `renderRefreshIntervalMs` only for values that must change without a new partial result, and compute those values from absolute time.
-- Set `rendersOwnProgress` separately when the renderer replaces the native `Running…` row.
+- For time-driven renderers, self-schedule repaints with `context.state` timers and `context.invalidate()`, and compute displayed values from absolute time.
 - Support `expanded` for detail on demand.
 - Keep default view compact.
 - Read `context.args` in `renderResult` instead of copying args into `context.state`.
@@ -2542,17 +2532,10 @@ const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);
 
 // Options can carry a muted description line, so the action and its
 // trade-off can be scanned separately. select() still resolves to the label.
-const action = await ctx.ui.select(
-  "Approve?",
-  [
-    { label: "Start executing", description: "keep full context" },
-    { label: "Compact, then execute", description: "best for long tasks" },
-  ],
-  {
-    subtitle: "Context now 29% full",   // muted line under the title
-    cancelHint: "go back",              // Describe what Esc actually does
-  },
-);
+const action = await ctx.ui.select("Approve?", [
+  { label: "Start executing", description: "keep full context" },
+  { label: "Compact, then execute", description: "best for long tasks" },
+]);
 
 // Confirm dialog
 const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");

package/docs/settings.md

@@ -65,7 +65,7 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
 | `outputPad` | number | `1` | Horizontal padding for user messages, assistant messages, and thinking (0 or 1) |
 | `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) |
 | `showHardwareCursor` | boolean | `false` | Show the terminal cursor while TUI positions it for IME support |
-| `tuiMode` | string | `"regular"` | Interactive TUI mode: `"regular"` or experimental `"fullscreen"`. Changes from `/settings` apply immediately; `--tui-mode` overrides this setting at startup |
+| `tuiMode` | string | `"fullscreen"` | Interactive TUI mode: `"fullscreen"` or `"regular"`. Changes from `/settings` apply immediately; `--tui-mode` overrides this setting at startup |
 | `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"` shows it temporarily while scrolling, `"always"` reserves the rightmost column and keeps it visible, and `"hidden"` hides it. Has no effect in regular TUI mode |
 
 For VS Code, include `--wait` so pi resumes after the editor exits:

package/docs/usage.md

@@ -233,7 +233,7 @@ pi --no-extensions -e ./my-extension.ts
 |--------|-------------|
 | `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
 | `--append-system-prompt <text>` | Append to system prompt |
-| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
+| `--tui-mode <mode>` | TUI mode: `fullscreen` (default) or `regular` |
 | `--verbose` | Force verbose startup |
 | `-a`, `--approve` | Trust project-local files for this run |
 | `-na`, `--no-approve` | Ignore project-local files for this run |

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
 	"name": "@astralyn/pi",
-	"version": "0.84.2",
+	"version": "0.84.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@astralyn/pi",
-			"version": "0.84.2",
+			"version": "0.84.3",
 			"license": "MIT",
 			"dependencies": {
 				"@earendil-works/pi-agent-core": "0.84.1",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@astralyn/pi",
-	"version": "0.84.2",
+	"version": "0.84.3",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {

package/dist/utils/coalescing-terminal.d.ts

@@ -1,132 +0,0 @@
-import { ProcessTerminal } from "@earendil-works/pi-tui";
-/**
- * ProcessTerminal that (1) coalesces every write issued within one synchronous
- * task into a single stdout write and (2) keeps content-driven full redraws
- * from destroying the terminal's scrollback.
- *
- * Coalescing: pi-tui emits each render pass as several separate stdout
- * writes: the frame wrapped in synchronized output (CSI ?2026h/l), then a
- * relative cursor move that parks the hardware cursor at the focused
- * component's caret for IME composition, then a cursor visibility toggle.
- * Terminals that anchor the IME candidate window to the hardware cursor
- * (Windows Terminal and other ConPTY hosts, WezTerm) can process the frame
- * write before the reposition write arrives, briefly leaving the cursor at
- * the end of the last repainted line. With an IME active this makes the
- * candidate window jump between the caret and the right edge of the input
- * line on every keystroke. Merging the writes makes each frame atomic, so the
- * only cursor position a terminal can observe is the final one.
- *
- * Scrollback preservation: pi-tui's fullRender(clear) opens with
- * `2J H 3J`, wiping the terminal's scrollback, and then replays the entire
- * transcript. During streaming, content-driven triggers (a line changing
- * above the viewport during markdown reflow) fire this routinely, which — in
- * terminals that clamp the scroll offset when scrollback vanishes, notably
- * Windows Terminal — yanks a scrolled-up reader to the top of the buffer on
- * every reflow (upstream #6502, #5576, #6050; rejected upstream fix #4204).
- *
- * Preservation is therefore windowed, not permanent: the host marks agent
- * runs via setAgentRunActive, which turns preservation on at run start and
- * keeps it on until the user's next input after the run settles, since they
- * may still be scrolled up reading. The input half of the window is observed
- * directly on this terminal's own input path, so it needs no TUI listener
- * and survives renderer switches (which reuse this terminal) untouched. An
- * idle-session full redraw — Ctrl+O toggles, mode switches — passes through
- * with upstream's wipe-and-replay, whose result is byte-perfect: scrollback
- * becomes the clean new transcript. Mid-run user toggles can arm
- * passNextFullRedraw for the same clean replay on their own frame.
- *
- * While preservation is active, a matching frame is rewritten to repaint
- * without the wipe. With setViewportTopProvider wired, the rewrite knows
- * which transcript line the visible screen starts at, so a frame that grew
- * the transcript repaints the on-screen rows with the new content at those
- * same positions and then scrolls the extra lines in at the bottom row.
- * Each bottom-row newline pushes the top row — already repainted with the
- * correct new content — into scrollback, exactly like ordinary streaming
- * output, so scrollback ends up byte-equivalent to the upstream full replay
- * without ever clearing it. Without the provider, or when the transcript
- * shrank (lines cannot be pulled back out of scrollback), the rewrite falls
- * back to overwriting the visible screen in place with the bottom
- * viewport-height rows, at the cost of a stale seam above the screen. ED 2
- * is avoided entirely in rewritten frames because conhost/Windows Terminal
- * implement it by scrolling the screen contents into scrollback rather than
- * erasing in place.
- *
- * Width- and height-change redraws keep the upstream wipe because re-wrapped
- * content genuinely invalidates old scrollback, and frames containing kitty
- * graphics pass through untouched. A frame that does not match the expected
- * shape is passed through unchanged, so if upstream reshapes its render
- * output the wrapper degrades back to stock behavior.
- */
-export declare class CoalescingTerminal extends ProcessTerminal {
-    private pending;
-    private flushQueued;
-    private lastWriteColumns;
-    private lastWriteRows;
-    private viewportTopProvider;
-    private preserve;
-    private passArmed;
-    private agentRunActive;
-    private flushOnExit;
-    /**
-     * Enable or disable the scrollback-preserving rewrite. Preservation is
-     * only worth its imperfections (stale renderings above the screen, seams
-     * on shrink) while the transcript is mutating on its own and the reader
-     * may be scrolled up — i.e. during an agent run and until the user's next
-     * input after it settles. Outside that window every full redraw passes
-     * through with upstream's wipe-and-replay, whose result is byte-perfect:
-     * scrollback becomes the clean new transcript. Default: disabled.
-     * setAgentRunActive drives this for the normal agent-run window; this
-     * primitive remains for direct control in tests.
-     */
-    setScrollbackPreservation(enabled: boolean): void;
-    /**
-     * Open or close the agent-run half of the preservation window. Opening
-     * (agent_start) turns preservation on. Closing (agent_settled) leaves
-     * preservation on: trailing reflow frames may land after the run while
-     * the reader is still scrolled up. The window then closes on the user's
-     * next input, observed in start()'s input wrapper — once the user acts
-     * they are back at the bottom, and upstream's clean wipe-and-replay wins
-     * again until the next run.
-     */
-    setAgentRunActive(active: boolean): void;
-    /**
-     * Arm a one-shot exemption for an explicit user action (Ctrl+O tool
-     * expansion, thinking visibility) so its own full redraw keeps the
-     * upstream wipe-and-replay even while preservation is active mid-run.
-     * The user just pressed a key, so they are interacting at the bottom;
-     * a clean replay beats preservation's stale-seam trade-offs there. The
-     * flag is cleared by the next write so it cannot leak onto a later
-     * streaming redraw.
-     */
-    passNextFullRedraw(): void;
-    /**
-     * Wire the renderer's notion of which transcript line the visible screen
-     * currently starts at (pi-tui's `previousViewportTop`). Full-redraw frames
-     * that grew the transcript then scroll the new above-screen lines into
-     * scrollback instead of dropping them. The provider is read while the
-     * frame is being written, i.e. before the renderer updates its own
-     * bookkeeping for that frame; returning undefined falls back to the
-     * bottom-anchored in-place repaint.
-     */
-    setViewportTopProvider(provider: () => number | undefined): void;
-    constructor();
-    start(onInput: (data: string) => void, onResize: () => void): void;
-    write(data: string): void;
-    moveBy(lines: number): void;
-    hideCursor(): void;
-    showCursor(): void;
-    clearLine(): void;
-    clearFromCursor(): void;
-    clearScreen(): void;
-    stop(): void;
-    /**
-     * Rewrite a full-redraw frame (`?2026h 2J H 3J <lines> ?2026l`) so it
-     * repaints the screen without wiping scrollback. Anything that does not
-     * match this exact shape — including width-change redraws and frames
-     * touching kitty images — passes through unchanged.
-     */
-    private preserveScrollback;
-    private readViewportTop;
-    private flush;
-}
-//# sourceMappingURL=coalescing-terminal.d.ts.map

package/dist/utils/coalescing-terminal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"coalescing-terminal.d.ts","sourceRoot":"","sources":["../../src/utils/coalescing-terminal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AASzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,qBAAa,kBAAmB,SAAQ,eAAe;IACtD,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,mBAAmB,CAAyC;IACpE,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,WAAW,CAAsB;IAEzC;;;;;;;;;;OAUG;IACH,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIjD;;;;;;;;OAQG;IACH,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAKxC;;;;;;;;OAQG;IACH,kBAAkB,IAAI,IAAI;IAI1B;;;;;;;;OAQG;IACH,sBAAsB,CAAC,QAAQ,EAAE,MAAM,MAAM,GAAG,SAAS,GAAG,IAAI;;IAWvD,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAoBlE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAUzB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ3B,UAAU,IAAI,IAAI;IAIlB,UAAU,IAAI,IAAI;IAIlB,SAAS,IAAI,IAAI;IAIjB,eAAe,IAAI,IAAI;IAIvB,WAAW,IAAI,IAAI;IAInB,IAAI,IAAI,IAAI;IAQrB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IA2E1B,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,KAAK;CASb"}

package/dist/utils/coalescing-terminal.js

@@ -1,292 +0,0 @@
-import { ProcessTerminal } from "@earendil-works/pi-tui";
-const SYNC_START = "\x1b[?2026h";
-const SYNC_END = "\x1b[?2026l";
-/** Clear screen, home, clear scrollback — pi-tui's fullRender(clear) preamble. */
-const CLEAR_WITH_SCROLLBACK = "\x1b[2J\x1b[H\x1b[3J";
-/** Kitty graphics APC prefix; frames touching images interleave cursor moves. */
-const KITTY_APC_PREFIX = "\x1b_G";
-/**
- * ProcessTerminal that (1) coalesces every write issued within one synchronous
- * task into a single stdout write and (2) keeps content-driven full redraws
- * from destroying the terminal's scrollback.
- *
- * Coalescing: pi-tui emits each render pass as several separate stdout
- * writes: the frame wrapped in synchronized output (CSI ?2026h/l), then a
- * relative cursor move that parks the hardware cursor at the focused
- * component's caret for IME composition, then a cursor visibility toggle.
- * Terminals that anchor the IME candidate window to the hardware cursor
- * (Windows Terminal and other ConPTY hosts, WezTerm) can process the frame
- * write before the reposition write arrives, briefly leaving the cursor at
- * the end of the last repainted line. With an IME active this makes the
- * candidate window jump between the caret and the right edge of the input
- * line on every keystroke. Merging the writes makes each frame atomic, so the
- * only cursor position a terminal can observe is the final one.
- *
- * Scrollback preservation: pi-tui's fullRender(clear) opens with
- * `2J H 3J`, wiping the terminal's scrollback, and then replays the entire
- * transcript. During streaming, content-driven triggers (a line changing
- * above the viewport during markdown reflow) fire this routinely, which — in
- * terminals that clamp the scroll offset when scrollback vanishes, notably
- * Windows Terminal — yanks a scrolled-up reader to the top of the buffer on
- * every reflow (upstream #6502, #5576, #6050; rejected upstream fix #4204).
- *
- * Preservation is therefore windowed, not permanent: the host marks agent
- * runs via setAgentRunActive, which turns preservation on at run start and
- * keeps it on until the user's next input after the run settles, since they
- * may still be scrolled up reading. The input half of the window is observed
- * directly on this terminal's own input path, so it needs no TUI listener
- * and survives renderer switches (which reuse this terminal) untouched. An
- * idle-session full redraw — Ctrl+O toggles, mode switches — passes through
- * with upstream's wipe-and-replay, whose result is byte-perfect: scrollback
- * becomes the clean new transcript. Mid-run user toggles can arm
- * passNextFullRedraw for the same clean replay on their own frame.
- *
- * While preservation is active, a matching frame is rewritten to repaint
- * without the wipe. With setViewportTopProvider wired, the rewrite knows
- * which transcript line the visible screen starts at, so a frame that grew
- * the transcript repaints the on-screen rows with the new content at those
- * same positions and then scrolls the extra lines in at the bottom row.
- * Each bottom-row newline pushes the top row — already repainted with the
- * correct new content — into scrollback, exactly like ordinary streaming
- * output, so scrollback ends up byte-equivalent to the upstream full replay
- * without ever clearing it. Without the provider, or when the transcript
- * shrank (lines cannot be pulled back out of scrollback), the rewrite falls
- * back to overwriting the visible screen in place with the bottom
- * viewport-height rows, at the cost of a stale seam above the screen. ED 2
- * is avoided entirely in rewritten frames because conhost/Windows Terminal
- * implement it by scrolling the screen contents into scrollback rather than
- * erasing in place.
- *
- * Width- and height-change redraws keep the upstream wipe because re-wrapped
- * content genuinely invalidates old scrollback, and frames containing kitty
- * graphics pass through untouched. A frame that does not match the expected
- * shape is passed through unchanged, so if upstream reshapes its render
- * output the wrapper degrades back to stock behavior.
- */
-export class CoalescingTerminal extends ProcessTerminal {
-    /**
-     * Enable or disable the scrollback-preserving rewrite. Preservation is
-     * only worth its imperfections (stale renderings above the screen, seams
-     * on shrink) while the transcript is mutating on its own and the reader
-     * may be scrolled up — i.e. during an agent run and until the user's next
-     * input after it settles. Outside that window every full redraw passes
-     * through with upstream's wipe-and-replay, whose result is byte-perfect:
-     * scrollback becomes the clean new transcript. Default: disabled.
-     * setAgentRunActive drives this for the normal agent-run window; this
-     * primitive remains for direct control in tests.
-     */
-    setScrollbackPreservation(enabled) {
-        this.preserve = enabled;
-    }
-    /**
-     * Open or close the agent-run half of the preservation window. Opening
-     * (agent_start) turns preservation on. Closing (agent_settled) leaves
-     * preservation on: trailing reflow frames may land after the run while
-     * the reader is still scrolled up. The window then closes on the user's
-     * next input, observed in start()'s input wrapper — once the user acts
-     * they are back at the bottom, and upstream's clean wipe-and-replay wins
-     * again until the next run.
-     */
-    setAgentRunActive(active) {
-        this.agentRunActive = active;
-        if (active)
-            this.preserve = true;
-    }
-    /**
-     * Arm a one-shot exemption for an explicit user action (Ctrl+O tool
-     * expansion, thinking visibility) so its own full redraw keeps the
-     * upstream wipe-and-replay even while preservation is active mid-run.
-     * The user just pressed a key, so they are interacting at the bottom;
-     * a clean replay beats preservation's stale-seam trade-offs there. The
-     * flag is cleared by the next write so it cannot leak onto a later
-     * streaming redraw.
-     */
-    passNextFullRedraw() {
-        this.passArmed = true;
-    }
-    /**
-     * Wire the renderer's notion of which transcript line the visible screen
-     * currently starts at (pi-tui's `previousViewportTop`). Full-redraw frames
-     * that grew the transcript then scroll the new above-screen lines into
-     * scrollback instead of dropping them. The provider is read while the
-     * frame is being written, i.e. before the renderer updates its own
-     * bookkeeping for that frame; returning undefined falls back to the
-     * bottom-anchored in-place repaint.
-     */
-    setViewportTopProvider(provider) {
-        this.viewportTopProvider = provider;
-    }
-    constructor() {
-        super();
-        this.pending = "";
-        this.flushQueued = false;
-        this.preserve = false;
-        this.passArmed = false;
-        this.agentRunActive = false;
-        this.flushOnExit = () => this.flush();
-        // A synchronous process.exit() before the queued microtask runs would
-        // otherwise drop the final frame.
-        process.on("exit", this.flushOnExit);
-    }
-    start(onInput, onResize) {
-        // stop() removes the exit flush, and renderer switches stop and start
-        // the shared terminal each time; restore it so a synchronous
-        // process.exit() during this lifecycle still flushes pending frames.
-        // remove-then-add keeps exactly one registration even when start()
-        // runs right after construction (constructor already registered) or
-        // across repeated start/stop cycles.
-        process.removeListener("exit", this.flushOnExit);
-        process.on("exit", this.flushOnExit);
-        // User input outside an active run closes the preservation window
-        // (see setAgentRunActive). Observing input here instead of on a TUI
-        // input listener keeps the window logic in one place and renderer
-        // switches — which stop and restart this shared terminal — rewrap
-        // the new handler automatically.
-        super.start((data) => {
-            if (!this.agentRunActive)
-                this.preserve = false;
-            onInput(data);
-        }, onResize);
-    }
-    write(data) {
-        if (data.length === 0)
-            return;
-        this.pending += this.preserveScrollback(data);
-        if (this.flushQueued)
-            return;
-        this.flushQueued = true;
-        queueMicrotask(() => this.flush());
-    }
-    // Route every escape-sequence helper through the coalescing buffer so a
-    // caller mixing helpers with write() keeps its output ordered.
-    moveBy(lines) {
-        if (lines > 0) {
-            this.write(`\x1b[${lines}B`);
-        }
-        else if (lines < 0) {
-            this.write(`\x1b[${-lines}A`);
-        }
-    }
-    hideCursor() {
-        this.write("\x1b[?25l");
-    }
-    showCursor() {
-        this.write("\x1b[?25h");
-    }
-    clearLine() {
-        this.write("\x1b[K");
-    }
-    clearFromCursor() {
-        this.write("\x1b[J");
-    }
-    clearScreen() {
-        this.write("\x1b[2J\x1b[H");
-    }
-    stop() {
-        // ProcessTerminal.stop() writes its teardown sequences directly to
-        // stdout, so pending frame data must go out first.
-        this.flush();
-        process.removeListener("exit", this.flushOnExit);
-        super.stop();
-    }
-    /**
-     * Rewrite a full-redraw frame (`?2026h 2J H 3J <lines> ?2026l`) so it
-     * repaints the screen without wiping scrollback. Anything that does not
-     * match this exact shape — including width-change redraws and frames
-     * touching kitty images — passes through unchanged.
-     */
-    preserveScrollback(data) {
-        const columns = this.columns;
-        const rows = this.rows;
-        const widthChanged = this.lastWriteColumns !== undefined && this.lastWriteColumns !== columns;
-        const heightChanged = this.lastWriteRows !== undefined && this.lastWriteRows !== rows;
-        this.lastWriteColumns = columns;
-        this.lastWriteRows = rows;
-        // One-shot: the very next write is the armed toggle's own frame (or a
-        // differential frame when the toggle stayed inside the viewport, in
-        // which case no exemption is needed and the flag must not linger).
-        const passAllowed = this.passArmed;
-        this.passArmed = false;
-        const prefix = SYNC_START + CLEAR_WITH_SCROLLBACK;
-        if (!data.startsWith(prefix) || !data.endsWith(SYNC_END)) {
-            return data;
-        }
-        // Outside the preservation window (idle sessions, pre-session UI) and
-        // for armed user toggles, upstream's wipe-and-replay is byte-perfect;
-        // let it through.
-        if (!this.preserve || passAllowed) {
-            return data;
-        }
-        // Re-wrapped/re-flowed content invalidates what scrollback holds and
-        // where the screen sits in it; keep the wipe.
-        if (widthChanged || heightChanged) {
-            return data;
-        }
-        if (data.includes(KITTY_APC_PREFIX)) {
-            return data;
-        }
-        const body = data.slice(prefix.length, data.length - SYNC_END.length);
-        // A second clear inside one write means the frame shape changed
-        // upstream; bail out rather than guess.
-        if (body.includes(CLEAR_WITH_SCROLLBACK)) {
-            return data;
-        }
-        // ED 2 (`2J`) is deliberately avoided in both rewrites below: conhost/
-        // Windows Terminal implement it by scrolling the current screen into
-        // scrollback (cls compatibility), so without the `3J` wipe each redraw
-        // would stack another screenful of duplicates into history.
-        const lines = body.split("\r\n");
-        const newViewportTop = Math.max(0, lines.length - rows);
-        const viewportTop = this.readViewportTop();
-        if (viewportTop !== undefined && viewportTop <= newViewportTop) {
-            // The transcript grew (or held steady): repaint the rows currently
-            // on screen with the new content at those same transcript
-            // positions, then scroll the remaining lines in at the bottom row.
-            // Each bottom-row newline pushes the already-repainted top row into
-            // scrollback, so scrollback receives exactly the new lines the
-            // upstream replay would have put there — no wipe, no loss.
-            const onScreen = lines.slice(viewportTop, viewportTop + rows);
-            const scrolled = lines.slice(viewportTop + rows);
-            let repaint = onScreen.map((line) => `\x1b[2K${line}`).join("\r\n");
-            for (const line of scrolled) {
-                repaint += `\r\n\x1b[2K${line}`;
-            }
-            return `${SYNC_START}\x1b[H${repaint}\x1b[J${SYNC_END}`;
-        }
-        // Fallback (no provider, or the transcript shrank — lines cannot be
-        // pulled back out of scrollback): repaint only the bottom
-        // viewport-height rows, overwriting the screen in place: home,
-        // erase-and-rewrite each row, erase whatever remains below. Writing the
-        // full transcript after a screen clear would push a duplicate copy of
-        // everything above the viewport into scrollback; the truncated
-        // overwrite produces the exact same final screen and cursor position as
-        // the full replay (rows beyond the screen would have scrolled out
-        // anyway).
-        const kept = lines.length > rows ? lines.slice(lines.length - rows) : lines;
-        const repaint = kept.map((line) => `\x1b[2K${line}`).join("\r\n");
-        return `${SYNC_START}\x1b[H${repaint}\x1b[J${SYNC_END}`;
-    }
-    // The provider reaches into the renderer's bookkeeping; treat anything
-    // unexpected as "unknown" and fall back rather than corrupt the screen.
-    readViewportTop() {
-        if (!this.viewportTopProvider)
-            return undefined;
-        try {
-            const value = this.viewportTopProvider();
-            return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : undefined;
-        }
-        catch {
-            return undefined;
-        }
-    }
-    flush() {
-        this.flushQueued = false;
-        if (this.pending.length === 0) {
-            return;
-        }
-        const data = this.pending;
-        this.pending = "";
-        super.write(data);
-    }
-}
-//# sourceMappingURL=coalescing-terminal.js.map

package/dist/utils/coalescing-terminal.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"coalescing-terminal.js","sourceRoot":"","sources":["../../src/utils/coalescing-terminal.ts"],"names":[],"mappings":"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","sourcesContent":["import { ProcessTerminal } from \"@earendil-works/pi-tui\";\n\nconst SYNC_START = \"\\x1b[?2026h\";\nconst SYNC_END = \"\\x1b[?2026l\";\n/** Clear screen, home, clear scrollback — pi-tui's fullRender(clear) preamble. */\nconst CLEAR_WITH_SCROLLBACK = \"\\x1b[2J\\x1b[H\\x1b[3J\";\n/** Kitty graphics APC prefix; frames touching images interleave cursor moves. */\nconst KITTY_APC_PREFIX = \"\\x1b_G\";\n\n/**\n * ProcessTerminal that (1) coalesces every write issued within one synchronous\n * task into a single stdout write and (2) keeps content-driven full redraws\n * from destroying the terminal's scrollback.\n *\n * Coalescing: pi-tui emits each render pass as several separate stdout\n * writes: the frame wrapped in synchronized output (CSI ?2026h/l), then a\n * relative cursor move that parks the hardware cursor at the focused\n * component's caret for IME composition, then a cursor visibility toggle.\n * Terminals that anchor the IME candidate window to the hardware cursor\n * (Windows Terminal and other ConPTY hosts, WezTerm) can process the frame\n * write before the reposition write arrives, briefly leaving the cursor at\n * the end of the last repainted line. With an IME active this makes the\n * candidate window jump between the caret and the right edge of the input\n * line on every keystroke. Merging the writes makes each frame atomic, so the\n * only cursor position a terminal can observe is the final one.\n *\n * Scrollback preservation: pi-tui's fullRender(clear) opens with\n * `2J H 3J`, wiping the terminal's scrollback, and then replays the entire\n * transcript. During streaming, content-driven triggers (a line changing\n * above the viewport during markdown reflow) fire this routinely, which — in\n * terminals that clamp the scroll offset when scrollback vanishes, notably\n * Windows Terminal — yanks a scrolled-up reader to the top of the buffer on\n * every reflow (upstream #6502, #5576, #6050; rejected upstream fix #4204).\n *\n * Preservation is therefore windowed, not permanent: the host marks agent\n * runs via setAgentRunActive, which turns preservation on at run start and\n * keeps it on until the user's next input after the run settles, since they\n * may still be scrolled up reading. The input half of the window is observed\n * directly on this terminal's own input path, so it needs no TUI listener\n * and survives renderer switches (which reuse this terminal) untouched. An\n * idle-session full redraw — Ctrl+O toggles, mode switches — passes through\n * with upstream's wipe-and-replay, whose result is byte-perfect: scrollback\n * becomes the clean new transcript. Mid-run user toggles can arm\n * passNextFullRedraw for the same clean replay on their own frame.\n *\n * While preservation is active, a matching frame is rewritten to repaint\n * without the wipe. With setViewportTopProvider wired, the rewrite knows\n * which transcript line the visible screen starts at, so a frame that grew\n * the transcript repaints the on-screen rows with the new content at those\n * same positions and then scrolls the extra lines in at the bottom row.\n * Each bottom-row newline pushes the top row — already repainted with the\n * correct new content — into scrollback, exactly like ordinary streaming\n * output, so scrollback ends up byte-equivalent to the upstream full replay\n * without ever clearing it. Without the provider, or when the transcript\n * shrank (lines cannot be pulled back out of scrollback), the rewrite falls\n * back to overwriting the visible screen in place with the bottom\n * viewport-height rows, at the cost of a stale seam above the screen. ED 2\n * is avoided entirely in rewritten frames because conhost/Windows Terminal\n * implement it by scrolling the screen contents into scrollback rather than\n * erasing in place.\n *\n * Width- and height-change redraws keep the upstream wipe because re-wrapped\n * content genuinely invalidates old scrollback, and frames containing kitty\n * graphics pass through untouched. A frame that does not match the expected\n * shape is passed through unchanged, so if upstream reshapes its render\n * output the wrapper degrades back to stock behavior.\n */\nexport class CoalescingTerminal extends ProcessTerminal {\n\tprivate pending = \"\";\n\tprivate flushQueued = false;\n\tprivate lastWriteColumns: number | undefined;\n\tprivate lastWriteRows: number | undefined;\n\tprivate viewportTopProvider: (() => number | undefined) | undefined;\n\tprivate preserve = false;\n\tprivate passArmed = false;\n\tprivate agentRunActive = false;\n\tprivate flushOnExit = () => this.flush();\n\n\t/**\n\t * Enable or disable the scrollback-preserving rewrite. Preservation is\n\t * only worth its imperfections (stale renderings above the screen, seams\n\t * on shrink) while the transcript is mutating on its own and the reader\n\t * may be scrolled up — i.e. during an agent run and until the user's next\n\t * input after it settles. Outside that window every full redraw passes\n\t * through with upstream's wipe-and-replay, whose result is byte-perfect:\n\t * scrollback becomes the clean new transcript. Default: disabled.\n\t * setAgentRunActive drives this for the normal agent-run window; this\n\t * primitive remains for direct control in tests.\n\t */\n\tsetScrollbackPreservation(enabled: boolean): void {\n\t\tthis.preserve = enabled;\n\t}\n\n\t/**\n\t * Open or close the agent-run half of the preservation window. Opening\n\t * (agent_start) turns preservation on. Closing (agent_settled) leaves\n\t * preservation on: trailing reflow frames may land after the run while\n\t * the reader is still scrolled up. The window then closes on the user's\n\t * next input, observed in start()'s input wrapper — once the user acts\n\t * they are back at the bottom, and upstream's clean wipe-and-replay wins\n\t * again until the next run.\n\t */\n\tsetAgentRunActive(active: boolean): void {\n\t\tthis.agentRunActive = active;\n\t\tif (active) this.preserve = true;\n\t}\n\n\t/**\n\t * Arm a one-shot exemption for an explicit user action (Ctrl+O tool\n\t * expansion, thinking visibility) so its own full redraw keeps the\n\t * upstream wipe-and-replay even while preservation is active mid-run.\n\t * The user just pressed a key, so they are interacting at the bottom;\n\t * a clean replay beats preservation's stale-seam trade-offs there. The\n\t * flag is cleared by the next write so it cannot leak onto a later\n\t * streaming redraw.\n\t */\n\tpassNextFullRedraw(): void {\n\t\tthis.passArmed = true;\n\t}\n\n\t/**\n\t * Wire the renderer's notion of which transcript line the visible screen\n\t * currently starts at (pi-tui's `previousViewportTop`). Full-redraw frames\n\t * that grew the transcript then scroll the new above-screen lines into\n\t * scrollback instead of dropping them. The provider is read while the\n\t * frame is being written, i.e. before the renderer updates its own\n\t * bookkeeping for that frame; returning undefined falls back to the\n\t * bottom-anchored in-place repaint.\n\t */\n\tsetViewportTopProvider(provider: () => number | undefined): void {\n\t\tthis.viewportTopProvider = provider;\n\t}\n\n\tconstructor() {\n\t\tsuper();\n\t\t// A synchronous process.exit() before the queued microtask runs would\n\t\t// otherwise drop the final frame.\n\t\tprocess.on(\"exit\", this.flushOnExit);\n\t}\n\n\toverride start(onInput: (data: string) => void, onResize: () => void): void {\n\t\t// stop() removes the exit flush, and renderer switches stop and start\n\t\t// the shared terminal each time; restore it so a synchronous\n\t\t// process.exit() during this lifecycle still flushes pending frames.\n\t\t// remove-then-add keeps exactly one registration even when start()\n\t\t// runs right after construction (constructor already registered) or\n\t\t// across repeated start/stop cycles.\n\t\tprocess.removeListener(\"exit\", this.flushOnExit);\n\t\tprocess.on(\"exit\", this.flushOnExit);\n\t\t// User input outside an active run closes the preservation window\n\t\t// (see setAgentRunActive). Observing input here instead of on a TUI\n\t\t// input listener keeps the window logic in one place and renderer\n\t\t// switches — which stop and restart this shared terminal — rewrap\n\t\t// the new handler automatically.\n\t\tsuper.start((data) => {\n\t\t\tif (!this.agentRunActive) this.preserve = false;\n\t\t\tonInput(data);\n\t\t}, onResize);\n\t}\n\n\toverride write(data: string): void {\n\t\tif (data.length === 0) return;\n\t\tthis.pending += this.preserveScrollback(data);\n\t\tif (this.flushQueued) return;\n\t\tthis.flushQueued = true;\n\t\tqueueMicrotask(() => this.flush());\n\t}\n\n\t// Route every escape-sequence helper through the coalescing buffer so a\n\t// caller mixing helpers with write() keeps its output ordered.\n\toverride moveBy(lines: number): void {\n\t\tif (lines > 0) {\n\t\t\tthis.write(`\\x1b[${lines}B`);\n\t\t} else if (lines < 0) {\n\t\t\tthis.write(`\\x1b[${-lines}A`);\n\t\t}\n\t}\n\n\toverride hideCursor(): void {\n\t\tthis.write(\"\\x1b[?25l\");\n\t}\n\n\toverride showCursor(): void {\n\t\tthis.write(\"\\x1b[?25h\");\n\t}\n\n\toverride clearLine(): void {\n\t\tthis.write(\"\\x1b[K\");\n\t}\n\n\toverride clearFromCursor(): void {\n\t\tthis.write(\"\\x1b[J\");\n\t}\n\n\toverride clearScreen(): void {\n\t\tthis.write(\"\\x1b[2J\\x1b[H\");\n\t}\n\n\toverride stop(): void {\n\t\t// ProcessTerminal.stop() writes its teardown sequences directly to\n\t\t// stdout, so pending frame data must go out first.\n\t\tthis.flush();\n\t\tprocess.removeListener(\"exit\", this.flushOnExit);\n\t\tsuper.stop();\n\t}\n\n\t/**\n\t * Rewrite a full-redraw frame (`?2026h 2J H 3J <lines> ?2026l`) so it\n\t * repaints the screen without wiping scrollback. Anything that does not\n\t * match this exact shape — including width-change redraws and frames\n\t * touching kitty images — passes through unchanged.\n\t */\n\tprivate preserveScrollback(data: string): string {\n\t\tconst columns = this.columns;\n\t\tconst rows = this.rows;\n\t\tconst widthChanged = this.lastWriteColumns !== undefined && this.lastWriteColumns !== columns;\n\t\tconst heightChanged = this.lastWriteRows !== undefined && this.lastWriteRows !== rows;\n\t\tthis.lastWriteColumns = columns;\n\t\tthis.lastWriteRows = rows;\n\t\t// One-shot: the very next write is the armed toggle's own frame (or a\n\t\t// differential frame when the toggle stayed inside the viewport, in\n\t\t// which case no exemption is needed and the flag must not linger).\n\t\tconst passAllowed = this.passArmed;\n\t\tthis.passArmed = false;\n\n\t\tconst prefix = SYNC_START + CLEAR_WITH_SCROLLBACK;\n\t\tif (!data.startsWith(prefix) || !data.endsWith(SYNC_END)) {\n\t\t\treturn data;\n\t\t}\n\t\t// Outside the preservation window (idle sessions, pre-session UI) and\n\t\t// for armed user toggles, upstream's wipe-and-replay is byte-perfect;\n\t\t// let it through.\n\t\tif (!this.preserve || passAllowed) {\n\t\t\treturn data;\n\t\t}\n\t\t// Re-wrapped/re-flowed content invalidates what scrollback holds and\n\t\t// where the screen sits in it; keep the wipe.\n\t\tif (widthChanged || heightChanged) {\n\t\t\treturn data;\n\t\t}\n\t\tif (data.includes(KITTY_APC_PREFIX)) {\n\t\t\treturn data;\n\t\t}\n\t\tconst body = data.slice(prefix.length, data.length - SYNC_END.length);\n\t\t// A second clear inside one write means the frame shape changed\n\t\t// upstream; bail out rather than guess.\n\t\tif (body.includes(CLEAR_WITH_SCROLLBACK)) {\n\t\t\treturn data;\n\t\t}\n\t\t// ED 2 (`2J`) is deliberately avoided in both rewrites below: conhost/\n\t\t// Windows Terminal implement it by scrolling the current screen into\n\t\t// scrollback (cls compatibility), so without the `3J` wipe each redraw\n\t\t// would stack another screenful of duplicates into history.\n\t\tconst lines = body.split(\"\\r\\n\");\n\t\tconst newViewportTop = Math.max(0, lines.length - rows);\n\t\tconst viewportTop = this.readViewportTop();\n\t\tif (viewportTop !== undefined && viewportTop <= newViewportTop) {\n\t\t\t// The transcript grew (or held steady): repaint the rows currently\n\t\t\t// on screen with the new content at those same transcript\n\t\t\t// positions, then scroll the remaining lines in at the bottom row.\n\t\t\t// Each bottom-row newline pushes the already-repainted top row into\n\t\t\t// scrollback, so scrollback receives exactly the new lines the\n\t\t\t// upstream replay would have put there — no wipe, no loss.\n\t\t\tconst onScreen = lines.slice(viewportTop, viewportTop + rows);\n\t\t\tconst scrolled = lines.slice(viewportTop + rows);\n\t\t\tlet repaint = onScreen.map((line) => `\\x1b[2K${line}`).join(\"\\r\\n\");\n\t\t\tfor (const line of scrolled) {\n\t\t\t\trepaint += `\\r\\n\\x1b[2K${line}`;\n\t\t\t}\n\t\t\treturn `${SYNC_START}\\x1b[H${repaint}\\x1b[J${SYNC_END}`;\n\t\t}\n\t\t// Fallback (no provider, or the transcript shrank — lines cannot be\n\t\t// pulled back out of scrollback): repaint only the bottom\n\t\t// viewport-height rows, overwriting the screen in place: home,\n\t\t// erase-and-rewrite each row, erase whatever remains below. Writing the\n\t\t// full transcript after a screen clear would push a duplicate copy of\n\t\t// everything above the viewport into scrollback; the truncated\n\t\t// overwrite produces the exact same final screen and cursor position as\n\t\t// the full replay (rows beyond the screen would have scrolled out\n\t\t// anyway).\n\t\tconst kept = lines.length > rows ? lines.slice(lines.length - rows) : lines;\n\t\tconst repaint = kept.map((line) => `\\x1b[2K${line}`).join(\"\\r\\n\");\n\t\treturn `${SYNC_START}\\x1b[H${repaint}\\x1b[J${SYNC_END}`;\n\t}\n\n\t// The provider reaches into the renderer's bookkeeping; treat anything\n\t// unexpected as \"unknown\" and fall back rather than corrupt the screen.\n\tprivate readViewportTop(): number | undefined {\n\t\tif (!this.viewportTopProvider) return undefined;\n\t\ttry {\n\t\t\tconst value = this.viewportTopProvider();\n\t\t\treturn typeof value === \"number\" && Number.isInteger(value) && value >= 0 ? value : undefined;\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t}\n\n\tprivate flush(): void {\n\t\tthis.flushQueued = false;\n\t\tif (this.pending.length === 0) {\n\t\t\treturn;\n\t\t}\n\t\tconst data = this.pending;\n\t\tthis.pending = \"\";\n\t\tsuper.write(data);\n\t}\n}\n"]}