@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/desktopControl/supervisor.js

@@ -0,0 +1,1774 @@
+import { DesktopMediaAdmissionCancelled } from './quicMedia.js';
+import { DesktopOverviewBudget, overviewPacket } from './overview.js';
+import { randomBytes } from 'node:crypto';
+import { decodeLobbyRequest, planLobby } from './lobby.js';
+import { setTimeout as dependencyDelay } from 'node:timers/promises';
+import { bounded, NativeCommandError } from './helperProcess.js';
+import { decodeMedia, mediaRequire, DesktopMediaFlowWindow, desktopMediaLane, DesktopDeliveryDelay, decodeConfig } from './media.js';
+import { DesktopRateController } from './rateController.js';
+import { AudioRateController, decodeAudio } from './audio.js';
+import { canonicalDesktopJson, encodeDesktopControl, decodeDesktopManagementFrame, DesktopProtocolError } from './protocol.js';
+const absoluteMotion = (message) => message.type === 'input' && message.payload.action === 'pointer';
+const diagnosticCodes = new Set(['invalid_request', 'unavailable', 'conflict', 'busy', 'rate_limited',
+    'authorization_lost', 'encoder_failed', 'resize_failed', 'transport_failed']);
+/** One authority owner and bounded management work queue; receive/heartbeat never await native I/O. */
+export class DesktopSessionSupervisor {
+    options;
+    get activeCount() { return Number(!!this.active && !this.active.retired) + this.candidates.size; }
+    generation;
+    active;
+    candidates = new Map();
+    tail = Promise.resolve();
+    pending = 0;
+    closed = false;
+    failedCleanup = false;
+    commands = new Map();
+    diagnosticId = 0;
+    lobbyJobs = 0;
+    lobbyContexts = new Map();
+    backgroundTail = Promise.resolve();
+    backgroundJobs = 0;
+    cleanupJobs = 0;
+    retainedSessions = new Map();
+    maintenance;
+    constructor(options) {
+        this.options = options;
+    }
+    async whenIdle(operation) {
+        if (this.closed || !this.generation || this.failedCleanup || this.maintenance || this.active || this.candidates.size ||
+            this.pending || this.cleanupJobs || this.lobbyJobs || this.backgroundJobs ||
+            [...this.lobbyContexts.values()].some(context => context.expires > Date.now()))
+            return false;
+        const maintenance = Promise.resolve().then(operation);
+        this.maintenance = maintenance;
+        try {
+            await maintenance;
+            return true;
+        }
+        finally {
+            if (this.maintenance === maintenance)
+                this.maintenance = undefined;
+        }
+    }
+    managementReady(generation) {
+        if (this.generation === generation)
+            return;
+        const previous = this.active;
+        this.generation = generation;
+        this.commands.clear();
+        this.clearLobbies();
+        if (previous) {
+            this.retire(previous);
+            void this.enqueue(() => this.cleanup(previous)).catch(() => { });
+        }
+        for (const candidate of [...this.candidates.values()]) {
+            this.retire(candidate);
+            void this.cleanup(candidate).catch(() => { });
+        }
+    }
+    managementClosed(generation) {
+        if (this.generation !== generation)
+            return;
+        this.generation = undefined;
+        this.clearLobbies();
+        const previous = this.active;
+        if (previous) {
+            this.retire(previous);
+            void this.enqueue(() => this.cleanup(previous)).catch(() => { });
+        }
+        for (const candidate of [...this.candidates.values()]) {
+            this.retire(candidate);
+            void this.cleanup(candidate).catch(() => { });
+        }
+    }
+    dispatch(frame, generation) {
+        if (this.maintenance)
+            return this.maintenance.catch(() => { }).then(() => this.dispatch(frame, generation));
+        if (generation !== this.generation)
+            return Promise.resolve();
+        if (frame.t === 'desktop_background')
+            return this.background(frame);
+        if (frame.t === 'desktop_lobby')
+            return this.planLobby(frame);
+        if (frame.t === 'desktop_prepare')
+            return this.prepare(frame);
+        if (frame.requireIsolation)
+            return this.isolate(frame, generation);
+        return this.cancel(frame.sessionId, { commandId: frame.commandId, deviceGeneration: generation, controlGeneration: frame.controlGeneration });
+    }
+    async isolate(frame, generation) {
+        const key = `${generation}:${frame.sessionId}:${frame.controlGeneration}`;
+        const retained = this.retainedSessions.get(key);
+        let isolated = false;
+        if (retained) {
+            this.retire(retained);
+            try {
+                await this.cleanup(retained);
+                isolated = true;
+            }
+            catch { }
+        }
+        if (this.generation === generation && !this.closed)
+            this.options.report(generation, {
+                t: 'desktop_isolation_result', commandId: frame.commandId, sessionId: frame.sessionId,
+                deviceGeneration: generation, controlGeneration: frame.controlGeneration, isolated,
+            });
+    }
+    background(frame) {
+        if (this.closed || frame.deviceGeneration !== this.generation || this.backgroundJobs >= 16)
+            return Promise.resolve();
+        this.backgroundJobs++;
+        const current = () => !this.closed && frame.deviceGeneration === this.generation &&
+            this.lobbyContexts.get(frame.lobbyId)?.commandId === frame.planId &&
+            (this.lobbyContexts.get(frame.lobbyId)?.expires ?? 0) > Date.now();
+        const next = this.backgroundTail.then(async () => {
+            if (!current() || !this.options.sockets.uploadWallpaper)
+                return;
+            try {
+                const wallpaper = this.options.provider.wallpaper ? await bounded(this.options.provider.wallpaper(frame.targetId, { width: frame.pixelWidth, height: frame.pixelHeight }), 8000) : null;
+                if (current())
+                    await this.options.sockets.uploadWallpaper(frame.grant, wallpaper, wallpaper?.asset.version === frame.cachedVersion);
+            }
+            catch {
+                if (current())
+                    await this.options.sockets.uploadWallpaper(frame.grant, null).catch(() => { });
+            }
+        });
+        this.backgroundTail = next.catch(() => { }).finally(() => { this.backgroundJobs--; });
+        return next;
+    }
+    async planLobby(frame) {
+        if (this.closed || frame.deviceGeneration !== this.generation || this.lobbyJobs >= 8)
+            return;
+        for (const [key, context] of this.lobbyContexts)
+            if (context.expires <= Date.now()) {
+                context.abort.abort();
+                this.lobbyContexts.delete(key);
+            }
+        if (!this.lobbyContexts.has(frame.lobbyId) && this.lobbyContexts.size >= 64)
+            return;
+        this.lobbyContexts.get(frame.lobbyId)?.abort.abort();
+        const context = { commandId: frame.commandId, abort: new AbortController(), expires: Date.now() + 30_000 };
+        this.lobbyContexts.set(frame.lobbyId, context);
+        const current = () => !this.closed && this.generation === frame.deviceGeneration &&
+            this.lobbyContexts.get(frame.lobbyId) === context && !context.abort.signal.aborted;
+        this.lobbyJobs++;
+        try {
+            const request = decodeLobbyRequest(JSON.stringify(frame.request));
+            const capabilities = await bounded(this.options.provider.probe(), 4000);
+            if (!current())
+                return;
+            mediaRequire(capabilities != null);
+            const plan = planLobby(request, capabilities, frame.lobbyId, frame.commandId, this.options.provider.automaticDpi ?? true);
+            const probeAbort = new AbortController();
+            const abortProbe = () => probeAbort.abort();
+            context.abort.signal.addEventListener('abort', abortProbe, { once: true });
+            const binding = { commandId: frame.commandId, sessionId: frame.lobbyId, displayId: plan.targetId,
+                deviceGeneration: frame.deviceGeneration, controlGeneration: request.revision, controlGrant: '' };
+            const verify = async (grant, quic) => {
+                let socket;
+                try {
+                    socket = await bounded(this.options.sockets.media({ ...binding, mediaTransport: quic ? 'quic' : 'wss' }, grant, probeAbort.signal, () => current() && !probeAbort.signal.aborted, quic), 2000);
+                }
+                catch { }
+                finally {
+                    socket?.close();
+                }
+            };
+            const probing = [frame.wssProbeGrant ? verify(frame.wssProbeGrant) : Promise.resolve(),
+                frame.quicProbeGrant && frame.quic ? verify(frame.quicProbeGrant, frame.quic) : Promise.resolve()];
+            void Promise.all(probing).finally(() => {
+                probeAbort.abort();
+                context.abort.signal.removeEventListener('abort', abortProbe);
+            });
+            if (current())
+                this.options.report(frame.deviceGeneration, { t: 'desktop_lobby_result', commandId: frame.commandId, lobbyId: frame.lobbyId,
+                    deviceGeneration: frame.deviceGeneration, plan, code: null });
+        }
+        catch {
+            if (current())
+                this.options.report(frame.deviceGeneration, { t: 'desktop_lobby_result', commandId: frame.commandId, lobbyId: frame.lobbyId,
+                    deviceGeneration: frame.deviceGeneration, plan: null, code: 'unavailable' });
+        }
+        finally {
+            this.lobbyJobs--;
+        }
+    }
+    clearLobbies() {
+        for (const context of this.lobbyContexts.values())
+            context.abort.abort();
+        this.lobbyContexts.clear();
+    }
+    enqueue(run) {
+        mediaRequire(this.pending < 16);
+        this.pending++;
+        const next = this.tail.then(run);
+        this.tail = next.catch(() => { }).finally(() => { this.pending--; });
+        return next;
+    }
+    preparationCurrent(binding) {
+        if (this.options.preparationCurrent)
+            return this.options.preparationCurrent(binding);
+        let begun = false;
+        return (beginEffect = false) => {
+            if (this.closed || binding.deviceGeneration !== this.generation || this.options.controllerCurrent?.(binding) === false)
+                throw new NativeCommandError('control_lost');
+            if (!begun && this.options.newWorkAllowed?.() === false)
+                return false;
+            if (beginEffect)
+                begun = true;
+            return true;
+        };
+    }
+    prepare(command) {
+        if (this.maintenance)
+            return this.maintenance.catch(() => { }).then(() => this.prepare(command));
+        decodeDesktopManagementFrame(JSON.stringify({ ...command, t: 'desktop_prepare' }), 'server');
+        if (this.closed || command.deviceGeneration !== this.generation)
+            return Promise.resolve();
+        if (this.options.newWorkAllowed?.() === false) {
+            this.options.report(command.deviceGeneration, { t: 'desktop_prepare_result', commandId: command.commandId, sessionId: command.sessionId, state: 'failed', code: 'busy' });
+            return Promise.resolve();
+        }
+        mediaRequire(this.pending < 16);
+        const key = `${command.deviceGeneration}:${command.commandId}`, serialized = canonicalDesktopJson(command);
+        const previousCommand = this.commands.get(key);
+        if (previousCommand) {
+            mediaRequire(previousCommand === serialized);
+            return Promise.resolve();
+        }
+        mediaRequire(this.commands.size < 1024);
+        this.commands.set(key, serialized);
+        mediaRequire(!command.candidate || this.candidates.size < 8);
+        const previous = command.candidate ? undefined : this.active;
+        const openingCurrent = previous ? this.preparationCurrent(command) : () => this.options.newWorkAllowed?.() !== false;
+        if (previous) {
+            if (!openingCurrent(true))
+                return Promise.resolve();
+            this.retire(previous);
+        }
+        const s = { diagnosticId: ++this.diagnosticId, diagnosticCount: 0, rateDiagnosticCount: 0, lastRateDiagnosticAt: -Infinity,
+            performanceDiagnosticCount: 0, lastPerformanceDiagnosticAt: -Infinity, diagnosticKey: randomBytes(16).toString('hex'), motionEncodeMs: 0,
+            binding: { ...command }, abort: new AbortController(), retired: false, viewerReady: false, starting: false,
+            startedEpoch: 0, decoderReady: false, presented: false, inputQueue: [], inputRunning: false, activeTasks: 0, commands: new Map(),
+            controller: new DesktopRateController({ fpsCeiling: 30, maxFps: 30 }), rateBusy: false, capturePaused: false, lastFeedbackBytes: 0,
+            activeBytes: 0, queuedAt: 0, lastPacketAt: performance.now(), receivedFrame: 0, firstCompleteFrame: 0, flow: new DesktopMediaFlowWindow(), delivery: new DesktopDeliveryDelay(), packetLoop: false, mediaWake: new Set(), nativeCreditDirty: false, nativeDisposed: { motion: 0, cursor: 0, exact: 0 }, configAdmittedEpoch: 0, recovery: [],
+            overviewBudget: new DesktopOverviewBudget(), overviewSequence: 0, overviewInitialPolls: 0, challenges: new Map(), rtts: [], rtt: 0, nextPing: performance.now() + 10000 };
+        mediaRequire(this.retainedSessions.size < 1024);
+        this.retainedSessions.set(`${command.deviceGeneration}:${command.sessionId}:${command.controlGeneration}`, s);
+        if (command.candidate)
+            this.candidates.set(s.binding.sessionId, s);
+        else
+            this.active = s;
+        const prepare = async () => {
+            if (previous)
+                await this.cleanup(previous);
+            if (!this.current(s))
+                return;
+            if (!openingCurrent()) {
+                this.options.report(command.deviceGeneration, { t: 'desktop_prepare_result', commandId: command.commandId, sessionId: command.sessionId, state: 'failed', code: 'busy' });
+                this.retire(s);
+                await this.cleanup(s);
+                return;
+            }
+            mediaRequire(!this.failedCleanup);
+            try {
+                // Discovery is side-effect free and independent of the authenticated socket attach.
+                const discovered = bounded(this.options.provider.probe(), 4000);
+                // Attach can fail first. Observe discovery's rejection until it is awaited below.
+                void discovered.catch(() => { });
+                const control = await bounded(this.options.sockets.control(s.binding, s.abort.signal, () => this.current(s)), 5000);
+                s.control = control;
+                if (!this.current(s)) {
+                    control.close();
+                    return;
+                }
+                const caps = await discovered;
+                if (!this.current(s))
+                    return;
+                if (caps && !caps.displays.some(display => display.id === command.displayId))
+                    this.options.refreshCapabilities?.(command.deviceGeneration);
+                mediaRequire(caps && caps.health === 'ready' && caps.displays.some(d => d.id === command.displayId));
+                this.options.report(command.deviceGeneration, { t: 'desktop_prepare_result', commandId: command.commandId, sessionId: command.sessionId, state: 'bound', code: null });
+                await this.send(s, { v: 1, type: 'offer', sessionId: command.sessionId, payload: caps });
+                void this.controlLoop(s);
+                s.timer = setInterval(() => {
+                    const backend = s.backend, configured = s.configured;
+                    void this.rateTick(s).catch(error => {
+                        if (this.current(s) && s.backend === backend && s.configured === configured) {
+                            this.diagnostic(s, 'rate_tick', error);
+                            return this.recover(s);
+                        }
+                    });
+                }, 100);
+                s.timer.unref();
+            }
+            catch (error) {
+                if (this.current(s)) {
+                    this.diagnostic(s, 'prepare', error);
+                    this.options.report(command.deviceGeneration, { t: 'desktop_prepare_result', commandId: command.commandId, sessionId: command.sessionId, state: 'failed', code: 'unavailable' });
+                    await this.fail(s);
+                }
+            }
+        };
+        return command.candidate ? prepare() : this.enqueue(prepare);
+    }
+    cancel(sessionId, identity) {
+        const s = this.active?.binding.sessionId === sessionId ? this.active : this.candidates.get(sessionId);
+        if (!s || s.binding.sessionId !== sessionId || identity && (identity.deviceGeneration !== s.binding.deviceGeneration || identity.controlGeneration !== s.binding.controlGeneration))
+            return Promise.resolve();
+        if (identity) {
+            const key = `${identity.deviceGeneration}:${identity.commandId}`, value = canonicalDesktopJson({ sessionId, ...identity });
+            const old = this.commands.get(key);
+            if (old) {
+                mediaRequire(old === value);
+                return Promise.resolve();
+            }
+            mediaRequire(this.commands.size < 1024);
+            this.commands.set(key, value);
+        }
+        this.retire(s);
+        return this.enqueue(() => this.cleanup(s));
+    }
+    current(s) {
+        return !this.closed && !s.retired &&
+            (this.active === s || this.candidates.get(s.binding.sessionId) === s) && this.generation === s.binding.deviceGeneration &&
+            (s.binding.candidate || this.options.controllerCurrent?.(s.binding) !== false);
+    }
+    diagnostic(s, origin, error, packet, command) {
+        // At most 16 fixed-shape records per session, before recovery resets its state.
+        // Never log error text/stacks, bindings, grants, input coordinates/text or media.
+        try {
+            if (s.diagnosticCount >= 16)
+                return;
+            const counters = s.backend?.nativeTelemetry;
+            const code = error instanceof NativeCommandError && diagnosticCodes.has(error.code) ? error.code :
+                error instanceof DesktopProtocolError ? 'protocol_invalid' : error === undefined ? 'none' : 'unexpected_error';
+            console.error(JSON.stringify({ event: 'desktop_supervisor_diagnostic', session: s.diagnosticId,
+                ordinal: ++s.diagnosticCount, origin, code, packet, command,
+                epoch: s.configured?.mediaEpoch ?? 0, startedEpoch: s.startedEpoch, receivedFrame: s.receivedFrame,
+                decoderReady: s.decoderReady, presented: s.presented, recovering: s.recovering === true,
+                activeTasks: s.activeTasks, queuedInputs: s.inputQueue.length, oldestInputMs: s.inputQueue.length ? Math.max(0, Math.round(performance.now() - s.inputQueue[0].at)) : 0, mediaAttached: !!s.media, inFlightBytes: s.flow.inFlightBytes,
+                queuedMs: s.queuedAt ? Math.max(0, Math.round(performance.now() - s.queuedAt)) : 0,
+                native: counters ? { epoch: counters.epoch, captured: counters.captured, encoded: counters.encoded,
+                    sentPayloadBytes: counters.sentPayloadBytes, pendingPayloadBytes: counters.pendingPayloadBytes,
+                    inputAvailable: counters.inputAvailable, pauseCapture: counters.pauseCapture } : undefined }));
+        }
+        catch { /* Diagnostics must not change recovery or cleanup. */ }
+    }
+    retire(s) {
+        if (this.candidates.get(s.binding.sessionId) === s)
+            this.candidates.delete(s.binding.sessionId);
+        s.retired = true;
+        s.inputQueue.length = 0;
+        s.abort.abort();
+        clearInterval(s.timer);
+        s.control?.close();
+        s.media?.close();
+        this.wakeMedia(s);
+        // Close native admission synchronously; waiting behind a dial/prepare must not
+        // postpone known-disconnect releases. Replacement still awaits this same result.
+        if (s.backend && !s.nativeCleanup) {
+            s.nativeCleanup = s.backend.stop();
+            void s.nativeCleanup.catch(() => { this.failedCleanup = true; });
+        }
+    }
+    cleanup(s) {
+        return s.cleanup ??= (async () => {
+            this.cleanupJobs++;
+            try {
+                this.retire(s);
+                try {
+                    const preparing = s.preparation ? await s.preparation.catch(() => undefined) : undefined;
+                    await (s.nativeCleanup ?? (s.backend ?? preparing)?.stop());
+                }
+                catch (error) {
+                    this.failedCleanup = true;
+                    throw error;
+                }
+                if (this.generation === s.binding.deviceGeneration && (s.backend || s.preparation))
+                    this.options.refreshCapabilities?.(s.binding.deviceGeneration);
+                if (this.active === s)
+                    this.active = undefined;
+            }
+            finally {
+                this.cleanupJobs--;
+            }
+        })();
+    }
+    async fail(s) {
+        if (!this.current(s))
+            return;
+        this.options.report(s.binding.deviceGeneration, { t: 'desktop_session_state', sessionId: s.binding.sessionId,
+            controlGeneration: s.binding.controlGeneration, state: 'FAILED', code: 'transport_failed' });
+        this.retire(s);
+        await this.cleanup(s);
+    }
+    async send(s, message) {
+        mediaRequire(this.current(s) && s.control);
+        await s.control.send(message);
+    }
+    async controlLoop(s) {
+        try {
+            for await (const message of s.control.messages) {
+                if (!this.current(s))
+                    return;
+                mediaRequire(message.sessionId === s.binding.sessionId);
+                if (message.type === 'input' || message.type === 'held_state' || message.type === 'clipboard_request') {
+                    this.scheduleInput(s, message);
+                    continue;
+                }
+                mediaRequire(s.activeTasks < 32);
+                s.activeTasks++;
+                // Each request rechecks its captured session after awaits. Text polling/media drain
+                // cannot prevent release, held snapshots or authenticated renewal from being read.
+                const receiving = message.type === 'audio_select' || message.type === 'audio_ready' || message.type === 'audio_feedback'
+                    ? (s.audioCommands = (s.audioCommands ?? Promise.resolve()).then(() => this.receive(s, message)))
+                    : this.receive(s, message);
+                void receiving.catch(error => {
+                    if (this.current(s))
+                        this.diagnostic(s, 'control_receive', error, undefined, message.type);
+                    return this.fail(s);
+                }).finally(() => { s.activeTasks--; });
+            }
+        }
+        catch (error) {
+            if (this.current(s))
+                this.diagnostic(s, 'control_stream', error);
+        }
+        if (this.current(s))
+            this.diagnostic(s, 'control_ended');
+        await this.fail(s);
+    }
+    scheduleInput(s, message) {
+        const last = s.inputQueue.at(-1)?.message;
+        const queued = { message, backend: s.backend, configured: s.configured, at: performance.now() };
+        // Replace only adjacent, unsent absolute positions in the same authority.
+        // Key/button/wheel/text, held snapshots and clipboard requests are barriers.
+        // One native operation is in flight: a delayed IPC reply cannot create an
+        // unbounded tail of obsolete positions or reorder a release behind a key.
+        if (last && absoluteMotion(last) && absoluteMotion(message) &&
+            last.payload.controlGeneration === message.payload.controlGeneration &&
+            'displayRevision' in last.payload && 'displayRevision' in message.payload &&
+            last.payload.displayRevision === message.payload.displayRevision) {
+            s.inputQueue[s.inputQueue.length - 1] = queued;
+        }
+        else {
+            mediaRequire(s.inputQueue.length < 128);
+            s.inputQueue.push(queued);
+        }
+        if (s.inputRunning)
+            return;
+        s.inputRunning = true;
+        void (async () => {
+            try {
+                while (this.current(s) && s.inputQueue.length) {
+                    const queued = s.inputQueue.shift();
+                    if (queued.backend === s.backend && queued.configured === s.configured)
+                        await this.receive(s, queued.message);
+                }
+            }
+            catch (error) {
+                if (this.current(s)) {
+                    this.diagnostic(s, 'control_receive', error);
+                    await this.fail(s);
+                }
+            }
+            finally {
+                s.inputRunning = false;
+            }
+        })();
+    }
+    async audioPackets(s, backend) {
+        if (!backend.audioPackets)
+            return;
+        try {
+            for await (const bytes of backend.audioPackets) {
+                if (!this.current(s) || s.backend !== backend)
+                    return;
+                const packet = decodeAudio(bytes);
+                if (!s.audioReady || !s.audioConfig || packet.epoch !== s.audioConfig.audioEpoch)
+                    continue;
+                const sendAudio = s.media?.sendAudio ?? s.control?.sendAudio;
+                if (sendAudio)
+                    await bounded(sendAudio(bytes), 80, 'audio_stale');
+            }
+        }
+        catch {
+            if (this.current(s) && s.backend === backend && s.audioConfig && s.audioCommand) {
+                s.audioConfig = undefined;
+                await backend.stopAudio?.().catch(() => { });
+                await this.send(s, { v: 1, type: 'audio_state', sessionId: s.binding.sessionId,
+                    payload: { commandId: s.audioCommand, state: 'unavailable', reason: 'audio_unavailable' } }).catch(() => { });
+            }
+        }
+        finally {
+            s.audioLoop = undefined;
+        }
+    }
+    async receive(s, message, resumeAudio = false) {
+        if (!this.current(s))
+            return;
+        if (resumeAudio && (message.type !== 'audio_select' || s.audioCommand !== message.payload.commandId || s.audioMode !== message.payload.mode))
+            return;
+        // A committed native resize can overtake already-forwarded control on the
+        // retained socket. Old geometry has no authority in the new epoch; discard
+        // it rather than retiring that healthy epoch or replaying held input there.
+        // Unbound/future geometry is also rejected without granting it authority or
+        // letting a single rejected command tear down the valid media session.
+        if (s.configured && (message.type === 'held_state' || message.type === 'input') &&
+            (message.payload.controlGeneration !== s.binding.controlGeneration ||
+                message.payload.displayRevision !== s.configured.displayRevision))
+            return;
+        if (message.type === 'focus' && s.configured &&
+            (message.payload.controlGeneration !== s.binding.controlGeneration ||
+                message.payload.mediaEpoch !== s.configured.mediaEpoch ||
+                message.payload.displayRevision !== s.configured.displayRevision))
+            return;
+        if (s.recovering && (message.type === 'held_state' || message.type === 'input')) {
+            mediaRequire(message.payload.controlGeneration === s.binding.controlGeneration &&
+                message.payload.displayRevision === s.configured?.displayRevision);
+            // The old helper is being stopped/verified. Valid messages already in flight
+            // cannot belong to the replacement and must never be replayed into it.
+            return;
+        }
+        if (message.type !== 'media_grant' && ['viewer_ready', 'decoder_ready', 'feedback', 'credit'].includes(message.type)) {
+            if (!s.backend || !s.configured)
+                return;
+            const epoch = 'epoch' in message.payload ? message.payload.epoch : 'mediaEpoch' in message.payload ? message.payload.mediaEpoch : undefined;
+            if (typeof epoch === 'number' && epoch < s.configured.mediaEpoch)
+                return;
+        }
+        if (message.type === 'media_grant') {
+            mediaRequire(message.controlGeneration === s.binding.controlGeneration && s.startCommand && !s.media && !s.mediaAttaching);
+            const attachment = Symbol('media_attachment'), backend = s.backend, configured = s.configured;
+            s.mediaAttaching = attachment;
+            s.flow = new DesktopMediaFlowWindow();
+            const bindingCurrent = () => this.current(s) && s.backend === backend && s.configured === configured;
+            const owns = () => bindingCurrent() && s.mediaAttaching === attachment;
+            let accepted;
+            const socketCurrent = () => accepted ? this.current(s) && s.media === accepted : owns();
+            try {
+                const media = await this.options.sockets.media(s.binding, message.grant, s.abort.signal, socketCurrent, message.quic);
+                if (!owns()) {
+                    media.close();
+                    return;
+                }
+                accepted = media;
+                s.media = media;
+                this.wakeMedia(s);
+                void media.closed?.then(() => {
+                    if (this.current(s) && s.media === media) {
+                        this.diagnostic(s, 'media_closed');
+                        void this.recover(s);
+                    }
+                });
+                if (media.cutEvents)
+                    void this.cutEvents(s, media).catch(error => { if (this.current(s) && s.media === media) {
+                        this.diagnostic(s, 'packet_loop', error);
+                        void this.fail(s);
+                    } });
+                await this.maybeStart(s);
+            }
+            catch (error) {
+                if (owns())
+                    throw error;
+            }
+            finally {
+                if (s.mediaAttaching === attachment)
+                    s.mediaAttaching = undefined;
+            }
+            return;
+        }
+        if (message.type === 'select' && this.options.newWorkAllowed?.() === false) {
+            await this.send(s, { v: 1, type: 'error', sessionId: s.binding.sessionId, payload: { code: 'busy', retryable: true } });
+            return;
+        }
+        if ('commandId' in message.payload && message.type !== 'audio_ready' && !message.type.startsWith('motion_cut_') && !(resumeAudio && message.type === 'audio_select')) {
+            const id = message.payload.commandId, body = canonicalDesktopJson(message);
+            const previous = s.commands.get(id);
+            if (previous) {
+                mediaRequire(previous === body);
+                return;
+            }
+            mediaRequire(s.commands.size < 1024);
+            s.commands.set(id, body);
+        }
+        switch (message.type) {
+            case 'motion_cut_prepare':
+                await this.prepareMotionCut(s, message.payload);
+                return;
+            case 'motion_cut_commit':
+                await this.commitMotionCut(s, message.payload);
+                return;
+            case 'cursor_visibility': {
+                let outcome = 'failed';
+                let fence = { mediaEpoch: 0, afterFrameId: 0 };
+                try {
+                    if (s.backend?.setCursorVisible) {
+                        fence = await s.backend.setCursorVisible(message.payload.visible);
+                        outcome = 'applied';
+                    }
+                }
+                catch { /* Report the failure without claiming visibility changed. */ }
+                if (this.current(s))
+                    await this.send(s, { v: 1, type: 'cursor_visibility_result', sessionId: s.binding.sessionId, payload: { ...message.payload, outcome, ...fence } });
+                return;
+            }
+            case 'appearance': {
+                let outcome = 'failed';
+                try {
+                    if (s.backend?.setAppearance) {
+                        await s.backend.setAppearance(message.payload.colorScheme);
+                        outcome = 'applied';
+                    }
+                }
+                catch { /* An appearance failure must not retire the video/input session. */ }
+                if (this.current(s))
+                    await this.send(s, { v: 1, type: 'appearance_result', sessionId: s.binding.sessionId,
+                        payload: { ...message.payload, outcome } });
+                return;
+            }
+            case 'select': {
+                const operationCurrent = this.preparationCurrent(s.binding);
+                const busy = async () => {
+                    if (s.commands.get(message.payload.commandId) === canonicalDesktopJson(message))
+                        s.commands.delete(message.payload.commandId);
+                    if (this.current(s))
+                        await this.send(s, { v: 1, type: 'error', sessionId: s.binding.sessionId, payload: { code: 'busy', retryable: true } });
+                };
+                if (this.candidates.get(s.binding.sessionId) === s && !await this.enqueue(async () => {
+                    mediaRequire(this.current(s));
+                    if (!operationCurrent())
+                        return false;
+                    const previous = this.active;
+                    if (previous) {
+                        if (!operationCurrent(true))
+                            return false;
+                        this.retire(previous);
+                        await this.cleanup(previous);
+                    }
+                    mediaRequire(this.current(s) && !this.failedCleanup);
+                    if (!operationCurrent())
+                        return false;
+                    this.candidates.delete(s.binding.sessionId);
+                    this.active = s;
+                    s.binding.candidate = false;
+                    return true;
+                })) {
+                    await busy();
+                    return;
+                }
+                if (!operationCurrent()) {
+                    await busy();
+                    return;
+                }
+                mediaRequire(!s.backend && !s.selection);
+                s.selection = message.payload;
+                s.configuredCommand = message.payload.commandId;
+                s.controller = new DesktopRateController({ fpsCeiling: message.payload.fpsCeiling, maxFps: message.payload.fpsCeiling });
+                s.preparation = this.options.provider.prepare(message.payload, s.binding, operationCurrent);
+                let backend;
+                try {
+                    backend = await s.preparation;
+                }
+                catch (error) {
+                    if (error instanceof NativeCommandError && error.code === 'busy') {
+                        if (s.selection === message.payload) {
+                            s.selection = undefined;
+                            s.configuredCommand = undefined;
+                            s.preparation = undefined;
+                        }
+                        await busy();
+                        return;
+                    }
+                    throw error;
+                }
+                if (!this.current(s)) {
+                    await backend.stop();
+                    return;
+                }
+                s.backend = backend;
+                void this.events(s, backend);
+                return;
+            }
+            case 'audio_select': {
+                const command = message.payload, backend = s.backend;
+                s.audioCommand = command.commandId;
+                s.audioMode = command.mode;
+                s.audioPolicy ??= new AudioRateController();
+                const bitrate = s.audioPolicy.select(command.mode);
+                try {
+                    if (command.mode === 'off') {
+                        s.audioConfig = undefined;
+                        s.audioFeedback = undefined;
+                        s.audioReady = false;
+                        s.control?.stopAudio?.();
+                        await backend?.stopAudio?.();
+                        if (this.current(s))
+                            await this.send(s, { v: 1, type: 'audio_state', sessionId: s.binding.sessionId, payload: { commandId: command.commandId, state: 'off', reason: null } });
+                        return;
+                    }
+                    if (!backend?.audioSupported || !backend.startAudio || !(s.media?.sendAudio ?? s.control?.sendAudio))
+                        throw new NativeCommandError('audio_unavailable');
+                    if (!s.media?.sendAudio)
+                        await s.control?.prepareAudio?.();
+                    if (!this.current(s) || s.audioCommand !== command.commandId)
+                        return;
+                    let configured = s.audioConfig;
+                    if (configured) {
+                        await backend.setAudioRate(bitrate);
+                        configured = { ...configured, commandId: command.commandId, bitrate };
+                    }
+                    else {
+                        s.audioReady = false;
+                        const audioEpoch = (s.audioEpoch ?? 0) + 1;
+                        s.audioEpoch = audioEpoch;
+                        const native = await backend.startAudio(audioEpoch, bitrate);
+                        configured = { ...native, commandId: command.commandId };
+                    }
+                    if (!this.current(s) || s.backend !== backend || s.audioCommand !== command.commandId)
+                        return;
+                    s.audioConfig = configured;
+                    s.audioFeedback = undefined;
+                    await this.send(s, { v: 1, type: 'audio_configured', sessionId: s.binding.sessionId, payload: configured });
+                    await this.send(s, { v: 1, type: 'audio_state', sessionId: s.binding.sessionId, payload: { commandId: command.commandId, state: 'buffering', reason: null } });
+                    s.audioLoop ??= this.audioPackets(s, backend);
+                }
+                catch {
+                    s.audioConfig = undefined;
+                    await backend?.stopAudio?.().catch(() => { });
+                    if (this.current(s))
+                        await this.send(s, { v: 1, type: 'audio_state', sessionId: s.binding.sessionId, payload: { commandId: command.commandId, state: 'unavailable', reason: 'audio_unavailable' } });
+                }
+                return;
+            }
+            case 'audio_ready': {
+                if (s.audioCommand === message.payload.commandId && s.audioConfig?.audioEpoch === message.payload.audioEpoch)
+                    s.audioReady = true;
+                return;
+            }
+            case 'audio_feedback': {
+                const value = message.payload, previous = s.audioFeedback;
+                if (!s.audioConfig || value.audioEpoch !== s.audioConfig.audioEpoch || !s.audioPolicy)
+                    return;
+                if (!previous) {
+                    s.audioFeedback = value;
+                    return;
+                }
+                if (value.receivedPackets < previous.receivedPackets || value.lostPackets < previous.lostPackets ||
+                    value.latePackets < previous.latePackets || value.underruns < previous.underruns)
+                    return;
+                s.audioFeedback = value;
+                const received = Math.max(0, value.receivedPackets - previous.receivedPackets), lost = Math.max(0, value.lostPackets - previous.lostPackets);
+                const late = Math.max(0, value.latePackets - previous.latePackets), total = received + lost;
+                const network = s.controller.diagnostics.networkState;
+                const bitrate = s.audioPolicy.observe(performance.now(), { queueMs: value.queueAgeMs, lateRatio: total ? late / total : 0,
+                    lostRatio: total ? lost / total : 0, underruns: Math.max(0, value.underruns - previous.underruns),
+                    congested: network === 'congested', headroom: network === 'usable' && total > 0 && lost === 0 && late === 0 });
+                if (bitrate !== s.audioConfig.bitrate && s.backend?.setAudioRate) {
+                    await s.backend.setAudioRate(bitrate);
+                    s.audioConfig = { ...s.audioConfig, bitrate };
+                    await this.send(s, { v: 1, type: 'audio_configured', sessionId: s.binding.sessionId, payload: s.audioConfig });
+                }
+                return;
+            }
+            case 'viewer_ready': {
+                this.ready(s, message.payload);
+                s.viewerReady = true;
+                await this.maybeStart(s);
+                return;
+            }
+            case 'start': {
+                mediaRequire(s.configured && s.viewerReady);
+                s.startCommand = message.payload.commandId;
+                await this.maybeStart(s);
+                return;
+            }
+            case 'credit': {
+                // The relay's initial credit can overtake viewer readiness and START on
+                // the retained control socket. This only funds the bound transport hop;
+                // returnNativeCredit still requires this epoch's actual capture START.
+                mediaRequire(s.configured && message.payload.epoch === s.configured.mediaEpoch &&
+                    (s.media || s.mediaAttaching));
+                s.flow.credit(message.payload);
+                s.lastPacketAt = performance.now();
+                this.wakeMedia(s);
+                this.returnNativeCredit(s);
+                return;
+            }
+            case 'decoder_ready': {
+                this.ready(s, message.payload);
+                mediaRequire(s.backend && s.codec && s.startedEpoch === s.configured.mediaEpoch && s.media);
+                const backend = s.backend, configured = s.configured;
+                s.decoderAcknowledgement = backend.decoderReady({ ...message.payload, representation: s.codec.representation, parameterSets: s.codec.parameterSets });
+                await s.decoderAcknowledgement;
+                if (this.current(s) && s.backend === backend && s.configured === configured)
+                    s.decoderReady = true;
+                return;
+            }
+            case 'feedback': {
+                const f = message.payload;
+                // Feedback is an observation, not authority to retire capture or input.
+                // A fast receiver can report before send() settles; old observations can
+                // also cross a configuration/cut. Leave accepted counters intact and wait
+                // for the next current observation instead of black-screening the owner.
+                if (!(s.backend && s.configured && f.epoch === s.configured.mediaEpoch &&
+                    f.presentedId <= s.receivedFrame && f.receivedId <= s.receivedFrame && f.receivedTotalBytes >= s.lastFeedbackBytes &&
+                    (!s.feedback || f.presentedId >= s.feedback.presentedId && f.decodedId >= s.feedback.decodedId && f.receivedId >= s.feedback.receivedId && f.exactPresentedSequence >= s.feedback.exactPresentedSequence)))
+                    return;
+                const previousExactPresented = s.feedback?.exactPresentedSequence ?? 0;
+                const backend = s.backend, configured = s.configured;
+                const observedAt = performance.now();
+                if (f.receivedTotalBytes > s.lastFeedbackBytes || f.receivedId > (s.feedback?.receivedId ?? 0))
+                    s.feedbackProgressAt = observedAt;
+                if (f.decodedId > (s.feedback?.decodedId ?? 0))
+                    s.decodeObservedAt = observedAt;
+                s.feedback = f;
+                s.lastFeedbackBytes = f.receivedTotalBytes;
+                s.delivery.received(f.receivedId, performance.now());
+                if (s.firstCompleteFrame > 0 && f.presentedId >= s.firstCompleteFrame && !s.presented) {
+                    const backend = s.backend, configured = s.configured;
+                    mediaRequire(s.decoderReady);
+                    const acknowledgement = s.presentationAcknowledgement ??= backend.firstPresented({ epoch: f.epoch, frameId: f.presentedId });
+                    try {
+                        await acknowledgement;
+                    }
+                    catch (error) {
+                        if (this.current(s) && s.backend === backend && s.configured === configured)
+                            throw error;
+                        return;
+                    }
+                    if (this.current(s) && s.backend === backend && s.configured === configured) {
+                        s.presented = true;
+                        // The Server has committed this geometry; publishing during negotiation
+                        // would invalidate the capability snapshot that authorized the attempt.
+                        this.options.refreshCapabilities?.(s.binding.deviceGeneration);
+                    }
+                }
+                if (f.exactPresentedSequence > previousExactPresented && this.current(s) && s.backend === backend &&
+                    s.configured === configured && s.presented) {
+                    await backend.acknowledge?.({ epoch: f.epoch, exactSequence: f.exactPresentedSequence });
+                }
+                return;
+            }
+            case 'clipboard_request': {
+                mediaRequire(s.backend?.clipboard && message.payload.controlGeneration === s.binding.controlGeneration);
+                const backend = s.backend, configured = s.configured;
+                if (!s.presented) {
+                    const acknowledgement = s.presentationAcknowledgement;
+                    mediaRequire(acknowledgement);
+                    try {
+                        await acknowledgement;
+                    }
+                    catch (error) {
+                        if (this.current(s) && s.backend === backend && s.configured === configured &&
+                            s.presentationAcknowledgement === acknowledgement)
+                            throw error;
+                        return;
+                    }
+                    if (!this.current(s) || s.backend !== backend || s.configured !== configured ||
+                        s.presentationAcknowledgement !== acknowledgement)
+                        return;
+                    mediaRequire(s.presented);
+                }
+                const result = await backend.clipboard(message.payload);
+                if (this.current(s) && s.backend === backend && s.configured === configured)
+                    await this.send(s, { v: 1, type: 'clipboard_result', sessionId: s.binding.sessionId, payload: result });
+                return;
+            }
+            case 'input': {
+                const backend = s.backend, configured = s.configured;
+                mediaRequire(backend);
+                if (!s.presented && message.payload.action !== 'release_all') {
+                    // Feedback already arrived on this ordered socket; its native commit
+                    // may still be awaiting IPC. Never admit before that exact commit.
+                    const acknowledgement = s.presentationAcknowledgement;
+                    mediaRequire(acknowledgement);
+                    try {
+                        await acknowledgement;
+                    }
+                    catch (error) {
+                        if (this.current(s) && s.backend === backend && s.configured === configured &&
+                            s.presentationAcknowledgement === acknowledgement)
+                            throw error;
+                        return;
+                    }
+                    if (!this.current(s) || s.backend !== backend || s.configured !== configured ||
+                        s.presentationAcknowledgement !== acknowledgement)
+                        return;
+                    mediaRequire(s.presented);
+                }
+                const result = await backend.input(message.payload);
+                if (this.current(s) && s.backend === backend && s.configured === configured)
+                    await this.send(s, { v: 1, type: 'input_result', sessionId: s.binding.sessionId, payload: result });
+                return;
+            }
+            case 'held_state': {
+                mediaRequire(s.backend && message.payload.controlGeneration === s.binding.controlGeneration && message.payload.displayRevision === s.configured?.displayRevision);
+                await s.backend.heldState(message.payload);
+                return;
+            }
+            case 'pong': {
+                const challenge = s.challenges.get(message.payload.challenge);
+                if (challenge) {
+                    if (!challenge.answered) {
+                        challenge.answered = true;
+                        s.rtt = Math.max(0, performance.now() - challenge.at);
+                        s.rtts.push(s.rtt);
+                        if (s.rtts.length > 60)
+                            s.rtts.shift();
+                    }
+                }
+                else if (s.backend)
+                    await s.backend.renewAuthenticatedLease({ leaseMs: 30000 });
+                return;
+            }
+            case 'ping': {
+                await this.send(s, { ...message, type: 'pong' });
+                return;
+            }
+            case 'cache_dependency': {
+                const request = message.payload, backend = s.backend, configured = s.configured;
+                mediaRequire(backend?.cacheDependency && backend.reserveOverview && request.controlGeneration === s.binding.controlGeneration &&
+                    request.mediaEpoch === configured?.mediaEpoch && request.displayRevision === configured.displayRevision);
+                let pixels;
+                try {
+                    pixels = await backend.cacheDependency(request);
+                }
+                catch (error) {
+                    if (!this.current(s) || s.backend !== backend || s.configured !== configured || backend.epoch !== undefined && backend.epoch !== request.mediaEpoch)
+                        return;
+                    throw error;
+                }
+                const result = { v: 1, type: 'cache_dependency_result', sessionId: s.binding.sessionId, payload: { request, pixels } };
+                const wireBytes = Buffer.byteLength(encodeDesktopControl(result)) + 8, deadline = performance.now() + 4000;
+                while (this.current(s) && s.backend === backend && s.configured === configured && (backend.epoch === undefined || backend.epoch === request.mediaEpoch)) {
+                    if (await backend.reserveOverview({ epoch: request.mediaEpoch, wireBytes })) {
+                        if (this.current(s) && s.backend === backend && s.configured === configured)
+                            await this.send(s, result);
+                        return;
+                    }
+                    mediaRequire(performance.now() < deadline);
+                    await dependencyDelay(10);
+                }
+                return;
+            }
+            case 'focus': {
+                const request = message.payload;
+                mediaRequire(s.backend?.focus && request.controlGeneration === s.binding.controlGeneration &&
+                    request.mediaEpoch === s.configured?.mediaEpoch && request.displayRevision === s.configured.displayRevision);
+                const backend = s.backend, configured = s.configured;
+                if (!s.presented) {
+                    const acknowledgement = s.presentationAcknowledgement;
+                    // Navigation crossing a configuration is obsolete. A valid first-frame
+                    // acknowledgement already in flight, however, precedes this command.
+                    if (!acknowledgement)
+                        return;
+                    try {
+                        await acknowledgement;
+                    }
+                    catch (error) {
+                        if (this.current(s) && s.backend === backend && s.configured === configured)
+                            throw error;
+                        return;
+                    }
+                    if (!this.current(s) || s.backend !== backend || s.configured !== configured ||
+                        s.presentationAcknowledgement !== acknowledgement || !s.presented)
+                        return;
+                }
+                const owns = () => this.current(s) && s.backend === backend && s.configured === configured &&
+                    (backend.epoch === undefined || backend.epoch === request.mediaEpoch);
+                let result;
+                try {
+                    result = await backend.focus(request.focus);
+                }
+                catch (error) {
+                    if (owns())
+                        throw error;
+                    return;
+                }
+                if (owns())
+                    await this.send(s, { v: 1, type: 'focus_result', sessionId: s.binding.sessionId, payload: { ...request, ...result } });
+                return;
+            }
+            case 'resize':
+            case 'request_refresh': {
+                mediaRequire(s.backend);
+                // A viewer command may cross an automatic media_open already in flight.
+                // The viewer retains its choice and retries after that epoch is presented.
+                if (s.automaticConfiguration)
+                    return;
+                if (!s.presented && s.presentationAcknowledgement) {
+                    const backend = s.backend, configured = s.configured, acknowledgement = s.presentationAcknowledgement;
+                    try {
+                        await acknowledgement;
+                    }
+                    catch (error) {
+                        if (this.current(s) && s.backend === backend && s.configured === configured &&
+                            s.presentationAcknowledgement === acknowledgement)
+                            throw error;
+                        return;
+                    }
+                    if (!this.current(s) || s.backend !== backend || s.configured !== configured ||
+                        s.presentationAcknowledgement !== acknowledgement)
+                        return;
+                }
+                if (!s.presented)
+                    return;
+                // The old stream must finish its credited writes before native can commit
+                // the new configuration. Input closes now; decoder/START retire at CONFIG.
+                s.viewerReady = false;
+                s.presented = false;
+                s.configuredCommand = message.payload.commandId;
+                s.backend?.configurationCommand?.(message.payload.commandId);
+                if (message.type === 'resize') {
+                    mediaRequire(message.payload.expectedDisplayRevision === s.configured?.displayRevision);
+                    const result = await s.backend.resize({ width: message.payload.width, height: message.payload.height,
+                        ...(message.payload.dpi === undefined ? {} : { dpi: message.payload.dpi }),
+                        ...(message.payload.captureRegion === undefined ? {} : { captureRegion: message.payload.captureRegion }) });
+                    if (this.current(s))
+                        await this.send(s, { v: 1, type: 'resize_result', sessionId: s.binding.sessionId, payload: { ...result, commandId: message.payload.commandId } });
+                }
+                else
+                    await s.backend.refresh();
+                return;
+            }
+            case 'stop':
+            case 'suspend':
+            case 'resume': {
+                this.retire(s);
+                await this.cleanup(s);
+                return;
+            }
+            case 'error': {
+                this.diagnostic(s, 'viewer_error');
+                await this.fail(s);
+                return;
+            }
+            case 'state': {
+                if (['FAILED', 'CLOSED', 'SUSPENDED'].includes(message.payload.state)) {
+                    this.diagnostic(s, 'viewer_state');
+                    this.retire(s);
+                    await this.cleanup(s);
+                }
+                return;
+            }
+            default: throw new Error('invalid_request');
+        }
+    }
+    ready(s, value) {
+        mediaRequire(s.configured && value.controlGeneration === s.binding.controlGeneration && value.mediaEpoch === s.configured.mediaEpoch && value.displayRevision === s.configured.displayRevision);
+    }
+    async maybeStart(s) {
+        if (!this.current(s) || !s.backend || !s.configured || !s.viewerReady || !s.startCommand || !s.media || s.starting || s.startedEpoch === s.configured.mediaEpoch)
+            return;
+        const configured = s.configured, epoch = configured.mediaEpoch, backend = s.backend;
+        if (backend.epoch !== undefined && backend.epoch !== epoch)
+            return;
+        s.starting = true;
+        // START is authorized. The persistent reader can receive CONFIG before
+        // the helper acknowledges start, so publish the permitted epoch first.
+        s.startedEpoch = epoch;
+        try {
+            await backend.start();
+            if (!this.current(s) || s.backend !== backend || s.configured !== configured)
+                return;
+            s.startedEpoch = epoch;
+            // Independent bounded hop: grant one initial native window, then replenish each
+            // fragment only after the actual device WS send callback, never after decode/present.
+            this.returnNativeCredit(s);
+            if (!this.current(s) || s.backend !== backend || s.configured !== configured || s.startedEpoch !== epoch)
+                return;
+            s.lastPacketAt = performance.now();
+            if (!s.packetLoop) {
+                s.packetLoop = true;
+                void this.packets(s);
+            }
+            if (s.audioMode && s.audioMode !== 'off' && s.audioCommand && !s.audioConfig) {
+                const mode = s.audioMode, commandId = s.audioCommand;
+                s.audioCommands = (s.audioCommands ?? Promise.resolve()).then(() => this.receive(s, { v: 1, type: 'audio_select',
+                    sessionId: s.binding.sessionId, payload: { commandId, mode } }, true)).catch(() => { });
+            }
+        }
+        catch (error) {
+            if (this.current(s) && s.backend === backend && s.configured === configured)
+                throw error;
+        }
+        finally {
+            if (s.backend === backend && s.configured === configured)
+                s.starting = false;
+        }
+    }
+    async events(s, backend) {
+        try {
+            for await (const event of backend.events) {
+                if (!this.current(s) || s.backend !== backend)
+                    return;
+                if (event.type === 'configured') {
+                    const cfg = event.configured;
+                    mediaRequire(cfg.deviceGeneration === s.binding.deviceGeneration && cfg.controlGeneration === s.binding.controlGeneration && cfg.commandId === s.configuredCommand);
+                    if (s.automaticConfiguration === cfg.commandId) {
+                        await this.send(s, { v: 1, type: 'media_open', sessionId: s.binding.sessionId, payload: { commandId: cfg.commandId } });
+                        if (!this.current(s) || s.backend !== backend)
+                            return;
+                        const oldMedia = s.media;
+                        s.media = undefined;
+                        oldMedia?.close();
+                        s.startCommand = undefined;
+                        s.automaticConfiguration = undefined;
+                    }
+                    s.configured = cfg;
+                    s.codec = undefined;
+                    s.viewerReady = false;
+                    s.decoderReady = false;
+                    s.decoderAcknowledgement = undefined;
+                    s.presented = false;
+                    if (s.selection)
+                        s.selection = { ...s.selection, captureRegion: cfg.captureRegion, width: cfg.width, height: cfg.height,
+                            ...(cfg.dpi === undefined ? {} : { dpi: cfg.dpi }) };
+                    s.startCommand = undefined;
+                    s.mediaAttaching = undefined;
+                    s.startedEpoch = 0;
+                    s.starting = false;
+                    s.firstCompleteFrame = 0;
+                    s.receivedFrame = 0;
+                    s.presentationAcknowledgement = undefined;
+                    s.flow = new DesktopMediaFlowWindow();
+                    s.configAdmittedEpoch = 0;
+                    s.nativeAdvertised = undefined;
+                    s.nativeDisposed = { motion: 0, cursor: 0, exact: 0 };
+                    s.motionCut = undefined;
+                    s.cutRequest = undefined;
+                    s.untrustedCut = undefined;
+                    this.wakeMedia(s);
+                    // Picture and exact presentation watermarks belong to this media epoch.
+                    // Keep lastFeedbackBytes: receivedTotalBytes is cumulative for the connection.
+                    s.feedback = undefined;
+                    s.feedbackProgressAt = undefined;
+                    s.decodeObservedAt = undefined;
+                    s.motionEncodeObservedAt = undefined;
+                    s.motionEncodeKey = undefined;
+                    s.motionEncodeMs = 0;
+                    s.delivery = new DesktopDeliveryDelay();
+                    s.capturePaused = false;
+                    s.recovering = false;
+                    await this.send(s, { v: 1, type: 'configured', sessionId: s.binding.sessionId, payload: cfg });
+                }
+                else if (event.type === 'failed') {
+                    this.diagnostic(s, 'backend_failed', new NativeCommandError(event.code));
+                    await this.recover(s);
+                }
+                else if (event.type === 'recovery' && !event.result.verified) {
+                    this.diagnostic(s, 'backend_recovery_unverified');
+                    await this.fail(s);
+                }
+            }
+        }
+        catch (error) {
+            if (this.current(s) && s.backend === backend) {
+                this.diagnostic(s, 'backend_events', error);
+                await this.fail(s);
+            }
+        }
+    }
+    cutBinding(s, p) {
+        return this.current(s) && p.controlGeneration === s.binding.controlGeneration && p.mediaEpoch === s.configured?.mediaEpoch && p.displayRevision === s.configured.displayRevision && s.startedEpoch === p.mediaEpoch && !s.recovering;
+    }
+    async cutEvents(s, media) {
+        for await (const event of media.cutEvents) {
+            if (!this.current(s) || s.media !== media)
+                return;
+            if (event.epoch < (s.configured?.mediaEpoch ?? 0))
+                continue;
+            mediaRequire(event.epoch === s.configured?.mediaEpoch);
+            if (event.action === 1) {
+                if (s.motionCut?.phase === 'committed' && event.cutId < s.motionCut.payload.cutId)
+                    continue;
+                if (s.presented && s.decoderReady && !s.recovering && !s.cutRequest && (!s.motionCut || s.motionCut.phase === 'committed')) {
+                    const commandId = randomBytes(16).toString('hex');
+                    s.cutRequest = commandId;
+                    await this.send(s, { v: 1, type: 'motion_cut_request', sessionId: s.binding.sessionId, payload: { commandId, controlGeneration: s.binding.controlGeneration, mediaEpoch: event.epoch, displayRevision: s.configured.displayRevision } });
+                }
+            }
+            else if (event.action === 2) {
+                // A transport proposal is untrusted until the coordinator's matching control transaction.
+                mediaRequire(!s.untrustedCut || canonicalDesktopJson(s.untrustedCut) === canonicalDesktopJson(event));
+                s.untrustedCut = event;
+            }
+            else if (event.action === 4 || event.action === 5) {
+                const cut = s.motionCut;
+                mediaRequire(cut && cut.fence && event.cutId === cut.payload.cutId && event.epoch === cut.payload.mediaEpoch && event.pictureThrough === cut.fence.pictureThrough && event.frameThrough === cut.fence.frameThrough);
+                if (event.action === 4)
+                    cut.acked = true;
+                else {
+                    mediaRequire(cut.phase === 'committing' && cut.acked);
+                    cut.resumed = true;
+                }
+                this.wakeMedia(s);
+            }
+            else if (event.action === 6)
+                throw new NativeCommandError('transport_failed');
+        }
+    }
+    async prepareMotionCut(s, payload) {
+        mediaRequire(this.cutBinding(s, payload) && s.presented && s.backend?.prepareMotionCut && s.backend.settleMotionCut && s.backend.mediaDisposed && s.backend.commitMotionCut && s.media);
+        let cut = s.motionCut;
+        if (cut && cut.payload.cutId === payload.cutId) {
+            mediaRequire(canonicalDesktopJson(cut.payload) === canonicalDesktopJson(payload));
+            if (cut.preparing)
+                await cut.preparing;
+        }
+        else {
+            mediaRequire(!cut || cut.phase === 'committed' && payload.cutId > cut.payload.cutId);
+            cut = { payload, phase: 'preparing', acked: false, resumed: false };
+            s.motionCut = cut;
+            this.wakeMedia(s);
+            const owner = cut, backend = s.backend, media = s.media;
+            cut.preparing = (async () => {
+                const fence = await backend.prepareMotionCut({ epoch: payload.mediaEpoch, cutId: payload.cutId });
+                mediaRequire(this.cutBinding(s, payload) && s.backend === backend && s.media === media && s.motionCut === owner && fence.epoch === payload.mediaEpoch && fence.cutId === payload.cutId);
+                owner.fence = fence;
+                this.wakeMedia(s);
+                if (media.cutCommand)
+                    await media.cutCommand(9, payload.cutId, payload.mediaEpoch, fence.pictureThrough, fence.frameThrough);
+                await backend.settleMotionCut(fence);
+                mediaRequire(this.cutBinding(s, payload) && s.backend === backend && s.media === media && s.motionCut === owner);
+                if (!media.cutCommand) {
+                    mediaRequire(media.sendCutBarrier);
+                    await media.sendCutBarrier({ v: 1, type: 'motion_cut_barrier', sessionId: s.binding.sessionId, payload: { ...payload, pictureThrough: fence.pictureThrough, frameThrough: fence.frameThrough } });
+                }
+                owner.phase = 'prepared';
+            })();
+            await cut.preparing;
+            cut.preparing = undefined;
+        }
+        mediaRequire(this.cutBinding(s, payload) && cut.fence);
+        await this.send(s, { v: 1, type: 'motion_cut_prepared', sessionId: s.binding.sessionId, payload: { ...payload, pictureThrough: cut.fence.pictureThrough, frameThrough: cut.fence.frameThrough } });
+    }
+    async commitMotionCut(s, payload) {
+        const cut = s.motionCut, backend = s.backend, media = s.media;
+        mediaRequire(this.cutBinding(s, payload) && cut && canonicalDesktopJson(cut.payload) === canonicalDesktopJson(payload) && backend?.commitMotionCut && media);
+        if (cut.phase === 'committed')
+            return;
+        if (cut.committing) {
+            await cut.committing;
+            return;
+        }
+        cut.committing = (async () => {
+            if (cut.preparing)
+                await cut.preparing;
+            mediaRequire(cut.phase === 'prepared');
+            cut.phase = 'committing';
+            if (media.cutCommand) {
+                while (!cut.acked) {
+                    mediaRequire(this.cutBinding(s, payload) && s.media === media);
+                    await this.waitMedia(s);
+                }
+                await media.cutCommand(11, payload.cutId, payload.mediaEpoch);
+                while (!cut.resumed) {
+                    mediaRequire(this.cutBinding(s, payload) && s.media === media);
+                    await this.waitMedia(s);
+                }
+            }
+            mediaRequire(this.cutBinding(s, payload) && s.backend === backend && s.media === media);
+            await backend.commitMotionCut({ epoch: payload.mediaEpoch, cutId: payload.cutId });
+            mediaRequire(this.cutBinding(s, payload) && s.backend === backend && s.media === media);
+            media.finishCut?.(payload.cutId);
+            cut.phase = 'committed';
+            s.cutRequest = undefined;
+            s.untrustedCut = undefined;
+            this.wakeMedia(s);
+        })();
+        await cut.committing;
+    }
+    disposeMotion(s, backend, packet, cut) {
+        mediaRequire(cut.fence && packet.type === 2 && packet.epoch === cut.payload.mediaEpoch && packet.sequence <= cut.fence.pictureThrough && backend.mediaDisposed);
+        backend.mediaDisposed(packet, cut.fence);
+        s.nativeDisposed.motion += packet.payload.length;
+        mediaRequire(Number.isSafeInteger(s.nativeDisposed.motion));
+        this.returnNativeCredit(s);
+        this.wakeMedia(s);
+    }
+    wakeMedia(s) { for (const wake of [...s.mediaWake])
+        wake(); }
+    async waitMedia(s) {
+        let wake;
+        const waiting = new Promise(resolve => { wake = resolve; s.mediaWake.add(wake); });
+        try {
+            await waiting;
+        }
+        finally {
+            s.mediaWake.delete(wake);
+        }
+    }
+    returnNativeCredit(s) {
+        s.nativeCreditDirty = true;
+        if (s.nativeCreditRunning)
+            return;
+        const task = (async () => {
+            while (this.current(s) && s.nativeCreditDirty) {
+                s.nativeCreditDirty = false;
+                const backend = s.backend, configured = s.configured, flow = s.flow;
+                if (!backend?.credit || !configured || s.startedEpoch !== configured.mediaEpoch || !flow.hasCredit)
+                    continue;
+                const value = { epoch: configured.mediaEpoch, ...flow.appliedCredit };
+                value.motionConsumedBytes += s.nativeDisposed.motion;
+                value.cursorConsumedBytes += s.nativeDisposed.cursor;
+                value.exactConsumedBytes += s.nativeDisposed.exact;
+                if (s.nativeAdvertised && canonicalDesktopJson(s.nativeAdvertised) === canonicalDesktopJson(value))
+                    continue;
+                try {
+                    await backend.credit(value);
+                }
+                catch (error) {
+                    if (this.current(s) && s.backend === backend && s.configured === configured) {
+                        this.diagnostic(s, 'packet_loop', error, { stage: 'native_credit', type: 0, sequence: 0, payloadBytes: 0 });
+                        await this.recover(s);
+                    }
+                    return;
+                }
+                if (this.current(s) && s.backend === backend && s.configured === configured && s.flow === flow)
+                    s.nativeAdvertised = value;
+            }
+        })();
+        s.nativeCreditRunning = task;
+        void task.finally(() => { if (s.nativeCreditRunning === task) {
+            s.nativeCreditRunning = undefined;
+            if (s.nativeCreditDirty && this.current(s))
+                this.returnNativeCredit(s);
+        } }).catch(() => { });
+    }
+    async packets(s) {
+        const backend = s.backend;
+        const queues = { motion: [], cursor: [], exact: [] };
+        const active = new Map();
+        let queuedBytes = 0, ended = false, failed = false, nextId = 0;
+        const current = () => this.current(s) && s.backend === backend;
+        const queuedCount = () => queues.motion.length + queues.cursor.length + queues.exact.length;
+        const updateAge = () => { if (!current())
+            return; s.queuedAt = Math.min(...[...active.values(), ...queues.motion, ...queues.cursor, ...queues.exact].map(r => r.at), Infinity); if (s.queuedAt === Infinity)
+            s.queuedAt = 0; };
+        const fail = async (error, p, stage = 'native_read') => {
+            if (failed || !current())
+                return;
+            failed = true;
+            ended = true;
+            this.wakeMedia(s);
+            this.diagnostic(s, 'packet_loop', error, { stage, type: p?.type ?? 0, sequence: p?.sequence ?? 0, payloadBytes: p?.payload.length ?? 0 });
+            await this.recover(s);
+        };
+        const worker = async (lane) => {
+            let packet, stage = 'native_read';
+            try {
+                while (current() && !failed) {
+                    const record = queues[lane][0];
+                    if (!record) {
+                        if (ended)
+                            return;
+                        await this.waitMedia(s);
+                        continue;
+                    }
+                    packet = record.p;
+                    if (lane === 'motion' && packet.type === 2) {
+                        while (current() && !failed && s.motionCut?.phase === 'preparing' && !s.motionCut.fence)
+                            await this.waitMedia(s);
+                        const cut = s.motionCut;
+                        if (cut?.fence && packet.epoch === cut.payload.mediaEpoch && packet.sequence <= cut.fence.pictureThrough) {
+                            queues[lane].shift();
+                            queuedBytes -= packet.payload.length;
+                            this.disposeMotion(s, backend, packet, cut);
+                            updateAge();
+                            continue;
+                        }
+                    }
+                    const configured = s.configured, flow = s.flow;
+                    mediaRequire(configured && packet.epoch === configured.mediaEpoch && packet.displayRevision === configured.displayRevision && s.startedEpoch === packet.epoch);
+                    if (packet.type !== 1) {
+                        while (current() && !failed && s.configAdmittedEpoch !== packet.epoch)
+                            await this.waitMedia(s);
+                        stage = 'decoder_wait';
+                        if ((packet.type === 2 || packet.type === 5) && !s.decoderReady && s.decoderAcknowledgement)
+                            await s.decoderAcknowledgement;
+                        mediaRequire(s.codec && ((packet.type !== 2 && packet.type !== 5) || s.decoderReady));
+                    }
+                    stage = 'credit_wait';
+                    while (current() && !failed && (!s.media || !flow.admit(lane, packet.payload.length)))
+                        await this.waitMedia(s);
+                    if (!current() || failed)
+                        return;
+                    const media = s.media;
+                    mediaRequire(media && s.configured === configured && s.flow === flow);
+                    const id = ++nextId;
+                    mediaRequire(flow.reserve(id, lane, packet.payload.length));
+                    queues[lane].shift();
+                    queuedBytes -= packet.payload.length;
+                    active.set(lane, record);
+                    updateAge();
+                    stage = 'send';
+                    try {
+                        await media.send(record.bytes);
+                    }
+                    catch (error) {
+                        flow.cancel(id);
+                        const cut = s.motionCut;
+                        if (error instanceof DesktopMediaAdmissionCancelled && current() && s.media === media && cut?.fence && error.cutId === cut.payload.cutId && error.epoch === packet.epoch && error.pictureSequence === packet.sequence) {
+                            this.disposeMotion(s, backend, packet, cut);
+                            active.delete(lane);
+                            updateAge();
+                            continue;
+                        }
+                        throw error;
+                    }
+                    flow.commit(id);
+                    if (!current() || s.configured !== configured || s.media !== media)
+                        return;
+                    s.lastPacketAt = performance.now();
+                    if (packet.type === 1) {
+                        s.configAdmittedEpoch = packet.epoch;
+                        this.wakeMedia(s);
+                    }
+                    if (packet.type === 2 || packet.type === 5) {
+                        s.activeBytes += packet.payload.length;
+                        if (packet.type === 2 && packet.fragmentIndex + 1 === packet.fragmentCount) {
+                            s.receivedFrame = Math.max(s.receivedFrame, packet.frameId);
+                            s.firstCompleteFrame ||= packet.frameId;
+                            if (!s.capturePaused)
+                                s.delivery.sent(packet.frameId, performance.now());
+                        }
+                    }
+                    stage = 'native_forwarded';
+                    backend.mediaForwarded?.(packet);
+                    active.delete(lane);
+                    updateAge();
+                    this.returnNativeCredit(s);
+                    this.wakeMedia(s);
+                }
+            }
+            catch (error) {
+                await fail(error, packet, stage);
+            }
+        };
+        const workers = ['motion', 'cursor', 'exact'].map(worker);
+        try {
+            for await (const bytes of backend.packets) {
+                if (!current() || failed)
+                    break;
+                const p = decodeMedia(bytes);
+                mediaRequire(s.configured && p.epoch === s.configured.mediaEpoch && p.displayRevision === s.configured.displayRevision && s.startedEpoch === p.epoch);
+                if (p.type === 1)
+                    s.codec = decodeConfig(p.payload);
+                mediaRequire(queuedBytes + s.flow.inFlightBytes + p.payload.length <= 524288 && queuedCount() + s.flow.recordCount < 128);
+                const lane = desktopMediaLane(p.type);
+                queues[lane].push({ bytes, p, at: performance.now() });
+                queuedBytes += p.payload.length;
+                updateAge();
+                this.wakeMedia(s);
+            }
+        }
+        catch (error) {
+            await fail(error);
+        }
+        finally {
+            ended = true;
+            this.wakeMedia(s);
+            await Promise.all(workers);
+            if (current())
+                s.queuedAt = 0;
+        }
+    }
+    async rateTick(s) {
+        if (s.tickBusy)
+            return;
+        s.tickBusy = true;
+        try {
+            await this.rateTickOwned(s);
+        }
+        finally {
+            s.tickBusy = false;
+        }
+    }
+    async rateTickOwned(s) {
+        if (!this.current(s) || !s.backend || !s.configured || s.startedEpoch !== s.configured.mediaEpoch || s.starting || s.rateBusy || s.motionCut && s.motionCut.phase !== 'committed')
+            return;
+        const backend = s.backend, configured = s.configured;
+        const transportCost = s.media?.transportCost?.();
+        if (transportCost && backend.accountTransportCost)
+            await backend.accountTransportCost(transportCost);
+        const audioCost = s.control?.audioTransportCost?.();
+        if (audioCost && backend.accountTransportCost)
+            await backend.accountTransportCost(audioCost);
+        if (!this.current(s) || s.backend !== backend || s.configured !== configured)
+            return;
+        if (backend.checkHealth && performance.now() >= (s.nextHealthAt ?? 0)) {
+            s.nextHealthAt = performance.now() + 1000;
+            try {
+                await backend.checkHealth();
+            }
+            catch (error) {
+                if (!this.current(s) || s.backend !== backend || s.configured !== configured)
+                    return;
+                this.diagnostic(s, 'native_health', error);
+                throw error;
+            }
+            const audioConfig = s.audioConfig;
+            if (audioConfig && backend.audioStatus) {
+                const status = await backend.audioStatus().catch(() => 'unavailable');
+                if (status === 'unavailable' && this.current(s) && s.backend === backend && s.audioConfig === audioConfig) {
+                    s.audioConfig = undefined;
+                    s.control?.stopAudio?.();
+                    await backend.stopAudio?.().catch(() => { });
+                    await this.send(s, { v: 1, type: 'audio_state', sessionId: s.binding.sessionId,
+                        payload: { commandId: audioConfig.commandId, state: 'unavailable', reason: 'audio_capture_unavailable' } }).catch(() => { });
+                }
+            }
+        }
+        if (!this.current(s) || s.backend !== backend || s.configured !== configured || s.startedEpoch !== configured.mediaEpoch)
+            return;
+        const now = performance.now(), queued = s.queuedAt ? now - s.queuedAt : 0;
+        if (now >= s.nextPing) {
+            s.nextPing = now + 10000;
+            for (const [challenge, value] of s.challenges)
+                if (now - value.at >= 90000)
+                    s.challenges.delete(challenge);
+            mediaRequire(s.challenges.size < 10);
+            const challenge = randomBytes(16).toString('hex');
+            s.challenges.set(challenge, { at: now, answered: false });
+            await this.send(s, { v: 1, type: 'ping', sessionId: s.binding.sessionId, payload: { challenge } });
+            if (!this.current(s) || s.backend !== backend || s.configured !== configured || s.startedEpoch !== configured.mediaEpoch)
+                return;
+        }
+        // Credit starvation is bounded backpressure. Feed queue age into rate/admission
+        // control instead of restarting a healthy helper when the remote reader is slow.
+        const baseline = s.rtts.length ? Math.min(...s.rtts) : 0;
+        const applied = backend.rateState?.applied ??
+            { targetBps: configured.rateTargetBps, fpsCeiling: configured.fpsCeiling };
+        const delivery = s.delivery.sample(now), excessRttMs = Math.max(0, s.rtt - baseline);
+        const queueAgeMs = s.feedback?.queueAgeMs ?? 0;
+        const timing = backend.nativeTelemetry?.lastFrameTiming;
+        if (timing && !timing.repair && timing.epoch === configured.mediaEpoch) {
+            const key = `${timing.epoch}:${timing.frameId}`;
+            if (key !== s.motionEncodeKey) {
+                s.motionEncodeKey = key;
+                s.motionEncodeObservedAt = now;
+                const elapsedUs = timing.encodeEndUs - timing.encodeBeginUs;
+                s.motionEncodeMs = Number.isFinite(elapsedUs) && elapsedUs >= 0 ? elapsedUs / 1000 : backend.nativeTelemetry?.lastEncodeMs ?? 0;
+            }
+        }
+        const encodeMs = s.motionEncodeMs;
+        const decodeMs = s.feedback?.decodeMs ?? 0;
+        const network = s.media?.networkSample?.();
+        const decision = s.controller.sample({ nowMs: now, activeBytes: s.activeBytes,
+            rttBaselineMs: baseline, excessRttMs, deliveryDelayMs: delivery.delayMs,
+            deliveryObservedAtMs: s.feedbackProgressAt ?? 0, encodeObservedAtMs: s.motionEncodeObservedAt ?? 0,
+            decodeObservedAtMs: s.decodeObservedAt ?? 0, network,
+            queueAgeMs, queuedSendMs: queued, encodeMs, decodeMs }, backend.runtimeRateReconfigure === true);
+        if (now - s.lastPerformanceDiagnosticAt >= (s.performanceDiagnosticCount < 30 ? 2000 : 10000)) {
+            s.lastPerformanceDiagnosticAt = now;
+            s.performanceDiagnosticCount = Math.min(30, s.performanceDiagnosticCount + 1);
+            try {
+                const native = backend.nativeTelemetry, previous = s.performanceSample;
+                const current = native ? { atMs: now, epoch: configured.mediaEpoch, captured: native.captured, encoded: native.encoded,
+                    refinements: native.refinementFrames ?? 0, payloadBytes: native.sentPayloadBytes } : undefined;
+                const comparable = current && previous && current.epoch === previous.epoch && now > previous.atMs &&
+                    current.encoded >= previous.encoded && current.refinements >= previous.refinements && current.payloadBytes >= previous.payloadBytes;
+                const seconds = comparable ? (now - previous.atMs) / 1000 : 0;
+                console.error(JSON.stringify({ event: 'desktop_supervisor_performance', session: s.diagnosticId,
+                    connectionId: s.diagnosticKey, processId: process.pid, atUnixMs: Date.now(),
+                    atMs: Math.round(now), epoch: configured.mediaEpoch, width: configured.width, height: configured.height,
+                    appliedTargetBps: applied.targetBps, appliedFpsCeiling: applied.fpsCeiling,
+                    queuedMs: Math.round(queued), queueAgeMs, excessRttMs, encodeMs, decodeMs,
+                    encodeMetric: 'source_unit_job', decodeMetric: 'submit_to_callback', networkScope: 'sender_to_server', network,
+                    presentMs: s.feedback?.presentMs, receiverQueueDepth: s.feedback?.queueDepth,
+                    policy: s.controller.diagnostics,
+                    captureConsumedFps: comparable && current.captured !== undefined && previous.captured !== undefined && current.captured >= previous.captured
+                        ? (current.captured - previous.captured) / seconds : undefined,
+                    motionCommittedFps: comparable ? (current.encoded - previous.encoded) / seconds : undefined,
+                    exactUpdatesPerSecond: comparable && native?.refinementFrames !== undefined ? (current.refinements - previous.refinements) / seconds : undefined,
+                    payloadBps: comparable ? (current.payloadBytes - previous.payloadBytes) * 8 / seconds : undefined,
+                    receivedFrame: s.receivedFrame, decodedId: s.feedback?.decodedId, presentedId: s.feedback?.presentedId,
+                    exactPresentedSequence: s.feedback?.exactPresentedSequence,
+                    native: backend.nativeTelemetry }));
+                s.performanceSample = current;
+            }
+            catch { }
+        }
+        const directPressure = Math.max(excessRttMs, queueAgeMs, queued) > 40 ||
+            Math.max(encodeMs, decodeMs) > 0.8 * 1000 / applied.fpsCeiling;
+        // Independent optional lane; never await snapshot/IO in focus rate or input processing.
+        const initialOverview = s.overviewSequence === 0;
+        if (backend.overview && backend.reserveOverview && s.control?.sendOverview && !s.overviewBusy && now >= (s.overviewNextAt ?? 0) &&
+            s.overviewBudget.canCapture(now, applied.targetBps, !initialOverview && (directPressure || s.capturePaused || s.rateBusy))) {
+            s.overviewBusy = true;
+            s.overviewNextAt = now + 2000;
+            const sourceWidth = configured.captureRegion?.sourceWidth ?? configured.width;
+            const sourceHeight = configured.captureRegion?.sourceHeight ?? configured.height;
+            void (async () => {
+                const image = await backend.overview(Math.min(s.overviewBudget.maxSide, s.overviewMaxSide ?? 640));
+                if (!image) {
+                    // Poll only initial asynchronous capture setup promptly; do not add a
+                    // two-second scheduling delay after WindowServer has produced its image.
+                    if (this.current(s) && s.backend === backend)
+                        s.overviewNextAt = performance.now() +
+                            (s.overviewSequence === 0 && s.overviewInitialPolls++ < 20 ? 250 : 2000);
+                    return;
+                }
+                if (image.sourceWidth !== sourceWidth || image.sourceHeight !== sourceHeight || !this.current(s) || s.backend !== backend ||
+                    s.configured !== configured || !initialOverview && (s.queuedAt || s.capturePaused))
+                    return;
+                const sequence = s.overviewSequence + 1;
+                const bytes = overviewPacket(image, sequence, s.binding.controlGeneration);
+                if (!s.overviewBudget.eligible(bytes, performance.now(), applied.targetBps))
+                    return;
+                if (!await backend.reserveOverview({ epoch: configured.mediaEpoch, wireBytes: bytes.length })) {
+                    if (this.current(s) && s.backend === backend && s.configured === configured && initialOverview) {
+                        s.overviewNextAt = performance.now() + 250;
+                        s.overviewMaxSide = 320;
+                    }
+                    return;
+                }
+                if (!this.current(s) || s.backend !== backend || s.configured !== configured ||
+                    !initialOverview && (s.queuedAt || s.capturePaused))
+                    return;
+                if (s.overviewBudget.admit(bytes, performance.now(), applied.targetBps)) {
+                    // Rejected captures have not used the initial preview's pressure exemption.
+                    s.overviewSequence = sequence;
+                    if (!await s.control.sendOverview(bytes))
+                        s.overviewBudget.disconnected();
+                }
+            })().catch(() => { }).finally(() => { s.overviewBusy = false; });
+        }
+        if (decision.pauseCapture !== s.capturePaused) {
+            s.capturePaused = decision.pauseCapture;
+            s.delivery.reset();
+        }
+        // Provider qualification, not the generic slow policy, decides whether a
+        // target change needs to retire codec/input authority.
+        if (backend.runtimeRateReconfigure)
+            decision.reopenEpoch = decision.fpsCeiling >
+                (backend.runtimeRateFpsCeiling ?? s.selection?.fpsCeiling ?? configured.fpsCeiling);
+        if (decision.targetBps === applied.targetBps && decision.fpsCeiling === applied.fpsCeiling)
+            decision.reopenEpoch = false;
+        const rateKey = `${decision.targetBps}:${decision.fpsCeiling}:${decision.pauseCapture}:${decision.reopenEpoch}`;
+        if (rateKey !== s.lastRateDiagnostic && now - s.lastRateDiagnosticAt >= 1000) {
+            s.lastRateDiagnostic = rateKey;
+            s.lastRateDiagnosticAt = now;
+            s.rateDiagnosticCount++;
+            try {
+                console.error(JSON.stringify({ event: 'desktop_supervisor_rate_decision', session: s.diagnosticId,
+                    connectionId: s.diagnosticKey, processId: process.pid, atUnixMs: Date.now(), policy: s.controller.diagnostics,
+                    ordinal: s.rateDiagnosticCount, epoch: configured.mediaEpoch, targetBps: decision.targetBps,
+                    fpsCeiling: decision.fpsCeiling, pauseCapture: decision.pauseCapture, reopenEpoch: decision.reopenEpoch,
+                    appliedTargetBps: applied.targetBps, appliedFpsCeiling: applied.fpsCeiling,
+                    queuedMs: Math.round(queued), queueAgeMs: s.feedback?.queueAgeMs ?? 0, excessRttMs: Math.max(0, s.rtt - baseline),
+                    deliveryDelayMs: delivery.delayMs, rawDeliveryExcessMs: delivery.excessMs,
+                    deliveryObservations: delivery.observations, deliveryEvidenceKnown: delivery.delayMs !== undefined,
+                    presented: s.presented }));
+            }
+            catch { /* Fixed, capped diagnostics do not affect rate decisions. */ }
+        }
+        s.activeBytes = 0;
+        if (!s.presented && decision.reopenEpoch)
+            return;
+        s.rateBusy = true;
+        try {
+            if (decision.reopenEpoch) {
+                if (!this.current(s) || s.backend !== backend || s.configured !== configured || s.startedEpoch !== configured.mediaEpoch)
+                    return;
+                const commandId = randomBytes(16).toString('hex');
+                s.configuredCommand = commandId;
+                s.automaticConfiguration = commandId;
+                s.backend?.configurationCommand?.(commandId);
+            }
+            if (this.current(s) && s.backend === backend && s.configured === configured && (decision.reopenEpoch || s.startedEpoch === configured.mediaEpoch))
+                await backend.setRate(decision);
+        }
+        finally {
+            s.rateBusy = false;
+            if (s.recoveryPending) {
+                s.recoveryPending = false;
+                await this.recover(s);
+            }
+        }
+    }
+    async recover(s) {
+        if (!this.current(s))
+            return;
+        // A failed media lane cannot be forgotten merely because the encoder is
+        // settling a rate command. Coalesce it and recover as soon as that owner exits.
+        if (s.rateBusy) {
+            if (!s.recovering)
+                s.recoveryPending = true;
+            return;
+        }
+        const now = performance.now();
+        s.recovery = s.recovery.filter(at => now - at < 30000);
+        if (s.recovery.length >= 2 || !s.selection) {
+            await this.fail(s);
+            return;
+        }
+        s.recovery.push(now);
+        s.rateBusy = true;
+        s.recovering = true;
+        try {
+            const backend = s.backend;
+            s.backend = undefined;
+            s.audioConfig = undefined;
+            s.audioFeedback = undefined;
+            s.audioReady = false;
+            s.control?.stopAudio?.();
+            if (s.audioCommand && s.audioMode && s.audioMode !== 'off')
+                await this.send(s, { v: 1, type: 'audio_state',
+                    sessionId: s.binding.sessionId, payload: { commandId: s.audioCommand, state: 'suspended', reason: 'audio_source_restarting' } });
+            s.mediaAttaching = undefined;
+            s.media?.close();
+            s.media = undefined;
+            s.packetLoop = false;
+            s.viewerReady = false;
+            s.decoderReady = false;
+            s.presented = false;
+            s.startedEpoch = 0;
+            s.starting = false;
+            s.startCommand = undefined;
+            await backend?.stop();
+            if (!this.current(s))
+                return;
+            const commandId = randomBytes(16).toString('hex');
+            s.configuredCommand = commandId;
+            await this.send(s, { v: 1, type: 'media_open', sessionId: s.binding.sessionId, payload: { commandId } });
+            if (!this.current(s))
+                return;
+            s.preparation = this.options.provider.prepare({ ...s.selection, commandId }, s.binding);
+            const next = await s.preparation;
+            if (!this.current(s)) {
+                await next.stop();
+                return;
+            }
+            s.backend = next;
+            void this.events(s, next);
+        }
+        catch (error) {
+            if (this.current(s))
+                this.diagnostic(s, 'recovery_failed', error);
+            await this.fail(s);
+        }
+        finally {
+            s.rateBusy = false;
+        }
+    }
+    async close() {
+        this.clearLobbies();
+        const candidates = [...this.candidates.values()];
+        for (const candidate of candidates)
+            this.retire(candidate);
+        const active = this.active;
+        if (active)
+            this.retire(active);
+        this.closed = true;
+        await this.maintenance?.catch(() => { });
+        await this.tail;
+        if (active)
+            await this.cleanup(active);
+        await Promise.all(candidates.map(candidate => this.cleanup(candidate)));
+    }
+}