tmux-ide 2.9.5 → 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

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import {
+  WorkspaceIdSchemaZ,
   TerminalAttachmentSemanticPaneIdSchemaZ,
   SessionRuntimeSemanticIntentSchemaZ,
   type SessionRuntimeControllerLease,
@@ -103,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 {
@@ -310,7 +318,9 @@ export class SessionRuntimeTransportBinding {
     semanticPaneId: string,
     offer: TerminalDeliveryOffer,
     onMessage: (message: TerminalDeliveryServerMessage) => void | Promise<void>,
+    deliveryWorkspaceName?: string,
   ) {
+    const address = WorkspaceIdSchemaZ.parse(deliveryWorkspaceName ?? this.session);
     this.#assertOpen();
     if (!this.#allowedSourcePaneIds.has(semanticPaneId)) {
       throw new SessionRuntimeControllerLeaseError(
@@ -324,6 +334,7 @@ export class SessionRuntimeTransportBinding {
       semanticPaneId,
       offer,
       onMessage,
+      address,
     );
   }
 
@@ -338,8 +349,13 @@ export class SessionRuntimeTransportBinding {
         "The transport no longer owns controller authority.",
       );
     }
+    const geometryFence =
+      intent.verb === "workspace.pane.resize" || intent.verb === "workspace.window.split.resize"
+        ? this.#captureResizeGeometryFence()
+        : undefined;
     const scopeKey = paneId ?? "session";
-    let handle = this.#intentHandles.get(scopeKey);
+    // Geometry authority is operation-specific; never reuse an input-only handle.
+    let handle = geometryFence ? undefined : this.#intentHandles.get(scopeKey);
     if (!handle) {
       const lease = this.#shared.lease;
       handle = this.#binder.registry.createExecutionHandle(
@@ -348,6 +364,7 @@ export class SessionRuntimeTransportBinding {
         [...this.#allowedSourcePaneIds],
         () => {
           this.#assertIntentScopeOpen();
+          geometryFence?.();
           assertLiveScope(this.#shared, lease, paneId);
           if (paneId !== undefined && !this.#allowedSourcePaneIds.has(paneId)) {
             throw new SessionRuntimeControllerLeaseError(
@@ -356,8 +373,9 @@ export class SessionRuntimeTransportBinding {
             );
           }
         },
+        geometryFence,
       );
-      this.#intentHandles.set(scopeKey, handle);
+      if (!geometryFence) this.#intentHandles.set(scopeKey, handle);
     }
     // Existing viewer transport protocol acknowledges reads without returning contents.
     // Private snapshots are available only through the dedicated automation boundary.
@@ -369,6 +387,41 @@ export class SessionRuntimeTransportBinding {
       });
   }
 
+  #captureResizeGeometryFence(): () => void {
+    const assertTransport = () => {
+      this.#assertOpen();
+      if (this.#shared.geometryTransportLeaseIds.at(-1) !== this.#transportLeaseId)
+        throw new SessionRuntimeControllerLeaseError(
+          "invalid-client-capability",
+          "The transport does not own the live geometry lease.",
+        );
+    };
+    assertTransport();
+    const lease = this.#explicitAuthority
+      ? this.#geometryAuthorityLease
+      : this.requestAuthority("geometry");
+    if (!lease)
+      throw new SessionRuntimeControllerLeaseError(
+        "stale-controller-lease",
+        "Geometry authority retired.",
+      );
+    const captured = Object.freeze({ ...lease });
+    const authorize = () => {
+      assertTransport();
+      if (
+        !this.#geometryAuthorityLease ||
+        !sameAuthorityLease(captured, this.#geometryAuthorityLease)
+      )
+        throw new SessionRuntimeControllerLeaseError(
+          "stale-controller-lease",
+          "Geometry authority retired.",
+        );
+      this.#shared.consumer.assertGeometryAuthority(captured);
+    };
+    authorize();
+    return authorize;
+  }
+
   sendInput(
     semanticPaneId: string,
     input: SessionRuntimeTerminalInput,
@@ -649,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(
@@ -681,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));
   }