tmux-ide 2.9.5 → 2.9.7

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

@@ -1,3 +1,15 @@
+import { setTimeout as waitForPublication } from "node:timers/promises";
+import {
+  WindowSplitResizeTargetSchemaZ,
+  type WindowLinkTarget,
+  type WindowSplitLayoutResource,
+  type WindowSplitResizeTarget,
+} from "@tmux-ide/contracts";
+import type {
+  createGuardedNativeSplitResize,
+  GuardedNativeSplitResizeResult,
+} from "../../lib/guarded-native-split-resize.ts";
+import { WindowSplitAuthority, WindowSplitLayoutUnavailable } from "./window-split-authority.ts";
 import { SharedWindowIndex } from "./shared-window-index.ts";
 import { RegisteredWindowGuard, type RegisteredWindowReader } from "./registered-window-guard.ts";
 import type { OwnedViewerAdapter } from "./owned-viewer-adapter.ts";
@@ -9,7 +21,6 @@ import {
   revalidateUnixSocketIdentity,
 } from "../../lib/unix-socket-authority.ts";
 import { execFile } from "node:child_process";
-import type { WindowLinkTarget } from "@tmux-ide/contracts";
 /**
  * MirrorService — the daemon-side shared mirror layer (m43 card 1).
  *
@@ -49,6 +60,12 @@ import {
 } from "./control-mode-ownership.ts";
 
 export interface MirrorServiceOptions {
+  /** Native server epoch for split observations; absent means unsupported. */
+  splitLayoutEpoch?: () => string | null;
+  /** Explicit split reads may prepare a supported observation owner once. */
+  splitLayoutPrepare?: () => Promise<boolean>;
+  /** Positively probe this native epoch before issuing handles; absent denies. */
+  splitLayoutCapability?: (epoch: string) => boolean | Promise<boolean>;
   onSharedWindowConflict?: (session: string, conflicted: boolean) => void;
   createOwnedViewerAdapter?: (session: string) => OwnedViewerAdapter | undefined;
   nativeServerIdentity?: import("../../lib/tmux-server-generation-runner.ts").NativeTmuxServerIdentity;
@@ -62,6 +79,8 @@ export interface MirrorServiceOptions {
   /** `tmux -f <file>` — tests pass /dev/null. */
   configFile?: string;
   pauseAfterSeconds?: number;
+  /** Enable kitty graphics acknowledgements on attach (default: on unless TMUX_IDE_KITTY_GRAPHICS=0). */
+  kittyGraphics?: boolean;
   /** Explicit capture tail override. Omitted preserves native retained history. */
   historyLines?: number;
   internalReadHookEmission?: SessionChannelOptions["internalReadHookEmission"];
@@ -145,6 +164,7 @@ export interface MirrorSessionRetention {
 }
 
 interface ChannelEntry {
+  splitAuthority?: WindowSplitAuthority;
   channel: SessionChannel;
   started: Promise<void>;
   refs: number;
@@ -362,6 +382,99 @@ export class MirrorService {
     };
   }
 
+  /** Read existing canonical ownership only; never attach or retain a new channel. */
+  async readWindowSplitLayout(
+    session: string,
+    target: WindowLinkTarget,
+  ): Promise<WindowSplitLayoutResource> {
+    const entry = this.channels.get(session);
+    if (this.disposed || !entry || entry.retired) throw new WindowSplitLayoutUnavailable();
+    await entry.started;
+    if (this.disposed || entry.retired || this.channels.get(session) !== entry)
+      throw new WindowSplitLayoutUnavailable();
+    if (this.opts.splitLayoutPrepare) {
+      let ready = false;
+      try {
+        ready = await this.opts.splitLayoutPrepare();
+      } catch {
+        /* Unavailable owner. */
+      }
+      if (!ready || this.disposed || entry.retired || this.channels.get(session) !== entry)
+        throw new WindowSplitLayoutUnavailable();
+    }
+    const epoch = this.opts.splitLayoutEpoch?.();
+    let supported = false;
+    try {
+      supported = Boolean(epoch && (await this.opts.splitLayoutCapability?.(epoch)));
+    } catch {
+      // Unsupported/retired servers never receive actionable split handles.
+    }
+    if (
+      !supported ||
+      this.disposed ||
+      entry.retired ||
+      this.channels.get(session) !== entry ||
+      this.opts.splitLayoutEpoch?.() !== epoch
+    )
+      throw new WindowSplitLayoutUnavailable();
+    entry.splitAuthority ??= new WindowSplitAuthority({
+      describe: (window) => entry.channel.describeSplitLayout(window),
+      serverEpoch: () => this.opts.splitLayoutEpoch?.() ?? null,
+    });
+    return entry.splitAuthority.read(target);
+  }
+
+  /** Resolve only issued handles, then revalidate immediately at native dispatch. */
+  async resizeWindowSplit(
+    session: string,
+    target: WindowSplitResizeTarget,
+    operationId: string,
+    authorizeBeforeEffect: () => void,
+    runNative: ReturnType<typeof createGuardedNativeSplitResize>,
+  ): Promise<
+    GuardedNativeSplitResizeResult & {
+      successor?: { resource: WindowSplitLayoutResource; splitId: string } | null;
+    }
+  > {
+    const captured = WindowSplitResizeTargetSchemaZ.parse(target);
+    const entry = this.channels.get(session);
+    const current = () => {
+      if (this.disposed || !entry || entry.retired || this.channels.get(session) !== entry)
+        throw new WindowSplitLayoutUnavailable();
+      if (!entry.splitAuthority) throw new WindowSplitLayoutUnavailable();
+      return entry.splitAuthority;
+    };
+    current();
+    await entry!.started;
+    const resolved = current().resolve(captured);
+    const successor = current().prepareSuccessor(captured);
+    const result = await runNative(resolved.request, {
+      operationId,
+      serverEpoch: resolved.serverEpoch,
+      session: resolved.session,
+      anchor: resolved.anchor,
+      authorizeBeforeEffect: () => {
+        current().resolve(captured);
+        authorizeBeforeEffect();
+      },
+    });
+    if (result.status !== "applied") return result;
+    // Native success is retained even if canonical publication is late or diverges.
+    // This grace period observes only; it never retries a native mutation.
+    const deadline = performance.now() + 100;
+    for (;;) {
+      try {
+        current();
+      } catch {
+        return { ...result, successor: null };
+      }
+      const next = successor(result.layout);
+      if (next !== undefined) return { ...result, successor: next };
+      if (performance.now() >= deadline) return { ...result, successor: null };
+      await waitForPublication(5);
+    }
+  }
+
   async executeWindowLinkAction(
     session: string,
     request: { action: "select" | "unlink"; target?: WindowLinkTarget; paneId?: string },
@@ -554,6 +667,7 @@ export class MirrorService {
     await Promise.allSettled(
       entries.map(async (entry) => {
         entry.retired = true;
+        entry.splitAuthority?.dispose();
         this.updateWindowMembership(entry.channel, []);
         this.channelSessions.delete(entry.channel);
         try {
@@ -625,6 +739,7 @@ export class MirrorService {
               nativeServerIdentity: this.opts.nativeServerIdentity,
               configFile: this.opts.configFile,
               pauseAfterSeconds: this.opts.pauseAfterSeconds,
+              kittyGraphics: this.opts.kittyGraphics ?? process.env.TMUX_IDE_KITTY_GRAPHICS !== "0",
               nowMicros: this.opts.nowMicros,
               nativeViewer: ownedViewer?.controlOptions(),
               nativeViewerReady: ownedViewer
@@ -730,6 +845,7 @@ export class MirrorService {
   private retire(session: string, entry: ChannelEntry): void {
     if (entry.retired) return;
     entry.retired = true;
+    entry.splitAuthority?.dispose();
     this.updateWindowMembership(entry.channel, []);
     this.channelSessions.delete(entry.channel);
     if (this.channels.get(session) === entry) this.channels.delete(session);

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

@@ -1,3 +1,14 @@
+/** Upstream tmux 3.8 reuses -R for a textual grid dump, not our JSON extension.
+ * Require the generated grid and first-row headers; arbitrary malformed native
+ * replies must remain errors rather than silently downgrading capture fidelity.
+ */
+export function isStockRawGridCapture(lines: readonly string[]): boolean {
+  return (
+    /^G [1-9][0-9]*x[1-9][0-9]* \([0-9]+\/[0-9]+\)$/.test(lines[0] ?? "") &&
+    /^\tL 0 \((?:-|0)\) flags=/.test(lines[1] ?? "")
+  );
+}
+
 /** Private native capture experiment; this is not the canonical renderer schema. */
 export interface NativeGridCaptureCell {
   readonly flags: number;

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

@@ -1,5 +1,9 @@
 import type { MirrorChannelIo } from "./control-channel.ts";
-import { decodeNativeGridCapture, type NativeGridCapture } from "./native-grid-capture.ts";
+import {
+  decodeNativeGridCapture,
+  isStockRawGridCapture,
+  type NativeGridCapture,
+} from "./native-grid-capture.ts";
 
 export type NativeGridReadResult =
   | {
@@ -83,6 +87,11 @@ export class NativeGridCaptureReader {
               finish({ status: "changed" });
               return;
             }
+            if (isStockRawGridCapture(reply.lines)) {
+              this.unsupported = true;
+              finish({ status: "unsupported" });
+              return;
+            }
             const snapshot = decodeNativeGridCapture(reply.lines.join("\n"));
             finish(
               snapshot

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

@@ -10,6 +10,7 @@ import {
 import { boundedTmuxInteractionAppendCommand } from "../../lib/tmux-interaction-retention.ts";
 import {
   decodeNativeGridCapture,
+  isStockRawGridCapture,
   isNativeBootstrapCapture,
   type NativeGridCapture,
 } from "./native-grid-capture.ts";
@@ -59,6 +60,7 @@ import type { InputAction } from "../protocol/input-coalescer.ts";
 import type { OwnedViewerAdapter } from "./owned-viewer-adapter.ts";
 import {
   parseLayout,
+  parseLayoutTree,
   parseLayoutChange,
   parseSessionWindowChanged,
   parseWindowPaneChanged,
@@ -211,7 +213,10 @@ function nativeBootstrapUnsupported(
   native: NativeGridCapture | null,
 ): boolean {
   if (ok)
-    return native !== null && (native.version !== 2 || native.currentAttributes === undefined);
+    return (
+      isStockRawGridCapture(lines) ||
+      (native !== null && (native.version !== 2 || native.currentAttributes === undefined))
+    );
   return lines.some((line) =>
     /^(?:parse error: )?(?:command capture-pane: )?unknown flag -R$/.test(line.trim()),
   );
@@ -344,6 +349,7 @@ interface SnapshotLease {
   cancelFence: (() => void) | null;
   cleanup?: () => void;
   ownsPause?: boolean;
+  attemptCharged?: boolean;
 }
 
 interface RecoveryRecord {
@@ -415,7 +421,29 @@ interface WindowRecord {
   modeKeys?: "emacs" | "vi";
 }
 
-type WindowLayout = ParsedLayout & { zoomed: boolean; unzoomed?: ParsedLayout };
+type WindowLayout = ParsedLayout & { zoomed: boolean; unzoomed?: ParsedLayout; rawLayout: string };
+
+/** Daemon-internal captured observation; execution still needs native identity guards. */
+export class SplitLayoutPublicationPending extends Error {
+  constructor() {
+    super("Split layout publication pending");
+    this.name = "SplitLayoutPublicationPending";
+  }
+}
+
+export interface NativeSplitLayoutSnapshot {
+  readonly sessionName: string;
+  readonly sessionCreated: string;
+  readonly runtimeSessionId: string;
+  readonly runtimeWindowId: string;
+  readonly semanticWindowId: string;
+  readonly rawLayout: string;
+  readonly panes: readonly {
+    readonly runtimePaneId: string;
+    readonly semanticPaneId: string;
+    readonly nativePaneBirthId: string;
+  }[];
+}
 
 function layoutIdentitiesEqual(left: WindowLayout, right: WindowLayout): boolean {
   const paneIds = (layout: ParsedLayout | undefined) => layout?.leaves.map((leaf) => leaf.id);
@@ -429,7 +457,7 @@ function layoutIdentitiesEqual(left: WindowLayout, right: WindowLayout): boolean
 interface WindowSyncStage {
   readonly observedAuthorityOrdinal: number;
   readonly windows: Map<string, WindowRecord>;
-  readonly layouts: Map<string, ParsedLayout & { zoomed: boolean; unzoomed?: ParsedLayout }>;
+  readonly layouts: Map<string, WindowLayout>;
   readonly currentWindow: string;
   readonly repairedIdentity: boolean;
   readonly links: readonly {
@@ -458,10 +486,7 @@ export class SessionChannel {
   private readonly panesByRuntime = new Map<string, PaneRecord>();
   private readonly panesBySemantic = new Map<string, PaneRecord>();
   private readonly windowsByRuntime = new Map<string, WindowRecord>();
-  private readonly layoutByWindow = new Map<
-    string,
-    ParsedLayout & { zoomed: boolean; unzoomed?: ParsedLayout }
-  >();
+  private readonly layoutByWindow = new Map<string, WindowLayout>();
   private readonly activePaneByWindow = new Map<string, string>();
   private readonly layoutSubscribers = new Set<(event: MirrorLayoutEvent) => void>();
   private readonly layoutAuthoritySubscribers = new Set<
@@ -500,7 +525,7 @@ export class SessionChannel {
   private readonly pendingLayoutOutput = new Map<
     string,
     {
-      layout: ParsedLayout & { zoomed: boolean; unzoomed?: ParsedLayout };
+      layout: WindowLayout;
       bytes: number;
       overflowed: boolean;
       records: Array<{
@@ -916,6 +941,71 @@ export class SessionChannel {
     };
   }
 
+  /** Exact native ancestry, never reconstructed from published pane rectangles. */
+  describeSplitLayout(target: WindowLinkTarget): NativeSplitLayoutSnapshot {
+    const authority = this.windowLinkAuthority;
+    const identity = this.attachedIdentity;
+    const generation = this.attachedServerGeneration;
+    if (this.disposed || this.degraded || !authority || !identity || !generation)
+      throw new Error("Split layout unavailable");
+    const resolved = authority.resolve(target);
+    const window = this.windowsByRuntime.get(resolved.runtimeWindowId);
+    const layout = this.layoutByWindow.get(resolved.runtimeWindowId);
+    if (
+      resolved.runtimeSessionId !== identity.runtimeSessionId ||
+      !window?.semanticId ||
+      window.semanticId !== target.expectedSemanticWindowId ||
+      !layout ||
+      layout.zoomed ||
+      !parseLayoutTree(layout.rawLayout)
+    )
+      throw new Error("Split layout unavailable");
+    if (this.pendingLayoutOutput.has(resolved.runtimeWindowId))
+      throw new SplitLayoutPublicationPending();
+    const native = parseLayout(layout.rawLayout)!;
+    const records = [...this.panesByRuntime.values()].filter(
+      (pane) => pane.windowRuntimeId === resolved.runtimeWindowId,
+    );
+    if (records.length !== native.leaves.length || native.leaves.length !== layout.leaves.length)
+      throw new Error("Split layout pane identity incomplete");
+    const panes = native.leaves.map((leaf) => {
+      const pane = this.panesByRuntime.get(leaf.id);
+      const birth = pane?.descriptor?.nativePaneBirthId;
+      if (
+        !pane ||
+        pane.windowRuntimeId !== resolved.runtimeWindowId ||
+        pane.descriptor?.runtimeSessionId !== identity.runtimeSessionId ||
+        pane.descriptor?.windowId !== resolved.runtimeWindowId ||
+        this.panesBySemantic.get(pane.semanticId) !== pane ||
+        !birth ||
+        !/^[1-9]\d*$/u.test(birth) ||
+        !layout.leaves.some(
+          (visible) =>
+            visible.id === leaf.id &&
+            visible.left === leaf.left &&
+            visible.top === leaf.top &&
+            visible.width === leaf.width &&
+            visible.height === leaf.height,
+        )
+      )
+        throw new Error("Split layout pane identity incomplete");
+      return Object.freeze({
+        runtimePaneId: pane.runtimeId,
+        semanticPaneId: pane.semanticId,
+        nativePaneBirthId: birth,
+      });
+    });
+    return Object.freeze({
+      sessionName: identity.sessionName,
+      sessionCreated: generation.sessionCreated,
+      runtimeSessionId: resolved.runtimeSessionId,
+      runtimeWindowId: resolved.runtimeWindowId,
+      semanticWindowId: window.semanticId,
+      rawLayout: layout.rawLayout,
+      panes: Object.freeze(panes),
+    });
+  }
+
   async executeWindowLinkAction(request: {
     action: "select" | "unlink";
     target?: WindowLinkTarget;
@@ -1874,6 +1964,7 @@ export class SessionChannel {
       return;
     }
     recovery.attempts += 1;
+    lease.attemptCharged = true;
     recovery.stage = "stock-pause";
     recovery.stock = new StockPaneSnapshot(this.snapshotContext(pane));
     // These rows were received before this pause and belong to the new seed,
@@ -2050,6 +2141,7 @@ export class SessionChannel {
       return;
     }
     recovery.attempts += 1;
+    lease.attemptCharged = true;
     const ordinal = ++recovery.reseedOrdinal;
     const participants = [...pane.subs]
       .filter((sub) => !sub.closed && !sub.frozen)
@@ -2839,6 +2931,12 @@ export class SessionChannel {
         if (pane.windowRuntimeId !== change.windowId) continue;
         const recovery = this.recoveries.get(pane.runtimeId);
         if (recovery?.lease && !recovery.lease.retired) {
+          // A newer layout cancels this capture; it is not a failed snapshot.
+          // Refund only this lease, retaining earlier failures and the original deadline.
+          if (recovery.lease.attemptCharged) {
+            recovery.lease.attemptCharged = false;
+            recovery.attempts -= 1;
+          }
           this.awaitSnapshotLayout(recovery);
           this.retrySnapshot(recovery);
         }
@@ -2847,6 +2945,7 @@ export class SessionChannel {
         ...parsed,
         zoomed: change.zoomed,
         unzoomed: parseLayout(change.layout) ?? undefined,
+        rawLayout: change.layout,
       };
       const previousLayout =
         this.pendingLayoutOutput.get(change.windowId)?.layout ??
@@ -3683,10 +3782,7 @@ export class SessionChannel {
         throw new Error("Inconsistent linked backing observation");
       backingRows.set(row.runtimeId, row);
     }
-    const nextLayoutByWindow = new Map<
-      string,
-      ParsedLayout & { zoomed: boolean; unzoomed?: ParsedLayout }
-    >();
+    const nextLayoutByWindow = new Map<string, WindowLayout>();
     for (const row of backingRows.values()) {
       const parsed = parseLayout(row.visible);
       if (!parsed) {
@@ -3694,7 +3790,12 @@ export class SessionChannel {
       }
       const unzoomed = parseLayout(row.full);
       if (!unzoomed) throw new Error(`full window layout for ${this.opts.session} is malformed`);
-      nextLayoutByWindow.set(row.runtimeId, { ...parsed, zoomed: row.zoomed, unzoomed });
+      nextLayoutByWindow.set(row.runtimeId, {
+        ...parsed,
+        zoomed: row.zoomed,
+        unzoomed,
+        rawLayout: row.full,
+      });
     }
     // Publish validated physical membership before any identity repair writes.
     // The receiving session may introduce duplicate stamps by linking a window.
@@ -3926,7 +4027,7 @@ export class SessionChannel {
 
   private async repairTrustedPaneIdentity(
     descriptors: readonly SessionPaneDescriptor[],
-    layouts: ReadonlyMap<string, ParsedLayout & { zoomed: boolean; unzoomed?: ParsedLayout }>,
+    layouts: ReadonlyMap<string, WindowLayout>,
   ): Promise<boolean> {
     if (this.opts.hasSharedWindowConflict?.())
       throw new Error(

package/packages/daemon/src/terminal/mirror/window-split-authority.ts

@@ -0,0 +1,244 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import {
+  NativeJournalUint64SchemaZ,
+  WindowLinkTargetSchemaZ,
+  WindowSplitLayoutResourceSchemaZ,
+  WindowSplitResizeTargetSchemaZ,
+  type WindowLinkTarget,
+  type WindowSplitLayoutResource,
+  type WindowSplitResizeTarget,
+} from "@tmux-ide/contracts";
+import { supportsNativeSessionGuard } from "../../lib/native-operation-command.ts";
+import type { NativeSplitResizeRequest } from "../protocol/native-split-resize.ts";
+import { parseLayoutTree, type LayoutTreeNode } from "../protocol/layout-parse.ts";
+import {
+  SplitLayoutPublicationPending,
+  type NativeSplitLayoutSnapshot,
+} from "./session-channel.ts";
+
+const MAX_RETAINED_WINDOWS = 32;
+interface SnapshotRecord {
+  readonly resource: WindowSplitLayoutResource;
+  readonly identity: string;
+  readonly snapshot: NativeSplitLayoutSnapshot;
+  readonly serverEpoch: string;
+  readonly paths: ReadonlyMap<string, readonly number[]>;
+}
+export class WindowSplitLayoutUnavailable extends Error {
+  constructor() {
+    super("Window split layout is unavailable or stale");
+    this.name = "WindowSplitLayoutUnavailable";
+  }
+}
+
+/** Bounded, opt-in handles for one canonical channel. A handle is not permission:
+ * the transport and owner must still authorize geometry and guard native effects.
+ * No raw tmux IDs, native layout strings or child paths enter the public resource.
+ * Re-read canonical state at resolution; native exact-layout guards cover changes
+ * not yet observed by the channel. Dispose this authority with its channel. */
+export class WindowSplitAuthority {
+  readonly #records = new Map<string, SnapshotRecord>();
+  #disposed = false;
+  constructor(
+    private readonly options: {
+      describe(window: WindowLinkTarget): NativeSplitLayoutSnapshot;
+      serverEpoch(): string | null;
+    },
+  ) {}
+
+  #capture(window: WindowLinkTarget) {
+    if (this.#disposed) throw new WindowSplitLayoutUnavailable();
+    const serverEpoch = z.uuid().parse(this.options.serverEpoch());
+    const snapshot = structuredClone(this.options.describe(window));
+    if (
+      snapshot.semanticWindowId !== window.expectedSemanticWindowId ||
+      !/^@(0|[1-9][0-9]{0,9})$/u.test(snapshot.runtimeWindowId) ||
+      Number(snapshot.runtimeWindowId.slice(1)) > 0xffffffff ||
+      !supportsNativeSessionGuard({
+        id: snapshot.runtimeSessionId,
+        name: snapshot.sessionName,
+        created: snapshot.sessionCreated,
+      })
+    )
+      throw new WindowSplitLayoutUnavailable();
+    const tree = parseLayoutTree(snapshot.rawLayout);
+    if (!tree || tree.width > 4096 || tree.height > 4096 || snapshot.panes.length > 256)
+      throw new WindowSplitLayoutUnavailable();
+    snapshot.panes.forEach((pane) => {
+      if (
+        !/^%(0|[1-9][0-9]{0,9})$/u.test(pane.runtimePaneId) ||
+        Number(pane.runtimePaneId.slice(1)) > 0xffffffff ||
+        !NativeJournalUint64SchemaZ.refine((birth) => birth !== "0").safeParse(
+          pane.nativePaneBirthId,
+        ).success
+      )
+        throw new WindowSplitLayoutUnavailable();
+    });
+    const mapping = new Map(snapshot.panes.map((pane) => [pane.runtimePaneId, pane]));
+    if (mapping.size !== snapshot.panes.length) throw new WindowSplitLayoutUnavailable();
+    const panes: WindowSplitLayoutResource["panes"] = [];
+    const paths = new Map<string, readonly number[]>();
+    const splits: WindowSplitLayoutResource["splits"] = [];
+    let nativeSerializationBudget = 5;
+    const visit = (node: LayoutTreeNode, path: readonly number[]) => {
+      nativeSerializationBudget += 21;
+      if (node.kind === "leaf") {
+        nativeSerializationBudget += node.id.length - 1;
+        const pane = mapping.get(node.id);
+        if (!pane) throw new WindowSplitLayoutUnavailable();
+        panes.push({
+          semanticPaneId: pane.semanticPaneId,
+          left: node.left,
+          top: node.top,
+          width: node.width,
+          height: node.height,
+        });
+        return;
+      }
+      node.children.forEach((child, index) => {
+        const childPath = [...path, index];
+        if (index < node.children.length - 1) {
+          const splitId = randomUUID();
+          paths.set(splitId, childPath);
+          splits.push({
+            splitId,
+            axis: node.axis,
+            boundary: node.axis === "cols" ? child.left + child.width : child.top + child.height,
+            start: node.axis === "cols" ? node.top : node.left,
+            length: node.axis === "cols" ? node.height : node.width,
+          });
+        }
+        visit(child, childPath);
+      });
+    };
+    visit(tree, []);
+    if (panes.length !== mapping.size || nativeSerializationBudget > 8192)
+      throw new WindowSplitLayoutUnavailable();
+    const resource = WindowSplitLayoutResourceSchemaZ.parse({
+      version: 1,
+      window,
+      layoutId: randomUUID(),
+      cols: tree.width,
+      rows: tree.height,
+      panes,
+      splits,
+    });
+    // Canonical pane order must not retire a valid geometric observation.
+    const identity = JSON.stringify({
+      window,
+      serverEpoch,
+      ...snapshot,
+      panes: [...snapshot.panes].sort((a, b) => a.runtimePaneId.localeCompare(b.runtimePaneId)),
+    });
+    return { resource, paths, snapshot, serverEpoch, identity };
+  }
+
+  read(rawWindow: WindowLinkTarget): WindowSplitLayoutResource {
+    const window = WindowLinkTargetSchemaZ.parse(rawWindow);
+    try {
+      const current = this.#capture(window);
+      const previous = this.#records.get(window.linkId);
+      const record = previous?.identity === current.identity ? previous : current;
+      this.#records.delete(window.linkId);
+      this.#records.set(window.linkId, record);
+      while (this.#records.size > MAX_RETAINED_WINDOWS)
+        this.#records.delete(this.#records.keys().next().value!);
+      return structuredClone(record.resource);
+    } catch {
+      this.#records.delete(window.linkId);
+      throw new WindowSplitLayoutUnavailable();
+    }
+  }
+
+  /** Capture ancestry before dispatch; mint a successor only from matching canonical publication. */
+  prepareSuccessor(rawTarget: WindowSplitResizeTarget) {
+    const target = WindowSplitResizeTargetSchemaZ.parse(rawTarget);
+    this.resolve(target);
+    const original = this.#records.get(target.window.linkId)!;
+    const path = original.paths.get(target.splitId)!;
+    return (
+      postLayout: string,
+    ): { resource: WindowSplitLayoutResource; splitId: string } | null | undefined => {
+      try {
+        const current = this.#capture(target.window);
+        const expectedIdentity = JSON.stringify({
+          window: target.window,
+          serverEpoch: original.serverEpoch,
+          ...original.snapshot,
+          rawLayout: postLayout,
+          panes: [...original.snapshot.panes].sort((a, b) =>
+            a.runtimePaneId.localeCompare(b.runtimePaneId),
+          ),
+        });
+        // A clamped no-op can already equal both the original and the post-state.
+        if (current.identity === expectedIdentity) {
+          const resource = this.read(target.window);
+          const canonical = this.#records.get(target.window.linkId)!;
+          if (canonical.identity !== expectedIdentity) return null;
+          const splitId = [...canonical.paths].find(
+            ([, candidate]) =>
+              candidate.length === path.length &&
+              candidate.every((part, index) => part === path[index]),
+          )?.[0];
+          return splitId ? { resource, splitId } : null;
+        }
+        return current.identity === original.identity ? undefined : null;
+      } catch (error) {
+        return error instanceof SplitLayoutPublicationPending ? undefined : null;
+      }
+    };
+  }
+
+  resolve(rawTarget: WindowSplitResizeTarget) {
+    const target = WindowSplitResizeTargetSchemaZ.parse(rawTarget);
+    const record = this.#records.get(target.window.linkId);
+    try {
+      if (
+        !record ||
+        record.resource.layoutId !== target.layoutId ||
+        JSON.stringify(record.resource.window) !== JSON.stringify(target.window)
+      )
+        throw new WindowSplitLayoutUnavailable();
+      const path = record.paths.get(target.splitId);
+      const split = record.resource.splits.find((entry) => entry.splitId === target.splitId);
+      if (!path || !split || this.#capture(target.window).identity !== record.identity)
+        throw new WindowSplitLayoutUnavailable();
+      const anchor = record.snapshot.panes[0]!;
+      const request: NativeSplitResizeRequest = {
+        sessionId: record.snapshot.runtimeSessionId,
+        windowId: record.snapshot.runtimeWindowId,
+        expectedLayout: record.snapshot.rawLayout,
+        path: [...path],
+        axis: split.axis,
+        boundary: target.boundary,
+      };
+      return {
+        request,
+        serverEpoch: record.serverEpoch,
+        session: {
+          id: record.snapshot.runtimeSessionId,
+          name: record.snapshot.sessionName,
+          created: record.snapshot.sessionCreated,
+        },
+        anchor: { paneId: anchor.runtimePaneId, paneBirthId: anchor.nativePaneBirthId! },
+      };
+    } catch {
+      // An invalid token must not evict another viewer's otherwise live token.
+      if (record && record.resource.layoutId === target.layoutId) {
+        try {
+          if (this.#capture(record.resource.window).identity !== record.identity)
+            this.#records.delete(target.window.linkId);
+        } catch {
+          this.#records.delete(target.window.linkId);
+        }
+      }
+      throw new WindowSplitLayoutUnavailable();
+    }
+  }
+
+  dispose(): void {
+    this.#disposed = true;
+    this.#records.clear();
+  }
+}