tmux-ide 2.9.11 → 2.9.13

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

@@ -0,0 +1,476 @@
+import { isOwnedTerminalReplicaRow } from "./terminal-replica-owned-row.ts";
+import { z } from "zod";
+import {
+  TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES,
+  TerminalProjectionSnapshotSchemaZ,
+  TerminalProjectionPatchSchemaZ,
+  TerminalProjectionPayloadSchemaZ,
+  TerminalDeferredHistorySchemaZ,
+  TerminalProjectionEnvelopeSchemaZ,
+  TerminalProjectionReceiptSchemaZ,
+  type TerminalReplicaSnapshot,
+  type TerminalProjectionSnapshot,
+  type TerminalProjectionPatch,
+  type TerminalProjectionPayload,
+  type TerminalDeferredHistory,
+  type TerminalProjectionEnvelope,
+  type TerminalProjectionReceipt,
+} from "@tmux-ide/contracts";
+import {
+  hashTerminalReplicaRows,
+  hashTerminalReplicaTombstone,
+  freezeTerminalReplicaRow,
+  terminalReplicaRowsEqual,
+} from "./terminal-replica.ts";
+import { hashCanonicalTerminalValue } from "./terminal-replica-hash-cache.ts";
+import {
+  BinaryTerminalWriter,
+  BinaryTerminalLimitError,
+  decodeBinaryTerminalTuple,
+} from "./terminal-delivery-binary.ts";
+import {
+  TerminalDeliveryStateTooLargeError,
+  writeTerminalProjectionRowCooperatively,
+  encodeTerminalProjectionMetadataTuple,
+  encodeTerminalProjectionViewportTuple,
+  decodeTerminalProjectionViewportTuple,
+  encodeTerminalProjectionPatchTuple,
+  decodeTerminalProjectionPatchTuple,
+  hashTerminalDeliveryRepresentation,
+} from "./terminal-delivery.ts";
+
+export function terminalHistoryCommitment(
+  snapshot: TerminalReplicaSnapshot,
+): TerminalDeferredHistory {
+  return Object.freeze(
+    TerminalDeferredHistorySchemaZ.parse({
+      rows: snapshot.history.length,
+      digest: hashTerminalReplicaRows(snapshot.history),
+    }),
+  );
+}
+export function projectAlternateSnapshot(
+  snapshot: TerminalReplicaSnapshot,
+): TerminalProjectionSnapshot {
+  const { history: _history, ...viewport } = snapshot;
+  void _history;
+  const candidate = { ...viewport, deferredHistory: terminalHistoryCommitment(snapshot) };
+  if (snapshot.grid.every(isOwnedTerminalReplicaRow)) {
+    const metadata = projectionMetadata(candidate);
+    validateViewportShape(snapshot.grid, metadata);
+    return freezeProjection({ ...metadata, grid: snapshot.grid });
+  }
+  return freezeProjection(TerminalProjectionSnapshotSchemaZ.parse(candidate));
+}
+function freezeProjection(value: TerminalProjectionSnapshot): TerminalProjectionSnapshot {
+  return Object.freeze({
+    ...value,
+    grid: (Object.isFrozen(value.grid) && value.grid.every(isOwnedTerminalReplicaRow)
+      ? value.grid
+      : Object.freeze(
+          value.grid.map((row) =>
+            isOwnedTerminalReplicaRow(row) ? row : freezeTerminalReplicaRow(row),
+          ),
+        )) as unknown as TerminalProjectionSnapshot["grid"],
+    cursor: Object.freeze(value.cursor),
+    modes: Object.freeze(value.modes),
+    placements: Object.freeze(
+      value.placements.map((p) => Object.freeze(p)),
+    ) as unknown as TerminalProjectionSnapshot["placements"],
+    bootstrap: Object.freeze(value.bootstrap),
+    deferredHistory: Object.freeze(value.deferredHistory),
+  });
+}
+const { grid: _projectionGrid, ...projectionMetadataShape } =
+  TerminalProjectionSnapshotSchemaZ.shape;
+void _projectionGrid;
+const ProjectionMetadataSchema = z.object(projectionMetadataShape).strict();
+function projectionMetadata(
+  value: Omit<TerminalReplicaSnapshot, "history"> & { deferredHistory: TerminalDeferredHistory },
+) {
+  const { grid: _grid, ...metadata } = value;
+  void _grid;
+  return ProjectionMetadataSchema.parse(metadata);
+}
+function validateViewportShape(
+  grid: TerminalProjectionSnapshot["grid"],
+  metadata: Omit<TerminalProjectionSnapshot, "grid">,
+): void {
+  if (
+    grid.length !== metadata.rows ||
+    metadata.cols * metadata.rows > 1_000_000 ||
+    grid.some((row) => !row || row.cells.length !== metadata.cols) ||
+    metadata.cursor.x >= metadata.cols ||
+    metadata.cursor.y >= metadata.rows ||
+    metadata.placements.some(
+      (p) => p.row + p.rows > metadata.rows || p.column + p.columns > metadata.cols,
+    )
+  )
+    throw new TypeError("Invalid projection viewport");
+}
+export function hashTerminalProjection(value: TerminalProjectionSnapshot): string {
+  return hashCanonicalTerminalValue([
+    "terminal-projection-v1",
+    value.cols,
+    value.rows,
+    hashTerminalReplicaRows(value.grid),
+    value.cursor,
+    value.modes,
+    value.placements,
+    value.bootstrap,
+    [value.deferredHistory.rows, value.deferredHistory.digest],
+  ]);
+}
+/** Checks the source root using its omitted-history commitment, not history materialization. */
+export function hashSourceSnapshotFromProjection(value: TerminalProjectionSnapshot): string {
+  return hashCanonicalTerminalValue([
+    "terminal-replica-v1",
+    value.cols,
+    value.rows,
+    hashTerminalReplicaRows(value.grid),
+    value.deferredHistory.digest,
+    value.cursor,
+    value.modes,
+    value.placements,
+    value.bootstrap,
+  ]);
+}
+function projectionEncodingError(error: unknown): never {
+  if (error instanceof BinaryTerminalLimitError)
+    throw new TerminalDeliveryStateTooLargeError(TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES + 1);
+  throw error;
+}
+export function encodeTerminalProjection(input: TerminalProjectionPayload): Uint8Array {
+  try {
+    return encodeProjection(input);
+  } catch (error) {
+    return projectionEncodingError(error);
+  }
+}
+function encodeProjection(input: TerminalProjectionPayload): Uint8Array {
+  const value = TerminalProjectionPayloadSchemaZ.parse(input);
+  const writer = new BinaryTerminalWriter();
+  writer.header(
+    value.frame,
+    value.revision,
+    value.frame === "seed" ? undefined : value.baseRevision,
+    "TCP1",
+  );
+  if (value.frame === "tombstone") writer.value(value.tombstone.reason);
+  else {
+    const data = value.frame === "seed" ? value.projection : value.patch;
+    const tuple =
+      value.frame === "seed"
+        ? encodeTerminalProjectionViewportTuple(value.projection)
+        : encodeTerminalProjectionPatchTuple(value.patch);
+    writer.value([...tuple, [data.deferredHistory.rows, data.deferredHistory.digest]]);
+  }
+  return writer.finish();
+}
+export function decodeTerminalProjection(bytes: Uint8Array): TerminalProjectionPayload {
+  const decoded = decodeBinaryTerminalTuple(bytes, "TCP1");
+  if (decoded.frame === "tombstone")
+    return TerminalProjectionPayloadSchemaZ.parse({
+      frame: decoded.frame,
+      baseRevision: decoded.baseRevision,
+      revision: decoded.revision,
+      tombstone: { reason: decoded.value },
+    });
+  const tuple = decoded.value;
+  const expected = decoded.frame === "seed" ? 8 : 7;
+  if (!Array.isArray(tuple) || tuple.length !== expected)
+    throw new TypeError("Invalid projection tuple");
+  const deferred = tuple[expected - 1];
+  if (!Array.isArray(deferred) || deferred.length !== 2)
+    throw new TypeError("Invalid deferred history tuple");
+  const deferredHistory = TerminalDeferredHistorySchemaZ.parse({
+    rows: deferred[0],
+    digest: deferred[1],
+  });
+  if (decoded.frame === "seed")
+    return {
+      frame: "seed",
+      revision: decoded.revision,
+      projection: freezeProjection(
+        TerminalProjectionSnapshotSchemaZ.parse({
+          ...decodeTerminalProjectionViewportTuple(tuple.slice(0, -1)),
+          deferredHistory,
+        }),
+      ),
+    };
+  return TerminalProjectionPayloadSchemaZ.parse({
+    frame: "patch",
+    baseRevision: decoded.baseRevision,
+    revision: decoded.revision,
+    patch: { ...decodeTerminalProjectionPatchTuple(tuple.slice(0, -1)), deferredHistory },
+  });
+}
+export function applyTerminalProjectionPatch(
+  current: TerminalProjectionSnapshot,
+  input: TerminalProjectionPatch,
+): TerminalProjectionSnapshot {
+  const patch = TerminalProjectionPatchSchemaZ.parse(input);
+  const cols = patch.dimensions?.cols ?? current.cols,
+    rows = patch.dimensions?.rows ?? current.rows;
+  // A resize requires every visible row, avoiding invented blank cells or implicit history.
+  if (cols !== current.cols || rows !== current.rows) {
+    if (patch.rows.length !== rows || new Set(patch.rows.map((r) => r.index)).size !== rows)
+      throw new TypeError("Projection resize requires complete visible rows");
+  }
+  const grid = current.grid.slice(0, rows);
+  const indices = new Set<number>();
+  for (const change of patch.rows) {
+    if (indices.has(change.index) || change.index >= rows || change.row.cells.length !== cols)
+      throw new TypeError("Invalid projection row patch");
+    indices.add(change.index);
+    const old = grid[change.index];
+    grid[change.index] =
+      old && terminalReplicaRowsEqual(old, change.row) ? old : freezeTerminalReplicaRow(change.row);
+  }
+  const candidate = {
+    ...current,
+    cols,
+    rows,
+    grid,
+    cursor: patch.cursor ?? current.cursor,
+    modes: patch.modes ?? current.modes,
+    placements: patch.placements ?? current.placements,
+    bootstrap: patch.bootstrap ?? current.bootstrap,
+    deferredHistory: patch.deferredHistory,
+  };
+  // Validate without using the parsed copy so unchanged immutable rows retain identity.
+  validateViewportShape(grid, projectionMetadata(candidate));
+  return freezeProjection(candidate);
+}
+export interface TerminalProjectionState {
+  readonly receipt: TerminalProjectionReceipt;
+  readonly projection: TerminalProjectionSnapshot | null;
+}
+export function hashTerminalProjectionTombstone(reason: string): string {
+  return hashCanonicalTerminalValue(["terminal-projection-tombstone-v1", reason]);
+}
+/** Atomic projection commit. Only this verified path creates a receipt; failures leave current intact. */
+export function commitTerminalProjection(
+  current: TerminalProjectionState | null,
+  envelope: TerminalProjectionEnvelope,
+  bytes: Uint8Array,
+): TerminalProjectionState {
+  const frame = TerminalProjectionEnvelopeSchemaZ.parse(envelope);
+  if (
+    bytes.length !== frame.representationBytes ||
+    hashTerminalDeliveryRepresentation(bytes) !== frame.representationHash
+  )
+    throw new TypeError("Projection representation mismatch");
+  const value = decodeTerminalProjection(bytes);
+  if (
+    value.frame !== frame.frame ||
+    value.revision !== frame.canonicalRevision ||
+    (value.frame === "seed"
+      ? frame.baseRevision !== null
+      : value.baseRevision !== frame.baseRevision)
+  )
+    throw new TypeError("Projection envelope mismatch");
+  if (current) {
+    for (const key of [
+      "workspaceName",
+      "semanticPaneId",
+      "generation",
+      "incarnation",
+      "deliveryNonce",
+    ] as const)
+      if (current.receipt[key] !== frame[key]) throw new TypeError("Projection lifetime mismatch");
+    if (
+      value.revision < current.receipt.canonicalRevision ||
+      (value.revision === current.receipt.canonicalRevision &&
+        (frame.canonicalStateHash !== current.receipt.canonicalStateHash ||
+          frame.projectionStateHash !== current.receipt.projectionStateHash))
+    )
+      throw new TypeError("Stale projection revision");
+    if (current.projection === null) throw new TypeError("Projection lifetime is closed");
+  }
+  if (
+    value.frame !== "seed" &&
+    (!current || current.receipt.canonicalRevision !== value.baseRevision)
+  )
+    throw new TypeError("Projection baseline mismatch");
+  const projection =
+    value.frame === "seed"
+      ? value.projection
+      : value.frame === "patch"
+        ? applyTerminalProjectionPatch(current!.projection!, value.patch)
+        : null;
+  const projectionHash = projection
+    ? hashTerminalProjection(projection)
+    : hashTerminalProjectionTombstone(value.frame === "tombstone" ? value.tombstone.reason : "");
+  const sourceHash = projection
+    ? hashSourceSnapshotFromProjection(projection)
+    : hashTerminalReplicaTombstone(value.frame === "tombstone" ? value.tombstone.reason : "");
+  if (projectionHash !== frame.projectionStateHash || sourceHash !== frame.canonicalStateHash)
+    throw new TypeError("Projection state proof mismatch");
+  const receipt = TerminalProjectionReceiptSchemaZ.parse({
+    type: "terminal.projection.receipt",
+    workspaceName: frame.workspaceName,
+    semanticPaneId: frame.semanticPaneId,
+    generation: frame.generation,
+    incarnation: frame.incarnation,
+    deliveryNonce: frame.deliveryNonce,
+    transactionId: frame.transactionId,
+    canonicalRevision: frame.canonicalRevision,
+    canonicalStateHash: frame.canonicalStateHash,
+    projectionStateHash: frame.projectionStateHash,
+    representationHash: frame.representationHash,
+  });
+  return Object.freeze({ projection, receipt: Object.freeze(receipt) });
+}
+
+function rowCheckpoints(
+  writer: BinaryTerminalWriter,
+  options: { readonly yieldControl: () => Promise<void>; readonly signal?: AbortSignal },
+) {
+  let cells = 0,
+    bytes = writer.byteLength;
+  return async (length: number) => {
+    cells += length;
+    if (cells >= 256 || writer.byteLength - bytes >= 32 * 1024) {
+      cells = 0;
+      bytes = writer.byteLength;
+      await options.yieldControl();
+      options.signal?.throwIfAborted();
+    }
+  };
+}
+
+/** Task checkpoints bound cell validation and emission even for a single giant row. */
+async function encodeProjectionCooperatively(
+  input: TerminalProjectionPayload,
+  options: { readonly yieldControl: () => Promise<void>; readonly signal?: AbortSignal },
+): Promise<Uint8Array> {
+  options.signal?.throwIfAborted();
+  if (input.frame === "tombstone") return encodeTerminalProjection(input);
+  if (input.frame === "patch") {
+    const { patch, ...header } = input;
+    const parsedHeader = z
+      .object({
+        frame: z.literal("patch"),
+        revision: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+        baseRevision: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+      })
+      .strict()
+      .parse(header);
+    if (parsedHeader.revision <= parsedHeader.baseRevision)
+      throw new TypeError("Projection revision must advance");
+    const { rows, ...metadata } = patch;
+    const { rows: _rowSchema, ...shape } = TerminalProjectionPatchSchemaZ.shape;
+    void _rowSchema;
+    const parsed = z.object(shape).strict().parse(metadata);
+    if (
+      !Array.isArray(rows) ||
+      rows.length > 4096 ||
+      (parsed.dimensions && (parsed.dimensions.cols > 4096 || parsed.dimensions.rows > 4096))
+    )
+      throw new TypeError("Projection patch bound");
+    let cells = 0;
+    const indices = new Set<number>();
+    const writer = new BinaryTerminalWriter();
+    writer.header("patch", parsedHeader.revision, parsedHeader.baseRevision, "TCP1");
+    writer.array(7);
+    writer.value(parsed.dimensions ? [parsed.dimensions.cols, parsed.dimensions.rows] : null);
+    writer.array(rows.length);
+    const checkpoint = rowCheckpoints(writer, options);
+    for (const entry of rows) {
+      const parsedEntry = z
+        .object({ index: z.number().int().min(0).max(4095), row: z.unknown() })
+        .strict()
+        .parse(entry);
+      if (indices.has(parsedEntry.index)) throw new TypeError("Duplicate projection row");
+      indices.add(parsedEntry.index);
+      cells += entry.row.cells.length;
+      if (cells > 1_000_000) throw new TypeError("Projection cell bound");
+      writer.array(2);
+      writer.value(parsedEntry.index);
+      await writeTerminalProjectionRowCooperatively(
+        writer,
+        entry.row,
+        parsed.dimensions?.cols ?? null,
+        options,
+      );
+      await checkpoint(entry.row.cells.length);
+    }
+    const tuple = encodeTerminalProjectionPatchTuple({ ...parsed, rows: [] });
+    writer.value(tuple[2]);
+    writer.value(tuple[3]);
+    if (tuple[4] === null) writer.value(null);
+    else {
+      const placements = tuple[4] as readonly unknown[];
+      writer.array(placements.length);
+      for (const value of placements) {
+        writer.value(value);
+        await options.yieldControl();
+        options.signal?.throwIfAborted();
+      }
+    }
+    writer.value(tuple[5]);
+    writer.value([parsed.deferredHistory.rows, parsed.deferredHistory.digest]);
+    options.signal?.throwIfAborted();
+    return writer.finish();
+  }
+  const { projection, ...header } = input;
+  const parsedHeader = z
+    .object({
+      frame: z.literal("seed"),
+      revision: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    })
+    .strict()
+    .parse(header);
+  const { grid, ...metadata } = projection;
+  const { grid: _gridSchema, ...metadataShape } = TerminalProjectionSnapshotSchemaZ.shape;
+  void _gridSchema;
+  const parsed = z.object(metadataShape).strict().parse(metadata);
+  if (
+    !Array.isArray(grid) ||
+    grid.length !== parsed.rows ||
+    parsed.cols * parsed.rows > 1_000_000 ||
+    parsed.cursor.x >= parsed.cols ||
+    parsed.cursor.y >= parsed.rows ||
+    parsed.placements.some(
+      (p) => p.row + p.rows > parsed.rows || p.column + p.columns > parsed.cols,
+    )
+  )
+    throw new TypeError("Invalid projection dimensions");
+  const writer = new BinaryTerminalWriter();
+  writer.header("seed", parsedHeader.revision, undefined, "TCP1");
+  writer.array(8);
+  writer.value(parsed.cols);
+  writer.value(parsed.rows);
+  writer.array(grid.length);
+  const checkpoint = rowCheckpoints(writer, options);
+  for (const row of grid) {
+    await writeTerminalProjectionRowCooperatively(writer, row, parsed.cols, options);
+    await checkpoint(row.cells.length);
+  }
+  const tuple = encodeTerminalProjectionMetadataTuple(parsed);
+  writer.value(tuple[0]);
+  writer.value(tuple[1]);
+  const placements = tuple[2] as readonly unknown[];
+  writer.array(placements.length);
+  for (const placement of placements) {
+    writer.value(placement);
+    await options.yieldControl();
+    options.signal?.throwIfAborted();
+  }
+  writer.value(tuple[3]);
+  writer.value([parsed.deferredHistory.rows, parsed.deferredHistory.digest]);
+  options.signal?.throwIfAborted();
+  return writer.finish();
+}
+
+export async function encodeTerminalProjectionCooperatively(
+  input: TerminalProjectionPayload,
+  options: { readonly yieldControl: () => Promise<void>; readonly signal?: AbortSignal },
+): Promise<Uint8Array> {
+  try {
+    return await encodeProjectionCooperatively(input, options);
+  } catch (error) {
+    return projectionEncodingError(error);
+  }
+}

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));
@@ -1048,7 +1051,7 @@ function hashTerminalReplicaRow(
   return hash;
 }
 
-function hashTerminalReplicaRows(
+export function hashTerminalReplicaRows(
   rows: readonly TerminalReplicaRow[],
   profile?: MutableTerminalReplicaApplyProfile,
   instrumentation?: TerminalReplicaApplyOptions["instrumentation"],
@@ -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"
                     ? {