@walkhi/code-relax 0.1.0-beta.1 → 0.1.0-beta.100

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

@@ -0,0 +1,114 @@
+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';
+
+import { managedEndpointUrl, readManagedEndpoint } from '../../managed-endpoint.mjs';
+export function createDesktopHost({ request = systemRequest, wait = delay, now = Date.now, timeout = 30000,
+  diagnose = record => console.info(JSON.stringify({ time: new Date().toISOString(), event: 'mac-desktop-close', ...record })),
+  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 url = readManagedEndpoint(stateRoot());
+      const info = await request({ operation: 'desktop-info', url });
+      return { ...info, managedUrl: url, desktopIdentity: info.desktop ? `${info.desktop}:${info.version}:${info.build}:${fingerprint(info.desktop)}` : null };
+    },
+    process: pid => request({ operation: 'process', pid }),
+    ownsListener: (expected, url) => request({ operation: 'owns-listener', expected, url }),
+    start: startBackground,
+    async stop(pid, expected) {
+      if (!expected || expected.pid !== pid) throw new Error('停止内核前缺少进程身份，未结束任何进程。');
+      return request({ operation: 'stop', expected });
+    },
+    async sharedServiceUrl() {
+      const info = await this.inspect();
+      return info.connectedToManagedServer ? info.managedUrl : '';
+    },
+    async startDesktop(bundlePath, environment) {
+      const managedUrl = managedEndpointUrl(environment.CODEX_APP_SERVER_WS_URL);
+      if (!managedUrl || managedUrl !== readManagedEndpoint(stateRoot())) 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 进程身份已变化，未请求退出。');
+      const started = now();
+      const identity = value => value ? { pid: value.pid, created: value.created, executable: value.executable } : null;
+      const context = { target: identity(info.process), version: info.version, build: info.build, timeoutMs: timeout };
+      diagnose({ ...context, stage: 'request' });
+      let result;
+      try { result = await request({ operation: 'desktop-close', bundlePath, expected: info.process }); }
+      catch (error) {
+        diagnose({ ...context, stage: 'request-failed', elapsedMs: now() - started, error: error.message });
+        throw error;
+      }
+      diagnose({ ...context, stage: 'request-returned', elapsedMs: now() - started,
+        quitRequested: result.quitRequested === true, alreadyStopped: result.stopped === true });
+      const deadline = now() + timeout;
+      while (true) {
+        let current;
+        try { current = await this.inspect(); }
+        catch (error) {
+          diagnose({ ...context, stage: 'inspect-failed', elapsedMs: now() - started, error: error.message });
+          throw error;
+        }
+        const observation = { ...context, elapsedMs: now() - started, current: identity(current.process),
+          finishedLaunching: current.finishedLaunching, connectedToManagedServer: current.connectedToManagedServer };
+        if (!current.running) { diagnose({ ...observation, stage: 'exited' }); return; }
+        if (current.process?.pid !== info.process.pid || current.process?.created !== info.process.created) {
+          diagnose({ ...observation, stage: 'process-changed' });
+          throw Object.assign(new Error('Mac 桌面端进程已变化，请刷新状态核对；未再次请求退出。'), { code: 'MAC_DESKTOP_CLOSE_CHANGED' });
+        }
+        if (now() >= deadline) {
+          diagnose({ ...observation, stage: 'timeout', quitRequested: result.quitRequested === true });
+          throw Object.assign(new Error('Mac 桌面端退出请求已发送，但未在等待时间内退出。请在 Mac 查看桌面端退出状态和诊断日志；未强制结束进程。'), { code: 'MAC_DESKTOP_CLOSE_TIMEOUT' });
+        }
+        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,11 @@
+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' }),
+      remove: async (_project, _operation, _save, removeNative) => { await removeNative(); return { status: 'not-applicable', reason: 'desktop-not-installed' }; } });
+  return register({ ...options, host }, action);
+}

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

@@ -0,0 +1,8 @@
+import os from 'node:os';
+import { systemRequest } from './system.mjs';
+import { networkCandidates } from '../posix/network-candidates.mjs';
+export { networkCandidates } from '../posix/network-candidates.mjs';
+
+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 };
+}

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

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { readRecord, writeRecord } from '../../service-lifecycle.mjs';
+
+const owner = 'code-relax-macos-runtime';
+const manifestName = '.code-relax-runtime.json';
+function filesAt(root, relative = '') {
+  const result = [];
+  if (fs.lstatSync(root).isSymbolicLink()) throw new Error('Codex 运行时目录不能是符号链接。');
+  for (const entry of fs.readdirSync(path.join(root, relative), { withFileTypes: true })) {
+    const name = path.join(relative, entry.name);
+    if (entry.isDirectory()) result.push(...filesAt(root, name));
+    else if (entry.isFile()) result.push(name);
+    else throw new Error(`Codex 运行时包含不支持的链接或文件：${name}`);
+  }
+  return result.sort();
+}
+export function packageRoot(executable) {
+  const bundleSuffix = path.join('CodexCLI.app', 'Contents', 'MacOS', 'codex');
+  const bundled = executable.endsWith(path.sep + bundleSuffix);
+  const root = bundled ? path.resolve(executable, '../../../..') : path.dirname(path.dirname(executable));
+  const metadata = readRecord(path.join(root, 'codex-package.json'));
+  if ((!bundled && path.basename(path.dirname(executable)) !== 'bin') || path.basename(executable) !== 'codex'
+      || metadata?.layoutVersion !== 1 || metadata.entrypoint !== 'bin/codex' || metadata.variant !== 'codex'
+      || !['aarch64-apple-darwin', 'x86_64-apple-darwin'].includes(metadata.target)
+      || metadata.resourcesDir !== 'codex-resources' || metadata.pathDir !== 'codex-path')
+    throw new Error('需要完整的官方 Mac Codex 运行时包，不能仅复制 codex 单个文件。');
+  for (const file of ['bin/codex', 'bin/codex-code-mode-host', 'codex-path/rg']) {
+    if (!fs.statSync(path.join(root, file)).isFile()) throw new Error(`Codex 运行时缺少 ${file}`);
+  }
+  if (!fs.statSync(path.join(root, 'codex-resources')).isDirectory()) throw new Error('Codex 运行时缺少资源目录。');
+  return root;
+}
+export function runtimeFingerprint(executable) {
+  const root = packageRoot(executable);
+  return JSON.stringify(filesAt(root).filter(name => name !== manifestName).map(name => {
+    const stat = fs.statSync(path.join(root, name));
+    return [name, stat.size, stat.mtimeMs, stat.ctimeMs, stat.ino, stat.mode & 0o777];
+  }));
+}
+async function digestFiles(root) {
+  const records = [];
+  for (const name of filesAt(root).filter(name => name !== manifestName)) {
+    const file = path.join(root, name), hash = createHash('sha256');
+    const before = fs.statSync(file);
+    for await (const chunk of fs.createReadStream(file)) hash.update(chunk);
+    const after = fs.statSync(file);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || before.ino !== after.ino)
+      throw new Error('Codex 更新正在替换文件，请待安装完成后重试。');
+    records.push({ name, size: after.size, mode: after.mode & 0o777, sha256: hash.digest('hex') });
+  }
+  return records;
+}
+const treeHash = files => createHash('sha256').update(JSON.stringify(files)).digest('hex');
+function removeFiles(root, names) {
+  for (const name of names) {
+    fs.unlinkSync(path.join(root, name));
+  }
+  // Empty package resource directories must also be removed, without recursive deletion.
+  const collect = directory => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (!entry.isDirectory()) throw new Error('运行时清理期间出现未知文件，保留目录。');
+      const child = path.join(directory, entry.name); collect(child); fs.rmdirSync(child);
+    }
+  };
+  collect(root);
+  fs.rmdirSync(root);
+}
+
+export async function retainRuntime(executable, stateRoot, version) {
+  const source = packageRoot(executable);
+  const sourceFingerprint = runtimeFingerprint(executable);
+  const files = await digestFiles(source);
+  if (sourceFingerprint !== runtimeFingerprint(executable)) throw new Error('Codex 包在核对期间发生变化，未切换内核。');
+  const digest = treeHash(files);
+  const parent = path.join(stateRoot, 'macos-runtimes'), target = path.join(parent, digest);
+  const retained = path.join(target, path.relative(source, executable));
+  if (fs.existsSync(target)) {
+    const manifest = readRecord(path.join(target, manifestName));
+    if (manifest?.owner !== owner || manifest.digest !== digest || treeHash(await digestFiles(target)) !== digest)
+      throw new Error('已保留的 Mac 内核内容不完整，未覆盖运行中的文件。');
+    return { executable: retained, sourceExecutable: executable, sourceFingerprint };
+  }
+  fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+  const staging = path.join(parent, `.${randomUUID()}.tmp`);
+  fs.mkdirSync(staging, { mode: 0o700 });
+  const created = [];
+  try {
+    for (const file of files) {
+      const destination = path.join(staging, file.name);
+      fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+      // APFS can clone blocks, but each snapshot has independent file identity.
+      // A hard link would let an in-place npm update modify the running kernel.
+      fs.copyFileSync(path.join(source, file.name), destination, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE);
+      created.push(file.name);
+      fs.chmodSync(destination, file.mode);
+    }
+    fs.mkdirSync(path.join(staging, 'codex-resources'), { recursive: true, mode: 0o700 });
+    if (treeHash(await digestFiles(staging)) !== digest || sourceFingerprint !== runtimeFingerprint(executable))
+      throw new Error('复制期间 Codex 包发生变化，未使用混合版本。');
+    writeRecord(path.join(staging, manifestName), { owner, digest, version, files });
+    created.push(manifestName);
+    fs.renameSync(staging, target);
+    return { executable: retained, sourceExecutable: executable, sourceFingerprint };
+  } catch (error) {
+    if (fs.existsSync(staging)) removeFiles(staging, created);
+    throw error;
+  }
+}
+
+export async function pruneRetainedDesktopRuntimes(stateRoot, keepExecutable) {
+  const parent = path.join(stateRoot, 'macos-runtimes');
+  if (!fs.existsSync(parent)) return;
+  const keep = packageRoot(path.resolve(keepExecutable));
+  // An installed (non-retained) process is not authority to clean this store.
+  if (path.dirname(keep) !== path.resolve(parent) || !/^[a-f0-9]{64}$/.test(path.basename(keep))) return;
+  for (const entry of fs.readdirSync(parent, { withFileTypes: true })) {
+    const directory = path.join(parent, entry.name);
+    if (!entry.isDirectory() || !/^[a-f0-9]{64}$/.test(entry.name) || directory === keep) continue;
+    const manifest = readRecord(path.join(directory, manifestName));
+    if (manifest?.owner !== owner || manifest.digest !== entry.name || !Array.isArray(manifest.files)) continue;
+    const actual = await digestFiles(directory);
+    if (treeHash(actual) !== entry.name || JSON.stringify(actual) !== JSON.stringify(manifest.files)) continue;
+    removeFiles(directory, [...actual.map(file => file.name), manifestName]);
+  }
+}

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

@@ -0,0 +1,18 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runtimePaths } from '../runtime-paths.mjs';
+import { readRecord } from '../../service-lifecycle.mjs';
+import { lanNetworks } from './network-info.mjs';
+import { desktopHost } from './desktop-host.mjs';
+
+export { lanNetworks };
+export const lanAddress = async () => (await lanNetworks())[0]?.address || '';
+export const sharedServiceUrl = () => desktopHost.sharedServiceUrl();
+export async function bridgeEnvironment() {
+  const environment = { ...process.env };
+  const installed = readRecord(path.join(runtimePaths().serviceRoot, 'installation.json'));
+  if (!installed?.nodeExecutable || !fs.existsSync(installed.nodeExecutable)) throw new Error('安装时选用的 Node 不存在，请重新执行 relax setup。');
+  environment.CODEX_MCP_NODE_PATH = installed.nodeExecutable;
+  delete environment.CODEX_APP_TOOLS_PIPE_PATH;
+  return { executable: installed.nodeExecutable, environment };
+}

package/dist/src/platform/macos/system.mjs

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const hostBinary = fileURLToPath(new URL('../../../native/macos-host/CodeRelaxHost', import.meta.url));
+export function systemRequest(request) {
+  if (process.platform !== 'darwin') return Promise.reject(new Error('需要 macOS 工作站。'));
+  if (!fs.existsSync(hostBinary)) return Promise.reject(new Error('缺少 Mac 系统适配组件，请先在 Mac 上执行 npm run build。'));
+  return new Promise((resolve, reject) => {
+    const child = spawn(hostBinary, [], { stdio: ['pipe', 'pipe', 'pipe'] });
+    let output = '', diagnostic = '', failure;
+    const timer = setTimeout(() => { failure = new Error('macOS 系统操作超时；请检查钥匙串是否已解锁。'); child.kill(); }, 60000);
+    child.stdout.setEncoding('utf8'); child.stderr.setEncoding('utf8');
+    child.stdout.on('data', value => {
+      output += value;
+      if (Buffer.byteLength(output) > 2 * 1024 * 1024) { failure = new Error('macOS 系统响应过大。'); child.kill(); }
+    });
+    child.stderr.on('data', value => { diagnostic = (diagnostic + value).slice(0, 1024); });
+    child.stdin.on('error', () => {});
+    child.once('error', () => { clearTimeout(timer); reject(new Error('无法启动 macOS 系统适配组件。')); });
+    child.once('close', code => {
+      clearTimeout(timer);
+      if (failure || code !== 0) return reject(failure || new Error(`macOS 系统操作失败：${diagnostic.trim() || code}`));
+      try { resolve(JSON.parse(output)); }
+      catch { reject(new Error('macOS 系统组件返回无效结果。')); }
+    });
+    child.stdin.end(JSON.stringify(request));
+  });
+}

package/dist/src/platform/macos/user-environment.mjs

@@ -0,0 +1,31 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { managedUserEnvironment, managedEnvironmentName } from '../managed-user-environment.mjs';
+import { systemRequest } from './system.mjs';
+
+const exec = promisify(execFile);
+const launchctl = async args => (await exec('/bin/launchctl', args, { timeout: 5000 })).stdout.trim();
+const readVariable = async name => {
+  try { return await launchctl(['getenv', name]); }
+  catch (error) { if (error.code === 1 && !error.stdout && !error.stderr) return ''; throw error; }
+};
+const adapter = managedUserEnvironment({
+  // The existing login service restores this only after the kernel is verified.
+  // A second static setenv LaunchAgent could race a newly selected dynamic port.
+  scope: 'user-launchd',
+  read: async () => {
+    if (process.getuid() === 0) throw new Error('请以普通 Mac 用户配置内核环境，不使用 sudo。');
+    await launchctl(['print-disabled', `gui/${process.getuid()}`]);
+    if (await launchctl(['managername']) !== 'Aqua')
+      throw new Error('请在当前 Mac 图形登录会话的终端运行 relax setup，以配置 Desktop 的用户环境。');
+    return { value: await readVariable(managedEnvironmentName), forceCli: await readVariable('CODEX_APP_SERVER_FORCE_CLI') };
+  },
+  set: url => launchctl(['setenv', managedEnvironmentName, url]),
+  unset: () => launchctl(['unsetenv', managedEnvironmentName]),
+});
+export async function configureManagedEnvironment(stateRoot, url) {
+  if (!(await systemRequest({ operation: 'desktop-info', url })).desktop)
+    return { configured: false, reason: 'desktop-not-installed' };
+  return adapter.configureManagedEnvironment(stateRoot, url);
+}
+export const { clearManagedEnvironment } = adapter;

package/dist/src/platform/managed-user-environment.mjs

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { readRecord, writeRecord } from '../service-lifecycle.mjs';
+import { managedEndpointUrl } from '../managed-endpoint.mjs';
+import { assertPlainPath } from '../skill-install.mjs';
+
+export const managedEnvironmentName = 'CODEX_APP_SERVER_WS_URL';
+const readText = file => {
+  try { return fs.readFileSync(file, 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+};
+
+// Platform adapters own the session mechanism; ownership and file updates are shared.
+export function managedUserEnvironment({ file = null, render, read, set, unset, scope, environment = process.env }) {
+  const values = record => record?.file === file && record?.scope === scope && record?.name === managedEnvironmentName ? record.values || [] : [];
+  const ownedValue = (record, value) => !!value && values(record).some(item => managedEndpointUrl(item) === value);
+  const ownedFile = (record, text) => !!file && text !== null && values(record)
+    .some(value => managedEndpointUrl(value) && text === render(value));
+  return {
+    async configureManagedEnvironment(stateRoot, url) {
+      if (!managedEndpointUrl(url)) throw new Error('未确认 Codex 内核地址，未修改环境变量。');
+      const ownershipPath = path.join(stateRoot, 'managed-environment.json');
+      if (file) assertPlainPath(file);
+      assertPlainPath(ownershipPath);
+      const record = readRecord(ownershipPath), text = file ? readText(file) : null, current = await read();
+      if (environment.CODEX_APP_SERVER_FORCE_CLI === '1' || current.forceCli === '1')
+        throw new Error('CODEX_APP_SERVER_FORCE_CLI=1 会让 Codex 忽略当前内核地址；未修改该配置。');
+      if (current.value && (current.value !== url || record) && !ownedValue(record, current.value))
+        throw new Error('用户已有其他 CODEX_APP_SERVER_WS_URL；未覆盖该配置。');
+      if (text !== null && !ownedFile(record, text))
+        throw new Error('同名用户环境文件不属于此安装或已被修改，未覆盖。');
+      if (!record && text === null && current.value === url)
+        return { configured: true, changed: false, owned: false, persistent: false, scope, value: url };
+      const expected = file ? render(url) : null, changed = text !== expected || current.value !== url;
+      // Journal owned endpoints before mutation so interrupted updates remain recoverable.
+      const ownership = { name: managedEnvironmentName, value: url, file, scope,
+        values: [...new Set([url, ...values(record).filter(value => value === current.value || (file && render(value) === text))])],
+        configuredAt: new Date().toISOString() };
+      writeRecord(ownershipPath, ownership);
+      if (text !== expected) {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        try {
+          fs.writeFileSync(temporary, expected, { flag: 'wx', mode: 0o600 });
+          fs.renameSync(temporary, file);
+        } finally { fs.rmSync(temporary, { force: true }); }
+      }
+      if (current.value !== url) await set(url);
+      if ((await read()).value !== url) throw new Error('CODEX_APP_SERVER_WS_URL 写入后读回不一致。');
+      ownership.values = [url];
+      writeRecord(ownershipPath, ownership);
+      return { configured: true, changed, owned: true, persistent: !!file, restoredAtServiceStart: true, scope, value: url };
+    },
+    async clearManagedEnvironment(stateRoot) {
+      const ownershipPath = path.join(stateRoot, 'managed-environment.json');
+      if (file) assertPlainPath(file);
+      assertPlainPath(ownershipPath);
+      const record = readRecord(ownershipPath), text = file ? readText(file) : null;
+      if (!record && text === null) return { removed: false, preserved: false, reason: 'not-owned' };
+      const current = await read();
+      let removed = false, preserved = false;
+      if (text !== null) {
+        if (ownedFile(record, text)) { fs.unlinkSync(file); removed = true; }
+        else preserved = true;
+      }
+      if (current.value) {
+        if (ownedValue(record, current.value)) {
+          await unset();
+          if ((await read()).value) throw new Error('CODEX_APP_SERVER_WS_URL 清理后读回仍不为空。');
+          removed = true;
+        } else preserved = true;
+      }
+      fs.rmSync(ownershipPath, { force: true });
+      return { removed, preserved, reason: preserved ? 'user-modified-or-not-owned' : removed ? 'removed' : 'already-empty' };
+    },
+  };
+}

package/dist/src/platform/native-package.mjs

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+export const nativeTargets = Object.freeze({
+  'win32-x64': { packageName: '@walkhi/code-relax-native-win32-x64', file: 'desktop-helper/CodeRelaxDesktop.exe' },
+  'darwin-arm64': { packageName: '@walkhi/code-relax-native-darwin-arm64', file: 'macos-host/CodeRelaxHost' },
+  'darwin-x64': { packageName: '@walkhi/code-relax-native-darwin-x64', file: 'macos-host/CodeRelaxHost' },
+  'linux-x64': { packageName: null, file: null },
+  'linux-arm64': { packageName: null, file: null },
+});
+
+const readJson = file => JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+
+// Native dependencies are selected by npm's os/cpu filters. Materialize only
+// this platform's helper before setup touches the installed workstation.
+export function prepareNativePackage(packageRoot, { platform = process.platform, arch = process.arch } = {}) {
+  const target = nativeTargets[`${platform}-${arch}`];
+  if (!target) throw new Error(`尚不支持此工作站平台：${platform}-${arch}。`);
+  const marker = path.join(packageRoot, 'dist/build-platform.json');
+  const build = readJson(marker);
+  if (!target.file) {
+    const pkg = readJson(path.join(packageRoot, 'package.json'));
+    if (!(build.platform === platform && build.arch === arch)
+        && !(build.layout === 'npm-platform-packages' && build.version === pkg.version))
+      throw new Error('安装包构建与当前系统、架构或版本不匹配，请重新安装。');
+    // Linux adapters use Node/procfs and the session's Secret Service. There is
+    // no private native helper to download; sharp/RTC select their own binaries.
+    fs.writeFileSync(marker, JSON.stringify({ platform, arch, version: pkg.version }));
+    return { platform, arch, materialized: false };
+  }
+  const destination = path.join(packageRoot, 'dist/native', target.file);
+  if (build.platform === platform && build.arch === arch) {
+    if (!fs.statSync(destination).isFile()) throw new Error('安装包缺少当前平台原生组件，请重新安装。');
+    if (platform === 'win32' && !fs.statSync(destination + '.update.json').isFile()) throw new Error('安装包缺少辅助组件升级签名。');
+    return { platform, arch, materialized: false };
+  }
+  const pkg = readJson(path.join(packageRoot, 'package.json'));
+  if (build.layout !== 'npm-platform-packages' || build.version !== pkg.version)
+    throw new Error('安装包构建与当前系统、架构或版本不匹配，请重新安装。');
+  const nativeVersion = pkg.optionalDependencies?.[target.packageName];
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(nativeVersion || ''))
+    throw new Error('安装包未锁定当前平台原生组件的精确版本。');
+  let manifest;
+  try { manifest = createRequire(path.join(packageRoot, 'package.json')).resolve(`${target.packageName}/package.json`); }
+  catch (error) {
+    if (error.code !== 'MODULE_NOT_FOUND') throw error;
+    throw new Error(`缺少 ${target.packageName}@${nativeVersion}；请勿省略 optional 依赖，使用 npm install -g @walkhi/code-relax@${pkg.version} --include=optional --allow-scripts=@walkhi/code-relax --foreground-scripts 重新安装。`);
+  }
+  const native = readJson(manifest);
+  if (native.name !== target.packageName || native.version !== nativeVersion
+      || native.os?.length !== 1 || native.os[0] !== platform || native.cpu?.length !== 1 || native.cpu[0] !== arch)
+    throw new Error('原生组件包的系统、架构或版本不匹配，未更新工作站。');
+  const source = path.join(path.dirname(manifest), 'native', target.file);
+  if (!fs.statSync(source).isFile()) throw new Error('平台包缺少原生组件，未更新工作站。');
+  const cameraSource = platform === 'win32' ? path.join(path.dirname(source), 'CodeRelaxCamera.exe') : null;
+  if (cameraSource && !fs.statSync(cameraSource).isFile()) throw new Error('平台包缺少摄像头组件，未更新工作站。');
+  if (platform === 'win32' && !fs.statSync(source + '.update.json').isFile()) throw new Error('平台包缺少辅助组件升级签名。');
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(source, destination);
+  if (cameraSource) {
+    fs.copyFileSync(cameraSource, path.join(path.dirname(destination), 'CodeRelaxCamera.exe'));
+    fs.copyFileSync(source + '.update.json', destination + '.update.json');
+  }
+  if (platform === 'darwin') fs.chmodSync(destination, 0o755);
+  // Only commit the selected platform after the component has been copied.
+  fs.writeFileSync(marker, JSON.stringify({ platform, arch, version: pkg.version }));
+  return { platform, arch, packageName: native.name, materialized: true };
+}

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

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

package/dist/src/platform/path-identity.mjs

@@ -0,0 +1,5 @@
+import path from 'node:path';
+export function executableKey(file, platform = process.platform) {
+  const resolved = path.resolve(file);
+  return platform === 'win32' ? resolved.toLowerCase() : resolved;
+}

package/dist/src/platform/posix/network-candidates.mjs

@@ -0,0 +1,23 @@
+import net from 'node:net';
+
+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);
+}