tmux-ide 2.9.0-beta.8 → 2.9.2

package/packages/daemon/dist/terminal/mirror/session-channel.js

@@ -1,3 +1,7 @@
+import { layoutContentRows } from "./layout-content-rows.js";
+import { decodeNativeAtomicSnapshot, decodeNativeAtomicDualSnapshot, nativeAtomicDualSnapshotPlan, nativeAtomicSnapshotPlan, } from "./native-atomic-snapshot.js";
+import { boundedTmuxInteractionAppendCommand } from "../../lib/tmux-interaction-retention.js";
+import { decodeNativeGridCapture, isNativeBootstrapCapture, } from "./native-grid-capture.js";
 /**
  * SessionChannel — one control-mode channel serving every pane subscription
  * of one tmux session (m43 card 1).
@@ -28,7 +32,7 @@
  */
 import { createHash, randomBytes } from "node:crypto";
 import { hostname } from "node:os";
-import { WORKSPACE_SEMANTIC_PANE_OPTION, WORKSPACE_SEMANTIC_WINDOW_OPTION, WorkspaceIdSchemaZ, } from "@tmux-ide/contracts";
+import { WINDOW_LINK_MAX_LINKS, WORKSPACE_SEMANTIC_PANE_OPTION, WORKSPACE_SEMANTIC_WINDOW_OPTION, WorkspaceIdSchemaZ, } from "@tmux-ide/contracts";
 import { textToHexKeys } from "../protocol/control.js";
 import { InputCoalescer } from "../protocol/input-coalescer.js";
 import { NativeGridCaptureReader } from "./native-grid-reader.js";
@@ -36,8 +40,11 @@ import { parseLayout, parseLayoutChange, parseSessionWindowChanged, parseWindowP
 import { SESSION_PANE_DESCRIPTOR_FORMAT, SessionDescriptorDiscovery, decodeControlReplyUtf8, decodeTmuxArgument, parseSessionPaneDescriptorReply, } from "../protocol/session-descriptor-discovery.js";
 import { resolvePaneDisplayName } from "../protocol/pane-display-name.js";
 import { finalizeWorkspaceTmuxReconciliation, planWorkspaceTmuxReconciliation, } from "../protocol/workspace-tmux-adapter.js";
+import { liveSessionIdForNativeIdentity } from "../protocol/live-session-identity.js";
+import { WindowLinkAuthority, WindowLinkResolutionError } from "./window-link-authority.js";
+import { buildNativeWindowLinkGuard, buildNativeWindowLinkPaneSelectGuard, classifyNativeWindowLinkGuardResult, } from "../../lib/tmux-window-link-guard.js";
 import { FlowLedger } from "./flow-ledger.js";
-import { PaneFeed } from "./pane-feed.js";
+import { PaneFeed, captureLinesFromAnsiBytes, parseCursorProbe } from "./pane-feed.js";
 import { INTERNAL_READ_OPERATION_OPTION, registerInternalReadOperation, retireInternalReadOperation, } from "../../lib/tmux-interaction-options.js";
 const TMUX_SERVER_HOSTNAME = hostname();
 /** Notifications whose payload cannot be applied directly — fall back to the
@@ -96,7 +103,19 @@ const RECOVERY_CURSOR_PROBE_FORMAT = [
     "#{mouse_utf8_flag}",
     "#{scroll_region_upper}",
     "#{scroll_region_lower}",
-].join(" ");
+    "#{scroll-on-clear}",
+]
+    // Older tmux versions leave unsupported format fields empty (for example
+    // bracket_paste_flag on 3.4). Preserve their slots without guessing a mode:
+    // collapsing an empty field shifts every later observation to the wrong key.
+    .map((field) => `#{?#{==:${field},},unknown,${field}}`)
+    .join(" ");
+/** Cache only proven server capability; malformed or failed reads can recover. */
+function nativeBootstrapUnsupported(ok, lines, native) {
+    if (ok)
+        return native !== null && (native.version !== 2 || native.currentAttributes === undefined);
+    return lines.some((line) => /^(?:parse error: )?(?:command capture-pane: )?unknown flag -R$/.test(line.trim()));
+}
 const FAILED_RESEED_RESULT = Object.freeze({
     ok: false,
     fingerprint: null,
@@ -126,6 +145,12 @@ function snapshotFingerprint(captureLines, cursorLine, fallbackSize) {
 function tmuxSingleQuote(value) {
     return `'${value.replaceAll("'", "'\\''")}'`;
 }
+function layoutIdentitiesEqual(left, right) {
+    const paneIds = (layout) => layout?.leaves.map((leaf) => leaf.id);
+    return (left.zoomed === right.zoomed &&
+        JSON.stringify(paneIds(left)) === JSON.stringify(paneIds(right)) &&
+        JSON.stringify(paneIds(left.unzoomed)) === JSON.stringify(paneIds(right.unzoomed)));
+}
 export function defaultMirrorPaneId() {
     return `pane.mirror.${randomBytes(8).toString("hex")}`;
 }
@@ -133,6 +158,9 @@ export function defaultMirrorWindowId() {
     return `window.mirror.${randomBytes(8).toString("hex")}`;
 }
 export class SessionChannel {
+    nativeBootstrapUnavailable = false;
+    nativeBootstrapConfirmed = false;
+    nativeProbeRetried = new WeakSet();
     opts;
     io;
     ledger = new FlowLedger();
@@ -148,17 +176,24 @@ export class SessionChannel {
     truthActive = new Map();
     truthWindow = new Map();
     currentWindow = "";
+    windowLinkAuthority = null;
+    latestWindowStage = null;
+    attachedServerGeneration = null;
     diagnostics = [];
     degraded = false;
     ageByRuntime = new Map();
     maxAgeMs = 0;
     geometryParticipating = false;
+    fittedWindows = new Map();
     cancelSync = null;
+    syncOrdinal = 0;
     lastDisplayNameSyncAtMs = 0;
     disposed = false;
     nativeGrid;
     nativeClientProbePending = false;
+    // Native captures fence every geometry event; inventory fences identity only.
     windowAuthorityOrdinal = 0;
+    windowIdentityOrdinal = 0;
     paneIncarnation = 0;
     recoveryOrdinal = 0;
     plainReseedActive = null;
@@ -182,7 +217,11 @@ export class SessionChannel {
         const onReply = action.traceIds?.length
             ? (reply) => this.opts.onInputAccepted?.(action, Math.floor(performance.now() * 1_000), reply.ok)
             : undefined;
-        if (action.kind === "literal") {
+        if (this.trySendOwnedInput(action, onReply)) {
+            // The existing coalescer still owns ordering. Never replay an accepted
+            // native dispatch even when its attribution metadata is unavailable.
+        }
+        else if (action.kind === "literal") {
             this.io.send(`send-keys -t ${action.pane} -H ${textToHexKeys(action.text).join(" ")}`, onReply);
         }
         else if (action.kind === "bytes") {
@@ -194,6 +233,57 @@ export class SessionChannel {
         if (action.traceIds?.length)
             this.opts.onInputWrite?.(action, startedAtMicros, Math.floor(performance.now() * 1_000), pendingBeforeSend);
     }, (flush) => queueMicrotask(flush));
+    trySendOwnedInput(action, onReply) {
+        const adapter = this.opts.ownedViewer;
+        if (!adapter)
+            return false;
+        const birth = this.panesByRuntime.get(action.pane)?.descriptor?.nativePaneBirthId;
+        if (!birth)
+            return false;
+        // Legacy callers may supply a tmux key expression. Only a single named key
+        // can be moved into structured argv without changing its interpretation.
+        if (action.kind === "key" && !/^[A-Za-z0-9_-]+$/.test(action.key))
+            return false;
+        const keys = action.kind === "literal"
+            ? ["-H", ...textToHexKeys(action.text)]
+            : action.kind === "bytes"
+                ? ["-H", ...Array.from(action.data, (byte) => byte.toString(16).padStart(2, "0"))]
+                : [action.key];
+        return adapter.tryDispatch(this.io, {
+            paneId: action.pane,
+            paneBirthId: birth,
+            commands: [["send-keys", "-t", action.pane, ...keys]],
+            resultIndex: 0,
+            limits: { maxBytes: 65536, maxLines: 1024 },
+        }, onReply ?? (() => { }));
+    }
+    captureWithViewer(runtime, flags, onStockMarker, onReply, limits) {
+        const command = ["capture-pane", "-p", ...flags, "-t", runtime];
+        const birth = this.panesByRuntime.get(runtime)?.descriptor?.nativePaneBirthId;
+        if (birth &&
+            this.opts.ownedViewer?.tryDispatch(this.io, {
+                paneId: runtime,
+                paneBirthId: birth,
+                commands: [command],
+                resultIndex: 0,
+                limits: limits ?? {
+                    maxBytes: RECOVERY_CAPTURE_MAX_BYTES,
+                    maxLines: RECOVERY_CAPTURE_MAX_LINES,
+                },
+            }, onReply))
+            return;
+        // Install compatibility metadata only after native dispatch declined without
+        // writing. Publish it to the caller before a synchronous error callback.
+        const marker = registerInternalReadOperation(runtime);
+        onStockMarker(marker);
+        const stock = `set-option -p -t ${runtime} ${INTERNAL_READ_OPERATION_OPTION} ${marker} ; ${command.join(" ")}`;
+        if (limits && this.io.commandListBoundedInline) {
+            this.io.commandListBoundedInline(stock, 2, 1, limits, onReply);
+        }
+        else {
+            this.io.commandListInline(stock, 2, 1, onReply);
+        }
+    }
     constructor(opts) {
         this.opts = opts;
         this.io = opts.createIo({
@@ -201,6 +291,7 @@ export class SessionChannel {
             onNotify: (name, rest) => this.onNotify(name, rest),
             onExit: () => this.onChannelExit(),
         });
+        opts.ownedViewer?.bindIo(this.io);
         this.nativeGrid = new NativeGridCaptureReader({
             commandBoundedInline: this.io.commandListBoundedInline
                 ? (command, limits, onReply) => {
@@ -209,12 +300,14 @@ export class SessionChannel {
                         onReply({ ok: false, lines: [] });
                         return;
                     }
-                    const marker = registerInternalReadOperation(runtime);
-                    this.io.commandListBoundedInline(`set-option -p -t ${runtime} ${INTERNAL_READ_OPERATION_OPTION} ${marker} ; ${command}`, 2, 1, limits, (reply) => {
-                        if (!reply.ok)
+                    let marker = null;
+                    this.captureWithViewer(runtime, ["-R", "-S", "-"], (value) => {
+                        marker = value;
+                    }, (reply) => {
+                        if (!reply.ok && marker)
                             this.retireInternalReadMarker(runtime, marker);
                         onReply(reply);
-                    });
+                    }, limits);
                 }
                 : undefined,
         });
@@ -246,6 +339,7 @@ export class SessionChannel {
         this.io.send("refresh-client -B 'tmux-ide-pane-borders:@*:#{pane-border-status}'");
         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) {
             // tmux does not guarantee `%client-attached` is broadcast to an
             // existing control client. A format subscription is the documented,
@@ -306,7 +400,13 @@ export class SessionChannel {
                 ? this.trustedInventoryFlight
                 : Promise.reject(new Error(`trusted inventory identity changed for ${this.opts.session}`));
         }
-        const flight = this.refreshTrustedInventory(expectedRuntimeSessionId).finally(() => {
+        const flight = this.refreshTrustedInventory(expectedRuntimeSessionId)
+            .catch((error) => {
+            this.windowLinkAuthority?.invalidate();
+            this.latestWindowStage = null;
+            throw error;
+        })
+            .finally(() => {
             if (this.trustedInventoryFlight === flight) {
                 this.trustedInventoryFlight = null;
                 this.trustedInventoryFlightSessionId = null;
@@ -325,21 +425,150 @@ export class SessionChannel {
         return this.attachedIdentity;
     }
     async captureAttachedSessionIdentity() {
-        const lines = await this.io.request(`display-message -p "#{qa:session_name}\t#{session_id}"`);
+        const lines = await this.io.request(`display-message -p "#{qa:session_name}\t#{session_id}\t#{pid}\t#{session_created}"`);
         if (lines.length !== 1)
             throw new Error(`mirror session ${this.opts.session} identity is absent`);
         const decodedLine = decodeControlReplyUtf8(lines[0]);
         if (decodedLine === null)
             throw new Error(`mirror session ${this.opts.session} identity is malformed`);
-        const [encodedName = "", runtimeSessionId = ""] = decodedLine.split("\t");
+        const [encodedName = "", runtimeSessionId = "", serverPid = "", sessionCreated = ""] = decodedLine.split("\t");
         const sessionName = decodeTmuxArgument(encodedName);
         if (sessionName.length === 0 ||
             sessionName.length > 160 ||
             !/^\$(?:0|[1-9][0-9]*)$/u.test(runtimeSessionId) ||
-            runtimeSessionId.length > 32) {
+            runtimeSessionId.length > 32 ||
+            !/^[1-9][0-9]*$/u.test(serverPid) ||
+            !/^[0-9]+$/u.test(sessionCreated)) {
             throw new Error(`mirror session ${this.opts.session} identity is malformed`);
         }
         this.attachedIdentity = Object.freeze({ sessionName, runtimeSessionId });
+        this.attachedServerGeneration = { serverPid, sessionCreated };
+        if (this.disposed)
+            return;
+        this.bindWindowLinkAuthority(liveSessionIdForNativeIdentity(serverPid, runtimeSessionId, sessionCreated));
+    }
+    bindWindowLinkAuthority(liveSessionId) {
+        const identity = this.attachedIdentity;
+        if (!identity || this.disposed)
+            throw new WindowLinkResolutionError("window_link_stale");
+        if (this.windowLinkAuthority?.liveSessionId === liveSessionId)
+            return;
+        this.windowLinkAuthority?.dispose();
+        this.windowLinkAuthority = new WindowLinkAuthority(liveSessionId, identity.runtimeSessionId);
+        if (this.latestWindowStage)
+            this.windowLinkAuthority.reconcile(this.latestWindowStage.links);
+    }
+    /** Capture this attached connection once; never resolve a replacement mid-operation. */
+    paneResizeTransport() {
+        const identity = this.attachedIdentity;
+        const generation = this.attachedServerGeneration;
+        const assertCurrent = () => {
+            if (this.disposed ||
+                !identity ||
+                !generation ||
+                this.attachedIdentity !== identity ||
+                this.attachedServerGeneration !== generation)
+                throw new Error("Resize control connection retired");
+        };
+        assertCurrent();
+        return async (args) => {
+            assertCurrent();
+            const listing = args.length === 6 &&
+                args[0] === "list-panes" &&
+                args[1] === "-s" &&
+                args[2] === "-t" &&
+                args[3] === `=${identity.sessionName}` &&
+                args[4] === "-F";
+            const resize = args.length === 11 &&
+                args[0] === "resize-pane" &&
+                args[1] === "-t" &&
+                /^%[0-9]+$/u.test(args[2]) &&
+                (args[3] === "-x" || args[3] === "-y") &&
+                /^[1-9][0-9]*$/u.test(args[4]) &&
+                args[5] === ";" &&
+                args[6] === "display-message" &&
+                args[7] === "-p" &&
+                args[8] === "-t" &&
+                args[9] === args[2] &&
+                args[10] === (args[3] === "-x" ? "#{pane_width}" : "#{pane_height}");
+            if (!listing && !resize)
+                throw new Error("Invalid resize control command");
+            // A runtime session ID prevents a rename/replacement from redirecting the lookup.
+            const pinned = listing
+                ? [...args.slice(0, 3), identity.runtimeSessionId, ...args.slice(4)]
+                : args;
+            const command = pinned
+                .map((arg, index) => (resize && index === 5 ? ";" : tmuxSingleQuote(arg)))
+                .join(" ");
+            const lines = listing
+                ? await this.io.request(command)
+                : await new Promise((resolve, reject) => {
+                    this.io.commandListInline(command, 2, 1, (reply) => reply.ok ? resolve(reply.lines) : reject(new Error("Resize control command failed")));
+                });
+            assertCurrent();
+            return lines
+                .map((line) => {
+                const decoded = decodeControlReplyUtf8(line);
+                if (decoded === null)
+                    throw new Error("Invalid resize control reply");
+                return decoded;
+            })
+                .join("\n");
+        };
+    }
+    async executeWindowLinkAction(request) {
+        const authority = this.windowLinkAuthority;
+        if (!authority || this.disposed)
+            throw new WindowLinkResolutionError("window_link_stale");
+        const pane = request.paneId ? this.panesBySemantic.get(request.paneId) : undefined;
+        if (request.paneId && !pane)
+            throw new WindowLinkResolutionError("window_link_backing_mismatch");
+        const semanticWindow = pane?.windowRuntimeId
+            ? this.windowsByRuntime.get(pane.windowRuntimeId)?.semanticId
+            : null;
+        const target = request.target ?? (semanticWindow ? authority.uniqueTargetForBacking(semanticWindow) : null);
+        if (!target)
+            throw new WindowLinkResolutionError("window_link_stale");
+        const resolved = authority.resolve(target);
+        if (pane && (pane.windowRuntimeId !== resolved.runtimeWindowId || request.action !== "select"))
+            throw new WindowLinkResolutionError("window_link_backing_mismatch");
+        const address = {
+            sessionId: resolved.runtimeSessionId,
+            windowIndex: resolved.index,
+            expectedWindowId: resolved.runtimeWindowId,
+            expectedServerPid: this.attachedServerGeneration.serverPid,
+            expectedSessionCreated: this.attachedServerGeneration.sessionCreated,
+        };
+        const args = pane
+            ? buildNativeWindowLinkPaneSelectGuard(address, pane.runtimeId)
+            : buildNativeWindowLinkGuard(address, request.action);
+        let outcome;
+        try {
+            if (!this.opts.executeWindowLinkGuard)
+                throw new Error("Window link executor unavailable");
+            const result = await this.opts.executeWindowLinkGuard(args);
+            outcome = classifyNativeWindowLinkGuardResult(result.status, result.stdout);
+        }
+        catch {
+            // A lost command boundary can follow a mutation; never retry automatically.
+            outcome = "indeterminate";
+        }
+        let timer;
+        const reconciled = await Promise.race([
+            this.syncNow().then(() => true, () => false),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), 2000);
+            }),
+        ]).finally(() => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        });
+        if (!reconciled) {
+            authority.invalidate();
+            this.latestWindowStage = null;
+            return { outcome, windowLinks: null };
+        }
+        return { outcome, windowLinks: authority.snapshot() };
     }
     /** Optional native backing, addressed through the verified semantic binding. */
     captureNativeBacking(semanticPaneId, ownsSubscription = () => true) {
@@ -363,13 +592,14 @@ export class SessionChannel {
             this.layoutTopologyEpoch === topologyEpoch &&
             this.windowAuthorityOrdinal === authorityOrdinal);
     }
-    subscribePane(semanticPaneId, onEvent, onLayout) {
+    subscribePane(semanticPaneId, onEvent, onLayout, nativeBootstrap = false) {
         const pane = this.panesBySemantic.get(semanticPaneId);
         if (!pane) {
             throw new Error(`unknown semantic pane ${semanticPaneId} in session ${this.opts.session}`);
         }
         const sub = {
             feed: new PaneFeed(),
+            nativeBootstrap: nativeBootstrap && !this.nativeBootstrapUnavailable,
             onEvent,
             onLayout: onLayout ?? null,
             pane,
@@ -474,7 +704,7 @@ export class SessionChannel {
                 throw error;
             }
         }
-        if (expectedByWindow.size !== inventory.panes[0].sessionWindowCount ||
+        if (this.latestWindowStage?.links.length !== inventory.panes[0].sessionWindowCount ||
             expectedByWindow.size !== this.windowsByRuntime.size) {
             throw new Error(`authoritative layout for ${this.opts.session} has incomplete windows`);
         }
@@ -533,10 +763,50 @@ export class SessionChannel {
             throw new RangeError("viewport must contain positive bounded terminal cells");
         }
         this.input.flush();
+        this.clearWindowViewports();
         this.io.send(`refresh-client -C ${cols}x${rows}`);
     }
+    /**
+     * Experimental: window-specific overrides stay private to this control client.
+     * Native tmux still falls back to the client size for unscoped neighbours;
+     * do not advertise isolated fitting until that behavior is accounted for.
+     */
+    fitWindowViewport(semanticWindowId, cols, rows) {
+        if (!Number.isSafeInteger(cols) ||
+            !Number.isSafeInteger(rows) ||
+            cols < 2 ||
+            rows < 2 ||
+            cols > 4096 ||
+            rows > 4096) {
+            throw new RangeError("viewport must contain positive bounded terminal cells");
+        }
+        const window = [...this.windowsByRuntime.values()].find((entry) => entry.semanticId === semanticWindowId);
+        if (!window || !/^@[0-9]+$/u.test(window.runtimeId)) {
+            throw new Error("unknown semantic window in this session");
+        }
+        const previous = this.fittedWindows.get(window.runtimeId);
+        if (previous?.cols === cols && previous.rows === rows)
+            return;
+        this.input.flush();
+        this.io.send(`refresh-client -C ${window.runtimeId}:${cols}x${rows}`);
+        this.fittedWindows.set(window.runtimeId, { cols, rows });
+    }
+    /** Must also run on geometry-owner handoff, before the next owner fits. */
+    clearWindowViewports() {
+        if (!this.fittedWindows.size)
+            return;
+        this.input.flush();
+        for (const runtimeId of this.fittedWindows.keys()) {
+            // A removed window no longer has a live override to clear.
+            if (this.windowsByRuntime.has(runtimeId))
+                this.io.send(`refresh-client -C ${runtimeId}:`);
+        }
+        this.fittedWindows.clear();
+    }
     /** Toggle whether the retained control client participates in tmux sizing. */
     setGeometryParticipation(active) {
+        if (!active)
+            this.clearWindowViewports();
         if (this.geometryParticipating === active)
             return;
         this.geometryParticipating = active;
@@ -571,6 +841,7 @@ export class SessionChannel {
         if (this.disposed)
             return;
         this.disposed = true;
+        this.windowLinkAuthority?.dispose();
         this.nativeGrid.dispose();
         this.settleFirstJoin();
         this.cancelSync?.();
@@ -580,6 +851,7 @@ export class SessionChannel {
         this.continueNotificationQueues.clear();
         this.discovery.dispose();
         this.input.flush();
+        this.opts.ownedViewer?.dispose();
         for (const pane of this.panesByRuntime.values()) {
             for (const sub of pane.subs) {
                 if (!sub.closed) {
@@ -641,43 +913,54 @@ export class SessionChannel {
         this.noteRecoveryOutput(pane, outputOrdinal);
     }
     // ── Seed / reseed (the atomic recipe) ────────────────────────────────────
-    reseed(sub, onSettled, deferPublish = false) {
+    reseed(lease, onSettled, deferPublish = false, deadlineAt = this.recoveryNowMs() + RECOVERY_ABSOLUTE_DEADLINE_MS) {
+        const { sub } = lease;
         if (sub.closed || sub.frozen || this.disposed) {
             onSettled?.(FAILED_RESEED_RESULT);
             return;
         }
-        sub.cancelCapture?.();
+        lease.cancelRecipe?.();
         const runtime = sub.pane.runtimeId;
         const epoch = sub.feed.beginReseed();
         let settled = false;
         let captureSucceeded = false;
         let markerRetired = false;
         let captureLines = null;
+        let capturedNativeSize = null;
         let cancelDeadline = null;
+        let resumeLayoutCapture = null;
+        const clearLayoutWait = () => {
+            if (sub.resumeLayoutCapture === resumeLayoutCapture)
+                sub.resumeLayoutCapture = null;
+            resumeLayoutCapture = null;
+        };
         const settle = (result) => {
             if (settled)
                 return;
             settled = true;
+            clearLayoutWait();
             cancelDeadline?.();
-            sub.cancelCapture = null;
+            lease.cancelRecipe = null;
             onSettled?.(result);
         };
         // Keystroke ordering: pending coalesced input leaves before the probes.
         this.input.flush();
         const history = this.opts.historyLines ?? "";
-        const internalReadMarker = registerInternalReadOperation(runtime);
+        let internalReadMarker = null;
         const retireMarker = () => {
             if (markerRetired)
                 return;
             markerRetired = true;
-            this.retireInternalReadMarker(runtime, internalReadMarker);
+            if (internalReadMarker)
+                this.retireInternalReadMarker(runtime, internalReadMarker);
         };
-        sub.cancelCapture = () => {
+        lease.cancelRecipe = () => {
             if (settled)
                 return;
             settled = true;
+            clearLayoutWait();
             cancelDeadline?.();
-            sub.cancelCapture = null;
+            lease.cancelRecipe = null;
             sub.feed.abort(epoch);
             if (!captureSucceeded)
                 retireMarker();
@@ -689,13 +972,52 @@ export class SessionChannel {
             if (!captureSucceeded)
                 retireMarker();
             settle(FAILED_RESEED_RESULT);
-        }, RECOVERY_ABSOLUTE_DEADLINE_MS);
+        }, Math.max(0, deadlineAt - this.recoveryNowMs()));
         // Keep retired reply slots in the control FIFO; their callbacks become
         // no-ops so late responses cannot publish or consume a newer capture.
         // Both probes ride one write burst; the FIFO reply order is the seam.
-        this.io.commandListInline(`set-option -p -t ${runtime} ${INTERNAL_READ_OPERATION_OPTION} ${internalReadMarker} ; capture-pane -p -e -J -S -${history} -t ${runtime}`, 2, 1, (reply) => {
+        this.captureWithViewer(runtime, [...(sub.nativeBootstrap ? ["-R"] : ["-e", "-J"]), "-S", `-${history}`], (marker) => {
+            internalReadMarker = marker;
+        }, (reply) => {
             if (settled)
                 return;
+            const native = sub.nativeBootstrap && reply.ok ? decodeNativeGridCapture(reply.lines.join("\n")) : null;
+            if (sub.nativeBootstrap &&
+                (!native || !isNativeBootstrapCapture(native)) &&
+                !nativeBootstrapUnsupported(reply.ok, reply.lines, native)) {
+                if (!this.nativeBootstrapConfirmed &&
+                    !this.nativeProbeRetried.has(sub) &&
+                    this.recoveryNowMs() < deadlineAt) {
+                    // An unknown server can swallow an unsupported command inside a
+                    // dynamic hook. Retry the ordinary probe once, with a fresh FIFO
+                    // seam and the original deadline, before invoking native recovery.
+                    this.nativeProbeRetried.add(sub);
+                    settled = true;
+                    sub.feed.abort(epoch);
+                    cancelDeadline?.();
+                    lease.cancelRecipe = null;
+                    retireMarker();
+                    this.reseed(lease, onSettled, deferPublish, deadlineAt);
+                    return;
+                }
+                sub.feed.abort(epoch);
+                retireMarker();
+                settle(FAILED_RESEED_RESULT);
+                return;
+            }
+            if (sub.nativeBootstrap && (!native || !isNativeBootstrapCapture(native))) {
+                // Unsupported/backing-only native exports fall back at a new FIFO
+                // capture seam. Never replay held bytes across these two captures.
+                settled = true;
+                retireMarker();
+                sub.feed.abort(epoch);
+                cancelDeadline?.();
+                lease.cancelRecipe = null;
+                sub.nativeBootstrap = false;
+                this.nativeBootstrapUnavailable = true;
+                this.reseed(lease, onSettled, deferPublish, deadlineAt);
+                return;
+            }
             if (!reply.ok) {
                 // Successful captures consume the marker atomically inside the tmux
                 // after-capture-pane hook. The command-list also prevents a concurrent
@@ -712,7 +1034,14 @@ export class SessionChannel {
                 return;
             }
             captureLines = [...reply.lines];
-            sub.feed.captureReply(epoch, reply.lines);
+            if (native) {
+                this.nativeBootstrapConfirmed = true;
+                capturedNativeSize = { cols: native.cols, rows: native.rows };
+            }
+            if (native)
+                sub.feed.captureNativeReply(epoch, native);
+            else
+                sub.feed.captureReply(epoch, reply.lines);
         });
         this.io.commandInline(`display-message -p -t ${runtime} "${RECOVERY_CURSOR_PROBE_FORMAT}"`, (reply) => {
             if (settled)
@@ -729,11 +1058,63 @@ export class SessionChannel {
                 settle(FAILED_RESEED_RESULT);
                 return;
             }
+            // Native/cursor replies can precede the paired layout/border reply.
+            // Never publish that candidate against old authority, nor replay held
+            // output over its snapshot. Recapture after the latest layout releases,
+            // retaining this recipe's original deadline and one queue lease.
+            const windowId = sub.pane.windowRuntimeId;
+            const probe = parseCursorProbe(reply.lines[0] ?? "");
+            const validCaptureGeometry = probe &&
+                Number.isSafeInteger(probe.x) &&
+                Number.isSafeInteger(probe.y) &&
+                probe.y < probe.rows &&
+                (!capturedNativeSize ||
+                    (capturedNativeSize.cols === probe.cols && capturedNativeSize.rows === probe.rows));
+            const layoutSize = validCaptureGeometry ? this.layoutCaptureSizeFor(sub) : null;
+            const pendingLayout = windowId !== null && this.pendingLayoutOutput.has(windowId);
+            const aheadOfLayout = layoutSize && probe && (layoutSize.cols !== probe.cols || layoutSize.rows !== probe.rows);
+            if (windowId && layoutSize && validCaptureGeometry && (pendingLayout || aheadOfLayout)) {
+                sub.feed.abort(epoch);
+                captureLines = null;
+                const waitingAfterSyncOrdinal = this.syncOrdinal;
+                resumeLayoutCapture = (completedSyncOrdinal) => {
+                    if (settled)
+                        return;
+                    if (this.recoveryNowMs() >= deadlineAt) {
+                        settle(FAILED_RESEED_RESULT);
+                        return;
+                    }
+                    const current = this.layoutCaptureSizeFor(sub);
+                    // Only a successful truth sync started after this wait is a causal
+                    // barrier, including resize-back to identical geometry. An older
+                    // in-flight sync and cached layout emissions cannot qualify it.
+                    if (!current)
+                        return;
+                    if (completedSyncOrdinal !== undefined) {
+                        if (completedSyncOrdinal <= waitingAfterSyncOrdinal)
+                            return;
+                    }
+                    else if (!pendingLayout &&
+                        current.cols === layoutSize.cols &&
+                        current.rows === layoutSize.rows)
+                        return;
+                    settled = true;
+                    clearLayoutWait();
+                    cancelDeadline?.();
+                    lease.cancelRecipe = null;
+                    this.reseed(lease, onSettled, deferPublish, deadlineAt);
+                };
+                sub.resumeLayoutCapture = resumeLayoutCapture;
+                if (!pendingLayout)
+                    this.scheduleSync();
+                return;
+            }
             const cursorLine = reply.lines[0] ?? "";
             const historySize = Number(cursorLine.trim().split(/\s+/)[14]);
             if (Number.isSafeInteger(historySize) && historySize >= 0)
                 sub.pane.historySize = historySize;
             const fallbackSize = this.layoutSizeFor(runtime);
+            this.observeScrollOnClear(sub.pane, cursorLine);
             const events = sub.feed.cursorReply(epoch, cursorLine, fallbackSize);
             let published = false;
             const publish = () => {
@@ -761,14 +1142,18 @@ export class SessionChannel {
     reseedPlain(sub, resumeReason = null) {
         if (sub.closed || sub.frozen || this.disposed)
             return;
-        if (this.plainReseedActive === sub)
+        // Layout observers can request a reseed reentrantly during admission. The
+        // waiting recipe already owns that request and its absolute deadline.
+        if (sub.resumeLayoutCapture)
+            return;
+        if (this.plainReseedActive?.sub === sub)
             sub.cancelCapture?.();
         if (!this.plainReseedQueue.has(sub) && this.plainReseedQueue.size >= MAX_QUEUED_PLAIN_RESEEDS) {
             this.failPlainReseed(sub);
             return;
         }
         this.plainReseedQueue.set(sub, resumeReason);
-        if (this.plainReseedActive !== sub) {
+        if (this.plainReseedActive?.sub !== sub) {
             // Output before this queued recipe starts is already in its future
             // capture. Do not publish it using the prior geometry in the meantime.
             sub.feed.beginReseed();
@@ -801,13 +1186,26 @@ export class SessionChannel {
             this.drainPlainReseeds();
             return;
         }
-        this.plainReseedActive = sub;
+        sub.cancelCapture?.();
+        const lease = { sub, cancelRecipe: null };
+        this.plainReseedActive = lease;
+        // The queue lease outlives individual native capability probes. Retrying
+        // or falling back replaces only cancelRecipe, never this queue owner.
+        sub.cancelCapture = () => {
+            if (this.plainReseedActive !== lease)
+                return;
+            lease.cancelRecipe?.();
+            sub.cancelCapture = null;
+            this.plainReseedActive = null;
+            this.drainPlainReseeds();
+        };
         // Only the recipe actually submitted to the control FIFO owns a five
         // second deadline. A large sibling projection cannot consume the waiting
         // panes' entire capture budgets before their commands have been written.
-        this.reseed(sub, (result) => {
-            if (this.plainReseedActive !== sub)
+        this.reseed(lease, (result) => {
+            if (this.plainReseedActive !== lease)
                 return;
+            sub.cancelCapture = null;
             this.plainReseedActive = null;
             if (!result.ok) {
                 // A stalled FIFO cannot make progress for queued recipes either. Retire
@@ -827,16 +1225,6 @@ export class SessionChannel {
             if (resumeReason && !sub.closed && !sub.frozen)
                 sub.onEvent({ type: "flow", state: "resumed", reason: resumeReason });
         }, true);
-        if (this.plainReseedActive === sub) {
-            const cancel = sub.cancelCapture;
-            sub.cancelCapture = () => {
-                cancel?.();
-                this.plainReseedQueue.delete(sub);
-                if (this.plainReseedActive === sub)
-                    this.plainReseedActive = null;
-                this.drainPlainReseeds();
-            };
-        }
     }
     retireInternalReadMarker(runtime, marker) {
         if (!/^%(?:0|[1-9][0-9]*)$/u.test(runtime))
@@ -844,8 +1232,37 @@ export class SessionChannel {
         retireInternalReadOperation(marker, runtime);
         // Pane capture phases overlap under cancellation. Clear only the exact
         // failed marker so a late A callback cannot erase the newer B authority.
-        this.io.send(`if-shell -t ${runtime} -F "#{==:#{${INTERNAL_READ_OPERATION_OPTION}},${marker}}" ` +
-            `"set-option -pu -t ${runtime} ${INTERNAL_READ_OPERATION_OPTION}" ""`);
+        // Both selected branches must emit one reply in addition to if-shell's
+        // own reply. An empty false branch emits none and shifts the control FIFO
+        // whenever the true branch runs during capture cancellation.
+        this.io.commandListInline(`if-shell -t ${runtime} -F "#{==:#{${INTERNAL_READ_OPERATION_OPTION}},${marker}}" ` +
+            `"set-option -pu -t ${runtime} ${INTERNAL_READ_OPERATION_OPTION}" ` +
+            `"display-message -p -t ${runtime} ''"`, 2, 1, () => { });
+    }
+    layoutCaptureSizeFor(sub) {
+        const windowId = sub.pane.windowRuntimeId;
+        const event = windowId ? this.layoutEventFor(windowId, sub.pane.runtimeId) : null;
+        if (!event || event.semanticWindowId === null)
+            return null;
+        const identities = event.panes.map((pane) => pane.semanticPaneId);
+        if (identities.some((id) => id === null) || new Set(identities).size !== identities.length)
+            return null;
+        const matches = event.panes.filter((pane) => pane.semanticPaneId === sub.pane.semanticId);
+        if (matches.length !== 1)
+            return null;
+        const pane = matches[0];
+        if (![event.cols, event.rows, pane.width, pane.height].every((value) => Number.isSafeInteger(value) && value > 0) ||
+            !Number.isSafeInteger(pane.left) ||
+            !Number.isSafeInteger(pane.top) ||
+            pane.left < 0 ||
+            pane.top < 0 ||
+            pane.left + pane.width > event.cols ||
+            pane.top + pane.height > event.rows)
+            return null;
+        return {
+            cols: pane.width,
+            rows: layoutContentRows(pane.top, pane.height, event.rows, event.paneBorderStatus),
+        };
     }
     layoutSizeFor(runtime) {
         for (const layout of this.layoutByWindow.values()) {
@@ -991,6 +1408,12 @@ export class SessionChannel {
                 sub.feed.abortCurrent();
         }
         this.observeRecovery(pane, recovery, "pause");
+        const nativeTarget = this.nativeRecoveryTarget(pane);
+        if (nativeTarget) {
+            this.beginRecoveryConvergence(recovery);
+            this.recoverNativeAtomic(pane, recovery, nativeTarget);
+            return;
+        }
         this.observeRecovery(pane, recovery, "continue-request");
         recovery.cancelCommandDeadline = this.scheduleRecovery(() => {
             if (this.recoveryPane(recovery) && !recovery.continueReply)
@@ -1066,7 +1489,161 @@ export class SessionChannel {
         }
         this.observeRecovery(pane, recovery, "pause");
         this.beginRecoveryConvergence(recovery);
-        this.beginFinalRecovery(recovery);
+        const nativeTarget = this.nativeRecoveryTarget(pane);
+        if (nativeTarget)
+            this.recoverNativeAtomic(pane, recovery, nativeTarget);
+        else
+            this.beginFinalRecovery(recovery);
+    }
+    nativeRecoveryTarget(pane) {
+        // Mixed/plain recovery requires an explicitly negotiated dual snapshot.
+        const live = [...pane.subs].filter((sub) => !sub.closed && !sub.frozen);
+        const representation = live.every((sub) => sub.nativeBootstrap) ? "native" : "dual";
+        const birth = pane.descriptor?.nativePaneBirthId;
+        let epoch;
+        try {
+            epoch = this.opts.ownedViewer?.atomicSnapshotEpoch?.(this.io, representation);
+        }
+        catch {
+            // Optional capability failure cannot strand ordinary recovery.
+            return null;
+        }
+        return live.length > 0 && birth && epoch
+            ? { serverEpoch: epoch, paneId: pane.runtimeId, paneBirthId: birth, representation }
+            : null;
+    }
+    recoverNativeAtomic(pane, recovery, target) {
+        if (this.recoveryPane(recovery) !== pane)
+            return;
+        const currentTarget = this.nativeRecoveryTarget(pane);
+        if (currentTarget?.serverEpoch !== target.serverEpoch ||
+            currentTarget.paneBirthId !== target.paneBirthId ||
+            currentTarget.representation !== target.representation) {
+            this.failRecovery(recovery, "command-error");
+            return;
+        }
+        if (recovery.attempts >= RECOVERY_MAX_ATTEMPTS) {
+            this.failRecovery(recovery, "attempts-exhausted");
+            return;
+        }
+        recovery.attempts += 1;
+        const ordinal = ++recovery.reseedOrdinal;
+        const participants = [...pane.subs]
+            .filter((sub) => !sub.closed && !sub.frozen)
+            .map((sub) => ({ sub, epoch: sub.feed.beginReseed() }));
+        const exact = () => {
+            const current = this.nativeRecoveryTarget(pane);
+            const live = [...pane.subs].filter((sub) => !sub.closed && !sub.frozen);
+            return (this.recoveryPane(recovery) === pane &&
+                recovery.reseedOrdinal === ordinal &&
+                current?.serverEpoch === target.serverEpoch &&
+                current.paneBirthId === target.paneBirthId &&
+                current.representation === target.representation &&
+                live.length === participants.length &&
+                participants.every(({ sub }) => live.includes(sub)));
+        };
+        let settled = false;
+        const failed = () => {
+            if (settled || this.recoveryPane(recovery) !== pane || recovery.reseedOrdinal !== ordinal)
+                return;
+            settled = true;
+            recovery.cancelCommandDeadline?.();
+            recovery.cancelCommandDeadline = null;
+            for (const { sub } of participants)
+                sub.feed.abortCurrent();
+            // A malformed/late reply may follow a committed resume. Every retry
+            // explicitly pauses first; never fall through to stock capture.
+            this.armRecoveryQuiet(recovery, () => this.recoverNativeAtomic(pane, recovery, target));
+        };
+        recovery.stage = "native-pause";
+        recovery.cancelCommandDeadline = this.scheduleRecovery(failed, RECOVERY_COMMAND_DEADLINE_MS);
+        this.input.flush();
+        this.io.commandInline(`refresh-client -A '${pane.runtimeId}:pause'`, (pauseReply) => {
+            if (settled || !exact()) {
+                failed();
+                return;
+            }
+            if (!pauseReply.ok) {
+                failed();
+                return;
+            }
+            recovery.stage = "native-capture";
+            recovery.cancelCommandDeadline?.();
+            recovery.cancelCommandDeadline = this.scheduleRecovery(failed, RECOVERY_COMMAND_DEADLINE_MS);
+            const accepted = this.opts.ownedViewer.tryDispatch(this.io, target.representation === "dual"
+                ? nativeAtomicDualSnapshotPlan({
+                    serverEpoch: target.serverEpoch,
+                    paneId: target.paneId,
+                    paneBirthId: target.paneBirthId,
+                })
+                : nativeAtomicSnapshotPlan({
+                    serverEpoch: target.serverEpoch,
+                    paneId: target.paneId,
+                    paneBirthId: target.paneBirthId,
+                }), (reply) => {
+                if (settled || !exact()) {
+                    failed();
+                    return;
+                }
+                const expected = {
+                    serverEpoch: target.serverEpoch,
+                    paneId: target.paneId,
+                    paneBirthId: target.paneBirthId,
+                };
+                const result = target.representation === "dual"
+                    ? decodeNativeAtomicDualSnapshot(reply, expected)
+                    : decodeNativeAtomicSnapshot(reply, expected);
+                if (result.status !== "ok") {
+                    failed();
+                    return;
+                }
+                this.nativeBootstrapConfirmed = true;
+                this.observeScrollOnClear(pane, result.cursorLine);
+                // The selected child reply owns its inline %continue. It adds no
+                // asynchronous notification debt to the legacy continue queue.
+                recovery.continueReply = true;
+                recovery.continueNotify = true;
+                const ansiLines = result.ansiCapture
+                    ? captureLinesFromAnsiBytes(result.ansiCapture)
+                    : null;
+                const deliveries = participants.map(({ sub, epoch }) => {
+                    if (sub.nativeBootstrap)
+                        sub.feed.captureNativeReply(epoch, result.capture);
+                    else if (ansiLines)
+                        sub.feed.captureReply(epoch, ansiLines);
+                    return {
+                        sub,
+                        events: sub.feed.cursorReply(epoch, result.cursorLine, this.layoutSizeFor(pane.runtimeId)),
+                    };
+                });
+                if (!exact() || deliveries.some(({ events }) => events.length === 0)) {
+                    failed();
+                    return;
+                }
+                for (const { sub, events } of deliveries)
+                    for (const event of events) {
+                        if (!exact()) {
+                            failed();
+                            return;
+                        }
+                        try {
+                            sub.onEvent(event);
+                        }
+                        catch {
+                            failed();
+                            return;
+                        }
+                    }
+                if (!exact()) {
+                    failed();
+                    return;
+                }
+                settled = true;
+                this.convergeRecovery(pane, recovery);
+            });
+            if (!accepted)
+                failed();
+        });
     }
     beginRecoveryConvergence(recovery) {
         if (recovery.cancelAbsoluteDeadline)
@@ -1111,6 +1688,7 @@ export class SessionChannel {
             return;
         }
         const participants = live.map((sub) => Object.freeze({ sub, epoch: sub.feed.beginReseed() }));
+        const nativeCapture = !this.nativeBootstrapUnavailable && participants.every(({ sub }) => sub.nativeBootstrap);
         const reseedOrdinal = ++recovery.reseedOrdinal;
         let settled = false;
         let captureSucceeded = false;
@@ -1121,7 +1699,7 @@ export class SessionChannel {
         // across both FIFO replies so no subscriber can join half a snapshot.
         this.input.flush();
         const history = this.opts.historyLines ?? "";
-        const internalReadMarker = registerInternalReadOperation(pane.runtimeId);
+        let internalReadMarker = null;
         const participantsExact = () => {
             if (this.recoveryPane(recovery) !== pane ||
                 recovery.reseedOrdinal !== reseedOrdinal ||
@@ -1135,7 +1713,8 @@ export class SessionChannel {
             if (markerRetired)
                 return;
             markerRetired = true;
-            this.retireInternalReadMarker(pane.runtimeId, internalReadMarker);
+            if (internalReadMarker)
+                this.retireInternalReadMarker(pane.runtimeId, internalReadMarker);
         };
         const fail = () => {
             if (settled)
@@ -1147,8 +1726,15 @@ export class SessionChannel {
                 sub.feed.abortCurrent();
             done(FAILED_RESEED_RESULT);
         };
-        this.io.commandListInline(`set-option -p -t ${pane.runtimeId} ${INTERNAL_READ_OPERATION_OPTION} ${internalReadMarker} ; capture-pane -p -e -J -S -${history} -t ${pane.runtimeId}`, 2, 1, (reply) => {
+        this.captureWithViewer(pane.runtimeId, [...(nativeCapture ? ["-R"] : ["-e", "-J"]), "-S", `-${history}`], (marker) => {
+            internalReadMarker = marker;
+        }, (reply) => {
             if (!reply.ok) {
+                if (nativeCapture && nativeBootstrapUnsupported(false, reply.lines, null)) {
+                    this.nativeBootstrapUnavailable = true;
+                    for (const { sub } of participants)
+                        sub.nativeBootstrap = false;
+                }
                 fail();
                 return;
             }
@@ -1158,8 +1744,24 @@ export class SessionChannel {
                 return;
             }
             captureLines = Object.freeze([...reply.lines]);
-            for (const { sub, epoch } of participants)
-                sub.feed.captureReply(epoch, captureLines);
+            const native = nativeCapture ? decodeNativeGridCapture(captureLines.join("\n")) : null;
+            if (nativeCapture && (!native || !isNativeBootstrapCapture(native))) {
+                if (nativeBootstrapUnsupported(true, captureLines, native)) {
+                    this.nativeBootstrapUnavailable = true;
+                    for (const { sub } of participants)
+                        sub.nativeBootstrap = false;
+                }
+                fail();
+                return;
+            }
+            if (native)
+                this.nativeBootstrapConfirmed = true;
+            for (const { sub, epoch } of participants) {
+                if (native)
+                    sub.feed.captureNativeReply(epoch, native);
+                else
+                    sub.feed.captureReply(epoch, captureLines);
+            }
         });
         this.io.commandInline(`display-message -p -t ${pane.runtimeId} "${RECOVERY_CURSOR_PROBE_FORMAT}"`, (reply) => {
             if (settled)
@@ -1170,10 +1772,15 @@ export class SessionChannel {
             }
             const cursorLine = reply.lines[0] ?? "";
             const fallbackSize = this.layoutSizeFor(pane.runtimeId);
+            this.observeScrollOnClear(pane, cursorLine);
             const deliveries = participants.map(({ sub, epoch }) => ({
                 sub,
                 epoch,
-                events: sub.feed.cursorReply(epoch, cursorLine, fallbackSize),
+                events: sub.feed
+                    .cursorReply(epoch, cursorLine, fallbackSize)
+                    .map((event) => event.type === "seed" && sub.nativeBootstrap && !nativeCapture
+                    ? { ...event, requiresNativeRecapture: true }
+                    : event),
             }));
             if (!participantsExact() || deliveries.some(({ events }) => events.length === 0)) {
                 fail();
@@ -1213,6 +1820,7 @@ export class SessionChannel {
             return;
         }
         const participants = live.map((sub) => Object.freeze({ sub, epoch: sub.feed.beginReseed() }));
+        const nativeCapture = !this.nativeBootstrapUnavailable && participants.every(({ sub }) => sub.nativeBootstrap);
         const reseedOrdinal = ++recovery.reseedOrdinal;
         const nonce = this.opts.generateAtomicHookNonce?.() ?? randomBytes(24).toString("hex");
         if (!/^[0-9a-f]{32,128}$/u.test(nonce)) {
@@ -1288,11 +1896,11 @@ export class SessionChannel {
             return;
         }
         const sentinel = (kind) => `display-message -p -l -t ${pane.runtimeId} ` + `"%tmux-ide-atomic-v1 ${nonce} ${kind}"`;
-        const observerCommands = ` ; set-buffer -a -b ${observer.bufferName} ${tmuxSingleQuote(observer.record)}` +
+        const observerCommands = ` ; ${boundedTmuxInteractionAppendCommand(observer.bufferName, observer.record)}` +
             ` ; wait-for -S ${observer.signalChannel}`;
         const body = `set-option -po -t ${pane.runtimeId} ${INTERNAL_READ_OPERATION_OPTION} ${internalReadMarker}` +
             ` ; ${sentinel("start")}` +
-            ` ; capture-pane -p -e -J -S -${this.opts.historyLines ?? ""} -t ${pane.runtimeId}` +
+            ` ; capture-pane -p ${nativeCapture ? "-R" : "-e -J"} -S -${this.opts.historyLines ?? ""} -t ${pane.runtimeId}` +
             ` ; ${sentinel("capture-end")}` +
             ` ; display-message -p -t ${pane.runtimeId} "${RECOVERY_CURSOR_PROBE_FORMAT}"` +
             ` ; ${sentinel("cursor-end")}` +
@@ -1344,13 +1952,34 @@ export class SessionChannel {
                         return;
                     }
                     const captureLines = Object.freeze([...result.captureLines]);
-                    for (const { sub, epoch } of participants)
-                        sub.feed.captureReply(epoch, captureLines);
+                    const native = nativeCapture ? decodeNativeGridCapture(captureLines.join("\n")) : null;
+                    if (nativeCapture && (!native || !isNativeBootstrapCapture(native))) {
+                        if (nativeBootstrapUnsupported(true, captureLines, native)) {
+                            this.nativeBootstrapUnavailable = true;
+                            for (const { sub } of participants)
+                                sub.nativeBootstrap = false;
+                        }
+                        fail(result.statusObserved);
+                        return;
+                    }
+                    if (native)
+                        this.nativeBootstrapConfirmed = true;
+                    for (const { sub, epoch } of participants) {
+                        if (native)
+                            sub.feed.captureNativeReply(epoch, native);
+                        else
+                            sub.feed.captureReply(epoch, captureLines);
+                    }
                     const fallbackSize = this.layoutSizeFor(pane.runtimeId);
+                    this.observeScrollOnClear(pane, result.cursorLine);
                     const deliveries = participants.map(({ sub, epoch }) => ({
                         sub,
                         epoch,
-                        events: sub.feed.cursorReply(epoch, result.cursorLine, fallbackSize),
+                        events: sub.feed
+                            .cursorReply(epoch, result.cursorLine, fallbackSize)
+                            .map((event) => event.type === "seed" && sub.nativeBootstrap && !nativeCapture
+                            ? { ...event, requiresNativeRecapture: true }
+                            : event),
                     }));
                     if (!participantsExact() || deliveries.some(({ events }) => events.length === 0)) {
                         fail(true);
@@ -1669,8 +2298,29 @@ export class SessionChannel {
         }
     }
     // ── Notifications (channel order is the invariant) ──────────────────────
+    observeScrollOnClear(pane, cursorLine) {
+        const value = cursorLine.trim().split(/\s+/)[22];
+        pane.scrollOnClear = value === "0" || value === "1" ? value === "1" : undefined;
+    }
     onNotify(name, rest) {
         if (name === "subscription-changed") {
+            const policy = /^tmux-ide-scroll-on-clear\s+\$[0-9]+\s+@[0-9]+\s+[0-9]+\s+(%[0-9]+)\s+:\s+([01])\s*$/u.exec(rest);
+            if (policy) {
+                const pane = this.panesByRuntime.get(policy[1]);
+                const enabled = policy[2] === "1";
+                if (pane && pane.scrollOnClear !== enabled) {
+                    pane.scrollOnClear = enabled;
+                    // A pending capture already reads policy in its ordered cursor
+                    // probe. Cancelling it here can repeatedly retire opening recipes
+                    // while tmux delivers the initial sampled option notification.
+                    // Live feeds instead replace content and policy together.
+                    if (!this.recoveries.has(pane.runtimeId))
+                        for (const sub of pane.subs)
+                            if (!sub.closed && !sub.frozen && sub.feed.currentState() === "live")
+                                this.reseedPlain(sub);
+                }
+                return;
+            }
             const history = /^tmux-ide-pane-history\s+\$[0-9]+\s+@[0-9]+\s+[0-9]+\s+(%[0-9]+)\s+:\s+([0-9]+)\s*$/u.exec(rest);
             if (history) {
                 const pane = this.panesByRuntime.get(history[1]);
@@ -1692,6 +2342,7 @@ export class SessionChannel {
             (/^tmux-ide-pane-borders\s+\$[0-9]+\s+@[0-9]+\s+[0-9]+\s+-\s*:\s*(top|bottom|off)\s*$/u.test(rest) ||
                 /^tmux-ide-copy-keys\s+\$[0-9]+\s+@[0-9]+\s+[0-9]+\s+-\s*:\s*(emacs|vi)\s*$/u.test(rest))) {
             this.windowAuthorityOrdinal += 1;
+            this.windowIdentityOrdinal += 1;
             this.scheduleSync();
             return;
         }
@@ -1700,6 +2351,8 @@ export class SessionChannel {
             name === "session-window-changed" ||
             STRUCTURAL_NOTIFICATIONS.has(name)) {
             this.windowAuthorityOrdinal += 1;
+            if (name !== "layout-change")
+                this.windowIdentityOrdinal += 1;
         }
         // Layout changes remain a second honest wake-up: a native resize can arrive
         // before the once-per-second subscription notification. The inventory
@@ -1712,6 +2365,10 @@ export class SessionChannel {
             const runtime = rest.trim().split(/\s+/)[0] ?? "";
             if (!runtime.startsWith("%"))
                 return;
+            if (this.recoveries.get(runtime)?.stage === "native-pause") {
+                this.ledger.notePause(runtime);
+                return;
+            }
             this.cancelRecovery(runtime);
             this.ledger.notePause(runtime);
             const pane = this.panesByRuntime.get(runtime);
@@ -1753,10 +2410,13 @@ export class SessionChannel {
         }
         if (name === "layout-change") {
             const change = parseLayoutChange(rest);
-            if (!change)
+            if (!change) {
+                this.windowIdentityOrdinal += 1;
                 return;
+            }
             const parsed = parseLayout(change.visible);
             if (!parsed) {
+                this.windowIdentityOrdinal += 1;
                 this.scheduleSync(); // never guess from a failed parse
                 return;
             }
@@ -1765,6 +2425,12 @@ export class SessionChannel {
                 zoomed: change.zoomed,
                 unzoomed: parseLayout(change.layout) ?? undefined,
             };
+            const previousLayout = this.pendingLayoutOutput.get(change.windowId)?.layout ??
+                this.layoutByWindow.get(change.windowId);
+            if (!pendingLayout.unzoomed ||
+                !previousLayout ||
+                !layoutIdentitiesEqual(previousLayout, pendingLayout))
+                this.windowIdentityOrdinal += 1;
             // Resync on BOTH structural deltas: an unknown leaf (new pane) and a
             // known pane of this window missing from the leaves (a killed pane in a
             // surviving window emits only %layout-change — without this, its
@@ -1837,6 +2503,11 @@ export class SessionChannel {
             return;
         }
         if (name === "session-window-changed") {
+            // The notification carries backing identity only; duplicate links require an index read.
+            if (this.windowLinkAuthority) {
+                this.scheduleSync();
+                return;
+            }
             const change = parseSessionWindowChanged(rest);
             if (!change)
                 return;
@@ -1881,10 +2552,16 @@ export class SessionChannel {
             this.nativeClientProbePending = false;
         });
     }
-    releasePendingLayout(windowRuntimeId) {
+    releasePendingLayout(windowRuntimeId, syncOrdinal) {
         const pending = this.pendingLayoutOutput.get(windowRuntimeId);
         this.pendingLayoutOutput.delete(windowRuntimeId);
         this.emitLayout(windowRuntimeId);
+        for (const pane of this.panesByRuntime.values()) {
+            if (pane.windowRuntimeId !== windowRuntimeId)
+                continue;
+            for (const sub of pane.subs)
+                sub.resumeLayoutCapture?.(syncOrdinal);
+        }
         if (pending?.overflowed) {
             for (const pane of this.panesByRuntime.values()) {
                 if (pane.windowRuntimeId === windowRuntimeId)
@@ -1920,6 +2597,9 @@ export class SessionChannel {
             this.emitLayoutAuthorityTo(subscriber, runtimeSessionId);
     }
     emitLayoutAuthorityTo(subscriber, runtimeSessionId) {
+        const windowLinks = this.windowLinkAuthority?.snapshot();
+        if (!windowLinks)
+            return;
         const layouts = [...this.layoutByWindow.keys()]
             .map((runtimeId) => this.layoutEventFor(runtimeId))
             .filter((event) => event !== null);
@@ -1927,6 +2607,7 @@ export class SessionChannel {
             session: this.opts.session,
             runtimeSessionId,
             topologyEpoch: this.layoutTopologyEpoch,
+            windowLinks,
             layouts,
         });
     }
@@ -2017,6 +2698,7 @@ export class SessionChannel {
     async syncNow() {
         if (this.disposed)
             return;
+        const syncOrdinal = ++this.syncOrdinal;
         const lines = await this.io.request(`list-panes -s -t "${this.opts.session}" -F "#{pane_id}\t#{pane_active}\t#{window_id}\t#{?window_active,1,0}"`);
         const truth = [];
         for (const line of lines) {
@@ -2030,8 +2712,12 @@ export class SessionChannel {
                 windowActive: windowActive === "1",
             });
         }
+        const previousCurrentWindow = this.currentWindow;
         const { listed, movedWindowRuntimeIds } = this.applyPaneTruth(truth);
-        await this.syncWindows(this.opts.session, movedWindowRuntimeIds);
+        await this.syncWindows(this.opts.session, movedWindowRuntimeIds, previousCurrentWindow, syncOrdinal);
+        for (const pane of this.panesByRuntime.values())
+            for (const sub of pane.subs)
+                sub.resumeLayoutCapture?.(syncOrdinal);
         this.discovery.discover(listed);
     }
     applyPaneTruth(truth) {
@@ -2079,7 +2765,7 @@ export class SessionChannel {
         return { listed, movedWindowRuntimeIds };
     }
     async refreshTrustedInventory(expectedRuntimeSessionId, attempt = 0) {
-        const authorityOrdinal = this.windowAuthorityOrdinal;
+        const authorityOrdinal = this.windowIdentityOrdinal;
         const beforeLines = await this.io.request(`list-panes -s -t "${expectedRuntimeSessionId}" -F "${SESSION_PANE_DESCRIPTOR_FORMAT}"`);
         if (this.disposed)
             throw new Error(`mirror session ${this.opts.session} is disposed`);
@@ -2089,7 +2775,20 @@ export class SessionChannel {
             parsed.descriptors.length !== beforeLines.length) {
             throw new Error(`trusted inventory for ${this.opts.session} is malformed`);
         }
-        const descriptors = parsed.descriptors;
+        const descriptorByPane = new Map();
+        for (const row of parsed.descriptors) {
+            const previous = descriptorByPane.get(row.runtimePaneId);
+            if (previous) {
+                const comparable = (value) => JSON.stringify({ ...value, windowActive: false, windowIndex: null });
+                if (comparable(previous) !== comparable(row))
+                    throw new Error("Inconsistent linked pane observation");
+                if (row.windowActive)
+                    descriptorByPane.set(row.runtimePaneId, row);
+            }
+            else
+                descriptorByPane.set(row.runtimePaneId, row);
+        }
+        const descriptors = [...descriptorByPane.values()];
         const runtimePaneIds = new Set(descriptors.map((pane) => pane.runtimePaneId));
         const runtimeSessionIds = new Set(descriptors.map((pane) => pane.runtimeSessionId));
         const activeWindowIds = new Set(descriptors.filter((pane) => pane.windowActive).map((pane) => pane.windowId));
@@ -2109,10 +2808,26 @@ export class SessionChannel {
             computedWindowCounts.set(runtimeWindowId, (computedWindowCounts.get(runtimeWindowId) ?? 0) + 1);
         }
         if (descriptors.some((pane) => pane.windowPaneCount !== computedWindowCounts.get(pane.windowId) ||
-            pane.sessionWindowCount !== computedWindowCounts.size)) {
+            pane.sessionWindowCount !== descriptors[0].sessionWindowCount)) {
             throw new Error(`trusted inventory for ${this.opts.session} has incomplete counts`);
         }
         const windowStage = await this.stageWindows(expectedRuntimeSessionId);
+        const descriptorKeys = new Set();
+        for (const row of parsed.descriptors) {
+            const link = windowStage.links.find((link) => link.index === row.windowIndex);
+            const key = `${row.windowIndex}:${row.runtimePaneId}`;
+            if (!link ||
+                link.runtimeWindowId !== row.windowId ||
+                link.active !== row.windowActive ||
+                descriptorKeys.has(key))
+                throw new Error(`trusted inventory for ${this.opts.session} lacks verified identity: inconsistent linked pane membership`);
+            descriptorKeys.add(key);
+        }
+        for (const link of windowStage.links) {
+            const count = computedWindowCounts.get(link.runtimeWindowId);
+            if (parsed.descriptors.filter((row) => row.windowIndex === link.index).length !== count)
+                throw new Error("Incomplete linked pane membership");
+        }
         const repairedPanes = await this.repairTrustedPaneIdentity(descriptors, windowStage.layouts);
         const afterLines = await this.io.request(`list-panes -s -t "${expectedRuntimeSessionId}" -F "${SESSION_PANE_DESCRIPTOR_FORMAT}"`);
         const confirmedWindowStage = await this.stageWindows(expectedRuntimeSessionId);
@@ -2122,8 +2837,8 @@ export class SessionChannel {
             confirmedWindowStage.repairedIdentity ||
             repairedPanes ||
             !coherent ||
-            !this.windowStagesEqual(windowStage, confirmedWindowStage) ||
-            authorityOrdinal !== this.windowAuthorityOrdinal) {
+            !this.windowStageIdentitiesEqual(windowStage, confirmedWindowStage) ||
+            authorityOrdinal !== this.windowIdentityOrdinal) {
             if (attempt >= 1)
                 throw new Error(`trusted inventory for ${this.opts.session} did not settle`);
             return await this.refreshTrustedInventory(expectedRuntimeSessionId, attempt + 1);
@@ -2153,6 +2868,7 @@ export class SessionChannel {
                 break;
         }
         if (confirmedWindowStage.currentWindow !== activeWindowId ||
+            confirmedWindowStage.links.length !== descriptors[0].sessionWindowCount ||
             confirmedWindowStage.windows.size !== computedWindowCounts.size ||
             !stagedPaneMembershipExact ||
             stagedPaneCount !== descriptors.length ||
@@ -2190,7 +2906,7 @@ export class SessionChannel {
             throw new Error(`trusted inventory for ${this.opts.session} is degraded`);
         }
         const windowCounts = computedWindowCounts;
-        const sessionWindowCount = computedWindowCounts.size;
+        const sessionWindowCount = confirmedWindowStage.links.length;
         const panes = descriptors.map((descriptor) => {
             const record = this.panesByRuntime.get(descriptor.runtimePaneId);
             const runtimeWindowId = descriptor.windowId;
@@ -2218,8 +2934,10 @@ export class SessionChannel {
                 active: descriptor.paneActive && descriptor.windowActive,
                 role: descriptor.role,
                 name: descriptor.name,
+                ...(descriptor.nameSource ? { nameSource: descriptor.nameSource } : {}),
                 type: descriptor.type,
                 missionStamp: descriptor.missionStamp,
+                nativePaneBirthId: descriptor.nativePaneBirthId ?? null,
                 dir: descriptor.cwd ?? "",
             });
         });
@@ -2229,12 +2947,18 @@ export class SessionChannel {
             panes: Object.freeze(panes),
         });
     }
-    async syncWindows(target = this.opts.session, requiredLayoutEmits = new Set()) {
-        const stage = await this.stageWindows(target);
-        this.commitWindowStage(stage, requiredLayoutEmits);
+    async syncWindows(target = this.opts.session, requiredLayoutEmits = new Set(), previousCurrentWindow = this.currentWindow, syncOrdinal) {
+        const stage = await this.stageWindows(target).catch((error) => {
+            this.windowLinkAuthority?.invalidate();
+            this.latestWindowStage = null;
+            throw error;
+        });
+        this.commitWindowStage(stage, requiredLayoutEmits, previousCurrentWindow, syncOrdinal);
         return stage.repairedIdentity;
     }
-    commitWindowStage(stage, requiredLayoutEmits = new Set(), previousCurrentWindow = this.currentWindow) {
+    commitWindowStage(stage, requiredLayoutEmits = new Set(), previousCurrentWindow = this.currentWindow, syncOrdinal) {
+        this.windowLinkAuthority?.reconcile(stage.links);
+        this.latestWindowStage = stage;
         const changedWindows = new Set();
         for (const [runtimeId, record] of stage.windows) {
             const previous = this.windowsByRuntime.get(runtimeId);
@@ -2271,6 +2995,9 @@ export class SessionChannel {
                 changedWindows.add(stage.currentWindow);
         }
         this.currentWindow = stage.currentWindow;
+        for (const runtimeId of this.fittedWindows.keys())
+            if (!stage.windows.has(runtimeId))
+                this.fittedWindows.delete(runtimeId);
         this.windowsByRuntime.clear();
         for (const [key, value] of stage.windows)
             this.windowsByRuntime.set(key, value);
@@ -2284,11 +3011,16 @@ export class SessionChannel {
             if (!stage.windows.has(runtimeId))
                 this.pendingLayoutOutput.delete(runtimeId);
         for (const runtimeId of layoutEmits)
-            this.releasePendingLayout(runtimeId);
+            this.releasePendingLayout(runtimeId, syncOrdinal);
         this.emitLayoutAuthority();
     }
-    windowStagesEqual(left, right) {
-        if (left.currentWindow !== right.currentWindow ||
+    // Inventory establishes pane/window identity, not a frozen terminal size.
+    // Native resize notifications independently publish geometry. Requiring two
+    // identical sizes here makes continuous dragging exhaust the inventory retry
+    // and revoke otherwise unchanged window links, stalling layout publication.
+    windowStageIdentitiesEqual(left, right) {
+        if (JSON.stringify(left.links) !== JSON.stringify(right.links) ||
+            left.currentWindow !== right.currentWindow ||
             left.windows.size !== right.windows.size ||
             left.layouts.size !== right.layouts.size) {
             return false;
@@ -2304,49 +3036,42 @@ export class SessionChannel {
                 leftWindow.name !== rightWindow.name ||
                 leftWindow.paneBorderStatus !== rightWindow.paneBorderStatus ||
                 leftWindow.modeKeys !== rightWindow.modeKeys ||
-                leftLayout.zoomed !== rightLayout.zoomed ||
-                JSON.stringify(leftLayout.unzoomed) !== JSON.stringify(rightLayout.unzoomed) ||
-                leftLayout.width !== rightLayout.width ||
-                leftLayout.height !== rightLayout.height ||
-                leftLayout.leaves.length !== rightLayout.leaves.length ||
-                leftLayout.leaves.some((leaf, index) => {
-                    const candidate = rightLayout.leaves[index];
-                    return (!candidate ||
-                        leaf.id !== candidate.id ||
-                        leaf.left !== candidate.left ||
-                        leaf.top !== candidate.top ||
-                        leaf.width !== candidate.width ||
-                        leaf.height !== candidate.height);
-                })) {
+                !layoutIdentitiesEqual(leftLayout, rightLayout)) {
                 return false;
             }
         }
         return true;
     }
     async stageWindows(target = this.opts.session) {
-        const lines = await this.io.request(`list-windows -t "${target}" -F "#{window_id}\t#{qa:@tmux_ide_window_id}\t#{qa:window_name}\t#{window_active}\t#{window_visible_layout}\t#{?window_zoomed_flag,1,0}\t#{pane-border-status}\t#{window_layout}\t#{mode-keys}"`);
+        const lines = await this.io.request(`list-windows -t "${target}" -F "#{window_id}\t#{qa:@tmux_ide_window_id}\t#{qa:window_name}\t#{window_active}\t#{window_visible_layout}\t#{?window_zoomed_flag,1,0}\t#{pane-border-status}\t#{window_layout}\t#{mode-keys}\t#{window_index}"`);
+        if (lines.length > WINDOW_LINK_MAX_LINKS)
+            throw new Error("Window link observation exceeds bound");
         const rows = [];
-        const seenRuntimeIds = new Set();
+        const seenIndexes = new Set();
         for (const raw of lines) {
             // Replies are latin1 byte strings; recover UTF-8 window names first.
             const line = Buffer.from(raw, "latin1").toString("utf8");
             const parts = line.split("\t");
-            if (parts.length !== 7 && parts.length !== 8 && parts.length !== 9) {
+            if (parts.length !== 10) {
                 throw new Error(`window layout truth for ${this.opts.session} is malformed`);
             }
-            const [runtimeId = "", stampRaw = "", nameRaw = "", active = "", visible = "", zoomed = "", borderStatus = "off", full = visible, modeKeys,] = parts;
+            const [runtimeId = "", stampRaw = "", nameRaw = "", active = "", visible = "", zoomed = "", borderStatus = "off", full = visible, modeKeys, indexRaw = "",] = parts;
+            const index = Number(indexRaw);
             if (!/^@[0-9]+$/u.test(runtimeId) ||
-                seenRuntimeIds.has(runtimeId) ||
+                !/^(?:0|[1-9][0-9]*)$/u.test(indexRaw) ||
+                !Number.isSafeInteger(index) ||
+                seenIndexes.has(index) ||
                 (active !== "0" && active !== "1") ||
                 (zoomed !== "0" && zoomed !== "1") ||
                 (borderStatus !== "top" && borderStatus !== "bottom" && borderStatus !== "off") ||
                 (modeKeys !== undefined && modeKeys !== "emacs" && modeKeys !== "vi")) {
                 throw new Error(`window layout truth for ${this.opts.session} is malformed`);
             }
-            seenRuntimeIds.add(runtimeId);
+            seenIndexes.add(index);
             const stamp = decodeTmuxArgument(stampRaw);
             const name = decodeTmuxArgument(nameRaw);
             rows.push({
+                index,
                 runtimeId,
                 stamp: stamp.length > 0 ? stamp : null,
                 name: name.length > 0 ? name : null,
@@ -2365,8 +3090,22 @@ export class SessionChannel {
         if (activeRows.length !== 1) {
             throw new Error(`window layout truth for ${this.opts.session} has inconsistent active window`);
         }
-        const nextLayoutByWindow = new Map();
+        const backingRows = new Map();
         for (const row of rows) {
+            const previous = backingRows.get(row.runtimeId);
+            if (previous &&
+                (previous.stamp !== row.stamp ||
+                    previous.name !== row.name ||
+                    previous.visible !== row.visible ||
+                    previous.full !== row.full ||
+                    previous.zoomed !== row.zoomed ||
+                    previous.paneBorderStatus !== row.paneBorderStatus ||
+                    previous.modeKeys !== row.modeKeys))
+                throw new Error("Inconsistent linked backing observation");
+            backingRows.set(row.runtimeId, row);
+        }
+        const nextLayoutByWindow = new Map();
+        for (const row of backingRows.values()) {
             const parsed = parseLayout(row.visible);
             if (!parsed) {
                 throw new Error(`window layout truth for ${this.opts.session} is malformed`);
@@ -2379,7 +3118,7 @@ export class SessionChannel {
         // Valid unique stamps are identity; missing/invalid/duplicated stamps are
         // ALL regenerated and stamped back (the pane policy, applied to windows).
         const stampCounts = new Map();
-        for (const row of rows) {
+        for (const row of backingRows.values()) {
             if (row.stamp && WorkspaceIdSchemaZ.safeParse(row.stamp).success) {
                 stampCounts.set(row.stamp, (stampCounts.get(row.stamp) ?? 0) + 1);
             }
@@ -2388,10 +3127,8 @@ export class SessionChannel {
         const generateWindowId = this.opts.generateWindowId ?? defaultMirrorWindowId;
         let repairedIdentity = false;
         const next = new Map();
-        let nextCurrentWindow = "";
-        for (const row of rows) {
-            if (row.active)
-                nextCurrentWindow = row.runtimeId;
+        const nextCurrentWindow = activeRows[0].runtimeId;
+        for (const row of backingRows.values()) {
             let semanticId = null;
             if (row.stamp && stampCounts.get(row.stamp) === 1) {
                 semanticId = row.stamp;
@@ -2434,6 +3171,12 @@ export class SessionChannel {
             layouts: nextLayoutByWindow,
             currentWindow: nextCurrentWindow,
             repairedIdentity,
+            links: rows.map((row) => ({
+                index: row.index,
+                runtimeWindowId: row.runtimeId,
+                semanticWindowId: next.get(row.runtimeId).semanticId ?? "",
+                active: row.active,
+            })),
         };
     }
     async reconcileIdentity(descriptors, listed) {
@@ -2624,6 +3367,8 @@ export class SessionChannel {
     onChannelExit() {
         if (this.disposed)
             return;
+        this.opts.ownedViewer?.dispose();
+        this.windowLinkAuthority?.dispose();
         this.nativeGrid.dispose();
         this.settleFirstJoin();
         for (const runtime of [...this.recoveries.keys()])