tmux-ide 2.9.6 → 2.9.7

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,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 = {
@@ -421,6 +445,7 @@ export class TerminalReplicaInterpreter {
         this.#nativeSeedBackingCandidate = undefined;
       }
       previous.dispose();
+      this.#publishGraphics();
       return;
     }
     if (operation.type === "cursor") {
@@ -445,6 +470,7 @@ export class TerminalReplicaInterpreter {
       }
       this.#backend.resize(operation.cols, operation.rows);
       this.#commit(false);
+      this.#publishGraphics();
       return;
     }
     const baseRevision = this.#revision;
@@ -462,6 +488,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 +506,13 @@ 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",
@@ -519,6 +551,7 @@ export class TerminalReplicaInterpreter {
     } else {
       this.#commit(false, this.#backend.dirtyRange(), trace);
     }
+    this.#publishGraphics();
   }
 
   #scheduleSyncRecovery(): void {
@@ -719,6 +752,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);

package/packages/daemon/src/terminal/session-runtime/transport-binding.ts

@@ -104,6 +104,13 @@ function assertLiveControllerPrincipal(
   }
 }
 
+function holdsCurrentLease(shared: SharedClient): boolean {
+  const lease = shared.lease;
+  if (!lease) return false;
+  const snapshot = shared.consumer.controllerSnapshot();
+  return snapshot.controllerClientId === lease.clientId && snapshot.revision === lease.revision;
+}
+
 const clientsByRegistry = new WeakMap<object, Map<string, SharedClient>>();
 
 function authenticatedSurface(transport: SessionRuntimeTransport, hostClientId: string): string {
@@ -695,20 +702,37 @@ export class SessionRuntimeTransportBinder {
   }
 
   activateController(target: SharedClient): void {
-    if (target.lease) return;
-    const current = [...this.#clients.values()].find(
-      (candidate) =>
-        candidate !== target &&
-        candidate.consumer.session === target.consumer.session &&
-        candidate.lease,
-    );
-    if (current?.lease) {
-      const previous = current.lease;
-      current.lease = null;
-      target.lease = current.consumer.handoffController(previous, target.consumer.clientId);
+    if (target.lease && holdsCurrentLease(target)) return;
+    target.lease = null;
+    const controllerClientId = target.consumer.controllerSnapshot().controllerClientId;
+    const current =
+      controllerClientId === null || controllerClientId === target.consumer.clientId
+        ? undefined
+        : [...this.#clients.values()].find(
+            (candidate) =>
+              candidate !== target &&
+              candidate.consumer.session === target.consumer.session &&
+              candidate.consumer.clientId === controllerClientId,
+          );
+    if (!current) {
+      // Free, already ours, or held by a principal outside this binder (for
+      // example the command-center owner route): plain acquisition decides.
+      target.lease = target.consumer.acquireController();
       return;
     }
-    target.lease = target.consumer.acquireController();
+    // A transport-bound holder whose binding lost its executable lease can
+    // never type again, yet it would keep every other viewer locked out. Re-
+    // derive its exact current lease so the handoff below reclaims it; a live
+    // holder simply hands off as before. Either way only one client can type.
+    const previous =
+      current.lease && holdsCurrentLease(current)
+        ? current.lease
+        : current.consumer.acquireController();
+    const handedOff = current.consumer.handoffController(previous, target.consumer.clientId);
+    // Drop the holder's lease only after the runtime accepted the handoff; a
+    // refusal (e.g. during topology verification) must leave it executable.
+    current.lease = null;
+    target.lease = handedOff;
   }
 
   async release(
@@ -727,18 +751,23 @@ export class SessionRuntimeTransportBinder {
     }
     shared.refs -= 1;
     if (shared.refs > 0) return;
-    if (shared.lease) {
-      // A same-host passive session channel keeps the controller PRINCIPAL
-      // continuous across interactive pane retargeting. It contributes no
-      // source-pane grant and cannot type; the lease retires with the last
-      // host/session ref, while a passive-only host never acquires one.
-      const retired = shared.lease;
-      shared.lease = null;
-      shared.consumer.releaseController(retired);
-    }
-    for (const [key, candidate] of this.#clients) {
-      if (candidate === shared) this.#clients.delete(key);
+    try {
+      if (shared.lease) {
+        // A same-host passive session channel keeps the controller PRINCIPAL
+        // continuous across interactive pane retargeting. It contributes no
+        // source-pane grant and cannot type; the lease retires with the last
+        // host/session ref, while a passive-only host never acquires one.
+        const retired = shared.lease;
+        shared.lease = null;
+        shared.consumer.releaseController(retired);
+      }
+    } finally {
+      // A refused surrender must never strand the controller on a client with
+      // no transport: closing the consumer retires whatever it still owns.
+      for (const [key, candidate] of this.#clients) {
+        if (candidate === shared) this.#clients.delete(key);
+      }
+      await shared.consumer.close();
     }
-    await shared.consumer.close();
   }
 }

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

@@ -102,6 +102,19 @@ export class XtermTerminalInterpreterBackend implements TerminalInterpreterBacke
     return this.#terminal.rows;
   }
 
+  graphicsCursor(): { x: number; line: number; alternate: boolean } {
+    const buffer = this.#terminal.buffer.active;
+    return {
+      x: Math.min(buffer.cursorX, this.#terminal.cols - 1),
+      line: buffer.baseY + buffer.cursorY,
+      alternate: buffer.type === "alternate",
+    };
+  }
+
+  graphicsViewportTop(): number {
+    return this.#terminal.buffer.active.baseY;
+  }
+
   write(data: Uint8Array | string): Promise<void> {
     return new Promise((resolve) => this.#terminal.write(data, resolve));
   }

package/packages/daemon/src/tui/mirror/runtime/application-home-agents-owner.ts

@@ -326,7 +326,12 @@ export function createApplicationHomeNavigationOwner(options: {
         command === "switch-session"
       )
         return null;
-      if (options.sessionOwner()?.snapshot()?.status !== "live") return "Open a live session first";
+      const status = options.sessionOwner()?.snapshot()?.status;
+      if (status !== "live") {
+        if (status === "rebinding") return "Terminal is updating. Try again shortly.";
+        if (status === "connecting") return "Opening terminal…";
+        return "Open a live session first";
+      }
       return command !== "new-window" && command !== "new-agent" && !options.focusedPane()
         ? "Select a live pane first"
         : null;

package/packages/daemon/src/tui/mirror/runtime/application-terminal-input-ingress.ts

@@ -108,7 +108,9 @@ export function createApplicationTerminalInputIngress(
     recovery = null;
   };
   const recover = (
-    inputs: ReturnType<typeof terminalInputsForPaste>,
+    inputs:
+      | ReturnType<typeof terminalInputsForPaste>
+      | (() => ReturnType<typeof terminalInputsForPaste> | null),
     bytes: Uint8Array,
     kind: "input" | "paste",
   ): boolean => {
@@ -145,7 +147,15 @@ export function createApplicationTerminalInputIngress(
         }
       : undefined;
     recovery.inputs.push(async () => {
-      for (const [index, input] of inputs.entries()) {
+      if (
+        version !== recoveryVersion ||
+        !sameScope(target, scope()) ||
+        generation()?.status !== "live"
+      )
+        return false;
+      const framed = typeof inputs === "function" ? inputs() : inputs;
+      if (framed === null) return false;
+      for (const [index, input] of framed.entries()) {
         if (
           version !== recoveryVersion ||
           !sameScope(target, scope()) ||
@@ -197,6 +207,23 @@ export function createApplicationTerminalInputIngress(
       }
     })();
   };
+  const pasteMode = (): boolean | null => {
+    const active = generation();
+    const pane = focusedPane();
+    if (active?.status !== "live" || !active.fastLane || !pane) return null;
+    const mode = active.fastLane.lane.paneState(pane)?.snapshot?.modes.bracketedPaste;
+    return typeof mode === "boolean" ? mode : null;
+  };
+  const deliverPaste = (bytes: Uint8Array): void => {
+    const mode = pasteMode();
+    if (mode === null) {
+      // Do not let the successful drain of the surrounding FIFO hide refusal.
+      ownsNote = false;
+      setNote("terminal unavailable · paste was not sent");
+      return;
+    }
+    sendApplicationTerminalPaste(interaction, bytes, captureOrigin(), mode);
+  };
   const captureOrigin = (): boolean =>
     Boolean(currentTuiPerformanceEventSink()?.terminalInputOrigin);
   const flush = (): void => {
@@ -291,7 +318,7 @@ export function createApplicationTerminalInputIngress(
       if (bytes.length === 0) return;
       const copy = Uint8Array.from(bytes);
       try {
-        terminalInputsForPaste(Buffer.from(copy).toString("utf8"));
+        terminalInputsForPaste(Buffer.from(copy).toString("utf8"), false);
       } catch {
         setNote("terminal unavailable · paste was rejected");
         return;
@@ -304,16 +331,24 @@ export function createApplicationTerminalInputIngress(
         active.fastLane &&
         focusedPane()
       ) {
-        sendApplicationTerminalPaste(interaction, copy, captureOrigin());
+        deliverPaste(copy);
         return;
       }
-      if (recover(terminalInputsForPaste(Buffer.from(copy).toString("utf8")), copy, "paste"))
+      if (
+        recover(
+          () => {
+            const mode = pasteMode();
+            return mode === null
+              ? null
+              : terminalInputsForPaste(Buffer.from(copy).toString("utf8"), mode);
+          },
+          copy,
+          "paste",
+        )
+      )
         return;
       noteAdmission(
-        pending.enqueue(
-          () => sendApplicationTerminalPaste(interaction, copy, captureOrigin()),
-          copy.byteLength,
-        ),
+        pending.enqueue(() => deliverPaste(copy), copy.byteLength),
         "paste",
       );
     },

package/packages/daemon/src/tui/mirror/runtime/application-terminal-paste.ts

@@ -20,9 +20,10 @@ export function sendApplicationTerminalPaste(
   interaction: ApplicationTerminalInteractionController,
   bytes: Uint8Array,
   captureOrigin: boolean,
+  bracketedPaste: boolean,
 ): void {
   const text = Buffer.from(bytes).toString("utf8");
-  const inputs = terminalInputsForPaste(text);
+  const inputs = terminalInputsForPaste(text, bracketedPaste);
   for (let index = 0; index < inputs.length; index += 1) {
     const parserOrigin =
       index === 0 && captureOrigin

package/packages/daemon/src/tui/mirror/runtime/terminal-input-adapter.ts

@@ -48,10 +48,13 @@ export function terminalInputForOpenTuiKey(
 }
 
 /** Preserve paste ordering and bracketed-paste semantics without an unbounded frame. */
-export function terminalInputsForPaste(text: string): readonly SessionRuntimeTerminalInput[] {
+export function terminalInputsForPaste(
+  text: string,
+  bracketedPaste: boolean,
+): readonly SessionRuntimeTerminalInput[] {
   if (text.length === 0) return [];
   if (text.includes("\0")) throw new TypeError("terminal paste must not contain NUL");
-  const framed = `\u001b[200~${text}\u001b[201~`;
+  const framed = bracketedPaste ? `\u001b[200~${text}\u001b[201~` : text;
   const inputs: SessionRuntimeTerminalInput[] = [];
   for (let offset = 0; offset < framed.length; ) {
     let end = Math.min(offset + SESSION_RUNTIME_MAX_TERMINAL_INPUT_TEXT_CHARS, framed.length);

package/packages/daemon-client/src/fleet-connection-status.ts

@@ -25,7 +25,7 @@ export function fleetConnectionMessage(status: FleetConnectionStatus): string {
     case "invalid-target":
       return "Check the SSH alias in this machine's settings.";
     case "incompatible":
-      return "Incompatible daemon protocol. Update the remote daemon, then retry.";
+      return "App and remote daemon protocols are incompatible. Check that this app and tmux-ide on the remote machine are up to date, then retry.";
     case "invalid-descriptor":
       return "Remote daemon discovery returned an invalid response. Check the installation.";
     case "daemon-missing":

package/packages/daemon-client/src/pane-creation-refusal.ts

@@ -0,0 +1,48 @@
+/** Read only a fixed refusal code; never retain server messages or private context. */
+export async function readPaneCreationRefusal(
+  response: Response,
+  signal: AbortSignal,
+): Promise<"harness_unavailable" | undefined> {
+  if (response.status !== 409 || !response.body) return undefined;
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  try {
+    for (;;) {
+      signal.throwIfAborted();
+      const { done, value } = await reader.read();
+      if (done) break;
+      length += value.byteLength;
+      if (length > 1024) return undefined;
+      chunks.push(value);
+    }
+    signal.throwIfAborted();
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    const value: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    if (
+      !value ||
+      typeof value !== "object" ||
+      Object.keys(value).length !== 1 ||
+      !("error" in value)
+    )
+      return undefined;
+    const error = value.error;
+    return error &&
+      typeof error === "object" &&
+      Object.keys(error).length === 1 &&
+      "code" in error &&
+      error.code === "harness_unavailable"
+      ? "harness_unavailable"
+      : undefined;
+  } catch {
+    return undefined;
+  } finally {
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}

package/packages/daemon-client/src/pane-stream-client.ts

@@ -33,6 +33,9 @@ import {
   type TerminalDeliveryVisibility,
   type WorkspaceMultiplexerMutationResult,
   type WindowLinkTopology,
+  TERMINAL_GRAPHICS_MAX_REQUEST_DIGESTS,
+  type TerminalGraphicsBlob,
+  type TerminalGraphicsState,
 } from "@tmux-ide/contracts";
 import {
   calibratePaneStreamClocks,
@@ -270,6 +273,14 @@ export interface OpenPaneStreamClientOptions {
   readonly onClockCalibrationOutcome?: (outcome: PaneStreamClockCalibrationOutcome) => void;
   readonly diagnosticNextTurn?: (callback: () => void) => () => void;
   readonly onLayout?: (frame: Extract<PaneStreamServerFrame, { type: "layout" }>) => void;
+  /** Kitty graphics state; only sent when the offer carried the graphics capability. */
+  readonly onTerminalGraphics?: (pane: string, state: TerminalGraphicsState) => void;
+  /** One chunk of requested image bytes (`blob.offset` into `blob.total`). */
+  readonly onTerminalGraphicsBlob?: (
+    pane: string,
+    blob: TerminalGraphicsBlob,
+    bytes: Uint8Array,
+  ) => void;
   readonly onLayoutSnapshot?: (
     frame: Extract<PaneStreamServerFrame, { type: "layout-snapshot" }>,
   ) => void;
@@ -313,6 +324,8 @@ export type ConnectIssuedPaneStreamRuntimeClientOptions = Pick<
   | "onClockCalibrationOutcome"
   | "diagnosticNextTurn"
   | "onLayout"
+  | "onTerminalGraphics"
+  | "onTerminalGraphicsBlob"
   | "onLayoutSnapshot"
   | "onInputAck"
   | "onCausalCellProof"
@@ -369,6 +382,8 @@ export interface PaneStreamRuntimeClient {
     operationId: string,
     intent: SessionRuntimeSemanticIntent,
   ): Promise<WorkspaceMultiplexerMutationResult | null>;
+  /** Pull image bytes announced in graphics state; the daemon sends each once per request. */
+  requestTerminalGraphics(pane: string, digests: readonly string[]): void;
   close(): void;
 }
 
@@ -1590,6 +1605,14 @@ export async function connectIssuedPaneStreamRuntimeClient(
     nack: (nack) => send({ type: "terminal-delivery-nack", nack }),
     setVisibility: (address, visibility) =>
       send({ type: "terminal-delivery-visibility", ...address, visibility }),
+    requestTerminalGraphics: (pane, digests) => {
+      for (let start = 0; start < digests.length; start += TERMINAL_GRAPHICS_MAX_REQUEST_DIGESTS)
+        send({
+          type: "terminal-graphics-request",
+          pane,
+          digests: digests.slice(start, start + TERMINAL_GRAPHICS_MAX_REQUEST_DIGESTS),
+        });
+    },
     submitIntent: (operationId, intent) =>
       new Promise<WorkspaceMultiplexerMutationResult | null>((resolve, reject) => {
         const timer = createRuntimeTimer(() => {
@@ -1651,6 +1674,12 @@ function routeFrame(
     case "layout":
       options.onLayout?.(frame);
       return;
+    case "terminal-graphics":
+      options.onTerminalGraphics?.(frame.pane, frame.state);
+      return;
+    case "terminal-graphics-blob":
+      options.onTerminalGraphicsBlob?.(frame.pane, frame.blob, decodeBase64(frame.data));
+      return;
     case "layout-snapshot":
       options.onLayoutSnapshot?.(frame);
       return;