@astralyn/pi 0.82.3 → 0.82.5

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

@@ -0,0 +1,116 @@
+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 enables it via
+ * setScrollbackPreservation while an agent run is mutating the transcript
+ * (and keeps it on until the user's next input after the run settles, since
+ * they may still be scrolled up reading), and leaves it off otherwise. 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 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.
+     */
+    setScrollbackPreservation(enabled: 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();
+    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

@@ -0,0 +1 @@
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;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,WAAW,CAAsB;IAEzC;;;;;;;;OAQG;IACH,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEhD;IAED;;;;;;;;OAQG;IACH,kBAAkB,IAAI,IAAI,CAEzB;IAED;;;;;;;;OAQG;IACH,sBAAsB,CAAC,QAAQ,EAAE,MAAM,MAAM,GAAG,SAAS,GAAG,IAAI,CAE/D;IAED,cAKC;IAEQ,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMjC;IAIQ,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMnC;IAEQ,UAAU,IAAI,IAAI,CAE1B;IAEQ,UAAU,IAAI,IAAI,CAE1B;IAEQ,SAAS,IAAI,IAAI,CAEzB;IAEQ,eAAe,IAAI,IAAI,CAE/B;IAEQ,WAAW,IAAI,IAAI,CAE3B;IAEQ,IAAI,IAAI,IAAI,CAMpB;IAED;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IA2E1B,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,KAAK;CASb","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 enables it via\n * setScrollbackPreservation while an agent run is mutating the transcript\n * (and keeps it on until the user's next input after the run settles, since\n * they may still be scrolled up reading), and leaves it off otherwise. 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 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 */\n\tsetScrollbackPreservation(enabled: boolean): void {\n\t\tthis.preserve = enabled;\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 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"]}

package/dist/utils/coalescing-terminal.js

@@ -0,0 +1,256 @@
+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 enables it via
+ * setScrollbackPreservation while an agent run is mutating the transcript
+ * (and keeps it on until the user's next input after the run settles, since
+ * they may still be scrolled up reading), and leaves it off otherwise. 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 {
+    pending = "";
+    flushQueued = false;
+    lastWriteColumns;
+    lastWriteRows;
+    viewportTopProvider;
+    preserve = false;
+    passArmed = false;
+    flushOnExit = () => this.flush();
+    /**
+     * 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.
+     */
+    setScrollbackPreservation(enabled) {
+        this.preserve = enabled;
+    }
+    /**
+     * 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();
+        // A synchronous process.exit() before the queued microtask runs would
+        // otherwise drop the final frame.
+        process.on("exit", this.flushOnExit);
+    }
+    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

@@ -0,0 +1 @@
+{"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 enables it via\n * setScrollbackPreservation while an agent run is mutating the transcript\n * (and keeps it on until the user's next input after the run settles, since\n * they may still be scrolled up reading), and leaves it off otherwise. 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 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 */\n\tsetScrollbackPreservation(enabled: boolean): void {\n\t\tthis.preserve = enabled;\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 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"]}

package/docs/bundled/extensions/README.md

@@ -8,6 +8,7 @@ They are registered as hidden built-in extensions and use the same public Extens
 |---|---|---|
 | `llama.cpp` | `/llama` | [llama.cpp](../../llama-cpp.md) |
 | `deepwiki` | `deepwiki` | [deepwiki.md](deepwiki.md) |
+| `plan` | `exit_plan`, `/plan` | [plan.md](plan.md) |
 | `question` | `question` | [question.md](question.md) |
 | `todo` | `todo`, `/todos` | [todo.md](todo.md) |
 | `rewind` | `/rewind`, `/tree` lifecycle | [rewind.md](rewind.md) |

package/docs/bundled/extensions/plan.md

@@ -0,0 +1,31 @@
+# plan — read-only plan mode
+
+Adds `/plan` for a Claude-Code-style planning phase: the model explores read-only, interviews the user, and leaves the mode through a user-approved `exit_plan` tool call that saves the plan to disk and optionally compacts the context before execution starts.
+
+## Behavior
+
+- `/plan` (or the `--plan` CLI flag) toggles plan mode. On entry the built-in `edit`, `write`, and `bash` tools and the bundled `subagent` tool are deactivated — `subagent` because child sessions do not inherit the restricted tool set. Read-only built-ins and other extension tools (`question`, `todo`, `deepwiki`, …) stay available. A `tool_call` guard also blocks the four tools for requests already in flight when the mode toggles.
+- While planning, the system prompt gains a plan-mode block: explore before asking, interview one decision at a time with the `question` tool (with a recommendation and trade-offs), skip the interview for small clear tasks, then present the full plan as response text before calling `exit_plan`.
+- `exit_plan(title, plan, revises?)` opens the approval menu:
+  - **Start executing (keep full context)** — saves the plan, restores tools, and execution continues in the same run.
+  - **Compact context, then execute** — saves the plan, ends the run (`terminate`), compacts once the run has settled, and only then restores tools; execution restarts via a kickoff message that embeds the plan text, so continuation never depends on the compaction summary. If compaction fails, tools are restored and execution proceeds with full context.
+  - **Keep planning** — optionally collects feedback (multi-line editor in the TUI, input dialog in RPC) and returns it to the model; plan mode stays active. `Esc` and dialog timeouts map here, never to an executing option.
+- Both executing options save the plan file. If the session has no name yet, the plan title becomes the session name.
+- `/plan` while planning exits directly without a menu or a file — the plan text is still in context. During a pending compaction the toggle is refused until the compaction settles.
+- Plan files live under `<agentDir>/plans/<sessionId>/NN-<slug>.md` (`~/.pi/agent/plans/…` by default, `PI_CODING_AGENT_DIR` respected) with `title`, `created`, `cwd`, `session`, and optional `revises` frontmatter. Numbering is append-only; revisions are new files that point back via `revises`.
+- To revise a plan mid-execution, re-enter with `/plan`: the system prompt lists the branch's saved plans so the model reads the latest one, accounts for completed work, and produces a revision.
+
+## Limits
+
+- The kickoff message embeds at most 24 000 characters of plan markdown; longer plans are truncated with a pointer to the full file.
+- In `json`/`print` modes `exit_plan` cannot ask, so it saves the plan and exits with context kept (write access is restored without a menu).
+- Approving with **Compact context, then execute** and then interrupting before compaction completes (quit, resume, branch switch) degrades to the keep-context exit on the next session start.
+
+## Implementation notes
+
+- **Conversation-backed state.** Every transition appends a `plan-mode` custom entry (never sent to the LLM); lifecycle handlers replay the current branch tail → head, so `/reload`, `/tree`, resume, and fork restore the mode. Fork and clone copy entries, so the recorded plan-file paths follow the new session even though it gets a fresh session id — the `<sessionId>` directory is only the initial storage location, not the index.
+- **State is keyed per session id** (todo pattern): resume and `/tree` can switch sessions within one process, and handlers re-point the active bucket before touching state.
+- **Tool restore is an inverse operation, not a snapshot.** Entry records which tools were actually removed; exit re-adds exactly those, so tools other extensions activate during planning are not revoked and tools the user had disabled are not resurrected.
+- **No write access is ever needed for the plan itself** — the plan text travels as an `exit_plan` parameter and the extension writes the file.
+- **The compact-then-execute window is closed by construction**: plan mode (and its tool restrictions) persists until compaction completes; the run is terminated by the tool result and the compaction starts on `agent_settled`, which fires once per fully settled run.
+- The `exit_plan` result text authoritatively announces mode changes because the per-run system prompt override is not rebuilt mid-run.

package/docs/bundled/extensions/question.md

@@ -7,13 +7,15 @@ Adds a `question` tool for asking one to four multiple-choice questions when the
 - Each option requires a concise description of its consequence or trade-off. Questions, labels, descriptions, and previews have input-length limits so the dialog stays usable.
 - A single single-select question submits as soon as the user selects an option.
 - A multi-question flow advances after each single-select answer; multi-select uses `Space` to toggle choices and Enter to continue. Once every question is answered, a **Review answers** view requires explicit submission.
+- Options are numbered; pressing `1`–`9` jumps to the matching option — selecting it in single-select, toggling it in multi-select. The custom-answer row's number opens its input.
 - `←` / `→` switch between adjacent questions without wrapping. The tab bar marks answered questions and the Review state.
 - `Chat about this` is available after the choices. It returns a `needs_clarification` outcome so the model explains or reformulates instead of treating the user as having declined.
-- `Type something.` is appended automatically for custom answers. Authored options may not use reserved labels (`Other`, `Type something.`, `Chat about this`, `Next`).
-- `Tab` opens a note editor for the focused option; in multi-select, the option must be selected first. On the custom-answer row, it opens custom-answer input.
-- Multi-select custom answers stay on the `Type something.` row, are selected when saved, and can be toggled with `Space` without losing text.
-- `preview` shows focused single-select content beside the choices on wide terminals and beneath them on narrow terminals. Preview height is capped and reports hidden lines.
+- `Type something.` is appended automatically for custom answers. Authored options may not use reserved labels (`Other`, `Type something.`, `Chat about this`); the comparison is case-insensitive and ignores surrounding whitespace.
+- `Tab` opens a note editor for the focused option; in multi-select, the option must be selected first. In single-select it also selects the option, and cancelling the note editor with `Esc` restores the previous selection. On the custom-answer row, it opens custom-answer input.
+- Multi-select custom answers stay on the `Type something.` row, are selected when saved, and can be toggled with `Space` without losing text. Enter on that row opens the input while no custom answer exists yet.
+- `preview` shows focused single-select content beside the choices on wide terminals and beneath them on narrow terminals. Preview height is capped and reports hidden lines. Previews on multi-select questions are rejected with a `preview_multiselect` error.
 - The dialog is available only in TUI mode. RPC, JSON, and print calls return a structured `no_ui` error rather than attempting a custom component.
+- Aborting the turn closes the dialog and resolves the call as cancelled with the answers given so far.
 
 ## Result contract
 
@@ -28,7 +30,7 @@ Adds a `question` tool for asking one to four multiple-choice questions when the
 }
 ```
 
-Only `content` reaches the model. Successful results are numbered, clearly identify single/custom/multi answers, retain notes, and state when a preview was selected without echoing its full source. Model-facing output is capped at 12,000 characters; if it is truncated, the result instructs the model to ask a focused follow-up question. Notes and custom answers are capped at 4,000 characters in the dialog.
+Only `content` reaches the model. Successful results are numbered, clearly identify single/custom/multi answers, retain notes, and state when a preview was selected without echoing its full source. Cancelling — via `Esc` or a turn abort — lists any answers already given as partial answers alongside the decline message. Model-facing output is capped at 12,000 characters; if it is truncated, the result instructs the model to ask a focused follow-up question. Notes and custom answers are capped at 4,000 characters in the dialog.
 
 The transcript uses a private `renderCall` / `renderResult` only to replace raw question JSON and model-oriented result text with concise user summaries. Pi retains its native tool shell, pending/error state, and collapsed/expanded behavior.
 
@@ -42,7 +44,7 @@ The transcript uses a private `renderCall` / `renderResult` only to replace raw
 ## Implementation notes
 
 - Uses Pi's native `ctx.ui.custom()` lifecycle; no state is shared with another extension.
-- The render cache is keyed by terminal width **and height**, because preview height depends on available rows and Pi resize only requests a render.
-- `validateQuestions` enforces uniqueness, reserved-label rejection, and text budgets beyond what the JSON schema can express.
+- The render cache is keyed by terminal width **and height**, because preview height depends on available rows and Pi resize only requests a render. Preview markdown rendering is additionally memoized per text and dimensions so editor keystrokes don't re-parse previews.
+- `validateQuestions` enforces only what the JSON schema cannot express: case-insensitive uniqueness, reserved-label rejection, and the preview/multi-select conflict. Length and count limits are enforced against the schema before the tool executes.
 - Dialog navigation follows Pi's injected select/input keybindings where applicable; custom actions such as Space-to-toggle remain explicit in the footer.
 

package/docs/bundled/extensions/rewind.md

@@ -13,7 +13,11 @@ Per turn: `before_agent_start` opens a snapshot frame (re-recording every tracke
 file at its turn-start state, reusing the latest backup when unchanged);
 `tool_call(edit|write)` backs up each newly edited file *before* it lands;
 `agent_settled` persists the frame to the session JSONL as a `pi-rewind-snapshot`
-custom entry **only when files changed**. Using `agent_settled` (not `agent_end`)
+custom entry **only when files changed**. The frame anchors to the **first** user
+entry the run appended — the message whose start the frame recorded; steering and
+follow-up messages consumed inside the same run append later user entries and do
+not steal the anchor (a run that appends no user entry, e.g. custom-triggered,
+records no frame). Using `agent_settled` (not `agent_end`)
 keeps auto-retry, overflow compaction-retry, and queued follow-ups in one logical
 turn — `agent_end` can fire while Pi still continues. Requires **Pi ≥ 0.80.4**
 (when `agent_settled` was added); older hosts never fire that event, so frames
@@ -24,18 +28,25 @@ rebuilt from them on `session_start`.
   `edit` and `write` tools. Files written by `bash` (redirects, codegen, `mv`) or
   edited by hand outside Pi are **not** tracked — same boundary as Claude Code's
   file-history. Rewind undoes *Pi's edits*, not arbitrary filesystem state.
-- **Time-travel is via `/tree`.** Navigating to a node whose turn changed files
-  prompts to restore them, listing the affected files (cwd-relative, up to 8
-  then *"+N more"*) under *"Restore 3 files to this point?  (+120 / −40)"*
-  when coarse line stats are available; choosing yes restores the work tree to
-  that turn's start state. Nodes with no file changes navigate silently. Only
-  files that actually differ are rewritten. Line totals are a bag-of-lines
+- **Time-travel is via `/tree`.** Navigating to a node whose recorded state
+  differs from the work tree prompts to restore, listing the affected files
+  (cwd-relative, up to 8 then *"+N more"*) under *"Restore 3 files to this
+  point?  (+120 / −40)"* when coarse line stats are available. The restore
+  target mirrors `/tree`'s own semantics: a **user message** target (whose turn
+  is removed and returned to the editor) restores to the state *before* that
+  turn ran; any **other** target (whose turn stays in the conversation)
+  restores to the state *after* that turn — the state recorded when the next
+  run began. When nothing was recorded after the target (e.g. the last turn's
+  assistant message), navigation is silent rather than rolling back edits the
+  conversation still contains. Nodes with no file changes navigate silently.
+  Only files that actually differ are rewritten. Line totals are a bag-of-lines
   estimate (capped at 1 MB per file), not a full Myers diff.
 - **`/rewind` is a settings + storage menu**, not a restore picker:
   - toggle rewind on/off,
   - set the auto-clean retention window,
   - inspect storage and prune (clean aged + orphaned / remove orphaned / remove
-    all except current).
+    all except current — the latter also keeps backups written to in the last
+    10 minutes, which may belong to sessions running in another Pi process).
 - **New files** created by `write` are tracked with a "did not exist" marker, so
   rewinding deletes them.
 - **Resume/fork** hard-links the prior session's backup blobs into the new