tmux-ide 2.9.6 → 2.9.7

package/packages/daemon/src/terminal/mirror/native-grid-capture.ts

@@ -1,3 +1,14 @@
+/** 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: readonly string[]): boolean {
+  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] ?? "")
+  );
+}
+
 /** Private native capture experiment; this is not the canonical renderer schema. */
 export interface NativeGridCaptureCell {
   readonly flags: number;

package/packages/daemon/src/terminal/mirror/native-grid-reader.ts

@@ -1,5 +1,9 @@
 import type { MirrorChannelIo } from "./control-channel.ts";
-import { decodeNativeGridCapture, type NativeGridCapture } from "./native-grid-capture.ts";
+import {
+  decodeNativeGridCapture,
+  isStockRawGridCapture,
+  type NativeGridCapture,
+} from "./native-grid-capture.ts";
 
 export type NativeGridReadResult =
   | {
@@ -83,6 +87,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/src/terminal/mirror/session-channel.ts

@@ -10,6 +10,7 @@ import {
 import { boundedTmuxInteractionAppendCommand } from "../../lib/tmux-interaction-retention.ts";
 import {
   decodeNativeGridCapture,
+  isStockRawGridCapture,
   isNativeBootstrapCapture,
   type NativeGridCapture,
 } from "./native-grid-capture.ts";
@@ -212,7 +213,10 @@ function nativeBootstrapUnsupported(
   native: NativeGridCapture | null,
 ): boolean {
   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()),
   );
@@ -345,6 +349,7 @@ interface SnapshotLease {
   cancelFence: (() => void) | null;
   cleanup?: () => void;
   ownsPause?: boolean;
+  attemptCharged?: boolean;
 }
 
 interface RecoveryRecord {
@@ -1959,6 +1964,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,
@@ -2135,6 +2141,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)
@@ -2924,6 +2931,12 @@ export class SessionChannel {
         if (pane.windowRuntimeId !== change.windowId) 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/src/terminal/pane-stream/pane-stream-websocket.ts

@@ -1,4 +1,5 @@
 import { PaneStreamLayoutSnapshotFrameSchemaZ, type WindowLinkTopology } from "@tmux-ide/contracts";
+import type { TerminalDeliveryGraphics } from "../session-runtime/terminal-delivery-hub.ts";
 import { z } from "zod";
 import {
   PANE_STREAM_MAX_HELD_DELTAS,
@@ -8,6 +9,7 @@ import {
   PANE_STREAM_PROTOCOL_VERSION,
   PANE_STREAM_REDEEM_PATH,
   PANE_STREAM_WEBSOCKET_SUBPROTOCOL,
+  TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES,
   PaneStreamClientFrameSchemaZ,
   PaneStreamLoopbackWebSocketUrlSchemaZ,
   PaneStreamRedeemFrameSchemaZ,
@@ -314,6 +316,7 @@ export interface SessionRuntimeTerminalDeliveryConnection {
   nack(nack: TerminalDeliveryNack): void;
   setVisibility(visibility: TerminalDeliveryVisibility): void;
   close(): Promise<void>;
+  readonly graphics?: TerminalDeliveryGraphics;
 }
 
 interface PendingTicket {
@@ -1039,6 +1042,10 @@ interface PaneChannel {
   frozenByWire: boolean;
   closed: boolean;
   batch: SeedBatch | null;
+  /** Kitty graphics: state announced to this client, and blob digests queued. */
+  graphicsAnnounced: boolean;
+  graphicsQueue: string[];
+  graphicsSending: boolean;
 }
 
 interface QueuedSend {
@@ -1046,6 +1053,9 @@ interface QueuedSend {
   remaining: number;
 }
 
+const GRAPHICS_MAX_QUEUED_DIGESTS = 256;
+const GRAPHICS_SEND_WINDOW_BYTES = 2 * 1024 * 1024;
+
 export class PaneStreamLiveConnection {
   readonly #clientId: string;
   readonly #socket: DirectTerminalSocket;
@@ -1214,6 +1224,9 @@ export class PaneStreamLiveConnection {
         frozenByWire: false,
         closed: false,
         batch: null,
+        graphicsAnnounced: false,
+        graphicsQueue: [],
+        graphicsSending: false,
       });
     }
   }
@@ -1619,6 +1632,7 @@ export class PaneStreamLiveConnection {
         await this.#sendTerminalDelivery(channel.semanticPaneId, message);
       pending.length = 0;
       markReady();
+      this.#startGraphics(channel);
     }
     this.#closeIfAllPanesGone();
   }
@@ -1730,6 +1744,70 @@ export class PaneStreamLiveConnection {
     await this.#awaitSemanticCredit(pane);
   }
 
+  /** Announce the pane's kitty graphics state; the client pulls bytes it lacks. */
+  #startGraphics(channel: PaneChannel): void {
+    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: string, digests: readonly string[]): void {
+    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: PaneChannel): Promise<void> {
+    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: string): Promise<void> {
     // Backpressure is pane-local. Aggregate pressure is guarded by the hard
     // socket ceiling in #drainNow, but must not let a noisy sibling prevent a
@@ -2301,6 +2379,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 ||

package/packages/daemon/src/terminal/protocol/session-descriptor-discovery.ts

@@ -183,7 +183,6 @@ export function parseSessionPaneDescriptorReply(
       !bounded(type, 256) ||
       !bounded(currentCommand, 512) ||
       !bounded(cwd, 4_096) ||
-      !bounded(title, 1_024) ||
       !bounded(windowName, 1_024) ||
       !bounded(name, 256) ||
       !bounded(missionStamp, 256) ||
@@ -203,7 +202,9 @@ export function parseSessionPaneDescriptorReply(
       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/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 {
@@ -875,6 +876,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,
@@ -1880,6 +1887,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,
@@ -2424,6 +2443,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;