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

package/dist/src/platform/README.md

@@ -1,12 +1,12 @@
-# 被控主机平台适配
-
-当前只实现 Windows Codex：
-
-- `windows/runtime-paths.mjs`：固定服务、用户状态、Codex 数据、附件和长期凭据路径。
-- `windows/service-host.mjs`：网卡、Bridge 进程环境和旧状态迁移。
-- `windows/desktop-host.mjs`、PowerShell 脚本：普通/共享 Desktop、快捷方式和隐藏控制台启动。
-- `windows/credential-store.mjs/.ps1`：私有中继电脑凭据的 DPAPI 与 ACL。
-
-Windows 专有脚本兼容系统自带 PowerShell 5.1。通用生命周期使用 Node 接口；系统检测和凭据保护不扩散到业务代码。
-
+# 被控主机平台适配
+
+当前只实现 Windows Codex：
+
+- `windows/runtime-paths.mjs`：固定服务、用户状态、Codex 数据、附件和长期凭据路径。
+- `windows/service-host.mjs`：网卡、Bridge 进程环境和旧状态迁移。
+- `windows/desktop-host.mjs`、PowerShell 脚本：普通/共享 Desktop、快捷方式和隐藏控制台启动。
+- `windows/credential-store.mjs/.ps1`：私有中继电脑凭据的 DPAPI 与 ACL。
+
+Windows 专有脚本兼容系统自带 PowerShell 5.1。通用生命周期使用 Node 接口；系统检测和凭据保护不扩散到业务代码。
+
 macOS、Linux 目录仅保留规划说明，尚无路径、IPC、进程或安装实现。接入排在控制端扩展之后，并需分别验证 Codex Desktop/app-server 的可用连接方式；只有独立 app-server 时不能宣称接管 Desktop 当前任务。

package/dist/src/platform/codex-protocol.mjs

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+const requiredMethods = ['thread/start', 'thread/resume', 'thread/list', 'thread/turns/list',
+  'thread/items/list', 'turn/start', 'turn/steer', 'turn/interrupt', 'model/list', 'project/list',
+  'project/create', 'project/update', 'project/move',
+  'fs/getMetadata', 'fs/readDirectory', 'fs/createDirectory', 'command/exec',
+  'thread/settings/update', 'configRequirements/read', 'thread/queue/list', 'thread/queue/add',
+  'thread/queue/delete', 'thread/queue/start', 'thread/read', 'thread/unsubscribe', 'config/read', 'account/rateLimits/read'];
+
+export function compareVersions(a, b) {
+  const parse = v => v.split(/[.-]/).map(part => /^\d+$/.test(part) ? Number(part) : part);
+  const aa = parse(a), bb = parse(b);
+  for (let i = 0; i < Math.max(aa.length, bb.length); i++) {
+    if (aa[i] === bb[i]) continue;
+    if (aa[i] === undefined) return 1;
+    if (bb[i] === undefined) return -1;
+    return typeof aa[i] === 'number' && typeof bb[i] === 'number' ? aa[i] - bb[i] : String(aa[i]).localeCompare(String(bb[i]));
+  }
+  return 0;
+}
+
+export async function verifyProtocol(executable, stateRoot) {
+  const directory = fs.mkdtempSync(path.join(stateRoot, 'cli-schema-'));
+  try {
+    await exec(executable, ['app-server', 'generate-json-schema', '--experimental', '--out', directory],
+      { windowsHide: true, timeout: 30000, maxBuffer: 4 * 1024 * 1024 });
+    const request = fs.readFileSync(path.join(directory, 'ClientRequest.json'), 'utf8');
+    const missing = requiredMethods.filter(method => !request.includes(`"${method}"`));
+    const turns = fs.readFileSync(path.join(directory, 'v2/ThreadTurnsListParams.json'), 'utf8');
+    if (!turns.includes('"itemsView"') || !turns.includes('"summary"')) missing.push('turn summary pagination');
+    if (missing.length) throw new Error(`缺少协议能力：${missing.join(', ')}`);
+  } finally {
+    const remove = dir => {
+      for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+        const file = path.join(dir, item.name);
+        if (item.isDirectory()) remove(file); else fs.unlinkSync(file);
+      }
+      fs.rmdirSync(dir);
+    };
+    remove(directory);
+  }
+}

package/dist/src/platform/codex-runtime.mjs

@@ -0,0 +1,3 @@
+import { platformModule } from './select.mjs';
+const adapter = await import(platformModule('codex-runtime'));
+export const { discoverCodex, resolveCodexRuntime, runtimeFilesAvailable, codeModeHostPath, runtimeFingerprint, pruneRetainedDesktopRuntimes } = adapter;

package/dist/src/platform/credential-store.mjs

@@ -0,0 +1,3 @@
+import { platformModule } from './select.mjs';
+const adapter = await import(platformModule('credential-store'));
+export const { credentialStore } = adapter;

package/dist/src/platform/desktop-host.mjs

@@ -0,0 +1,3 @@
+import { platformModule } from './select.mjs';
+const adapter = await import(platformModule('desktop-host'));
+export const { desktopHost, resolveStateRoot, removeDesktopShortcut, residentStartup } = adapter;

package/dist/src/platform/desktop-project-registration.mjs

@@ -0,0 +1,3 @@
+import { platformModule } from './select.mjs';
+const adapter = await import(platformModule('desktop-project-registration'));
+export const { withDesktopProjectRegistration } = adapter;

package/dist/src/platform/desktop-project-store.mjs

@@ -0,0 +1,149 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { processAlive } from '../background-process.mjs';
+
+// Desktop state is validated by structure, not by application version.
+// Desktop reads this file once and flushes its complete in-memory snapshot.
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const key = value => process.platform === 'win32'
+  ? path.win32.normalize(value).replace(/[\\/]+$/, '').toLowerCase() : path.posix.normalize(value).replace(/\/+$/, '');
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const fail = (message, details) => { throw Object.assign(new Error(message), { statusCode: 409, details }); };
+
+export const desktopProjectRestartWarning = '创建项目需要短暂关闭并重新打开 Codex Desktop，以完成桌面登记。请先保存桌面上未发送的内容；仅由旧桌面实例承接的任务可能中断。手机连接、工作站服务和 Codex 内核保持运行。';
+
+function parseState(bytes) {
+  const state = JSON.parse(bytes.toString('utf8').replace(/^\uFEFF/, ''));
+  if (!object(state) || !object(state['local-projects']) || !Array.isArray(state['project-order'])
+    || state['project-order'].some(id => typeof id !== 'string')) {
+    fail('Codex Desktop 项目文件结构无效，未修改桌面文件。');
+  }
+  return state;
+}
+
+export function registerProjectInState(state, project, codexDataRoot) {
+  if (!Number.isFinite(project.createdAt) || !Number.isFinite(project.updatedAt)) {
+    fail('内核项目时间字段无效，未修改桌面文件。');
+  }
+  const projects = state['local-projects'];
+  const scope = state['app-server-project-id-by-legacy-project-id-by-host']?.[`local:${codexDataRoot}`];
+  if (scope !== undefined && !object(scope)) fail('Codex Desktop 项目映射结构无效，未修改桌面文件。');
+  for (const [legacyId, nativeId] of Object.entries(scope || {})) {
+    if ((legacyId === project.id || nativeId === project.id) && legacyId !== nativeId) {
+      fail('该项目已有不同的桌面身份映射，未覆盖已有登记。');
+    }
+  }
+  const previous = projects[project.id];
+  const rootPaths = project.roots.map(root => root.path);
+  if (previous && (previous.id !== project.id || previous.name !== project.name || !Array.isArray(previous.rootPaths)
+    || previous.rootPaths.length !== rootPaths.length || previous.rootPaths.some((root, index) => key(root) !== key(rootPaths[index])))) {
+    fail('该项目的桌面登记内容已变化，未覆盖已有登记。');
+  }
+  // With identical native/desktop IDs, Desktop storeProject adopts the native
+  // project at startup. No legacy mapping, thread reassignment or import is needed.
+  const result = { ...state, 'local-projects': { ...projects, [project.id]: previous || {
+    id: project.id, name: project.name, rootPaths,
+    createdAt: project.createdAt * 1000, updatedAt: project.updatedAt * 1000,
+  } } };
+  result['project-order'] = state['project-order'].includes(project.id)
+    ? state['project-order'] : [project.id, ...state['project-order']];
+  return result;
+}
+
+async function acquireLock(stateRoot, operationId) {
+  const file = path.join(stateRoot, 'desktop-launch.lock');
+  try {
+    const previous = JSON.parse(await fs.readFile(file, 'utf8') || 'null');
+    if (previous?.owner === 'project-registration' && Number.isInteger(previous.pid) && !processAlive(previous.pid)) {
+      await fs.unlink(file);
+    }
+  } catch (error) { if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error; }
+  let handle;
+  try { handle = await fs.open(file, 'wx'); }
+  catch (error) { if (error.code === 'EEXIST') fail('Codex Desktop 正在启动或登记项目，请稍后再试。'); throw error; }
+  try { await handle.writeFile(JSON.stringify({ owner: 'project-registration', pid: process.pid, operationId })); }
+  catch (error) { await handle.close(); await fs.unlink(file); throw error; }
+  return async () => { await handle.close(); await fs.unlink(file); };
+}
+
+export async function withDesktopProjectRegistration(options, action) {
+  const { stateRoot, codexDataRoot, operationId, confirmed, serverUrl,
+    host, wait = delay, readyTimeoutMs = 30000 } = options;
+  const stateFile = path.join(codexDataRoot, '.codex-global-state.json');
+  const release = await acquireLock(stateRoot, operationId);
+  try {
+    try { await fs.access(path.join(stateRoot, 'shared-recovery.lock')); fail('Codex Desktop 正在恢复连接，请稍后创建项目。'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const info = await host.inspect();
+    parseState(await fs.readFile(stateFile));
+    if (info.running && confirmed !== true) fail(desktopProjectRestartWarning, { desktopRestartRequired: true });
+    if (info.running && await host.sharedServiceUrl() !== serverUrl) {
+      fail('Codex Desktop 尚未接入当前工作站内核，请先完成 Desktop 接入后创建项目。');
+    }
+    return await action({
+      async register(project, operation, saveOperation) {
+        let restartNeeded = operation.desktopWasRunning === true;
+        let registrationError;
+        const current = await host.inspect();
+        if (current.desktop !== info.desktop || current.desktopIdentity !== info.desktopIdentity) fail('Codex Desktop 安装版本发生变化，项目保留，未修改桌面文件。');
+        if (current.running) {
+          if (confirmed !== true) fail(desktopProjectRestartWarning, { desktopRestartRequired: true });
+          if (await host.sharedServiceUrl() !== serverUrl) fail('Codex Desktop 内核连接已变化，未关闭桌面。');
+          restartNeeded = true;
+          operation.desktopWasRunning = true;
+          await saveOperation();
+        }
+        try {
+          if (current.running) await host.closeDesktop(info.desktop);
+          if ((await host.inspect()).running) fail('Codex Desktop 尚未退出，未修改桌面文件。');
+          const original = await fs.readFile(stateFile);
+          const state = parseState(original);
+          const updated = registerProjectInState(state, project, codexDataRoot);
+          if (JSON.stringify(updated) !== JSON.stringify(state)) {
+            const backupDirectory = path.join(stateRoot, 'desktop-project-backups');
+            await fs.mkdir(backupDirectory, { recursive: true });
+            const backup = path.join(backupDirectory, `${operationId}-${randomUUID()}.json`);
+            await fs.writeFile(backup, original, { flag: 'wx', mode: 0o600 });
+            operation.desktopBackup = backup;
+            await saveOperation();
+            const temporary = `${stateFile}.${operationId}.tmp`;
+            try {
+              const source = original.toString('utf8');
+              const replacement = Buffer.from(`${source.startsWith('\uFEFF') ? '\uFEFF' : ''}${JSON.stringify(updated)}${source.endsWith('\n') ? '\n' : ''}`);
+              await fs.writeFile(temporary, replacement, { flag: 'wx', mode: 0o600 });
+              if ((await host.inspect()).running || digest(await fs.readFile(stateFile)) !== digest(original)) {
+                fail('Codex Desktop 状态在登记期间发生变化，未覆盖原文件，请核对后重试。');
+              }
+              await fs.rename(temporary, stateFile);
+              if (digest(await fs.readFile(stateFile)) !== digest(replacement)) throw new Error('Codex Desktop 登记文件未能核对，原状态备份已保留。');
+            } finally { await fs.rm(temporary, { force: true }); }
+          }
+          operation.desktopRegistered = true;
+          await saveOperation();
+        } catch (error) { registrationError = error; }
+        // Restore the UI even if the registry write failed. This never starts or
+        // restarts a kernel and never changes the service's active connections.
+        if (restartNeeded) {
+          try {
+            if (!(await host.inspect()).running) await host.startDesktop(info.desktop, { CODEX_APP_SERVER_WS_URL: serverUrl, CODEX_HOME: codexDataRoot });
+            const deadline = Date.now() + readyTimeoutMs;
+            while (!await host.desktopReady()) {
+              if (Date.now() >= deadline) throw new Error('Codex Desktop 尚未重新就绪。');
+              await wait(500);
+            }
+            if (await host.sharedServiceUrl() !== serverUrl) throw new Error('Desktop 未接入原工作站内核。');
+          } catch (error) {
+            throw new Error([registrationError?.message, `项目已保留，重新打开 Codex Desktop 未完成：${error.message}`].filter(Boolean).join(' '));
+          }
+        }
+        if (registrationError) throw registrationError;
+        const finalState = parseState(await fs.readFile(stateFile));
+        const verified = registerProjectInState(finalState, project, codexDataRoot);
+        if (JSON.stringify(verified) !== JSON.stringify(finalState)) throw new Error('项目已创建，但 Desktop 登记未能在最终文件中核对。');
+        return { status: 'registered', restarted: restartNeeded };
+      },
+    });
+  } finally { await release(); }
+}

package/dist/src/platform/linux/README.md

@@ -1,3 +1,3 @@
-# linux 被控主机（预留）
-
-仅规划 Codex 的系统路径、进程/IPC 和运行环境适配，尚未实现。接入排在控制端扩展之后；不预设支持 Desktop 共享任务。
+# linux 被控主机（预留）
+
+仅规划 Codex 的系统路径、进程/IPC 和运行环境适配，尚未实现。接入排在控制端扩展之后；不预设支持 Desktop 共享任务。

package/dist/src/platform/macos/README.md

@@ -1,3 +1,3 @@
-# macos 被控主机（预留）
-
-仅规划 Codex 的系统路径、进程/IPC 和运行环境适配，尚未实现。接入排在控制端扩展之后；不预设支持 Desktop 共享任务。
+# macos 被控主机（预留）
+
+仅规划 Codex 的系统路径、进程/IPC 和运行环境适配，尚未实现。接入排在控制端扩展之后；不预设支持 Desktop 共享任务。

package/dist/src/platform/macos/codex-runtime.mjs

@@ -0,0 +1,125 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
+import { compareVersions, verifyProtocol } from '../codex-protocol.mjs';
+import { readRecord, writeRecord } from '../../service-lifecycle.mjs';
+import { retainRuntime, runtimeFingerprint, packageRoot } from './retained-runtime.mjs';
+export { runtimeFingerprint, pruneRetainedDesktopRuntimes } from './retained-runtime.mjs';
+
+const exec = promisify(execFile);
+export const codeModeHostPath = executable => path.join(packageRoot(executable), 'bin/codex-code-mode-host');
+const fileExists = file => { try { return fs.statSync(file).isFile(); } catch (error) { if (error.code === 'ENOENT') return false; throw error; } };
+export function nativeExecutable(file) {
+  if (!fileExists(file)) return false;
+  const descriptor = fs.openSync(file, 'r');
+  try {
+    const magic = Buffer.alloc(4);
+    if (fs.readSync(descriptor, magic, 0, 4, 0) !== 4) return false;
+    return [0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic.readUInt32BE());
+  } finally { fs.closeSync(descriptor); }
+}
+export function runtimeFilesAvailable(executable) {
+  try { return nativeExecutable(executable) && nativeExecutable(codeModeHostPath(executable)); }
+  catch (error) { if (error.code === 'EACCES') throw error; return false; }
+}
+function nativeEntry(file) {
+  if (!fileExists(file)) return null;
+  file = fs.realpathSync(file);
+  if (nativeExecutable(file)) return file;
+  if (path.basename(path.dirname(file)) === 'bin') {
+    const bundle = path.resolve(file, '../../CodexCLI.app/Contents/MacOS/codex');
+    if (nativeExecutable(bundle)) return bundle;
+  }
+  return null;
+}
+
+// Match the official CLI's native package mapping. Never launch the npm JS shim as a kernel.
+export function discoverCodex(environment = process.env, { home = os.homedir(), arch = process.arch } = {}) {
+  if (!['arm64', 'x64'].includes(arch)) throw new Error(`不支持的 Mac CPU：${arch}`);
+  const found = new Map();
+  const add = (file, source) => {
+    file = nativeEntry(file);
+    if (!file) return;
+    fs.accessSync(file, fs.constants.X_OK);
+    const executable = fs.realpathSync(file);
+    if (!found.has(executable)) found.set(executable, { executable, source });
+  };
+  if (environment.CODE_RELAX_CODEX_PATH) {
+    const file = environment.CODE_RELAX_CODEX_PATH;
+    if (!path.isAbsolute(file) || path.basename(file) !== 'codex') throw new Error('CODE_RELAX_CODEX_PATH 必须是原生 codex 程序的绝对路径。');
+    add(file, 'explicit');
+    if (!found.size) throw new Error('指定的 Codex 原生程序不存在或不是 Mach-O 可执行文件。');
+    return [...found.values()];
+  }
+  for (const directory of ['/Applications', path.join(home, 'Applications')]) {
+    for (const name of ['ChatGPT.app', 'Codex.app']) {
+      const bundle = path.join(directory, name);
+      if (!fileExists(path.join(bundle, 'Contents/Info.plist'))) continue;
+      const id = execFileSync('/usr/bin/plutil', ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', path.join(bundle, 'Contents/Info.plist')], { encoding: 'utf8', timeout: 5000 }).trim();
+      if (id !== 'com.openai.codex') continue;
+      add(path.join(bundle, 'Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex'), 'desktop');
+    }
+  }
+  const codexHome = environment.CODEX_HOME?.trim() || path.join(home, '.codex');
+  const directories = [...String(environment.PATH || '').split(path.delimiter), environment.CODEX_INSTALL_DIR,
+    path.join(home, '.local/bin'), path.join(codexHome, 'packages/standalone/current/bin')].filter(item => item && path.isAbsolute(item));
+  const target = `${arch === 'arm64' ? 'aarch64' : 'x86_64'}-apple-darwin`;
+  for (const directory of new Set(directories)) {
+    const entry = path.join(directory, 'codex');
+    if (!fileExists(entry)) continue;
+    if (nativeEntry(entry)) { add(entry, 'cli'); continue; }
+    let root = path.dirname(fs.realpathSync(entry));
+    while (true) {
+      const packageFile = path.join(root, 'package.json');
+      if (fileExists(packageFile) && readRecord(packageFile)?.name === '@openai/codex') {
+        let vendor = path.join(root, 'vendor');
+        try { vendor = path.join(path.dirname(createRequire(packageFile).resolve(`@openai/codex-darwin-${arch}/package.json`)), 'vendor'); }
+        catch (error) { if (error.code !== 'MODULE_NOT_FOUND') throw error; }
+        add(path.join(vendor, target, 'bin/codex'), 'npm');
+        break;
+      }
+      const parent = path.dirname(root);
+      if (parent === root) break;
+      root = parent;
+    }
+  }
+  return [...found.values()];
+}
+
+export async function resolveCodexRuntime(stateRoot, { refresh = false, environment = process.env } = {}) {
+  fs.mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
+  const recordFile = path.join(stateRoot, 'codex-runtime.json');
+  const saved = readRecord(recordFile);
+  const codexHome = path.resolve(environment.CODEX_HOME?.trim() || saved?.codexHome || path.join(os.homedir(), '.codex'));
+  const explicit = environment.CODE_RELAX_CODEX_PATH || (saved?.source === 'explicit' ? saved.sourceExecutable : '');
+  if (!refresh && saved?.executable && (!explicit || explicit === saved.sourceExecutable) && codexHome === saved.codexHome
+      && runtimeFilesAvailable(saved.executable) && saved.fingerprint === runtimeFingerprint(saved.executable)) return saved;
+  const candidates = [], rejected = [];
+  for (const candidate of discoverCodex({ ...environment, CODEX_HOME: codexHome, CODE_RELAX_CODEX_PATH: explicit })) {
+    try {
+      if (candidate.source === 'desktop') {
+        const bundle = path.resolve(packageRoot(candidate.executable), '../../..');
+        await exec('/usr/bin/codesign', ['--verify', '--deep', '--strict', '-R=identifier \"com.openai.codex\" and anchor apple generic and certificate leaf[subject.OU] = \"2DC432GLL2\"', bundle], { timeout: 30000 });
+      }
+      if (!runtimeFilesAvailable(candidate.executable)) throw new Error('缺少配套原生 codex-code-mode-host');
+      const { stdout } = await exec(candidate.executable, ['--version'], { timeout: 10000, env: { ...environment, CODEX_HOME: codexHome } });
+      const version = /^codex-cli (\d+\.\d+\.\d+(?:-[\w.]+)?)/m.exec(stdout)?.[1];
+      if (!version) throw new Error('无法识别 Codex 版本');
+      candidates.push({ ...candidate, version });
+    } catch (error) { rejected.push(`${candidate.executable}: ${error.message}`); }
+  }
+  candidates.sort((a, b) => Number(b.source === 'desktop') - Number(a.source === 'desktop') || compareVersions(b.version, a.version));
+  for (const candidate of candidates) {
+    try {
+      const retained = await retainRuntime(candidate.executable, stateRoot, candidate.version);
+      await verifyProtocol(retained.executable, stateRoot);
+      const result = { ...candidate, ...retained, codexHome, fingerprint: runtimeFingerprint(retained.executable) };
+      writeRecord(recordFile, result);
+      return result;
+    } catch (error) { rejected.push(`${candidate.executable}: ${error.message}`); }
+  }
+  throw new Error(`未找到具备所需协议能力的 Mac Codex 内核，请安装官方 Codex 应用或完整 CLI 并登录账号。${rejected.length ? '\n' + rejected.join('\n') : ''}`);
+}

package/dist/src/platform/macos/credential-store.mjs

@@ -0,0 +1,10 @@
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { runtimePaths } from '../runtime-paths.mjs';
+import { systemRequest } from './system.mjs';
+
+export function credentialStore(action, record, root = runtimePaths().credentialsRoot) {
+  if (!['load', 'save'].includes(action)) throw new Error('无效的钥匙串操作。');
+  const account = createHash('sha256').update(path.resolve(root)).digest('hex');
+  return systemRequest({ operation: 'credentials', action, account, record });
+}

package/dist/src/platform/macos/desktop-host.mjs

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { startBackground } from '../../background-process.mjs';
+import { systemRequest } from './system.mjs';
+import { assertPlainPath } from '../../skill-install.mjs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { runtimePaths } from '../runtime-paths.mjs';
+import { readRecord } from '../../service-lifecycle.mjs';
+export { residentStartup } from './resident-startup.mjs';
+
+const managedUrl = 'ws://127.0.0.1:45839';
+export function createDesktopHost({ request = systemRequest, wait = delay, now = Date.now, timeout = 10000,
+  stateRoot = () => runtimePaths().stateRoot, fingerprint = file => {
+    const stat = fs.statSync(path.join(file, 'Contents/Info.plist'));
+    return `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+  } } = {}) {
+  return {
+    desktopIntegration: true,
+    async inspect() {
+      const info = await request({ operation: 'desktop-info' });
+      return { ...info, desktopIdentity: info.desktop ? `${info.desktop}:${info.version}:${info.build}:${fingerprint(info.desktop)}` : null };
+    },
+    process: pid => request({ operation: 'process', pid }),
+    start: startBackground,
+    async stop(pid, expected) {
+      if (!expected || expected.pid !== pid) throw new Error('停止内核前缺少进程身份，未结束任何进程。');
+      return request({ operation: 'stop', expected });
+    },
+    async sharedServiceUrl() {
+      return (await this.inspect()).connectedToManagedServer ? managedUrl : '';
+    },
+    async startDesktop(bundlePath, environment) {
+      if (environment.CODEX_APP_SERVER_WS_URL !== managedUrl) throw new Error('Desktop 内核地址与工作站不一致。');
+      const runtime = readRecord(path.join(stateRoot(), 'codex-runtime.json'));
+      const codexHome = environment.CODEX_HOME || runtime?.codexHome;
+      if (!codexHome || !path.isAbsolute(codexHome)) throw new Error('缺少已选内核的 CODEX_HOME，请先运行 relax setup。');
+      const info = await this.inspect();
+      if (info.running) throw new Error('Desktop 仍在运行，未创建第二个实例。');
+      if (info.desktop !== bundlePath) throw new Error('Codex Desktop 安装位置已变化，请重新检查。');
+      return request({ operation: 'desktop-start', bundlePath,
+        environment: { CODEX_HOME: codexHome, CODEX_APP_SERVER_WS_URL: managedUrl } });
+    },
+    async closeDesktop(bundlePath) {
+      const info = await this.inspect();
+      if (!info.running) return;
+      if (info.desktop !== bundlePath || !info.process) throw new Error('Desktop 进程身份已变化，未请求退出。');
+      await request({ operation: 'desktop-close', bundlePath, expected: info.process });
+      const deadline = now() + timeout;
+      while ((await this.inspect()).running) {
+        if (now() >= deadline) throw new Error('Desktop 尚未正常退出，请在 Mac 上处理未保存内容后重试；未强制结束进程。');
+        await wait(200);
+      }
+    },
+    async desktopReady() {
+      const info = await this.inspect();
+      return info.running && info.finishedLaunching && info.connectedToManagedServer;
+    },
+    async prepareKernelRestart() {
+      const info = await this.inspect();
+      if (!info.running || !info.connectedToManagedServer) return null;
+      await this.closeDesktop(info.desktop);
+      return info.desktop;
+    },
+    async resumeAfterKernelRestart(bundlePath, environment) {
+      if (!bundlePath) return;
+      await this.startDesktop(bundlePath, environment);
+      const deadline = now() + 30000;
+      while (!await this.desktopReady()) {
+        if (now() >= deadline) throw new Error('内核已就绪，但 Mac Desktop 尚未重新接入。');
+        await wait(500);
+      }
+    },
+    ready: async url => { try { return (await fetch(url, { signal: AbortSignal.timeout(1000) })).ok; } catch { return false; } },
+  };
+}
+export const desktopHost = createDesktopHost();
+export async function resolveStateRoot(stateRoot) {
+  assertPlainPath(stateRoot);
+  fs.mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
+  return fs.realpathSync(stateRoot);
+}
+export async function removeDesktopShortcut() { return { removed: false, reason: 'not-used-on-macos' }; }

package/dist/src/platform/macos/desktop-project-registration.mjs

@@ -0,0 +1,10 @@
+import { desktopHost } from './desktop-host.mjs';
+import { withDesktopProjectRegistration as register } from '../desktop-project-store.mjs';
+
+// Verified against the Mac 26.1007.71326 local-projects/project-order store.
+export async function withDesktopProjectRegistration(options, action) {
+  const host = options.host || desktopHost;
+  if (!(await host.inspect()).desktop)
+    return action({ register: async () => ({ status: 'not-applicable', reason: 'desktop-not-installed' }) });
+  return register({ ...options, host }, action);
+}

package/dist/src/platform/macos/network-info.mjs

@@ -0,0 +1,28 @@
+import os from 'node:os';
+import net from 'node:net';
+import { systemRequest } from './system.mjs';
+
+const privateIpv4 = address => {
+  if (net.isIP(address) !== 4) return false;
+  const [a, b] = address.split('.').map(Number);
+  return a === 10 || (a === 192 && b === 168) || (a === 172 && b >= 16 && b <= 31) || (a === 100 && b >= 64 && b <= 127);
+};
+export function networkCandidates(hardware, addresses) {
+  const results = [];
+  const seen = new Set();
+  for (const item of hardware) {
+    if (!['wifi', 'ethernet'].includes(item.networkType) || typeof item.interfaceName !== 'string') continue;
+    const label = value => String(value).replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 80);
+    const interfaceName = label(item.interfaceName), networkName = label(item.networkName || interfaceName);
+    if (!interfaceName || !networkName) continue;
+    for (const info of addresses[item.interfaceName] || []) {
+      if (info.internal || !privateIpv4(info.address) || seen.has(info.address)) continue;
+      seen.add(info.address);
+      results.push({ address: info.address, interfaceName, networkName, networkType: item.networkType });
+    }
+  }
+  return results.slice(0, 8);
+}
+export async function lanNetworks() {
+  return networkCandidates(await systemRequest({ operation: 'network-interfaces' }), os.networkInterfaces());
+}

package/dist/src/platform/macos/project-locations.mjs

@@ -0,0 +1,8 @@
+import path from 'node:path';
+import { systemRequest } from './system.mjs';
+
+export async function projectLocations() {
+  const { home, documents, downloads } = await systemRequest({ operation: 'locations' });
+  if (![home, documents, downloads].every(value => typeof value === 'string' && path.isAbsolute(value))) throw new Error('Mac 用户目录无效。');
+  return { home, downloads, defaultParent: path.join(documents, 'ChatGPT'), roots: ['/'] };
+}

package/dist/src/platform/macos/resident-startup.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readRecord } from '../../service-lifecycle.mjs';
+import { assertPlainPath } from '../../skill-install.mjs';
+import { runtimePaths } from '../runtime-paths.mjs';
+
+const exec = promisify(execFile);
+export const launchAgentLabel = 'cn.walkhi.code-relax';
+const xml = value => String(value).replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' }[character]));
+export function launchAgentPlist({ serviceRoot, nodeExecutable, stateRoot, home, environment }) {
+  const entry = path.join(serviceRoot, 'dist/bin/codex-remote.mjs');
+  // npm adds temporary .bin directories during postinstall. Login must use the
+  // user's stable tool paths after the source archive has been removed.
+  const stablePath = String(environment.PATH || '').split(':')
+    .filter(value => value.startsWith('/') && !value.endsWith('/node_modules/.bin')).join(':');
+  const variables = { HOME: home, PATH: stablePath || '/usr/bin:/bin:/usr/sbin:/sbin' };
+  for (const name of ['CODEX_HOME', 'CODEX_INSTALL_DIR', 'CODE_RELAX_CODEX_PATH']) if (environment[name]) variables[name] = environment[name];
+  const strings = [nodeExecutable, entry, ...Object.values(variables), stateRoot];
+  if (strings.some(value => /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(value))) throw new Error('登录启动参数含无效控制字符。');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${launchAgentLabel}</string>
+<key>ProgramArguments</key><array>${[nodeExecutable, entry, 'start', '--json'].map(value => `<string>${xml(value)}</string>`).join('')}</array>
+<key>RunAtLoad</key><true/>
+<key>AbandonProcessGroup</key><true/>
+<key>EnvironmentVariables</key><dict>${Object.entries(variables).map(([key, value]) => `<key>${key}</key><string>${xml(value)}</string>`).join('')}</dict>
+<key>StandardOutPath</key><string>${xml(path.join(stateRoot, 'login.stdout.log'))}</string>
+<key>StandardErrorPath</key><string>${xml(path.join(stateRoot, 'login.stderr.log'))}</string>
+</dict></plist>
+`;
+}
+
+export async function residentStartup({ serviceRoot, nodeExecutable }, action = 'status') {
+  if (!['status', 'enable', 'disable'].includes(action)) throw new Error('无效的登录启动操作。');
+  const uid = process.getuid();
+  if (uid === 0) throw new Error('请以普通 Mac 用户安装 Code Relax，不使用 sudo。');
+  const home = os.homedir();
+  const file = path.join(home, 'Library/LaunchAgents', `${launchAgentLabel}.plist`);
+  const domain = `gui/${uid}`, target = `${domain}/${launchAgentLabel}`;
+  assertPlainPath(file);
+  let current;
+  if (fs.existsSync(file)) {
+    const { stdout } = await exec('/usr/bin/plutil', ['-convert', 'json', '-o', '-', file], { timeout: 5000 });
+    current = JSON.parse(stdout);
+    if (current.Label !== launchAgentLabel || current.ProgramArguments?.[1] !== path.join(serviceRoot, 'dist/bin/codex-remote.mjs'))
+      throw new Error('同名 LaunchAgent 不属于此安装，未覆盖或移除。');
+  }
+  const { stdout: disabled } = await exec('/bin/launchctl', ['print-disabled', domain], { timeout: 5000 });
+  const isDisabled = /"cn\.walkhi\.code-relax"\s*=>\s*true/.test(disabled);
+  const expectedArguments = [nodeExecutable, path.join(serviceRoot, 'dist/bin/codex-remote.mjs'), 'start', '--json'];
+  const enabled = JSON.stringify(current?.ProgramArguments) === JSON.stringify(expectedArguments)
+    && current.RunAtLoad === true && current.AbandonProcessGroup === true
+    && current.EnvironmentVariables?.HOME === home && !isDisabled;
+  if (action === 'status') return { enabled, path: file, mechanism: 'LaunchAgent' };
+  if (action === 'disable') {
+    if (!current) return { enabled: false, removed: false, path: file };
+    let loaded = false;
+    try { await exec('/bin/launchctl', ['print', target], { timeout: 5000 }); loaded = true; }
+    catch (error) { if (error.code !== 113) throw error; }
+    if (loaded) await exec('/bin/launchctl', ['bootout', target], { timeout: 5000 });
+    await exec('/bin/launchctl', ['disable', target], { timeout: 5000 });
+    fs.unlinkSync(file);
+    return { enabled: false, removed: true, path: file };
+  }
+  const { stateRoot } = runtimePaths();
+  const runtime = readRecord(path.join(stateRoot, 'codex-runtime.json'));
+  const environment = { ...process.env, ...(runtime?.codexHome ? { CODEX_HOME: runtime.codexHome } : {}) };
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(temporary, launchAgentPlist({ serviceRoot, nodeExecutable, stateRoot, home, environment }), { flag: 'wx', mode: 0o600 });
+    await exec('/usr/bin/plutil', ['-lint', temporary], { timeout: 5000 });
+    fs.renameSync(temporary, file);
+  } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
+  await exec('/bin/launchctl', ['enable', target], { timeout: 5000 });
+  // setup/start already launches the service. Bootstrap would run a second start
+  // concurrently; launchd will load this user agent at the next GUI login.
+  return { enabled: true, path: file, mechanism: 'LaunchAgent', appliesAtNextLogin: true };
+}