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

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

@@ -1,149 +1,208 @@
-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(); }
-}
+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 内核保持运行。';
+export const desktopProjectRemovalWarning = '移除项目需要短暂关闭并重新打开 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 entry = previous || {
+    id: project.id, name: project.name, rootPaths,
+    createdAt: project.createdAt * 1000, updatedAt: project.updatedAt * 1000,
+  };
+  // Put the new project first in both the registry and
+  // its explicit display order, including a partial registration resumed later.
+  const result = { ...state, 'local-projects': { [project.id]: entry,
+    ...Object.fromEntries(Object.entries(projects).filter(([id]) => id !== project.id)) } };
+  result['project-order'] = [project.id, ...state['project-order'].filter(id => id !== project.id)];
+  return result;
+}
+
+export function updateProjectInState(state, project, codexDataRoot, previous) {
+  const scope = state['app-server-project-id-by-legacy-project-id-by-host']?.[`local:${codexDataRoot}`];
+  if (scope !== undefined && !object(scope)) fail('Codex Desktop 项目映射结构无效。');
+  const ids = new Set([project.id, ...Object.entries(scope || {}).filter(([, id]) => id === project.id).map(([id]) => id)]);
+  const projects = { ...state['local-projects'] };
+  const matches = (entry, value) => entry.name === value.name && Array.isArray(entry.rootPaths)
+    && entry.rootPaths.length === value.roots.length && entry.rootPaths.every((root, i) => key(root) === key(value.roots[i].path));
+  let found = false;
+  for (const id of ids) {
+    const entry = projects[id]; if (!entry) continue;
+    if (!matches(entry, previous) && !matches(entry, project)) fail('桌面项目已被其他操作修改，请刷新后重新编辑。');
+    projects[id] = { ...entry, name: project.name, rootPaths: project.roots.map(root => root.path), updatedAt: project.updatedAt * 1000 };
+    found = true;
+  }
+  return found ? { ...state, 'local-projects': projects } : registerProjectInState(state, project, codexDataRoot);
+}
+
+export function removeProjectFromState(state, project, codexDataRoot) {
+  const scopeKey = `local:${codexDataRoot}`;
+  const mappings = state['app-server-project-id-by-legacy-project-id-by-host'];
+  const scope = mappings?.[scopeKey];
+  if (scope !== undefined && !object(scope)) fail('Codex Desktop 项目映射结构无效，未修改桌面文件。');
+  const ids = new Set([project.id, ...Object.entries(scope || {}).filter(([, id]) => id === project.id).map(([id]) => id)]);
+  const result = { ...state, 'local-projects': { ...state['local-projects'] },
+    'project-order': state['project-order'].filter(id => !ids.has(id)) };
+  for (const id of ids) delete result['local-projects'][id];
+  if (state['pinned-project-ids'] !== undefined) {
+    if (!Array.isArray(state['pinned-project-ids'])) fail('Codex Desktop 项目置顶结构无效。');
+    result['pinned-project-ids'] = state['pinned-project-ids'].filter(id => !ids.has(id));
+  }
+  if (scope) result['app-server-project-id-by-legacy-project-id-by-host'] = { ...mappings,
+    [scopeKey]: Object.fromEntries(Object.entries(scope).filter(([id]) => !ids.has(id))) };
+  const assignments = state['thread-project-assignments'];
+  if (assignments !== undefined) {
+    if (!object(assignments) || state['projectless-thread-ids'] !== undefined && !Array.isArray(state['projectless-thread-ids'])) {
+      fail('Codex Desktop 对话项目归属结构无效。');
+    }
+    const remaining = { ...assignments }, projectless = new Set(state['projectless-thread-ids'] || []);
+    for (const [id, assignment] of Object.entries(assignments)) {
+      if (assignment?.projectKind !== 'local' || !ids.has(assignment.projectId)) continue;
+      delete remaining[id]; projectless.add(id);
+    }
+    result['thread-project-assignments'] = remaining;
+    result['projectless-thread-ids'] = [...projectless];
+  }
+  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 removing = options.operation === 'remove';
+  const updating = options.operation === 'update';
+  const warning = removing ? desktopProjectRemovalWarning : updating ? desktopProjectRestartWarning.replace('创建项目', '编辑项目') : desktopProjectRestartWarning;
+  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(warning, { desktopRestartRequired: true });
+    if (info.running && await host.sharedServiceUrl() !== serverUrl) {
+      fail('Codex Desktop 尚未接入当前工作站内核，请先完成 Desktop 接入后操作项目。');
+    }
+    const mutate = async (project, operation, saveOperation, removeNative) => {
+        const transform = updating ? (state, value, root) => updateProjectInState(state, value, root, operation.previousProject)
+          : removing ? removeProjectFromState : registerProjectInState;
+        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(warning, { 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 = transform(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 }); }
+          }
+          // Remove only after the desktop registry has been saved and while
+          // Desktop is closed. project/delete detaches members, never their files.
+          if (removing) await removeNative();
+          operation[removing ? 'desktopRemoved' : '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, `${removing ? '项目移除状态已记录' : '项目已保留'}，重新打开 Codex Desktop 未完成：${error.message}`].filter(Boolean).join(' '));
+          }
+        }
+        if (registrationError) throw registrationError;
+        const finalState = parseState(await fs.readFile(stateFile));
+        const verified = transform(finalState, project, codexDataRoot);
+        if (JSON.stringify(verified) !== JSON.stringify(finalState)) throw new Error('Desktop 项目状态未能在最终文件中核对，请检查后继续完成操作。');
+        return { status: removing ? 'removed' : updating ? 'updated' : 'registered', restarted: restartNeeded };
+    };
+    return await action({ register: mutate, remove: mutate });
+  } finally { await release(); }
+}

package/dist/src/platform/file-opener.mjs

@@ -0,0 +1,9 @@
+import { spawn } from 'node:child_process';
+
+export function openFile(file) {
+  const executable = { win32: 'explorer.exe', darwin: '/usr/bin/open', linux: 'xdg-open' }[process.platform];
+  if (!executable) throw new Error(`不支持此平台的文件打开操作：${process.platform}`);
+  const viewer = spawn(executable, [file], { detached: true, stdio: 'ignore', windowsHide: true });
+  viewer.once('error', error => console.error(`无法打开二维码：${error.message}`));
+  viewer.unref();
+}

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

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

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

@@ -0,0 +1,56 @@
+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 { verifyProtocol } from '../codex-protocol.mjs';
+import { readRecord, writeRecord } from '../../service-lifecycle.mjs';
+import { installedDesktop, verifyDesktopPackage } from './desktop-installation.mjs';
+import { retainRuntime, runtimeFingerprint } from './retained-runtime.mjs';
+export { runtimeFingerprint, pruneRetainedDesktopRuntimes } from './retained-runtime.mjs';
+
+const exec = promisify(execFile);
+export const codeModeHostPath = executable => path.join(path.dirname(executable), 'codex-code-mode-host');
+export function nativeExecutable(file, arch = process.arch) {
+  let descriptor;
+  try {
+    descriptor = fs.openSync(file, 'r');
+    const bytes = Buffer.alloc(20);
+    if (fs.readSync(descriptor, bytes, 0, 20, 0) !== 20) return false;
+    return bytes.subarray(0, 4).equals(Buffer.from([127, 69, 76, 70])) && bytes[4] === 2 && bytes[5] === 1
+      && bytes.readUInt16LE(18) === ({ x64: 62, arm64: 183 }[arch]);
+  } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
+}
+export function runtimeFilesAvailable(executable) {
+  return nativeExecutable(executable) && nativeExecutable(codeModeHostPath(executable))
+    && nativeExecutable(path.join(path.dirname(executable), 'rg'));
+}
+export function discoverCodex(environment = process.env) {
+  const desktop = installedDesktop(environment);
+  if (!desktop) return [];
+  const executable = path.join(desktop.desktop, 'resources/codex');
+  if (environment.CODE_RELAX_CODEX_PATH && path.resolve(environment.CODE_RELAX_CODEX_PATH) !== executable)
+    throw new Error('Linux 工作站需要官方 ChatGPT 桌面版内核，CODE_RELAX_CODEX_PATH 与桌面内核不一致。');
+  return nativeExecutable(executable) ? [{ executable, source: 'desktop', desktop: desktop.desktop }] : [];
+}
+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'), saved = readRecord(recordFile);
+  const codexHome = path.resolve(environment.CODEX_HOME?.trim() || saved?.codexHome || path.join(os.homedir(), '.codex'));
+  if (!refresh && saved?.source === 'desktop' && saved.executable && codexHome === saved.codexHome
+      && (!environment.CODE_RELAX_CODEX_PATH || environment.CODE_RELAX_CODEX_PATH === saved.sourceExecutable)
+      && runtimeFilesAvailable(saved.executable) && saved.fingerprint === runtimeFingerprint(saved.executable)) return saved;
+  const [candidate] = discoverCodex(environment);
+  if (!candidate) throw new Error('请先安装并登录官方 Linux ChatGPT 桌面版；独立 CLI 不能代替点点所需的桌面接入。');
+  verifyDesktopPackage(candidate.desktop);
+  if (!runtimeFilesAvailable(candidate.executable)) throw new Error('Linux 桌面内核缺少当前架构的配套组件。');
+  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('无法识别 Linux 桌面内核版本。');
+  const retained = await retainRuntime(candidate.executable, stateRoot, version);
+  await verifyProtocol(retained.executable, stateRoot);
+  const result = { ...candidate, ...retained, version, codexHome, fingerprint: runtimeFingerprint(retained.executable) };
+  writeRecord(recordFile, result);
+  return result;
+}

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

@@ -0,0 +1,28 @@
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { runtimePaths } from '../runtime-paths.mjs';
+
+export async function credentialStore(action, record, root = runtimePaths().credentialsRoot) {
+  if (!['load', 'save'].includes(action)) throw new Error('无效的凭据操作。');
+  if (action === 'save' && (!record || typeof record !== 'object' || Array.isArray(record))) throw new Error('无效的凭据记录。');
+  const account = createHash('sha256').update(path.resolve(root)).digest('hex');
+  const args = action === 'load' ? ['lookup'] : ['store', '--label=Code Relax'];
+  args.push('service', 'cn.walkhi.code-relax', 'account', account);
+  return new Promise((resolve, reject) => {
+    const child = execFile('secret-tool', args, { encoding: 'utf8', timeout: 60000, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) {
+        if (action === 'load' && error.code === 1 && !stderr.trim()) return resolve({ record: null });
+        return reject(new Error(error.code === 'ENOENT' ? '请安装 libsecret 的 secret-tool，并在已解锁钥匙环的 Linux 桌面会话中运行。'
+          : `Linux Secret Service 操作失败：${stderr.trim() || error.code}`));
+      }
+      try {
+        const value = action === 'load' ? JSON.parse(stdout) : record;
+        if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Linux 钥匙环中的凭据记录无效。');
+        resolve({ record: value });
+      } catch (error) { reject(error); }
+    });
+    child.stdin.on('error', error => { if (error.code !== 'EPIPE') reject(error); });
+    child.stdin.end(action === 'save' ? JSON.stringify(record) : undefined);
+  });
+}

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

@@ -0,0 +1,83 @@
+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, 'resources/linux-package-metadata.json'));
+    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 尚未正常退出，请在 Linux 上处理未保存内容后重试；未强制结束进程。');
+        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('内核已就绪，但 Linux 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) {
+  if (process.getuid() === 0) throw new Error('请以普通 Linux 桌面用户安装 Code Relax，不使用 sudo。');
+  assertPlainPath(stateRoot);
+  fs.mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
+  return fs.realpathSync(stateRoot);
+}
+export async function removeDesktopShortcut() { return { removed: false, reason: 'not-used-on-linux' }; }

package/dist/src/platform/linux/desktop-installation.mjs

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+// Official Linux 26.1007.71326 deb: /usr/bin/chatgpt -> codex-launcher,
+// ChatGPT and resources/{codex,codex-code-mode-host,rg} share this root.
+export function installedDesktop(environment = process.env) {
+  const roots = ['/usr/lib/chatgpt', '/opt/chatgpt', '/opt/ChatGPT'];
+  for (const directory of String(environment.PATH || '').split(':').filter(value => value.startsWith('/'))) {
+    try { roots.push(path.dirname(fs.realpathSync(path.join(directory, 'chatgpt')))); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  for (const root of new Set(roots)) {
+    const metadataFile = path.join(root, 'resources/linux-package-metadata.json');
+    if (!fs.existsSync(metadataFile)) continue;
+    const metadata = JSON.parse(fs.readFileSync(metadataFile, 'utf8'));
+    if (metadata.codexAppBrand !== 'chatgpt' || metadata.codexBuildFlavor !== 'prod' || !metadata.version) continue;
+    const executable = path.join(root, 'ChatGPT');
+    if (!fs.existsSync(executable)) continue;
+    return { desktop: fs.realpathSync(root), executable: fs.realpathSync(executable), version: metadata.version, build: metadata.version };
+  }
+  return null;
+}
+export function verifyDesktopPackage(root) {
+  const file = path.join(root, 'resources/codex');
+  // Trust the machine's installed package database; do not treat a JSON brand
+  // marker as an operating-system signature or accept an unrelated CLI shim.
+  if (fs.existsSync('/usr/bin/dpkg-query')) {
+    const owner = execFileSync('/usr/bin/dpkg-query', ['-S', file], { encoding: 'utf8' }).trim();
+    if (!owner.split('\n').some(line => line === `chatgpt: ${file}`)) throw new Error('内核不属于已安装的官方 chatgpt 软件包。');
+  } else if (fs.existsSync('/usr/bin/rpm')) {
+    if (execFileSync('/usr/bin/rpm', ['-qf', '--qf', '%{NAME}', file], { encoding: 'utf8' }).trim() !== 'chatgpt') throw new Error('内核软件包身份不匹配。');
+  } else if (fs.existsSync('/usr/bin/pacman')) {
+    if (!/^chatgpt(?:-bin)?$/.test(execFileSync('/usr/bin/pacman', ['-Qoq', file], { encoding: 'utf8' }).trim())) throw new Error('内核软件包身份不匹配。');
+  } else throw new Error('无法核对 Linux 桌面版软件包，请通过官方软件包安装 ChatGPT。');
+}

package/dist/src/platform/linux/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 Linux 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);
+}