@vibecook/ghosttea-react 0.6.1 → 0.7.0

package/dist/runtime.js

@@ -10,10 +10,23 @@ function sameSessionActivity(left, right) {
         left.foregroundProcessGroupId === right.foregroundProcessGroupId &&
         left.observedAtMs === right.observedAtMs);
 }
+/** States that leave a screen on display which the host is no longer updating. */
+export function showsStaleScreen(state) {
+    return state !== "live" && state !== "opening";
+}
+/** Whether a pane is showing stale content: frozen outright, or live but not yet redrawn. */
+export function sessionIsFrozen(state) {
+    return showsStaleScreen(state.state) || state.awaitingRecoveryFrame;
+}
 const FRAME_SUBSCRIPTION_ACK_TIMEOUT_MS = 10_000;
 const FRAME_SUBSCRIPTION_ACK_PROTOCOL_MINOR = 7;
 const FRAME_BRIDGE_CAPABILITY_VERSION = 1;
+const CONFIG_PROTOCOL_MINOR = 10;
+const REMOTE_LIFECYCLE_PROTOCOL_MINOR = 12;
+const CONTROL_REVISION_CAS_PROTOCOL_MINOR = 13;
 const DEFAULT_FRAME_SUBSCRIPTION_GRACE_MS = 1_000;
+/** A one-shot resume covers a 20 s dial plus the attach handshake. */
+const RECONNECT_REQUEST_TIMEOUT_MS = 60_000;
 export function waitForGhostteaRendererPorts(timeoutMs = 10_000) {
     return new Promise((resolve, reject) => {
         const timeout = window.setTimeout(() => {
@@ -61,7 +74,15 @@ export class GhostteaTerminalRuntime extends EventTarget {
     #scrollbarByHandle = new Map();
     #focusByView = new Map();
     #views = new Map();
+    #remoteSessions = new Map();
+    #controlBySession = new Map();
+    /** Sessions whose current outage episode has already produced a full snapshot. */
+    #recoveredSessions = new Set();
+    #remoteLifecycleSupported = false;
+    #controlRevisionCasSupported = false;
     #rendererBackend = "starting";
+    #configSnapshot;
+    #configProtocolSupported = false;
     #metadataTimers = new Map();
     #resync;
     #performanceRequestId = 1;
@@ -112,6 +133,9 @@ export class GhostteaTerminalRuntime extends EventTarget {
             else if (data.type === "frame-resync-complete") {
                 this.#resync.complete(data.sessionHandle);
             }
+            else if (data.type === "frame-committed") {
+                this.#recordCommittedFrame(data.sessionHandle, data.fullSnapshot);
+            }
             else if (data.type === "catalog-pressure") {
                 console.warn(`[terminal-runtime] native text catalog budget exceeded for ${data.sessionHandle}; using bounded fallback text`);
                 this.dispatchEvent(new CustomEvent("catalog-pressure", { detail: data }));
@@ -210,6 +234,12 @@ export class GhostteaTerminalRuntime extends EventTarget {
             this.dispatchEvent(new CustomEvent("session-metadata", { detail: exited }));
             this.dispatchEvent(new CustomEvent("session-exited", { detail }));
         });
+        this.#control.addEventListener("events-lost", () => {
+            // The daemon dropped events faster than this client drained them. Any
+            // of them could have been a session-exited, so reconcile against the
+            // daemon's authoritative session list.
+            void this.#resyncAfterLostEvents();
+        });
         this.#control.addEventListener("session-activity-changed", (event) => {
             const detail = event.detail;
             const handle = this.#handleBySessionId.get(detail.sessionId);
@@ -223,20 +253,23 @@ export class GhostteaTerminalRuntime extends EventTarget {
         });
         this.#control.addEventListener("control-changed", (event) => {
             const detail = event.detail;
-            for (const [viewId, view] of this.#views) {
-                if (view.sessionId !== detail.sessionId)
-                    continue;
-                if (viewId !== detail.controllerViewId) {
-                    view.controlEpoch = undefined;
-                    continue;
-                }
-                view.controlEpoch = detail.controlEpoch;
-                if (view.desiredCols !== undefined &&
-                    view.desiredRows !== undefined &&
-                    (view.desiredCols !== detail.cols || view.desiredRows !== detail.rows)) {
-                    this.#sendResize(viewId, view, view.desiredCols, view.desiredRows);
-                }
-            }
+            this.#applyController(detail.sessionId, { viewId: detail.controllerViewId, controlEpoch: detail.controlEpoch }, detail.cols, detail.rows);
+        });
+        this.#control.addEventListener("control-state", (event) => {
+            const detail = event.detail;
+            this.#applyController(detail.sessionId, detail.controller, detail.cols, detail.rows, detail.controlRevision);
+        });
+        this.#control.addEventListener("remote-session-state-changed", (event) => {
+            const detail = event.detail;
+            this.#applyRemoteSessionState(detail.sessionId, detail, false);
+        });
+        this.#control.addEventListener("view-state-changed", (event) => {
+            const detail = event.detail;
+            this.#applyViewState(detail.viewId, detail);
+        });
+        this.#control.addEventListener("config-changed", (event) => {
+            const detail = event.detail;
+            this.#installConfig(detail.config);
         });
         this.#frames = ports.frames;
         this.#frames.onmessage = ({ data }) => {
@@ -286,9 +319,44 @@ export class GhostteaTerminalRuntime extends EventTarget {
         if (hello.type !== "hello" || hello.protocolMajor !== PROTOCOL_MAJOR)
             throw new Error("ghosttead protocol mismatch");
         this.#frameSubscriptionAcksSupported = hello.protocolMinor >= FRAME_SUBSCRIPTION_ACK_PROTOCOL_MINOR;
+        this.#configProtocolSupported = hello.protocolMinor >= CONFIG_PROTOCOL_MINOR;
+        this.#remoteLifecycleSupported = hello.protocolMinor >= REMOTE_LIFECYCLE_PROTOCOL_MINOR;
+        this.#controlRevisionCasSupported = hello.protocolMinor >= CONTROL_REVISION_CAS_PROTOCOL_MINOR;
+        if (this.#configProtocolSupported && hello.configRevision !== undefined) {
+            await this.#refreshConfig();
+        }
         await this.#queueFrameSubscriptionSync();
         console.info("[terminal-runtime] authenticated ghosttead protocol");
     }
+    get configSnapshot() {
+        return this.#configSnapshot;
+    }
+    async getConfig() {
+        await this.connect();
+        return this.#configSnapshot;
+    }
+    async reloadConfig() {
+        await this.connect();
+        const response = await this.#control.request({ type: "reload-config" });
+        if (response.type !== "config")
+            throw new Error("ghosttead returned an unexpected configuration response");
+        this.#installConfig(response.config);
+        return response.config;
+    }
+    #installConfig(config) {
+        if (this.#configSnapshot?.revision === config.revision)
+            return;
+        this.#configSnapshot = config;
+        this.dispatchEvent(new CustomEvent("config-changed", { detail: config }));
+    }
+    async #refreshConfig() {
+        if (!this.#configProtocolSupported || !this.#control)
+            return;
+        const response = await this.#control.request({ type: "get-config" });
+        if (response.type !== "config")
+            throw new Error("ghosttead returned an unexpected configuration response");
+        this.#installConfig(response.config);
+    }
     #handleFrameChannelControl(message) {
         if (!message || typeof message !== "object")
             return false;
@@ -555,6 +623,74 @@ export class GhostteaTerminalRuntime extends EventTarget {
         }
         return response.sessions;
     }
+    /**
+     * Reconcile tracked sessions against the daemon's authoritative list after
+     * an events-lost notice. A session still listed but now exited had its exit
+     * event lost; a session absent from the list entirely exited and left the
+     * registry, so its exit details are gone and are reported as unknown.
+     */
+    async #resyncAfterLostEvents() {
+        try {
+            const before = new Map();
+            for (const session of this.#sessionByHandle.values()) {
+                before.set(session.id, session);
+            }
+            const [sessions] = await Promise.all([
+                this.listSessions(),
+                this.#refreshConfig(),
+                this.#reconcileRemoteSessions(),
+            ]);
+            const known = new Set();
+            for (const session of sessions) {
+                known.add(session.id);
+                const previous = before.get(session.id);
+                if (!previous || previous.exited || !session.exited)
+                    continue;
+                this.#cancelMetadataRefresh(session.handle);
+                this.dispatchEvent(new CustomEvent("session-metadata", { detail: session }));
+                this.dispatchEvent(new CustomEvent("session-exited", {
+                    detail: {
+                        requestId: 0,
+                        type: "session-exited",
+                        sessionId: session.id,
+                        exitCode: session.exitCode,
+                        exitSignal: session.exitSignal,
+                        requestedTermination: session.requestedTermination,
+                        exitOutcome: session.exitOutcome ?? "unknown",
+                    },
+                }));
+            }
+            for (const [handle, session] of this.#sessionByHandle) {
+                if (session.exited || known.has(session.id))
+                    continue;
+                const detail = {
+                    requestId: 0,
+                    type: "session-exited",
+                    sessionId: session.id,
+                    exitCode: null,
+                    exitSignal: null,
+                    requestedTermination: null,
+                    exitOutcome: "unknown",
+                };
+                this.#cancelMetadataRefresh(handle);
+                const exited = {
+                    ...session,
+                    exited: true,
+                    exitCode: null,
+                    exitSignal: null,
+                    requestedTermination: null,
+                    exitOutcome: "unknown",
+                };
+                this.#sessionByHandle.set(handle, exited);
+                this.dispatchEvent(new CustomEvent("session-metadata", { detail: exited }));
+                this.dispatchEvent(new CustomEvent("session-exited", { detail }));
+            }
+        }
+        catch (error) {
+            if (!this.#disposed)
+                console.error("[terminal-runtime] failed to resynchronize state after lost events", error);
+        }
+    }
     async listRemoteHosts() {
         await this.connect();
         const response = await this.#control.request({ type: "list-remote-hosts" });
@@ -569,7 +705,7 @@ export class GhostteaTerminalRuntime extends EventTarget {
             throw new Error("ghosttead returned an unexpected response");
         return response.sessions;
     }
-    async openRemoteSession(deviceId, remoteSessionId, cols, rows) {
+    async openRemoteSession(deviceId, remoteSessionId, cols, rows, deviceName = deviceId) {
         await this.connect();
         const response = await this.#control.request({
             type: "open-remote-session",
@@ -582,6 +718,25 @@ export class GhostteaTerminalRuntime extends EventTarget {
         if (response.type !== "session-created")
             throw new Error("ghosttead could not open the remote session");
         this.registerSession(response.session);
+        // The session counts as remote from here, before any daemon event, so its
+        // input is never queued. A daemon on this minor reports `opening` until
+        // the first snapshot lands, so start there and let its events take over;
+        // an older daemon reports nothing at all, and seeding `opening` against it
+        // would block input forever. The sequence below is under every real event.
+        this.#remoteSessions.set(response.session.id, {
+            sessionId: response.session.id,
+            state: this.#remoteLifecycleSupported ? "opening" : "live",
+            reason: null,
+            exit: null,
+            lifecycleSeq: -1,
+            deviceId,
+            deviceName,
+            attempt: null,
+            nextRetryMs: null,
+            lastContactMs: null,
+            observedAt: performance.now(),
+            awaitingRecoveryFrame: false,
+        });
         return response.session;
     }
     async #refreshSession(sessionHandle) {
@@ -590,7 +745,9 @@ export class GhostteaTerminalRuntime extends EventTarget {
             return;
         if (!this.#control)
             throw new Error(`Session ${sessionHandle} is not ready for frame resynchronization`);
-        const response = await this.#control.request({ type: "refresh-session", sessionId: session.id });
+        // A refresh of a remote session re-attaches and resynchronizes over the
+        // network, so it needs the same budget as a one-shot reconnect.
+        const response = await this.#control.request({ type: "refresh-session", sessionId: session.id }, RECONNECT_REQUEST_TIMEOUT_MS);
         if (response.type !== "ok")
             throw new Error("ghosttead rejected frame resynchronization");
     }
@@ -637,8 +794,15 @@ export class GhostteaTerminalRuntime extends EventTarget {
             desiredCols: undefined,
             desiredRows: undefined,
             pendingInput: [],
+            lastViewStateSeq: undefined,
+            lastAttachmentEpoch: undefined,
+            claimedEpoch: undefined,
+            claimedRevision: 0,
         };
         this.#views.set(viewId, view);
+        const remote = this.#remoteSessions.get(sessionId);
+        if (remote && remote.state !== "live")
+            this.#setCursorFrozen(sessionId, true);
         void subscription.ready
             .then(() => {
             const current = this.#views.get(viewId);
@@ -657,8 +821,16 @@ export class GhostteaTerminalRuntime extends EventTarget {
             const current = this.#views.get(viewId);
             if (current !== view)
                 return;
-            current.attachmentEpoch = response.attachmentEpoch;
-            current.readWrite = response.readWrite;
+            const applied = this.#applyViewState(viewId, {
+                ...(response.viewStateSeq !== undefined ? { viewStateSeq: response.viewStateSeq } : {}),
+                viewState: "attached",
+                attachmentEpoch: response.attachmentEpoch,
+                readWrite: response.readWrite,
+                error: null,
+                retryable: null,
+            });
+            if (!applied)
+                return;
             this.dispatchEvent(new CustomEvent("view-attached", {
                 detail: { sessionId, sessionHandle, viewId, readWrite: response.readWrite },
             }));
@@ -712,17 +884,301 @@ export class GhostteaTerminalRuntime extends EventTarget {
             },
         };
     }
-    #sendViewInput(viewId, operation) {
+    get remoteLifecycleSupported() {
+        return this.#remoteLifecycleSupported;
+    }
+    /** Last known lifecycle of a remote session; undefined for local sessions. */
+    remoteSession(sessionId) {
+        return this.#remoteSessions.get(sessionId);
+    }
+    #applyController(sessionId, controller, cols, rows, revision = 0) {
+        const previous = this.#controlBySession.get(sessionId);
+        // A revisioned announcement older than what is cached is a queued view of
+        // the past, and must be dropped whole. Keeping its payload while raising
+        // the revision would manufacture a state that never existed — "nobody
+        // holds control, as of the newest revision" — and that reads as an empty
+        // seat the funnel may claim. The compare-and-swap would not catch it
+        // either: the expectation would be genuinely current, so the host would
+        // accept a claim that takes control from the real holder.
+        if (revision >= 1 && previous !== undefined && revision < previous.revision)
+            return;
+        this.#controlBySession.set(sessionId, {
+            controller,
+            // A legacy `control-changed` carries no revision; keep the last one so a
+            // downgrade never looks like the controller was cleared at a newer one.
+            // Unrevisioned announcements cannot be ordered against each other, so
+            // they stay last-write-wins — the only semantics available for them.
+            revision: Math.max(revision, previous?.revision ?? 0),
+        });
+        for (const [viewId, view] of this.#views) {
+            if (view.sessionId !== sessionId)
+                continue;
+            if (!controller || controller.viewId !== viewId) {
+                view.controlEpoch = undefined;
+                continue;
+            }
+            view.controlEpoch = controller.controlEpoch;
+            if (view.desiredCols !== undefined &&
+                view.desiredRows !== undefined &&
+                (view.desiredCols !== cols || view.desiredRows !== rows)) {
+                this.#sendResize(viewId, view, view.desiredCols, view.desiredRows);
+            }
+        }
+        // A cleared controller is the one case worth re-evaluating: the pane that
+        // still holds focus may now take control back.
+        for (const viewId of this.#viewIdsForSession(sessionId))
+            this.#maybeReclaim(viewId);
+    }
+    *#viewIdsForSession(sessionId) {
+        for (const [viewId, view] of this.#views) {
+            if (view.sessionId === sessionId)
+                yield viewId;
+        }
+    }
+    /**
+     * The single funnel for taking resize control (§4.2.3). Every condition that
+     * gates a claim re-enters here when it changes, because no one event is
+     * enough: recovery marks a view attached before its session reaches live, and
+     * the focus setter suppresses repeat `true` updates, so a claim keyed on
+     * either alone would be skipped and never retried.
+     *
+     * At most one claim per attachment epoch, plus one more each time the
+     * controller is cleared at a newer revision.
+     *
+     * A host that reports real revisions gets a compare-and-swap, so a claim or
+     * a clear that landed since this client last looked rejects the attempt
+     * instead of silently overwriting it. The outcome is asymmetric and needs no
+     * loop of its own: the daemon announces the resulting controller state, this
+     * funnel re-runs on it, and another pane holding control simply fails the
+     * guard above while an empty seat at a newer revision passes the one below.
+     */
+    #maybeReclaim(viewId) {
+        const view = this.#views.get(viewId);
+        if (!view || view.readWrite === false)
+            return;
+        const attachmentEpoch = view.attachmentEpoch;
+        if (attachmentEpoch === undefined)
+            return;
+        if (view.desiredCols === undefined || view.desiredRows === undefined)
+            return;
+        if (this.#focusByView.get(viewId) !== true)
+            return;
+        const remote = this.#remoteSessions.get(view.sessionId);
+        if (remote && (remote.state !== "live" || remote.awaitingRecoveryFrame))
+            return;
+        const control = this.#controlBySession.get(view.sessionId);
+        const controller = control?.controller ?? null;
+        // Never take control from another pane. Our own name on the record is not
+        // a reason to stop: after a resume it is the previous incarnation's, and
+        // the new attachment epoch below is what decides.
+        if (controller && controller.viewId !== viewId)
+            return;
+        const revision = control?.revision ?? 0;
+        // One claim per attachment epoch. A controller *cleared* at a newer
+        // revision earns one more; the seat being confirmed as ours does not.
+        if (view.claimedEpoch === attachmentEpoch && (controller !== null || view.claimedRevision >= revision))
+            return;
+        const session = this.#sessionByHandle.get(view.sessionHandle);
+        if (!session)
+            return;
+        view.claimedEpoch = attachmentEpoch;
+        view.claimedRevision = revision;
+        this.#control?.notify({
+            type: "focus-and-resize",
+            sessionId: session.id,
+            viewId,
+            attachmentEpoch,
+            cols: view.desiredCols,
+            rows: view.desiredRows,
+            // Revision 0 is the "legacy, unknown" sentinel, never a real observation
+            // to swap against: a host without revisions only understands the
+            // unconditional claim, so the field stays off. The negotiated minor is
+            // checked too, because a cached revision could outlive a daemon
+            // downgrade and a daemon that predates the field would ignore it —
+            // turning a swap the caller believes in into a silent overwrite.
+            ...(this.#controlRevisionCasSupported && revision >= 1 ? { expectedControlRevision: revision } : {}),
+        });
+    }
+    /**
+     * The only path that mutates per-view attachment state, whether the update
+     * arrived as an event, a reconciliation, or an attach response. A sequence
+     * at or below the last applied one is a delayed transition from an abandoned
+     * attempt and is dropped; an update without a sequence comes from a daemon
+     * older than the fence and applies directly.
+     */
+    #applyViewState(viewId, update) {
+        const view = this.#views.get(viewId);
+        if (!view)
+            return false;
+        if (update.viewStateSeq !== undefined) {
+            if (view.lastViewStateSeq !== undefined && update.viewStateSeq <= view.lastViewStateSeq)
+                return false;
+            view.lastViewStateSeq = update.viewStateSeq;
+        }
+        const remote = this.#remoteSessions.has(view.sessionId);
+        if (update.viewState === "attached" && update.attachmentEpoch !== null) {
+            // Nothing typed against the previous incarnation may ride out on a
+            // freshly armed epoch.
+            if (remote)
+                view.pendingInput.length = 0;
+            view.attachmentEpoch = update.attachmentEpoch;
+            view.lastAttachmentEpoch = update.attachmentEpoch;
+            if (update.readWrite !== null)
+                view.readWrite = update.readWrite;
+            this.#maybeReclaim(viewId);
+            return true;
+        }
+        view.pendingInput.length = 0;
+        view.attachmentEpoch = undefined;
+        return true;
+    }
+    #applyRemoteSessionState(sessionId, lifecycle, authoritative) {
+        const previous = this.#remoteSessions.get(sessionId);
+        if (previous) {
+            // A reconciliation is the source of truth and may restate its sequence;
+            // a pushed event at a sequence already seen is stale.
+            const stale = authoritative
+                ? lifecycle.lifecycleSeq < previous.lifecycleSeq
+                : lifecycle.lifecycleSeq <= previous.lifecycleSeq;
+            if (stale)
+                return false;
+        }
+        // Lifecycle events and frames travel independent channels, so a recovery
+        // snapshot can commit either side of the live transition. An episode's
+        // latch is cleared when it begins and set by any full snapshot, which lets
+        // both arrival orders resolve without either one having to come first.
+        if (showsStaleScreen(lifecycle.state) && (previous === undefined || !showsStaleScreen(previous.state))) {
+            this.#recoveredSessions.delete(sessionId);
+        }
+        // Coming back from a frozen state, the screen on display is still the one
+        // from before the outage. Keep it marked stale until the recovered stream
+        // has committed a full frame; `opening` never had a screen to distrust.
+        const awaitingRecoveryFrame = lifecycle.state === "live" &&
+            previous !== undefined &&
+            (previous.awaitingRecoveryFrame || showsStaleScreen(previous.state)) &&
+            !this.#recoveredSessions.has(sessionId);
+        const state = {
+            ...lifecycle,
+            sessionId,
+            observedAt: performance.now(),
+            awaitingRecoveryFrame,
+        };
+        this.#remoteSessions.set(sessionId, state);
+        if (state.state !== "live") {
+            for (const view of this.#views.values()) {
+                if (view.sessionId === sessionId)
+                    view.pendingInput.length = 0;
+            }
+        }
+        this.#setCursorFrozen(sessionId, sessionIsFrozen(state));
+        this.dispatchEvent(new CustomEvent("remote-session-state", { detail: state }));
+        for (const viewId of this.#viewIdsForSession(sessionId))
+            this.#maybeReclaim(viewId);
+        return true;
+    }
+    /**
+     * A committed frame is only evidence of recovery if it carries a whole
+     * screen: a partial update repaints part of the stale one, which is exactly
+     * what would thaw a pane too early.
+     */
+    #recordCommittedFrame(sessionHandle, fullSnapshot) {
+        if (!fullSnapshot)
+            return;
+        const sessionId = this.#sessionByHandle.get(sessionHandle)?.id;
+        if (sessionId === undefined || !this.#remoteSessions.has(sessionId))
+            return;
+        this.#recoveredSessions.add(sessionId);
+        this.#thawRecoveredSession(sessionId);
+    }
+    /** What the pane shows is current again, so stop marking it stale. */
+    #thawRecoveredSession(sessionId) {
+        const state = this.#remoteSessions.get(sessionId);
+        if (!state || !state.awaitingRecoveryFrame || !this.#recoveredSessions.has(sessionId))
+            return;
+        const thawed = { ...state, awaitingRecoveryFrame: false };
+        this.#remoteSessions.set(sessionId, thawed);
+        this.#setCursorFrozen(sessionId, sessionIsFrozen(thawed));
+        this.dispatchEvent(new CustomEvent("remote-session-state", { detail: thawed }));
+        for (const viewId of this.#viewIdsForSession(sessionId))
+            this.#maybeReclaim(viewId);
+    }
+    /** Hold the cursor steady while the replica is frozen, without disturbing focus. */
+    #setCursorFrozen(sessionId, frozen) {
+        for (const [viewId, view] of this.#views) {
+            if (view.sessionId === sessionId)
+                this.#postWorker({ type: "cursor-frozen", surfaceId: viewId, frozen });
+        }
+    }
+    async #remoteSessionStateRequest(command, timeoutMs) {
+        await this.connect();
+        if (!this.#remoteLifecycleSupported)
+            return undefined;
+        const response = await this.#control.request(command, timeoutMs);
+        if (response.type !== "remote-session-state") {
+            throw new Error("ghosttead returned an unexpected remote session state");
+        }
+        this.#applyRemoteSessionState(command.sessionId, response, true);
+        this.#applyController(command.sessionId, response.controller, response.cols, response.rows, response.controlRevision);
+        for (const view of response.views)
+            this.#applyViewState(view.viewId, view);
+        return this.#remoteSessions.get(command.sessionId);
+    }
+    /** Rebuild this client's state for one remote session from the daemon. */
+    async getRemoteSessionState(sessionId) {
+        return this.#remoteSessionStateRequest({ type: "get-remote-session-state", sessionId }, 10_000);
+    }
+    async reconnectRemoteSession(sessionId) {
+        return this.#remoteSessionStateRequest({ type: "reconnect-remote-session", sessionId }, RECONNECT_REQUEST_TIMEOUT_MS);
+    }
+    async retryRemoteView(sessionId, viewId) {
+        await this.connect();
+        if (!this.#remoteLifecycleSupported)
+            return;
+        const response = await this.#control.request({ type: "retry-remote-view", sessionId, viewId }, RECONNECT_REQUEST_TIMEOUT_MS);
+        if (response.type !== "view-state")
+            throw new Error("ghosttead returned an unexpected view state");
+        this.#applyViewState(response.viewId, response);
+    }
+    #reconcileRemoteSessions() {
+        if (!this.#remoteLifecycleSupported)
+            return Promise.resolve();
+        return Promise.all([...this.#remoteSessions.keys()].map((sessionId) => this.getRemoteSessionState(sessionId).catch((error) => {
+            if (!this.#disposed) {
+                console.warn(`[terminal-runtime] could not reconcile remote session ${sessionId}`, error);
+            }
+        })));
+    }
+    /**
+     * `silent` marks operations that drop without the keystroke hint: focus and
+     * geometry updates are cosmetic, and pointer gestures are already answered
+     * by the pane's frozen treatment.
+     */
+    #sendViewInput(viewId, operation, silent = false) {
         const view = this.#views.get(viewId);
         if (!view || view.readWrite === false)
             return;
-        if (view.attachmentEpoch === undefined) {
+        const remote = this.#remoteSessions.get(view.sessionId);
+        const attachmentEpoch = view.attachmentEpoch;
+        // Input for a remote session is dropped with feedback rather than queued:
+        // replaying a keystroke across an outage would deliver it to a screen the
+        // user has never seen. The queue below survives only for a local session's
+        // mount-to-attach gap, which is a local IPC round-trip.
+        if (remote && (remote.state !== "live" || attachmentEpoch === undefined)) {
+            view.pendingInput.length = 0;
+            if (!silent)
+                this.#reportSuppressedInput(view.sessionId, viewId, remote.state);
+            return;
+        }
+        if (attachmentEpoch === undefined) {
             if (view.pendingInput.length < 256)
                 view.pendingInput.push(operation);
             return;
         }
         view.inputSequence += 1;
-        operation(view.attachmentEpoch, view.inputSequence);
+        operation(attachmentEpoch, view.inputSequence);
+    }
+    #reportSuppressedInput(sessionId, viewId, state) {
+        this.dispatchEvent(new CustomEvent("input-suppressed", { detail: { sessionId, viewId, state } }));
     }
     sendText(sessionId, viewId, text) {
         this.#sendViewInput(viewId, (attachmentEpoch, inputSequence) => this.#control?.notify({ type: "send-text", sessionId, viewId, attachmentEpoch, inputSequence, text }));
@@ -743,17 +1199,18 @@ export class GhostteaTerminalRuntime extends EventTarget {
             this.#postWorker({ type: "cursor-activity", sessionHandle: handle });
     }
     sendMouse(sessionId, viewId, event) {
-        this.#sendViewInput(viewId, (attachmentEpoch, inputSequence) => this.#control?.notify({ type: "send-mouse", sessionId, viewId, attachmentEpoch, inputSequence, event }));
+        this.#sendViewInput(viewId, (attachmentEpoch, inputSequence) => this.#control?.notify({ type: "send-mouse", sessionId, viewId, attachmentEpoch, inputSequence, event }), true);
     }
     scroll(sessionId, viewId, rows) {
         if (rows === 0)
             return;
-        this.#sendViewInput(viewId, (attachmentEpoch, inputSequence) => this.#control?.notify({ type: "scroll", sessionId, viewId, attachmentEpoch, inputSequence, rows }));
+        // Scrolling is host-side input, so it is simply inert while frozen.
+        this.#sendViewInput(viewId, (attachmentEpoch, inputSequence) => this.#control?.notify({ type: "scroll", sessionId, viewId, attachmentEpoch, inputSequence, rows }), true);
     }
     scrollTo(sessionId, viewId, row) {
         if (!Number.isSafeInteger(row) || row < 0)
             return;
-        this.#sendViewInput(viewId, (attachmentEpoch, inputSequence) => this.#control?.notify({ type: "scroll-to", sessionId, viewId, attachmentEpoch, inputSequence, row }));
+        this.#sendViewInput(viewId, (attachmentEpoch, inputSequence) => this.#control?.notify({ type: "scroll-to", sessionId, viewId, attachmentEpoch, inputSequence, row }), true);
     }
     scrollbar(sessionHandle) {
         return this.#scrollbarByHandle.get(sessionHandle);
@@ -779,6 +1236,9 @@ export class GhostteaTerminalRuntime extends EventTarget {
             cursor: rgb(theme.cursor),
         });
     }
+    setEffects(sessionHandle, effects, surfaceId) {
+        this.#postWorker({ type: "effects", sessionHandle, ...(surfaceId ? { surfaceId } : {}), effects });
+    }
     setSelection(sessionHandle, selection, surfaceId) {
         this.#postWorker({ type: "selection", sessionHandle, ...(surfaceId ? { surfaceId } : {}), selection });
     }
@@ -799,6 +1259,9 @@ export class GhostteaTerminalRuntime extends EventTarget {
         if (view) {
             view.desiredCols = cols;
             view.desiredRows = rows;
+            // An explicit claim is the funnel's outcome, not a competing path.
+            view.claimedEpoch = view.attachmentEpoch;
+            view.claimedRevision = this.#controlBySession.get(view.sessionId)?.revision ?? 0;
         }
         const session = this.#sessionByHandle.get(sessionHandle);
         if (!session)
@@ -812,7 +1275,7 @@ export class GhostteaTerminalRuntime extends EventTarget {
                 cols,
                 rows,
             });
-        });
+        }, true);
     }
     setFocused(sessionHandle, viewId, focused, cols, rows) {
         const view = this.#views.get(viewId);
@@ -820,8 +1283,13 @@ export class GhostteaTerminalRuntime extends EventTarget {
             view.desiredCols = cols;
             view.desiredRows = rows;
         }
-        if (this.#focusByView.get(viewId) === focused)
+        if (this.#focusByView.get(viewId) === focused) {
+            // Focus has not moved, so the claim below will not run — but an epoch or
+            // controller change since the last update may have made one possible,
+            // and nothing else would ever retry it after a resume.
+            this.#maybeReclaim(viewId);
             return;
+        }
         this.#focusByView.set(viewId, focused);
         this.#postWorker({ type: "focus", surfaceId: viewId, sessionHandle, focused });
         const session = this.#sessionByHandle.get(sessionHandle);
@@ -837,6 +1305,11 @@ export class GhostteaTerminalRuntime extends EventTarget {
                 focused,
             });
             if (focused) {
+                // Taking focus is a deliberate claim, and counts as this epoch's.
+                if (view) {
+                    view.claimedEpoch = attachmentEpoch;
+                    view.claimedRevision = this.#controlBySession.get(view.sessionId)?.revision ?? 0;
+                }
                 this.#control?.notify({
                     type: "focus-and-resize",
                     sessionId: session.id,
@@ -846,18 +1319,24 @@ export class GhostteaTerminalRuntime extends EventTarget {
                     rows,
                 });
             }
-        });
+        }, true);
     }
     async copySelection(sessionId, viewId, selection, selectAll = false) {
         await this.connect();
         const view = this.#views.get(viewId);
-        if (!view || view.sessionId !== sessionId || view.attachmentEpoch === undefined)
+        if (!view || view.sessionId !== sessionId)
+            return "";
+        // A frozen replica stays copyable: offline the daemon answers from the
+        // retained snapshot and authorizes by ownership, so the last epoch this
+        // view held is enough to name the attachment.
+        const attachmentEpoch = view.attachmentEpoch ?? view.lastAttachmentEpoch;
+        if (attachmentEpoch === undefined)
             return "";
         const response = await this.#control.request({
             type: "selection-text",
             sessionId,
             viewId,
-            attachmentEpoch: view.attachmentEpoch,
+            attachmentEpoch,
             startColumn: selection.anchor.column,
             startRow: selection.anchor.row,
             endColumn: selection.focus.column,
@@ -866,6 +1345,13 @@ export class GhostteaTerminalRuntime extends EventTarget {
         });
         if (response.type !== "selection-text")
             throw new Error("ghosttead returned an unexpected selection response");
+        // Offline the daemon can only reach the retained screen, so say so rather
+        // than letting a short copy read as the whole scrollback.
+        if (response.scope !== undefined) {
+            this.dispatchEvent(new CustomEvent("selection-scope", {
+                detail: { sessionId, viewId, scope: response.scope },
+            }));
+        }
         if (response.text)
             this.#platform.writeClipboard(response.text);
         return response.text;
@@ -920,6 +1406,9 @@ export class GhostteaTerminalRuntime extends EventTarget {
         }
         this.#sessionByHandle.delete(handle);
         this.#handleBySessionId.delete(sessionId);
+        this.#remoteSessions.delete(sessionId);
+        this.#controlBySession.delete(sessionId);
+        this.#recoveredSessions.delete(sessionId);
         if (subscriptionChanged) {
             this.#frameSubscriptionVersion += 1;
             this.#syncFrameSubscriptionsInBackground();
@@ -940,8 +1429,12 @@ export class GhostteaTerminalRuntime extends EventTarget {
             return;
         view.desiredCols = cols;
         view.desiredRows = rows;
-        if (view.attachmentEpoch === undefined || view.controlEpoch === undefined)
+        if (view.attachmentEpoch === undefined || view.controlEpoch === undefined) {
+            // Dimensions are one of the funnel's conditions: a pane that measured
+            // itself while uncontrolled may now be able to take control.
+            this.#maybeReclaim(viewId);
             return;
+        }
         this.#sendResize(viewId, view, cols, rows);
     }
     dispose() {
@@ -977,6 +1470,9 @@ export class GhostteaTerminalRuntime extends EventTarget {
         }
         this.#performanceRequests.clear();
         this.#views.clear();
+        this.#remoteSessions.clear();
+        this.#controlBySession.clear();
+        this.#recoveredSessions.clear();
         this.#focusByView.clear();
         this.#mountGenerationBySurface.clear();
         this.#mouseTrackingByHandle.clear();