@walkhi/code-relax 0.1.0-beta.65 → 0.1.0-beta.68

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

@@ -1,76 +1,76 @@
-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-linux-runtime';
-const manifestName = '.code-relax-runtime.json';
-// Linux Desktop currently ships a flat, statically linked runtime, unlike Mac.
-const names = ['codex', 'codex-code-mode-host', 'rg'];
-export function runtimeFingerprint(executable) {
-  return JSON.stringify(names.map(name => {
-    const stat = fs.statSync(path.join(path.dirname(executable), name));
-    return [name, stat.size, stat.mtimeMs, stat.ctimeMs, stat.ino, stat.mode & 0o777];
-  }));
-}
-async function digestFiles(root) {
-  const files = [];
-  for (const name of names) {
-    const file = path.join(root, name), hash = createHash('sha256');
-    const before = fs.lstatSync(file);
-    if (!before.isFile()) throw new Error(`Linux 内核组件不是普通文件：${name}`);
-    for await (const chunk of fs.createReadStream(file)) hash.update(chunk);
-    const after = fs.statSync(file);
-    if (before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
-      throw new Error('Linux 内核更新正在替换文件，请稍后重试。');
-    files.push({ name, size: after.size, mode: after.mode & 0o777, sha256: hash.digest('hex') });
-  }
-  return files;
-}
-const treeHash = files => createHash('sha256').update(JSON.stringify(files)).digest('hex');
-export async function retainRuntime(executable, stateRoot, version) {
-  const source = path.dirname(executable), sourceFingerprint = runtimeFingerprint(executable);
-  const files = await digestFiles(source), digest = treeHash(files);
-  if (sourceFingerprint !== runtimeFingerprint(executable)) throw new Error('Linux 内核在核对期间发生变化。');
-  const parent = path.join(stateRoot, 'linux-runtimes'), target = path.join(parent, digest);
-  const result = { executable: path.join(target, 'codex'), sourceExecutable: executable, sourceFingerprint };
-  if (fs.existsSync(target)) {
-    if (readRecord(path.join(target, manifestName))?.owner !== owner || treeHash(await digestFiles(target)) !== digest)
-      throw new Error('保留的 Linux 内核不完整，未覆盖运行中的文件。');
-    return result;
-  }
-  fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
-  const staging = path.join(parent, `.${randomUUID()}.tmp`), created = [];
-  fs.mkdirSync(staging, { mode: 0o700 });
-  try {
-    for (const file of files) {
-      const destination = path.join(staging, file.name);
-      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);
-    }
-    if (treeHash(await digestFiles(staging)) !== digest || sourceFingerprint !== runtimeFingerprint(executable))
-      throw new Error('Linux 内核复制期间发生变化，未使用混合版本。');
-    writeRecord(path.join(staging, manifestName), { owner, digest, version, files });
-    created.push(manifestName);
-    fs.renameSync(staging, target);
-    return result;
-  } catch (error) {
-    if (fs.existsSync(staging)) { for (const name of created) fs.unlinkSync(path.join(staging, name)); fs.rmdirSync(staging); }
-    throw error;
-  }
-}
-export async function pruneRetainedDesktopRuntimes(stateRoot, keepExecutable) {
-  const parent = path.resolve(stateRoot, 'linux-runtimes'), keep = path.dirname(path.resolve(keepExecutable));
-  if (path.dirname(keep) !== parent || !/^[a-f0-9]{64}$/.test(path.basename(keep)) || !fs.existsSync(parent)) 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 record = readRecord(path.join(directory, manifestName));
-    if (record?.owner !== owner || record.digest !== entry.name) continue;
-    if (fs.readdirSync(directory).sort().join('|') !== [...names, manifestName].sort().join('|')) continue;
-    const actual = await digestFiles(directory);
-    if (treeHash(actual) !== entry.name || JSON.stringify(record.files) !== JSON.stringify(actual)) continue;
-    for (const name of [...names, manifestName]) fs.unlinkSync(path.join(directory, name));
-    fs.rmdirSync(directory);
-  }
-}
+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-linux-runtime';
+const manifestName = '.code-relax-runtime.json';
+// Linux Desktop currently ships a flat, statically linked runtime, unlike Mac.
+const names = ['codex', 'codex-code-mode-host', 'rg'];
+export function runtimeFingerprint(executable) {
+  return JSON.stringify(names.map(name => {
+    const stat = fs.statSync(path.join(path.dirname(executable), name));
+    return [name, stat.size, stat.mtimeMs, stat.ctimeMs, stat.ino, stat.mode & 0o777];
+  }));
+}
+async function digestFiles(root) {
+  const files = [];
+  for (const name of names) {
+    const file = path.join(root, name), hash = createHash('sha256');
+    const before = fs.lstatSync(file);
+    if (!before.isFile()) throw new Error(`Linux 内核组件不是普通文件：${name}`);
+    for await (const chunk of fs.createReadStream(file)) hash.update(chunk);
+    const after = fs.statSync(file);
+    if (before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+      throw new Error('Linux 内核更新正在替换文件，请稍后重试。');
+    files.push({ name, size: after.size, mode: after.mode & 0o777, sha256: hash.digest('hex') });
+  }
+  return files;
+}
+const treeHash = files => createHash('sha256').update(JSON.stringify(files)).digest('hex');
+export async function retainRuntime(executable, stateRoot, version) {
+  const source = path.dirname(executable), sourceFingerprint = runtimeFingerprint(executable);
+  const files = await digestFiles(source), digest = treeHash(files);
+  if (sourceFingerprint !== runtimeFingerprint(executable)) throw new Error('Linux 内核在核对期间发生变化。');
+  const parent = path.join(stateRoot, 'linux-runtimes'), target = path.join(parent, digest);
+  const result = { executable: path.join(target, 'codex'), sourceExecutable: executable, sourceFingerprint };
+  if (fs.existsSync(target)) {
+    if (readRecord(path.join(target, manifestName))?.owner !== owner || treeHash(await digestFiles(target)) !== digest)
+      throw new Error('保留的 Linux 内核不完整，未覆盖运行中的文件。');
+    return result;
+  }
+  fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+  const staging = path.join(parent, `.${randomUUID()}.tmp`), created = [];
+  fs.mkdirSync(staging, { mode: 0o700 });
+  try {
+    for (const file of files) {
+      const destination = path.join(staging, file.name);
+      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);
+    }
+    if (treeHash(await digestFiles(staging)) !== digest || sourceFingerprint !== runtimeFingerprint(executable))
+      throw new Error('Linux 内核复制期间发生变化，未使用混合版本。');
+    writeRecord(path.join(staging, manifestName), { owner, digest, version, files });
+    created.push(manifestName);
+    fs.renameSync(staging, target);
+    return result;
+  } catch (error) {
+    if (fs.existsSync(staging)) { for (const name of created) fs.unlinkSync(path.join(staging, name)); fs.rmdirSync(staging); }
+    throw error;
+  }
+}
+export async function pruneRetainedDesktopRuntimes(stateRoot, keepExecutable) {
+  const parent = path.resolve(stateRoot, 'linux-runtimes'), keep = path.dirname(path.resolve(keepExecutable));
+  if (path.dirname(keep) !== parent || !/^[a-f0-9]{64}$/.test(path.basename(keep)) || !fs.existsSync(parent)) 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 record = readRecord(path.join(directory, manifestName));
+    if (record?.owner !== owner || record.digest !== entry.name) continue;
+    if (fs.readdirSync(directory).sort().join('|') !== [...names, manifestName].sort().join('|')) continue;
+    const actual = await digestFiles(directory);
+    if (treeHash(actual) !== entry.name || JSON.stringify(record.files) !== JSON.stringify(actual)) continue;
+    for (const name of [...names, manifestName]) fs.unlinkSync(path.join(directory, name));
+    fs.rmdirSync(directory);
+  }
+}

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

@@ -1,18 +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 };
-}
+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/README.md

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

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

@@ -100,10 +100,6 @@ export async function resolveCodexRuntime(stateRoot, { refresh = false, environm
   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];

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

@@ -1,11 +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);
-}
+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

@@ -1,8 +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());
-}
+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

@@ -1,8 +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: ['/'] };
-}
+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

@@ -1,84 +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 };
-}
+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 };
+}