@astralyn/pi 0.82.2 → 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/README.md

@@ -0,0 +1,38 @@
+# Bundled features
+
+The installed `@astralyn/pi` package includes a small set of workflows and presentation choices on top of its coding-agent behavior. Upstream Pi release tags are synchronization input, not a separate user documentation set.
+
+## Extensions
+
+The following extensions are loaded as hidden built-ins. They use the same public Extension API available to external extensions.
+
+| Extension | Tool or command | Purpose |
+|---|---|---|
+| `llama.cpp` | `/llama` | Manage models served by the local llama.cpp router |
+| `deepwiki` | `deepwiki` | Query indexed public GitHub repository documentation |
+| `question` | `question` | Ask structured questions through native interactive UI |
+| `rewind` | `/rewind` | Create and restore project snapshots around session lifecycle operations |
+| `router` | `/router` | Configure and probe Codex-style routing endpoints |
+| `statusline` | Footer status | Show concise extension-managed activity state |
+| `subagent` | `subagent`, `/agents` | Delegate bounded work to isolated child Pi sessions |
+| `todo` | `todo`, `/todos` | Track multi-step work with dependencies and status |
+
+See the [bundled extension catalog](extensions/README.md) for configuration and behavior details.
+
+## Context safety
+
+Long tool loops are checked after a completed tool batch and before another provider request. When the active context crosses the configured auto-compaction threshold, Pi compacts and rebuilds the context before continuing the same run. Cancellation, compaction failure, an unavailable cut point, or retained context that remains unsafe stops before another provider request.
+
+See [Compaction](../compaction.md).
+
+## Tool presentation
+
+Native tool calls use a consistent `●` call and `│` result shell with bounded collapsed output. Built-in semantic renderers remain responsible for paths, diffs, syntax highlighting, command output, and images.
+
+See [Native tool presentation](tool-presentation.md).
+
+## Themes
+
+The package includes `ice-cream-dark` and `ice-cream-light` alongside the standard `dark` and `light` themes.
+
+See [Bundled themes](themes.md) and [Theme authoring](../themes.md).

package/docs/bundled/extensions/README.md

@@ -0,0 +1,19 @@
+# Bundled extensions
+
+These are extensions shipped in the `@astralyn/pi` npm package. For the public API used to write external extensions, see the [Extension API documentation](../../extensions.md).
+
+They are registered as hidden built-in extensions and use the same public Extension API available to external extensions. Their implementation details are internal to the package and are not required for installation or configuration.
+
+| Extension | Tool or command | Documentation |
+|---|---|---|
+| `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) |
+| `router` | `/router` | [router.md](router.md) |
+| `statusline` | Footer | [statusline.md](statusline.md) |
+| `subagent` | `subagent`, `/agents` | [subagent.md](subagent.md) |
+
+The catalog documents installed-package behavior and configuration; it does not require access to the package's internal source.

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/{distribution → bundled}/extensions/question.md

@@ -46,14 +46,3 @@ The transcript uses a private `renderCall` / `renderResult` only to replace raw
 - `validateQuestions` enforces uniqueness, reserved-label rejection, and text budgets beyond what the JSON schema can express.
 - Dialog navigation follows Pi's injected select/input keybindings where applicable; custom actions such as Space-to-toggle remain explicit in the footer.
 
-**Files:**
-
-- `constants.ts` — tool identity and model-facing prompt copy
-- `index.ts` — tool registration and execution
-- `dialog.ts` — interactive dialog, review, and discussion flow
-- `schema.ts` — params and semantic validation
-- `state.ts` — per-question dialog state helpers and answer ordering
-- `results.ts` — bounded model-result builders
-- `render.ts` — compact transcript summaries within Pi's native tool frame
-- `limits.ts` — UI and model-output budgets
-- `types.ts` — shared interfaces and the `OTHER_OPTION` sentinel

package/docs/{distribution → 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
@@ -71,15 +82,5 @@ rebuilt from them on `session_start`.
 - **Config is memory-cached.** `config.json` is re-read on `session_start` and updated in memory when `/rewind` saves.
 - **Restore path is single-scan.** The `/tree` confirm pass caches changed absolute paths; IO is concurrency-capped (16).
 
-**Files:**
-
-- `index.ts` — lifecycle hooks (`tool_call`, `before_agent_start`, `agent_settled`, `session_start`, `session_before_tree`/`session_tree`, `session_shutdown`) and the `/rewind` command
-- `engine.ts` — the file-history backup engine (track / snapshot / apply / resume-migrate), ported from Claude Code's file-history
-- `snapshot.ts` — persisted snapshot data shapes (pure)
-- `config.ts` — load/save `rewind/config.json`
-- `gc.ts` — age + orphan storage reclamation; storage inventory for the menu
-- `menu.ts` — the `/rewind` settings + storage menu
-- `restore.ts` — `/tree`-target → snapshot matching and restore
-- `paths.ts`, `text.ts`, `tool-path.ts` — private helpers owned by this plugin
 
 Architecture informed by oh-my-pi (GPL-3.0) and Claude Code's file-history; independent implementation.

package/docs/{distribution → bundled}/extensions/router.md

@@ -4,7 +4,7 @@
 
 Configuration lives at `~/.pi/agent/router.json`.
 
-Providers are registered at extension load via `pi.registerProvider` (config form + `streamSimple`). They do **not** go through `models.json`. This follows Pi's documented custom-provider path ([providers.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md), [custom-provider.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/custom-provider.md)): the stream wraps the built-in `openAIResponsesApi()` from `@earendil-works/pi-ai/compat` (same approach as the GitLab Duo example), then reshapes the request for Codex-style relays.
+Providers are registered at extension load via `pi.registerProvider` (config form + `streamSimple`). They do **not** go through `models.json`. This follows Pi's documented custom-provider path ([providers.md](../../providers.md), [custom-provider.md](../../custom-provider.md)): the stream wraps the built-in `openAIResponsesApi()` from `@earendil-works/pi-ai/compat` (same approach as the GitLab Duo example), then reshapes the request for Codex-style relays.
 
 ---
 
@@ -123,17 +123,4 @@ Session affinity headers use hyphenated form (`session-id`, `x-client-request-id
 
 **Multi-turn tool calls.** On a fixed relay + fixed model, tool-call ids preserve the Responses form and replay like Codex. Pi only rewrites ids across model boundaries. Staying on one model for long tool + reasoning sessions avoids id sanitization.
 
-**Files:**
 
-| File | Role |
-|:-:|:-:|
-| `index.ts` | Async factory: load config, register providers, handle `/router` commands |
-| `store.ts` | `router.json` read / write |
-| `register.ts` | `registerProvider` / unregister |
-| `stream.ts` | Wraps `openAIResponsesApi` + payload reshape |
-| `probe.ts` | `GET …/models` catalog fetch |
-| `presets.ts` | 272k defaults + thinking-level map helpers |
-| `dialog.ts` | Selectors, multi-select, thinking editor (dirty Esc warning) |
-| `ui.ts` | Command flows; auto-save on relay mutations |
-| `constants.ts` | Command name, defaults, `router-codex` API tag |
-| `types.ts` | Config types |

package/docs/{distribution → bundled}/extensions/statusline.md

@@ -95,7 +95,7 @@ may be removed manually.
 
 ## Limits
 
-- Auto-enables only in TUI mode on `session_start`; RPC and print modes show the upstream footer.
+- Auto-enables only in TUI mode on `session_start`; RPC and print modes have no TUI footer.
 - The native `(auto)` compaction marker is not reproduced because Pi does not expose that state to extensions.
 
 ## Implementation notes
@@ -107,4 +107,3 @@ Footer paint is hot (every TUI render). The extension caches:
 
 Both caches clear on footer `invalidate()`.
 
-**Files:** `index.ts` — footer lifecycle, formatting, usage aggregation, and responsive two-line left/right layout.

package/docs/{distribution → 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.
 
@@ -93,10 +93,3 @@ They apply only to future subagent runs and never change the parent session's `/
 
 There are no background agents, persistent worker IDs, unread state, fleet panel, statusline widget, send/stop/resume control plane, completion notifications, swarm/coordinator, worktree isolation, nested agents, MCP, hooks, or agent memory.
 
-**Files:** `src/extensions/subagent/`
-
-- `index.ts` — registration, parent provider synchronization, `/agents`, shutdown cleanup
-- `agents.ts` / `settings.ts` / `resolve.ts` — profile discovery, persistent overrides, task validation
-- `sdk-runner.ts` / `runner.ts` — isolated sessions, progress, abort, concurrency, modes
-- `activity.ts` / `render.ts` — bounded evidence, usage, native transcript rendering
-- `schema.ts` / `types.ts` / `constants.ts` — public tool contract and data model

package/docs/bundled/extensions/todo.md

@@ -0,0 +1,28 @@
+# todo — task list overlay
+
+Adds a `todo` tool plus `/todos` for multi-step work, with a live overlay above the editor.
+
+## Behavior
+
+- Actions: `create`, `update`, `list`, `get`, `delete`, `clear`. Statuses: `pending`, `in_progress`, `completed`, `deleted`. `list` accepts an optional `status` filter and `includeDeleted`; `status: "deleted"` includes tombstones directly.
+- The live overlay renders above the editor and hides itself when there are no visible tasks.
+- Creation always starts a task as `pending`; `blockedBy` dependencies are supported for sequencing, and missing dependencies, deleted dependencies, self-dependencies, and cycles are rejected. A task cannot move to `in_progress` or `completed` until every `blockedBy` dependency is `completed`.
+- Deletion — via `delete` or `update` with `status: "deleted"` — leaves an immutable tombstone for branch history, removes that task from every dependent `blockedBy` list, and therefore releases dependents. `clear` empties the list without reusing ids.
+- Newly completed tasks remain visible for 30 seconds, then drop from the overlay; historical completions loaded by `/reload` or `/tree` stay hidden so live work remains prominent.
+- **Exactly one `in_progress`.** Moving a task to `in_progress` auto-demotes any other `in_progress` tasks to `pending`; the tool result lists demoted ids so the model sees the side effect.
+- **Verification soft nudge.** When a completion leaves the list fully done with 3+ completed tasks and no subject/description matching `verif|test|check|review`, the tool result appends a short NOTE (text only — `details` schema unchanged).
+
+## Limits
+
+- `list` output is bounded at 50 items by default, with a trailing notice when truncated.
+- The overlay body is capped at 10 rows; its truncation summary includes hidden status counts.
+- Newly completed tasks remain visible for 30 seconds then drop from the overlay.
+
+## Implementation notes
+
+- **Conversation-backed state.** Every tool result stores a full snapshot in `details`; lifecycle handlers replay the current branch on `/reload`, compaction, and session-tree navigation. There is no separate disk database. Compaction-safe by design: `sessionManager.getBranch()` returns the full branch history — only `buildSessionContext` summarizes for the LLM. Replay walks the branch **tail → head** and stops at the latest todo `toolResult`.
+- **State is keyed per session id.** Resume and `/tree` can switch sessions within one process; `execute` and the lifecycle handlers re-point the active bucket before touching state.
+- **Status transitions are gated.** `completed` can be reopened to `in_progress` or `pending`, but a `deleted` tombstone is terminal. Single-active is enforced on demote (not hard-reject) so the model does not need a retry loop.
+- **Tool execution is sequential** (`executionMode: "sequential"`) so parallel tool calls cannot race on in-memory state. Validation failures **throw** so Pi marks `isError: true` and the branch replays the last good snapshot.
+- **Overlay paint is pure + width-cached.** Completion visibility bookkeeping runs in `update()` plus a disposable timeout, never during `render`. Same terminal width reuses the last line array.
+

package/docs/{distribution → bundled}/themes.md

@@ -1,8 +1,8 @@
 # Bundled theme design
 
-This document describes the themes shipped by the distribution. For theme discovery, JSON format, and custom theme authoring, see the [Theme API documentation](../themes.md).
+This document describes the themes shipped in the `@astralyn/pi` package. For theme discovery, JSON format, and custom theme authoring, see the [Theme API documentation](../themes.md).
 
-The Fork bundles two Pi themes using the native theme schema and loader:
+The package bundles two Pi themes using the native theme schema and loader:
 
 | Theme | Use |
 |---|---|
@@ -46,13 +46,6 @@ The palette keeps an ice-cream / sea-salt identity: cool cyan-blue accents with
 
 Bundled dialogs, overlays, and the statusline use semantic theme helpers such as `theme.fg(...)` and `theme.bg(...)`. They do not hard-code ANSI colors or hex values.
 
-## Theme files
+## Theme assets
 
-The source assets are:
-
-```text
-src/modes/interactive/theme/ice-cream-dark.json
-src/modes/interactive/theme/ice-cream-light.json
-```
-
-The normal package build copies all theme JSON assets into the runtime package. The themes use the schema at `src/modes/interactive/theme/theme-schema.json`.
+The built-in theme names are stable user-facing identifiers. In an installed package, the JSON assets are available under `dist/modes/interactive/theme/` if you need to inspect them; normal use does not require accessing those internal files.