add-coder 0.3.24 → 0.3.25-0

package/README.md

@@ -220,21 +220,47 @@ Plan 里的 Task 不应该停留在文档里。add-coder 将 tasks.md 末尾的
 tasks.md §IDE JSON → TodoWrite → IDE 面板
 ```
 
-### ⑩ 并发协作契约：多智能体协作即契约
+### ⑩ 并发契约体系：协作层 + 进程层双层
 
-多个 Agent 同时改一个仓库，没有契约必然冲突——改同一批文件、审计归因混乱。add-coder 把并行协作变成一份**经 HITL 审批的契约**：
+多个 Agent 同时改一个仓库，没有契约必然冲突——改同一批文件、审计归因混乱。add-coder 把并行协作变成**经 HITL 审批的契约体系**，分两层：
 
-| 机制 | 实现 |
-|------|------|
-| **总控 Plan + N 个子 Plan** | Lead Agent 调度，专家按 description 触发条件委派，满足即拉起 |
-| **文件边界** | 默认软隔离（git diff 交叉检查），大改升级 git worktree 硬隔离 |
-| **仲裁链路** | 跨边界修改走 BOUNDARY_REQUEST → Lead 裁决 → 落库可查 |
-| **审计分桶** | 每个专家独立 planKeyword，query_audit_logs 各域各查 |
+| 层 | 契约 | 版本 | 职责 |
+|----|------|------|------|
+| **协作层** | 并发协作契约（collab-contract） | v1（v0.3.18） | 多智能体协作秩序：总控 Plan + N 个子 Plan / 文件边界 / 仲裁链路 / 审计分桶 |
+| **进程层** | [多 IDE 进程并发契约](./docs/multi-ide-concurrency-contract.md) | v2（v0.3.25） | MCP Server 并发行为承诺：连接模型 / 幂等键 / PROJECT_ID 校验 / 断开隔离四态 / 生命周期拆分 / client 编排差异矩阵 |
 
-> 契约模板：`templates/core/templates/collab-contract-template.md`（init 后同步到项目 `.add/templates/`），契约新建/重大变更走 `COLLAB_CONTRACT` 审批。
+> 协作层模板：`templates/core/templates/collab-contract-template.md`（契约新建/重大变更走 `COLLAB_CONTRACT` 审批）。
+> 进程层文档：`docs/multi-ide-concurrency-contract.md`（Codex Parallel MCP / TAgent / Claude Code 并发行为对齐基准）。
 >
 > 📜 溯源：并发契约原创时间戳 → [CHANGELOG v0.3.18「并发协作契约」](https://github.com/xiaomingming92/add-coder/blob/main/CHANGELOG.md#0318---2026-08-05)；"酷"的工程学定义 → [what-makes-software-cool.md](https://github.com/xiaomingming92/add-coder/blob/main/docs/what-makes-software-cool.md)——契约的审计分桶与完成判定（DPS ≥ 80）正长在"熵值管控"四维上。
 
+### ⑪ Codex MCP 原生接入（v0.3.25）
+
+> **状态区分**："已生成 Codex 模板" ≠ "Codex MCP 端到端已验证"——以下 6 步是**已验证闭环**，不写自定义脚本即可完成接入。
+
+```bash
+# 1. 安装 add-coder（已安装可跳过）
+npm i -g add-coder
+
+# 2. 初始化 Codex 适配（hooks 模板 + config.toml 真源）
+add-coder init --adapter=codex
+
+# 3. 输出可直接使用的 config.toml 片段（不写盘，不初始化项目）
+add-coder init --adapter=codex --print-mcp-config
+
+# 4a. 粘贴片段到 ~/.codex/config.toml（Windows: %USERPROFILE%\.codex\config.toml）
+# 4b. 或自动写入（显式确认 + 先备份 + 防重复）
+add-coder init --adapter=codex --write-user-config
+
+# 5. 重启 Codex（App/CLI/IDE 扩展通用，修改 config.toml 后需重启生效）
+
+# 6. 验证：Codex 中发现 add_coder MCP Server，完整工具集可调用（29 tools）
+```
+
+**Windows 分支**：`--print-mcp-config` 在 win32 平台自动输出 `cmd /c npx.cmd` 启动分支（原生 PowerShell 场景，不依赖 WSL）。
+
+**命名兼容**：MCP Server ID 归一化为 `add_coder`（连字符→下划线，Codex 约束）；`env.PROJECT_ROOT` 由渲染时注入，多项目粘贴错误配置时 mcp-server 启动即校验退出（进程层契约 §4）。
+
 ---
 
 ## 📖 案例示范：老安卓设备续命工程
@@ -351,7 +377,7 @@ npx add-coder init
 | `.qoder/` | Qoder 适配（hooks、settings.json、mcp.json） |
 | `.vscode/` | VS Code 适配（settings.json、tasks.json） |
 | `.trae/` | Trae 适配（hooks.json、settings.json） |
-| `.codex/` | Codex 适配（hooks.json、settings.json） |
+| `.codex/` | Codex 适配（hooks.json、settings.json、config.toml.example） |
 
 ## MCP 审计工具链
 

package/dist/index.js

@@ -623,8 +623,18 @@ function renderAdapter4(config, targetDir, dryRun, magicDir) {
 }
 
 // src/adapters/codex/renderer.ts
+function codexCommandFor(platform) {
+  return platform === "win32" ? "cmd /c npx.cmd" : "npx";
+}
 function renderAdapter5(config, targetDir, dryRun, magicDir) {
-  return renderAdapterBase(config, magicDir, magicDir === ".vscode", dryRun);
+  const files = renderAdapterBase(config, magicDir, magicDir === ".vscode", dryRun);
+  const codexCommand = codexCommandFor(process.platform);
+  for (const [rel, content] of files) {
+    if (rel.endsWith("config.toml.example") || rel.endsWith("config.toml")) {
+      files.set(rel, content.replaceAll("{{codexCommand}}", codexCommand));
+    }
+  }
+  return files;
 }
 
 // src/lib/utils.ts
@@ -1366,7 +1376,8 @@ async function injectPrisma2(projectRoot, options = {}) {
 // src/cli/commands/init.ts
 import { readFileSync as readFileSync9, writeFileSync as writeFileSync6, existsSync as existsSync11, mkdirSync as mkdirSync6, copyFileSync as copyFileSync2, readdirSync as readdirSync4 } from "fs";
 import { createHash } from "crypto";
-import { resolve as resolve8 } from "path";
+import { resolve as resolve8, dirname as dirname5, join as pathJoin } from "path";
+import { homedir as homedir2 } from "os";
 import { createConnection as createConnection2 } from "net";
 
 // src/lib/model-predownload.ts
@@ -1455,6 +1466,10 @@ var ADAPTER_RENDERERS = {
 };
 var MAGIC_DIR_MAP = { claude: ".claude", qoder: ".qoder", vscode: ".vscode", trae: ".trae", codex: ".codex" };
 async function initCommand(options) {
+  if (options.printMcpConfig || options.writeUserConfig) {
+    await handleCodexMcpConfig(options);
+    return;
+  }
   const ctx = await prepare(options);
   writeComposeEnv(ctx);
   if (!options.dryRun) {
@@ -1477,6 +1492,51 @@ async function initCommand(options) {
     }
   }
 }
+async function handleCodexMcpConfig(options) {
+  const projectRoot = process.cwd();
+  const magicDir = MAGIC_DIR_MAP[options.adapter ?? "codex"] ?? ".codex";
+  const config = await loadConfig(projectRoot, options.config, { force: true });
+  config.projectRoot = projectRoot;
+  config.magicDir = magicDir;
+  const files = renderAdapter5(config, projectRoot, !!options.dryRun, magicDir);
+  const tomlEntry = [...files.entries()].find(
+    ([rel]) => rel.endsWith("config.toml.example") || rel.endsWith("config.toml")
+  );
+  if (!tomlEntry) {
+    console.error("\u2717 config.toml \u6E32\u67D3\u4EA7\u7269\u7F3A\u5931\uFF08\u68C0\u67E5 templates/adapters/codex/config.toml.example\uFF09");
+    process.exit(1);
+  }
+  const toml = tomlEntry[1];
+  if (options.printMcpConfig) {
+    console.log("\n# \u5C06\u4EE5\u4E0B\u7247\u6BB5\u7C98\u8D34\u5230 ~/.codex/config.toml\uFF08\u6216\u4F7F\u7528 --write-user-config \u81EA\u52A8\u5199\u5165\uFF09");
+    console.log(toml);
+  }
+  if (options.writeUserConfig) {
+    const userConfigPath = pathJoin(homedir2(), ".codex", "config.toml");
+    if (options.dryRun) {
+      console.log(`[dry-run] \u5C06\u5199\u5165 ${userConfigPath}`);
+      return;
+    }
+    if (existsSync11(userConfigPath) && readFileSync9(userConfigPath, "utf-8").includes("mcp_servers.add_coder")) {
+      console.log(`\u26A0\uFE0F ${userConfigPath} \u5DF2\u5B58\u5728 mcp_servers.add_coder \u914D\u7F6E\uFF0C\u8DF3\u8FC7\uFF08\u907F\u514D\u91CD\u590D\uFF09`);
+      return;
+    }
+    const answer = await ask(`\u5199\u5165 ${userConfigPath}\uFF1F\uFF08y/N\uFF09 \u2192 `);
+    if (answer.trim().toLowerCase() !== "y") {
+      console.log("\u5DF2\u53D6\u6D88\u5199\u5165");
+      return;
+    }
+    if (existsSync11(userConfigPath)) {
+      const backup = `${userConfigPath}.bak-${Date.now()}`;
+      copyFileSync2(userConfigPath, backup);
+      console.log(`\u5DF2\u5907\u4EFD\u539F\u914D\u7F6E \u2192 ${backup}`);
+    }
+    mkdirSync6(dirname5(userConfigPath), { recursive: true });
+    writeFileSync6(userConfigPath, `
+${toml}`, { flag: "a" });
+    console.log(`\u2705 \u5DF2\u5199\u5165 ${userConfigPath}\uFF0C\u91CD\u542F Codex \u751F\u6548`);
+  }
+}
 async function resolveAdapter(projectRoot, specified) {
   if (specified) {
     if (!MAGIC_DIR_MAP[specified]) throw new Error(`\u672A\u77E5 adapter: ${specified}`);
@@ -1899,7 +1959,7 @@ function finalize(ctx, result, dbFail) {
 
 // src/cli/commands/sync.ts
 import { existsSync as existsSync12, readFileSync as readFileSync10, writeFileSync as writeFileSync7, mkdirSync as mkdirSync7 } from "fs";
-import { resolve as resolve9, dirname as dirname5 } from "path";
+import { resolve as resolve9, dirname as dirname6 } from "path";
 import { createHash as createHash2 } from "crypto";
 
 // src/lib/path-normalize.ts
@@ -2144,7 +2204,7 @@ async function syncCommand(options = {}) {
 }
 function printMigrateGuidance(targetPath, changed) {
   const g = SYNC_PRISMA_CONFIG.POST_SYNC;
-  const isManaged = existsSync12(resolve9(dirname5(targetPath), "migrations"));
+  const isManaged = existsSync12(resolve9(dirname6(targetPath), "migrations"));
   const actions = isManaged ? g.MANAGED_ACTIONS : g.UNMANAGED_ACTIONS;
   console.log(`  \u25B6 \u5DF2\u5199\u5165 ${changed} \u5904\u53D8\u66F4\uFF0C${g.HEADER}`);
   for (const a of actions) {
@@ -2338,7 +2398,7 @@ async function checkPrismaDiff(projectRoot, options) {
   } else {
     console.log(`
   \u76EE\u6807 schema \u6587\u4EF6\u4E0D\u5B58\u5728: ${result.targetPath}`);
-    mkdirSync7(dirname5(targetPath), { recursive: true });
+    mkdirSync7(dirname6(targetPath), { recursive: true });
     writeFileSync7(targetPath, "// add.prisma \u2014 ADD \u6CBB\u7406\u6A21\u578B\n\n", "utf-8");
     const n = injectMissingModels(targetPath, result.missing);
     console.log(`  \u2705 \u5DF2\u521B\u5EFA\u5E76\u6CE8\u5165 ${n} \u4E2A\u6A21\u578B/\u679A\u4E3E`);
@@ -2668,7 +2728,7 @@ async function modelDownloadCommand(options) {
 }
 var program = new Command();
 program.name("add-coder").description("\u521D\u59CB\u5316 ADD \u8303\u5F0F\u5DE5\u4F5C\u6D41\u6A21\u677F").version(version);
-program.command("init").description("\u521D\u59CB\u5316 ADD \u6A21\u677F\u5230\u5F53\u524D\u9879\u76EE").option("--adapter <type>", "\u76EE\u6807 IDE: claude | qoder | vscode | trae | codex").option("--config <path>", "\u6307\u5B9A\u914D\u7F6E\u6587\u4EF6\u8DEF\u5F84").option("--force", "\u8986\u76D6\u5DF2\u6709\u6587\u4EF6\uFF0C\u4E0D\u4EA4\u4E92").option("--dry-run", "\u9884\u89C8\u6A21\u5F0F\uFF0C\u4E0D\u5B9E\u9645\u5199\u5165").option("--stack <name>", "\u6280\u672F\u6808\u7EA6\u675F profile \u540D\uFF08\u5982 machineserver\uFF0C\u53EF\u9009\uFF09").option("--skip-model", "\u8DF3\u8FC7 embedding \u6A21\u578B\u9884\u4E0B\u8F7D").action(initCommand);
+program.command("init").description("\u521D\u59CB\u5316 ADD \u6A21\u677F\u5230\u5F53\u524D\u9879\u76EE").option("--adapter <type>", "\u76EE\u6807 IDE: claude | qoder | vscode | trae | codex").option("--config <path>", "\u6307\u5B9A\u914D\u7F6E\u6587\u4EF6\u8DEF\u5F84").option("--force", "\u8986\u76D6\u5DF2\u6709\u6587\u4EF6\uFF0C\u4E0D\u4EA4\u4E92").option("--dry-run", "\u9884\u89C8\u6A21\u5F0F\uFF0C\u4E0D\u5B9E\u9645\u5199\u5165").option("--stack <name>", "\u6280\u672F\u6808\u7EA6\u675F profile \u540D\uFF08\u5982 machineserver\uFF0C\u53EF\u9009\uFF09").option("--skip-model", "\u8DF3\u8FC7 embedding \u6A21\u578B\u9884\u4E0B\u8F7D").option("--print-mcp-config", "Codex: stdout \u8F93\u51FA config.toml \u7247\u6BB5\uFF08\u4E0D\u5199\u76D8\uFF0C\u4E0D\u521D\u59CB\u5316\u9879\u76EE\uFF09").option("--write-user-config", "Codex: \u663E\u5F0F\u786E\u8BA4\u540E\u5199\u5165 ~/.codex/config.toml\uFF08\u5148\u5907\u4EFD\uFF09").action(initCommand);
 program.command("sync").description("\u589E\u91CF\u540C\u6B65\u7F3A\u5931\u6587\u4EF6\uFF08--patch \u8986\u76D6\u5DF2\u6709\u6A21\u677F\uFF09").option("--adapter <type>", "\u76EE\u6807 IDE: claude | qoder | vscode | trae | codex").option("--patch", "\u8986\u76D6\u5DF2\u6709\u6A21\u677F\u6587\u4EF6\uFF08\u4E0D\u78B0 plans/specs/reviews\uFF09").option("-i, --interactive", "\u4EA4\u4E92\u5F0F\u9009\u62E9\u8981\u540C\u6B65\u7684\u6587\u4EF6").option("--model", "\u68C0\u6D4B\u5230\u7F3A\u5931\u65F6\u4E0B\u8F7D embedding \u6A21\u578B").action(syncCommand);
 program.command("status").description("\u68C0\u67E5 ADD \u6A21\u677F\u5B8C\u6574\u6027").action(statusCommand);
 program.command("stack").description("\u7BA1\u7406\u6280\u672F\u6808\u7EA6\u675F profile\uFF08list / set <name> / show / --clear\uFF09").argument("[sub]", "list | set | show").argument("[name]", "set <name>: profile \u540D\uFF08\u5185\u7F6E\u6216\u81EA\u5B9A\u4E49\uFF09").option("--adapter <type>", "\u76EE\u6807 IDE: claude | qoder | vscode | trae | codex").option("--clear", "\u6E05\u9664\u6280\u672F\u6808\u8BBE\u7F6E\uFF08\u4E2D\u6027\uFF09").action(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "add-coder",
-  "version": "0.3.24",
+  "version": "0.3.25-0",
   "private": false,
   "description": "[codein2027](https://github.com/xiaomingming92/codein2027) - A complete scaffolding for building the ADD programming paradigm, the implementation layer for AI code governance. Core principle: Audit as Infrastructure. Breaks the black-box programming process and cross-session amnesia, evolving programming paradigms into an auditable, traceable, and convergent new era. npx-ready.\n\n[codein2027](https://github.com/xiaomingming92/codein2027) 快速构建 ADD 编程范式的完整脚手架——AI 代码治理的落地方案。以「审计即基础设施」为核心，彻底打破编程过程黑盒与跨轮失忆，让编程范式进化为可审计、可追溯、可收敛的新时代。npx 即用，人人可体验。",
   "repository": {

package/templates/.add-coder-src-hash.json

@@ -1,5 +1,5 @@
 {
-  "_version": "0.3.24",
+  "_version": "0.3.25-0",
   "adapters/claude/hooks/doc-format-guard.sh": "ec59ad3f",
   "adapters/claude/hooks/lib/common.sh": "4f3e64ad",
   "adapters/claude/hooks/lib/context-inject.sh": "cfc8c65e",
@@ -26,6 +26,7 @@
   "adapters/claude/hooks/subagent-stop.sh": "0f89e28c",
   "adapters/claude/mcp.json": "4ddc5120",
   "adapters/claude/settings.json": "067ccc45",
+  "adapters/codex/config.toml.example": "de1634aa",
   "adapters/codex/hooks/doc-format-guard.sh": "8e134e78",
   "adapters/codex/hooks/lib/common.sh": "4f3e64ad",
   "adapters/codex/hooks/lib/context-inject.sh": "cfc8c65e",
@@ -180,7 +181,7 @@
   "core/rules/profiles/webapp-profile.md": "e493ae7b",
   "core/rules/project_rules.md": "82b25e08",
   "core/rules/theory-practice-map.toml": "b1db99fd",
-  "core/scripts/db-ensure.sh": "1ef7a9f3",
+  "core/scripts/db-ensure.sh": "94a5ff92",
   "core/scripts/gen-plan-index.sh": "bfc6ad3e",
   "core/scripts/mcp-server/elicitation/confirm.ts": "924857b8",
   "core/scripts/mcp-server/elicitation/index.ts": "44c5dc3f",
@@ -202,7 +203,8 @@
   "core/scripts/mcp-server/shared/package.json": "e3d5a4a2",
   "core/scripts/mcp-server/shared/prisma.ts": "a9618f99",
   "core/scripts/mcp-server/shared/project-root-strategy.ts": "1a5bdc57",
-  "core/scripts/mcp-server/shared/response.ts": "f7806b67",
+  "core/scripts/mcp-server/shared/redact.ts": "22e008aa",
+  "core/scripts/mcp-server/shared/response.ts": "0d1539a8",
   "core/scripts/mcp-server/shared/run-command.ts": "42caf972",
   "core/scripts/mcp-server/tasks/index.ts": "c040eb75",
   "core/scripts/mcp-server/tasks/runner.ts": "d84bd35d",
@@ -214,20 +216,20 @@
   "core/scripts/mcp-server/tools/gateway/check_add_route_completeness.ts": "b58e76ee",
   "core/scripts/mcp-server/tools/gateway/check_add_route_status.ts": "23fbbb6b",
   "core/scripts/mcp-server/tools/gateway/check_dps.ts": "4d599b38",
-  "core/scripts/mcp-server/tools/gateway/check_rahs.ts": "4078b0f1",
-  "core/scripts/mcp-server/tools/gateway/check_spec_sync.ts": "486df441",
+  "core/scripts/mcp-server/tools/gateway/check_rahs.ts": "3ce99c7c",
+  "core/scripts/mcp-server/tools/gateway/check_spec_sync.ts": "8d6efd83",
   "core/scripts/mcp-server/tools/gateway/helpers.ts": "f8794a92",
   "core/scripts/mcp-server/tools/gateway/index.ts": "559acb75",
   "core/scripts/mcp-server/tools/gateway.backup": "65eae393",
   "core/scripts/mcp-server/tools/hitl.ts": "f447345f",
   "core/scripts/mcp-server/tools/hook-event-report.ts": "3f21836e",
-  "core/scripts/mcp-server/tools/index.ts": "884172ba",
+  "core/scripts/mcp-server/tools/index.ts": "3e6b6135",
   "core/scripts/mcp-server/tools/plan.ts": "477fd80d",
   "core/scripts/mcp-server/tools/quality.ts": "c4634453",
   "core/scripts/mcp-server/tools/registrar.ts": "efd81b3a",
   "core/scripts/mcp-server/tools/review.ts": "370f84f2",
   "core/scripts/mcp-server/types.ts": "6c5e60bc",
-  "core/scripts/mcp-server.ts": "99cc6833",
+  "core/scripts/mcp-server.ts": "48b1fd69",
   "core/skills/add-paradigm/SKILL.md": "5d4fa389",
   "core/skills/session-init/SKILL.md": "bb1205b0",
   "core/specs/add-coder-npm-package/checklist.md": "ed92032c",

package/templates/adapters/codex/config.toml.example

@@ -0,0 +1,20 @@
+# Codex MCP 配置模板（真源）
+# 渲染后分发到 .codex/ 与各 magic dirs templates/，供 --print-mcp-config 输出
+# 使用方式:
+#   npx add-coder init --adapter=codex --print-mcp-config   # stdout 输出片段
+#   npx add-coder init --adapter=codex --write-user-config  # 显式确认后写入 ~/.codex/config.toml
+#
+# Windows 分支（renderer 按平台注入，无需手动修改）:
+#   win32: command = "cmd /c"  args = ["npx.cmd", "tsx", "..."]   # .cmd 分支
+#   posix: command = "npx"     args = ["tsx", "..."]
+#
+# 安全约定:
+#   - env 只引用环境变量（{{projectRoot}} 由渲染时注入，密码/连接串禁止写入模板）
+#   - DATABASE_URL 请通过消费方 .env 或 IDE 环境传入，模板不包含任何连接串
+
+[mcp_servers.add_coder]
+command = "{{codexCommand}}"
+args = ["tsx", "{{magicDir}}/scripts/mcp-server.ts"]
+env = {
+  PROJECT_ROOT = "{{projectRoot}}",
+}

package/templates/core/scripts/db-ensure.sh

@@ -156,6 +156,14 @@ apply_atlas_diff() {
 # ⑦ Atlas 同步主流程（探测 → dev-url → 目标 → baseline → diff → apply）
 atlas_sync() {
   [ "$ENGINE" = "sqlite" ] && return 0
+  # 迁移锁（进程层契约 v2 §6）：多 IDE 并发 init 时仅一个进程执行迁移
+  # 非阻塞拿锁（pg_try_advisory_lock），会话级锁——脚本退出连接断开自动释放
+  LOCK_KEY="0xADD001"
+  LOCKED="$(podman exec "${PROJECT_NAME:-add-project}-postgres" psql -U "${DATABASE_USER:-admin}" -d "${PROJECT_NAME:-add-project}" -tAc "SELECT pg_try_advisory_lock(${LOCK_KEY});" 2>/dev/null || true)"
+  if [ "$LOCKED" != "t" ]; then
+    echo "!!! 另一个进程正在迁移，请稍后重试"
+    return 1
+  fi
   if ! atlas_cmd version > /dev/null 2>&1; then
     echo "!!! Atlas 不可用。add-coder sync --patch 可自动安装 @ariga/atlas；或手动: pnpm add -D @ariga/atlas"
     echo "    降级路径: prisma-diff（免 shadow）→ db-push + 强制备份；文档: README「Atlas 数据库同步能力」"

package/templates/core/scripts/mcp-server/shared/redact.ts

@@ -0,0 +1,28 @@
+/*
+ * @Author       : xiaomingming wujixmm@gmail.com
+ * @Date         : 2026-08-10 18:41:34
+ * @LastEditors  : xiaomingming wujixmm@gmail.com
+ * @LastEditTime : 2026-08-10 18:41:35
+ * @FilePath     : /farm-agent/home/xmm/ai/add-coder/templates/core/scripts/mcp-server/shared/redact.ts
+ * @Description  : 
+ */
+// 敏感信息脱敏（进程层并发契约 v2：日志/错误不泄露 DATABASE_URL/密码）
+// 统一入口：response.ts 的 textResponse/errorResponse 内部调用，一处封装全覆盖所有工具
+
+const CONNECTION_URL_RE =
+  /(postgres(?:ql)?|mysql|redis|mongodb(?:\+srv)?):\/\/[^\s"'`]+/gi
+
+export function redactUrl(url: string): string {
+  // postgres://user:pass@host:port/db → postgres://user:****@host:port/db
+  return url.replace(/(:\/\/[^:/\s]+:)([^@/\s]+)(@)/, "$1****$3")
+}
+
+export function redact(text: string): string {
+  return text.replace(CONNECTION_URL_RE, (m) => {
+    try {
+      return redactUrl(m)
+    } catch {
+      return m
+    }
+  })
+}

package/templates/core/scripts/mcp-server/shared/response.ts

@@ -1,9 +1,10 @@
 import type { ToolResponse } from "../types.js"
+import { redact } from "./redact.js"
 
 export function textResponse(text: string): { content: ToolResponse } {
-  return { content: [{ type: "text", text }] }
+  return { content: [{ type: "text", text: redact(text) }] }
 }
 
 export function errorResponse(message: string): { content: ToolResponse; isError: boolean } {
-  return { content: [{ type: "text", text: message }], isError: true }
+  return { content: [{ type: "text", text: redact(message) }], isError: true }
 }

package/templates/core/scripts/mcp-server/tools/gateway/check_rahs.ts

@@ -9,7 +9,7 @@
 import * as z from "zod/v4";
 import type { ToolRegistrar } from "../registrar.js";
 import { existsSync } from "fs";
-import { join } from "path";
+import { join, basename } from "path";
 import { textResponse, errorResponse } from "../../shared/response.js";
 import {
   readFileSafe,
@@ -42,7 +42,9 @@ export function registerCheckRahs(server: ToolRegistrar) {
         );
         const pm = apf.find(
           (f) =>
-            f.toLowerCase().includes(pp.toLowerCase()) && f.includes("-plan-v"),
+            f.toLowerCase().includes(pp.toLowerCase()) &&
+            f.includes("-plan-v") &&
+            !f.includes(".hitl"),
         );
         if (!pm)
           return errorResponse(`未找到匹配的 Plan 文件（关键词: ${pp}）`);
@@ -80,6 +82,71 @@ export function registerCheckRahs(server: ToolRegistrar) {
           })) as Array<{ id: string }>;
           auditScore = Math.min(100, logs.length * 10);
         } catch {}
+        // ── 范围保真度 / Spec 合规 / 阶段对称性：从静态基线改为动态计算（修复：
+        //    三个维度原为固定 80，任何 Plan 的 RAHS 上限 88 永远无法通过）──
+        try {
+          const arFile = apf.find(
+            (f) =>
+              f.toLowerCase().includes(pp.toLowerCase()) &&
+              f.toLowerCase().includes("add-route"),
+          );
+          if (arFile) {
+            const arContent =
+              (await readFileSafe(join(plansDir, arFile))) || "";
+            const checks = arContent.match(/^- \[[ x]\]/gm) || [];
+            const done = checks.filter((c) => c.includes("[x]")).length;
+            // 阶段对称性：add-route Step 产出项勾选率（Handoff/Report Closure 等
+            //    条件项未勾选时按比例折算，不阻塞）
+            symScore = checks.length > 0
+              ? Math.max(70, Math.round((done / checks.length) * 100))
+              : 70;
+          }
+        } catch {}
+        try {
+          // Spec 合规：checklist [T] 项勾选率（[R] 运行时项不计入）
+          const specDir = join(PROJECT_ROOT, MAGIC_DIR, "specs");
+          const sn = basename(pm, ".md").replace(/-plan-v\d+$/i, "");
+          const clPath = join(specDir, sn, "checklist.md");
+          if (existsSync(clPath)) {
+            const cl = (await readFileSafe(clPath)) || "";
+            const tItems = cl.match(/^- \[[ x]\] \[T\]/gm) || [];
+            const tDone = tItems.filter((c) => c.includes("[x]")).length;
+            specScore = tItems.length > 0
+              ? Math.max(70, Math.round((tDone / tItems.length) * 100))
+              : 70;
+          }
+        } catch {}
+        try {
+          // 范围保真度：git diff 变更文件与 add-route 附录清单匹配率
+          const arFile = apf.find(
+            (f) =>
+              f.toLowerCase().includes(pp.toLowerCase()) &&
+              f.toLowerCase().includes("add-route"),
+          );
+          if (arFile) {
+            const arContent =
+              (await readFileSafe(join(plansDir, arFile))) || "";
+            const appendix = (
+              arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml)`/g) ||
+              []
+            ).map((f: string) => f.replace(/`/g, "").toLowerCase());
+            const diff = runCommand("git", ["diff", "--name-only"], {
+              cwd: PROJECT_ROOT,
+              timeout: 5000,
+            });
+            const diffFiles = diff.stdout
+              .trim()
+              .split("\n")
+              .filter(Boolean)
+              .map((f: string) => f.toLowerCase());
+            if (appendix.length > 0 && diffFiles.length > 0) {
+              const matched = diffFiles.filter((f) =>
+                appendix.some((a) => f === a || f.endsWith(`/${a}`)),
+              ).length;
+              scopeScore = Math.max(70, Math.round((matched / diffFiles.length) * 100));
+            }
+          }
+        } catch {}
         const parts = [
           "=== RAHS：Runtime Architecture Health Score ===",
           `Plan 关键词: "${pp}"`,

package/templates/core/scripts/mcp-server/tools/gateway/check_spec_sync.ts

@@ -69,7 +69,7 @@ export function registerCheckSpecSync(server: ToolRegistrar) {
           lines.push(`add-route: ${arFile}`);
           const arContent = (await readFileSafe(join(plansDir, arFile))) || "";
           // 提取 add-route 附录文件清单
-          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json)`/g) || [])
+          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml)`/g) || [])
             .map((f: string) => f.replace(/`/g, ""));
           lines.push(`附录文件: ${appendixFiles.length} 个`);
 

package/templates/core/scripts/mcp-server/tools/index.ts

@@ -12,6 +12,61 @@ import { registerReviewTools } from "./review.js"
 import { PROJECT_ID } from "../shared/env.js"
 import type { ToolRegistrar } from "./registrar.js"
 
+// ── 读写分级信号量节流（进程层并发契约 v2 §7：Codex Parallel MCP 真并行兑底） ──
+// 读工具共享 8 并发；写工具共享 4 并发；超限请求排队（MCP 协议允许延迟响应，排队即天然反压）
+const READ_MAX = 8
+const WRITE_MAX = 4
+
+const READ_TOOLS = new Set([
+  "get_project_context", "find_related_docs", "get_db_schema", "query_audit_logs",
+  "plan_status", "review_status", "status_hitl", "contract_status",
+  "check_dps", "check_rahs", "check_add_route_status", "check_spec_sync",
+  "check_add_route_completeness", "check_phase_symmetry", "check_failure_path",
+  "check_add_compliance", "get_hook_events",
+])
+
+function createSemaphore(limit: number) {
+  let active = 0
+  const queue: (() => void)[] = []
+  const acquire = () =>
+    new Promise<void>((resolve) => {
+      if (active < limit) {
+        active++
+        resolve()
+      } else {
+        queue.push(resolve)
+      }
+    })
+  const release = () => {
+    active--
+    const next = queue.shift()
+    if (next) {
+      active++
+      next()
+    }
+  }
+  return { acquire, release }
+}
+
+// 429 指数退避重试（3 次，250ms 起步，倍率 2x）：上游限流不直接透传
+async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
+  let lastErr: unknown
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    try {
+      return await fn()
+    } catch (e) {
+      lastErr = e
+      const msg = e instanceof Error ? e.message : String(e)
+      if (!/429|rate.?limit|限流/i.test(msg)) throw e
+      await new Promise((r) => setTimeout(r, 250 * 2 ** (attempt - 1)))
+    }
+  }
+  throw lastErr
+}
+
+const readSem = createSemaphore(READ_MAX)
+const writeSem = createSemaphore(WRITE_MAX)
+
 export function registerAllTools(server: McpServer) {
   // D9 多 MCP 路由安全：派生装饰版 registrar，为所有工具 description 注入项目身份前缀
   const origRegister = server.registerTool.bind(server)
@@ -20,10 +75,20 @@ export function registerAllTools(server: McpServer) {
   type ToolCb = Parameters<RegisterTool>[2]
   const registerTool = ((name: string, config: ToolConfig, cb: ToolCb) => {
     const c = config as { description?: string }
+    // 读写分级节流 + 429 退避（进程层契约 v2：Codex 并行调用兜底）
+    const sem = READ_TOOLS.has(name) ? readSem : writeSem
+    const throttledCb = (async (...args: unknown[]) => {
+      await sem.acquire()
+      try {
+        return await withRetry(async () => cb(...(args as Parameters<ToolCb>)))
+      } finally {
+        sem.release()
+      }
+    }) as ToolCb
     return origRegister(
       name,
       { ...config, description: `[项目: ${PROJECT_ID}] ${c.description ?? ""}` },
-      cb,
+      throttledCb,
     )
   }) as RegisterTool
   const registrar: ToolRegistrar = { registerTool }

package/templates/core/scripts/mcp-server.ts

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/server"
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio"
 import { registerAll } from "./mcp-server/index.js"
+import { redact } from "./mcp-server/shared/redact.js"
 
 async function main() {
   const server = new McpServer(
@@ -14,6 +15,6 @@ async function main() {
 }
 
 main().catch((error) => {
-  console.error("[ADD-MCP] Fatal error:", error)
+  console.error("[ADD-MCP] Fatal error:", redact(error instanceof Error ? error.message : String(error)))
   process.exit(1)
 })