@playcraft/cli 0.1.12 → 0.1.14

package/dist/workspace-runtime/serve.js

@@ -120,19 +120,24 @@ export async function startWorkspaceRuntime(config, options = {}) {
             state,
             url: `http://${formatHost(config.listen.host)}:${port}`,
             async close() {
+                const serverClosed = closeServer(server);
                 await closeCliCredentials(state);
                 await gitCredentials?.close();
-                disposeDesktopHost(state);
-                disposeTerminalHost(state);
-                await closeServer(server);
                 try {
-                    await native?.close?.();
+                    await disposeDesktopHost(state);
                 }
-                catch {
-                    /* adapter shutdown is best-effort */
+                finally {
+                    disposeTerminalHost(state);
+                    try {
+                        await native?.close?.();
+                    }
+                    catch {
+                        /* adapter shutdown is best-effort */
+                    }
+                    await serverClosed;
+                    await journal?.close();
+                    lock.release();
                 }
-                await journal?.close();
-                lock.release();
             },
         };
     }

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

@@ -2,6 +2,9 @@ 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.
@@ -24,10 +27,11 @@ export function desktopHost(state) {
     }
     return host;
 }
-export function disposeDesktopHost(state) {
-    hosts.get(state)?.dispose();
+export async function disposeDesktopHost(state) {
+    const host = hosts.get(state);
     hosts.delete(state);
     sources.delete(state);
+    await host?.dispose();
 }
 export class DesktopHost {
     state;
@@ -41,6 +45,8 @@ export class DesktopHost {
     holdMs = holdDuration(process.env.PLAYCRAFT_DESKTOP_HOLD_MS);
     holdExpiresAt;
     holdTimer;
+    preview;
+    disposed = false;
     constructor(state) {
         this.state = state;
         this.source = sources.get(state);
@@ -66,7 +72,7 @@ export class DesktopHost {
         return this.snapshot();
     }
     async handleHttp(request, response, url) {
-        if (this.state.journal.destroyed()) {
+        if (this.disposed || this.state.journal.destroyed()) {
             writeError(response, 'runtime_destroyed');
             return;
         }
@@ -74,6 +80,43 @@ export class DesktopHost {
             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);
+                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') {
@@ -118,7 +161,7 @@ export class DesktopHost {
             rejectUpgrade(socket, 401, runtimeError('unauthenticated', 'control_token_required'));
             return;
         }
-        if (this.state.journal.destroyed()) {
+        if (this.disposed || this.state.journal.destroyed()) {
             rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'runtime_destroyed'));
             return;
         }
@@ -133,9 +176,11 @@ export class DesktopHost {
         }
         this.sockets.handleUpgrade(request, socket, head, (ws) => this.attach(ws, generation));
     }
-    dispose() {
+    async dispose() {
+        this.disposed = true;
         this.release();
         this.sockets.close();
+        await this.preview?.dispose();
     }
     release() {
         this.clearHold();
@@ -190,6 +235,7 @@ export class DesktopHost {
         }
         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', () => {
@@ -204,12 +250,34 @@ export class DesktopHost {
                     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;
@@ -223,12 +291,6 @@ export class DesktopHost {
         };
         ws.on('close', close);
         ws.on('error', close);
-        ws.on('message', (data, isBinary) => {
-            if (this.holder !== 'human' || this.generation !== generation)
-                return;
-            if (viewer.upstream?.readyState === WebSocket.OPEN)
-                viewer.upstream.send(data, { binary: isBinary });
-        });
     }
     rejectPlainConnect(response, url) {
         if (this.currentStatus() !== 'ready') {
@@ -293,6 +355,7 @@ export class DesktopHost {
 }
 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' ||

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()));
+    }
+}

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

@@ -0,0 +1,53 @@
+import { createServer } from 'node:http';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { extname, join, relative, sep } from 'node:path';
+const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml',
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.webp': 'image/webp', '.wasm': 'application/wasm' };
+export async function startStaticPreview(root, welcome = false) {
+    const realRoot = await realpath(root);
+    const server = createServer((request, response) => {
+        void (async () => {
+            try {
+                const pathname = decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname);
+                if (welcome && pathname === '/') {
+                    response.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+                    response.end(welcomePage());
+                    return;
+                }
+                const segments = pathname.split('/').filter(Boolean);
+                if (segments.some((segment) => segment.startsWith('.')))
+                    throw new Error('hidden_path');
+                const target = await realpath(join(realRoot, ...segments, ...(pathname.endsWith('/') ? ['index.html'] : [])));
+                const path = relative(realRoot, target);
+                if (path === '..' || path.startsWith(`..${sep}`) || !(await stat(target)).isFile())
+                    throw new Error('outside_root');
+                const body = await readFile(target);
+                response.writeHead(200, { 'content-type': types[extname(target)] ?? 'application/octet-stream', 'cache-control': 'no-store' });
+                response.end(request.method === 'HEAD' ? undefined : body);
+            }
+            catch {
+                response.writeHead(404);
+                response.end();
+            }
+        })();
+    });
+    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('preview_port_unavailable');
+    let stopped = false;
+    return { url: `http://127.0.0.1:${address.port}/`, alive: () => server.listening && !stopped,
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            server.closeAllConnections();
+            await new Promise((resolve) => server.close(() => resolve()));
+        } };
+}
+function welcomePage() {
+    const messages = { en: { title: 'Your workspace desktop is ready', body: 'Add a project to see its preview here.' },
+        zh: { title: '工作区桌面已就绪', body: '添加项目后，这里会显示项目预览。' } };
+    return `<!doctype html><html lang="en"><meta charset="utf-8"><title>${messages.en.title}</title><style>body{margin:0;background:#f1f0eb;color:#252724;font:22px system-ui;display:grid;min-height:100vh;place-items:center}main{max-width:680px;padding:48px}h1{font-size:42px}p{line-height:1.7;color:#596159}</style><main><h1>${messages.en.title}</h1><p>${messages.en.body}</p><h2 lang="zh">${messages.zh.title}</h2><p lang="zh">${messages.zh.body}</p></main></html>`;
+}

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

@@ -0,0 +1,189 @@
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { join } from 'node:path';
+import { lstat } from 'node:fs/promises';
+import { workspaceRoot, WorkspaceContextError } from '../workspaces/registry.js';
+import { startStaticPreview } from './desktop-preview-static.js';
+import { previewPlan, requiresNodeModules } from './desktop-preview-config.js';
+import { launchPreviewProcess, startManagedPreview } from './desktop-preview-service.js';
+import { planInstall, scheduleDependencyInstall, readDependencies } from '../workspaces/dependencies.js';
+export class DesktopPreviewError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'DesktopPreviewError';
+    }
+}
+/** One visible browser; project services and browser profiles survive workspace switches. */
+export class DesktopPreviewHost {
+    state;
+    options;
+    pending = new Map();
+    servers = new Map();
+    emptyDependencyReady = new Map();
+    activeBrowser;
+    activation = Promise.resolve();
+    disposed = false;
+    disposal;
+    requestedKey;
+    constructor(state, options = {}) {
+        this.state = state;
+        this.options = options;
+    }
+    open(workspaceId) {
+        if (!this.canNavigate())
+            return Promise.resolve();
+        const key = workspaceId ?? 'single';
+        this.requestedKey = key;
+        const existing = this.pending.get(key);
+        if (existing)
+            return existing;
+        const task = this.openWorkspace(key, workspaceId).catch((error) => {
+            if (error instanceof DesktopPreviewError || error instanceof WorkspaceContextError)
+                throw error;
+            throw new DesktopPreviewError('desktop_preview_start_failed');
+        }).finally(() => this.pending.delete(key));
+        this.pending.set(key, task);
+        return task;
+    }
+    dispose() {
+        if (this.disposal)
+            return this.disposal;
+        this.disposed = true;
+        this.disposal = (async () => {
+            const stopped = await Promise.allSettled([
+                ...(this.activeBrowser ? [this.activeBrowser.process.stop()] : []),
+                ...[...this.servers.values()].map(({ server }) => server.stop()),
+            ]);
+            await Promise.allSettled([...this.pending.values()]);
+            this.servers.clear();
+            this.activeBrowser = undefined;
+            if (stopped.some((result) => result.status === 'rejected'))
+                throw new DesktopPreviewError('desktop_preview_start_failed');
+        })();
+        return this.disposal;
+    }
+    canNavigate() {
+        return !this.disposed && !this.state.journal.destroyed() && (this.options.canNavigate?.() ?? true);
+    }
+    async openWorkspace(key, workspaceId) {
+        const root = await workspaceRoot(this.state, workspaceId);
+        const deadline = Date.now() + (this.options.timeoutMs ?? 90_000);
+        if (!this.canNavigate())
+            return;
+        const plan = await previewPlan(root);
+        if (!this.canNavigate())
+            return;
+        if (plan.dependencies) {
+            const dependencyDeadline = Math.min(deadline, Date.now() + (this.options.dependencyTimeoutMs ?? 60_000));
+            if (!await this.ensureDependencies(key, plan.root, dependencyDeadline))
+                return;
+        }
+        if (!this.canNavigate())
+            return;
+        const signature = JSON.stringify(plan);
+        const entry = this.servers.get(key);
+        let server = entry?.server;
+        if (!server?.alive() || entry?.signature !== signature) {
+            await server?.stop();
+            if (!this.canNavigate())
+                return;
+            server = plan.command ? await startManagedPreview({ state: this.state, options: this.options,
+                root: plan.root, command: plan.command, path: plan.path, deadline, cancelled: () => !this.canNavigate() }) : await startStaticPreview(root, plan.welcome);
+            if (!server)
+                return;
+            if (!this.canNavigate()) {
+                await server.stop();
+                return;
+            }
+            this.servers.set(key, { server, signature });
+        }
+        const current = this.activation.then(() => this.activate(key, root, server, deadline));
+        this.activation = current.catch(() => undefined);
+        await current;
+    }
+    async ensureDependencies(key, root, deadline) {
+        const initialPlan = await planInstall(root);
+        if (initialPlan.kind === 'install' && !await requiresNodeModules(root)
+            && this.emptyDependencyReady.get(root) === initialPlan.lockHash)
+            return this.canNavigate();
+        let finished = false;
+        const install = () => {
+            finished = false;
+            void scheduleDependencyInstall(this.state, key, root, () => this.canNavigate()).finally(() => { finished = true; });
+        };
+        if (!this.canNavigate())
+            return false;
+        install();
+        while (Date.now() < deadline) {
+            if (!this.canNavigate())
+                return false;
+            if (finished) {
+                const current = await planInstall(root);
+                if (!this.canNavigate())
+                    return false;
+                const record = readDependencies(this.state, key);
+                if (record.status === 'failed')
+                    throw new DesktopPreviewError('dependencies_not_ready');
+                if (current.kind === 'skip' && record.status === 'none')
+                    return true;
+                if (current.kind === 'install' && record.status === 'ready' && !await requiresNodeModules(root)) {
+                    this.emptyDependencyReady.set(root, current.lockHash);
+                    return this.canNavigate();
+                }
+                if (current.kind === 'install' && record.lockHash === current.lockHash) {
+                    const modules = await lstat(join(root, 'node_modules')).catch(() => undefined);
+                    if (record.status === 'ready' && modules?.isDirectory() && !modules.isSymbolicLink())
+                        return true;
+                }
+                // A changed manifest or lockfile needs a current install before this project can start.
+                if (!this.canNavigate())
+                    return false;
+                install();
+            }
+            await delay(this.options.pollIntervalMs ?? 100);
+        }
+        if (!this.canNavigate())
+            return false;
+        throw new DesktopPreviewError('dependencies_not_ready');
+    }
+    async activate(key, root, server, deadline) {
+        const canActivate = () => this.canNavigate() && this.requestedKey === key;
+        if (!canActivate())
+            return;
+        if (this.activeBrowser?.alive && this.activeBrowser.key === key && this.activeBrowser.server === server)
+            return;
+        if (Date.now() >= deadline)
+            throw new DesktopPreviewError('desktop_preview_timeout');
+        const socketPath = this.options.launcherSocket ?? process.env.PLAYCRAFT_LAUNCHER_SOCKET;
+        if (!socketPath)
+            throw new DesktopPreviewError('desktop_browser_unavailable');
+        if (this.activeBrowser)
+            await this.activeBrowser.process.stop();
+        this.activeBrowser = undefined;
+        if (!canActivate())
+            return;
+        const profile = join(this.options.profileRoot ?? '/home/playcraft-dev/.cache/playcraft-desktop', key);
+        const executable = this.options.browserExecutable ?? '/usr/bin/chromium';
+        const command = `test -x ${quote(executable)} || exit 127; mkdir -p -- ${quote(profile)} || exit 1; exec ${quote(executable)} --no-first-run --no-default-browser-check --disable-dev-shm-usage --start-maximized --user-data-dir=${quote(profile)} --app=${quote(server.url)}`;
+        const child = await launchPreviewProcess({ socketPath,
+            processId: `desktop-preview-browser-${randomUUID()}`, runtimeEpoch: this.state.runtimeEpoch,
+            argv: ['/usr/bin/bash', '-lc', command], cwd: root, env: { DISPLAY: process.env.DISPLAY ?? ':0' } }, this.options, deadline, () => !canActivate(), 'desktop_browser_start_failed');
+        if (!child)
+            return;
+        const browser = { key, server, process: child, alive: true };
+        let exitCode;
+        child.onExit((code) => { browser.alive = false; exitCode = code; });
+        child.stdout?.resume();
+        child.stderr?.resume();
+        this.activeBrowser = browser;
+        await delay(150);
+        if (!browser.alive) {
+            await child.stop();
+            this.activeBrowser = undefined;
+            throw new DesktopPreviewError(exitCode === 127 ? 'desktop_browser_unavailable' : 'desktop_browser_start_failed');
+        }
+    }
+}
+export function quote(value) { return `'${value.replaceAll("'", "'\\''")}'`; }

package/dist/workspace-runtime/server/dispatch.js

@@ -10,6 +10,7 @@ import { loadWorkspaceSkillArtifact } from '../workspaces/skill-artifact-loader.
 import { enableLocalProjectSkill, syncLocalProjectSkills } from '../../project-skills/local-store.js';
 import { NativePreparationError } from '../codex/native-adapter.js';
 import { disposeTerminalHost } from './terminal-host.js';
+import { disposeDesktopHost } from './desktop-host.js';
 import { captureWorkspaceTree, liveTreeDigest, materializeSnapshot, publishFileSnapshot, } from '../workspaces/file-snapshot.js';
 import { objectStoreHeaders, oneSaveAtATime, rememberFileCheckpoint, unchangedCheckpoint, workspaceSaves, } from '../workspaces/checkpoint-saves.js';
 import { InvalidWorkspacePathError, resolveWorkspaceFile, restoreWorkspaceFiles, snapshotWorkspaceFiles, writeWorkspaceFile, } from '../workspaces/files.js';
@@ -590,10 +591,15 @@ async function executeDestroy(state, scopeKey, operation) {
     await state.gitCredentials?.destroy();
     disposeTerminalHost(state);
     try {
-        await state.native?.close?.();
+        await disposeDesktopHost(state);
     }
-    catch {
-        /* Codex process shutdown is best-effort once the runtime is destroyed */
+    finally {
+        try {
+            await state.native?.close?.();
+        }
+        catch {
+            /* Codex process shutdown is best-effort once the runtime is destroyed */
+        }
     }
     const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted'));
     await recordNativeEvents(state, accepted, [

package/dist/workspace-runtime/server/rfb-watch-gate.js

@@ -0,0 +1,168 @@
+/**
+ * RFB (Remote Framebuffer, 远程帧缓冲) viewing needs a handshake and picture requests.
+ * This gate supports the sandbox's version 3.8 / None security negotiation.
+ * Input requires a hold for the entire message; unsupported framing closes the stream.
+ */
+const INPUT_TYPES = new Set([4, 5, 6, 250, 251, 255]);
+const VERSION = Buffer.from('RFB 003.008\n');
+const MAX_CLIPBOARD_BYTES = 1_000_000;
+export function createRfbWatchGate() {
+    let server = Buffer.alloc(0);
+    let client = Buffer.alloc(0);
+    let phase = 'server-version';
+    let messageInputAllowed = false;
+    const fail = () => {
+        phase = 'failed';
+        server = Buffer.alloc(0);
+        client = Buffer.alloc(0);
+    };
+    const observeServer = (chunk) => {
+        if (phase === 'ready' || phase === 'failed')
+            return;
+        let offset = 0;
+        while (offset < chunk.length) {
+            let size = serverMessageSize(server, phase);
+            if (size === 'invalid') {
+                fail();
+                return;
+            }
+            const count = Math.min(size - server.length, chunk.length - offset);
+            server = Buffer.concat([server, chunk.subarray(offset, offset + count)]);
+            offset += count;
+            size = serverMessageSize(server, phase);
+            if (size === 'invalid') {
+                fail();
+                return;
+            }
+            if (server.length < size)
+                continue;
+            if (phase === 'server-version' && server.equals(VERSION))
+                phase = 'client-version';
+            else if (phase === 'server-types' && server.subarray(1).includes(1))
+                phase = 'client-security';
+            else if (phase === 'server-result' && server.readUInt32BE(0) === 0)
+                phase = 'client-init';
+            else if (phase === 'server-init')
+                phase = 'ready';
+            else {
+                fail();
+                return;
+            }
+            server = Buffer.alloc(0);
+            // The first picture can share the ServerInit chunk; it needs no buffering.
+            if (phase === 'ready')
+                return;
+        }
+    };
+    const clientBytes = (chunk, allowInput) => {
+        if (phase === 'failed')
+            return [];
+        const outgoing = [];
+        let offset = 0;
+        if (client.length > 0)
+            messageInputAllowed &&= allowInput;
+        while (offset < chunk.length) {
+            if (client.length === 0)
+                messageInputAllowed = allowInput;
+            let size = phase === 'client-version' ? 12
+                : phase === 'client-security' || phase === 'client-init' ? 1
+                    : phase === 'server-init' || phase === 'ready' ? clientMessageSize(client)
+                        : 'invalid';
+            if (size === 'invalid') {
+                fail();
+                return [];
+            }
+            const count = Math.min(size - client.length, chunk.length - offset);
+            client = Buffer.concat([client, chunk.subarray(offset, offset + count)]);
+            offset += count;
+            if (phase === 'server-init' || phase === 'ready')
+                size = clientMessageSize(client);
+            if (size === 'invalid') {
+                fail();
+                return [];
+            }
+            if (client.length < size)
+                continue;
+            if (phase === 'client-version' && client.equals(VERSION))
+                phase = 'server-types';
+            else if (phase === 'client-security' && client[0] === 1)
+                phase = 'server-result';
+            else if (phase === 'client-init' && client[0] <= 1)
+                phase = 'server-init';
+            else if (phase !== 'server-init' && phase !== 'ready') {
+                fail();
+                return [];
+            }
+            else if (INPUT_TYPES.has(client[0]) && !messageInputAllowed) {
+                client = Buffer.alloc(0);
+                continue;
+            }
+            outgoing.push(client);
+            client = Buffer.alloc(0);
+        }
+        return outgoing;
+    };
+    return { get failed() { return phase === 'failed'; }, observeServer, clientBytes };
+}
+function serverMessageSize(buffer, phase) {
+    if (phase === 'server-version')
+        return 12;
+    if (phase === 'server-types') {
+        if (buffer.length < 1)
+            return 1;
+        return buffer[0] === 0 ? 'invalid' : 1 + buffer[0];
+    }
+    if (phase === 'server-result')
+        return 4;
+    if (phase === 'server-init') {
+        if (buffer.length < 24)
+            return 24;
+        const length = buffer.readUInt32BE(20);
+        return length > 4096 ? 'invalid' : 24 + length;
+    }
+    return 'invalid';
+}
+function clientMessageSize(buffer) {
+    if (buffer.length === 0)
+        return 1;
+    const type = buffer[0];
+    if (type === 0)
+        return 20;
+    if (type === 3 || type === 150)
+        return 10;
+    if (type === 4)
+        return 8;
+    if (type === 5)
+        return 6;
+    if (type === 250)
+        return 4;
+    if (type === 2) {
+        if (buffer.length < 4)
+            return 4;
+        const count = buffer.readUInt16BE(2);
+        return count > 64 ? 'invalid' : 4 + count * 4;
+    }
+    if (type === 6) {
+        if (buffer.length < 8)
+            return 8;
+        // Extended clipboard messages encode their payload size as a negative length.
+        const length = Math.abs(buffer.readInt32BE(4));
+        return length > MAX_CLIPBOARD_BYTES ? 'invalid' : 8 + length;
+    }
+    if (type === 248) {
+        if (buffer.length < 9)
+            return 9;
+        return buffer[8] > 64 ? 'invalid' : 9 + buffer[8];
+    }
+    if (type === 251) {
+        if (buffer.length < 8)
+            return 8;
+        return buffer[6] > 16 ? 'invalid' : 8 + buffer[6] * 16;
+    }
+    if (type === 255) {
+        if (buffer.length < 2)
+            return 2;
+        return buffer[1] === 0 ? 12 : 'invalid';
+    }
+    return 'invalid';
+}

package/dist/workspace-runtime/workspaces/dependencies.js

@@ -31,26 +31,41 @@ const running = new WeakMap();
 /**
  * Starts the install after a workspace is registered; opening the workspace never waits for it.
  * Registering again retries a failed install and reinstalls after the manifest or lockfile
- * changed. One install runs per workspace at a time: a second call gets the running one. The
- * returned task settles when that install has finished or been found current.
+ * changed. One install runs per workspace at a time: the same directory shares its task; another
+ * directory waits for it before installing. The returned task covers the requested directory.
  */
-export function scheduleDependencyInstall(state, workspaceId, root) {
+export function scheduleDependencyInstall(state, workspaceId, root, shouldStart) {
     const inFlight = running.get(state) ?? new Map();
     running.set(state, inFlight);
     const existing = inFlight.get(workspaceId);
-    if (existing)
-        return existing;
-    const task = installOnce(state, workspaceId, root)
+    if (existing?.root === root) {
+        if (!shouldStart)
+            existing.guards = undefined;
+        else
+            existing.guards?.push(shouldStart);
+        return existing.task;
+    }
+    const scheduled = { root, task: Promise.resolve(), guards: shouldStart ? [shouldStart] : undefined };
+    const begin = () => {
+        if (state.journal.destroyed() || (scheduled.guards && !scheduled.guards.some((guard) => guard())))
+            return;
+        return installOnce(state, workspaceId, root);
+    };
+    const task = (existing ? existing.task.then(begin) : begin() ?? Promise.resolve())
         .catch((error) => {
         console.error(`[workspace-runtime] dependency install for ${workspaceId} failed to run`, error);
     })
-        .finally(() => inFlight.delete(workspaceId));
-    inFlight.set(workspaceId, task);
+        .finally(() => { if (inFlight.get(workspaceId)?.task === task)
+        inFlight.delete(workspaceId); });
+    scheduled.task = task;
+    inFlight.set(workspaceId, scheduled);
     return task;
 }
 /** Settles every install started in this process; used by tests and shutdown. */
 export async function settleDependencyInstalls(state) {
-    await Promise.all([...(running.get(state)?.values() ?? [])]);
+    while (running.get(state)?.size) {
+        await Promise.all([...(running.get(state)?.values() ?? [])].map((record) => record.task));
+    }
 }
 export function readDependencies(state, workspaceId) {
     return state.journal.getWorkspaceDependencies(workspaceId) ?? { workspaceId, status: 'pending' };

package/dist/workspace-runtime/workspaces/prepare.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isLocalWorkspaceGitAuthMode, isLocalWorkspaceGitEnvironment, matchWorkspaceGitGatewayCloneUrl, workspacePreparationSchema, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { isLocalWorkspaceGitAuthMode, isLocalWorkspaceGitEnvironment, matchWorkspaceGitGatewayCloneUrl, sameWorkspaceRegistration, workspacePreparationSchema, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { WorkspaceContextError } from './context-error.js';
 import { scaffoldEmptyWorkspace } from './empty-template.js';
 /** The caller holds the Workspace lock. Only an absent, never-published directory may be prepared. */
@@ -29,7 +29,11 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
         throw new WorkspaceContextError('workspace_recovery_required');
     if (await exists(target))
         throw new WorkspaceContextError('workspace_checkout_conflict');
-    const receipt = previous ?? {
+    // An unfinished checkout recorded before the fork instructions were known must be cloned again.
+    const forkMatches = !previous || samePendingFork(previous.binding, binding);
+    if (previous && !forkMatches)
+        await rm(join(parent, previous.stagingName), { recursive: true, force: true });
+    const receipt = previous && forkMatches ? previous : {
         binding,
         stagingName: `.prepare-${binding.workspaceId}-${randomUUID()}`,
         status: 'cloning',
@@ -172,11 +176,15 @@ async function exists(path) {
         throw error;
     }
 }
+function samePendingFork(left, right) {
+    const fork = (value) => value.targetKind === 'standalone' ? undefined : value.pendingFork;
+    return JSON.stringify(fork(left) ?? null) === JSON.stringify(fork(right) ?? null);
+}
 async function readReceipt(path, binding) {
     try {
         const value = JSON.parse(await readFile(path, 'utf8'));
         const parsed = workspaceRegistrationSchema.parse(value.binding);
-        if (JSON.stringify(parsed) !== JSON.stringify(binding) ||
+        if (!sameWorkspaceRegistration(parsed, binding) ||
             !['cloning', 'ready', 'published'].includes(value.status) ||
             !new RegExp(`^\\.prepare-${binding.workspaceId}-[0-9a-f-]{36}$`).test(value.stagingName))
             throw new Error();

package/dist/workspace-runtime/workspaces/registry.js

@@ -2,7 +2,7 @@ import { execFile } from 'node:child_process';
 import { lstat, realpath } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { promisify } from 'node:util';
-import { isLocalWorkspaceGitAuthMode, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { isLocalWorkspaceGitAuthMode, sameWorkspaceRegistration, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { prepareWorkspaceCheckout } from './prepare.js';
 import { WorkspaceContextError } from './context-error.js';
 import { scheduleDependencyInstall } from './dependencies.js';
@@ -64,7 +64,7 @@ export async function registerWorkspace(state, input, leaseFence, preparation) {
         state.acceptedLeaseFence = leaseFence;
         await state.journal.setAcceptedLeaseFence(leaseFence);
         const existing = state.journal.getWorkspace(binding.workspaceId);
-        if (existing && JSON.stringify(existing) !== JSON.stringify(binding))
+        if (existing && !sameWorkspaceRegistration(existing, binding))
             throw new WorkspaceContextError('workspace_binding_conflict');
         let root;
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": false,
   "type": "module",
   "engines": {
@@ -48,8 +48,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.1.12",
-    "@playcraft/common": "^0.1.12",
+    "@playcraft/build": "^0.1.14",
+    "@playcraft/common": "^0.1.14",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",