tmux-ide 2.9.6 → 2.9.7

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({
@@ -1468,6 +1469,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 +1619,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 +2313,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,6 @@
 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, 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 +592,8 @@ class PreAuthAdmission {
         socket.off("error", this.#onClose);
     }
 }
+const GRAPHICS_MAX_QUEUED_DIGESTS = 256;
+const GRAPHICS_SEND_WINDOW_BYTES = 2 * 1024 * 1024;
 export class PaneStreamLiveConnection {
     #clientId;
     #socket;
@@ -723,6 +725,9 @@ export class PaneStreamLiveConnection {
                 frozenByWire: false,
                 closed: false,
                 batch: null,
+                graphicsAnnounced: false,
+                graphicsQueue: [],
+                graphicsSending: false,
             });
         }
     }
@@ -1097,6 +1102,7 @@ export class PaneStreamLiveConnection {
                 await this.#sendTerminalDelivery(channel.semanticPaneId, message);
             pending.length = 0;
             markReady();
+            this.#startGraphics(channel);
         }
         this.#closeIfAllPanesGone();
     }
@@ -1201,6 +1207,73 @@ 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;
+        graphics.subscribe((state) => {
+            if (this.#closed || channel.closed)
+                return;
+            channel.graphicsAnnounced = true;
+            this.#sendFrame(null, { type: "terminal-graphics", pane: channel.semanticPaneId, state });
+        });
+    }
+    #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;
+        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 image = channel.delivery?.graphics?.image(digest);
+                if (!image)
+                    continue;
+                const total = image.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;
+                    const end = Math.min(total, offset + TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES);
+                    this.#sendFrame(null, {
+                        type: "terminal-graphics-blob",
+                        pane: channel.semanticPaneId,
+                        blob: {
+                            digest,
+                            format: image.format,
+                            width: image.width,
+                            height: image.height,
+                            total,
+                            offset,
+                        },
+                        data: Buffer.from(image.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 +1847,10 @@ 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 === "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)
@@ -1222,6 +1228,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)
@@ -1624,6 +1643,7 @@ class SessionRuntimeConsumerImpl {
                 this.#deliveryConnections.delete(connection);
                 await upstream.close();
             },
+            ...(upstream.graphics ? { graphics: upstream.graphics } : {}),
         };
         this.#deliveryConnections.add(connection);
         return connection;

package/packages/daemon/dist/terminal/session-runtime/terminal-delivery-hub.js

@@ -1,6 +1,6 @@
 import { StockCaptureTabUnavailableError } from "./stock-capture-fidelity.js";
 import { MAX_RETAINED_NATIVE_BACKING_BYTES, takeNativeSeedBacking, } from "./native-seed-backing.js";
-import { WorkspaceIdSchemaZ, TERMINAL_DELIVERY_PATCH_TO_SEED_BYTES, TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES, TerminalDeliveryEnvelopeSchemaZ, TerminalDeliveryAckSchemaZ, TerminalDeliveryNackSchemaZ, TerminalDeliveryOfferSchemaZ, TerminalDeliveryVisibilitySchemaZ, } from "@tmux-ide/contracts";
+import { WorkspaceIdSchemaZ, TERMINAL_GRAPHICS_CAPABILITY_VERSION, TERMINAL_DELIVERY_PATCH_TO_SEED_BYTES, TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES, TerminalDeliveryEnvelopeSchemaZ, TerminalDeliveryAckSchemaZ, TerminalDeliveryNackSchemaZ, TerminalDeliveryOfferSchemaZ, TerminalDeliveryVisibilitySchemaZ, } from "@tmux-ide/contracts";
 import { TerminalDeliveryStateTooLargeError, terminalReplicaRowsEqual, TERMINAL_COMPACT_COOPERATIVE_SEED_CELLS, applyTerminalReplicaUpdate, applyTerminalReplicaUpdateCooperatively, terminalReplicaUpdateNeedsCooperativeReduction, encodeCompactSemanticTerminalUpdate, encodeCompactSemanticTerminalUpdateCooperatively, terminalSemanticUpdateNeedsCooperativeEncoding, encodeAnsiTerminalRepresentation, encodeSemanticTerminalUpdate, hashTerminalDeliveryRepresentation, negotiateTerminalDelivery, preaccountSemanticTerminalUpdateBytes, } from "@tmux-ide/core";
 import { SYSTEM_SESSION_RUNTIME_SCHEDULER, } from "./runtime-scheduler.js";
 import { DISABLED_SESSION_RUNTIME_OBSERVABILITY, } from "./runtime-observability.js";
@@ -171,6 +171,9 @@ export class SessionRuntimeTerminalDeliveryHub {
                     this.#recordDeliveryStatus(client, this.#panes.get(client.paneId));
                 },
                 close: async () => this.#closeClient(client),
+                ...(offer.protocolVersions.includes(TERMINAL_GRAPHICS_CAPABILITY_VERSION)
+                    ? { graphics: this.#graphicsFor(semanticPaneId, client, closed) }
+                    : {}),
             };
         }
         catch (error) {
@@ -196,6 +199,22 @@ export class SessionRuntimeTerminalDeliveryHub {
             this.#pendingClients.delete(key);
         }
     }
+    #graphicsFor(semanticPaneId, client, closed) {
+        const owner = this.#ownerForPane(semanticPaneId);
+        return {
+            subscribe: (listener) => {
+                if (client.closed || !owner.subscribeGraphics)
+                    return () => { };
+                const unsubscribe = owner.subscribeGraphics((state) => {
+                    if (!client.closed)
+                        listener(state);
+                });
+                void closed.then(unsubscribe);
+                return unsubscribe;
+            },
+            image: (digest) => (client.closed ? null : (owner.graphicsImage?.(digest) ?? null)),
+        };
+    }
     /** Retire only this pane's delivery owners before its canonical owner is disposed. */
     failPaneCapture(semanticPaneId, error) {
         for (const client of this.#clients.values())

package/packages/daemon/dist/terminal/session-runtime/terminal-replica-interpreter.js

@@ -6,6 +6,7 @@ import { SYSTEM_SESSION_RUNTIME_SCHEDULER, } from "./runtime-scheduler.js";
 import { DISABLED_SESSION_RUNTIME_OBSERVABILITY, } from "./runtime-observability.js";
 import { createXtermTerminalInterpreterBackend } from "./xterm-terminal-interpreter-backend.js";
 import { CAUSAL_CELL_OSC, CausalCellLedger, cellsEqual, } from "./causal-cell-ledger.js";
+import { KITTY_PLACEMENT_OSC, KittyApcScanner, KittyImageStore, } from "../graphics/kitty-graphics.js";
 /** Daemon-owned, sans-I/O VT interpreter with one FIFO for bytes and geometry. */
 export class TerminalReplicaInterpreter {
     #nativeSeedBackingCandidate;
@@ -37,6 +38,13 @@ export class TerminalReplicaInterpreter {
     #pendingWrites = [];
     #writeFlushScheduled = false;
     #widgetGate = false;
+    // kitty graphics: images outlive reseeds; the scanner owns split APCs.
+    #kittyScanner = new KittyApcScanner();
+    #kitty;
+    #kittyPending = new Map();
+    #graphicsListeners = new Set();
+    #graphics = null;
+    #graphicsKey = "";
     #markerTail = "";
     #pendingResize = null;
     // null: no unpublished writes; undefined: a write requires full projection.
@@ -79,6 +87,8 @@ export class TerminalReplicaInterpreter {
             rows: options.rows,
             scrollback: this.#scrollback,
         });
+        this.#kitty = new KittyImageStore(options.kittyImageBudget ? { budget: options.kittyImageBudget } : {});
+        this.#attachKitty(this.#backend);
         this.#snapshot = blankTerminalReplicaSnapshot(options.cols, options.rows);
         this.#seedReady = new Promise((resolve, reject) => {
             this.#resolveSeedReady = resolve;
@@ -239,6 +249,9 @@ export class TerminalReplicaInterpreter {
             }
             const previous = this.#backend;
             this.#backend = replacement;
+            this.#attachKitty(replacement);
+            // tmux never saw cursor-anchored placements; a capture cannot restore them.
+            this.#kitty.dropCursorPlacements();
             this.#nativeReseedRequested = false;
             this.#scrollback = scrollback;
             this.#bootstrap = {
@@ -262,6 +275,7 @@ export class TerminalReplicaInterpreter {
                 this.#nativeSeedBackingCandidate = undefined;
             }
             previous.dispose();
+            this.#publishGraphics();
             return;
         }
         if (operation.type === "cursor") {
@@ -287,6 +301,7 @@ export class TerminalReplicaInterpreter {
             }
             this.#backend.resize(operation.cols, operation.rows);
             this.#commit(false);
+            this.#publishGraphics();
             return;
         }
         const baseRevision = this.#revision;
@@ -304,6 +319,7 @@ export class TerminalReplicaInterpreter {
         };
         this.#revision = revision;
         this.#closed = true;
+        this.#kitty.dispose();
         this.#causalCell?.fail("transport-closed");
         this.#clearSyncRecovery();
         if (this.#needsSeed)
@@ -321,8 +337,14 @@ export class TerminalReplicaInterpreter {
         this.#admitRaw(data);
         this.#stats.parseBatches += 1;
         this.#observeMarkerBytes(data);
+        const scanned = this.#kittyScanner.scan(data);
+        for (const command of scanned.commands)
+            this.#kittyPending.set(command.marker, command);
         const parseStarted = this.#observability.enabled ? this.#observability.nowMicros() : 0;
-        await this.#writeToBackend(this.#backend, data);
+        // Always forward the scanner's output: tmux splits %output (~2 KiB) inside
+        // kitty APCs (~4 KiB chunks), so a chunk with no completed command can still
+        // be all image payload that must never reach the VT parser as text.
+        await this.#writeToBackend(this.#backend, scanned.forward);
         if (this.#observability.enabled)
             this.#observability.recordSpan("parse", "terminal-replica-write", parseStarted, this.#observability.nowMicros(), trace);
         // The parser resets its dirty tracker per write. Synchronized output may
@@ -356,6 +378,7 @@ export class TerminalReplicaInterpreter {
         else {
             this.#commit(false, this.#backend.dirtyRange(), trace);
         }
+        this.#publishGraphics();
     }
     #scheduleSyncRecovery() {
         if (this.#syncRecovery || this.#closed)
@@ -541,6 +564,50 @@ export class TerminalReplicaInterpreter {
             bootstrap: this.#bootstrap,
         });
     }
+    /** The pane's kitty image store (bytes for the graphics side channel). */
+    kittyImages() {
+        return this.#kitty;
+    }
+    /** Latest graphics state, or null while the pane has never held an image. */
+    currentGraphics() {
+        return this.#graphics;
+    }
+    onGraphics(listener) {
+        this.#graphicsListeners.add(listener);
+        return () => this.#graphicsListeners.delete(listener);
+    }
+    /** Publish graphics state when the store or the viewport-relative placements moved. */
+    #publishGraphics() {
+        if (this.#graphics === null && this.#kitty.revision === 0)
+            return;
+        const state = this.#kitty.state(this.#backend.graphicsViewportTop?.() ?? 0, this.#backend.rows, this.#backend.cols, this.#backend.modes().alternateScreen);
+        const key = JSON.stringify([state.revision, state.placements]);
+        if (key === this.#graphicsKey)
+            return;
+        this.#graphicsKey = key;
+        this.#graphics = state;
+        for (const listener of this.#graphicsListeners) {
+            try {
+                listener(state);
+            }
+            catch {
+                // Renderer callbacks never poison the authoritative parser FIFO.
+            }
+        }
+    }
+    #attachKitty(backend) {
+        // Minimal test backends omit the OSC seam; they simply never place images.
+        if (typeof backend.registerOscHandler !== "function")
+            return;
+        backend.registerOscHandler(KITTY_PLACEMENT_OSC, (data) => {
+            const command = this.#kittyPending.get(Number(data));
+            if (!command)
+                return true;
+            this.#kittyPending.delete(Number(data));
+            this.#kitty.apply(command, backend.graphicsCursor?.() ?? null);
+            return true;
+        });
+    }
     #currentSnapshotHash() {
         return (this.#snapshotHash ??= hashTerminalReplicaSnapshot(this.#snapshot));
     }

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

@@ -1,3 +1,4 @@
+import { HistoryAnchorOwner, } from "./history-anchor-owner.js";
 import { layoutContentRows } from "../mirror/layout-content-rows.js";
 import { terminalReplicaRowsEqual } from "@tmux-ide/core";
 import { projectNativeGridRow } from "../mirror/native-grid-projection.js";
@@ -20,6 +21,7 @@ export class SessionRuntimeTerminalReplicaOwner {
     #start;
     #upstream = null;
     #disposed = false;
+    #historyAnchors = new HistoryAnchorOwner();
     #cols = 80;
     #rows = 24;
     #layoutEpoch = 0;
@@ -56,12 +58,14 @@ export class SessionRuntimeTerminalReplicaOwner {
                 if (this.#disposed || this.#reseed || this.#waitingForGeometryCapture)
                     return;
                 this.#waitingForGeometryCapture = true;
+                this.#historyAnchors.invalidate();
                 this.#supervise(this.#start.then(() => {
                     if (!this.#disposed && this.#waitingForGeometryCapture)
                         this.#upstream?.reseed();
                 }));
             },
             onUpdate: (update, trace) => {
+                this.#historyAnchors.observe(update);
                 this.#publishedIncarnation = update.incarnation;
                 if (update.type === "terminal.seed") {
                     this.#bootstrapped = true;
@@ -137,6 +141,16 @@ export class SessionRuntimeTerminalReplicaOwner {
     failCausalCell(reason, traceId) {
         this.#interpreter.failCausalCell(reason, traceId);
     }
+    captureHistoryAnchor(proof, historyIndex) {
+        if (this.#disposed || this.#reseed || this.#waitingForGeometryCapture)
+            return { status: "unavailable" };
+        return this.#historyAnchors.capture(proof, historyIndex);
+    }
+    resolveHistoryAnchor(proof, token) {
+        if (this.#disposed || this.#reseed || this.#waitingForGeometryCapture)
+            return { status: "unavailable" };
+        return this.#historyAnchors.resolve(proof, token);
+    }
     /** Scalar diagnostic only: no seed construction, hashing, or owner creation. */
     inputDispatchIncarnation() {
         return this.#disposed ? null : this.#publishedIncarnation;
@@ -248,6 +262,17 @@ export class SessionRuntimeTerminalReplicaOwner {
             },
         };
     }
+    /** Kitty graphics side channel: current state now (if any), then every change. */
+    subscribeGraphics(listener) {
+        const current = this.#interpreter.currentGraphics();
+        if (current)
+            listener(current);
+        return this.#interpreter.onGraphics(listener);
+    }
+    /** Image bytes by content digest, while the pane's store still holds them. */
+    graphicsImage(digest) {
+        return this.#interpreter.kittyImages().imageByDigest(digest) ?? null;
+    }
     async subscribeSource(listener, onRaw) {
         const canonical = await this.subscribe(listener);
         this.#rawListeners.add(onRaw);
@@ -268,6 +293,7 @@ export class SessionRuntimeTerminalReplicaOwner {
             return;
         this.#noteLifecycle(`dispose-${reason}`);
         this.#disposed = true;
+        this.#historyAnchors.invalidate();
         this.#historyTimer?.cancel();
         this.#historyTimer = null;
         this.#subscriptionEpoch += 1;
@@ -330,6 +356,7 @@ export class SessionRuntimeTerminalReplicaOwner {
             // Deterministic capture point: reset opens the atomic capture. A probe
             // armed after reset belongs to the next post-capture delta, never to this
             // already-started reseed.
+            this.#historyAnchors.invalidate();
             this.#reseed = {
                 nativeCols: event.cols,
                 nativeRows: event.rows,
@@ -447,6 +474,7 @@ export class SessionRuntimeTerminalReplicaOwner {
         if (!this.#bootstrapped || this.#reseed || this.#waitingForGeometryCapture)
             return;
         this.#waitingForGeometryCapture = true;
+        this.#historyAnchors.invalidate();
         void this.#start.then(() => {
             if (!this.#disposed && this.#waitingForGeometryCapture)
                 this.#upstream?.reseed();
@@ -557,6 +585,7 @@ export class SessionRuntimeTerminalReplicaOwner {
         this.#noteLifecycle("reseed-retry", diagnostic);
         this.#reseedRetryCount += 1;
         this.#waitingForGeometryCapture = true;
+        this.#historyAnchors.invalidate();
         void this.#start.then(() => {
             if (!this.#disposed)
                 this.#upstream?.reseed();
@@ -564,6 +593,7 @@ export class SessionRuntimeTerminalReplicaOwner {
     }
     #supervise(operation) {
         void operation.catch((error) => {
+            this.#historyAnchors.invalidate();
             this.#noteLifecycle("interpreter-fault");
             this.#interpreter.abort(error);
             this.#onFault?.(error);