tmux-ide 2.9.12 → 2.9.13

package/packages/daemon/src/terminal/graphics/native-surface-provider.ts

@@ -0,0 +1,308 @@
+import { NativeSurfaceDemand } from "./native-surface-demand.ts";
+import {
+  SessionRuntimeGenerationSchemaZ,
+  TerminalSurfaceAuditTokenSchemaZ,
+  TerminalSurfaceOfferSchemaZ,
+  TerminalSurfaceReceiverSchemaZ,
+  TERMINAL_SURFACE_MAX_BYTES,
+  TERMINAL_SURFACE_MAX_OUTSTANDING,
+  TERMINAL_SURFACE_MAX_CONTROL_BYTES,
+  type TerminalSurfaceReceiver,
+  type TerminalSurfaceOffer,
+  type TerminalSurfacePeer,
+  type TerminalSurfaceFallback,
+} from "@tmux-ide/contracts";
+
+type Reason = TerminalSurfaceFallback["reason"];
+type Control = TerminalSurfaceOffer | TerminalSurfacePeer | TerminalSurfaceFallback;
+/** Native provider owns the actual kernel proof, immutable backing and GPU-safe
+ * reuse policy. These callbacks must enqueue bounded work, never block Node. */
+export interface NativeSurfaceProducerConnection {
+  start(): void;
+  retire(sequence: number): void;
+  fallback(): void;
+  close(): void;
+}
+export interface NativeSurfaceProvider {
+  readonly auditToken: readonly number[];
+  open(context: {
+    readonly receiver: TerminalSurfaceReceiver;
+    readonly panes: readonly string[];
+    /** Reserve and send control before transferring a native right. False means
+     * no transfer is allowed; retry/backpressure belongs to the native owner. */
+    offer(value: unknown): boolean;
+  }): NativeSurfaceProducerConnection;
+}
+export interface NativeSurfaceSession {
+  retire(sequence: number): boolean;
+  fallback(reason: Reason): void;
+  close(): void;
+  readonly outstanding: number;
+}
+interface Registration {
+  readonly provider: NativeSurfaceProvider;
+  readonly auditToken: number[];
+  readonly sessions: Set<Session>;
+}
+
+/** Internal daemon registration only. Never construct a provider from terminal
+ * content, request-supplied paths, a PID lookup or a loopback address. The native
+ * owner must be authenticated before registration; kernel proof still follows. */
+export class NativeSurfaceProviderRegistry {
+  readonly demand = new NativeSurfaceDemand();
+  readonly generation: string;
+  #registration: Registration | null = null;
+  #sessions = new Set<Session>();
+  #bytes = 0;
+  #frames = 0;
+  #revision = 0;
+  #closed = false;
+  #watchers = new Set<(available: boolean) => void>();
+  #notificationQueued = false;
+  constructor(generation: string) {
+    this.generation = SessionRuntimeGenerationSchemaZ.parse(generation);
+  }
+  get revision(): number {
+    return this.#revision;
+  }
+  get available(): boolean {
+    return this.#registration !== null;
+  }
+  watchAvailability(listener: (available: boolean) => void): () => void {
+    if (this.#closed || this.#watchers.size >= 256)
+      throw new Error("Native surface availability subscription unavailable");
+    this.#watchers.add(listener);
+    this.#notifyAvailability();
+    return () => this.#watchers.delete(listener);
+  }
+  #notifyAvailability(): void {
+    if (this.#notificationQueued) return;
+    this.#notificationQueued = true;
+    // Provider registration must finish before a viewer can open its channel.
+    queueMicrotask(() => {
+      this.#notificationQueued = false;
+      for (const listener of [...this.#watchers]) {
+        if (!this.#watchers.has(listener)) continue;
+        try {
+          listener(this.available);
+        } catch {
+          this.#watchers.delete(listener);
+        }
+      }
+      if (this.#closed) this.#watchers.clear();
+    });
+  }
+  register(provider: NativeSurfaceProvider): () => void {
+    if (this.#closed) throw new Error("Native surface registry closed");
+    if (this.#registration) throw new Error("Native surface provider already registered");
+    const registration: Registration = {
+      provider,
+      auditToken: TerminalSurfaceAuditTokenSchemaZ.parse(provider.auditToken),
+      sessions: new Set(),
+    };
+    this.#registration = registration;
+    this.#revision++;
+    this.#notifyAvailability();
+    return () => {
+      if (this.#registration !== registration) return;
+      this.#registration = null;
+      this.#revision++;
+      // Existing original sockets may still ACK retained GPU storage. Replacing
+      // a provider never redirects those ACKs to the replacement process.
+      for (const session of registration.sessions) session.fallback("unsupported");
+      this.#notifyAvailability();
+    };
+  }
+  open(
+    receiver: TerminalSurfaceReceiver,
+    panes: readonly string[],
+    send: (frame: Control) => boolean,
+    deliveryNonce?: (pane: string, generation: string) => string | null,
+  ): NativeSurfaceSession | null {
+    receiver = TerminalSurfaceReceiverSchemaZ.parse(receiver);
+    const registration = this.#registration;
+    if (!registration || receiver.generation !== this.generation || this.#sessions.size >= 32)
+      return null;
+    const session = new Session(
+      receiver,
+      panes,
+      registration,
+      send,
+      deliveryNonce,
+      (bytes) => {
+        if (this.#frames >= 32 || this.#bytes + bytes > 256 * 1024 * 1024) return false;
+        this.#frames++;
+        this.#bytes += bytes;
+        return true;
+      },
+      (bytes) => {
+        this.#frames--;
+        this.#bytes -= bytes;
+      },
+      () => {
+        registration.sessions.delete(session);
+        this.#sessions.delete(session);
+      },
+    );
+    registration.sessions.add(session);
+    this.#sessions.add(session);
+    session.start();
+    return session;
+  }
+  close(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.demand.close();
+    this.#registration = null;
+    this.#revision++;
+    for (const session of [...this.#sessions]) session.close();
+    this.#notifyAvailability();
+  }
+}
+
+class Session implements NativeSurfaceSession {
+  #producer: NativeSurfaceProducerConnection | null = null;
+  #outstanding = new Map<number, number>();
+  #bytes = 0;
+  #lastSequence = 0;
+  #stopped = false;
+  #closed = false;
+  readonly #panes: ReadonlySet<string>;
+  constructor(
+    readonly receiver: TerminalSurfaceReceiver,
+    panes: readonly string[],
+    readonly registration: Registration,
+    readonly send: (frame: Control) => boolean,
+    readonly deliveryNonce: ((pane: string, generation: string) => string | null) | undefined,
+    readonly reserve: (bytes: number) => boolean,
+    readonly release: (bytes: number) => void,
+    readonly disposed: () => void,
+  ) {
+    this.#panes = new Set(panes);
+  }
+  get outstanding(): number {
+    return this.#outstanding.size;
+  }
+  start(): void {
+    try {
+      const producer = this.registration.provider.open({
+        receiver: structuredClone(this.receiver),
+        panes: [...this.#panes],
+        offer: (value) => this.#offer(value),
+      });
+      if (this.#stopped || this.#closed) {
+        try {
+          producer.close();
+        } catch {
+          /* Registration already revoked this connection. */
+        }
+        this.close();
+        return;
+      }
+      this.#producer = producer;
+      if (
+        !this.#send({
+          type: "terminal-surface-peer",
+          version: 1,
+          generation: this.receiver.generation,
+          connectionNonce: this.receiver.connectionNonce,
+          auditToken: [...this.registration.auditToken],
+        })
+      ) {
+        this.close();
+        return;
+      }
+      if (!this.#stopped && !this.#closed) this.#producer?.start();
+    } catch {
+      this.fallback("storage");
+    }
+  }
+  #offer(value: unknown): boolean {
+    if (this.#closed || this.#stopped || !this.#producer) return false;
+    const parsed = TerminalSurfaceOfferSchemaZ.safeParse(value);
+    if (!parsed.success) return false;
+    let offer = parsed.data;
+    // A producer's own read-only subscription has a different delivery nonce.
+    // Only the daemon owning the target viewer may bind that nonce. Preserve
+    // canonical revision/hash/incarnation exactly; the receiver verifies them.
+    if (this.deliveryNonce) {
+      const nonce = this.deliveryNonce(offer.pane, offer.generation);
+      if (!nonce) return false;
+      const rebound = TerminalSurfaceOfferSchemaZ.safeParse({ ...offer, deliveryNonce: nonce });
+      if (!rebound.success) return false;
+      offer = rebound.data;
+    }
+    if (
+      offer.generation !== this.receiver.generation ||
+      !this.#panes.has(offer.pane) ||
+      offer.sequence <= this.#lastSequence ||
+      this.#outstanding.size >= TERMINAL_SURFACE_MAX_OUTSTANDING ||
+      this.#bytes + offer.allocationBytes > TERMINAL_SURFACE_MAX_BYTES ||
+      Buffer.byteLength(JSON.stringify(offer)) > TERMINAL_SURFACE_MAX_CONTROL_BYTES ||
+      !this.reserve(offer.allocationBytes)
+    )
+      return false;
+    this.#lastSequence = offer.sequence;
+    this.#outstanding.set(offer.sequence, offer.allocationBytes);
+    this.#bytes += offer.allocationBytes;
+    if (this.#send(offer)) return !this.#closed && !this.#stopped;
+    this.close();
+    return false;
+  }
+  retire(sequence: number): boolean {
+    const bytes = this.#outstanding.get(sequence);
+    if (this.#closed || bytes === undefined) return false;
+    this.#outstanding.delete(sequence);
+    this.#bytes -= bytes;
+    this.release(bytes);
+    try {
+      this.#producer?.retire(sequence);
+    } catch {
+      this.fallback("storage");
+    }
+    return true;
+  }
+  fallback(reason: Reason): void {
+    if (this.#closed || this.#stopped) return;
+    this.#stopped = true;
+    try {
+      this.#producer?.fallback();
+    } catch {
+      /* Native owner cannot authorize new transfers. */
+    }
+    if (
+      !this.#send({
+        type: "terminal-surface-fallback",
+        version: 1,
+        generation: this.receiver.generation,
+        connectionNonce: this.receiver.connectionNonce,
+        reason,
+      })
+    )
+      this.close();
+  }
+  close(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    // Closing releases accounting/reference ownership, never grants buffer reuse.
+    // Native receivers retain their own backing/GPU leases after this connection.
+    for (const bytes of this.#outstanding.values()) this.release(bytes);
+    this.#outstanding.clear();
+    this.#bytes = 0;
+    try {
+      this.#producer?.close();
+    } catch {
+      /* All daemon-side admissions remain revoked. */
+    } finally {
+      this.#producer = null;
+      this.disposed();
+    }
+  }
+  #send(frame: Control): boolean {
+    try {
+      return this.send(frame);
+    } catch {
+      return false;
+    }
+  }
+}

package/packages/daemon/src/terminal/graphics/native-surface-viewer.ts

@@ -0,0 +1,154 @@
+import { randomUUID } from "node:crypto";
+import type {
+  TerminalSurfaceAvailable,
+  TerminalSurfaceFallback,
+  TerminalSurfaceOffer,
+  TerminalSurfacePeer,
+  TerminalSurfaceReceiver,
+  TerminalSurfaceRetired,
+} from "@tmux-ide/contracts";
+import type {
+  NativeSurfaceProviderRegistry,
+  NativeSurfaceSession,
+} from "./native-surface-provider.ts";
+
+type Output =
+  | TerminalSurfaceAvailable
+  | TerminalSurfaceFallback
+  | TerminalSurfaceOffer
+  | TerminalSurfacePeer;
+type Entry = { receiver: TerminalSurfaceReceiver; session: NativeSurfaceSession };
+const MAX_RETAINED = 8;
+
+/** One terminal socket owns every negotiation and its remaining GPU retirements. */
+export class NativeSurfaceViewer {
+  #stop: (() => void) | null = null;
+  #closed = false;
+  #revision = -1;
+  #nonce: string | null = null;
+  #used = false;
+  #active: Entry | null = null;
+  #retained = new Map<string, Entry>();
+  constructor(
+    readonly registry: NativeSurfaceProviderRegistry,
+    readonly panes: readonly string[],
+    readonly send: (frame: Output) => boolean,
+    readonly deliveryNonce: (pane: string, generation: string) => string | null,
+  ) {}
+  start(): void {
+    if (this.#closed || this.#stop) return;
+    try {
+      this.#stop = this.registry.watchAvailability((available) => {
+        if (this.#closed || this.#revision === this.registry.revision) return;
+        this.#revision = this.registry.revision;
+        this.#active?.session.fallback("unsupported");
+        this.#active = null;
+        this.#prune();
+        this.#nonce = available ? randomUUID() : null;
+        this.#used = false;
+        this.#send({
+          type: "terminal-surface-available",
+          version: 1,
+          generation: this.registry.generation,
+          connectionNonce: this.#nonce,
+        });
+      });
+    } catch {
+      this.#send({
+        type: "terminal-surface-available",
+        version: 1,
+        generation: this.registry.generation,
+        connectionNonce: null,
+      });
+      this.close();
+    }
+  }
+  receive(frame: TerminalSurfaceReceiver): boolean {
+    if (
+      this.#closed ||
+      frame.generation !== this.registry.generation ||
+      frame.connectionNonce !== this.#nonce
+    )
+      return false;
+    const previous = this.#retained.get(frame.connectionNonce);
+    if (previous) return JSON.stringify(previous.receiver) === JSON.stringify(frame);
+    if (this.#used) return false;
+    this.#used = true;
+    this.#prune();
+    if (this.#retained.size >= MAX_RETAINED) {
+      this.#fallback(frame, "budget");
+      return true;
+    }
+    const session = this.registry.open(
+      frame,
+      this.panes,
+      (control) => this.#send(control),
+      this.deliveryNonce,
+    );
+    if (!session) {
+      this.#fallback(frame, "unsupported");
+      return true;
+    }
+    if (this.#closed) {
+      session.close();
+      return true;
+    }
+    const entry = { receiver: frame, session };
+    this.#retained.set(frame.connectionNonce, entry);
+    this.#active = entry;
+    return true;
+  }
+  retire(frame: TerminalSurfaceRetired): boolean {
+    if (this.#closed || frame.generation !== this.registry.generation) return false;
+    const entry = this.#retained.get(frame.connectionNonce);
+    if (!entry?.session.retire(frame.sequence)) return false;
+    this.#prune();
+    return true;
+  }
+  fallback(frame: TerminalSurfaceFallback): boolean {
+    if (this.#closed || frame.generation !== this.registry.generation) return false;
+    const entry = this.#retained.get(frame.connectionNonce);
+    if (!entry) return this.#used && frame.connectionNonce === this.#nonce;
+    entry.session.fallback(frame.reason);
+    if (this.#active === entry) this.#active = null;
+    this.#prune();
+    return true;
+  }
+  #fallback(receiver: TerminalSurfaceReceiver, reason: TerminalSurfaceFallback["reason"]): void {
+    this.#send({
+      type: "terminal-surface-fallback",
+      version: 1,
+      generation: receiver.generation,
+      connectionNonce: receiver.connectionNonce,
+      reason,
+    });
+  }
+  #prune(): void {
+    for (const [nonce, entry] of this.#retained) {
+      if (entry !== this.#active && entry.session.outstanding === 0) {
+        entry.session.close();
+        this.#retained.delete(nonce);
+      }
+    }
+  }
+  #send(frame: Output): boolean {
+    if (this.#closed) return false;
+    try {
+      if (this.send(frame)) return !this.#closed;
+    } catch {
+      /* Revoke a failed sink. */
+    }
+    this.close();
+    return false;
+  }
+  close(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#stop?.();
+    this.#stop = null;
+    for (const entry of this.#retained.values()) entry.session.close();
+    this.#retained.clear();
+    this.#active = null;
+    this.#nonce = null;
+  }
+}

package/packages/daemon/src/terminal/mirror/mirror-service.ts

@@ -92,6 +92,8 @@ export interface MirrorServiceOptions {
   controlModeOwnershipRegistry?: ControlModeOwnershipRegistry;
   /** Emitted only after an event-triggered list-clients proof of a native client. */
   onNativeClientActivity?: (session: string) => void;
+  /** Proven native viewer presence; null preserves fallback while unknown. */
+  onNativeClientPresence?: (session: string, present: boolean | null) => void;
   captureInputWrite?: (
     session: string,
     ...args: Parameters<NonNullable<SessionChannelOptions["captureInputWrite"]>>
@@ -813,6 +815,9 @@ export class MirrorService {
             }
           },
           onNativeClientActivity: () => this.opts.onNativeClientActivity?.(session),
+          onNativeClientPresence: this.opts.onNativeClientPresence
+            ? (present) => this.opts.onNativeClientPresence?.(session, present)
+            : undefined,
           captureInputWrite: (action, semanticPaneId) =>
             this.opts.captureInputWrite?.(session, action, semanticPaneId),
           onInputWrite: (action, startedAtMicros, endedAtMicros, pendingBeforeSend) =>

package/packages/daemon/src/terminal/mirror/session-channel.ts

@@ -272,6 +272,8 @@ export interface SessionChannelOptions {
   onExit?: () => void;
   /** Event-driven proof that a non-control tmux client is actively attached. */
   onNativeClientActivity?: () => void;
+  /** null means unproven: consumers must preserve ordinary terminal output. */
+  onNativeClientPresence?: (present: boolean | null) => void;
   /** Optional diagnostic capture before dispatch; completion must not affect input. */
   captureInputWrite?: (
     action: InputAction,
@@ -514,6 +516,8 @@ export class SessionChannel {
   private disposed = false;
   private readonly nativeGrid: NativeGridCaptureReader;
   private nativeClientProbePending = false;
+  private nativeClientProbeDirty = false;
+  private nativeClientProbeClosed = false;
   // Native captures fence every geometry event; inventory fences identity only.
   private windowAuthorityOrdinal = 0;
   private readonly layoutNotificationOrdinals = new Map<string, number>();
@@ -751,7 +755,7 @@ export class SessionChannel {
     this.io.send("refresh-client -B 'tmux-ide-copy-keys:@*:#{mode-keys}'");
     this.io.send("refresh-client -B 'tmux-ide-pane-history:%*:#{history_size}'");
     this.io.send("refresh-client -B 'tmux-ide-scroll-on-clear:%*:#{scroll-on-clear}'");
-    if (this.opts.onNativeClientActivity) {
+    if (this.opts.onNativeClientActivity || this.opts.onNativeClientPresence) {
       // tmux does not guarantee `%client-attached` is broadcast to an
       // existing control client. A format subscription is the documented,
       // event-driven observation seam; its notification only schedules the
@@ -760,6 +764,7 @@ export class SessionChannel {
     }
     await this.syncNow();
     await this.firstJoin;
+    if (this.opts.onNativeClientPresence) this.probeNativeClientActivity();
   }
 
   // ── Public surface (semantic ids only) ──────────────────────────────────
@@ -1489,6 +1494,7 @@ export class SessionChannel {
   async dispose(): Promise<void> {
     if (this.disposed) return;
     this.disposed = true;
+    this.opts.onNativeClientPresence?.(null);
     this.snapshotActive?.cleanup?.();
     this.snapshotActive?.cancelFence?.();
     this.snapshotActive = null;
@@ -2951,7 +2957,7 @@ export class SessionChannel {
     // before the once-per-second subscription notification. The inventory
     // (not either notification) remains the proof.
     if (
-      this.opts.onNativeClientActivity &&
+      (this.opts.onNativeClientActivity || this.opts.onNativeClientPresence) &&
       (NATIVE_CLIENT_NOTIFICATIONS.has(name) || name === "layout-change")
     ) {
       this.probeNativeClientActivity();
@@ -3142,23 +3148,36 @@ export class SessionChannel {
   }
 
   private probeNativeClientActivity(): void {
-    if (this.nativeClientProbePending || this.disposed) return;
+    if (this.disposed || this.nativeClientProbeClosed) return;
+    this.opts.onNativeClientPresence?.(null);
+    if (this.nativeClientProbePending) {
+      this.nativeClientProbeDirty ||= this.opts.onNativeClientPresence !== undefined;
+      return;
+    }
     this.nativeClientProbePending = true;
+    this.nativeClientProbeDirty = false;
     void this.io
       .request(
         `list-clients -t "${this.opts.session}" -F "#{client_control_mode}\t#{client_activity}"`,
       )
       .then((lines) => {
-        // The daemon's own mirror is a control-mode client. Only a tmux-owned
-        // attached client (control mode = 0) is honest evidence for yielding
-        // geometry; notification names alone can include our own lifecycle.
-        if (lines.some((line) => /^0\t\d+$/u.test(line.trim()))) {
-          this.opts.onNativeClientActivity?.();
-        }
+        if (this.disposed || this.nativeClientProbeClosed || this.nativeClientProbeDirty) return;
+        // Control-mode clients include our own mirrors. Only complete valid
+        // inventory proves absence; malformed replies must preserve fallback.
+        const valid = lines.every((line) => /^[01]\t\d+$/u.test(line.trim()));
+        const present = lines.some((line) => /^0\t\d+$/u.test(line.trim()));
+        this.opts.onNativeClientPresence?.(present ? true : valid ? false : null);
+        if (present) this.opts.onNativeClientActivity?.();
+      })
+      .catch(() => {
+        if (!this.disposed && !this.nativeClientProbeClosed)
+          this.opts.onNativeClientPresence?.(null);
       })
-      .catch(() => undefined)
       .finally(() => {
         this.nativeClientProbePending = false;
+        // An attach/detach while the query ran invalidated its answer. Keep one
+        // follow-up request, rather than dropping the event or growing a queue.
+        if (this.nativeClientProbeDirty) this.probeNativeClientActivity();
       });
   }
 
@@ -4209,6 +4228,8 @@ export class SessionChannel {
 
   private onChannelExit(): void {
     if (this.disposed) return;
+    this.nativeClientProbeClosed = true;
+    this.opts.onNativeClientPresence?.(null);
     this.snapshotActive?.cancelFence?.();
     this.snapshotActive = null;
     this.snapshotQueue.clear();