tmux-ide 2.9.6 → 2.9.8

package/packages/daemon/src/terminal/session-runtime/history-anchor-owner.ts

@@ -0,0 +1,190 @@
+import { randomUUID } from "node:crypto";
+import type { CanonicalTerminalReplicaUpdate } from "@tmux-ide/contracts";
+
+export interface HistoryAnchorProof {
+  readonly workspaceName: string;
+  readonly semanticPaneId: string;
+  readonly generation: string;
+  readonly incarnation: string;
+  readonly revision: number;
+  readonly stateHash: string;
+}
+export type HistoryAnchorIdentity = Pick<
+  HistoryAnchorProof,
+  "workspaceName" | "semanticPaneId" | "generation" | "incarnation"
+>;
+type Failure = { readonly status: "unavailable" | "stale" | "lost" };
+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 {
+  #current: (HistoryAnchorProof & { cols: number; rows: number; alternate: boolean }) | null = null;
+  #first = 0;
+  #length = 0;
+  #proofs = new Map<string, { first: number; length: number; expires: number }>();
+  #tokens = new Map<string, { ordinal: number }>();
+  constructor(private readonly now: () => number = () => performance.now()) {}
+
+  invalidate(): void {
+    this.#current = null;
+    this.#first = 0;
+    this.#length = 0;
+    this.#tokens.clear();
+    this.#proofs.clear();
+  }
+
+  observe(update: CanonicalTerminalReplicaUpdate): void {
+    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: HistoryAnchorProof,
+    historyIndex: number,
+  ): Failure | { status: "captured"; token: string } {
+    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: HistoryAnchorIdentity,
+    token: string,
+  ): Failure | { status: "resolved"; proof: HistoryAnchorProof; historyIndex: number } {
+    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: HistoryAnchorIdentity): Failure | null {
+    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: HistoryAnchorProof): string {
+    return JSON.stringify([
+      proof.workspaceName,
+      proof.semanticPaneId,
+      proof.generation,
+      proof.incarnation,
+      proof.revision,
+      proof.stateHash,
+    ]);
+  }
+  #remember(): void {
+    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(): void {
+    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/src/terminal/session-runtime/registry.ts

@@ -1,3 +1,4 @@
+import type { HistoryAnchorRequest, HistoryAnchorResult } from "@tmux-ide/contracts";
 import { StockCaptureTabUnavailableError } from "./stock-capture-fidelity.ts";
 import type { OwnedNativePlanCompletion } from "../../lib/owned-native-interaction-bindings.ts";
 import type {
@@ -255,6 +256,8 @@ export interface SessionRuntimeConsumer {
     rows: number,
     semanticWindowId?: string,
   ): void;
+  /** Renderer cell size in device pixels, forwarded to tmux. */
+  setCellPixels?(width: number, height: number, precise?: { width: number; height: number }): void;
   fitViewportWithAuthority(
     lease: SessionRuntimeAuthorityLease,
     cols: number,
@@ -875,6 +878,12 @@ export class SessionRuntimeRegistry implements PaneStreamMirror {
     return await this.#runtime(session).describe();
   }
 
+  historyAnchor(session: string, request: HistoryAnchorRequest): HistoryAnchorResult {
+    const runtime = this.#sessions.get(session);
+    if (this.#disposed || !runtime) return { status: "unavailable" };
+    return runtime.historyAnchor(request);
+  }
+
   async captureNativeBacking(
     session: string,
     semanticPaneId: string,
@@ -1760,6 +1769,17 @@ class SessionRuntime {
     }
   }
 
+  /** Renderer cell size in device pixels; benign, so any connected client may set it. */
+  setCellPixels(
+    clientId: string,
+    width: number,
+    height: number,
+    precise?: { width: number; height: number },
+  ): void {
+    this.#assertConnected(clientId);
+    this.#mirror.setCellPixels?.(this.session, width, height, precise);
+  }
+
   fitViewportWithAuthority(
     clientId: string,
     lease: SessionRuntimeAuthorityLease,
@@ -1880,6 +1900,18 @@ class SessionRuntime {
     }
   }
 
+  historyAnchor(request: HistoryAnchorRequest): HistoryAnchorResult {
+    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: string,
     expected?: NativeBackingIdentity,
@@ -2323,6 +2355,11 @@ class SessionRuntimeConsumerImpl implements SessionRuntimeConsumer {
     this.#runtime.fitViewport(this.clientId, lease, cols, rows, semanticWindowId);
   }
 
+  setCellPixels(width: number, height: number, precise?: { width: number; height: number }): void {
+    this.#assertOpen();
+    this.#runtime.setCellPixels(this.clientId, width, height, precise);
+  }
+
   fitViewportWithAuthority(
     lease: SessionRuntimeAuthorityLease,
     cols: number,
@@ -2424,6 +2461,7 @@ class SessionRuntimeConsumerImpl implements SessionRuntimeConsumer {
         this.#deliveryConnections.delete(connection);
         await upstream.close();
       },
+      ...(upstream.graphics ? { graphics: upstream.graphics } : {}),
     };
     this.#deliveryConnections.add(connection);
     return connection;

package/packages/daemon/src/terminal/session-runtime/terminal-delivery-hub.ts

@@ -1,3 +1,4 @@
+import type { KittyImage } from "../graphics/kitty-graphics.ts";
 import { StockCaptureTabUnavailableError } from "./stock-capture-fidelity.ts";
 import {
   MAX_RETAINED_NATIVE_BACKING_BYTES,
@@ -8,6 +9,8 @@ import {
 } from "./native-seed-backing.ts";
 import {
   WorkspaceIdSchemaZ,
+  TERMINAL_GRAPHICS_CAPABILITY_VERSION,
+  type TerminalGraphicsState,
   TERMINAL_DELIVERY_PATCH_TO_SEED_BYTES,
   TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES,
   TerminalDeliveryEnvelopeSchemaZ,
@@ -124,6 +127,17 @@ export interface TerminalDeliveryConnection {
   nack(nack: TerminalDeliveryNack): void;
   setVisibility(visibility: TerminalDeliveryVisibility): void;
   close(): Promise<void>;
+  /**
+   * Kitty graphics side channel, present only when the client offered
+   * TERMINAL_GRAPHICS_CAPABILITY_VERSION. Delivery is independent of the
+   * canonical FIFO: renderers resolve state against cells they already hold.
+   */
+  readonly graphics?: TerminalDeliveryGraphics;
+}
+
+export interface TerminalDeliveryGraphics {
+  subscribe(listener: (state: TerminalGraphicsState) => void): () => void;
+  image(digest: string): KittyImage | null;
 }
 
 interface NativeBackingLease {
@@ -173,6 +187,8 @@ export interface TerminalDeliverySourceOwner {
     ) => void,
     onRaw: (record: TerminalReplicaCommittedRaw) => void,
   ): Promise<TerminalReplicaSourceSubscription>;
+  subscribeGraphics?(listener: (state: TerminalGraphicsState) => void): () => void;
+  graphicsImage?(digest: string): KittyImage | null;
 }
 
 interface ClientState {
@@ -451,6 +467,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) {
       if (!(error instanceof StockCaptureTabUnavailableError)) throw error;
@@ -474,6 +493,25 @@ export class SessionRuntimeTerminalDeliveryHub {
     }
   }
 
+  #graphicsFor(
+    semanticPaneId: string,
+    client: ClientState,
+    closed: Promise<unknown>,
+  ): TerminalDeliveryGraphics {
+    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: string, error: StockCaptureTabUnavailableError): void {
     for (const client of this.#clients.values())

package/packages/daemon/src/terminal/session-runtime/terminal-interpreter-backend.ts

@@ -25,6 +25,10 @@ export interface TerminalInterpreterBackend {
   /** Public-parser diagnostic OSC seam; installed only for an active probe. */
   registerOscHandler(identifier: number, handler: (data: string) => boolean): () => void;
   write(data: Uint8Array | string): Promise<void>;
+  /** SPIKE (kitty graphics): cursor as an absolute buffer line, read mid-parse. */
+  graphicsCursor?(): { readonly x: number; readonly line: number; readonly alternate: boolean };
+  /** SPIKE (kitty graphics): absolute buffer line of viewport row 0. */
+  graphicsViewportTop?(): number;
   /** Exact native painted state; false means this parser cannot import it. */
   canImportNativeGrid?(): boolean;
   importNativeGrid?(snapshot: NativeGridCapture): boolean;

package/packages/daemon/src/terminal/session-runtime/terminal-replica-interpreter.ts

@@ -44,6 +44,14 @@ import {
   cellsEqual,
   type CausalCellLedgerResult,
 } from "./causal-cell-ledger.ts";
+import {
+  KITTY_PLACEMENT_OSC,
+  KittyApcScanner,
+  KittyImageStore,
+  type KittyCommand,
+  type KittyImageBudget,
+} from "../graphics/kitty-graphics.ts";
+import type { TerminalGraphicsState } from "@tmux-ide/contracts";
 
 type CloseReason = "pane-closed" | "session-restarted" | "runtime-disposed";
 export type TerminalReplicaInterpreterOperation =
@@ -115,6 +123,8 @@ export interface TerminalReplicaInterpreterOptions {
   readonly observability?: SessionRuntimeObservability;
   /** Parser implementation only; SessionRuntime remains the sole state authority. */
   readonly backendFactory?: TerminalInterpreterBackendFactory;
+  /** Shared kitty image byte quotas; defaults to the daemon-wide budget. */
+  readonly kittyImageBudget?: KittyImageBudget;
 }
 
 export interface TerminalReplicaInterpreterStats {
@@ -165,6 +175,13 @@ export class TerminalReplicaInterpreter {
   }> = [];
   #writeFlushScheduled = false;
   #widgetGate = false;
+  // kitty graphics: images outlive reseeds; the scanner owns split APCs.
+  readonly #kittyScanner = new KittyApcScanner();
+  readonly #kitty: KittyImageStore;
+  readonly #kittyPending = new Map<number, KittyCommand>();
+  readonly #graphicsListeners = new Set<(state: TerminalGraphicsState) => void>();
+  #graphics: TerminalGraphicsState | null = null;
+  #graphicsKey = "";
   #markerTail = "";
   #pendingResize: { cols: number; rows: number } | null = null;
   // null: no unpublished writes; undefined: a write requires full projection.
@@ -208,6 +225,10 @@ 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;
@@ -400,6 +421,18 @@ export class TerminalReplicaInterpreter {
       }
       const previous = this.#backend;
       this.#backend = replacement;
+      this.#attachKitty(replacement);
+      // A capture replay does not erase graphics already observed by this owner.
+      // Keep anchors only when both backends agree on their coordinate basis;
+      // reflow, history replacement and authoritative stream resets are ambiguous.
+      const sameGraphicsBasis =
+        operation.bootstrap === "painted-capture" &&
+        previous.cols === replacement.cols &&
+        previous.rows === replacement.rows &&
+        previous.graphicsViewportTop?.() !== undefined &&
+        previous.graphicsViewportTop?.() === replacement.graphicsViewportTop?.() &&
+        previous.modes().alternateScreen === replacement.modes().alternateScreen;
+      if (!sameGraphicsBasis) this.#kitty.dropCursorPlacements();
       this.#nativeReseedRequested = false;
       this.#scrollback = scrollback;
       this.#bootstrap = {
@@ -421,6 +454,7 @@ export class TerminalReplicaInterpreter {
         this.#nativeSeedBackingCandidate = undefined;
       }
       previous.dispose();
+      this.#publishGraphics();
       return;
     }
     if (operation.type === "cursor") {
@@ -434,6 +468,8 @@ export class TerminalReplicaInterpreter {
       return;
     }
     if (operation.type === "resize") {
+      if (operation.cols !== this.#backend.cols || operation.rows !== this.#backend.rows)
+        this.#kitty.dropCursorPlacements();
       this.#causalCell?.fail("geometry-drift");
       if (this.#backend.modes().synchronizedOutput) {
         // Geometry is part of the admitted FIFO even while publication is
@@ -445,6 +481,7 @@ export class TerminalReplicaInterpreter {
       }
       this.#backend.resize(operation.cols, operation.rows);
       this.#commit(false);
+      this.#publishGraphics();
       return;
     }
     const baseRevision = this.#revision;
@@ -462,6 +499,7 @@ export class TerminalReplicaInterpreter {
     };
     this.#revision = revision;
     this.#closed = true;
+    this.#kitty.dispose();
     this.#causalCell?.fail("transport-closed");
     this.#clearSyncRecovery();
     if (this.#needsSeed)
@@ -479,8 +517,18 @@ 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.
+    // A chunk entirely inside image payload changes nothing the parser can
+    // see. Skipping it matters: every parser write settles on a later timer
+    // turn, so a frame split into dozens of %output chunks would otherwise
+    // serialize dozens of turns and fall behind a 30 fps image stream.
+    if (scanned.forward.byteLength === 0) return;
+    await this.#writeToBackend(this.#backend, scanned.forward);
     if (this.#observability.enabled)
       this.#observability.recordSpan(
         "parse",
@@ -519,6 +567,7 @@ export class TerminalReplicaInterpreter {
     } else {
       this.#commit(false, this.#backend.dirtyRange(), trace);
     }
+    this.#publishGraphics();
   }
 
   #scheduleSyncRecovery(): void {
@@ -719,6 +768,55 @@ export class TerminalReplicaInterpreter {
     });
   }
 
+  /** The pane's kitty image store (bytes for the graphics side channel). */
+  kittyImages(): KittyImageStore {
+    return this.#kitty;
+  }
+
+  /** Latest graphics state, or null while the pane has never held an image. */
+  currentGraphics(): TerminalGraphicsState | null {
+    return this.#graphics;
+  }
+
+  onGraphics(listener: (state: TerminalGraphicsState) => void): () => void {
+    this.#graphicsListeners.add(listener);
+    return () => this.#graphicsListeners.delete(listener);
+  }
+
+  /** Publish graphics state when the store or the viewport-relative placements moved. */
+  #publishGraphics(): void {
+    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: TerminalInterpreterBackend): void {
+    // 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(): string {
     return (this.#snapshotHash ??= hashTerminalReplicaSnapshot(this.#snapshot));
   }

package/packages/daemon/src/terminal/session-runtime/terminal-replica-owner.ts

@@ -1,3 +1,8 @@
+import {
+  HistoryAnchorOwner,
+  type HistoryAnchorIdentity,
+  type HistoryAnchorProof,
+} from "./history-anchor-owner.ts";
 import { layoutContentRows } from "../mirror/layout-content-rows.ts";
 import type { NativeGridCapture } from "../mirror/native-grid-capture.ts";
 import type {
@@ -27,6 +32,8 @@ import type {
 } from "./runtime-observability.ts";
 import { DISABLED_SESSION_RUNTIME_OBSERVABILITY } from "./runtime-observability.ts";
 import type { CausalCellLedgerResult } from "./causal-cell-ledger.ts";
+import type { KittyImage } from "../graphics/kitty-graphics.ts";
+import type { TerminalGraphicsState } from "@tmux-ide/contracts";
 
 export interface TerminalReplicaSubscription {
   readonly generation: SessionRuntimeGeneration;
@@ -96,6 +103,7 @@ export class SessionRuntimeTerminalReplicaOwner {
   readonly #start: Promise<void>;
   #upstream: MirrorSubscription | null = null;
   #disposed = false;
+  readonly #historyAnchors = new HistoryAnchorOwner();
   #cols = 80;
   #rows = 24;
   #layoutEpoch = 0;
@@ -144,6 +152,7 @@ export class SessionRuntimeTerminalReplicaOwner {
       onNativeReseedRequired: () => {
         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();
@@ -151,6 +160,7 @@ export class SessionRuntimeTerminalReplicaOwner {
         );
       },
       onUpdate: (update, trace) => {
+        this.#historyAnchors.observe(update);
         this.#publishedIncarnation = update.incarnation;
         if (update.type === "terminal.seed") {
           this.#bootstrapped = true;
@@ -232,6 +242,18 @@ export class SessionRuntimeTerminalReplicaOwner {
     this.#interpreter.failCausalCell(reason, traceId);
   }
 
+  captureHistoryAnchor(proof: HistoryAnchorProof, historyIndex: number) {
+    if (this.#disposed || this.#reseed || this.#waitingForGeometryCapture)
+      return { status: "unavailable" as const };
+    return this.#historyAnchors.capture(proof, historyIndex);
+  }
+
+  resolveHistoryAnchor(proof: HistoryAnchorIdentity, token: string) {
+    if (this.#disposed || this.#reseed || this.#waitingForGeometryCapture)
+      return { status: "unavailable" as const };
+    return this.#historyAnchors.resolve(proof, token);
+  }
+
   /** Scalar diagnostic only: no seed construction, hashing, or owner creation. */
   inputDispatchIncarnation(): string | null {
     return this.#disposed ? null : this.#publishedIncarnation;
@@ -350,6 +372,18 @@ export class SessionRuntimeTerminalReplicaOwner {
     };
   }
 
+  /** Kitty graphics side channel: current state now (if any), then every change. */
+  subscribeGraphics(listener: (state: TerminalGraphicsState) => void): () => void {
+    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: string): KittyImage | null {
+    return this.#interpreter.kittyImages().imageByDigest(digest) ?? null;
+  }
+
   async subscribeSource(
     listener: (
       update: CanonicalTerminalReplicaUpdate,
@@ -377,6 +411,7 @@ export class SessionRuntimeTerminalReplicaOwner {
     if (this.#disposed) return;
     this.#noteLifecycle(`dispose-${reason}`);
     this.#disposed = true;
+    this.#historyAnchors.invalidate();
     this.#historyTimer?.cancel();
     this.#historyTimer = null;
     this.#subscriptionEpoch += 1;
@@ -437,6 +472,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,
@@ -561,6 +597,7 @@ export class SessionRuntimeTerminalReplicaOwner {
     this.#reseedRetryCount = 0;
     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();
     });
@@ -690,6 +727,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();
     });
@@ -697,6 +735,7 @@ export class SessionRuntimeTerminalReplicaOwner {
 
   #supervise(operation: Promise<void>): void {
     void operation.catch((error) => {
+      this.#historyAnchors.invalidate();
       this.#noteLifecycle("interpreter-fault");
       this.#interpreter.abort(error);
       this.#onFault?.(error);