@code-yeongyu/senpi 2026.6.30 → 2026.7.3

package/node_modules/@earendil-works/pi-tui/dist/tui.js

@@ -6,6 +6,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
 import { isKeyRelease, matchesKey } from "./keys.js";
+import { isMultiplexerSession, useLegacyMuxRender, viewportRenderEnabled } from "./mux.js";
 import { isOsc11BackgroundColorResponse, parseOsc11BackgroundColor, parseTerminalColorSchemeReport, } from "./terminal-colors.js";
 import { deleteKittyImage, getCapabilities, isImageLine, setCellDimensions } from "./terminal-image.js";
 import { extractSegments, normalizeTerminalOutput, sliceByColumn, sliceWithWidth, visibleWidth } from "./utils.js";
@@ -55,6 +56,103 @@ export function isFocusable(component) {
  */
 export const CURSOR_MARKER = "\x1b_pi:c\x07";
 export { visibleWidth };
+const renderErrorLoggedClasses = new Set();
+let renderErrorLogWrites = 0;
+const DIAGNOSTIC_LOG_MODE = 0o600;
+const VIEWPORT_RENDER_OVERSCAN = 16;
+// Keep scroll-region wins cheap when a few visible rows mutate during append streaming.
+const MAX_SCROLL_DIFF_ROWS = 4;
+const viewportRenderStats = {
+    lastNormalizedLines: 0,
+    lastKittyImageScannedLines: 0,
+    totalNormalizedLines: 0,
+    totalKittyImageScannedLines: 0,
+    boundedFrames: 0,
+    escapedFrames: 0,
+    fullFrames: 0,
+};
+export function __renderErrorLogStats() {
+    if (process.env.PI_TUI_TEST_SEAMS !== "1") {
+        return undefined;
+    }
+    return { writes: renderErrorLogWrites };
+}
+export function __viewportRenderStats() {
+    if (process.env.PI_TUI_TEST_SEAMS !== "1") {
+        return undefined;
+    }
+    return { ...viewportRenderStats };
+}
+function recordViewportRenderStats(normalizedLines, mode) {
+    viewportRenderStats.lastNormalizedLines = normalizedLines;
+    viewportRenderStats.totalNormalizedLines += normalizedLines;
+    if (mode === "bounded") {
+        viewportRenderStats.boundedFrames += 1;
+    }
+    else if (mode === "escaped") {
+        viewportRenderStats.escapedFrames += 1;
+    }
+    else {
+        viewportRenderStats.fullFrames += 1;
+    }
+}
+function recordKittyImageScanStats(scannedLines) {
+    viewportRenderStats.lastKittyImageScannedLines = scannedLines;
+    viewportRenderStats.totalKittyImageScannedLines += scannedLines;
+}
+function componentRenderErrorName(component) {
+    return component.constructor.name || "AnonymousComponent";
+}
+function logRenderErrorOnce(component, error) {
+    const componentName = componentRenderErrorName(component);
+    if (renderErrorLoggedClasses.has(componentName)) {
+        return;
+    }
+    renderErrorLoggedClasses.add(componentName);
+    renderErrorLogWrites += 1;
+    const errorText = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    const logPath = path.join(os.homedir(), ".senpi", "agent", "senpi-debug.log");
+    const msg = `[${new Date().toISOString()}] render error: ${componentName}: ${errorText}\n`;
+    appendRenderErrorLogBestEffort(logPath, msg);
+}
+function appendRenderErrorLogBestEffort(logPath, msg) {
+    try {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        fs.appendFileSync(logPath, msg, { encoding: "utf8", mode: DIAGNOSTIC_LOG_MODE });
+        chmodDiagnosticLogBestEffort(logPath);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return;
+        }
+        throw error;
+    }
+}
+function writeRenderDiagnosticBestEffort(logPath, data) {
+    try {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        fs.writeFileSync(logPath, data, { encoding: "utf8", mode: DIAGNOSTIC_LOG_MODE });
+        chmodDiagnosticLogBestEffort(logPath);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return false;
+        }
+        throw error;
+    }
+}
+function chmodDiagnosticLogBestEffort(logPath) {
+    try {
+        fs.chmodSync(logPath, DIAGNOSTIC_LOG_MODE);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return;
+        }
+        throw error;
+    }
+}
 /** Parse a SizeValue into absolute value given a reference size */
 function parseSizeValue(value, referenceSize) {
     if (value === undefined)
@@ -120,7 +218,16 @@ export class Container {
     render(width) {
         const lines = [];
         for (const child of this.children) {
-            const childLines = child.render(width);
+            let childLines;
+            try {
+                childLines = child.render(width);
+            }
+            catch (error) {
+                logRenderErrorOnce(child, error);
+                const componentName = componentRenderErrorName(child);
+                // Focus ownership stays unchanged; render containment must not steal or clear focus implicitly.
+                childLines = [`[render error: ${componentName}]`];
+            }
             for (const line of childLines) {
                 lines.push(line);
             }
@@ -133,9 +240,12 @@ export class Container {
  */
 export class TUI extends Container {
     static { this.MIN_RENDER_INTERVAL_MS = 16; }
-    constructor(terminal, showHardwareCursor) {
+    #lastCursorVisibility;
+    #muxDetector;
+    constructor(terminal, options) {
         super();
         this.previousLines = [];
+        this.previousRawLines = [];
         this.previousKittyImageIds = new Set();
         this.previousWidth = 0;
         this.previousHeight = 0;
@@ -151,6 +261,8 @@ export class TUI extends Container {
         this.maxLinesRendered = 0; // Track terminal's working area (max lines ever rendered)
         this.previousViewportTop = 0; // Track previous viewport top for resize-aware cursor moves
         this.fullRedrawCount = 0;
+        this.muxViewportRepaintCount = 0;
+        this.overWideCrashDumpWritten = false;
         this.stopped = false;
         this.pendingOsc11BackgroundReplies = 0;
         this.pendingOsc11BackgroundQueries = [];
@@ -161,13 +273,19 @@ export class TUI extends Container {
         this.overlayStack = [];
         this.overlayFocusRestore = { status: "inactive" };
         this.terminal = terminal;
-        if (showHardwareCursor !== undefined) {
-            this.showHardwareCursor = showHardwareCursor;
+        // Preserve existing positional boolean callers while allowing explicit render-policy overrides.
+        const normalizedOptions = typeof options === "boolean" ? { showHardwareCursor: options } : (options ?? {});
+        this.#muxDetector = normalizedOptions.muxDetector ?? isMultiplexerSession;
+        if (normalizedOptions.showHardwareCursor !== undefined) {
+            this.showHardwareCursor = normalizedOptions.showHardwareCursor;
         }
     }
     get fullRedraws() {
         return this.fullRedrawCount;
     }
+    get muxViewportRepaints() {
+        return this.muxViewportRepaintCount;
+    }
     getShowHardwareCursor() {
         return this.showHardwareCursor;
     }
@@ -176,7 +294,7 @@ export class TUI extends Container {
             return;
         this.showHardwareCursor = enabled;
         if (!enabled) {
-            this.terminal.hideCursor();
+            this.#setCursorVisibility(false);
         }
         this.requestRender();
     }
@@ -318,7 +436,7 @@ export class TUI extends Container {
         if (!options?.nonCapturing && this.isOverlayVisible(entry)) {
             this.setFocus(component);
         }
-        this.terminal.hideCursor();
+        this.#setCursorVisibility(false);
         this.requestRender();
         // Return handle for controlling this overlay
         return {
@@ -334,7 +452,7 @@ export class TUI extends Container {
                         this.setFocus(topVisible?.component ?? entry.preFocus);
                     }
                     if (this.overlayStack.length === 0)
-                        this.terminal.hideCursor();
+                        this.#setCursorVisibility(false);
                     this.requestRender();
                 }
             },
@@ -416,7 +534,7 @@ export class TUI extends Container {
             this.setFocus(topVisible?.component ?? overlay.preFocus);
         }
         if (this.overlayStack.length === 0)
-            this.terminal.hideCursor();
+            this.#setCursorVisibility(false);
         this.requestRender();
     }
     /** Check if there are any visible overlays */
@@ -451,8 +569,9 @@ export class TUI extends Container {
     }
     start() {
         this.stopped = false;
+        this.#lastCursorVisibility = undefined;
         this.terminal.start((data) => this.handleInput(data), () => this.requestRender());
-        this.terminal.hideCursor();
+        this.#setCursorVisibility(false);
         if (this.terminalColorSchemeNotificationsEnabled) {
             this.terminal.write("\x1b[?2031h");
         }
@@ -513,9 +632,12 @@ export class TUI extends Container {
             }
             this.terminal.write("\r\n");
         }
-        this.terminal.showCursor();
+        this.#lastCursorVisibility = undefined;
+        this.#setCursorVisibility(true);
         this.terminal.stop();
+        this.#lastCursorVisibility = undefined;
         this.previousLines = [];
+        this.previousRawLines = [];
         this.previousKittyImageIds.clear();
         this.previousWidth = 0;
         this.previousHeight = 0;
@@ -524,10 +646,22 @@ export class TUI extends Container {
         this.maxLinesRendered = 0;
         this.previousViewportTop = 0;
     }
+    #setCursorVisibility(visible) {
+        if (this.#lastCursorVisibility === visible)
+            return;
+        if (visible) {
+            this.terminal.showCursor();
+        }
+        else {
+            this.terminal.hideCursor();
+        }
+        this.#lastCursorVisibility = visible;
+    }
     requestRender(force = false, source = "unknown") {
         if (force) {
             this.inputRenderPending = false;
             this.previousLines = [];
+            this.previousRawLines = [];
             this.previousWidth = -1; // -1 triggers widthChanged, forcing a full clear
             this.previousHeight = -1; // -1 triggers heightChanged, forcing a full clear
             this.cursorRow = 0;
@@ -892,17 +1026,96 @@ export class TUI extends Container {
         return result;
     }
     static { this.SEGMENT_RESET = "\x1b[0m\x1b]8;;\x07"; }
-    applyLineResets(lines) {
-        const reset = TUI.SEGMENT_RESET;
+    /**
+     * Every frame write is bracketed by synchronized output (DECSET 2026) and
+     * disables autowrap (DECAWM, DECRST 7) while rows are painted. Differential
+     * rendering tracks the cursor with relative moves only, so a row the
+     * terminal draws wider than visibleWidth() measured (East-Asian-ambiguous
+     * glyphs, emoji newer than the terminal's Unicode tables, decomposed jamo)
+     * would wrap, silently shift the cursor one row down, and leave stale ghost
+     * rows behind on every following diff. With autowrap off such rows clip at
+     * the last column instead. Autowrap is restored at frame end so the shell
+     * never observes the disabled state.
+     */
+    static { this.FRAME_BEGIN = "\x1b[?2026h\x1b[?7l"; }
+    static { this.FRAME_END = "\x1b[?7h\x1b[?2026l"; }
+    setPreviousLines(lines, rawLines) {
+        this.previousLines = lines;
+        this.previousRawLines = rawLines;
+    }
+    normalizeLine(line) {
+        if (isImageLine(line)) {
+            return { line, normalized: false };
+        }
+        return { line: normalizeTerminalOutput(line) + TUI.SEGMENT_RESET, normalized: true };
+    }
+    applyLineResets(lines, mode = "full") {
+        const normalizedLines = [];
+        let normalizedCount = 0;
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i];
-            if (!isImageLine(line)) {
-                lines[i] = normalizeTerminalOutput(line) + reset;
+            if (isImageLine(line)) {
+                normalizedLines.push(line);
+            }
+            else {
+                normalizedLines.push(normalizeTerminalOutput(line) + TUI.SEGMENT_RESET);
+                normalizedCount += 1;
             }
         }
-        return lines;
+        recordViewportRenderStats(normalizedCount, mode);
+        return {
+            lines: normalizedLines,
+            firstRawChanged: 0,
+            compareEndExclusive: normalizedLines.length,
+            bounded: false,
+        };
+    }
+    applyViewportLineResets(rawLines, viewportTop, height, stableDimensions) {
+        if (!viewportRenderEnabled() ||
+            !stableDimensions ||
+            this.previousLines.length === 0 ||
+            this.previousLines.length !== rawLines.length ||
+            this.previousRawLines.length !== rawLines.length) {
+            return this.applyLineResets(rawLines);
+        }
+        const windowStart = Math.max(0, viewportTop - VIEWPORT_RENDER_OVERSCAN);
+        const windowEnd = Math.min(rawLines.length, viewportTop + height + VIEWPORT_RENDER_OVERSCAN);
+        let firstRawChanged = -1;
+        for (let i = 0; i < rawLines.length; i++) {
+            if (rawLines[i] === this.previousRawLines[i]) {
+                continue;
+            }
+            if (firstRawChanged === -1) {
+                firstRawChanged = i;
+            }
+            if (i < windowStart || i >= windowEnd) {
+                return this.applyLineResets(rawLines, "escaped");
+            }
+        }
+        const lines = this.previousLines.slice();
+        let normalizedCount = 0;
+        if (firstRawChanged !== -1) {
+            for (let i = windowStart; i < windowEnd; i++) {
+                if (rawLines[i] === this.previousRawLines[i]) {
+                    continue;
+                }
+                const normalized = this.normalizeLine(rawLines[i] ?? "");
+                lines[i] = normalized.line;
+                if (normalized.normalized) {
+                    normalizedCount += 1;
+                }
+            }
+        }
+        recordViewportRenderStats(normalizedCount, "bounded");
+        return {
+            lines,
+            firstRawChanged,
+            compareEndExclusive: windowEnd,
+            bounded: true,
+        };
     }
     collectKittyImageIds(lines) {
+        recordKittyImageScanStats(lines.length);
         const ids = new Set();
         for (const line of lines) {
             for (const id of extractKittyImageIds(line)) {
@@ -950,6 +1163,24 @@ export class TUI extends Container {
         expandForLines(newLines);
         return { firstChanged: expandedFirstChanged, lastChanged: expandedLastChanged };
     }
+    changedRangeNeedsKittyImageExpansion(lines, firstChanged, lastChanged) {
+        if (this.previousKittyImageIds.size > 0) {
+            return true;
+        }
+        const start = Math.max(0, firstChanged);
+        const end = Math.min(lines.length - 1, lastChanged);
+        let scannedLines = 0;
+        for (let i = start; i <= end; i++) {
+            scannedLines += 1;
+            const line = lines[i] ?? "";
+            if (isImageLine(line) || extractKittyImageIds(line).length > 0) {
+                recordKittyImageScanStats(scannedLines);
+                return true;
+            }
+        }
+        recordKittyImageScanStats(scannedLines);
+        return false;
+    }
     deleteChangedKittyImages(firstChanged, lastChanged) {
         if (firstChanged < 0 || lastChanged < firstChanged)
             return "";
@@ -965,6 +1196,9 @@ export class TUI extends Container {
     getViewportRows(lines, viewportTop, height) {
         return Array.from({ length: height }, (_, row) => lines[viewportTop + row] ?? "");
     }
+    shouldPreserveMuxScrollback() {
+        return this.#muxDetector() && !useLegacyMuxRender();
+    }
     createViewportInsertScrollPlan(newLines, prevViewportTop, height, lineCountDelta) {
         if (lineCountDelta <= 0 || lineCountDelta >= height || this.overlayStack.length > 0) {
             return undefined;
@@ -988,19 +1222,24 @@ export class TUI extends Container {
         if (regionHeight <= 0 || regionHeight < lineCountDelta) {
             return undefined;
         }
+        const mutatedRows = [];
         for (let row = 0; row < regionHeight - lineCountDelta; row++) {
             if (previousVisible[row + lineCountDelta] !== nextVisible[row]) {
-                return undefined;
+                mutatedRows.push({ screenRow: row, content: nextVisible[row] });
+                if (mutatedRows.length > MAX_SCROLL_DIFF_ROWS) {
+                    return undefined;
+                }
             }
         }
         return {
             viewportTop,
             regionBottom: regionHeight - 1,
             insertedRows: nextVisible.slice(regionHeight - lineCountDelta, regionHeight),
+            mutatedRows,
         };
     }
-    renderViewportInsertScroll(plan, newLines, cursorPos, width, height) {
-        let buffer = "\x1b[?2026h";
+    renderViewportInsertScroll(plan, newLines, rawLines, cursorPos, width, height) {
+        let buffer = TUI.FRAME_BEGIN;
         const regionTop = 0;
         const regionBottom = plan.regionBottom;
         buffer += `\x1b[${regionTop + 1};${regionBottom + 1}r`;
@@ -1008,27 +1247,35 @@ export class TUI extends Container {
         buffer += "\n".repeat(plan.insertedRows.length);
         buffer += "\x1b[r";
         const firstInsertedScreenRow = regionBottom - plan.insertedRows.length + 1;
+        let finalPaintedScreenRow = firstInsertedScreenRow + plan.insertedRows.length - 1;
         for (let index = 0; index < plan.insertedRows.length; index++) {
             const screenRow = firstInsertedScreenRow + index;
-            buffer += `\x1b[${screenRow + 1};1H\x1b[2K`;
+            buffer += `\x1b[${screenRow + 1};1H\x1b[2K${TUI.SEGMENT_RESET}`;
             buffer += plan.insertedRows[index] ?? "";
         }
-        buffer += "\x1b[?2026l";
+        for (const row of plan.mutatedRows) {
+            buffer += `\x1b[${row.screenRow + 1};1H\x1b[2K${TUI.SEGMENT_RESET}`;
+            buffer += row.content;
+            finalPaintedScreenRow = row.screenRow;
+        }
+        buffer += TUI.FRAME_END;
         this.terminal.write(buffer);
         this.cursorRow = Math.max(0, newLines.length - 1);
-        this.hardwareCursorRow = plan.viewportTop + firstInsertedScreenRow + plan.insertedRows.length - 1;
+        this.hardwareCursorRow = plan.viewportTop + finalPaintedScreenRow;
         this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);
         this.previousViewportTop = plan.viewportTop;
         this.positionHardwareCursor(cursorPos, newLines.length);
-        this.previousLines = newLines;
+        this.setPreviousLines(newLines, rawLines);
         this.previousKittyImageIds = this.collectKittyImageIds(newLines);
         this.previousWidth = width;
         this.previousHeight = height;
     }
-    renderScrollbackReplay(newLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow) {
-        let buffer = "\x1b[?2026h";
+    renderScrollbackReplay(newLines, rawLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow) {
+        let buffer = TUI.FRAME_BEGIN;
         buffer += this.deleteKittyImages(this.previousKittyImageIds);
-        buffer += "\x1b[3J";
+        if (!this.shouldPreserveMuxScrollback()) {
+            buffer += "\x1b[3J";
+        }
         const currentScreenRow = Math.max(0, Math.min(height - 1, hardwareCursorRow - prevViewportTop));
         if (currentScreenRow > 0) {
             buffer += `\x1b[${currentScreenRow}A`;
@@ -1037,21 +1284,52 @@ export class TUI extends Container {
         for (let row = 0; row < bufferLength; row++) {
             if (row > 0)
                 buffer += "\r\n";
-            buffer += "\r\x1b[2K";
+            buffer += `\r\x1b[2K${TUI.SEGMENT_RESET}`;
             buffer += newLines[row] ?? "";
         }
-        buffer += "\x1b[?2026l";
+        buffer += TUI.FRAME_END;
         this.terminal.write(buffer);
         this.cursorRow = Math.max(0, newLines.length - 1);
         this.hardwareCursorRow = bufferLength - 1;
         this.maxLinesRendered = newLines.length;
         this.previousViewportTop = Math.max(0, bufferLength - height);
         this.positionHardwareCursor(cursorPos, newLines.length);
-        this.previousLines = newLines;
+        this.setPreviousLines(newLines, rawLines);
         this.previousKittyImageIds = this.collectKittyImageIds(newLines);
         this.previousWidth = width;
         this.previousHeight = height;
     }
+    renderMuxViewportRepaint(newLines, rawLines, cursorPos, width, height, viewportTop = Math.max(0, newLines.length - height)) {
+        const previousVisible = this.getViewportRows(this.previousLines, this.previousViewportTop, height);
+        const nextVisible = this.getViewportRows(newLines, viewportTop, height);
+        if (previousVisible.some(isImageLine) || nextVisible.some(isImageLine)) {
+            return false;
+        }
+        let buffer = TUI.FRAME_BEGIN;
+        const currentScreenRow = Math.max(0, Math.min(height - 1, this.hardwareCursorRow - this.previousViewportTop));
+        if (currentScreenRow > 0) {
+            buffer += `\x1b[${currentScreenRow}A`;
+        }
+        for (let row = 0; row < height; row++) {
+            if (row > 0)
+                buffer += "\r\n";
+            buffer += `\r\x1b[2K${TUI.SEGMENT_RESET}`;
+            buffer += newLines[viewportTop + row] ?? "";
+        }
+        buffer += TUI.FRAME_END;
+        this.terminal.write(buffer);
+        this.muxViewportRepaintCount += 1;
+        this.cursorRow = Math.max(0, newLines.length - 1);
+        this.hardwareCursorRow = viewportTop + Math.max(0, height - 1);
+        this.maxLinesRendered = newLines.length;
+        this.previousViewportTop = viewportTop;
+        this.positionHardwareCursor(cursorPos, newLines.length);
+        this.setPreviousLines(newLines, rawLines);
+        this.previousKittyImageIds = this.collectKittyImageIds(newLines);
+        this.previousWidth = width;
+        this.previousHeight = height;
+        return true;
+    }
     /** Splice overlay content into a base line at a specific column. Single-pass optimized. */
     compositeLineAt(baseLine, overlayLine, startCol, overlayWidth, totalWidth) {
         if (isImageLine(baseLine))
@@ -1140,17 +1418,23 @@ export class TUI extends Container {
         }
         // Extract cursor position before applying line resets (marker must be found first)
         const cursorPos = this.extractCursorPosition(newLines, height);
-        newLines = this.applyLineResets(newLines);
+        const rawLines = newLines;
+        const normalizedLines = this.applyViewportLineResets(rawLines, prevViewportTop, height, !widthChanged && !heightChanged);
+        newLines = normalizedLines.lines;
+        const preserveMuxScrollback = this.shouldPreserveMuxScrollback();
         // Helper to clear scrollback and viewport and render all new lines
-        const fullRender = (clear) => {
+        const fullRender = (clear, clearScrollback = clear) => {
             this.fullRedrawCount += 1;
-            let buffer = "\x1b[?2026h"; // Begin synchronized output
+            let buffer = TUI.FRAME_BEGIN;
             if (clear) {
                 buffer += this.deleteKittyImages(this.previousKittyImageIds);
-                buffer += "\x1b[2J\x1b[H\x1b[3J"; // Clear screen, home, then clear scrollback
+                buffer += "\x1b[2J\x1b[H";
+                if (clearScrollback && !preserveMuxScrollback) {
+                    buffer += "\x1b[3J";
+                }
             }
             else {
-                buffer += "\r\x1b[2K";
+                buffer += `\r\x1b[2K${TUI.SEGMENT_RESET}`;
             }
             for (let i = 0; i < newLines.length; i++) {
                 if (i > 0)
@@ -1170,7 +1454,7 @@ export class TUI extends Container {
                 }
                 buffer += line;
             }
-            buffer += "\x1b[?2026l"; // End synchronized output
+            buffer += TUI.FRAME_END;
             this.terminal.write(buffer);
             this.cursorRow = Math.max(0, newLines.length - 1);
             this.hardwareCursorRow = this.cursorRow;
@@ -1184,7 +1468,7 @@ export class TUI extends Container {
             const bufferLength = Math.max(height, newLines.length);
             this.previousViewportTop = Math.max(0, bufferLength - height);
             this.positionHardwareCursor(cursorPos, newLines.length);
-            this.previousLines = newLines;
+            this.setPreviousLines(newLines, rawLines);
             this.previousKittyImageIds = this.collectKittyImageIds(newLines);
             this.previousWidth = width;
             this.previousHeight = height;
@@ -1195,7 +1479,8 @@ export class TUI extends Container {
                 return;
             const logPath = path.join(os.homedir(), ".senpi", "agent", "senpi-debug.log");
             const msg = `[${new Date().toISOString()}] fullRender: ${reason} (prev=${this.previousLines.length}, new=${newLines.length}, height=${height})\n`;
-            fs.appendFileSync(logPath, msg);
+            fs.appendFileSync(logPath, msg, { encoding: "utf8", mode: DIAGNOSTIC_LOG_MODE });
+            chmodDiagnosticLogBestEffort(logPath);
         };
         // First render - just output everything without clearing (assumes clean screen)
         if (this.previousLines.length === 0 && !widthChanged && !heightChanged) {
@@ -1206,7 +1491,8 @@ export class TUI extends Container {
         // Width changes always need a full re-render because wrapping changes.
         if (widthChanged) {
             logRedraw(`terminal width changed (${this.previousWidth} -> ${width})`);
-            fullRender(true);
+            // In multiplexers, re-emit the viewport without 3J so pane history survives; an older copy may remain above.
+            fullRender(true, !preserveMuxScrollback);
             return;
         }
         // Height changes normally need a full re-render to keep the visible viewport aligned,
@@ -1214,7 +1500,14 @@ export class TUI extends Container {
         // In that environment, a full redraw causes the entire history to replay on every toggle.
         if (heightChanged && !isTermuxSession()) {
             logRedraw(`terminal height changed (${this.previousHeight} -> ${height})`);
-            fullRender(true);
+            if (preserveMuxScrollback) {
+                if (!this.renderMuxViewportRepaint(newLines, rawLines, cursorPos, width, height)) {
+                    fullRender(true, false);
+                }
+            }
+            else {
+                fullRender(true);
+            }
             return;
         }
         // Content shrunk below the working area and no overlays - re-render to clear empty rows
@@ -1222,14 +1515,16 @@ export class TUI extends Container {
         // Configurable via setClearOnShrink() or PI_CLEAR_ON_SHRINK=0 env var
         if (this.clearOnShrink && newLines.length < this.maxLinesRendered && this.overlayStack.length === 0) {
             logRedraw(`clearOnShrink (maxLinesRendered=${this.maxLinesRendered})`);
-            fullRender(true);
+            fullRender(true, !preserveMuxScrollback);
             return;
         }
         // Find first and last changed lines
         let firstChanged = -1;
         let lastChanged = -1;
         const maxLines = Math.max(newLines.length, this.previousLines.length);
-        for (let i = 0; i < maxLines; i++) {
+        const diffScanStart = normalizedLines.bounded && normalizedLines.firstRawChanged !== -1 ? normalizedLines.firstRawChanged : 0;
+        const diffScanEndExclusive = normalizedLines.bounded ? normalizedLines.compareEndExclusive : maxLines;
+        for (let i = diffScanStart; i < diffScanEndExclusive; i++) {
             const oldLine = i < this.previousLines.length ? this.previousLines[i] : "";
             const newLine = i < newLines.length ? newLines[i] : "";
             if (oldLine !== newLine) {
@@ -1247,7 +1542,8 @@ export class TUI extends Container {
             }
             lastChanged = newLines.length - 1;
         }
-        if (firstChanged !== -1) {
+        const needsKittyImageExpansion = firstChanged !== -1 && this.changedRangeNeedsKittyImageExpansion(newLines, firstChanged, lastChanged);
+        if (needsKittyImageExpansion) {
             const expandedRange = this.expandChangedRangeForKittyImages(firstChanged, lastChanged, newLines);
             firstChanged = expandedRange.firstChanged;
             lastChanged = expandedRange.lastChanged;
@@ -1262,19 +1558,19 @@ export class TUI extends Container {
             return;
         }
         if (insertScrollPlan) {
-            this.renderViewportInsertScroll(insertScrollPlan, newLines, cursorPos, width, height);
+            this.renderViewportInsertScroll(insertScrollPlan, newLines, rawLines, cursorPos, width, height);
             return;
         }
         // All changes are in deleted lines (nothing to render, just clear)
         if (firstChanged >= newLines.length) {
             if (this.previousLines.length > newLines.length) {
-                let buffer = "\x1b[?2026h";
+                let buffer = TUI.FRAME_BEGIN;
                 buffer += this.deleteChangedKittyImages(firstChanged, lastChanged);
                 // Move to end of new content (clamp to 0 for empty content)
                 const targetRow = Math.max(0, newLines.length - 1);
                 if (targetRow < prevViewportTop) {
                     logRedraw(`deleted lines moved viewport up (${targetRow} < ${prevViewportTop})`);
-                    fullRender(true);
+                    fullRender(true, !preserveMuxScrollback);
                     return;
                 }
                 const lineDiff = computeLineDiff(targetRow);
@@ -1287,7 +1583,7 @@ export class TUI extends Container {
                 const extraLines = this.previousLines.length - newLines.length;
                 if (extraLines > height) {
                     logRedraw(`extraLines > height (${extraLines} > ${height})`);
-                    fullRender(true);
+                    fullRender(true, !preserveMuxScrollback);
                     return;
                 }
                 const clearStartOffset = newLines.length === 0 ? 0 : 1;
@@ -1295,7 +1591,7 @@ export class TUI extends Container {
                     buffer += `\x1b[${clearStartOffset}B`;
                 }
                 for (let i = 0; i < extraLines; i++) {
-                    buffer += "\r\x1b[2K";
+                    buffer += `\r\x1b[2K${TUI.SEGMENT_RESET}`;
                     if (i < extraLines - 1)
                         buffer += "\x1b[1B";
                 }
@@ -1303,13 +1599,13 @@ export class TUI extends Container {
                 if (moveBack > 0) {
                     buffer += `\x1b[${moveBack}A`;
                 }
-                buffer += "\x1b[?2026l";
+                buffer += TUI.FRAME_END;
                 this.terminal.write(buffer);
                 this.cursorRow = targetRow;
                 this.hardwareCursorRow = targetRow;
             }
             this.positionHardwareCursor(cursorPos, newLines.length);
-            this.previousLines = newLines;
+            this.setPreviousLines(newLines, rawLines);
             this.previousKittyImageIds = this.collectKittyImageIds(newLines);
             this.previousWidth = width;
             this.previousHeight = height;
@@ -1339,12 +1635,20 @@ export class TUI extends Container {
             }
             if (firstVisibleChanged === -1) {
                 if (lineCountDelta !== 0) {
-                    this.renderScrollbackReplay(newLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow);
+                    if (preserveMuxScrollback) {
+                        // Above-viewport scrollback may stay stale in mux panes; only the visible viewport is repainted.
+                        if (!this.renderMuxViewportRepaint(newLines, rawLines, cursorPos, width, height, viewportTop)) {
+                            fullRender(true, false);
+                        }
+                    }
+                    else {
+                        this.renderScrollbackReplay(newLines, rawLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow);
+                    }
                     return;
                 }
                 this.cursorRow = Math.max(0, newLines.length - 1);
                 this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);
-                this.previousLines = newLines;
+                this.setPreviousLines(newLines, rawLines);
                 this.previousWidth = width;
                 this.previousHeight = height;
                 this.previousViewportTop = viewportTop;
@@ -1352,7 +1656,7 @@ export class TUI extends Container {
             }
             if (viewportTop !== prevViewportTop) {
                 const previousViewportBottom = Math.min(this.previousLines.length - 1, prevViewportTop + height - 1);
-                let buffer = "\x1b[?2026h";
+                let buffer = TUI.FRAME_BEGIN;
                 buffer += this.deleteChangedKittyImages(prevViewportTop, previousViewportBottom);
                 const currentScreenRow = Math.max(0, Math.min(height - 1, hardwareCursorRow - prevViewportTop));
                 if (currentScreenRow > 0) {
@@ -1361,17 +1665,17 @@ export class TUI extends Container {
                 for (let row = 0; row < height; row++) {
                     if (row > 0)
                         buffer += "\r\n";
-                    buffer += "\r\x1b[2K";
+                    buffer += `\r\x1b[2K${TUI.SEGMENT_RESET}`;
                     buffer += newLines[viewportTop + row] ?? "";
                 }
-                buffer += "\x1b[?2026l";
+                buffer += TUI.FRAME_END;
                 this.terminal.write(buffer);
                 this.cursorRow = Math.max(0, newLines.length - 1);
                 this.hardwareCursorRow = viewportTop + Math.max(0, height - 1);
                 this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);
                 this.previousViewportTop = viewportTop;
                 this.positionHardwareCursor(cursorPos, newLines.length);
-                this.previousLines = newLines;
+                this.setPreviousLines(newLines, rawLines);
                 this.previousKittyImageIds = this.collectKittyImageIds(newLines);
                 this.previousWidth = width;
                 this.previousHeight = height;
@@ -1382,7 +1686,7 @@ export class TUI extends Container {
         }
         // Render from first changed line to end
         // Build buffer with all updates wrapped in synchronized output
-        let buffer = "\x1b[?2026h"; // Begin synchronized output
+        let buffer = TUI.FRAME_BEGIN;
         buffer += this.deleteChangedKittyImages(firstChanged, lastChanged);
         const prevViewportBottom = prevViewportTop + height - 1;
         const moveTargetRow = appendStart ? firstChanged - 1 : firstChanged;
@@ -1420,12 +1724,12 @@ export class TUI extends Container {
                 const imageStartScreenRow = i - viewportTop;
                 if (imageStartScreenRow < 0 || imageStartScreenRow + imageReservedRows > height) {
                     logRedraw(`kitty image pre-clear would scroll (${imageStartScreenRow} + ${imageReservedRows} > ${height})`);
-                    fullRender(true);
+                    fullRender(true, !preserveMuxScrollback);
                     return;
                 }
-                buffer += "\x1b[2K";
+                buffer += `\x1b[2K${TUI.SEGMENT_RESET}`;
                 for (let row = 1; row < imageReservedRows; row++) {
-                    buffer += "\r\n\x1b[2K";
+                    buffer += `\r\n\x1b[2K${TUI.SEGMENT_RESET}`;
                 }
                 buffer += `\x1b[${imageReservedRows - 1}A`;
                 buffer += line;
@@ -1433,32 +1737,44 @@ export class TUI extends Container {
                 i += imageReservedRows - 1;
                 continue;
             }
-            buffer += "\x1b[2K"; // Clear current line
-            if (!isImage && visibleWidth(line) > width) {
+            buffer += `\x1b[2K${TUI.SEGMENT_RESET}`; // Clear current line
+            const lineWidth = visibleWidth(line);
+            if (!isImage && lineWidth > width) {
                 // Log all lines to crash file for debugging
                 const crashLogPath = path.join(os.homedir(), ".senpi", "agent", "senpi-crash.log");
                 const crashData = [
                     `Crash at ${new Date().toISOString()}`,
                     `Terminal width: ${width}`,
-                    `Line ${i} visible width: ${visibleWidth(line)}`,
+                    `Line ${i} visible width: ${lineWidth}`,
                     "",
                     "=== All rendered lines ===",
                     ...newLines.map((l, idx) => `[${idx}] (w=${visibleWidth(l)}) ${l}`),
                     "",
                 ].join("\n");
-                fs.mkdirSync(path.dirname(crashLogPath), { recursive: true });
-                fs.writeFileSync(crashLogPath, crashData);
-                // Clean up terminal state before throwing
-                this.stop();
-                const errorMsg = [
-                    `Rendered line ${i} exceeds terminal width (${visibleWidth(line)} > ${width}).`,
-                    "",
-                    "This is likely caused by a custom TUI component not truncating its output.",
-                    "Use visibleWidth() to measure and truncateToWidth() to truncate lines.",
-                    "",
-                    `Debug log written to: ${crashLogPath}`,
-                ].join("\n");
-                throw new Error(errorMsg);
+                if (process.env.PI_TUI_STRICT_RENDER === "1") {
+                    const crashDumpWritten = writeRenderDiagnosticBestEffort(crashLogPath, crashData);
+                    // Clean up terminal state before throwing
+                    this.stop();
+                    const errorMsg = [
+                        `Rendered line ${i} exceeds terminal width (${lineWidth} > ${width}).`,
+                        "",
+                        "This is likely caused by a custom TUI component not truncating its output.",
+                        "Use visibleWidth() to measure and truncateToWidth() to truncate lines.",
+                        "",
+                        crashDumpWritten
+                            ? `Debug log written to: ${crashLogPath}`
+                            : `Debug log could not be written to: ${crashLogPath}`,
+                    ].join("\n");
+                    throw new Error(errorMsg);
+                }
+                if (!this.overWideCrashDumpWritten) {
+                    writeRenderDiagnosticBestEffort(crashLogPath, crashData);
+                    this.overWideCrashDumpWritten = true;
+                }
+                const truncatedLine = sliceByColumn(line, 0, width, true) + TUI.SEGMENT_RESET;
+                newLines[i] = truncatedLine;
+                buffer += truncatedLine;
+                continue;
             }
             buffer += line;
         }
@@ -1474,12 +1790,12 @@ export class TUI extends Container {
             }
             const extraLines = this.previousLines.length - newLines.length;
             for (let i = newLines.length; i < this.previousLines.length; i++) {
-                buffer += "\r\n\x1b[2K";
+                buffer += `\r\n\x1b[2K${TUI.SEGMENT_RESET}`;
             }
             // Move cursor back to end of new content
             buffer += `\x1b[${extraLines}A`;
         }
-        buffer += "\x1b[?2026l"; // End synchronized output
+        buffer += TUI.FRAME_END;
         if (process.env.PI_TUI_DEBUG === "1") {
             const debugDir = "/tmp/tui";
             fs.mkdirSync(debugDir, { recursive: true });
@@ -1506,7 +1822,8 @@ export class TUI extends Container {
                 "=== buffer ===",
                 JSON.stringify(buffer),
             ].join("\n");
-            fs.writeFileSync(debugPath, debugData);
+            fs.writeFileSync(debugPath, debugData, { encoding: "utf8", mode: DIAGNOSTIC_LOG_MODE });
+            chmodDiagnosticLogBestEffort(debugPath);
         }
         // Write entire buffer at once
         this.terminal.write(buffer);
@@ -1520,8 +1837,10 @@ export class TUI extends Container {
         this.previousViewportTop = Math.max(prevViewportTop, finalCursorRow - height + 1);
         // Position hardware cursor for IME
         this.positionHardwareCursor(cursorPos, newLines.length);
-        this.previousLines = newLines;
-        this.previousKittyImageIds = this.collectKittyImageIds(newLines);
+        this.setPreviousLines(newLines, rawLines);
+        if (needsKittyImageExpansion) {
+            this.previousKittyImageIds = this.collectKittyImageIds(newLines);
+        }
         this.previousWidth = width;
         this.previousHeight = height;
     }
@@ -1531,34 +1850,36 @@ export class TUI extends Container {
      * @param totalLines Total number of rendered lines
      */
     positionHardwareCursor(cursorPos, totalLines) {
-        if (!cursorPos || totalLines <= 0) {
-            this.terminal.hideCursor();
-            return;
-        }
-        // Clamp cursor position to valid range
-        const targetRow = Math.max(0, Math.min(cursorPos.row, totalLines - 1));
-        const targetCol = Math.max(0, cursorPos.col);
-        // Move cursor from current position to target
-        const rowDelta = targetRow - this.hardwareCursorRow;
         let buffer = "";
-        if (rowDelta > 0) {
-            buffer += `\x1b[${rowDelta}B`; // Move down
+        if (!cursorPos || totalLines <= 0) {
+            if (this.#lastCursorVisibility !== false) {
+                buffer += "\x1b[?25l";
+                this.#lastCursorVisibility = false;
+            }
         }
-        else if (rowDelta < 0) {
-            buffer += `\x1b[${-rowDelta}A`; // Move up
+        else {
+            // Clamp cursor position to valid range
+            const targetRow = Math.max(0, Math.min(cursorPos.row, totalLines - 1));
+            const targetCol = Math.max(0, cursorPos.col);
+            // Move cursor from current position to target
+            const rowDelta = targetRow - this.hardwareCursorRow;
+            if (rowDelta > 0) {
+                buffer += `\x1b[${rowDelta}B`; // Move down
+            }
+            else if (rowDelta < 0) {
+                buffer += `\x1b[${-rowDelta}A`; // Move up
+            }
+            // Move to absolute column (1-indexed)
+            buffer += `\x1b[${targetCol + 1}G`;
+            this.hardwareCursorRow = targetRow;
+            if (this.#lastCursorVisibility !== this.showHardwareCursor) {
+                buffer += this.showHardwareCursor ? "\x1b[?25h" : "\x1b[?25l";
+                this.#lastCursorVisibility = this.showHardwareCursor;
+            }
         }
-        // Move to absolute column (1-indexed)
-        buffer += `\x1b[${targetCol + 1}G`;
         if (buffer) {
             this.terminal.write(buffer);
         }
-        this.hardwareCursorRow = targetRow;
-        if (this.showHardwareCursor) {
-            this.terminal.showCursor();
-        }
-        else {
-            this.terminal.hideCursor();
-        }
     }
     /**
      * Query the terminal's default background color with OSC 11 (`ESC ] 11 ; ? BEL`).