@astralyn/pi 0.82.3 → 0.82.4

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

@@ -0,0 +1,62 @@
+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. Content-driven triggers (a line changing above the viewport
+ * during streaming markdown reflow, large content shrinks) fire this
+ * routinely, which erases pre-session shell history and — in terminals that
+ * clamp the scroll offset when scrollback vanishes, notably Windows
+ * Terminal — yanks a scrolled-up viewport to the top of the buffer
+ * (upstream #6502, #5576, #6050; rejected upstream fix #4204). Frames
+ * matching that shape are rewritten to overwrite the visible screen in place
+ * (home, erase-and-rewrite each row, erase below) with only the bottom
+ * viewport-height rows, which leaves scrollback (and the reader's scroll
+ * position) untouched while producing a byte-identical final screen state.
+ * ED 2 is avoided entirely because conhost/Windows Terminal implement it by
+ * scrolling the screen contents into scrollback rather than erasing in
+ * place. Width-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 flushOnExit;
+    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 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,kBAAmB,SAAQ,eAAe;IACtD,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,WAAW,CAAsB;IAEzC,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;IAwC1B,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. Content-driven triggers (a line changing above the viewport\n * during streaming markdown reflow, large content shrinks) fire this\n * routinely, which erases pre-session shell history and — in terminals that\n * clamp the scroll offset when scrollback vanishes, notably Windows\n * Terminal — yanks a scrolled-up viewport to the top of the buffer\n * (upstream #6502, #5576, #6050; rejected upstream fix #4204). Frames\n * matching that shape are rewritten to overwrite the visible screen in place\n * (home, erase-and-rewrite each row, erase below) with only the bottom\n * viewport-height rows, which leaves scrollback (and the reader's scroll\n * position) untouched while producing a byte-identical final screen state.\n * ED 2 is avoided entirely because conhost/Windows Terminal implement it by\n * scrolling the screen contents into scrollback rather than erasing in\n * place. Width-change redraws keep the upstream wipe because\n * re-wrapped content genuinely invalidates old scrollback, and frames\n * containing kitty graphics pass through untouched. A frame that does not\n * match the expected shape is passed through unchanged, so if upstream\n * reshapes its render 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 flushOnExit = () => this.flush();\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 widthChanged = this.lastWriteColumns !== undefined && this.lastWriteColumns !== columns;\n\t\tthis.lastWriteColumns = columns;\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// Re-wrapped content invalidates what scrollback holds; keep the wipe.\n\t\tif (widthChanged) {\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// Repaint only the bottom viewport-height rows, overwriting the screen\n\t\t// in place: home, erase-and-rewrite each row, erase whatever remains\n\t\t// below. Writing the full transcript after a screen clear would push a\n\t\t// duplicate copy of everything above the viewport into scrollback; the\n\t\t// truncated overwrite produces the exact same final screen and cursor\n\t\t// position as the full replay (rows beyond the screen would have\n\t\t// scrolled out anyway). ED 2 (`2J`) is deliberately avoided even for\n\t\t// the visible screen: conhost/Windows Terminal implement it by\n\t\t// scrolling the current screen into scrollback (cls compatibility), so\n\t\t// without the `3J` wipe each redraw would stack another screenful of\n\t\t// duplicates into history.\n\t\tconst lines = body.split(\"\\r\\n\");\n\t\tconst rows = this.rows;\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\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,151 @@
+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. Content-driven triggers (a line changing above the viewport
+ * during streaming markdown reflow, large content shrinks) fire this
+ * routinely, which erases pre-session shell history and — in terminals that
+ * clamp the scroll offset when scrollback vanishes, notably Windows
+ * Terminal — yanks a scrolled-up viewport to the top of the buffer
+ * (upstream #6502, #5576, #6050; rejected upstream fix #4204). Frames
+ * matching that shape are rewritten to overwrite the visible screen in place
+ * (home, erase-and-rewrite each row, erase below) with only the bottom
+ * viewport-height rows, which leaves scrollback (and the reader's scroll
+ * position) untouched while producing a byte-identical final screen state.
+ * ED 2 is avoided entirely because conhost/Windows Terminal implement it by
+ * scrolling the screen contents into scrollback rather than erasing in
+ * place. Width-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;
+    flushOnExit = () => this.flush();
+    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 widthChanged = this.lastWriteColumns !== undefined && this.lastWriteColumns !== columns;
+        this.lastWriteColumns = columns;
+        const prefix = SYNC_START + CLEAR_WITH_SCROLLBACK;
+        if (!data.startsWith(prefix) || !data.endsWith(SYNC_END)) {
+            return data;
+        }
+        // Re-wrapped content invalidates what scrollback holds; keep the wipe.
+        if (widthChanged) {
+            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;
+        }
+        // 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). ED 2 (`2J`) is deliberately avoided even for
+        // the visible screen: 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 rows = this.rows;
+        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}`;
+    }
+    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. Content-driven triggers (a line changing above the viewport\n * during streaming markdown reflow, large content shrinks) fire this\n * routinely, which erases pre-session shell history and — in terminals that\n * clamp the scroll offset when scrollback vanishes, notably Windows\n * Terminal — yanks a scrolled-up viewport to the top of the buffer\n * (upstream #6502, #5576, #6050; rejected upstream fix #4204). Frames\n * matching that shape are rewritten to overwrite the visible screen in place\n * (home, erase-and-rewrite each row, erase below) with only the bottom\n * viewport-height rows, which leaves scrollback (and the reader's scroll\n * position) untouched while producing a byte-identical final screen state.\n * ED 2 is avoided entirely because conhost/Windows Terminal implement it by\n * scrolling the screen contents into scrollback rather than erasing in\n * place. Width-change redraws keep the upstream wipe because\n * re-wrapped content genuinely invalidates old scrollback, and frames\n * containing kitty graphics pass through untouched. A frame that does not\n * match the expected shape is passed through unchanged, so if upstream\n * reshapes its render 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 flushOnExit = () => this.flush();\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 widthChanged = this.lastWriteColumns !== undefined && this.lastWriteColumns !== columns;\n\t\tthis.lastWriteColumns = columns;\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// Re-wrapped content invalidates what scrollback holds; keep the wipe.\n\t\tif (widthChanged) {\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// Repaint only the bottom viewport-height rows, overwriting the screen\n\t\t// in place: home, erase-and-rewrite each row, erase whatever remains\n\t\t// below. Writing the full transcript after a screen clear would push a\n\t\t// duplicate copy of everything above the viewport into scrollback; the\n\t\t// truncated overwrite produces the exact same final screen and cursor\n\t\t// position as the full replay (rows beyond the screen would have\n\t\t// scrolled out anyway). ED 2 (`2J`) is deliberately avoided even for\n\t\t// the visible screen: conhost/Windows Terminal implement it by\n\t\t// scrolling the current screen into scrollback (cls compatibility), so\n\t\t// without the `3J` wipe each redraw would stack another screenful of\n\t\t// duplicates into history.\n\t\tconst lines = body.split(\"\\r\\n\");\n\t\tconst rows = this.rows;\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\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/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

package/docs/bundled/extensions/subagent.md

@@ -8,7 +8,8 @@ Exactly one mode is required per call:
 
 - **Single**: `agent`, `description`, and `prompt`.
 - **Parallel**: `tasks`, an array of independent task objects.
-- **Chain**: `chain`, an array of sequential task objects. `{previous}` in a later prompt is replaced by the previous worker's bounded final response.
+
+There is deliberately no chain mode: sequential work is driven by the parent, which reads each report before writing the next briefing.
 
 Every task object has:
 
@@ -17,11 +18,9 @@ agent?       Agent profile name; defaults to general
 description  Short UI label
 prompt       Self-contained worker briefing
 cwd?         Relative directory inside the parent working directory
-model?       Temporary provider/model override
-thinking?    Temporary thinking-level override
 ```
 
-Parallel and chain batches allow at most eight tasks. A session-scoped gate runs at most three workers concurrently, including sibling `subagent` calls from the same parent session.
+Parallel batches allow at most eight tasks. A session-scoped gate runs at most five workers concurrently, including sibling `subagent` calls from the same parent session.
 
 ## Agent profiles
 
@@ -50,26 +49,26 @@ Project definitions are loaded only after Pi trusts the project. Invalid Markdow
 
 Built-in profiles:
 
-- `general`: read, bash, edit, write, grep, find, and ls.
-- `explorer`: read-only `read`, `grep`, `find`, and `ls`, with low thinking by default.
+- `general`: read, bash, edit, and write.
+- `explorer`: read-only `read`, `grep`, `find`, and `ls`.
 
 A profile may only allow Pi built-in tools. Child sessions load no extensions, skills, or prompt templates, so a worker cannot recursively call `subagent` or inherit unrelated extension capabilities. Project context files such as `AGENTS.md` remain available.
 
 ## Model and thinking selection
 
-The model/thinking resolution order is:
+The model/thinking resolution has exactly two layers:
 
 ```text
-per-call tool fields
-  > saved /agents profile override
-  > profile Markdown frontmatter
-  > current parent session
+saved /agents profile override > current parent session
 ```
 
+Callers cannot pick models per call, and profile Markdown `model`/`thinking`
+frontmatter is intentionally ignored: agent files travel across machines, so a
+pinned model rarely exists in the reader's environment.
+
 Run `/agents` to choose a profile and set either field to:
 
-- **inherit**: force the active parent-session value;
-- **agent default**: clear the saved override and use Markdown/default inheritance;
+- **inherit**: follow the parent session's current value;
 - a configured `provider/model` or explicit supported thinking level.
 
 Overrides are user-owned and saved atomically in:
@@ -84,8 +83,9 @@ They apply only to future subagent runs and never change the parent session's `/
 
 - The parent tool call waits until every worker reaches a terminal state.
 - 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. A failed or aborted chain step skips its remaining steps.
-- Progress is rendered in Pi's native tool transcript. The collapsed view shows status, recent activity, usage, and the configured expand hint; `Ctrl+O` shows bounded activities and final Markdown reports.
+- 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 `Retrying (n/m) in Xs…`), and a failure that produced no work (for example a preflight auth throw) is rerun at the task level up to two more times. Runs with partial work behind them are never rerun.
+- Progress is rendered in Pi's native tool transcript. The collapsed view shows an intent line (for example `Verifying changes`), the current tool marked with `›`, live elapsed time, usage with a `ctx:` context watermark, and the configured expand hint. The call-level status dot belongs to the tool shell; run and activity rows only use `›`, `○`, `✓`, `×`, and `■`. `Ctrl+O` shows bounded activities and final Markdown reports; expanded batches start with a numbered contents list whose numbers match the `──` section headers.
 - 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.
 - Nested usage is returned with the tool result and included in parent session accounting.
 

package/docs/compaction.md

@@ -284,7 +284,7 @@ Fired before auto-compaction or `/compact`. Can cancel or provide custom summary
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;
+  const { preparation, branchEntries, customInstructions, reason, timing, willRetry, signal } = event;
 
   // preparation.messagesToSummarize - messages to summarize
   // preparation.turnPrefixMessages - split turn prefix (if isSplitTurn)
@@ -296,10 +296,14 @@ pi.on("session_before_compact", async (event, ctx) => {
 
   // branchEntries - all entries on current branch (for custom state)
   // reason - "manual" (/compact), "threshold", or "overflow"
+  // timing - "manual", "midTurn" (between tool batches), "postRun", or "prePrompt"
   // willRetry - whether overflow recovery intends to retry if compaction produces a safe retained context
   // signal - AbortSignal (pass to LLM calls)
 
-  // Cancel:
+  // Cancel. Consequences depend on timing: a "midTurn" cancel skips compaction
+  // for the rest of the run and the run continues at your risk of overflowing;
+  // other timings leave the over-threshold context to fail closed before the
+  // next provider request.
   return { cancel: true };
 
   // Custom summary:

package/docs/docs.json

@@ -64,6 +64,10 @@
           "title": "DeepWiki",
           "path": "bundled/extensions/deepwiki.md"
         },
+        {
+          "title": "Plan",
+          "path": "bundled/extensions/plan.md"
+        },
         {
           "title": "Question",
           "path": "bundled/extensions/question.md"

package/docs/extensions.md

@@ -454,12 +454,14 @@ Fired on compaction. See [compaction.md](compaction.md) for details.
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;
+  const { preparation, branchEntries, customInstructions, reason, timing, willRetry, signal } = event;
 
   // reason - "manual" (/compact), "threshold", or "overflow"
+  // timing - "manual", "midTurn" (between tool batches), "postRun", or "prePrompt"
   // willRetry - whether overflow recovery intends to retry if compaction produces a safe retained context
 
-  // Cancel:
+  // Cancel. A "midTurn" cancel skips compaction for the rest of the run and the
+  // run continues at your risk; other timings fail closed on the oversized context.
   return { cancel: true };
 
   // Custom summary:

package/npm-shrinkwrap.json

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

package/package.json

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