tmux-ide 2.9.6 → 2.9.8

package/packages/daemon/dist/terminal/mirror/control-channel.js

@@ -868,6 +868,16 @@ export class ControlChannelCore {
         }));
     }
 }
+/**
+ * Server-wide, idempotent: `-q` keeps a stock tmux (no such option) quiet.
+ * Images reach this control client either way; the option only lets programs
+ * detect support, and the environment tells new panes' programs that this
+ * server's renderer shows placeholder images.
+ */
+export const KITTY_GRAPHICS_SETUP = [
+    "set-option -gq kitty-graphics on",
+    "set-environment -g TMUX_IDE_GRAPHICS kitty",
+];
 export function mirrorControlAttachArgs(options, pauseAfterSeconds = DEFAULT_PAUSE_AFTER_SECONDS) {
     const attach = [
         "attach",
@@ -1009,7 +1019,13 @@ export class MirrorControlChannel {
                 this.core.fail(String(err));
                 reject(err);
             });
-        }).then(() => this.initializeNativeViewer());
+        }).then(() => {
+            // One command per send: tmux answers a `;` list with one block per command.
+            if (this.opts.kittyGraphics)
+                for (const command of KITTY_GRAPHICS_SETUP)
+                    this.send(command);
+            return this.initializeNativeViewer();
+        });
     }
     get nativeViewerIdentity() {
         return this.viewerIdentity ? { ...this.viewerIdentity } : null;

package/packages/daemon/dist/terminal/mirror/mirror-service.js

@@ -369,6 +369,12 @@ export class MirrorService {
         this.assertWindowOwnership(session);
         entry.channel.fitWindowViewport(semanticWindowId, cols, rows);
     }
+    setCellPixels(session, width, height, precise) {
+        const entry = this.channels.get(session);
+        if (!entry || entry.retired)
+            return;
+        entry.channel.setCellPixels(width, height, precise);
+    }
     clearWindowViewports(session) {
         const entry = this.channels.get(session);
         if (entry && !entry.retired)
@@ -532,6 +538,7 @@ export class MirrorService {
                             nativeServerIdentity: this.opts.nativeServerIdentity,
                             configFile: this.opts.configFile,
                             pauseAfterSeconds: this.opts.pauseAfterSeconds,
+                            kittyGraphics: this.opts.kittyGraphics ?? process.env.TMUX_IDE_KITTY_GRAPHICS !== "0",
                             nowMicros: this.opts.nowMicros,
                             nativeViewer: ownedViewer?.controlOptions(),
                             nativeViewerReady: ownedViewer

package/packages/daemon/dist/terminal/mirror/native-grid-capture.js

@@ -1,3 +1,11 @@
+/** Upstream tmux 3.8 reuses -R for a textual grid dump, not our JSON extension.
+ * Require the generated grid and first-row headers; arbitrary malformed native
+ * replies must remain errors rather than silently downgrading capture fidelity.
+ */
+export function isStockRawGridCapture(lines) {
+    return (/^G [1-9][0-9]*x[1-9][0-9]* \([0-9]+\/[0-9]+\)$/.test(lines[0] ?? "") &&
+        /^\tL 0 \((?:-|0)\) flags=/.test(lines[1] ?? ""));
+}
 const MAX_BYTES = 16 * 1024 * 1024;
 const MAX_ROWS = MAX_BYTES / 64;
 const MAX_CELLS = 1_000_000;

package/packages/daemon/dist/terminal/mirror/native-grid-reader.js

@@ -1,4 +1,4 @@
-import { decodeNativeGridCapture } from "./native-grid-capture.js";
+import { decodeNativeGridCapture, isStockRawGridCapture, } from "./native-grid-capture.js";
 /** One experimental capability owner per control connection. */
 export class NativeGridCaptureReader {
     io;
@@ -57,6 +57,11 @@ export class NativeGridCaptureReader {
                         finish({ status: "changed" });
                         return;
                     }
+                    if (isStockRawGridCapture(reply.lines)) {
+                        this.unsupported = true;
+                        finish({ status: "unsupported" });
+                        return;
+                    }
                     const snapshot = decodeNativeGridCapture(reply.lines.join("\n"));
                     finish(snapshot
                         ? {

package/packages/daemon/dist/terminal/mirror/session-channel.js

@@ -1,7 +1,7 @@
 import { layoutContentRows } from "./layout-content-rows.js";
 import { decodeNativeAtomicSnapshot, decodeNativeAtomicDualSnapshot, nativeAtomicDualSnapshotPlan, nativeAtomicSnapshotPlan, } from "./native-atomic-snapshot.js";
 import { boundedTmuxInteractionAppendCommand } from "../../lib/tmux-interaction-retention.js";
-import { decodeNativeGridCapture, isNativeBootstrapCapture, } from "./native-grid-capture.js";
+import { decodeNativeGridCapture, isStockRawGridCapture, isNativeBootstrapCapture, } from "./native-grid-capture.js";
 /**
  * SessionChannel — one control-mode channel serving every pane subscription
  * of one tmux session (m43 card 1).
@@ -114,7 +114,8 @@ const RECOVERY_CURSOR_PROBE_FORMAT = [
 /** Cache only proven server capability; malformed or failed reads can recover. */
 function nativeBootstrapUnsupported(ok, lines, native) {
     if (ok)
-        return native !== null && (native.version !== 2 || native.currentAttributes === undefined);
+        return (isStockRawGridCapture(lines) ||
+            (native !== null && (native.version !== 2 || native.currentAttributes === undefined)));
     return lines.some((line) => /^(?:parse error: )?(?:command capture-pane: )?unknown flag -R$/.test(line.trim()));
 }
 const FAILED_RESEED_RESULT = Object.freeze({
@@ -852,7 +853,50 @@ export class SessionChannel {
         this.input.flush();
         this.clearWindowViewports();
         this.restoreWindowSizing(this.attachedIdentity?.runtimeSessionId ?? `=${this.opts.session}`);
-        this.io.send(`refresh-client -C ${cols}x${rows}`);
+        this.io.send(`refresh-client -C ${cols}x${rows}${this.cellPixelSuffix()}`);
+        this.clientViewport = { cols, rows };
+    }
+    clientViewport = null;
+    cellPixels = null;
+    /** "/WxH" for tmux's refresh-client -C (patched tmux; stock ignores it). */
+    cellPixelSuffix() {
+        if (!this.cellPixels)
+            return "";
+        const { width, height, precise } = this.cellPixels;
+        return `/${width}x${height}` + (precise ? `/${precise.width}x${precise.height}` : "");
+    }
+    /**
+     * The renderer's cell size in device pixels. tmux answers CSI 14t/16t and
+     * sets TIOCGWINSZ pixels from it, so image programs render 1:1 for the
+     * window. Re-applies the current viewport when the size changes.
+     */
+    setCellPixels(width, height, precise) {
+        if (!Number.isSafeInteger(width) ||
+            !Number.isSafeInteger(height) ||
+            width < 1 ||
+            height < 1 ||
+            width > 1024 ||
+            height > 1024)
+            throw new RangeError("cell pixel size out of range");
+        if (precise &&
+            [precise.width, precise.height].some((value) => !Number.isSafeInteger(value) || value < 1000 || value > 1024000))
+            throw new RangeError("precise cell pixel size out of range");
+        if (this.cellPixels?.width === width &&
+            this.cellPixels.height === height &&
+            this.cellPixels.precise?.width === precise?.width &&
+            this.cellPixels.precise?.height === precise?.height)
+            return;
+        this.cellPixels = { width, height, ...(precise ? { precise } : {}) };
+        if (!this.geometryParticipating)
+            return;
+        this.input.flush();
+        if (this.fittedWindows.size > 0) {
+            for (const [runtimeId, size] of this.fittedWindows)
+                if (this.windowsByRuntime.has(runtimeId))
+                    this.io.send(`refresh-client -C ${runtimeId}:${size.cols}x${size.rows}${this.cellPixelSuffix()}`);
+        }
+        else if (this.clientViewport)
+            this.io.send(`refresh-client -C ${this.clientViewport.cols}x${this.clientViewport.rows}${this.cellPixelSuffix()}`);
     }
     restoreWindowSizing(target) {
         if (!this.geometryParticipating)
@@ -893,7 +937,7 @@ export class SessionChannel {
             return;
         this.input.flush();
         this.restoreWindowSizing(window.runtimeId);
-        this.io.send(`refresh-client -C ${window.runtimeId}:${cols}x${rows}`);
+        this.io.send(`refresh-client -C ${window.runtimeId}:${cols}x${rows}${this.cellPixelSuffix()}`);
         this.fittedWindows.set(window.runtimeId, { cols, rows });
     }
     /** Must also run on geometry-owner handoff, before the next owner fits. */
@@ -1468,6 +1512,7 @@ export class SessionChannel {
             return;
         }
         recovery.attempts += 1;
+        lease.attemptCharged = true;
         recovery.stage = "stock-pause";
         recovery.stock = new StockPaneSnapshot(this.snapshotContext(pane));
         // These rows were received before this pause and belong to the new seed,
@@ -1617,6 +1662,7 @@ export class SessionChannel {
             return;
         }
         recovery.attempts += 1;
+        lease.attemptCharged = true;
         const ordinal = ++recovery.reseedOrdinal;
         const participants = [...pane.subs]
             .filter((sub) => !sub.closed && !sub.frozen)
@@ -2310,6 +2356,12 @@ export class SessionChannel {
                     continue;
                 const recovery = this.recoveries.get(pane.runtimeId);
                 if (recovery?.lease && !recovery.lease.retired) {
+                    // A newer layout cancels this capture; it is not a failed snapshot.
+                    // Refund only this lease, retaining earlier failures and the original deadline.
+                    if (recovery.lease.attemptCharged) {
+                        recovery.lease.attemptCharged = false;
+                        recovery.attempts -= 1;
+                    }
                     this.awaitSnapshotLayout(recovery);
                     this.retrySnapshot(recovery);
                 }

package/packages/daemon/dist/terminal/pane-stream/pane-stream-websocket.js

@@ -1,6 +1,7 @@
+import { inflateSync } from "node:zlib";
 import { PaneStreamLayoutSnapshotFrameSchemaZ } from "@tmux-ide/contracts";
 import { z } from "zod";
-import { PANE_STREAM_MAX_HELD_DELTAS, PANE_STREAM_MAX_OUTPUT_BYTES, PANE_STREAM_MAX_PANES, PANE_STREAM_MAX_SEED_BYTES, PANE_STREAM_PROTOCOL_VERSION, PANE_STREAM_REDEEM_PATH, PANE_STREAM_WEBSOCKET_SUBPROTOCOL, PaneStreamClientFrameSchemaZ, PaneStreamLoopbackWebSocketUrlSchemaZ, PaneStreamRedeemFrameSchemaZ, PaneStreamServerFrameSchemaZ, sharedMonotonicMicros, } from "@tmux-ide/contracts";
+import { PANE_STREAM_MAX_HELD_DELTAS, PANE_STREAM_MAX_OUTPUT_BYTES, PANE_STREAM_MAX_PANES, PANE_STREAM_MAX_SEED_BYTES, PANE_STREAM_PROTOCOL_VERSION, PANE_STREAM_REDEEM_PATH, PANE_STREAM_WEBSOCKET_SUBPROTOCOL, TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES, TERMINAL_GRAPHICS_CELL_PIXELS_CAPABILITY_VERSION, TERMINAL_GRAPHICS_PRECISE_PIXELS_CAPABILITY_VERSION, TERMINAL_GRAPHICS_LEGACY_MAX_IMAGE_BYTES, TERMINAL_GRAPHICS_ZLIB_CAPABILITY_VERSION, PaneStreamClientFrameSchemaZ, PaneStreamLoopbackWebSocketUrlSchemaZ, PaneStreamRedeemFrameSchemaZ, PaneStreamServerFrameSchemaZ, sharedMonotonicMicros, } from "@tmux-ide/contracts";
 import { canonicalOriginOrNull, digestSecret, digestsEqual, rawDataByteLength, rawDataToBuffer, safeCloseSocket, strictJsonParse, } from "../attachments/admission-util.js";
 import { SessionRuntimeControllerLeaseError } from "../session-runtime/registry.js";
 import { terminalDeliveryObservationOrdinal } from "../session-runtime/terminal-delivery-observation-identity.js";
@@ -592,6 +593,25 @@ class PreAuthAdmission {
         socket.off("error", this.#onClose);
     }
 }
+const GRAPHICS_MAX_QUEUED_DIGESTS = 256;
+/** Graphics state as renderers without zlib support must see it. */
+export function rawGraphicsState(state) {
+    const legacy = state.images.map((image) => image.format === "rgba-zlib" || image.format === "rgb-zlib"
+        ? {
+            ...image,
+            format: image.format === "rgba-zlib" ? "rgba" : "rgb",
+            bytes: image.width * image.height * (image.format === "rgba-zlib" ? 4 : 3),
+        }
+        : image);
+    const images = legacy.filter((image) => image.bytes <= TERMINAL_GRAPHICS_LEGACY_MAX_IMAGE_BYTES);
+    const kept = new Set(images.map((image) => image.digest));
+    return {
+        ...state,
+        images,
+        placements: state.placements.filter((placement) => kept.has(placement.digest)),
+    };
+}
+const GRAPHICS_SEND_WINDOW_BYTES = 2 * 1024 * 1024;
 export class PaneStreamLiveConnection {
     #clientId;
     #socket;
@@ -723,6 +743,11 @@ export class PaneStreamLiveConnection {
                 frozenByWire: false,
                 closed: false,
                 batch: null,
+                graphicsAnnounced: false,
+                graphicsQueue: [],
+                graphicsSending: false,
+                graphicsServed: new Map(),
+                graphicsState: null,
             });
         }
     }
@@ -1097,6 +1122,7 @@ export class PaneStreamLiveConnection {
                 await this.#sendTerminalDelivery(channel.semanticPaneId, message);
             pending.length = 0;
             markReady();
+            this.#startGraphics(channel);
         }
         this.#closeIfAllPanesGone();
     }
@@ -1201,6 +1227,146 @@ export class PaneStreamLiveConnection {
         }
         await this.#awaitSemanticCredit(pane);
     }
+    /** Announce the pane's kitty graphics state; the client pulls bytes it lacks. */
+    #startGraphics(channel) {
+        const graphics = channel.delivery?.graphics;
+        if (!graphics)
+            return;
+        // Renderers that cannot inflate see raw formats; their bytes are inflated
+        // when served.
+        const zlib = this.#descriptor.terminalDelivery?.protocolVersions.includes(TERMINAL_GRAPHICS_ZLIB_CAPABILITY_VERSION) === true;
+        channel.graphicsZlib = zlib;
+        // Renderers that report cell pixels learn up front that this daemon
+        // accepts them, before any image exists.
+        const cellPixels = this.#descriptor.terminalDelivery?.protocolVersions.includes(TERMINAL_GRAPHICS_CELL_PIXELS_CAPABILITY_VERSION) === true;
+        const preciseCellPixels = this.#descriptor.terminalDelivery?.protocolVersions.includes(TERMINAL_GRAPHICS_PRECISE_PIXELS_CAPABILITY_VERSION) === true;
+        let announced = false;
+        graphics.subscribe((state) => {
+            announced = true;
+            if (this.#closed || channel.closed)
+                return;
+            channel.graphicsAnnounced = true;
+            channel.graphicsState = state;
+            // A program redrawing one image id (every frame of an animation or a
+            // page) needs the new bytes at once: push them instead of waiting for
+            // the renderer's round trip.
+            const pushed = [];
+            for (const image of state.images) {
+                const served = channel.graphicsServed.get(image.imageId);
+                if (served !== undefined && served !== image.digest)
+                    pushed.push(image.digest);
+            }
+            this.#sendFrame(null, {
+                type: "terminal-graphics",
+                pane: channel.semanticPaneId,
+                state: {
+                    ...(zlib ? state : rawGraphicsState(state)),
+                    ...(cellPixels ? { cellPixels: true } : {}),
+                    ...(preciseCellPixels ? { preciseCellPixels: true } : {}),
+                },
+            });
+            if (pushed.length > 0)
+                this.#queueGraphics(channel, pushed);
+        });
+        if (cellPixels && !announced && !this.#closed && !channel.closed) {
+            channel.graphicsAnnounced = true;
+            this.#sendFrame(null, {
+                type: "terminal-graphics",
+                pane: channel.semanticPaneId,
+                state: {
+                    revision: 0,
+                    images: [],
+                    placements: [],
+                    cellPixels: true,
+                    ...(preciseCellPixels ? { preciseCellPixels: true } : {}),
+                },
+            });
+        }
+    }
+    #requestGraphics(pane, digests) {
+        const channel = this.#panes.get(pane);
+        // Requests are only meaningful after an announcement; ignore stray ones.
+        if (!channel || channel.closed || !channel.graphicsAnnounced)
+            return;
+        this.#queueGraphics(channel, digests);
+    }
+    #queueGraphics(channel, digests) {
+        for (const digest of digests)
+            if (!channel.graphicsQueue.includes(digest) &&
+                channel.graphicsQueue.length < GRAPHICS_MAX_QUEUED_DIGESTS)
+                channel.graphicsQueue.push(digest);
+        if (!channel.graphicsSending)
+            void this.#drainGraphics(channel);
+    }
+    /**
+     * Blob bytes yield to terminal frames: each chunk waits until the socket's
+     * buffered bytes fall below a small window, so images never trip the
+     * socket-wide backpressure ceiling or delay a pane's next seed for long.
+     */
+    async #drainGraphics(channel) {
+        channel.graphicsSending = true;
+        try {
+            while (!this.#closed && !channel.closed && channel.graphicsQueue.length > 0) {
+                const digest = channel.graphicsQueue.shift();
+                const graphics = channel.delivery?.graphics;
+                const image = graphics?.image(digest);
+                if (!graphics || !image)
+                    continue;
+                for (const entry of channel.graphicsState?.images ?? [])
+                    if (entry.digest === digest)
+                        channel.graphicsServed.set(entry.imageId, digest);
+                const raw = !channel.graphicsZlib && image.format.endsWith("-zlib");
+                let data = image.data;
+                if (raw) {
+                    const expected = image.width * image.height * (image.format === "rgba-zlib" ? 4 : 3);
+                    if (expected < 1 || expected > TERMINAL_GRAPHICS_LEGACY_MAX_IMAGE_BYTES)
+                        continue;
+                    try {
+                        data = inflateSync(image.data, { maxOutputLength: expected });
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (data.byteLength !== expected)
+                        continue;
+                }
+                if (!channel.graphicsZlib && data.byteLength > TERMINAL_GRAPHICS_LEGACY_MAX_IMAGE_BYTES)
+                    continue;
+                const format = raw ? (image.format === "rgba-zlib" ? "rgba" : "rgb") : image.format;
+                const total = data.byteLength;
+                for (let offset = 0; offset < total; offset += TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES) {
+                    while ((this.#socket.bufferedAmount ?? 0) > GRAPHICS_SEND_WINDOW_BYTES) {
+                        if (this.#closed || channel.closed)
+                            return;
+                        await new Promise((resolve) => setTimeout(resolve, 5));
+                    }
+                    if (this.#closed || channel.closed)
+                        return;
+                    // A superseded frame (the id was redrawn) is abandoned mid-transfer;
+                    // the renderer drops the partial image and shows the newer one.
+                    if (offset > 0 && graphics.image(digest) !== image)
+                        break;
+                    const end = Math.min(total, offset + TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES);
+                    this.#sendFrame(null, {
+                        type: "terminal-graphics-blob",
+                        pane: channel.semanticPaneId,
+                        blob: {
+                            digest,
+                            format,
+                            width: image.width,
+                            height: image.height,
+                            total,
+                            offset,
+                        },
+                        data: Buffer.from(data.subarray(offset, end)).toString("base64"),
+                    });
+                }
+            }
+        }
+        finally {
+            channel.graphicsSending = false;
+        }
+    }
     #awaitSemanticCredit(pane) {
         // Backpressure is pane-local. Aggregate pressure is guarded by the hard
         // socket ceiling in #drainNow, but must not let a noisy sibling prevent a
@@ -1774,6 +1940,19 @@ export class PaneStreamLiveConnection {
             this.#acceptSemanticIntent(frame.operationId, frame.intent);
             return;
         }
+        if (frame.type === "terminal-graphics-request") {
+            this.#requestGraphics(frame.pane, frame.digests);
+            return;
+        }
+        if (frame.type === "terminal-cell-pixels") {
+            try {
+                this.#sessionRuntimeBinding?.setCellPixels?.(frame.width, frame.height, frame.precise);
+            }
+            catch {
+                // A retired runtime simply keeps tmux's default cell size.
+            }
+            return;
+        }
         if (frame.type === "viewport") {
             if (!this.#descriptor.terminalDelivery ||
                 this.#descriptor.viewerMode !== "interactive" ||

package/packages/daemon/dist/terminal/protocol/session-descriptor-discovery.js

@@ -129,7 +129,6 @@ export function parseSessionPaneDescriptorReply(lines) {
             !bounded(type, 256) ||
             !bounded(currentCommand, 512) ||
             !bounded(cwd, 4_096) ||
-            !bounded(title, 1_024) ||
             !bounded(windowName, 1_024) ||
             !bounded(name, 256) ||
             !bounded(missionStamp, 256) ||
@@ -148,7 +147,9 @@ export function parseSessionPaneDescriptorReply(lines) {
             type: nonempty(type),
             currentCommand: nonempty(currentCommand),
             cwd: nonempty(cwd),
-            title: nonempty(title),
+            // Stock tmux turns any APC, including kitty graphics payloads, into the
+            // pane title; an overlong title names nothing and must not drop the pane.
+            title: bounded(title, 1_024) ? nonempty(title) : null,
             windowIndex,
             windowName: nonempty(windowName),
             windowId: /^@(?:0|[1-9][0-9]*)$/u.test(windowId) ? windowId : null,

package/packages/daemon/dist/terminal/session-runtime/history-anchor-owner.js

@@ -0,0 +1,171 @@
+import { randomUUID } from "node:crypto";
+const MAX_TOKENS = 32;
+const PROOF_TTL_MS = 5 * 60_000;
+/** Owner-private row ordinals. Never changes terminal v1 payloads or hashes. */
+export class HistoryAnchorOwner {
+    now;
+    #current = null;
+    #first = 0;
+    #length = 0;
+    #proofs = new Map();
+    #tokens = new Map();
+    constructor(now = () => performance.now()) {
+        this.now = now;
+    }
+    invalidate() {
+        this.#current = null;
+        this.#first = 0;
+        this.#length = 0;
+        this.#tokens.clear();
+        this.#proofs.clear();
+    }
+    observe(update) {
+        if (update.type === "terminal.tombstone") {
+            this.invalidate();
+            return;
+        }
+        if (update.type === "terminal.seed") {
+            this.invalidate();
+            this.#length = update.snapshot.history.length;
+            this.#current = {
+                workspaceName: update.workspaceName,
+                semanticPaneId: update.semanticPaneId,
+                generation: update.generation,
+                incarnation: update.incarnation,
+                revision: update.revision,
+                stateHash: update.stateHash,
+                cols: update.cols,
+                rows: update.rows,
+                alternate: update.snapshot.modes.alternateScreen,
+            };
+            this.#remember();
+            return;
+        }
+        const old = this.#current;
+        if (!old ||
+            old.workspaceName !== update.workspaceName ||
+            old.semanticPaneId !== update.semanticPaneId ||
+            old.generation !== update.generation ||
+            old.incarnation !== update.incarnation ||
+            old.revision !== update.baseRevision) {
+            this.invalidate();
+            return;
+        }
+        const delta = update.patch.historyDelta;
+        const alternate = update.patch.modes?.alternateScreen ?? old.alternate;
+        if (delta &&
+            (!Number.isSafeInteger(delta.trim) || delta.trim < 0 || delta.trim > this.#length)) {
+            this.invalidate();
+            return;
+        }
+        const length = update.patch.history?.length ??
+            this.#length - (delta?.trim ?? 0) + (delta?.append.length ?? 0);
+        const reset = update.patch.history !== undefined ||
+            update.cols !== old.cols ||
+            update.rows !== old.rows ||
+            alternate !== old.alternate;
+        if (reset) {
+            this.#tokens.clear();
+            this.#proofs.clear();
+            this.#first = 0;
+        }
+        else
+            this.#first += delta?.trim ?? 0;
+        if (!Number.isSafeInteger(this.#first + length)) {
+            this.invalidate();
+            return;
+        }
+        this.#length = length;
+        this.#current = {
+            workspaceName: update.workspaceName,
+            semanticPaneId: update.semanticPaneId,
+            generation: update.generation,
+            incarnation: update.incarnation,
+            revision: update.revision,
+            stateHash: update.stateHash,
+            cols: update.cols,
+            rows: update.rows,
+            alternate,
+        };
+        this.#prune();
+        this.#remember();
+    }
+    capture(proof, historyIndex) {
+        const failure = this.#admitIdentity(proof);
+        if (failure)
+            return failure;
+        this.#prune();
+        const known = this.#current && this.#key(proof) === this.#key(this.#current)
+            ? { first: this.#first, length: this.#length }
+            : this.#proofs.get(this.#key(proof));
+        if (!known)
+            return { status: "stale" };
+        if (!Number.isSafeInteger(historyIndex) || historyIndex < 0 || historyIndex >= known.length)
+            return { status: "lost" };
+        const ordinal = known.first + historyIndex;
+        if (ordinal < this.#first || ordinal >= this.#first + this.#length)
+            return { status: "lost" };
+        while (this.#tokens.size >= MAX_TOKENS)
+            this.#tokens.delete(this.#tokens.keys().next().value);
+        const token = randomUUID();
+        // Saved tabs retain identity until capacity eviction or actual history loss.
+        this.#tokens.set(token, { ordinal });
+        return { status: "captured", token };
+    }
+    resolve(proof, token) {
+        const failure = this.#admitIdentity(proof);
+        if (failure)
+            return failure;
+        this.#prune();
+        const entry = this.#tokens.get(token);
+        if (!entry)
+            return { status: "lost" };
+        const { workspaceName, semanticPaneId, generation, incarnation, revision, stateHash } = this.#current;
+        return {
+            status: "resolved",
+            proof: { workspaceName, semanticPaneId, generation, incarnation, revision, stateHash },
+            historyIndex: entry.ordinal - this.#first,
+        };
+    }
+    #admitIdentity(proof) {
+        const current = this.#current;
+        if (!current || current.alternate)
+            return { status: "unavailable" };
+        return current.workspaceName === proof.workspaceName &&
+            current.semanticPaneId === proof.semanticPaneId &&
+            current.generation === proof.generation &&
+            current.incarnation === proof.incarnation
+            ? null
+            : { status: "stale" };
+    }
+    #key(proof) {
+        return JSON.stringify([
+            proof.workspaceName,
+            proof.semanticPaneId,
+            proof.generation,
+            proof.incarnation,
+            proof.revision,
+            proof.stateHash,
+        ]);
+    }
+    #remember() {
+        if (!this.#current || this.#current.alternate)
+            return;
+        while (this.#proofs.size >= 64)
+            this.#proofs.delete(this.#proofs.keys().next().value);
+        this.#proofs.set(this.#key(this.#current), {
+            first: this.#first,
+            length: this.#length,
+            expires: this.now() + PROOF_TTL_MS,
+        });
+    }
+    #prune() {
+        const now = this.now();
+        for (const [key, value] of this.#proofs)
+            if (value.expires <= now)
+                this.#proofs.delete(key);
+        for (const [token, entry] of this.#tokens)
+            if (entry.ordinal < this.#first || entry.ordinal >= this.#first + this.#length)
+                this.#tokens.delete(token);
+    }
+}

package/packages/daemon/dist/terminal/session-runtime/registry.js

@@ -457,6 +457,12 @@ export class SessionRuntimeRegistry {
     async describeSession(session) {
         return await this.#runtime(session).describe();
     }
+    historyAnchor(session, request) {
+        const runtime = this.#sessions.get(session);
+        if (this.#disposed || !runtime)
+            return { status: "unavailable" };
+        return runtime.historyAnchor(request);
+    }
     async captureNativeBacking(session, semanticPaneId, expected) {
         const runtime = this.#sessions.get(session);
         if (this.#disposed || !runtime)
@@ -1128,6 +1134,11 @@ class SessionRuntime {
             throw new SessionRuntimeControllerLeaseError("invalid-client-capability", "The client does not own this geometry authority lease.");
         }
     }
+    /** Renderer cell size in device pixels; benign, so any connected client may set it. */
+    setCellPixels(clientId, width, height, precise) {
+        this.#assertConnected(clientId);
+        this.#mirror.setCellPixels?.(this.session, width, height, precise);
+    }
     fitViewportWithAuthority(clientId, lease, cols, rows, semanticWindowId) {
         this.assertGeometryAuthority(clientId, lease);
         this.#mirror.setGeometryParticipation(this.session, true);
@@ -1222,6 +1233,19 @@ class SessionRuntime {
             throw error;
         }
     }
+    historyAnchor(request) {
+        if (this.#disposed)
+            return { status: "unavailable" };
+        const owner = this.#terminalReplicas.get(request.proof.semanticPaneId);
+        if (!owner)
+            return { status: "unavailable" };
+        if (request.operation.kind === "capture") {
+            if (!("revision" in request.proof) || !("stateHash" in request.proof))
+                return { status: "stale" };
+            return owner.captureHistoryAnchor(request.proof, request.operation.historyIndex);
+        }
+        return owner.resolveHistoryAnchor(request.proof, request.operation.token);
+    }
     async captureNativeBacking(semanticPaneId, expected) {
         const owner = this.#terminalReplicas.get(semanticPaneId);
         if (!owner)
@@ -1552,6 +1576,10 @@ class SessionRuntimeConsumerImpl {
         this.#assertOpen();
         this.#runtime.fitViewport(this.clientId, lease, cols, rows, semanticWindowId);
     }
+    setCellPixels(width, height, precise) {
+        this.#assertOpen();
+        this.#runtime.setCellPixels(this.clientId, width, height, precise);
+    }
     fitViewportWithAuthority(lease, cols, rows, semanticWindowId) {
         this.#assertOpen();
         this.#runtime.fitViewportWithAuthority(this.clientId, lease, cols, rows, semanticWindowId);
@@ -1624,6 +1652,7 @@ class SessionRuntimeConsumerImpl {
                 this.#deliveryConnections.delete(connection);
                 await upstream.close();
             },
+            ...(upstream.graphics ? { graphics: upstream.graphics } : {}),
         };
         this.#deliveryConnections.add(connection);
         return connection;