tmux-ide 2.9.12 → 2.9.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-ide",
-  "version": "2.9.12",
+  "version": "2.9.13",
   "description": "The open-source workspace for coding agents: run Claude Code, Codex and other agents in tmux with live status",
   "type": "module",
   "bin": {

package/packages/contracts/src/index.ts

@@ -50,6 +50,8 @@ export * from "./session-runtime.ts";
 export * from "./terminal-replica.ts";
 export * from "./terminal-delivery.ts";
 export * from "./terminal-graphics.ts";
+export * from "./terminal-graphics-compressed.ts";
+export * from "./terminal-surfaces.ts";
 export * from "./terminal-runtime-inventory.ts";
 export * from "./experience-shell.ts";
 export * from "./application-shell.ts";

package/packages/contracts/src/pane-stream.ts

@@ -1,3 +1,12 @@
+import {
+  TerminalSurfaceWatchSchemaZ,
+  TerminalSurfaceReceiverSchemaZ,
+  TerminalSurfaceAvailableSchemaZ,
+  TerminalSurfacePeerSchemaZ,
+  TerminalSurfaceOfferSchemaZ,
+  TerminalSurfaceRetiredSchemaZ,
+  TerminalSurfaceFallbackSchemaZ,
+} from "./terminal-surfaces.ts";
 import {
   TerminalProjectionEnvelopeSchemaZ,
   TerminalProjectionReceiptSchemaZ,
@@ -436,6 +445,10 @@ export const PaneStreamClientFrameSchemaZ = z.union([
   PaneStreamTerminalGraphicsRequestFrameSchemaZ,
   PaneStreamTerminalGraphicsLocalReleaseFrameSchemaZ,
   PaneStreamTerminalCellPixelsFrameSchemaZ,
+  TerminalSurfaceWatchSchemaZ,
+  TerminalSurfaceReceiverSchemaZ,
+  TerminalSurfaceRetiredSchemaZ,
+  TerminalSurfaceFallbackSchemaZ,
 ]);
 export type PaneStreamClientFrame = z.infer<typeof PaneStreamClientFrameSchemaZ>;
 
@@ -855,6 +868,10 @@ export const PaneStreamErrorFrameSchemaZ = z
   .strict();
 
 export const PaneStreamServerFrameSchemaZ = z.discriminatedUnion("type", [
+  TerminalSurfaceAvailableSchemaZ,
+  TerminalSurfacePeerSchemaZ,
+  TerminalSurfaceOfferSchemaZ,
+  TerminalSurfaceFallbackSchemaZ,
   PaneStreamReadyFrameSchemaZ,
   PaneStreamSeedBatchFrameSchemaZ,
   PaneStreamOutputFrameSchemaZ,

package/packages/contracts/src/terminal-delivery.ts

@@ -35,7 +35,8 @@ export type TerminalDeliveryEncoding = z.infer<typeof TerminalDeliveryEncodingSc
 
 export const TerminalDeliveryOfferSchemaZ = z
   .object({
-    protocolVersions: z.array(z.number().int().positive()).min(1).max(8),
+    // Interactive binary/graphics offers use eight slots; native surfaces add one.
+    protocolVersions: z.array(z.number().int().positive()).min(1).max(9),
     encodings: z.array(TerminalDeliveryEncodingSchemaZ).min(1).max(4),
     richPlacements: z.boolean(),
   })

package/packages/contracts/src/terminal-graphics-compressed.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import {
+  TerminalGraphicsBinaryHeaderSchemaZ,
+  TERMINAL_GRAPHICS_BINARY_HEADER_BYTES,
+  TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES,
+} from "./terminal-graphics.ts";
+
+/** TGB2 uses an independent zlib stream per chunk. Digest/offset/total still
+ * describe the original image bytes. Decoders must require exact output length,
+ * stream termination and complete input consumption before hashing or painting. */
+export const TerminalGraphicsCompressedHeaderSchemaZ = TerminalGraphicsBinaryHeaderSchemaZ.extend({
+  compression: z.literal("zlib"),
+  decodedBytes: z.number().int().min(1).max(TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES),
+}).superRefine((header, context) => {
+  if (
+    header.blob.offset + header.decodedBytes > header.blob.total ||
+    (header.blob.format !== "rgb" && header.blob.format !== "rgba")
+  )
+    context.addIssue({ code: "custom", message: "Invalid compressed graphics range or format" });
+});
+export type TerminalGraphicsCompressedHeader = z.infer<
+  typeof TerminalGraphicsCompressedHeaderSchemaZ
+>;
+export function encodeTerminalGraphicsCompressed(
+  header: TerminalGraphicsCompressedHeader,
+  bytes: Uint8Array,
+): Uint8Array {
+  const parsed = TerminalGraphicsCompressedHeaderSchemaZ.parse(header);
+  const json = new TextEncoder().encode(JSON.stringify(parsed));
+  if (
+    json.length > TERMINAL_GRAPHICS_BINARY_HEADER_BYTES ||
+    bytes.length < 1 ||
+    bytes.length >= parsed.decodedBytes
+  )
+    throw new Error("Invalid compressed graphics bounds");
+  const result = new Uint8Array(8 + json.length + bytes.length);
+  result.set([84, 71, 66, 50]);
+  new DataView(result.buffer).setUint32(4, json.length, false);
+  result.set(json, 8);
+  result.set(bytes, 8 + json.length);
+  return result;
+}
+/** Only parses the envelope; inflation belongs on the receiving worker. */
+export function decodeTerminalGraphicsCompressed(data: Uint8Array): {
+  header: TerminalGraphicsCompressedHeader;
+  bytes: Uint8Array;
+} {
+  if (
+    data.length < 10 ||
+    data.length > 8 + TERMINAL_GRAPHICS_BINARY_HEADER_BYTES + TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES ||
+    data[0] !== 84 ||
+    data[1] !== 71 ||
+    data[2] !== 66 ||
+    data[3] !== 50
+  )
+    throw new Error("Invalid compressed graphics frame");
+  const length = new DataView(data.buffer, data.byteOffset, data.byteLength).getUint32(4, false);
+  if (length < 1 || length > TERMINAL_GRAPHICS_BINARY_HEADER_BYTES || 8 + length >= data.length)
+    throw new Error("Invalid compressed graphics header");
+  const header = TerminalGraphicsCompressedHeaderSchemaZ.parse(
+    JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(data.subarray(8, 8 + length))),
+  );
+  const bytes = data.subarray(8 + length);
+  if (bytes.length >= header.decodedBytes) throw new Error("Invalid compressed graphics payload");
+  return { header, bytes };
+}

package/packages/contracts/src/terminal-graphics.ts

@@ -18,6 +18,10 @@ import { TerminalAttachmentSemanticPaneIdSchemaZ } from "./semantic-identity.ts"
 export const TERMINAL_GRAPHICS_CAPABILITY_VERSION = 101;
 /** Raw binary blob frames; requires the graphics side channel (101). */
 export const TERMINAL_GRAPHICS_BINARY_CAPABILITY_VERSION = 107;
+/** Bundles 113/114 include projection 111/112 and bounded lossless raw-pixel chunks.
+ * Older daemons ignore these and retain the offered compact/text and JSON graphics fallback. */
+export const TERMINAL_GRAPHICS_COMPRESSED_CAPABILITY_VERSION = 113;
+export const TERMINAL_GRAPHICS_COMPRESSED_LOCAL_CAPABILITY_VERSION = 114;
 /** Verified same-host file leases, including binary-blob fallback (107).
  * Offer 108 instead of 107 to retain the existing eight-capability bound.
  * Never infer locality from a loopback URL. */
@@ -100,6 +104,7 @@ export const TerminalGraphicsStateSchemaZ = z
     cellPixels: z.literal(true).optional(),
     preciseCellPixels: z.literal(true).optional(),
     binaryBlobs: z.literal(true).optional(),
+    compressedBlobs: z.literal(true).optional(),
     localFiles: z.literal(true).optional(),
   })
   .strict();

package/packages/contracts/src/terminal-surfaces.ts

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { TerminalAttachmentSemanticPaneIdSchemaZ } from "./semantic-identity.ts";
+import { SessionRuntimeGenerationSchemaZ } from "./session-runtime.ts";
+
+/** Native surface control only: no pixel bytes, filesystem paths or raw Mach names.
+ * These schemas do not authenticate a peer or advertise support. They are valid
+ * for native delivery only after explicit negotiation and verified same-host
+ * authentication. A receiver request may instead get an unsupported fallback;
+ * that never authorizes endpoint lookup. SSH/unsupported peers retain the
+ * existing graphics transport.
+ */
+export const TERMINAL_SURFACE_MAX_BYTES = 64 * 1024 * 1024;
+/** Additive opt-in; does not replace binary/kitty fallback capability bundles. */
+export const TERMINAL_SURFACE_CAPABILITY_VERSION = 116;
+export const TERMINAL_SURFACE_MAX_OUTSTANDING = 8;
+export const TERMINAL_SURFACE_MAX_CONTROL_BYTES = 16 * 1024;
+const NonNilUuid = z.uuid().refine((value) => value !== "00000000-0000-0000-0000-000000000000");
+const Sequence = z.number().int().min(1).max(Number.MAX_SAFE_INTEGER);
+/** Opaque full kernel audit identity, including incarnation. Values from control
+ * must still match the kernel trailer; numeric PID alone is never proof. */
+export const TerminalSurfaceAuditTokenSchemaZ = z
+  .array(z.number().int().min(0).max(0xffff_ffff))
+  .length(8)
+  .refine((token) => token.some((word) => word !== 0));
+const scope = {
+  version: z.literal(1),
+  generation: SessionRuntimeGenerationSchemaZ,
+  connectionNonce: NonNilUuid,
+};
+
+export const TerminalSurfaceWatchSchemaZ = z
+  .object({
+    type: z.literal("terminal-surface-watch"),
+    version: z.literal(1),
+    generation: SessionRuntimeGenerationSchemaZ,
+  })
+  .strict();
+export type TerminalSurfaceWatch = z.infer<typeof TerminalSurfaceWatchSchemaZ>;
+
+export const TerminalSurfaceAvailableSchemaZ = z
+  .object({
+    type: z.literal("terminal-surface-available"),
+    version: z.literal(1),
+    generation: SessionRuntimeGenerationSchemaZ,
+    connectionNonce: NonNilUuid.nullable(),
+  })
+  .strict();
+export type TerminalSurfaceAvailable = z.infer<typeof TerminalSurfaceAvailableSchemaZ>;
+
+export const TerminalSurfaceReceiverSchemaZ = z
+  .object({
+    type: z.literal("terminal-surface-receiver"),
+    ...scope,
+    pid: z.number().int().min(1).max(0x7fff_ffff),
+    slot: z.number().int().min(0).max(31),
+    auditToken: TerminalSurfaceAuditTokenSchemaZ,
+    challenge: NonNilUuid,
+  })
+  .strict();
+export type TerminalSurfaceReceiver = z.infer<typeof TerminalSurfaceReceiverSchemaZ>;
+
+export const TerminalSurfacePeerSchemaZ = z
+  .object({
+    type: z.literal("terminal-surface-peer"),
+    ...scope,
+    auditToken: TerminalSurfaceAuditTokenSchemaZ,
+  })
+  .strict();
+export type TerminalSurfacePeer = z.infer<typeof TerminalSurfacePeerSchemaZ>;
+
+/** Mirrors the Rust admission envelope. Admission additionally checks the exact
+ * retained committed pane identity before reservation and again before import.
+ * A storage ticket correlates a separately transferred capability, never a path.
+ */
+/** Rectangle in the committed pane's visible cell grid. History and pane
+ * replacement never inherit this placement; the canonical identity fences it. */
+export const TerminalSurfacePlacementSchemaZ = z
+  .object({
+    row: z.number().int().min(0).max(16383),
+    column: z.number().int().min(0).max(16383),
+    rows: z.number().int().min(1).max(16384),
+    columns: z.number().int().min(1).max(16384),
+  })
+  .strict()
+  .refine((rect) => rect.row + rect.rows <= 16384 && rect.column + rect.columns <= 16384);
+export type TerminalSurfacePlacement = z.infer<typeof TerminalSurfacePlacementSchemaZ>;
+
+export const TerminalSurfaceOfferSchemaZ = z
+  .object({
+    type: z.literal("terminal-surface-offer"),
+    version: z.literal(1),
+    pane: TerminalAttachmentSemanticPaneIdSchemaZ,
+    generation: SessionRuntimeGenerationSchemaZ,
+    incarnation: z.string().min(1).max(256),
+    deliveryNonce: NonNilUuid,
+    canonicalRevision: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    canonicalStateHash: z.string().regex(/^[0-9a-f]{16}$/u),
+    sequence: Sequence,
+    surfaceId: NonNilUuid,
+    placement: TerminalSurfacePlacementSchemaZ,
+    storageTicket: NonNilUuid,
+    format: z.literal("bgra8-straight"),
+    width: z.number().int().min(1).max(16384),
+    height: z.number().int().min(1).max(16384),
+    stride: z.number().int().min(4).max(TERMINAL_SURFACE_MAX_BYTES),
+    allocationBytes: z.number().int().min(4).max(TERMINAL_SURFACE_MAX_BYTES),
+  })
+  .strict()
+  .refine(
+    (offer) =>
+      offer.stride % 4 === 0 &&
+      offer.stride >= offer.width * 4 &&
+      offer.stride * offer.height <= offer.allocationBytes,
+  );
+export type TerminalSurfaceOffer = z.infer<typeof TerminalSurfaceOfferSchemaZ>;
+
+/** Sent on the original connection only after final backing/GPU ownership drops.
+ * Receipt, import, CPU decode or submission to Metal is not retirement. */
+export const TerminalSurfaceRetiredSchemaZ = z
+  .object({
+    type: z.literal("terminal-surface-retired"),
+    ...scope,
+    sequence: Sequence,
+  })
+  .strict();
+export type TerminalSurfaceRetired = z.infer<typeof TerminalSurfaceRetiredSchemaZ>;
+
+/** Ends this connection's native negotiation. A replacement connection starts
+ * fresh; no native storage is freed merely because fallback was requested. */
+export const TerminalSurfaceFallbackSchemaZ = z
+  .object({
+    type: z.literal("terminal-surface-fallback"),
+    ...scope,
+    reason: z.enum(["unsupported", "timeout", "identity", "budget", "storage"]),
+  })
+  .strict();
+export type TerminalSurfaceFallback = z.infer<typeof TerminalSurfaceFallbackSchemaZ>;

package/packages/core/src/terminal-delivery.ts

@@ -1,4 +1,6 @@
 import {
+  TERMINAL_GRAPHICS_COMPRESSED_CAPABILITY_VERSION,
+  TERMINAL_GRAPHICS_COMPRESSED_LOCAL_CAPABILITY_VERSION,
   TERMINAL_PROJECTION_CAPABILITY_VERSION,
   TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION,
 } from "@tmux-ide/contracts";
@@ -88,7 +90,9 @@ export function negotiateTerminalDelivery(
         v === TERMINAL_DELIVERY_BINARY_CAPABILITY_VERSION ||
         v === TERMINAL_DELIVERY_BINARY_LOCAL_CAPABILITY_VERSION ||
         v === TERMINAL_PROJECTION_CAPABILITY_VERSION ||
-        v === TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION,
+        v === TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION ||
+        v === TERMINAL_GRAPHICS_COMPRESSED_CAPABILITY_VERSION ||
+        v === TERMINAL_GRAPHICS_COMPRESSED_LOCAL_CAPABILITY_VERSION,
     ) && offer.encodings.includes("semantic-compact-v1");
   const encoding = binary
     ? ("semantic-binary-v1" as const)
@@ -112,7 +116,9 @@ export function negotiateTerminalDelivery(
       offer.protocolVersions.some(
         (v) =>
           v === TERMINAL_PROJECTION_CAPABILITY_VERSION ||
-          v === TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION,
+          v === TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION ||
+          v === TERMINAL_GRAPHICS_COMPRESSED_CAPABILITY_VERSION ||
+          v === TERMINAL_GRAPHICS_COMPRESSED_LOCAL_CAPABILITY_VERSION,
       )
         ? { alternateScreenProjection: "deferred-history-v1" as const }
         : {}),

package/packages/core/src/terminal-replica.ts

@@ -704,6 +704,9 @@ function applyTerminalReplicaPatchProfiled(
     patch.placements === undefined &&
     patch.bootstrap === undefined;
   if (unchanged) return current;
+  Object.freeze(grid);
+  if (grid !== current.grid && cols === current.cols && rows === current.rows)
+    registerGridPatchHash(current.grid, grid, preparedRows, profile, instrumentation);
   let history: readonly TerminalReplicaRow[];
   if (patch.history) {
     history = Object.freeze(patch.history.map(freezeRow));
@@ -1086,6 +1089,36 @@ export async function primeTerminalReplicaRowsHashCooperatively(
     ROW_ARRAY_HASH_CACHE.set(rows, { hash, length: rows.length });
 }
 
+function registerGridPatchHash(
+  previous: readonly TerminalReplicaRow[],
+  next: readonly TerminalReplicaRow[],
+  changes: readonly { readonly index: number; readonly row: TerminalReplicaRow }[],
+  profile?: MutableTerminalReplicaApplyProfile,
+  instrumentation?: TerminalReplicaApplyOptions["instrumentation"],
+): void {
+  const prior = ROW_ARRAY_HASH_CACHE.get(previous);
+  // A cached sequence proves that every retained row is deeply immutable.
+  // Without that proof (including cold or external snapshots), hash normally.
+  // Dense scrolling is cheaper as one linear fold than repeated polynomial
+  // replacements; preserve that path when more than a quarter of rows change.
+  if (!prior || changes.length > previous.length / 4) return;
+  let hash = prior.hash;
+  for (const { index } of changes) {
+    const row = next[index]!;
+    if (row === previous[index]) continue;
+    if (!isTerminalReplicaRowDeeplyFrozen(row)) return;
+    const before = BigInt(`0x${hashTerminalReplicaRow(previous[index]!)}`);
+    const after = BigInt(`0x${hashTerminalReplicaRow(row, profile, instrumentation)}`);
+    hash = BigInt.asUintN(
+      64,
+      hash + (after - before) * pow64(ROW_SEQUENCE_BASE, prior.length - 1 - index),
+    );
+  }
+  // applyTerminalReplicaPatch owns/froze this array and validates unique indices.
+  // The polynomial is unchanged: replace only each changed row's contribution.
+  ROW_ARRAY_HASH_CACHE.set(next, { hash, length: next.length });
+}
+
 export function registerTerminalReplicaRowsDeltaHash(
   previous: readonly TerminalReplicaRow[],
   next: readonly TerminalReplicaRow[],

package/packages/daemon/dist/command-center/resources/saved-machine-route.js

@@ -1,3 +1,4 @@
+import { mountSavedMachineWatch } from "./saved-machine-watch.js";
 import { bodyLimit } from "hono/body-limit";
 import { z } from "zod";
 import { SavedMachineRegistrySchema } from "@tmux-ide/contracts";
@@ -13,6 +14,7 @@ const MutationRequest = z.strictObject({
     change: SavedMachineMutationSchema,
 });
 export function mountSavedMachineRoute(app, options) {
+    mountSavedMachineWatch(app, options);
     const authorize = ownerAuthorityGate(options.ownerToken, {
         whenOwnerless: "unavailable",
         unavailableMessage: "Machine registry unavailable",

package/packages/daemon/dist/command-center/resources/saved-machine-watch.js

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { SavedMachineRegistrySchema, } from "@tmux-ide/contracts";
+import { loadSavedMachines, watchSavedMachines } from "../../lib/saved-machines.js";
+import { ownerAuthorityGate } from "../owner-authority.js";
+export const SAVED_MACHINE_WATCH_WAIT_MS = 20_000;
+const MAX_WATCHERS = 32;
+const Query = z.strictObject({
+    expectedInstanceId: z.uuid(),
+    after: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+});
+function snapshot(value) {
+    const registry = SavedMachineRegistrySchema.parse(value);
+    return {
+        registry,
+        revision: createHash("sha256").update(JSON.stringify(registry)).digest("hex"),
+    };
+}
+/** One bounded notification request. A new request always observes the latest registry. */
+export function mountSavedMachineWatch(app, options) {
+    const authorize = ownerAuthorityGate(options.ownerToken, {
+        whenOwnerless: "unavailable",
+        unavailableMessage: "Machine registry unavailable",
+        mismatchMessage: "Machine registry requires owner authority",
+    });
+    const read = options.read ?? loadSavedMachines;
+    const watch = options.watch ?? watchSavedMachines;
+    let active = 0;
+    app.get("/api/resources/saved-machines/watch", async (c) => {
+        const gate = authorize(c);
+        if (gate)
+            return gate;
+        c.header("Cache-Control", "no-store");
+        const query = Query.safeParse(c.req.query());
+        if (!query.success)
+            return c.json({ error: "Invalid registry watch request" }, 400);
+        if (query.data.expectedInstanceId !== options.daemon.instanceId)
+            return c.json({ error: "Daemon generation changed" }, 409);
+        if (active >= MAX_WATCHERS)
+            return c.json({ error: "Registry watch capacity reached" }, 429);
+        active++;
+        try {
+            const initial = snapshot(read());
+            if (query.data.after !== initial.revision)
+                return c.json({ daemon: options.daemon, ...initial });
+            const signal = c.req.raw.signal;
+            const result = await new Promise((resolve) => {
+                let settled = false;
+                let stop = () => { };
+                const finish = (result) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    signal.removeEventListener("abort", aborted);
+                    try {
+                        stop();
+                    }
+                    finally {
+                        resolve(result);
+                    }
+                };
+                const aborted = () => finish({ status: 408 });
+                const timer = setTimeout(() => finish({ status: 200, revision: initial.revision, registry: null }), SAVED_MACHINE_WATCH_WAIT_MS);
+                timer.unref();
+                const changed = (value) => {
+                    if (settled)
+                        return;
+                    try {
+                        const next = snapshot(value);
+                        if (next.revision !== initial.revision)
+                            finish({ status: 200, ...next });
+                    }
+                    catch {
+                        finish({ status: 503 });
+                    }
+                };
+                signal.addEventListener("abort", aborted, { once: true });
+                if (signal.aborted) {
+                    aborted();
+                    return;
+                }
+                try {
+                    stop = watch(changed, () => finish({ status: 503 }));
+                    // Watch implementations may synchronously report an initial error/change.
+                    if (settled) {
+                        stop();
+                        return;
+                    }
+                    // Close the read-before-subscribe race independently of watcher behavior.
+                    changed(read());
+                }
+                catch {
+                    finish({ status: 503 });
+                }
+            });
+            if (result.status !== 200)
+                return c.json({
+                    error: result.status === 408 ? "Registry watch cancelled" : "Machine registry unavailable",
+                }, result.status);
+            return c.json({
+                daemon: options.daemon,
+                revision: result.revision,
+                registry: result.registry,
+            });
+        }
+        catch {
+            return c.json({ error: "Machine registry unavailable" }, 503);
+        }
+        finally {
+            active--;
+        }
+    });
+}

package/packages/daemon/dist/command-center/server.js

@@ -1,3 +1,4 @@
+import { TERMINAL_SURFACE_CAPABILITY_VERSION } from "@tmux-ide/contracts";
 import { mountAutomationRoutes } from "./automation.js";
 import { mountTmuxServerRoutes } from "./tmux-servers.js";
 import { streamBoundedLogs } from "./log-stream.js";
@@ -422,6 +423,18 @@ export function createApp(options = {}) {
             status: "ok",
             daemon: daemonInstanceIdentity,
             capabilities: {
+                ...(c.req.query("nativeSurfaces") === "1"
+                    ? {
+                        nativeSurfaces: {
+                            supported: !!options.paneStreamIssueBackend &&
+                                options.nativeSurfaceProviderSupported?.() === true,
+                            available: options.paneStreamIssueBackend !== undefined &&
+                                options.paneStreamIssueBackend !== null &&
+                                options.nativeSurfaceProviderAvailable?.() === true,
+                            protocolVersion: TERMINAL_SURFACE_CAPABILITY_VERSION,
+                        },
+                    }
+                    : {}),
                 // Opt-in keeps the response compatible with older strict host schemas.
                 ...(c.req.query("windowViewport") === "1"
                     ? {

package/packages/daemon/dist/command-center/tmux-servers.js

@@ -1,3 +1,4 @@
+import { NativeSurfaceLocationSchema } from "../lib/native-surface-context.js";
 import { mountTmuxServerHistoryAnchorRoute } from "./tmux-server-history-anchor.js";
 import { mountTmuxServerDiagnosticsRoute } from "./tmux-server-diagnostics.js";
 import { WindowSplitLayoutUnavailable } from "../terminal/mirror/window-split-authority.js";
@@ -191,6 +192,14 @@ export function mountTmuxServerRoutes(app, options) {
             }),
         }));
     }));
+    app.post(`${scoped}/native-surface-context`, route(async (c) => {
+        const server = scope(c);
+        const target = NativeSurfaceLocationSchema.parse(await boundedJson(c.req.raw, 8192));
+        c.req.raw.signal.throwIfAborted();
+        const context = await options.owners.withOwner(server, (owner) => owner.resolveNativeSurfaceContext(target, c.req.raw.signal));
+        c.req.raw.signal.throwIfAborted();
+        return c.json({ version: 1, server, context });
+    }));
     app.get(`${scoped}/inventory/:workspaceName`, route(async (c) => {
         const server = scope(c);
         const workspaceName = workspaceSchema.parse(c.req.param("workspaceName"));

package/packages/daemon/dist/lib/daemon-embed.js

@@ -6,6 +6,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { createNativeSurfaceContextResolver } from "./native-surface-context.js";
+import { NativeSurfaceProviderRegistry } from "../terminal/graphics/native-surface-provider.js";
 import { TmuxServerVersionSchemaZ } from "@tmux-ide/contracts";
 import { createNativeSplitCapabilityProbe, createNativeSplitReadiness, } from "./native-split-capability.js";
 import { executeCanonicalSplitMutation } from "./canonical-split-mutation.js";
@@ -80,6 +82,7 @@ import { InteractionEvidenceAuthority } from "./interaction-evidence-authority.j
 import { createNativeTerminalAttachmentRuntime, WorkspaceTerminalInventoryRuntime, } from "../terminal/attachments/native-runtime.js";
 import { createTmuxAgentStatusProbe } from "../terminal/attachments/agent-status-probe.js";
 import { attachTerminalAttachmentWebSocket, } from "../server/terminal-attachment-upgrade.js";
+import { attachNativeSurfaceProvider } from "../server/native-surface-provider-upgrade.js";
 import { attachPaneStreamWebSocket, } from "../server/pane-stream-upgrade.js";
 import { createPaneStreamRuntime, } from "../terminal/pane-stream/runtime.js";
 import { SessionRuntimeRegistry } from "../terminal/session-runtime/registry.js";
@@ -543,6 +546,8 @@ async function startHttpServer({ sessionName, requestedPort, bindHostname, dir,
             issue: (request, context) => getTerminalAttachmentRuntime().admission.issue(request, context),
         },
         paneStreamIssueBackend: paneStreamRuntime.coordinator,
+        nativeSurfaceProviderSupported: () => serverOwners.isDefaultCurrent() && paneStreamRuntime.nativeSurfaces !== undefined,
+        nativeSurfaceProviderAvailable: () => serverOwners.isDefaultCurrent() && paneStreamRuntime.nativeSurfaces?.available === true,
         applicationShellInventoryBackend: terminalInventoryRuntime,
         startupReadinessAttachmentBackend: terminalInventoryRuntime,
         catalogLiveSessions,
@@ -586,7 +591,16 @@ async function startHttpServer({ sessionName, requestedPort, bindHostname, dir,
     });
     const terminalAttachmentBoundary = attachTerminalAttachmentWebSocket(server, (create) => (create ? getTerminalAttachmentRuntime() : peekTerminalAttachmentRuntime())?.admission ??
         null);
-    const paneStreamBoundary = attachPaneStreamWebSocket(server, paneStreamRuntime.coordinator, PANE_STREAM_REDEEM_PATH, () => serverOwners.isDefaultCurrent());
+    const paneStreamSocketBoundary = attachPaneStreamWebSocket(server, paneStreamRuntime.coordinator, PANE_STREAM_REDEEM_PATH, () => serverOwners.isDefaultCurrent());
+    const nativeProviderBoundary = paneStreamRuntime.nativeSurfaces
+        ? attachNativeSurfaceProvider(server, paneStreamRuntime.nativeSurfaces, localBypassToken ?? null, () => serverOwners.isDefaultCurrent())
+        : null;
+    const paneStreamBoundary = {
+        async close() {
+            nativeProviderBoundary?.close();
+            await paneStreamSocketBoundary.close();
+        },
+    };
     serverOwners.attach(server);
     try {
         await new Promise((resolve, reject) => {
@@ -1059,6 +1073,7 @@ async function startEmbeddedDaemonGeneration(opts) {
                 externalInteractionObserver.setDiagnostics(diagnostics);
                 setFleetFactsObserverDiagnostics(diagnostics);
             }
+            const nativeSurfaces = process.platform === "darwin" ? new NativeSurfaceProviderRegistry(instanceId) : undefined;
             sessionRuntimeRegistry = new SessionRuntimeRegistry({
                 generation: instanceId,
                 ...(runtimeObservability ? { observability: runtimeObservability } : {}),
@@ -1085,6 +1100,7 @@ async function startEmbeddedDaemonGeneration(opts) {
                     publishResourceChange: (change) => broadcastResourceChanged(change, instanceId),
                 },
                 mirror: {
+                    onNativeClientPresence: (session, present) => nativeSurfaces?.demand.presence(session, present),
                     splitLayoutEpoch: () => observationSelector?.nativeServerEpoch ?? null,
                     splitLayoutPrepare: createNativeSplitReadiness({
                         observation: () => observationSelector ?? null,
@@ -1249,6 +1265,7 @@ async function startEmbeddedDaemonGeneration(opts) {
                 }
             }
             paneStreamRuntime = createPaneStreamRuntime({
+                nativeSurfaces,
                 localImages,
                 daemonInstanceId: instanceId,
                 webSocketUrl: paneStreamWebSocketUrl(bindHostname, port),
@@ -1353,6 +1370,20 @@ async function startEmbeddedDaemonGeneration(opts) {
                         return grant ? interactionEvidence.captureSourceBinding(grant) : null;
                     },
                     interactionReceipts,
+                    resolveNativeSurfaceContext: createNativeSurfaceContextResolver({
+                        generation: instanceId,
+                        registry: workspaceRegistry,
+                        catalog: createNativeTmuxServerCatalog(workspaceRegistry, fleetFactsTmuxRunner),
+                        inventory: terminalInventoryRuntime,
+                        run: (args, signal) => fleetFactsTmuxRunner(args, signal),
+                        assertOpen: () => {
+                            if (defaultEditorContextRetired ||
+                                serverOwners?.defaultRetired ||
+                                !initialNativeServerIdentity ||
+                                terminalInventoryRuntime?.lifecycleState() !== "ready")
+                                throw new Error("Default native surface context owner is unavailable");
+                        },
+                    }),
                     resolvePaneEditorContext: createPaneEditorContextResolver({
                         generation: instanceId,
                         registry: workspaceRegistry,