cabletidy 0.1.0 → 0.2.0

package/README.md

@@ -31,7 +31,9 @@ Codex 的可选模型设置目前只支持与本机官方 GPT 目录明确对应
 
 ## 安装与运行
 
-推荐 Node.js 24，也支持 Node.js 22.13 及以上的 22.x 版本；完整版本约束见 `package.json`。目前验证平台为 Linux，macOS 和 Windows 尚待验证。
+推荐 Node.js 24，也支持 Node.js 22.13 及以上的 22.x 版本；完整版本约束见 `package.json`。CI 在 Linux、macOS 和 Windows 上执行源码测试与安装冒烟测试，平台验证结果以对应提交的 CI 为准。Windows 使用系统自带的 Windows PowerShell 查询进程身份；Codex 模型目录查询还需要允许 PowerShell `Add-Type` 调用 Windows Job Object API。
+
+`0.2.0` 的变更与升级注意事项见 [发布说明](https://github.com/ZY-WANG-0304/cabletidy/blob/main/docs/releases/0.2.0.md)。
 
 ### 从 npm 官方源安装
 
@@ -52,7 +54,7 @@ npm exec --yes --registry=https://registry.npmjs.org/ --package=cabletidy -- cab
 拿到 `.tgz` 安装包后，无需 clone 仓库即可安装：
 
 ```bash
-npm install -g /absolute/path/cabletidy-0.1.0.tgz
+npm install -g /absolute/path/cabletidy-0.2.0.tgz
 cabletidy --version
 cabletidy start
 ```
@@ -60,7 +62,7 @@ cabletidy start
 也可以不做全局安装，直接运行同一个安装包：
 
 ```bash
-npm exec --yes --package=/absolute/path/cabletidy-0.1.0.tgz -- cabletidy start
+npm exec --yes --package=/absolute/path/cabletidy-0.2.0.tgz -- cabletidy start
 ```
 
 安装包仍依赖本机 Node.js；npm 会下载尚未缓存的运行时依赖，因此 `.tgz` 本身不代表完全离线安装。安装过程不会启动服务或修改客户端配置。
@@ -77,6 +79,7 @@ cabletidy status
 ```
 
 `status` 同时显示 daemon 是否在线、管理台 URL、配置版本和当前配置套装列表；每套配置包含 ID、名称、目标 CLI、本地接入 URL 和启用状态，不再需要单独的 URL 或 Web 状态命令。
+`status` 和不带参数的命令只读取状态，不创建数据目录、配置、密钥或备份。尚未初始化时，只提示未启动以及运行 `cabletidy start`，不返回预设的管理台地址。
 
 升级时先停止服务，再安装最新版本并重新启动：
 
@@ -93,7 +96,7 @@ cabletidy start
 npm ci
 npm start
 
-# 生成可安装的 cabletidy-0.1.0.tgz。
+# 生成可安装的 cabletidy-0.2.0.tgz。
 npm pack
 ```
 
@@ -106,7 +109,7 @@ npm test
 npm run test:package
 ```
 
-安装冒烟测试会在临时目录打包、安装、启动和卸载，验证安装后的 CLI、Web 资源及用户数据保留；需要能够获取 npm 依赖。Linux 上还验证 SIGINT / SIGTERM 和端口冲突。分发方案的取舍、维护者发布流程与后续服务管理设计见 [安装与分发决策](https://github.com/ZY-WANG-0304/cabletidy/blob/main/docs/installation-research.md)。
+安装冒烟测试会在临时目录打包、安装、启动和卸载，验证安装后的 CLI、Web 资源、重复启动、重启地址及用户数据保留；需要能够获取 npm 依赖。Linux / macOS 验证 SIGINT / SIGTERM；Windows 直接执行 npm 的 `.cmd` 入口，验证强制终止后的旧锁恢复。Windows 的退出处理逻辑通过测试 IPC 触发验证，真实终端 Ctrl+C 的事件投递仍需交互验收。分发方案的取舍、维护者发布流程与后续服务管理设计见 [安装与分发决策](https://github.com/ZY-WANG-0304/cabletidy/blob/main/docs/installation-research.md)。
 
 使用 Codex 可选模型设置时，本机需要可执行支持 `debug models --bundled` 的 Codex CLI，daemon 的 `PATH` 必须包含它。目录读取失败不会阻止纯透传配置的创建、代理启动、预览或应用，但会阻止新增模型设置或应用包含模型设置的 Codex 接入；管理台可在更新 Codex 后刷新模型列表。已在 Codex 0.154.0 验证目录加载和实际请求。
 
@@ -120,15 +123,27 @@ CABLETIDY_HOME="$PWD/.cabletidy-dev" cabletidy start
 
 源码运行时，将命令末尾的 `cabletidy start` 换成 `npm start`。
 
-Web 管理台与所有 Virtual Provider 共用 `127.0.0.1:43100`。每份配置通过 `/<配置ID>/v1/...` 接入，例如 `http://127.0.0.1:43100/codex-main/v1/responses`；管理接口仍使用 `/api/v1/...`。
+首次执行 `start` 且数据目录中没有 `config.json` 时，先尝试监听 `127.0.0.1:43100`；若端口已被占用，则直接由操作系统分配空闲端口。监听成功后将实际端口保存到 `config.json` 的 `web.port`，后续启动复用该端口。多人共用服务器时，各用户的数据目录独立，首次启动会自动避开已占用端口。
+
+已有配置中的端口（包括手动指定的端口）被占用时，启动会明确报错，不会自动更换。可以停止占用端口的服务，或修改 `web.port` 后重启，并重新应用客户端配置。实际地址以启动输出或 `cabletidy status` 为准。
+
+同一份数据目录只允许运行一个实例，启动和退出清理期间均持有 `daemon.lock`。锁记录主机名、持有者 PID 和进程启动标识：Linux 使用系统启动 ID 与进程启动时钟，macOS 使用 `ps` 的启动时间，Windows 使用 PowerShell 的 `StartTime`。正常退出或启动失败后释放；只有能识别锁的代次、确认原进程已退出或 PID 已被复用，且锁至少 10 秒未更新时才自动回收。被暂停的实例仍然持有锁，恢复后不会因锁被误回收而崩溃。
+
+旧版本的空锁目录、缺少启动标识的存活 PID、进程查询不可用或来自另一主机的锁，可能无法确认归属。此时启动返回 `ELOCKUNKNOWN` 并列出锁目录路径；继续等待不会补全缺失信息。请检查并停止使用该数据目录的 CableTidy，确认没有运行中或暂停中的实例后，手动删除提示的 `daemon.lock` 目录并重新启动，保留 `config.json` 和 `secrets.json`。不要仅凭 `status` 离线就删除锁，暂停中的实例也可能无法响应探测。
+
+Web 管理台与所有 Virtual Provider 共用最终分配的端口。以下示例假设端口为 `43100`；每份配置通过 `/<配置ID>/v1/...` 接入，例如 `http://127.0.0.1:43100/codex-main/v1/responses`；管理接口仍使用 `/api/v1/...`。
 
 ## Web 配置管理
 
 管理台直接显示配置列表，首次使用与后续使用采用相同的操作流程，不设置介绍页或配置向导。点击“新建配置”填写：
 
-- 配置名称（可选）；留空时按 `Codex / <上游主机名>` 自动生成展示名称。
+- 目标 CLI：Codex 或 Claude Code。
+- 配置名称（可选）；留空时按 `<CLI 名称> / <上游主机名>` 自动生成展示名称。
 - 上游地址和 API Key。
-- 模型设置（可选）：需要改名时选择 Codex 官方模型并填写上游真实模型名；默认无需添加。
+- Claude Code 上游可选 `x-api-key` 或 `Authorization: Bearer` 认证。
+- 模型设置（可选）：Codex 选择官方模型，Claude Code 填写客户端请求中的完整模型 ID；上游模型 ID 留空时直接透传。
+- Claude Code 的“模型别名”（可选）：Opus / Sonnet / Fable / Haiku 从本次填写的客户端模型 ID 中选择，也可由 Claude 默认决定。
+- Claude Code 的“默认模型”（可选）：启动模型和子代理模型均以下拉选项选择。启动模型支持 Claude 官方的 `best`、`opus`、`sonnet`、`fable`、`haiku`、`opusplan`；子代理模型支持 `opus`、`sonnet`、`fable`、`haiku`。两者都可选择对应的默认行为，或当前配置中的客户端模型 ID；保存别名本身，不提前转换为具体模型 ID。
 
 点击“创建配置”后，服务端自动校验、保存并使配置生效，成功后进入详情页。本地服务入口和路由自动生成。配置 ID 按配置名称规范化生成，Virtual Provider ID 为 `cabletidy_<配置ID>`，并直接用作 Codex 的 `model_provider`；URL 路径使用不带此前缀的配置 ID。留空名称时，自动生成的名称也会参与 ID 规范化；如果多个配置使用同一上游主机且都留空名称，需要为后续配置填写不同名称。
 
@@ -136,7 +151,7 @@ Web 管理台与所有 Virtual Provider 共用 `127.0.0.1:43100`。每份配置
 
 仅在存在实际未保存修改时，切换页面、返回列表或关闭页面会提示确认；改回原值后不再拦截。点击“刷新模型列表”同步更新沿用官方定义的元数据和最新限制，保留手动覆盖值与其他表单输入。
 
-“应用到 Codex”保持独立，只有主动点击时才修改 Codex 配置文件。测试连通性和配置预览使用已保存的配置。
+“应用到 Codex”和“应用到 Claude Code”保持独立，只有主动点击时才修改客户端配置文件。测试连通性和配置预览使用已保存的配置。
 
 按需在 Codex 套装详情页中添加模型设置；仅覆盖上下文时无需填写上游模型 ID。模型能力与上下文默认折叠，元数据默认“沿用官方定义”；
 展开并选择“覆盖上游限制”后可设置 context window 和图片输入，已有覆盖值或待确认的旧策略会自动展开。不提供固定 reasoning effort 或未实现的 compact 控件。
@@ -212,9 +227,78 @@ curl http://127.0.0.1:43100/codex-main/v1/models
 Claude Code 适配器会自动注入固定的 `cabletidy-local` 占位值以满足客户端认证检查，
 它不是密钥，本地服务不会校验这个值。Generic CLI 只生成本地地址和模型环境变量。
 
+## Claude Code 接入
+
+新建配置时选择 Claude Code，填写 Anthropic Messages 兼容上游地址、认证方式和凭据。Anthropic 官方 API 和提供同协议的中转服务使用同一接入流程，每份配置仍只连接一个上游。
+
+默认透传客户端模型名，无需登记模型。按需添加“客户端完整模型 ID → 上游模型 ID”映射；仅改名不会限制工具、图片、thinking 等能力，具体能力由客户端和上游决定。已有配置中的显式能力限制仍然生效。Claude Code 的 `sonnet`、`opus` 等别名会在客户端解析，映射应填写实际发到 API 的完整模型 ID。
+
+模型映射只提供“客户端模型 ID”和“上游模型 ID”。客户端输入框支持搜索官方建议，也可直接填写自定义 ID；上游 ID 手动填写，留空时原样透传。建议目录内置于 `web/claude-models.js`，根据 [Anthropic 模型文档](https://platform.claude.com/docs/en/about-claude/models/overview) 整理，记录核对日期和来源，随 CableTidy 发版更新，无需额外 API Key。目录只辅助输入，不限制保存或请求中的模型名，也不会自动加入 `/v1/models`。
+
+“Claude Code 模型选择”分为“模型别名”和“默认模型”：前者包含 Opus/Sonnet/Fable/Haiku 的别名指向，后者包含下拉选择的启动模型和子代理模型。启动模型和子代理模型的下拉都提供默认行为、对应的官方别名和当前配置客户端模型 ID；创建页使用本次填写的模型映射，详情页使用已保存的模型映射，不使用上游模型 ID 或其他配置的模型。模型发现开关保留在表单底部，不单独分组。四个家族别名分别生成官方的 `ANTHROPIC_DEFAULT_<家族>_MODEL` 变量，Fable 使用 `ANTHROPIC_DEFAULT_FABLE_MODEL`。模型改名时同步更新引用它的家族别名、启动模型和子代理模型；删除映射时，引用该客户端 ID 的选择回到默认。启动模型或子代理模型选择的官方别名始终保留原文，由 Claude 解析，即使与内部模型 ID 同名也不会提前展开。保存后需要重新应用客户端配置。已不在候选列表中的旧默认值会在下一次正常保存时清空，页面不会自动写回配置。
+
+选择默认行为时 CableTidy 不指定该字段对应的模型；再次应用会恢复此前接管的对应环境变量原值，由 Claude 自身配置决定。选择启动模型通过 `ANTHROPIC_MODEL` 设置，选择子代理模型通过 `CLAUDE_CODE_SUBAGENT_MODEL` 设置，后续每次启动都会生效。上下文、reasoning effort 和压缩策略仍由 Claude Code 管理，不生成没有实际效果的逐模型窗口或 compact 设置。
+
+启动模型下拉不提供 `[1m]` 选项。`[1m]` 是 Claude Code 自身的上下文模式控制，Claude Code 会在发送上游请求前移除该后缀；CableTidy 无法通过 `/v1/models` 判断或保证上游支持 1M，也没有专门的 1M 能力验证，因此不在界面中暴露此配置。
+
+### 预览、应用与撤销
+
+点击“预览配置”不会写入文件。预览仅展示 CableTidy 生成的字段、目标路径和冲突提示，不回显原客户端文件中的凭据。“应用到 Claude Code”增量合并用户配置的 `env`：默认位置为 `~/.claude/settings.json`，Windows 为 `%USERPROFILE%\.claude\settings.json`；设置了 `CLAUDE_CONFIG_DIR` 时使用该目录。
+
+接入的核心配置如下，Base URL 不额外带 `/v1`：
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:43100/claude-main",
+    "ANTHROPIC_AUTH_TOKEN": "cabletidy-local"
+  }
+}
+```
+
+生成的完整配置还会将用户环境中的旧 API Key、OAuth Token、自定义请求头置空，并将云厂商接入开关设为 `0`，使该配置使用 Messages 本地入口。原值会保留供撤销使用。权限、Hooks、MCP、根级 `model` 和其他用户设置保持不变；项目配置、`--settings` 或企业 managed settings 仍可能覆盖用户配置。应用后重新启动 Claude Code，用 `/status` 核对 Base URL 和认证来源。
+
+用户只填写上游凭据。本地不生成、保存或校验 Key；`cabletidy-local` 是公开占位值，仅满足 Claude 客户端认证检查，不会转发给上游。直接调用四个本地接口可以完全不带认证头。真实上游认证始终来自 CableTidy 的 secrets store。
+
+应用前会在 CableTidy 的 `backups` 目录备份原文件，在 Claude 配置目录的 `.cabletidy-settings.json` 中记录接管字段及原值，文件权限为 `0600`。切换到另一份 Claude 配置后，撤销仍恢复最初接入前的值。点击当前已应用配置的“撤销接入”恢复这些字段，保留应用后新增的无关设置；不会停止本地服务。
+
+如果接管字段已被手工修改，预览列出冲突字段，应用和撤销均停止写入，不覆盖修改，也不显示冲突字段的秘密值。请先核对备份并保留自己的修改后处理冲突。无效 JSON、非普通文件和符号链接文件不会被替换。已有 `claude.env.v1` 配置继续兼容，新配置使用 `claude.settings.json.v1`。
+
+管理台仅展示实际应用到 `settings.json` 的 JSON 片段，包含将合并的 `env` 字段，并显示目标路径、变更字段和冲突提示。点击“应用到 Claude Code”后仍显示同一种内容，不展示独立文件、Shell 命令或 PowerShell 等其他接入方式。
+
+### 本地接口
+
+所有路径均相对于 `ANTHROPIC_BASE_URL`，共享配置的启停状态：
+
+| 方法 | 路径 | 行为 |
+| --- | --- | --- |
+| POST | `/v1/messages` | 普通及 SSE 推理；保留查询参数、协议扩展字段和 `anthropic-*` 请求头 |
+| POST | `/v1/messages/count_tokens` | 使用相同上游和模型映射，返回上游计数；不要求 `max_tokens`，上游不支持时保留其错误 |
+| GET | `/v1/models` | 只返回当前配置显式设置的客户端模型，协议字段 `display_name` 使用客户端 ID；支持 `limit=1..1000` 和 `after_id` |
+| HEAD | `/api/hello` | 本地返回 204、不请求上游，仅确认本地入口可达 |
+
+`/messages` 保留为旧版兼容路径。标准接口应使用 `/v1/messages`。SSE 保留 ping、工具参数增量和流内错误，客户端断开时取消上游请求；模型改名只修改 Messages 响应及 `message_start` 的模型字段，不改工具数据。上游错误保留原状态码和响应体，重试、请求 ID 和 Anthropic 限流头随响应转发。
+
+模型发现需在客户端开启 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`，可通过管理台复选框生成。纯透传配置返回空列表，不影响其他模型请求；模型列表不是白名单，也不自动发现上游模型。Claude 会按自身版本过滤发现条目，不含 `claude` 或 `anthropic` 的别名可能不显示。Token counting 为官方可选接口，上游不支持时 Claude 可退回上下文估算。
+
+“测试连通性”与 Codex 使用相同逻辑：使用已保存的连接向上游 Base URL 发起 GET 请求，检查 HTTP 可达性并展示耗时，不发起模型推理，也不判断认证、模型或流式推理是否可用。
+
+### 验证与范围
+
+`npm test` 包含模拟上游的协议、免认证入口、配置合并、恢复、冲突与管理台测试。安装本机 Claude Code 后可执行原生 CLI 冒烟测试，它使用临时配置目录和本地模拟上游，不调用真实模型，也不修改日常 Claude 配置：
+
+```bash
+npm run test:claude
+
+# 多个安装版本共存时，可指定要验证的可执行文件。
+CABLETIDY_CLAUDE_BIN=/absolute/path/claude npm run test:claude
+```
+
+首版仅支持 Anthropic Messages 兼容上游。HTTP/HTTPS 企业网络代理、动态上游凭据、Bedrock/Vertex 原生协议转换和内置 `claude gateway` 托管不在本版范围。模型网关不代表 npm、Git、MCP 子进程或 Claude 其他联网流量也经过 CableTidy。
+
 ## 其他 CLI
 
-Claude Code 使用 Anthropic Messages Virtual Provider，目标配置通过管理台预览。未来的 Gemini CLI、OpenCode 和其他编程 CLI 可以增加各自的 Target Adapter；它们不需要被强行改成 OpenAI 配置。
+未来的 Gemini CLI、OpenCode 和其他编程 CLI 可以增加各自的 Target Adapter；它们不需要被强行改成 OpenAI 配置。
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabletidy",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A local multi-target coding CLI gateway and provider manager.",
   "license": "MIT",
   "repository": {
@@ -32,9 +32,14 @@
     "dev": "node --watch src/server.mjs",
     "test": "node --test test/*.test.mjs",
     "test:package": "node --test scripts/package-smoke.mjs",
+    "test:claude": "node --test scripts/claude-smoke.mjs",
     "prepublishOnly": "npm test && npm run test:package"
   },
   "dependencies": {
+    "proper-lockfile": "^4.1.2",
     "toml-eslint-parser": "^1.0.3"
+  },
+  "devDependencies": {
+    "cross-spawn": "^7.0.6"
   }
 }

package/src/claude-config-file.mjs

@@ -0,0 +1,172 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import lockfile from "proper-lockfile";
+import { backupFile, writeJsonAtomic } from "./config.mjs";
+
+const STATE_FILE = ".cabletidy-settings.json";
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const digest = (value) => crypto.createHash("sha256").update(value ?? "<absent>").digest("hex");
+const snapshot = (env, key) => Object.hasOwn(env, key) ? { present: true, value: env[key] } : { present: false };
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+
+function parseSettings(text, file) {
+  try { return JSON.parse(text); }
+  catch { throw new Error(`Invalid JSON in ${file}; the file was left unchanged.`); }
+}
+
+export function claudeConfigHome(options = {}) {
+  return path.resolve(options.claudeHome || process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude"));
+}
+
+async function readOptional(file) {
+  try {
+    const stat = await fs.lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Expected a regular file: ${file}`);
+    return await fs.readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function readState(home) {
+  const file = path.join(home, "settings.json");
+  const text = await readOptional(file);
+  const settings = text === null ? {} : parseSettings(text, file);
+  if (!record(settings) || (settings.env !== undefined && !record(settings.env))) {
+    throw new Error(`Invalid Claude settings object: ${file}`);
+  }
+  const stateText = await readOptional(path.join(home, STATE_FILE));
+  let state = stateText === null ? null : parseSettings(stateText, path.join(home, STATE_FILE));
+  if (state?.pending) {
+    // Recover either side of an interrupted atomic settings replacement.
+    if (digest(text) === state.pending.before) state = state.pending.previous;
+    else if (digest(text) === state.pending.after) delete state.pending;
+    else throw new Error("Claude settings changed during an interrupted apply; restore from backup before retrying.");
+  }
+  if (state !== null && (state.version !== 1 || !record(state.fields) || typeof state.bindingId !== "string")) {
+    throw new Error(`Invalid CableTidy ownership record: ${path.join(home, STATE_FILE)}`);
+  }
+  for (const [key, field] of Object.entries(state?.fields || {})) {
+    if (!key.startsWith("ANTHROPIC_") && !key.startsWith("CLAUDE_CODE_")) throw new Error("Invalid managed environment key");
+    if (!record(field) || !record(field.before) || typeof field.applied !== "string") throw new Error("Invalid managed environment record");
+  }
+  return { file, text, settings, state, stateText };
+}
+
+function plan(snapshotData, vars, bindingId) {
+  const { settings, state } = snapshotData;
+  const next = structuredClone(settings);
+  const env = next.env || {};
+  const fields = {};
+  const conflicts = [];
+  const changed = [];
+  for (const [key, field] of Object.entries(state?.fields || {})) {
+    if (!same(snapshot(env, key), { present: true, value: field.applied })) conflicts.push(`env.${key}`);
+  }
+  for (const key of new Set([...Object.keys(state?.fields || {}), ...Object.keys(vars)])) {
+    const current = snapshot(env, key);
+    const old = state?.fields[key];
+    if (Object.hasOwn(vars, key)) {
+      fields[key] = { before: old?.before || current, applied: vars[key] };
+      env[key] = vars[key];
+    } else if (old.before.present) env[key] = old.before.value;
+    else delete env[key];
+    if (!same(current, snapshot(env, key))) changed.push(`env.${key}`);
+  }
+  if (Object.keys(env).length || (state?.hadEnv ?? Object.hasOwn(settings, "env"))) next.env = env;
+  else delete next.env;
+  return {
+    next, conflicts, changed,
+    state: {
+      version: 1, bindingId, fields,
+      hadEnv: state?.hadEnv ?? Object.hasOwn(settings, "env"),
+    },
+  };
+}
+
+function diagnostics(settings, vars) {
+  const warnings = [];
+  const env = settings.env || {};
+  for (const key of Object.keys(vars)) {
+    if (Object.hasOwn(env, key) && env[key] !== vars[key]) warnings.push(`Will replace env.${key}; its original value is retained for restore.`);
+  }
+  if (settings.apiKeyHelper) warnings.push("An existing apiKeyHelper is preserved. Verify the active credential source with /status.");
+  if (settings.forceLoginMethod) warnings.push("An existing forceLoginMethod may require a different login method.");
+  warnings.push("Project settings, --settings and managed policies can override user settings. Restart Claude Code and check /status after applying.");
+  return warnings;
+}
+
+export async function prepareClaudeSettings(artifacts, options = {}) {
+  const home = claudeConfigHome(options);
+  const current = await readState(home);
+  const staged = plan(current, artifacts.environment.vars, artifacts.bindingId);
+  return {
+    ...artifacts,
+    settingsPath: current.file,
+    changes: staged.changed,
+    canApply: staged.conflicts.length === 0,
+    canRestore: current.state?.bindingId === artifacts.bindingId,
+    conflicts: staged.conflicts,
+    warnings: [...(artifacts.warnings || []), ...diagnostics(current.settings, artifacts.environment.vars)],
+  };
+}
+
+async function withSettingsLock(options, operation) {
+  const home = claudeConfigHome(options);
+  await fs.mkdir(home, { recursive: true, mode: 0o700 });
+  const release = await lockfile.lock(home, { realpath: true, retries: { retries: 20, minTimeout: 25, maxTimeout: 100 } });
+  try { return await operation(home); }
+  finally { await release(); }
+}
+
+async function commit(home, current, staged, options, restoring) {
+  if (staged.conflicts.length) {
+    throw new Error(`Claude settings were edited after applying CableTidy: ${staged.conflicts.join(", ")}. Preserve your edits before retrying.`);
+  }
+  const backups = options.paths?.backups || path.join(os.homedir(), ".cabletidy", "backups");
+  await fs.mkdir(backups, { recursive: true, mode: 0o700 });
+  const stateFile = path.join(home, STATE_FILE);
+  const backup = await backupFile(current.file, backups, "claude-settings.json");
+  await backupFile(stateFile, backups, "claude-settings-state.json");
+  if (await readOptional(current.file) !== current.text || await readOptional(stateFile) !== current.stateText) {
+    throw new Error("Claude settings changed during apply; preview and retry.");
+  }
+  const contents = `${JSON.stringify(staged.next, null, 2)}\n`;
+  await writeJsonAtomic(stateFile, {
+    ...staged.state,
+    pending: { before: digest(current.text), after: digest(contents), previous: current.state },
+  });
+  try {
+    if (await readOptional(current.file) !== current.text) throw new Error("Claude settings changed during apply; preview and retry.");
+    await writeJsonAtomic(current.file, staged.next);
+  } catch (error) {
+    if (current.stateText !== null) await writeJsonAtomic(stateFile, JSON.parse(current.stateText));
+    else await fs.unlink(stateFile);
+    throw error;
+  }
+  // A pending record remains recoverable if finalizing the ledger fails.
+  if (restoring) await fs.unlink(stateFile);
+  else await writeJsonAtomic(stateFile, staged.state);
+  return { applied: [current.file], backup, changes: staged.changed, mode: restoring ? "restored" : "managed_proxy" };
+}
+
+export function applyClaudeSettings(artifacts, options = {}) {
+  return withSettingsLock(options, async (home) => {
+    const current = await readState(home);
+    const staged = plan(current, artifacts.environment.vars, artifacts.bindingId);
+    const result = await commit(home, current, staged, options, false);
+    return { ...result, environment: artifacts.environment, warnings: diagnostics(current.settings, artifacts.environment.vars) };
+  });
+}
+
+export function restoreClaudeSettings(bindingId, options = {}) {
+  return withSettingsLock(options, async (home) => {
+    const current = await readState(home);
+    if (!current.state) throw new Error("No Claude settings are managed by CableTidy.");
+    if (current.state.bindingId !== bindingId) throw new Error(`Claude Code currently uses another CableTidy configuration: ${current.state.bindingId}`);
+    return commit(home, current, plan(current, {}, bindingId), options, true);
+  });
+}

package/src/cli.mjs

@@ -31,7 +31,12 @@ async function main() {
   const paths = getPaths();
 
   if (command === "status") {
-    const [config, runtime] = await Promise.all([loadConfig(paths), readRuntimeInfo(paths)]);
+    const config = await loadConfig(paths);
+    if (!config) {
+      print({ runtime: { status: "offline", liveness: "尚未启动，未找到配置；请执行 cabletidy start" } });
+      return;
+    }
+    const runtime = await readRuntimeInfo(paths);
     const daemon = runtime ? await probeDaemon(runtime) : { online: false, reason: "runtime.json 不存在" };
     const web = runtime?.web || {
       host: config.web.listenHost,

package/src/codex-catalog.mjs

@@ -1,4 +1,6 @@
 import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { powershell } from "./process-identity.mjs";
 import { clientModelIdForProfile, effectiveCapabilities } from "./model-resolver.mjs";
 
 let cached;
@@ -7,11 +9,16 @@ let activeCommand;
 
 async function executeCodex(args) {
   const timeout = AbortSignal.timeout(15_000);
-  const command = spawn("codex", args, {
+  const windows = process.platform === "win32";
+  const command = spawn(windows ? powershell : "codex", windows ? [
+    "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File",
+    fileURLToPath(new URL("./windows-codex.ps1", import.meta.url)),
+    args[0] === "--version" ? "version" : "models", String(process.pid),
+  ] : args, {
     windowsHide: true,
     stdio: ["ignore", "pipe", "pipe"],
-    // Keep npm launcher descendants in a group we can stop on forced daemon exit.
-    detached: process.platform !== "win32",
+    // Windows ignores console Ctrl+C inside the supervisor; POSIX uses a group.
+    detached: !windows,
   });
   activeCommand = command;
   const closed = new Promise(resolve => {
@@ -21,7 +28,8 @@ async function executeCodex(args) {
   const completed = new Promise((resolve, reject) => {
     command.once("error", reject);
     command.once("exit", (code, signal) => {
-      if (code !== 0) reject(new Error(`codex exited with ${signal || code}`));
+      if (code !== 0) reject(Object.assign(new Error(`codex exited with ${signal || code}`),
+        windows && code === 127 ? { code: "ENOENT" } : {}));
     });
     // Descendants may hold the pipes open after the launcher has exited.
     onTimeout = () => reject(timeout.reason);
@@ -56,6 +64,7 @@ async function readCommandOutput(stream) {
 export function forceStopCodexCatalog() {
   if (!activeCommand?.pid) return;
   try {
+    // Terminating the Windows supervisor closes its Job Object and its entire tree.
     if (process.platform === "win32") activeCommand.kill("SIGKILL");
     else process.kill(-activeCommand.pid, "SIGKILL");
   } catch (error) {

package/src/config.mjs

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
 import os from "node:os";
 import path from "node:path";
 import { normalizeConfigurationIdentities } from "../web/config-identity.js";
@@ -27,6 +28,7 @@ export function getPaths(home = DEFAULT_HOME) {
     config: path.join(home, "config.json"),
     secrets: path.join(home, "secrets.json"),
     runtime: path.join(home, "runtime.json"),
+    lock: path.join(home, "daemon.lock"),
     backups: path.join(home, "backups"),
   };
 }
@@ -37,7 +39,6 @@ export function defaultConfig() {
     revision: 0,
     daemon: {},
     web: {
-      enabled: true,
       listenHost: "127.0.0.1",
       port: 43100,
     },
@@ -76,7 +77,7 @@ export function normalizeConfig(input = {}) {
   // lifetime settings are no longer part of the effective configuration.
   delete config.web.sessionTtlSeconds;
   if (isRecord(config.daemon)) delete config.daemon.proxyPortRange;
-  migratePrototypeCodexFields(config);
+  discardObsoleteCodexFields(config);
   for (const provider of Object.values(config.virtualProviders)) {
     if (isRecord(provider)) {
       delete provider.localAuth;
@@ -92,18 +93,13 @@ export function normalizeConfig(input = {}) {
   return config;
 }
 
-function migratePrototypeCodexFields(config) {
-  // Read legacy prototype keys once, translate useful values, and discard
-  // profile-file metadata before the config reaches runtime or disk.
+function discardObsoleteCodexFields(config) {
   for (const upstream of Object.values(config.upstreams)) {
     if (!isRecord(upstream)) continue;
     // These policy placeholders never affected runtime behavior.
     for (const field of ["requestMaxRetries", "streamMaxRetries", "streamIdleTimeoutMs", "requiresOpenaiAuth", "supportsWebsockets"]) {
       delete upstream[field];
     }
-    if (!upstream.integration && upstream.providerFormat === "codex.toml.v1") {
-      upstream.integration = "codex-native-provider";
-    }
     delete upstream.envKey;
     delete upstream.codexNative;
     delete upstream.providerFormat;
@@ -112,30 +108,7 @@ function migratePrototypeCodexFields(config) {
 
   for (const model of Object.values(config.models)) {
     if (!isRecord(model)) continue;
-    const legacy = isRecord(model.targetOverrides?.codex)
-      ? model.targetOverrides.codex
-      : isRecord(model.legacyCodex)
-        ? model.legacyCodex
-        : null;
-    if (isRecord(legacy)) {
-      if (model.clientModelId === undefined && legacy.model) {
-        model.clientModelId = legacy.model;
-      }
-      if (model.contextWindow === undefined && legacy.modelContextWindow !== undefined) {
-        model.contextWindow = legacy.modelContextWindow;
-      }
-      if (model.compact === undefined && legacy.modelAutoCompactTokenLimit !== undefined) {
-        model.compact = {
-          strategy: "auto",
-          tokenLimit: legacy.modelAutoCompactTokenLimit,
-        };
-      }
-      if (model.personality === undefined && legacy.personality) {
-        model.personality = legacy.personality;
-      }
-    }
-    // Profile IDs, profile file paths, and other target-only fields belonged
-    // to the old prototype. They are migration input, not CableTidy state.
+    // Prototype metadata is discarded, never promoted into current fields.
     delete model.legacyCodex;
     if (isRecord(model.targetOverrides)) {
       delete model.targetOverrides.codex;
@@ -147,12 +120,6 @@ function migratePrototypeCodexFields(config) {
 
   for (const binding of Object.values(config.bindings)) {
     if (!isRecord(binding)) continue;
-    if (!binding.integration && binding.providerFormat === "codex.toml.v1") {
-      binding.integration = "codex-native-provider";
-    }
-    if (binding.targetFormat === "codex.toml.v1") {
-      binding.targetFormat = "codex.config.toml.v1";
-    }
     delete binding.providerFormat;
     if (isRecord(binding.codex)) {
       for (const key of ["profileFiles", "sourceUpstream", "sourceProviderId"]) {
@@ -165,7 +132,7 @@ function migratePrototypeCodexFields(config) {
 }
 
 export function publicConfig(config) {
-  const copy = structuredClone(normalizeConfig(config));
+  const copy = normalizeConfig(config);
   redactSecretFields(copy);
   return copy;
 }
@@ -179,38 +146,50 @@ export function stripSecretFields(value) {
 export async function ensureStore(paths = getPaths()) {
   await fs.mkdir(paths.home, { recursive: true, mode: 0o700 });
   await fs.mkdir(paths.backups, { recursive: true, mode: 0o700 });
-  try {
-    await fs.access(paths.config);
-  } catch {
-    await writeJsonAtomic(paths.config, defaultConfig(), 0o600);
-  }
-  try {
-    await fs.access(paths.secrets);
-  } catch {
-    await writeJsonAtomic(paths.secrets, {}, 0o600);
-  }
 }
 
 export async function loadConfig(paths = getPaths()) {
-  await ensureStore(paths);
-  const raw = await fs.readFile(paths.config, "utf8");
-  return normalizeConfig(JSON.parse(raw));
+  try {
+    const raw = await fs.readFile(paths.config, "utf8");
+    return normalizeConfig(JSON.parse(raw));
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
 }
 
 export async function loadSecrets(paths = getPaths()) {
-  await ensureStore(paths);
-  const raw = await fs.readFile(paths.secrets, "utf8");
-  const parsed = JSON.parse(raw);
-  return isRecord(parsed) ? parsed : {};
+  try {
+    const raw = await fs.readFile(paths.secrets, "utf8");
+    const parsed = JSON.parse(raw);
+    return isRecord(parsed) ? parsed : {};
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
 }
 
 export async function writeJsonAtomic(file, value, mode = 0o600) {
   const directory = path.dirname(file);
   await fs.mkdir(directory, { recursive: true, mode: 0o700 });
   const temporary = `${file}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`;
-  await fs.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode });
-  await fs.chmod(temporary, mode);
-  await fs.rename(temporary, file);
+  try {
+    await fs.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode });
+    await fs.chmod(temporary, mode);
+    const deadline = Date.now() + 1000;
+    while (true) {
+      try {
+        await fs.rename(temporary, file);
+        return;
+      } catch (error) {
+        // Windows readers and antivirus can briefly deny an atomic replacement.
+        if (!["EPERM", "EACCES", "EBUSY"].includes(error.code) || Date.now() >= deadline) throw error;
+        await delay(50);
+      }
+    }
+  } finally {
+    await fs.rm(temporary, { force: true }).catch(() => {});
+  }
 }
 
 export async function saveConfig(config, paths = getPaths()) {
@@ -222,16 +201,17 @@ export async function saveSecrets(secrets, paths = getPaths()) {
 }
 
 export async function backupFile(file, backupsDirectory, label) {
+  let contents;
   try {
-    const contents = await fs.readFile(file);
-    const stamp = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
-    const backup = path.join(backupsDirectory, `${stamp}-${label}`);
-    await fs.writeFile(backup, contents, { mode: 0o600 });
-    return backup;
+    contents = await fs.readFile(file);
   } catch (error) {
     if (error.code === "ENOENT") return null;
     throw error;
   }
+  const stamp = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
+  const backup = path.join(backupsDirectory, `${stamp}-${label}`);
+  await fs.writeFile(backup, contents, { mode: 0o600 });
+  return backup;
 }
 
 export function secretRefForUpstream(id) {