@walkhi/code-relax 0.1.0-beta.30 → 0.1.0-beta.32

package/dist/src/celsius-client.mjs

@@ -1,107 +1,107 @@
-import { EventEmitter } from 'node:events';
-import WebSocket from 'ws';
-
-// Shared Celsius framing and acknowledged topic lifecycle; callers own identity and HTTP.
-export class CelsiusClient extends EventEmitter {
-  constructor({ getConnection, topics = [] }) {
-    super(); this.getConnection = getConnection; this.initialTopics = topics;
-    this.generation = 0; this.topics = new Map(); this.commands = new Map();
-    this.nextId = 0; this.topicLoads = new Map();
-  }
-  async connect() {
-    if (this.ready) return;
-    if (this.connecting) return this.connecting;
-    const generation = this.generation;
-    const work = (async () => {
-      const value = await this.getConnection();
-      if (generation !== this.generation) throw new Error('消息连接已变化。');
-      const url = new URL(value.websocket_url);
-      if (url.protocol !== 'wss:' || url.username || url.password) throw new Error('消息推送地址无效。');
-      await new Promise((resolve, reject) => {
-        const socket = new WebSocket(url, { handshakeTimeout: 15000, maxPayload: 8 * 1024 * 1024 });
-        this.socket = socket;
-        const timer = setTimeout(() => { reject(new Error('消息推送订阅超时。')); socket.terminate(); }, 30000);
-        const current = () => this.socket === socket && generation === this.generation;
-        socket.on('error', () => {}); // Do not expose the signed URL in library errors.
-        socket.on('open', async () => {
-          try {
-            await this.command({ type: 'connect', presence: { type: 'presence', state: 'background' } });
-            for (const topic of this.initialTopics) await this.subscribe(topic);
-            if (!current()) throw new Error('消息连接已变化。');
-            this.ready = true; clearTimeout(timer); resolve(); this.emit('connected');
-          } catch (error) { clearTimeout(timer); reject(error); socket.terminate(); }
-        });
-        socket.on('message', data => {
-          if (!current()) return;
-          let frames; try { frames = JSON.parse(data.toString()); } catch { return; }
-          if (!Array.isArray(frames)) return;
-          for (const frame of frames) {
-            if (frame.type === 'message') this.receive(frame);
-            else if (frame.id != null) this.commands.get(frame.id)?.resolve(frame.reply);
-          }
-        });
-        socket.on('close', code => {
-          clearTimeout(timer); reject(new Error('消息推送连接已断开。'));
-          if (!current()) return;
-          this.ready = false; this.socket = null;
-          for (const entry of this.commands.values()) entry.reject(new Error('消息推送连接已断开。'));
-          this.commands.clear(); this.topics.clear(); this.topicLoads.clear();
-          this.emit('disconnected', { source: 'celsius', code });
-        });
-      });
-    })();
-    this.connecting = work;
-    try { await work; } finally { if (this.connecting === work) this.connecting = null; }
-  }
-
-  command(command) {
-    if (this.socket?.readyState !== WebSocket.OPEN) return Promise.reject(new Error('消息推送尚未连接。'));
-    const id = ++this.nextId;
-    const socket = this.socket;
-    return new Promise((resolve, reject) => {
-      const finish = (error, value) => {
-        if (!this.commands.has(id)) return;
-        clearTimeout(timer); this.commands.delete(id);
-        if (error) reject(error); else resolve(value);
-      };
-      const timer = setTimeout(() => { finish(new Error('消息推送请求超时。')); socket.terminate(); }, 30000);
-      this.commands.set(id, { resolve: value => finish(null, value), reject: error => finish(error) });
-      socket.send(JSON.stringify([{ id, command }]), error => { if (error) finish(new Error('消息推送连接已断开。')); });
-    });
-  }
-
-  async subscribe(name, { offset, requireRecovery = false } = {}) {
-    if (this.topics.has(name)) return;
-    if (this.topicLoads.has(name)) return this.topicLoads.get(name);
-    const generation = this.generation, socket = this.socket;
-    // Every transport reconnection invalidates chat snapshots and reads a new
-    // latest window. An old offset never certifies the new snapshot by itself.
-    const work = this.command({ type: 'subscribe', topic_id: name, ...(offset == null ? {} : { offset }) }).then(reply => {
-      if (socket !== this.socket || generation !== this.generation) throw new Error('消息连接已变化。');
-      if (reply?.type !== 'subscribe' || reply.topic_id !== name) throw new Error('消息推送订阅未确认。');
-      if (requireRecovery && !reply.recovered) throw new Error('ChatGPT 输出历史未完整接续，请核对原消息。');
-      this.topics.set(name, reply.last_offset || null);
-      if (reply.recovered) for (const message of reply.catchups || []) this.receive(message);
-    });
-    this.topicLoads.set(name, work);
-    try { await work; } finally { if (this.topicLoads.get(name) === work) this.topicLoads.delete(name); }
-  }
-
-  async unsubscribe(name) {
-    if (!this.topics.delete(name) || this.socket?.readyState !== WebSocket.OPEN) return;
-    await this.command({ type: 'unsubscribe', topic_id: name });
-  }
-
-  receive(frame) {
-    if (frame.offset) this.topics.set(frame.topic_id, frame.offset);
-    this.emit('message', frame.topic_id, frame.payload);
-  }
-
-
-  close() {
-    this.generation++; this.ready = false; this.connecting = null;
-    const socket = this.socket; this.socket = null; socket?.terminate();
-    for (const entry of this.commands.values()) entry.reject(new Error('消息推送连接已结束。'));
-    this.commands.clear(); this.topics.clear(); this.topicLoads.clear();
-  }
-}
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+
+// Shared Celsius framing and acknowledged topic lifecycle; callers own identity and HTTP.
+export class CelsiusClient extends EventEmitter {
+  constructor({ getConnection, topics = [] }) {
+    super(); this.getConnection = getConnection; this.initialTopics = topics;
+    this.generation = 0; this.topics = new Map(); this.commands = new Map();
+    this.nextId = 0; this.topicLoads = new Map();
+  }
+  async connect() {
+    if (this.ready) return;
+    if (this.connecting) return this.connecting;
+    const generation = this.generation;
+    const work = (async () => {
+      const value = await this.getConnection();
+      if (generation !== this.generation) throw new Error('消息连接已变化。');
+      const url = new URL(value.websocket_url);
+      if (url.protocol !== 'wss:' || url.username || url.password) throw new Error('消息推送地址无效。');
+      await new Promise((resolve, reject) => {
+        const socket = new WebSocket(url, { handshakeTimeout: 15000, maxPayload: 8 * 1024 * 1024 });
+        this.socket = socket;
+        const timer = setTimeout(() => { reject(new Error('消息推送订阅超时。')); socket.terminate(); }, 30000);
+        const current = () => this.socket === socket && generation === this.generation;
+        socket.on('error', () => {}); // Do not expose the signed URL in library errors.
+        socket.on('open', async () => {
+          try {
+            await this.command({ type: 'connect', presence: { type: 'presence', state: 'background' } });
+            for (const topic of this.initialTopics) await this.subscribe(topic);
+            if (!current()) throw new Error('消息连接已变化。');
+            this.ready = true; clearTimeout(timer); resolve(); this.emit('connected');
+          } catch (error) { clearTimeout(timer); reject(error); socket.terminate(); }
+        });
+        socket.on('message', data => {
+          if (!current()) return;
+          let frames; try { frames = JSON.parse(data.toString()); } catch { return; }
+          if (!Array.isArray(frames)) return;
+          for (const frame of frames) {
+            if (frame.type === 'message') this.receive(frame);
+            else if (frame.id != null) this.commands.get(frame.id)?.resolve(frame.reply);
+          }
+        });
+        socket.on('close', code => {
+          clearTimeout(timer); reject(new Error('消息推送连接已断开。'));
+          if (!current()) return;
+          this.ready = false; this.socket = null;
+          for (const entry of this.commands.values()) entry.reject(new Error('消息推送连接已断开。'));
+          this.commands.clear(); this.topics.clear(); this.topicLoads.clear();
+          this.emit('disconnected', { source: 'celsius', code });
+        });
+      });
+    })();
+    this.connecting = work;
+    try { await work; } finally { if (this.connecting === work) this.connecting = null; }
+  }
+
+  command(command) {
+    if (this.socket?.readyState !== WebSocket.OPEN) return Promise.reject(new Error('消息推送尚未连接。'));
+    const id = ++this.nextId;
+    const socket = this.socket;
+    return new Promise((resolve, reject) => {
+      const finish = (error, value) => {
+        if (!this.commands.has(id)) return;
+        clearTimeout(timer); this.commands.delete(id);
+        if (error) reject(error); else resolve(value);
+      };
+      const timer = setTimeout(() => { finish(new Error('消息推送请求超时。')); socket.terminate(); }, 30000);
+      this.commands.set(id, { resolve: value => finish(null, value), reject: error => finish(error) });
+      socket.send(JSON.stringify([{ id, command }]), error => { if (error) finish(new Error('消息推送连接已断开。')); });
+    });
+  }
+
+  async subscribe(name, { offset, requireRecovery = false } = {}) {
+    if (this.topics.has(name)) return;
+    if (this.topicLoads.has(name)) return this.topicLoads.get(name);
+    const generation = this.generation, socket = this.socket;
+    // Every transport reconnection invalidates chat snapshots and reads a new
+    // latest window. An old offset never certifies the new snapshot by itself.
+    const work = this.command({ type: 'subscribe', topic_id: name, ...(offset == null ? {} : { offset }) }).then(reply => {
+      if (socket !== this.socket || generation !== this.generation) throw new Error('消息连接已变化。');
+      if (reply?.type !== 'subscribe' || reply.topic_id !== name) throw new Error('消息推送订阅未确认。');
+      if (requireRecovery && !reply.recovered) throw new Error('ChatGPT 输出历史未完整接续，请核对原消息。');
+      this.topics.set(name, reply.last_offset || null);
+      if (reply.recovered) for (const message of reply.catchups || []) this.receive(message);
+    });
+    this.topicLoads.set(name, work);
+    try { await work; } finally { if (this.topicLoads.get(name) === work) this.topicLoads.delete(name); }
+  }
+
+  async unsubscribe(name) {
+    if (!this.topics.delete(name) || this.socket?.readyState !== WebSocket.OPEN) return;
+    await this.command({ type: 'unsubscribe', topic_id: name });
+  }
+
+  receive(frame) {
+    if (frame.offset) this.topics.set(frame.topic_id, frame.offset);
+    this.emit('message', frame.topic_id, frame.payload);
+  }
+
+
+  close() {
+    this.generation++; this.ready = false; this.connecting = null;
+    const socket = this.socket; this.socket = null; socket?.terminate();
+    for (const entry of this.commands.values()) entry.reject(new Error('消息推送连接已结束。'));
+    this.commands.clear(); this.topics.clear(); this.topicLoads.clear();
+  }
+}

package/dist/src/code-browser.mjs

@@ -1,100 +1,100 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { execFile } from 'node:child_process';
-import protocol from '../shared/code-browser.cjs';
-import { fileRange, fileRevision } from './file-transfer-range.mjs';
-
-async function checkedPath(root, relative) {
-  const target = protocol.child(root, relative);
-  return fs.realpath(target);
-}
-
-function git(cwd, args) {
-  return new Promise((resolve, reject) => execFile('git', ['--no-optional-locks', '--literal-pathspecs', '-c', 'core.quotePath=false', ...args],
-    { cwd, encoding: 'utf8', maxBuffer: protocol.maxBytes, timeout: 15000, windowsHide: true },
-    (error, stdout, stderr) => {
-      if (error) reject(Object.assign(new Error(error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER'
-        ? 'Git 输出超过预览上限（1 MiB）。' : String(stderr || error.message).trim()), { statusCode: 422 }));
-      else resolve(stdout);
-    }));
-}
-
-export async function browseCode(rpc, operation, query) {
-  if (operation === 'change') return protocol.change(rpc, query);
-  if (operation === 'changes') return protocol.changes(rpc, query);
-  if (operation === 'roots') return { ...await protocol.context(rpc, query), workspaceDiff: true, sizeCheckedBeforeRead: true };
-  const root = query.get('root');
-  if (typeof root !== 'string' || !path.isAbsolute(root)) protocol.fail('请输入电脑上的绝对目录路径。');
-  if (operation === 'workspace' || operation === 'workspace-file') {
-    const realRoot = await checkedPath(root, '');
-    const repository = (await git(realRoot, ['rev-parse', '--show-toplevel'])).trim();
-    const scope = path.relative(repository, realRoot).replaceAll('\\', '/') || '.';
-    if (scope.startsWith('..') || path.isAbsolute(scope)) protocol.fail('无法确认 Git 仓库范围。', 403);
-    const toRelative = name => protocol.relative(realRoot, path.resolve(repository, name));
-    if (operation === 'workspace-file') {
-      const group = query.get('group');
-      if (!['staged', 'unstaged'].includes(group)) protocol.fail('未知的变更来源。');
-      const names = [query.get('path'), query.get('oldPath')].filter(Boolean);
-      if (!names.length) protocol.fail('请选择变更文件。');
-      const paths = names.map(name => path.relative(repository, protocol.child(realRoot, name)).replaceAll('\\', '/'));
-      const diff = await git(repository, ['diff', ...(group === 'staged' ? ['--cached'] : []), '--no-ext-diff', '--no-textconv', '--no-color', names.length > 1 ? '--find-renames' : '--no-renames', '--', ...paths]);
-      return { diff, scope: group === 'staged' ? '当前工作区 · 已暂存' : '当前工作区 · 未暂存' };
-    }
-    const entries = [];
-    for (const group of ['unstaged', 'staged']) {
-      const fields = (await git(repository, ['diff', ...(group === 'staged' ? ['--cached'] : []), '--name-status', '-z', '--find-renames', '--no-ext-diff', '--no-textconv', '--', scope])).split('\0');
-      for (let i = 0; i < fields.length && fields[i];) {
-        const status = fields[i++], first = fields[i++];
-        const renamed = /^[RC]/.test(status), last = renamed ? fields[i++] : first;
-        const name = toRelative(last), oldPath = renamed ? toRelative(first) : null;
-        if (name == null) { if (oldPath != null) entries.push({ path: oldPath, oldPath: null, status: 'D', group }); continue; }
-        entries.push({ path: name, oldPath, status: renamed && oldPath == null ? 'A' : status, group });
-      }
-    }
-    for (const name of (await git(repository, ['ls-files', '--others', '--exclude-standard', '-z', '--', scope])).split('\0').filter(Boolean)) {
-      const relative = toRelative(name);
-      if (relative != null) entries.push({ path: relative, status: '?', group: 'untracked' });
-    }
-    if (entries.length > protocol.maxEntries) protocol.fail('变更文件超过 4000 项，暂不支持展示。', 413);
-    return { root, entries, scope: '当前工作区快照 · 非本次任务归属' };
-  }
-  const relative = query.get('path') || '';
-  const target = await checkedPath(root, relative);
-  if ((operation === 'image' || operation === 'binary')) {
-    const handle = await fs.open(target, 'r');
-    try {
-      const before = await handle.stat();
-      if (!before.isFile()) protocol.fail('请选择普通文件。', 415);
-      if (before.size > protocol.maxFileBytes) protocol.fail('文件超过预览上限（20 MiB）。', 413);
-      if (!before.size) protocol.fail('文件为空。', 415);
-      const revision = fileRevision(before);
-      const { offset, length } = fileRange(query, before.size, revision);
-      const header = Buffer.alloc(12);
-      await handle.read(header, 0, header.length, 0);
-      const mimeType = operation === 'binary' ? 'application/octet-stream' : protocol.imageMime(header);
-      const data = Buffer.alloc(length);
-      const { bytesRead } = await handle.read(data, 0, data.length, offset);
-      const real = await checkedPath(root, relative), after = await handle.stat(), onDisk = await fs.stat(real);
-      if (real !== target || bytesRead !== data.length || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs || after.size !== before.size || onDisk.ino !== before.ino || onDisk.dev !== before.dev || onDisk.mtimeMs !== before.mtimeMs || onDisk.size !== before.size) protocol.fail('读取期间文件发生变化，请重新打开。', 409);
-      return { name: path.basename(target), size: before.size, offset, revision, mimeType, data };
-    } finally { await handle.close(); }
-  }
-  if (operation === 'directory') {
-    const entries = await fs.readdir(target, { withFileTypes: true });
-    const result = { entries: entries.map(entry => ({ fileName: entry.name, isDirectory: entry.isDirectory(), isFile: entry.isFile() })) };
-    await checkedPath(root, relative);
-    return protocol.directory(result);
-  }
-  if (operation === 'file') {
-    const before = await fs.stat(target);
-    if (!before.isFile()) protocol.fail('请选择普通文件。', 415);
-    if (before.size > protocol.maxBytes) protocol.fail('文件超过只读预览上限（1 MiB）。', 413);
-    const result = { dataBase64: (await fs.readFile(target)).toString('base64') };
-    const real = await checkedPath(root, relative), after = await fs.stat(real);
-    if (real !== target || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ino !== after.ino) {
-      protocol.fail('读取期间文件发生变化，请刷新。', 409);
-    }
-    return { ...protocol.fromBase64(result.dataBase64), modifiedAtMs: after.mtimeMs };
-  }
-  protocol.fail('未知的代码浏览操作。', 404);
-}
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import protocol from '../shared/code-browser.cjs';
+import { fileRange, fileRevision } from './file-transfer-range.mjs';
+
+async function checkedPath(root, relative) {
+  const target = protocol.child(root, relative);
+  return fs.realpath(target);
+}
+
+function git(cwd, args) {
+  return new Promise((resolve, reject) => execFile('git', ['--no-optional-locks', '--literal-pathspecs', '-c', 'core.quotePath=false', ...args],
+    { cwd, encoding: 'utf8', maxBuffer: protocol.maxBytes, timeout: 15000, windowsHide: true },
+    (error, stdout, stderr) => {
+      if (error) reject(Object.assign(new Error(error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER'
+        ? 'Git 输出超过预览上限（1 MiB）。' : String(stderr || error.message).trim()), { statusCode: 422 }));
+      else resolve(stdout);
+    }));
+}
+
+export async function browseCode(rpc, operation, query) {
+  if (operation === 'change') return protocol.change(rpc, query);
+  if (operation === 'changes') return protocol.changes(rpc, query);
+  if (operation === 'roots') return { ...await protocol.context(rpc, query), workspaceDiff: true, sizeCheckedBeforeRead: true };
+  const root = query.get('root');
+  if (typeof root !== 'string' || !path.isAbsolute(root)) protocol.fail('请输入电脑上的绝对目录路径。');
+  if (operation === 'workspace' || operation === 'workspace-file') {
+    const realRoot = await checkedPath(root, '');
+    const repository = (await git(realRoot, ['rev-parse', '--show-toplevel'])).trim();
+    const scope = path.relative(repository, realRoot).replaceAll('\\', '/') || '.';
+    if (scope.startsWith('..') || path.isAbsolute(scope)) protocol.fail('无法确认 Git 仓库范围。', 403);
+    const toRelative = name => protocol.relative(realRoot, path.resolve(repository, name));
+    if (operation === 'workspace-file') {
+      const group = query.get('group');
+      if (!['staged', 'unstaged'].includes(group)) protocol.fail('未知的变更来源。');
+      const names = [query.get('path'), query.get('oldPath')].filter(Boolean);
+      if (!names.length) protocol.fail('请选择变更文件。');
+      const paths = names.map(name => path.relative(repository, protocol.child(realRoot, name)).replaceAll('\\', '/'));
+      const diff = await git(repository, ['diff', ...(group === 'staged' ? ['--cached'] : []), '--no-ext-diff', '--no-textconv', '--no-color', names.length > 1 ? '--find-renames' : '--no-renames', '--', ...paths]);
+      return { diff, scope: group === 'staged' ? '当前工作区 · 已暂存' : '当前工作区 · 未暂存' };
+    }
+    const entries = [];
+    for (const group of ['unstaged', 'staged']) {
+      const fields = (await git(repository, ['diff', ...(group === 'staged' ? ['--cached'] : []), '--name-status', '-z', '--find-renames', '--no-ext-diff', '--no-textconv', '--', scope])).split('\0');
+      for (let i = 0; i < fields.length && fields[i];) {
+        const status = fields[i++], first = fields[i++];
+        const renamed = /^[RC]/.test(status), last = renamed ? fields[i++] : first;
+        const name = toRelative(last), oldPath = renamed ? toRelative(first) : null;
+        if (name == null) { if (oldPath != null) entries.push({ path: oldPath, oldPath: null, status: 'D', group }); continue; }
+        entries.push({ path: name, oldPath, status: renamed && oldPath == null ? 'A' : status, group });
+      }
+    }
+    for (const name of (await git(repository, ['ls-files', '--others', '--exclude-standard', '-z', '--', scope])).split('\0').filter(Boolean)) {
+      const relative = toRelative(name);
+      if (relative != null) entries.push({ path: relative, status: '?', group: 'untracked' });
+    }
+    if (entries.length > protocol.maxEntries) protocol.fail('变更文件超过 4000 项，暂不支持展示。', 413);
+    return { root, entries, scope: '当前工作区快照 · 非本次任务归属' };
+  }
+  const relative = query.get('path') || '';
+  const target = await checkedPath(root, relative);
+  if ((operation === 'image' || operation === 'binary')) {
+    const handle = await fs.open(target, 'r');
+    try {
+      const before = await handle.stat();
+      if (!before.isFile()) protocol.fail('请选择普通文件。', 415);
+      if (before.size > protocol.maxFileBytes) protocol.fail('文件超过预览上限（20 MiB）。', 413);
+      if (!before.size) protocol.fail('文件为空。', 415);
+      const revision = fileRevision(before);
+      const { offset, length } = fileRange(query, before.size, revision);
+      const header = Buffer.alloc(12);
+      await handle.read(header, 0, header.length, 0);
+      const mimeType = operation === 'binary' ? 'application/octet-stream' : protocol.imageMime(header);
+      const data = Buffer.alloc(length);
+      const { bytesRead } = await handle.read(data, 0, data.length, offset);
+      const real = await checkedPath(root, relative), after = await handle.stat(), onDisk = await fs.stat(real);
+      if (real !== target || bytesRead !== data.length || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs || after.size !== before.size || onDisk.ino !== before.ino || onDisk.dev !== before.dev || onDisk.mtimeMs !== before.mtimeMs || onDisk.size !== before.size) protocol.fail('读取期间文件发生变化，请重新打开。', 409);
+      return { name: path.basename(target), size: before.size, offset, revision, mimeType, data };
+    } finally { await handle.close(); }
+  }
+  if (operation === 'directory') {
+    const entries = await fs.readdir(target, { withFileTypes: true });
+    const result = { entries: entries.map(entry => ({ fileName: entry.name, isDirectory: entry.isDirectory(), isFile: entry.isFile() })) };
+    await checkedPath(root, relative);
+    return protocol.directory(result);
+  }
+  if (operation === 'file') {
+    const before = await fs.stat(target);
+    if (!before.isFile()) protocol.fail('请选择普通文件。', 415);
+    if (before.size > protocol.maxBytes) protocol.fail('文件超过只读预览上限（1 MiB）。', 413);
+    const result = { dataBase64: (await fs.readFile(target)).toString('base64') };
+    const real = await checkedPath(root, relative), after = await fs.stat(real);
+    if (real !== target || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ino !== after.ino) {
+      protocol.fail('读取期间文件发生变化，请刷新。', 409);
+    }
+    return { ...protocol.fromBase64(result.dataBase64), modifiedAtMs: after.mtimeMs };
+  }
+  protocol.fail('未知的代码浏览操作。', 404);
+}

package/dist/src/desktop-launcher.mjs

@@ -1,46 +1,46 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { setTimeout as delay } from 'node:timers/promises';
-import { readRecord } from './service-lifecycle.mjs';
-import { ManagedAppServer, managedAppServerUrl as sharedUrl, managedPortAvailable as portAvailable } from './managed-app-server.mjs';
-export { portAvailable };
-export async function launchDesktop({ stateRoot, host, environment = process.env, available = portAvailable, wait = delay, timeout = 30000, recoveryId, progress = () => {} }) {
-  fs.mkdirSync(stateRoot, { recursive: true });
-  const recovery = readRecord(path.join(stateRoot, 'shared-recovery.lock'));
-  if (recovery && recovery.operationId !== recoveryId) throw new Error('Codex 内核正在启动，请用 relax doctor 查看恢复状态。');
-  const lock = path.join(stateRoot, 'desktop-launch.lock');
-  let descriptor;
-  let managed;
-  try { descriptor = fs.openSync(lock, 'wx'); }
-  catch (error) {
-    if (error.code === 'EEXIST') throw new Error('另一个 Desktop 启动操作正在进行；若上次异常退出，请确认没有启动器运行后移除 desktop-launch.lock。');
-    throw error;
-  }
-  try {
-    const info = await host.inspect();
-    if (!info.desktop) throw new Error('未安装 Codex Desktop，请使用 relax start 启动工作站。');
-    const connected = await host.sharedServiceUrl();
-    if (info.running) {
-      if (connected) return { reused: true };
-      throw new Error('请先保存任务并完全退出 Codex Desktop，再接入 Codex 内核；不会自动结束正在运行的任务。');
-    }
-    const childEnv = { ...environment };
-    for (const key of ['CODEX_APP_SERVER_WS_URL', 'CODEX_APP_SERVER_FORCE_CLI', 'CODEX_APP_TOOLS_PIPE_PATH']) delete childEnv[key];
-    progress('starting-app-server');
-    managed = new ManagedAppServer({ stateRoot, host, environment, available, wait, timeout });
-    if (!await managed.start()) throw new Error(managed.snapshot().error || 'Codex 内核未就绪。');
-    const runtime = readRecord(path.join(stateRoot, 'codex-runtime.json'));
-    if (runtime?.codexHome) childEnv.CODEX_HOME = runtime.codexHome;
-    childEnv.CODEX_APP_SERVER_WS_URL = sharedUrl;
-    progress('starting-desktop');
-    await host.startDesktop(info.desktop, childEnv);
-    const deadline = Date.now() + timeout;
-    while (true) {
-      const ready = await host.desktopReady();
-      if (ready) break;
-      if (Date.now() >= deadline) throw new Error('Desktop 尚未接入 Codex 内核。请查看 Desktop 窗口后重试。');
-      await wait(500);
-    }
-    return { reused: false };
-  } finally { managed?.close(); fs.closeSync(descriptor); fs.rmSync(lock, { force: true }); }
-}
+import fs from 'node:fs';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { readRecord } from './service-lifecycle.mjs';
+import { ManagedAppServer, managedAppServerUrl as sharedUrl, managedPortAvailable as portAvailable } from './managed-app-server.mjs';
+export { portAvailable };
+export async function launchDesktop({ stateRoot, host, environment = process.env, available = portAvailable, wait = delay, timeout = 30000, recoveryId, progress = () => {} }) {
+  fs.mkdirSync(stateRoot, { recursive: true });
+  const recovery = readRecord(path.join(stateRoot, 'shared-recovery.lock'));
+  if (recovery && recovery.operationId !== recoveryId) throw new Error('Codex 内核正在启动，请用 relax doctor 查看恢复状态。');
+  const lock = path.join(stateRoot, 'desktop-launch.lock');
+  let descriptor;
+  let managed;
+  try { descriptor = fs.openSync(lock, 'wx'); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new Error('另一个 Desktop 启动操作正在进行；若上次异常退出，请确认没有启动器运行后移除 desktop-launch.lock。');
+    throw error;
+  }
+  try {
+    const info = await host.inspect();
+    if (!info.desktop) throw new Error('未安装 Codex Desktop，请使用 relax start 启动工作站。');
+    const connected = await host.sharedServiceUrl();
+    if (info.running) {
+      if (connected) return { reused: true };
+      throw new Error('请先保存任务并完全退出 Codex Desktop，再接入 Codex 内核；不会自动结束正在运行的任务。');
+    }
+    const childEnv = { ...environment };
+    for (const key of ['CODEX_APP_SERVER_WS_URL', 'CODEX_APP_SERVER_FORCE_CLI', 'CODEX_APP_TOOLS_PIPE_PATH']) delete childEnv[key];
+    progress('starting-app-server');
+    managed = new ManagedAppServer({ stateRoot, host, environment, available, wait, timeout });
+    if (!await managed.start()) throw new Error(managed.snapshot().error || 'Codex 内核未就绪。');
+    const runtime = readRecord(path.join(stateRoot, 'codex-runtime.json'));
+    if (runtime?.codexHome) childEnv.CODEX_HOME = runtime.codexHome;
+    childEnv.CODEX_APP_SERVER_WS_URL = sharedUrl;
+    progress('starting-desktop');
+    await host.startDesktop(info.desktop, childEnv);
+    const deadline = Date.now() + timeout;
+    while (true) {
+      const ready = await host.desktopReady();
+      if (ready) break;
+      if (Date.now() >= deadline) throw new Error('Desktop 尚未接入 Codex 内核。请查看 Desktop 窗口后重试。');
+      await wait(500);
+    }
+    return { reused: false };
+  } finally { managed?.close(); fs.closeSync(descriptor); fs.rmSync(lock, { force: true }); }
+}