@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/desktopControl/helperProcess.js

@@ -0,0 +1,602 @@
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { setTimeout as delay } from 'node:timers/promises';
+import { z } from 'zod';
+import { DesktopProtocolError, parseDesktopJson } from './protocol.js';
+import { decodeMedia, mediaRequire } from './media.js';
+import { decodeAudio } from './audio.js';
+import { randomBytes as automationRandomBytes } from 'node:crypto';
+import { parseAutomationJson } from './automationJson.js';
+import { AutomationTransport } from './automationTransport.js';
+import { AutomationSession } from './automationSession.js';
+import { decodeAutomationFailureDetail } from './automationProtocol.js';
+const execute = promisify(execFile);
+const commands = ['focus', 'cache_dependency', 'transport_cost', 'prepare_motion_cut', 'commit_motion_cut', 'prepare', 'start', 'decoder_ready', 'first_presented', 'acknowledge', 'credit', 'renew', 'input', 'clipboard', 'overview', 'reserve_overview', 'resize',
+    'held_state', 'text_result', 'recover_display', 'set_rate', 'refresh', 'stop', 'verify_cleanup', 'probe', 'status'];
+const safe = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const handshakeSchema = z.strictObject({ ipc: z.literal(1), providerVersion: z.literal('axom-linux-1'),
+    representations: z.tuple([z.literal(1)]),
+    inputAbi: z.literal(1), rateAbi: z.literal(1), continuationAbi: z.literal(1), motionRecoveryAbi: z.literal(1), runtimeRateReconfigure: z.literal(false),
+    rateLimits: z.strictObject({ minBps: z.literal(500000), maxBps: z.literal(20000000), stepBps: z.literal(4000), maxFps: z.literal(60) }),
+    supportedCommands: z.array(z.string()).refine(a => commands.every(c => a.includes(c))) });
+export function validateNativeHandshake(value, platform = 'linux') {
+    (platform === 'linux' ? handshakeSchema : handshakeSchema.extend({ providerVersion: z.literal('axom-macos-1'),
+        rateLimits: handshakeSchema.shape.rateLimits.extend({ maxFps: z.literal(30) }) })).parse(value);
+}
+/** One waiter, pulled reads: a blocked media consumer never blocks the control reader. */
+export class NativeByteReader {
+    max;
+    iterator;
+    bytes = Buffer.alloc(0);
+    constructor(stream, max = 65600) {
+        this.max = max;
+        this.iterator = stream[Symbol.asyncIterator]();
+    }
+    async exact(size) {
+        mediaRequire(Number.isInteger(size) && size > 0 && size <= this.max);
+        while (this.bytes.length < size) {
+            const next = await this.iterator.next();
+            if (next.done)
+                throw new DesktopProtocolError('Native stream ended');
+            mediaRequire(Buffer.isBuffer(next.value) && this.bytes.length + next.value.length <= this.max + 65536);
+            this.bytes = Buffer.concat([this.bytes, next.value]);
+        }
+        const value = this.bytes.subarray(0, size);
+        this.bytes = this.bytes.subarray(size);
+        return value;
+    }
+}
+export class NativeControlReader {
+    reader;
+    constructor(stream) { this.reader = new NativeByteReader(stream, 49152); }
+    async read() {
+        const size = (await this.reader.exact(4)).readUInt32BE();
+        mediaRequire(size > 0 && size <= 49152);
+        // lastEncodeMs is the sole fractional native counter.
+        const bytes = await this.reader.exact(size);
+        return parseDesktopJson(bytes, 49152, nativeIntegerFields);
+    }
+}
+const nativeIntegerFields = new Set(['ipc', 'id', 'epoch', 'width', 'height', 'dpi', 'fpsCeiling', 'targetBps', 'rateTargetBps',
+    'motionRecoveryAbi', 'cutId', 'pictureThrough', 'frameThrough', 'continuationAbi', 'inputAbi', 'rateAbi', 'representations', 'representation', 'minBps', 'maxBps', 'stepBps', 'maxFps',
+    'maxRateBps', 'bufferBits', 'maxBFrames', 'nextFrameId', 'frameId', 'leaseMs', 'motionConsumedBytes', 'cursorConsumedBytes', 'exactConsumedBytes', 'windowBytes',
+    'hrdBitRate', 'hrdCpbSize', 'spsWidth', 'spsHeight', 'spsMaxReorderFrames',
+    'rcModeValue', 'blockLevelRateControl', 'spsMaxRateBps', 'spsBufferBits',
+    'controlGeneration', 'displayRevision', 'sequence', 'lastAllocatedFrameId', 'frameIdLimit', 'captured', 'encoded', 'sentPayloadBytes',
+    'videoPayloadBytes', 'headerBytes', 'rateReopens', 'refinementFrames', 'motionContinuations', 'pendingPayloadBytes', 'rateCooldownUntilMs', 'nowMs', 'initialAtMs',
+    'cacheId', 'exactSequence', 'initialReservoirBits', 'capacityBits', 'availableBits', 'integratedTargetBits', 'transportBytes', 'debtBits', 'appliedAtMonotonicMs', 'lastInputSequence', 'lastAppliedInputSequence', 'wireBytes',
+    'sourceCaptureUs', 'captureBeginUs', 'captureEndUs', 'captureCompareBeginUs', 'captureCompareEndUs', 'captureCopyBeginUs', 'captureCopyEndUs', 'encodeBeginUs', 'encodeEndUs', 'committedUs']);
+const budgetSchema = z.strictObject({ nowMs: safe, initialAtMs: safe, initialReservoirBits: safe, capacityBits: safe,
+    availableBits: safe, integratedTargetBits: safe, transportBytes: safe, debtBits: safe });
+const frameTimingSchema = z.strictObject({ clock: z.literal('steady_clock'), epoch: safe.min(1), frameId: safe.min(1), repair: z.boolean(),
+    sourceCaptureUs: safe, captureBeginUs: safe, captureEndUs: safe, captureCompareBeginUs: safe.default(0), captureCompareEndUs: safe.default(0),
+    captureCopyBeginUs: safe.default(0), captureCopyEndUs: safe.default(0), encodeBeginUs: safe, encodeEndUs: safe, committedUs: safe,
+}).refine(timing => timing.encodeBeginUs <= timing.encodeEndUs && timing.encodeEndUs <= timing.committedUs &&
+    (timing.repair ? timing.sourceCaptureUs === 0 && timing.captureBeginUs === 0 && timing.captureEndUs === 0 :
+        timing.captureBeginUs <= timing.captureEndUs && timing.captureEndUs <= timing.encodeBeginUs &&
+            (timing.captureCompareBeginUs === 0 && timing.captureCompareEndUs === 0 && timing.captureCopyBeginUs === 0 && timing.captureCopyEndUs === 0 ||
+                timing.captureCompareBeginUs <= timing.captureCompareEndUs &&
+                    timing.captureCompareEndUs <= timing.captureCopyBeginUs && timing.captureCopyBeginUs <= timing.captureCopyEndUs &&
+                    timing.captureCopyEndUs <= timing.captureEndUs)), 'Invalid native frame timing');
+const countersSchema = z.strictObject({ epoch: safe, lastAllocatedFrameId: safe, frameIdLimit: safe, captured: safe, encoded: safe,
+    sentPayloadBytes: safe, videoPayloadBytes: safe, headerBytes: safe, rateReopens: safe, targetBps: safe, fpsCeiling: safe,
+    pauseCapture: z.boolean(), lastEncodeMs: z.number().finite().min(0), lastFrameTiming: frameTimingSchema.nullable(), refinementFrames: safe.optional(), motionContinuations: safe.optional(), pendingPayloadBytes: safe, rateCooldownUntilMs: safe,
+    rateBudget: budgetSchema.optional(), inputAvailable: z.boolean(), lastInputSequence: safe });
+const replySchema = z.union([
+    z.strictObject({ ipc: z.literal(1), id: safe, ok: z.literal(true), result: z.record(z.string(), z.unknown()), counters: countersSchema }),
+    z.strictObject({ ipc: z.literal(1), id: safe, ok: z.literal(false), code: z.enum(['invalid_request', 'unavailable', 'conflict', 'busy',
+            'rate_limited', 'authorization_lost', 'encoder_failed']), counters: countersSchema }),
+]);
+export class NativeCommandError extends Error {
+    code;
+    counters;
+    detail;
+    constructor(code, counters, detail = null) {
+        super(code);
+        this.code = code;
+        this.counters = counters;
+        this.detail = detail;
+    }
+}
+/** Local queue retirement, created only before allocating an ID or writing bytes. */
+class NativeCommandCancelled extends NativeCommandError {
+    constructor() { super('cancelled'); }
+}
+export async function bounded(promise, ms, code = 'transport_failed') {
+    let timer;
+    try {
+        return await Promise.race([promise, new Promise((_, reject) => { timer = setTimeout(() => reject(new NativeCommandError(code)), ms); })]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class HelperProcess {
+    executable;
+    env;
+    child;
+    reader;
+    media;
+    audio;
+    audioSupported = false;
+    id = 0;
+    queued = 0;
+    tail = Promise.resolve();
+    stopped = false;
+    termination;
+    pending = new Map();
+    active = new Set();
+    stopPromise;
+    exited = false;
+    closed;
+    counters;
+    constructor(executable, env) {
+        this.executable = executable;
+        this.env = env;
+        this.child = spawn(executable, ['--media-fd', '3'], { stdio: ['pipe', 'pipe', 'ignore', 'pipe', 'pipe'], env: { ...env, AXOM_KEEPER_AUDIO_FD: '4' }, detached: false });
+        this.child.stdin.on('error', () => { });
+        this.reader = new NativeControlReader(this.child.stdout);
+        this.media = new NativeByteReader(this.child.stdio[3]);
+        this.audio = new NativeByteReader(this.child.stdio[4]);
+        this.closed = new Promise(resolve => {
+            this.child.once('exit', () => { this.exited = true; this.rejectPending(new NativeCommandError('transport_failed')); resolve(); });
+            this.child.once('error', () => { this.exited = true; this.rejectPending(new NativeCommandError('transport_failed')); resolve(); });
+        });
+    }
+    static async launch(executable, env = process.env, platform = 'linux') {
+        const h = new HelperProcess(executable, env);
+        try {
+            const handshake = await bounded(h.reader.read(), 3000, 'unavailable');
+            validateNativeHandshake(handshake, platform);
+            h.audioSupported = handshake.supportedCommands.includes('audio_start');
+            void h.readReplies();
+            return h;
+        }
+        catch {
+            await h.terminate();
+            throw new NativeCommandError('unavailable');
+        }
+    }
+    get pid() { return this.child.pid; }
+    async readReplies() {
+        try {
+            while (!this.stopped && !this.exited) {
+                const reply = replySchema.parse(await this.reader.read());
+                const first = this.pending.entries().next();
+                mediaRequire(!first.done && reply.id === first.value[0]);
+                const [id, pending] = first.value;
+                this.pending.delete(id);
+                clearTimeout(pending.timer);
+                this.counters = reply.counters;
+                if (reply.ok)
+                    pending.resolve({ result: reply.result, counters: reply.counters });
+                else
+                    pending.reject(new NativeCommandError(reply.code, reply.counters));
+            }
+        }
+        catch (error) {
+            if (!this.stopped)
+                this.fail(error);
+        }
+    }
+    rejectPending(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+    fail(error) { this.rejectPending(error); void this.terminate(); }
+    request(command, binding, payload = {}, current = () => true) {
+        if (this.stopped || this.exited || ![...commands, 'cursor_visibility', 'audio_start', 'audio_rate', 'audio_stop', 'audio_status'].includes(command) || this.queued >= 32)
+            return Promise.reject(new NativeCommandError('transport_failed'));
+        const barrier = !['credit', 'status', 'input', 'transport_cost', 'cache_dependency'].includes(command);
+        const prior = barrier ? [...this.active] : [];
+        const identity = { ...binding }, epoch = this.counters?.epoch;
+        let data;
+        try {
+            data = structuredClone(payload);
+        }
+        catch (error) {
+            this.fail(error);
+            return Promise.reject(error);
+        }
+        this.queued++;
+        const queuedAt = performance.now();
+        let startedAt = queuedAt;
+        let response;
+        const issued = this.tail.then(async () => {
+            // A barrier drains prior validated replies and their owner continuations,
+            // then excludes every later write until its own reply has completed.
+            if (barrier)
+                await Promise.allSettled(prior);
+            startedAt = performance.now();
+            if (this.stopped || this.exited || !Number.isSafeInteger(this.id + 1))
+                throw new NativeCommandError('transport_failed');
+            if (!current() || command === 'input' && epoch !== undefined && this.counters?.epoch !== epoch)
+                throw new NativeCommandCancelled();
+            // The owner may withdraw capture authority while this rate command waits.
+            // All other payload fields retain their enqueue-time snapshot.
+            if (command === 'set_rate')
+                Object.assign(data, { pauseCapture: payload.pauseCapture });
+            const id = ++this.id, bytes = Buffer.from(JSON.stringify({ ipc: 1, id, command, binding: identity, payload: data }));
+            mediaRequire(bytes.length > 0 && bytes.length <= 49152);
+            response = new Promise((resolve, reject) => {
+                const timer = setTimeout(() => this.fail(new NativeCommandError('transport_failed')), 5000);
+                this.pending.set(id, { resolve, reject, timer });
+            });
+            // A reply can precede the write callback; retain its failure without an
+            // unhandled rejection while write ownership is still being confirmed.
+            void response.catch(() => { });
+            const prefix = Buffer.alloc(4);
+            prefix.writeUInt32BE(bytes.length);
+            await bounded(write(this.child.stdin, Buffer.concat([prefix, bytes])), 5000);
+        });
+        const run = issued.then(() => response);
+        const report = (error) => {
+            if (error instanceof NativeCommandCancelled)
+                return;
+            if (!(error instanceof NativeCommandError) || !['busy', 'rate_limited'].includes(error.code)) {
+                console.error(JSON.stringify({ event: 'desktop_native_command_failed', command,
+                    code: error instanceof NativeCommandError ? error.code : 'transport_failed', elapsedMs: Math.round(performance.now() - startedAt), queuedMs: Math.round(startedAt - queuedAt), queued: this.queued }));
+            }
+            if (!(error instanceof NativeCommandError) || !error.counters)
+                this.fail(error);
+        };
+        const completed = run.catch(error => { report(error); throw error; }).finally(() => {
+            this.queued--;
+            this.active.delete(completed);
+        });
+        this.active.add(completed);
+        // Observe issuance errors before allowing the next queued write. Reply
+        // failures are reported by completed; the reader independently fails all
+        // in-flight work on malformed or unknown replies.
+        this.tail = (barrier ? completed : issued).catch(error => {
+            if (!(error instanceof NativeCommandCancelled) && (!(error instanceof NativeCommandError) || !error.counters))
+                this.fail(error);
+        });
+        return completed;
+    }
+    get packets() {
+        const self = this;
+        return { async *[Symbol.asyncIterator]() {
+                while (!self.stopped && !self.exited) {
+                    const header = await self.media.exact(64), size = header.readUInt32BE(48);
+                    mediaRequire(size > 0 && size <= 65536);
+                    const bytes = Buffer.concat([header, await self.media.exact(size)]);
+                    decodeMedia(bytes);
+                    yield bytes;
+                }
+            } };
+    }
+    get audioPackets() {
+        const self = this;
+        return { async *[Symbol.asyncIterator]() {
+                while (!self.stopped && !self.exited) {
+                    const header = await self.audio.exact(40), size = header.readUInt16BE(36);
+                    mediaRequire(size > 0 && size <= 1000);
+                    const bytes = Buffer.concat([header, await self.audio.exact(size)]);
+                    decodeAudio(bytes);
+                    yield bytes;
+                }
+            } };
+    }
+    stop(binding) {
+        return this.stopPromise ??= (async () => {
+            if (!this.exited) {
+                try {
+                    await bounded(this.request('stop', binding), 750);
+                }
+                catch { /* EOF cleanup remains authoritative. */ }
+            }
+            await this.terminate();
+            await HelperProcess.verifyCleanup(this.executable, this.env);
+        })();
+    }
+    terminate() {
+        return this.termination ??= (async () => {
+            this.stopped = true;
+            this.rejectPending(new NativeCommandError('transport_failed'));
+            if (!this.exited) {
+                this.child.kill('SIGTERM');
+                try {
+                    await bounded(this.closed, 1000);
+                }
+                catch {
+                    this.child.kill('SIGKILL');
+                    await bounded(this.closed, 2000);
+                }
+            }
+            this.child.stdin?.destroy();
+            this.child.stdout?.destroy();
+            this.child.stdio[3]?.destroy();
+            this.child.stdio[4]?.destroy();
+        })();
+    }
+    static async verifyCleanup(executable, env = process.env) {
+        const deadline = performance.now() + 3000;
+        do {
+            try {
+                await execute(executable, ['--verify-input-cleanup'], { env, timeout: 750, maxBuffer: 4096 });
+                return;
+            }
+            catch {
+                await delay(25);
+            }
+        } while (performance.now() < deadline);
+        throw new NativeCommandError('unavailable');
+    }
+}
+function write(stream, bytes) {
+    return new Promise((resolve, reject) => stream.write(bytes, error => error ? reject(error) : resolve()));
+}
+export async function launchAutomationHelper(executable, env, binding) {
+    if (!binding.native || !binding.preparation)
+        throw new NativeCommandError('trusted_preparation_unavailable');
+    const token = automationRandomBytes(32).toString('hex');
+    const child = spawn(executable, ['--automation-fd', '3'], { stdio: ['pipe', 'pipe', 'ignore', 'pipe'],
+        env: { ...env, AXOM_AUTOMATION_TOKEN: token, AXOM_AUTOMATION_FEATURES: 'capture_wait_v1' } });
+    child.stdin.on('error', () => { });
+    const control = new NativeByteReader(child.stdout, 49152), binary = new NativeByteReader(child.stdio[3], 8388608 + 49156);
+    let ended = false, controlId = 0, writeCount = 0, writeTail = Promise.resolve();
+    const renewals = new Map();
+    const preparations = new Map();
+    const statuses = new Map();
+    const readControls = new Map();
+    const send = (text) => {
+        if (ended || writeCount >= 64)
+            return Promise.reject(new NativeCommandError('resource_limit'));
+        const body = Buffer.from(text);
+        if (!body.length || body.length > 49152)
+            return Promise.reject(new NativeCommandError('invalid_argument'));
+        const prefix = Buffer.alloc(4);
+        prefix.writeUInt32BE(body.length);
+        writeCount++;
+        const pending = writeTail.then(() => { if (ended)
+            throw new NativeCommandError('closed'); return bounded(write(child.stdin, Buffer.concat([prefix, body])), 1000); });
+        writeTail = pending.catch(() => { }).finally(() => { writeCount--; });
+        return pending;
+    };
+    const transport = new AutomationTransport(send, requestId => { void send(JSON.stringify({ command: 'cancel', requestId })).catch(() => { }); });
+    const retire = () => {
+        if (ended)
+            return;
+        ended = true;
+        transport.close('transport_failed');
+        for (const renewal of renewals.values()) {
+            clearTimeout(renewal.timer);
+            renewal.reject(new NativeCommandError('closed'));
+        }
+        renewals.clear();
+        for (const pending of preparations.values()) {
+            clearTimeout(pending.timer);
+            pending.detach();
+            pending.reject(new NativeCommandError('closed'));
+        }
+        preparations.clear();
+        for (const pending of statuses.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(new NativeCommandError('closed'));
+        }
+        statuses.clear();
+        for (const pending of readControls.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(new NativeCommandError('closed'));
+        }
+        readControls.clear();
+    };
+    const closed = new Promise(resolve => { child.once('exit', () => { retire(); resolve(); }); child.once('error', () => { retire(); resolve(); }); });
+    const readControl = async () => {
+        const size = (await control.exact(4)).readUInt32BE();
+        return parseAutomationJson(await control.exact(size), 49152).value;
+    };
+    const stop = async () => {
+        try {
+            if (!ended)
+                await send(JSON.stringify({ command: 'shutdown' }));
+        }
+        catch { }
+        retire();
+        child.kill('SIGTERM');
+        try {
+            await bounded(closed, 1000);
+        }
+        catch {
+            child.kill('SIGKILL');
+            await bounded(closed, 2000);
+        }
+        child.stdin?.destroy();
+        child.stdout?.destroy();
+        child.stdio[3].destroy();
+    };
+    try {
+        const handshake = await bounded(readControl(), 3000, 'unsupported_automation_protocol');
+        if (handshake.automationProtocol !== 1 || !Array.isArray(handshake.operations) || !handshake.operations.includes('capture'))
+            throw new NativeCommandError('unsupported_automation_protocol');
+        await send(JSON.stringify({ command: 'bind', token, context: { ...binding.native, route: binding.route, executionId: binding.executionId,
+                preparation: { ...binding.preparation, selector: null, mode: null } } }));
+        const attached = await bounded(readControl(), 3000, 'unsupported_automation_protocol');
+        if (attached.control !== 'bound' || !Array.isArray(attached.operations))
+            throw new NativeCommandError('unsupported_automation_protocol');
+        void (async () => {
+            while (!ended) {
+                const message = await readControl();
+                const readPending = readControls.get(message.id);
+                if (readPending && ['status_only', 'isolate', 'prepare_failed'].includes(message.control)) {
+                    readControls.delete(message.id);
+                    clearTimeout(readPending.timer);
+                    if (message.control === 'prepare_failed')
+                        readPending.reject(new NativeCommandError(message.code));
+                    else if (message.control !== readPending.command || message.result?.physical !== 'completed' || message.result?.revoked !== true)
+                        readPending.reject(new NativeCommandError('isolation_unconfirmed'));
+                    else
+                        readPending.resolve(message.result);
+                }
+                else if (message.control === 'lease_admitted') {
+                    const renewal = renewals.get(message.id);
+                    if (!renewal)
+                        continue;
+                    renewals.delete(message.id);
+                    clearTimeout(renewal.timer);
+                    renewal.resolve({ admitted: true, physical: message.physical });
+                }
+                else if (message.control === 'prepared' || message.control === 'prepare_failed') {
+                    const pending = preparations.get(message.id);
+                    if (!pending)
+                        continue;
+                    preparations.delete(message.id);
+                    clearTimeout(pending.timer);
+                    pending.detach();
+                    if (message.control === 'prepared')
+                        pending.resolve(message.attachment);
+                    else
+                        pending.reject(new NativeCommandError(message.code, undefined, decodeAutomationFailureDetail(message.detail)));
+                }
+                else if (message.control === 'control_status') {
+                    const pending = statuses.get(message.id);
+                    if (!pending)
+                        continue;
+                    statuses.delete(message.id);
+                    clearTimeout(pending.timer);
+                    pending.resolve({ physical: message.physical, revoked: message.revoked });
+                }
+                else if (message.control !== 'close_admitted') {
+                    const accepted = transport.acceptResponse(JSON.stringify(message));
+                    if (!accepted.ok && accepted.code !== 'unknown_request')
+                        throw new NativeCommandError('invalid_response');
+                }
+            }
+        })().catch(() => { retire(); child.kill('SIGTERM'); });
+        void (async () => {
+            while (!ended) {
+                const prefix = await binary.exact(4), length = prefix.readUInt32BE();
+                if (length < 1 || length > 49152)
+                    throw new NativeCommandError('invalid_binary');
+                const header = await binary.exact(length), value = parseAutomationJson(header, 49152).value;
+                if (!Number.isInteger(value.bytesLength) || value.bytesLength < 1 || value.bytesLength > 8388608)
+                    throw new NativeCommandError('invalid_binary');
+                transport.acceptBinary(Buffer.concat([prefix, header, await binary.exact(value.bytesLength)]));
+            }
+        })().catch(() => { retire(); child.kill('SIGTERM'); });
+        return new AutomationSession(transport, binding, { operations: attached.operations.filter((operation) => handshake.operations.includes(operation)), close: stop,
+            readControl: async (command, fields) => {
+                if (readControls.size >= 8 || ended)
+                    throw new NativeCommandError('resource_limit');
+                const requestId = `read-control-${++controlId}`;
+                const pending = new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => { readControls.delete(requestId); reject(new NativeCommandError('timed_out')); }, 5000);
+                    readControls.set(requestId, { command, resolve, reject, timer });
+                });
+                void send(JSON.stringify({ command, requestId, ...fields })).catch(error => {
+                    const entry = readControls.get(requestId);
+                    if (entry) {
+                        readControls.delete(requestId);
+                        clearTimeout(entry.timer);
+                        entry.reject(error);
+                    }
+                });
+                return pending;
+            },
+            prepare: async (preparation, options = {}) => {
+                if (preparations.size + renewals.size + statuses.size >= 8 || ended)
+                    throw new NativeCommandError('resource_limit');
+                if (options.signal?.aborted)
+                    throw new NativeCommandError('cancelled');
+                const requestId = `attachment-${++controlId}`;
+                const pending = new Promise((resolve, reject) => {
+                    const abort = () => {
+                        const entry = preparations.get(requestId);
+                        if (!entry)
+                            return;
+                        preparations.delete(requestId);
+                        clearTimeout(entry.timer);
+                        entry.detach();
+                        reject(new NativeCommandError('cancelled'));
+                        void send(JSON.stringify({ command: 'cancel', requestId })).catch(() => { });
+                    };
+                    const timer = setTimeout(() => { abort(); }, options.timeoutMs ?? 65000);
+                    preparations.set(requestId, { resolve, reject, timer, detach: () => options.signal?.removeEventListener('abort', abort) });
+                    options.signal?.addEventListener('abort', abort, { once: true });
+                });
+                void send(JSON.stringify({ command: 'prepare', requestId, preparation })).catch(error => {
+                    const entry = preparations.get(requestId);
+                    if (entry) {
+                        preparations.delete(requestId);
+                        clearTimeout(entry.timer);
+                        entry.detach();
+                        entry.reject(error);
+                    }
+                });
+                return pending;
+            },
+            status: async () => {
+                if (preparations.size + renewals.size + statuses.size >= 8 || ended)
+                    throw new NativeCommandError('resource_limit');
+                const id = ++controlId;
+                const pending = new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => { statuses.delete(id); reject(new NativeCommandError('timed_out')); }, 1000);
+                    statuses.set(id, { resolve, reject, timer });
+                });
+                void send(JSON.stringify({ command: 'control_status', id })).catch(error => { const entry = statuses.get(id); if (entry) {
+                    clearTimeout(entry.timer);
+                    statuses.delete(id);
+                    entry.reject(error);
+                } });
+                return pending;
+            },
+            renew: async (leaseMs) => {
+                if (preparations.size + renewals.size + statuses.size >= 8 || ended)
+                    throw new NativeCommandError('resource_limit');
+                const id = ++controlId;
+                const pending = new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => { renewals.delete(id); reject(new NativeCommandError('timed_out')); }, 1000);
+                    renewals.set(id, { resolve, reject, timer });
+                });
+                try {
+                    await send(JSON.stringify({ command: 'renew', id, leaseMs }));
+                    return await pending;
+                }
+                catch (error) {
+                    const renewal = renewals.get(id);
+                    if (renewal) {
+                        clearTimeout(renewal.timer);
+                        renewals.delete(id);
+                        renewal.resolve({ admitted: true, physical: 'failed' });
+                    }
+                    throw error;
+                }
+            } });
+    }
+    catch (error) {
+        await stop();
+        throw error instanceof NativeCommandError ? error : new NativeCommandError('unsupported_automation_protocol');
+    }
+}
+/** A single bounded session/event consumer; overflow retires the session. */
+export class DesktopQueue {
+    limit;
+    values = [];
+    wake;
+    ended = false;
+    constructor(limit = 64) {
+        this.limit = limit;
+    }
+    push(value) {
+        if (this.ended)
+            return;
+        if (this.wake) {
+            const wake = this.wake;
+            this.wake = undefined;
+            wake({ value, done: false });
+        }
+        else {
+            mediaRequire(this.values.length < this.limit);
+            this.values.push(value);
+        }
+    }
+    close() { this.ended = true; this.values = []; this.wake?.({ value: undefined, done: true }); this.wake = undefined; }
+    [Symbol.asyncIterator]() {
+        return { next: () => this.values.length ? Promise.resolve({ value: this.values.shift(), done: false }) :
+                this.ended ? Promise.resolve({ value: undefined, done: true }) : new Promise(resolve => { mediaRequire(!this.wake); this.wake = resolve; }) };
+    }
+}

package/dist/workstation/desktopControl/hostGrant.js

@@ -0,0 +1,65 @@
+import { promises as fs, constants } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+export const deviceHostGrantSchema = z.strictObject({ schemaVersion: z.literal(2), hostGeneration: z.string().min(1).max(128),
+    executable: z.string().startsWith('/').max(4096), sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    socket: z.string().startsWith('/').max(103), token: z.string().regex(/^[a-f0-9]{64}$/) });
+async function verifiedSocketPath(socket, checks) {
+    const realpath = checks.realpath ?? ((file) => fs.realpath(file)), canonical = await realpath(socket);
+    if (canonical === socket)
+        return true;
+    // Older macOS producers stored /tmp while the OS resolves its root-owned system alias.
+    // Exact prefix substitution rejects every additional symlink or path normalization.
+    if ((checks.platform ?? process.platform) !== 'darwin' || !socket.startsWith('/tmp/') || canonical !== '/private' + socket)
+        return false;
+    try {
+        const lstat = checks.systemLstat ?? ((file) => fs.lstat(file));
+        const link = await lstat('/tmp'), target = await lstat('/private/tmp');
+        const destination = await (checks.systemReadlink ?? ((file) => fs.readlink(file)))('/tmp');
+        return link.isSymbolicLink() && link.uid === 0 && target.isDirectory() && target.uid === 0 && !!(target.mode & 0o1000) &&
+            (destination === 'private/tmp' || destination === '/private/tmp') && await realpath('/tmp') === '/private/tmp' && await realpath('/private/tmp') === '/private/tmp';
+    }
+    catch {
+        return false;
+    }
+}
+export async function readDeviceHostDescriptor(fileName) {
+    const parent = await fs.lstat(path.dirname(fileName));
+    if (!parent.isDirectory() || parent.uid !== process.getuid?.() || parent.mode & 0o077)
+        throw new Error('unsafe_native_host');
+    const file = await fs.open(fileName, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let grant;
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.uid !== process.getuid?.() || stat.mode & 0o077 || stat.size > 16384)
+            throw new Error('unsafe_native_host');
+        grant = deviceHostGrantSchema.parse(JSON.parse(await file.readFile('utf8')));
+    }
+    finally {
+        await file.close();
+    }
+    return grant;
+}
+export async function readDeviceHostGrant(fileName, allowRootExecutable = false, checks = {}) {
+    const grant = await readDeviceHostDescriptor(fileName);
+    const parent = await fs.lstat(path.dirname(grant.socket)), socket = await fs.lstat(grant.socket);
+    if (!parent.isDirectory() || parent.uid !== process.getuid?.() || parent.mode & 0o077 || !socket.isSocket() || socket.uid !== process.getuid?.() || socket.mode & 0o077 ||
+        !await verifiedSocketPath(grant.socket, checks) || await (checks.realpath ?? ((file) => fs.realpath(file)))(grant.executable) !== grant.executable)
+        throw new Error('unsafe_native_host');
+    const executable = await fs.open(grant.executable, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await executable.stat();
+        if (!stat.isFile() || stat.uid !== process.getuid?.() && !(allowRootExecutable && stat.uid === 0) || stat.mode & 0o022 || stat.size > 32 * 1024 * 1024)
+            throw new Error('unsafe_native_host');
+        const hash = createHash('sha256');
+        for await (const bytes of executable.createReadStream({ autoClose: false }))
+            hash.update(bytes);
+        if (hash.digest('hex') !== grant.sha256)
+            throw new Error('unsafe_native_host');
+    }
+    finally {
+        await executable.close();
+    }
+    return grant;
+}