@playcraft/cli 0.1.24 → 0.1.25

package/dist/workspace-runtime/server/desktop-host.js

@@ -0,0 +1,429 @@
+import { connect as connectTcp } from 'node:net';
+import { WebSocket, WebSocketServer } from 'ws';
+import { desktopHealthSchema, desktopResourceName, runtimeError, } from '@playcraft/common/cloud-workspace/runtime';
+import { controlTokenMatches, extractControlToken } from './auth.js';
+import { createRfbWatchGate } from './rfb-watch-gate.js';
+import { DesktopPreviewError, DesktopPreviewHost } from './desktop-preview.js';
+import { WorkspaceContextError } from '../workspaces/context-error.js';
+/**
+ * A takeover holds the desktop for this long, whether or not a page is watching, and ends on its
+ * own unless the user renews it.
+ */
+const HOLD_MS = 20 * 60_000;
+const sources = new WeakMap();
+const hosts = new WeakMap();
+export function setDesktopSource(state, source) {
+    if (source)
+        sources.set(state, source);
+    else
+        sources.delete(state);
+    hosts.get(state)?.replaceSource(source);
+}
+export function desktopHost(state) {
+    let host = hosts.get(state);
+    if (!host) {
+        host = new DesktopHost(state);
+        hosts.set(state, host);
+    }
+    return host;
+}
+export async function disposeDesktopHost(state) {
+    const host = hosts.get(state);
+    hosts.delete(state);
+    sources.delete(state);
+    await host?.dispose();
+}
+export class DesktopHost {
+    state;
+    generation = 0;
+    holder = 'none';
+    probed = 'display_not_started';
+    viewers = new Set();
+    sockets = new WebSocketServer({ noServer: true });
+    source;
+    upstream = loopbackUpstream(process.env.PLAYCRAFT_DESKTOP_UPSTREAM);
+    holdMs = holdDuration(process.env.PLAYCRAFT_DESKTOP_HOLD_MS);
+    holdExpiresAt;
+    holdTimer;
+    preview;
+    disposed = false;
+    constructor(state) {
+        this.state = state;
+        this.source = sources.get(state);
+    }
+    replaceSource(source) {
+        this.source = source;
+    }
+    snapshot() {
+        return desktopHealthSchema.parse({
+            status: this.currentStatus(),
+            streamGeneration: this.generation,
+            holder: this.holder,
+            agentInput: this.holder === 'human' ? 'revoked' : 'open',
+            ...(this.holder === 'human' && this.holdExpiresAt
+                ? { holdExpiresAt: new Date(this.holdExpiresAt).toISOString() }
+                : {}),
+        });
+    }
+    async refresh() {
+        if (!this.source && this.upstream) {
+            this.probed = (await probePort(this.upstream.port)) ? 'ready' : 'display_not_started';
+        }
+        return this.snapshot();
+    }
+    async handleHttp(request, response, url) {
+        if (this.disposed || this.state.journal.destroyed()) {
+            writeError(response, 'runtime_destroyed');
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/desktop/health') {
+            writeJson(response, 200, await this.refresh());
+            return;
+        }
+        if (request.method === 'POST' && url.pathname === '/runtime/desktop/open') {
+            await this.refresh();
+            if (this.currentStatus() !== 'ready') {
+                writeError(response, this.currentStatus());
+                return;
+            }
+            if (this.holder === 'human') {
+                writeJson(response, 200, this.snapshot());
+                return;
+            }
+            try {
+                this.preview ??= new DesktopPreviewHost(this.state, {
+                    canNavigate: () => !this.disposed && !this.state.journal.destroyed() && this.holder !== 'human',
+                });
+                await this.preview.open(url.searchParams.get('workspaceId') ?? undefined, url.searchParams.get('directoryName') ?? 'basic');
+                if (this.disposed || this.state.journal.destroyed()) {
+                    writeError(response, 'runtime_destroyed');
+                    return;
+                }
+                const health = await this.refresh();
+                if (this.disposed || this.state.journal.destroyed()) {
+                    writeError(response, 'runtime_destroyed');
+                    return;
+                }
+                if (health.status !== 'ready') {
+                    writeError(response, health.status);
+                    return;
+                }
+                writeJson(response, 200, health);
+            }
+            catch (error) {
+                const reason = error instanceof DesktopPreviewError ? error.code
+                    : error instanceof WorkspaceContextError ? error.message : 'desktop_preview_start_failed';
+                writeError(response, reason);
+            }
+            return;
+        }
+        if (request.method === 'POST' && url.pathname === '/runtime/desktop/takeover') {
+            await this.refresh();
+            if (this.currentStatus() !== 'ready') {
+                writeError(response, this.currentStatus());
+                return;
+            }
+            this.holder = 'human';
+            this.cutViewers();
+            this.hold();
+            writeJson(response, 200, this.snapshot());
+            return;
+        }
+        if (request.method === 'POST' && url.pathname === '/runtime/desktop/renew') {
+            if (this.holder !== 'human') {
+                writeError(response, 'desktop_not_held');
+                return;
+            }
+            this.hold();
+            writeJson(response, 200, this.snapshot());
+            return;
+        }
+        if (request.method === 'DELETE' && url.pathname === '/runtime/desktop') {
+            this.release();
+            writeJson(response, 200, this.snapshot());
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/desktop/connect') {
+            await this.refresh();
+            this.rejectPlainConnect(response, url);
+            return;
+        }
+        if (request.method === 'GET' && url.pathname.startsWith('/runtime/desktop/resources/')) {
+            await this.refresh();
+            await this.writeResource(response, url);
+            return;
+        }
+        writeJson(response, 404, { error: 'not_found' });
+    }
+    handleUpgrade(request, socket, head) {
+        const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+        if (!controlTokenMatches(this.state.config.controlToken, extractControlToken(request.headers))) {
+            rejectUpgrade(socket, 401, runtimeError('unauthenticated', 'control_token_required'));
+            return;
+        }
+        if (this.disposed || this.state.journal.destroyed()) {
+            rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'runtime_destroyed'));
+            return;
+        }
+        if (this.currentStatus() !== 'ready') {
+            rejectUpgrade(socket, 409, runtimeError('capability_unavailable', this.currentStatus()));
+            return;
+        }
+        const generation = generationOf(url);
+        if (generation === undefined || generation !== this.generation) {
+            rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'desktop_stale'));
+            return;
+        }
+        this.sockets.handleUpgrade(request, socket, head, (ws) => this.attach(ws, generation));
+    }
+    async dispose() {
+        this.disposed = true;
+        this.release();
+        this.sockets.close();
+        await this.preview?.dispose();
+    }
+    release() {
+        this.clearHold();
+        this.holder = 'none';
+        this.cutViewers();
+    }
+    /** Starts or renews the hold; when it runs out the desktop is released as if by hand. */
+    hold() {
+        this.clearHold();
+        this.holdExpiresAt = Date.now() + this.holdMs;
+        this.holdTimer = setTimeout(() => {
+            this.holdTimer = undefined;
+            if (this.holder === 'human')
+                this.release();
+        }, this.holdMs);
+        this.holdTimer.unref?.();
+    }
+    clearHold() {
+        if (this.holdTimer)
+            clearTimeout(this.holdTimer);
+        this.holdTimer = undefined;
+        this.holdExpiresAt = undefined;
+    }
+    currentStatus() {
+        if (this.source)
+            return this.source.health().status;
+        if (this.upstream)
+            return this.probed;
+        return 'display_not_started';
+    }
+    cutViewers() {
+        this.generation += 1;
+        for (const viewer of this.viewers)
+            this.drop(viewer);
+        this.viewers.clear();
+    }
+    drop(viewer) {
+        viewer.detach();
+        viewer.upstream?.close();
+        if (viewer.ws.readyState === WebSocket.OPEN)
+            viewer.ws.close();
+    }
+    attach(ws, generation) {
+        const viewer = { generation, ws, detach: () => undefined };
+        const send = (chunk, binary = true) => {
+            if (this.generation !== generation || ws.readyState !== WebSocket.OPEN)
+                return;
+            ws.send(chunk, { binary });
+        };
+        if (this.source) {
+            viewer.detach = this.source.attach(generation, (chunk) => send(chunk));
+        }
+        else if (this.upstream) {
+            const upstream = new WebSocket(`ws://127.0.0.1:${this.upstream.port}/`);
+            const watch = createRfbWatchGate();
+            viewer.upstream = upstream;
+            viewer.detach = () => upstream.close();
+            upstream.on('error', () => {
+                if (!this.source && this.generation === generation)
+                    this.probed = 'display_unavailable';
+                if (ws.readyState === WebSocket.OPEN)
+                    ws.close(1011, 'desktop_unavailable');
+            });
+            upstream.on('message', (data, isBinary) => {
+                if (this.generation !== generation) {
+                    this.drop(viewer);
+                    return;
+                }
+                const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data);
+                watch.observeServer(chunk);
+                if (watch.failed) {
+                    ws.close(1008, 'desktop_protocol_error');
+                    upstream.close();
+                    return;
+                }
+                send(chunk, isBinary);
+            });
+            upstream.on('close', () => {
+                if (ws.readyState === WebSocket.OPEN)
+                    ws.close();
+            });
+            ws.on('message', (data, isBinary) => {
+                if (this.generation !== generation)
+                    return;
+                const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data);
+                if (viewer.upstream?.readyState !== WebSocket.OPEN)
+                    return;
+                const outgoing = watch.clientBytes(chunk, this.holder === 'human');
+                if (watch.failed) {
+                    ws.close(1008, 'desktop_protocol_error');
+                    upstream.close();
+                    return;
+                }
+                for (const message of outgoing) {
+                    viewer.upstream.send(message, { binary: isBinary });
+                }
+            });
+        }
+        this.viewers.add(viewer);
+        let closed = false;
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            this.viewers.delete(viewer);
+            viewer.detach();
+            viewer.upstream?.close();
+        };
+        ws.on('close', close);
+        ws.on('error', close);
+    }
+    rejectPlainConnect(response, url) {
+        if (this.currentStatus() !== 'ready') {
+            writeError(response, this.currentStatus());
+            return;
+        }
+        const generation = generationOf(url);
+        if (generation === undefined || generation !== this.generation) {
+            writeError(response, 'desktop_stale');
+            return;
+        }
+        writeError(response, 'websocket_required');
+    }
+    async writeResource(response, url) {
+        if (this.currentStatus() !== 'ready') {
+            writeError(response, this.currentStatus());
+            return;
+        }
+        const name = desktopResourceName(decodeURIComponent(url.pathname.slice('/runtime/desktop/resources/'.length)));
+        if (!name) {
+            writeJson(response, 400, { error: 'invalid_desktop_resource' });
+            return;
+        }
+        const generation = url.searchParams.get('generation');
+        const document = name === 'vnc.html' || name.endsWith('/vnc.html');
+        if (document && Number(generation) !== this.generation) {
+            writeError(response, 'desktop_stale');
+            return;
+        }
+        if (generation !== null && Number(generation) !== this.generation) {
+            writeError(response, 'desktop_stale');
+            return;
+        }
+        if (this.source) {
+            const file = this.source.readResource(name);
+            if (!file) {
+                writeJson(response, 404, { error: 'not_found' });
+                return;
+            }
+            writeBytes(response, 200, file.contentType, file.body);
+            return;
+        }
+        if (!this.upstream) {
+            writeError(response, 'display_not_started');
+            return;
+        }
+        const upstream = await fetch(`http://127.0.0.1:${this.upstream.port}/${name}`, {
+            redirect: 'error',
+            signal: AbortSignal.timeout(5_000),
+        }).catch(() => undefined);
+        if (!upstream) {
+            writeError(response, 'display_unavailable');
+            return;
+        }
+        const body = Buffer.from(await upstream.arrayBuffer());
+        if (!upstream.ok) {
+            writeBytes(response, upstream.status, upstream.headers.get('content-type') ?? 'application/octet-stream', body);
+            return;
+        }
+        writeBytes(response, 200, upstream.headers.get('content-type') ?? 'application/octet-stream', body);
+    }
+}
+export function desktopRoute(pathname) {
+    return (pathname === '/runtime/desktop/health' ||
+        pathname === '/runtime/desktop/open' ||
+        pathname === '/runtime/desktop/connect' ||
+        pathname === '/runtime/desktop/takeover' ||
+        pathname === '/runtime/desktop/renew' ||
+        pathname === '/runtime/desktop' ||
+        pathname.startsWith('/runtime/desktop/resources/'));
+}
+function generationOf(url) {
+    const value = url.searchParams.get('generation');
+    if (!value || !/^\d+$/.test(value))
+        return undefined;
+    return Number(value);
+}
+function loopbackUpstream(value) {
+    if (!value)
+        return undefined;
+    const match = /^(?:127\.0\.0\.1|localhost):(\d+)$/.exec(value.trim());
+    if (!match)
+        return undefined;
+    const port = Number(match[1]);
+    if (port < 1 || port > 65535)
+        return undefined;
+    return { port };
+}
+function holdDuration(value) {
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : HOLD_MS;
+}
+function probePort(port) {
+    return new Promise((resolve) => {
+        const socket = connectTcp({ host: '127.0.0.1', port });
+        const timer = setTimeout(() => {
+            socket.destroy();
+            resolve(false);
+        }, 200);
+        socket.once('connect', () => {
+            clearTimeout(timer);
+            socket.end();
+            resolve(true);
+        });
+        socket.once('error', () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+    });
+}
+function writeError(response, reason) {
+    writeJson(response, 409, runtimeError('capability_unavailable', reason));
+}
+function writeJson(response, status, body) {
+    const payload = JSON.stringify(body);
+    response.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(payload),
+        'cache-control': 'no-store',
+    });
+    response.end(payload);
+}
+function writeBytes(response, status, contentType, body) {
+    response.writeHead(status, {
+        'content-type': contentType,
+        'content-length': body.length,
+        'cache-control': 'no-store',
+    });
+    response.end(body);
+}
+function rejectUpgrade(socket, status, body) {
+    const payload = JSON.stringify(body);
+    const title = status === 401 ? 'Unauthorized' : 'Conflict';
+    socket.write(`HTTP/1.1 ${status} ${title}\r\ncontent-type: application/json; charset=utf-8\r\ncontent-length: ${Buffer.byteLength(payload)}\r\nconnection: close\r\n\r\n${payload}`);
+    socket.destroy();
+}

package/dist/workspace-runtime/server/desktop-preview-config.js

@@ -0,0 +1,81 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { DesktopPreviewError } from './desktop-preview.js';
+import JSON5 from 'json5';
+export async function previewPlan(root) {
+    const config = await optionalJson(root, '.playcraft/workspace.json');
+    const preview = object(config?.preview);
+    if (config?.preview !== undefined) {
+        if (!preview || typeof preview !== 'object' || typeof preview.command !== 'string' || !preview.command.trim()
+            || (preview.cwd !== undefined && typeof preview.cwd !== 'string') || (preview.path !== undefined && typeof preview.path !== 'string')) {
+            throw new DesktopPreviewError('desktop_preview_unconfigured');
+        }
+        const cwd = typeof preview.cwd === 'string' ? preview.cwd : '.';
+        if (isAbsolute(cwd))
+            throw new DesktopPreviewError('desktop_preview_unconfigured');
+        let realRoot;
+        try {
+            realRoot = await realpath(join(root, cwd));
+        }
+        catch {
+            throw new DesktopPreviewError('desktop_preview_unconfigured');
+        }
+        const resolved = relative(await realpath(root), realRoot);
+        if (resolved === '..' || resolved.startsWith(`..${sep}`) || !(await stat(realRoot)).isDirectory()) {
+            throw new DesktopPreviewError('desktop_preview_unconfigured');
+        }
+        return { root: realRoot, command: preview.command, path: entryPath(preview.path), dependencies: await exists(join(realRoot, 'package.json')) };
+    }
+    const manifest = await optionalJson(root, 'package.json');
+    if (manifest) {
+        const dev = object(manifest.scripts)?.dev;
+        const vite = object(manifest.dependencies)?.vite ?? object(manifest.devDependencies)?.vite;
+        if (typeof dev === 'string' && /^\s*vite(?:\s|$)/.test(dev) && typeof vite === 'string') {
+            return { root, command: 'pnpm run dev --host 127.0.0.1 --port {port} --strictPort', path: '/', dependencies: true };
+        }
+        throw new DesktopPreviewError('desktop_preview_unconfigured');
+    }
+    return { root, path: '/', dependencies: false, welcome: !await exists(join(root, 'index.html')) };
+}
+function entryPath(path) {
+    if (path === undefined)
+        return '/';
+    if (typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//') || path.includes('\\')) {
+        throw new DesktopPreviewError('desktop_preview_unconfigured');
+    }
+    const url = new URL(path, 'http://127.0.0.1');
+    if (url.origin !== 'http://127.0.0.1')
+        throw new DesktopPreviewError('desktop_preview_unconfigured');
+    return `${url.pathname}${url.search}${url.hash}`;
+}
+async function exists(path) { try {
+    return (await stat(path)).isFile();
+}
+catch {
+    return false;
+} }
+export async function requiresNodeModules(root) {
+    const manifest = await optionalJson(root, 'package.json');
+    return ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']
+        .some((key) => Object.keys(object(manifest?.[key]) ?? {}).length > 0);
+}
+async function optionalJson(root, path) {
+    try {
+        const resolved = await realpath(join(root, path));
+        const location = relative(await realpath(root), resolved);
+        if (location === '..' || location.startsWith(`..${sep}`))
+            throw new DesktopPreviewError('desktop_preview_unconfigured');
+        const result = object(JSON5.parse(await readFile(resolved, 'utf8')));
+        if (!result)
+            throw new DesktopPreviewError('desktop_preview_unconfigured');
+        return result;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new DesktopPreviewError('desktop_preview_unconfigured');
+    }
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}

package/dist/workspace-runtime/server/desktop-preview-service.js

@@ -0,0 +1,157 @@
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:net';
+import { setTimeout as delay } from 'node:timers/promises';
+import { startLauncherProcess } from '../codex/launcher-client.js';
+import { DesktopPreviewError, quote } from './desktop-preview.js';
+// The supervisor runs under the same developer identity as its service. It proves that the
+// loopback listener belongs to its process group before Runtime probes the configured page.
+const supervisor = String.raw `
+const fs = require('node:fs');
+const {spawn,execFileSync} = require('node:child_process');
+const [command,portText,marker] = process.argv.slice(1);
+const port = Number(portText);
+const child = spawn(process.platform==='linux'?'/usr/bin/bash':'/bin/bash',['-lc',command],{stdio:['ignore','inherit','inherit']});
+child.on('error',()=>process.exit(97));
+child.on('exit',code=>process.exit(code === 0 ? 97 : code || 97));
+function listeners() {
+  if (process.platform === 'linux') {
+    const sockets = ['tcp','tcp6'].flatMap(kind => fs.readFileSync('/proc/net/'+kind,'utf8').trim().split('\n').slice(1).flatMap(line=>{
+      const columns=line.trim().split(/\s+/); const [address,p]=columns[1].split(':');
+      return parseInt(p,16)===port && columns[3]==='0A' ? [{id:columns[9],local:address==='0100007F'||address==='00000000000000000000000001000000'}] : [];
+    }));
+    const owned=new Set();
+    for (const pid of fs.readdirSync('/proc').filter(name=>/^\d+$/.test(name))) {
+      try {
+        const stat=fs.readFileSync('/proc/'+pid+'/stat','utf8');
+        if (Number(stat.slice(stat.lastIndexOf(')')+2).split(' ')[2])!==process.pid) continue;
+        for (const fd of fs.readdirSync('/proc/'+pid+'/fd')) {
+          try { const match=fs.readlinkSync('/proc/'+pid+'/fd/'+fd).match(/^socket:\[(\d+)\]$/); if(match)owned.add(match[1]); } catch {}
+        }
+      } catch {}
+    }
+    return sockets.map(socket=>({local:socket.local,owned:owned.has(socket.id)}));
+  }
+  const pids=new Set(execFileSync('/bin/ps',['-axo','pid=,pgid='],{encoding:'utf8'}).trim().split('\n').flatMap(line=>{
+    const [pid,group]=line.trim().split(/\s+/); return Number(group)===process.pid?[Number(pid)]:[];
+  }));
+  let listing='';try{listing=execFileSync('/usr/sbin/lsof',['-nP','-iTCP:'+port,'-sTCP:LISTEN','-Fpn'],{encoding:'utf8',stdio:['ignore','pipe','ignore']});}catch{}
+  let pid=0;return listing.split('\n').flatMap(line=>{
+    if(line.startsWith('p'))pid=Number(line.slice(1));
+    return line.startsWith('n')?[{local:line.slice(1).startsWith('127.0.0.1:')||line.slice(1).startsWith('[::1]:'),owned:pids.has(pid)}]:[];
+  });
+}
+let ready=false;
+const timer=setInterval(()=>{
+  try {
+    const found=listeners();
+    if(found.some(socket=>!socket.local||!socket.owned)){console.log(marker+':port');process.exit(98);}
+    if(!ready&&found.some(socket=>socket.owned)){ready=true;clearInterval(timer);console.log(marker+':ready');}
+  } catch {console.log(marker+':failed');process.exit(97);}
+},50);
+`;
+export async function startManagedPreview(input) {
+    const { state, options } = input;
+    const socketPath = options.launcherSocket ?? process.env.PLAYCRAFT_LAUNCHER_SOCKET;
+    if (!socketPath)
+        throw new DesktopPreviewError('desktop_preview_start_failed');
+    const port = await reservePort();
+    const url = new URL(input.path, `http://127.0.0.1:${port}/`).href;
+    const marker = `PLAYCRAFT_PREVIEW_${randomUUID()}`;
+    const command = `export HOST=127.0.0.1 PORT=${port} PLAYCRAFT_PREVIEW_PORT=${port}; exec ${quote(process.execPath)} -e ${quote(supervisor)} -- ${quote(input.command.replaceAll('{port}', String(port)))} ${port} ${quote(marker)}`;
+    const processHandle = await launchPreviewProcess({ socketPath,
+        processId: `desktop-preview-service-${randomUUID()}`, runtimeEpoch: state.runtimeEpoch,
+        argv: ['/usr/bin/bash', '-lc', command], cwd: input.root, env: {} }, options, input.deadline, input.cancelled, 'desktop_preview_start_failed');
+    if (!processHandle)
+        return undefined;
+    let alive = true;
+    let stopped = false;
+    let stopping;
+    let owned = false;
+    let failure;
+    let tail = '';
+    processHandle.onExit((code) => { alive = false; failure ??= code === 98 ? 'desktop_preview_port_unavailable' : 'desktop_preview_start_failed'; });
+    processHandle.stdout?.on('data', (chunk) => {
+        tail = (tail + chunk.toString('utf8')).slice(-8192);
+        if (tail.includes(`${marker}:ready`))
+            owned = true;
+        if (tail.includes(`${marker}:port`))
+            failure = 'desktop_preview_port_unavailable';
+        if (tail.includes(`${marker}:failed`))
+            failure = 'desktop_preview_start_failed';
+    });
+    processHandle.stderr?.resume();
+    const stop = () => stopping ??= processHandle.stop().then(() => { stopped = true; alive = false; });
+    try {
+        while (Date.now() < input.deadline) {
+            if (input.cancelled()) {
+                await stop();
+                return undefined;
+            }
+            if (!alive || failure)
+                throw new DesktopPreviewError(failure ?? 'desktop_preview_start_failed');
+            if (owned) {
+                try {
+                    const response = await fetch(url, { signal: AbortSignal.timeout(Math.min(500, Math.max(1, input.deadline - Date.now()))) });
+                    await response.body?.cancel();
+                    if (response.ok && alive)
+                        return { url, alive: () => alive && !stopped && !stopping, stop };
+                }
+                catch { }
+            }
+            await delay(options.pollIntervalMs ?? 100);
+        }
+        throw new DesktopPreviewError('desktop_preview_timeout');
+    }
+    catch (error) {
+        await stop();
+        throw error;
+    }
+}
+/** Starting the launcher is bounded too; late replies are stopped after cancellation. */
+export async function launchPreviewProcess(input, options, deadline, cancelled, failure) {
+    let finished = false;
+    let abandoned = false;
+    let failed = false;
+    let child;
+    void (options.startProcess ?? startLauncherProcess)(input).then((value) => {
+        child = value;
+        finished = true;
+        if (abandoned)
+            void value.stop().catch(() => undefined);
+    }, () => { finished = true; failed = true; });
+    while (!finished) {
+        if (cancelled()) {
+            abandoned = true;
+            return undefined;
+        }
+        if (Date.now() >= deadline) {
+            abandoned = true;
+            throw new DesktopPreviewError('desktop_preview_timeout');
+        }
+        await delay(Math.min(options.pollIntervalMs ?? 50, Math.max(1, deadline - Date.now())));
+    }
+    if (failed || !child)
+        throw new DesktopPreviewError(failure);
+    if (cancelled()) {
+        await child.stop();
+        return undefined;
+    }
+    return child;
+}
+async function reservePort() {
+    const server = createServer();
+    try {
+        await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+        const address = server.address();
+        if (!address || typeof address === 'string')
+            throw new Error('port_unavailable');
+        return address.port;
+    }
+    catch {
+        throw new DesktopPreviewError('desktop_preview_port_unavailable');
+    }
+    finally {
+        if (server.listening)
+            await new Promise((resolve) => server.close(() => resolve()));
+    }
+}