@boyingliu01/xp-gate 0.31.0 → 0.31.2

package/lib/shared-paths.js

@@ -14,13 +14,9 @@ const fs = require('fs');
  * Resolve the user's home directory cross-platform.
  * Fallback chain: HOME → USERPROFILE → os.homedir()
  */
-const HOME_DIR = process.env.HOME || process.env.USERPROFILE || os.homedir();
-
-const CONFIG_DIR = path.join(HOME_DIR, '.config', 'xp-gate');
-const CONFIG_FILE = path.join(CONFIG_DIR, 'xp-gate.json');
-const GLOBAL_HOOKS_DIR = path.join(CONFIG_DIR, 'hooks');
-const GLOBAL_ADAPTERS_DIR = path.join(CONFIG_DIR, 'adapters');
-const GLOBAL_MODULES_DIR = path.join(CONFIG_DIR, 'modules');
+function resolveHomeDir() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
 
 /**
  * Detect which AI agent platform is currently in use.
@@ -28,11 +24,12 @@ const GLOBAL_MODULES_DIR = path.join(CONFIG_DIR, 'modules');
  * @returns {'opencode' | 'claude-code' | 'qoder'}
  */
 function detectPlatform() {
+  const homeDir = resolveHomeDir();
   // Any ~/.qoder content counts as Qoder: a brand-new install has no skills/
   // subdirectory yet, so a skills-only marker misdetects it as opencode and
   // configureQoderDelphiAgents deploys zero Delphi agents (#424).
-  if (fs.existsSync(path.join(HOME_DIR, '.qoder'))) return 'qoder';
-  if (fs.existsSync(path.join(HOME_DIR, '.claude', 'skills'))) return 'claude-code';
+  if (fs.existsSync(path.join(homeDir, '.qoder'))) return 'qoder';
+  if (fs.existsSync(path.join(homeDir, '.claude', 'skills'))) return 'claude-code';
   return 'opencode';
 }
 
@@ -49,23 +46,60 @@ function detectPlatform() {
  * @returns {string} Path to the platform-specific git hooks template directory
  */
 function getTemplateDir() {
+  const homeDir = resolveHomeDir();
   const platform = detectPlatform();
   const configDir = platform === 'claude-code' ? '.claude' :
                     platform === 'qoder' ? '.qoder' :
                     path.join('.config', 'opencode');
-  return path.join(HOME_DIR, configDir, 'git-hooks-template');
+  return path.join(homeDir, configDir, 'git-hooks-template');
 }
 
-const TEMPLATE_DIR = getTemplateDir();
+// ---------------------------------------------------------------------------
+// The constants below are DERIVED FROM THE ENVIRONMENT, so they are computed
+// per property access rather than once at require() time.
+//
+// They used to be plain `const`s evaluated at module load. That made the value
+// depend on WHO LOADED THIS MODULE FIRST: detect-deps.js requires shared-paths
+// at its own load, so any consumer loaded earlier froze the paths to whatever
+// HOME was at that moment. In the doctor test suite that was the REAL home
+// directory — detect-deps is loaded in beforeAll, before any test sets HOME —
+// so doctor reported `Config file: Not found` for every fixture that had in
+// fact written the config, and `--fix` returned 1 on a healthy installation.
+//
+// A getter keeps the existing `require`-and-destructure call sites working
+// (module.exports.CONFIG_FILE still evaluates to a string), while making the
+// value follow process.env.HOME.
+// ---------------------------------------------------------------------------
+function defineLazy(obj, name, compute) {
+  Object.defineProperty(obj, name, {
+    enumerable: true,
+    get: compute,
+    // The values are a pure function of the environment; caching them for the
+    // lifetime of the process would reintroduce the bug fixed here.
+    configurable: true,
+  });
+}
+
+const GLOBAL_DIRS = {
+  CONFIG_DIR: () => path.join(resolveHomeDir(), '.config', 'xp-gate'),
+  GLOBAL_HOOKS_DIR: () => path.join(GLOBAL_DIRS.CONFIG_DIR(), 'hooks'),
+  GLOBAL_ADAPTERS_DIR: () => path.join(GLOBAL_DIRS.CONFIG_DIR(), 'adapters'),
+  GLOBAL_MODULES_DIR: () => path.join(GLOBAL_DIRS.CONFIG_DIR(), 'modules'),
+};
 
-module.exports = {
-  HOME_DIR,
-  CONFIG_DIR,
-  CONFIG_FILE,
-  TEMPLATE_DIR,
-  GLOBAL_HOOKS_DIR,
-  GLOBAL_ADAPTERS_DIR,
-  GLOBAL_MODULES_DIR,
+// Base name for the other derived paths.
+GLOBAL_DIRS.CONFIG_FILE = () => path.join(GLOBAL_DIRS.CONFIG_DIR(), 'xp-gate.json');
+
+const exportsObj = {
   detectPlatform,
   getTemplateDir,
+  resolveHomeDir,
 };
+
+defineLazy(exportsObj, 'HOME_DIR', () => resolveHomeDir());
+for (const [name, compute] of Object.entries(GLOBAL_DIRS)) {
+  defineLazy(exportsObj, name, compute);
+}
+defineLazy(exportsObj, 'TEMPLATE_DIR', () => getTemplateDir());
+
+module.exports = exportsObj;

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** fcd717af
+**Generated:** 2026-10-25
+**Commit:** 1ab53eff
 **Branch:** main
-**Version:** 0.31.0.0
+**Version:** 0.31.2.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** fcd717af
+**Generated:** 2026-10-25
+**Commit:** 1ab53eff
 **Branch:** main
-**Version:** 0.31.0.0
+**Version:** 0.31.2.0
 
 ## OVERVIEW
 **Gate M** (incremental mutation testing) + **Gate M2** helpers (test-layer detection used by `src/mock-policy/`). Pre-push quality gate. TypeScript-only; uses Stryker.

package/mutation/__tests__/gremlins-runner.test.ts

@@ -106,7 +106,7 @@ describe('GremlinsRunner', () => {
 
   it('returns report=null (never throws) when the report lines are absent', async () => {
     let closeCb: ((code: number | null) => void) | undefined;
-    vi.mocked(spawn).mockReturnValue(mockChild({ stdout: () => {}, close: cb => { closeCb = cb; } }));
+    vi.mocked(spawn).mockReturnValue(mockChild({ stdout: () => { /* no output: the stub emits nothing on stdout */ }, close: cb => { closeCb = cb; } }));
 
     const runner = new GremlinsRunner();
     const promise = runner.run({ files: ['src/foo.py'], timeoutMs: 5000, cwd: '/tmp' });
@@ -136,7 +136,7 @@ describe('GremlinsRunner', () => {
 
   it('passes --gremlin-targets derived from the changed file directories', async () => {
     let closeCb: ((code: number | null) => void) | undefined;
-    vi.mocked(spawn).mockReturnValue(mockChild({ stdout: () => {}, close: cb => { closeCb = cb; } }));
+    vi.mocked(spawn).mockReturnValue(mockChild({ stdout: () => { /* no output: the stub emits nothing on stdout */ }, close: cb => { closeCb = cb; } }));
 
     const runner = new GremlinsRunner();
     const promise = runner.run({ files: ['src/foo/bar.py', 'src/baz.py'], timeoutMs: 5000, cwd: '/tmp' });
@@ -152,7 +152,7 @@ describe('GremlinsRunner', () => {
 
   it('reports timedOut when the child exceeds the deadline', async () => {
     let closeCb: ((code: number | null) => void) | undefined;
-    const child = mockChild({ stdout: () => {}, close: cb => { closeCb = cb; } });
+    const child = mockChild({ stdout: () => { /* no output: the stub emits nothing on stdout */ }, close: cb => { closeCb = cb; } });
     vi.mocked(spawn).mockReturnValue(child);
 
     const runner = new GremlinsRunner();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.31.0",
+  "version": "0.31.2",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "bin/xp-gate.js"

package/plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.31.0",
+  "version": "0.31.2",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. Includes 12 pre-commit gates (Gate 0-11), 8 pre-push gates, Sprint Flow (6 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/claude-code/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** fcd717af
+**Generated:** 2026-10-25
+**Commit:** 1ab53eff
 **Branch:** main
-**Version:** 0.31.0.0
+**Version:** 0.31.2.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/claude-code/skills/delphi-review/SKILL.md

@@ -392,6 +392,11 @@ delphi-review(
 )
 ```
 
+> **先确认该工具真的存在（#574）**：不是所有 DSH profile 都装了它。若当前会话的工具列表里
+> 没有 `delphi-review`，说明插件未安装 —— 此时**不要**推断"那就用 subagent / workflow 吧"。
+> 按下方【通道白名单】处理：要么装插件（`dsh plugin add @boyingliu01/dsh-plugin-xp-gate`），
+> 要么走 external 脚本路径，要么 BLOCK。
+
 该工具**直连外部 OpenAI 兼容网关**，每个席位绑定一个不同模型，因此不依赖宿主配置即可
 满足不变量。它复用**同一份** `.delphi-config.json`，无需额外配置。
 
@@ -431,6 +436,51 @@ delphi-review(
 - 降级证据落盘 `delphi-reviewed.json`：`channel`、`fallback_reason`（如 `dsh_subagent_model_selection_disabled`）、`probe_evidence`（①②③ 的实测摘录）。
 - 两通道同不变量：三专家齐全、`requested_model` 互异、consensus ≥90%、**无单专家路径**。
 - 可用性探测可用 `xp-gate doctor delphi` 复核（DSH 环境下含 `subagentModelSelection` 持久化设置检查）。
+
+##### 通道白名单（default-deny，#574）
+
+上面的双通道契约是**允许清单**，不是"除 subagent 外都能用"。**只有这两条通道合法**：
+`subagent`（native，需通过 ①②③）与 external（插件工具 / `delphi-external-review.cjs`）。
+
+**其余一切扇出机制一律禁止**，包括但不限于：
+
+| 禁止的通道 | 为什么禁止 |
+|---|---|
+| `workflow` 工具的 `agent()` 扇出 | `agent()` 的 `provider`/`model` **不受** `allowedModels` 约束（`dsh-workflow-ptc` 里没有任何白名单校验，直达 `subagents.start`）。脚本里写什么模型就真的跑什么模型。 |
+| 手写脚本 / 循环里逐个调 `subagent` 但省略 `model` | 缺 `model` 时子代理**静默继承宿主会话模型**，三席变一席。 |
+| Agent Teams / `spawn_teammate` | 团队成员模型不可逐条指定，且 `TeamMemberView.model` 是输出字段、可能是继承值。 |
+| 任何"从网关模型清单里挑三个"的做法 | 网关可能注册上百个模型，任意三个互异都满足旧不变量 —— 这正是 #574 的事故形态。 |
+
+**推荐通道不可用时，必须 BLOCK 并如实报告，不得自行选一条"看起来能跑"的路径。**
+判定句：*如果我正在用的派发机制不在上面两条之内，立即停止，输出 BLOCK 并说明缺什么。*
+
+##### 席位解析（派发前强制步骤，#574）
+
+模型 ID **只能来自 `.delphi-config.json`**，不得来自会话默认模型、网关模型清单、
+记忆、或上一次评审的残留。派发前依次执行：
+
+1. 读取 `<项目根>/.delphi-config.json`，取 `active_profile` 指向的 profile。
+   （查找顺序：项目根 → `~/.config/xp-gate/.delphi-config.json`；多份存在时以项目根为准。）
+2. 解出 `architecture` / `technical` / `feasibility` 三个席位的 `model`，**去空白**。
+3. **原样打印**这三个 ID 与 `active_profile`，作为本轮派发的凭据。
+4. 只用这三个字面量派发；脚本里**不得出现配置中不存在的模型 ID**。
+5. 三席位必须互异 —— 若配置本身有重复，这是配置错误，BLOCK，不要去"挑一个换掉"。
+
+> 反例（2026-10-22 实测事故）：某次 code-walkthrough 的 workflow 脚本硬编码了
+> `s-deepseek-v4.1-flash` / `g-deepseek-v4-pro` / `doubao-seed-2.0-pro`，
+> 而配置写的是三个 `local-*` 免费席位。三者互异、评审"成功"、Gate MW 判 APPROVED，
+> 但付费模型被真实调用，而 `local-*` 只落了 1/3。16 次 workflow 运行中读取配置的次数为 **0**。
+
+##### 执行后核验（#574）
+
+评审结束后必须逐席位核对**实际解析到的模型**，不能只看请求值：
+
+- 证据来源：子会话的 `request/header`（平台日志）或 external 脚本的回执 `resolved_model`。
+- 三席 `requested_model` 必须**逐一等于**配置中同角色的席位（按角色对应，不是"三者在集合里"）。
+- 任一不匹配 → 本次评审**作废**，不得写入 `.code-walkthrough-result.json`，按 BLOCK 处理。
+- Gate MW 会独立复核这一点（#574）：存在 `.delphi-config.json` 时，
+  证据里每个 `requested_model` 必须等于该角色的配置席位，否则 pre-push 直接 BLOCK。
+
 #### WorkBuddy 平台（Expert 团队模式）
 
 WorkBuddy 侧以 Team 型专家团（示例：`delphi-review-team`，安装在 `~/.workbuddy/plugins/marketplaces/my-experts/plugins/`，创建方式见 [docs/platform-workbuddy.md](../../docs/platform-workbuddy.md)）承载评审，触发本技能后按此路由执行：

package/plugins/claude-code/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** fcd717af
+**Generated:** 2026-10-25
+**Commit:** 1ab53eff
 **Branch:** main
-**Version:** 0.31.0.0
+**Version:** 0.31.2.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/claude-code/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** fcd717af
+**Generated:** 2026-10-25
+**Commit:** 1ab53eff
 **Branch:** main
-**Version:** 0.31.0.0
+**Version:** 0.31.2.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/dsh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/dsh-plugin-xp-gate",
-  "version": "0.31.0",
+  "version": "0.31.2",
   "description": "XP-Gate deterministic quality gates + AI workflow skills as a DeepSeek Harness (DSH) native plugin: gate-check / gate-principles / gate-arch tools + 12 SKILL.md skills",
   "type": "module",
   "main": "./lib/index.js",

package/plugins/dsh/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** fcd717af
+**Generated:** 2026-10-25
+**Commit:** 1ab53eff
 **Branch:** main
-**Version:** 0.31.0.0
+**Version:** 0.31.2.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/dsh/skills/delphi-review/SKILL.md

@@ -392,6 +392,11 @@ delphi-review(
 )
 ```
 
+> **先确认该工具真的存在（#574）**：不是所有 DSH profile 都装了它。若当前会话的工具列表里
+> 没有 `delphi-review`，说明插件未安装 —— 此时**不要**推断"那就用 subagent / workflow 吧"。
+> 按下方【通道白名单】处理：要么装插件（`dsh plugin add @boyingliu01/dsh-plugin-xp-gate`），
+> 要么走 external 脚本路径，要么 BLOCK。
+
 该工具**直连外部 OpenAI 兼容网关**，每个席位绑定一个不同模型，因此不依赖宿主配置即可
 满足不变量。它复用**同一份** `.delphi-config.json`，无需额外配置。
 
@@ -431,6 +436,51 @@ delphi-review(
 - 降级证据落盘 `delphi-reviewed.json`：`channel`、`fallback_reason`（如 `dsh_subagent_model_selection_disabled`）、`probe_evidence`（①②③ 的实测摘录）。
 - 两通道同不变量：三专家齐全、`requested_model` 互异、consensus ≥90%、**无单专家路径**。
 - 可用性探测可用 `xp-gate doctor delphi` 复核（DSH 环境下含 `subagentModelSelection` 持久化设置检查）。
+
+##### 通道白名单（default-deny，#574）
+
+上面的双通道契约是**允许清单**，不是"除 subagent 外都能用"。**只有这两条通道合法**：
+`subagent`（native，需通过 ①②③）与 external（插件工具 / `delphi-external-review.cjs`）。
+
+**其余一切扇出机制一律禁止**，包括但不限于：
+
+| 禁止的通道 | 为什么禁止 |
+|---|---|
+| `workflow` 工具的 `agent()` 扇出 | `agent()` 的 `provider`/`model` **不受** `allowedModels` 约束（`dsh-workflow-ptc` 里没有任何白名单校验，直达 `subagents.start`）。脚本里写什么模型就真的跑什么模型。 |
+| 手写脚本 / 循环里逐个调 `subagent` 但省略 `model` | 缺 `model` 时子代理**静默继承宿主会话模型**，三席变一席。 |
+| Agent Teams / `spawn_teammate` | 团队成员模型不可逐条指定，且 `TeamMemberView.model` 是输出字段、可能是继承值。 |
+| 任何"从网关模型清单里挑三个"的做法 | 网关可能注册上百个模型，任意三个互异都满足旧不变量 —— 这正是 #574 的事故形态。 |
+
+**推荐通道不可用时，必须 BLOCK 并如实报告，不得自行选一条"看起来能跑"的路径。**
+判定句：*如果我正在用的派发机制不在上面两条之内，立即停止，输出 BLOCK 并说明缺什么。*
+
+##### 席位解析（派发前强制步骤，#574）
+
+模型 ID **只能来自 `.delphi-config.json`**，不得来自会话默认模型、网关模型清单、
+记忆、或上一次评审的残留。派发前依次执行：
+
+1. 读取 `<项目根>/.delphi-config.json`，取 `active_profile` 指向的 profile。
+   （查找顺序：项目根 → `~/.config/xp-gate/.delphi-config.json`；多份存在时以项目根为准。）
+2. 解出 `architecture` / `technical` / `feasibility` 三个席位的 `model`，**去空白**。
+3. **原样打印**这三个 ID 与 `active_profile`，作为本轮派发的凭据。
+4. 只用这三个字面量派发；脚本里**不得出现配置中不存在的模型 ID**。
+5. 三席位必须互异 —— 若配置本身有重复，这是配置错误，BLOCK，不要去"挑一个换掉"。
+
+> 反例（2026-10-22 实测事故）：某次 code-walkthrough 的 workflow 脚本硬编码了
+> `s-deepseek-v4.1-flash` / `g-deepseek-v4-pro` / `doubao-seed-2.0-pro`，
+> 而配置写的是三个 `local-*` 免费席位。三者互异、评审"成功"、Gate MW 判 APPROVED，
+> 但付费模型被真实调用，而 `local-*` 只落了 1/3。16 次 workflow 运行中读取配置的次数为 **0**。
+
+##### 执行后核验（#574）
+
+评审结束后必须逐席位核对**实际解析到的模型**，不能只看请求值：
+
+- 证据来源：子会话的 `request/header`（平台日志）或 external 脚本的回执 `resolved_model`。
+- 三席 `requested_model` 必须**逐一等于**配置中同角色的席位（按角色对应，不是"三者在集合里"）。
+- 任一不匹配 → 本次评审**作废**，不得写入 `.code-walkthrough-result.json`，按 BLOCK 处理。
+- Gate MW 会独立复核这一点（#574）：存在 `.delphi-config.json` 时，
+  证据里每个 `requested_model` 必须等于该角色的配置席位，否则 pre-push 直接 BLOCK。
+
 #### WorkBuddy 平台（Expert 团队模式）
 
 WorkBuddy 侧以 Team 型专家团（示例：`delphi-review-team`，安装在 `~/.workbuddy/plugins/marketplaces/my-experts/plugins/`，创建方式见 [docs/platform-workbuddy.md](../../docs/platform-workbuddy.md)）承载评审，触发本技能后按此路由执行：

package/plugins/dsh/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** fcd717af
+**Generated:** 2026-10-25
+**Commit:** 1ab53eff
 **Branch:** main
-**Version:** 0.31.0.0
+**Version:** 0.31.2.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/dsh/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-22
-**Commit:** fcd717af
+**Generated:** 2026-10-25
+**Commit:** 1ab53eff
 **Branch:** main
-**Version:** 0.31.0.0
+**Version:** 0.31.2.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/dsh/src/delphi-config-env-diagnostics.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect } from "vitest"
+import { DelphiSetupError, expandEnv, expandEnvDetailed, resolveConfig } from "./delphi-config.js"
+
+/**
+ * @test REQ-DSH-016
+ * @intent #576：「变量未设置」和「变量已设置为空串」以及「变量已设置但当前进程没有
+ *         继承到」在旧实现里被渲染成同一句 `is not set in the environment`。
+ *         第一句是事实错误，第二句丢掉了最常见的真实原因（宿主进程环境陈旧），
+ *         把排查引向 key 本身、配置写法、网关权限——唯独不会想到重启宿主。
+ *
+ *         这组用例要求 expandEnv 不丢失这一区分，并要求报错文案把已知事实全部
+ *         说出来：变量名、占位符形状、以及 env 中是否存在大小写不同的同名变量
+ *         （Windows 环境变量大小写不敏感，POSIX 敏感——这是真实的平台差异）。
+ *
+ *         旁路探测（读取注册表 / shell 启动文件）只能作为可选诊断：探测本身
+ *         出错必须静默降级为现有文案，绝不能让诊断成为新的失败点。
+ * @covers AC-DSH-016-04
+ */
+
+const baseConfig = {
+  active_profile: "whalecloud",
+  profiles: {
+    whalecloud: {
+      provider: "whalecloud",
+      providers: {
+        whalecloud: {
+          base_url: "https://lab.example.com/gpt-proxy",
+          api_key: "${WHALECLOUD_API_KEY}",
+        },
+      },
+      experts: [
+        { id: "Expert A", role: "architecture", model: "g-glm-5.3-flash", max_tokens: 32000 },
+        { id: "Expert B", role: "technical", model: "g-qwen3.8-flash" },
+        { id: "Expert C", role: "feasibility", model: "g-deepseek-flash" },
+      ],
+      consensus: { threshold_percent: 90, max_review_rounds: 5 },
+    },
+  },
+}
+
+const configWith = (apiKey: string) => ({
+  ...baseConfig,
+  profiles: {
+    whalecloud: {
+      ...baseConfig.profiles.whalecloud,
+      providers: {
+        whalecloud: {
+          base_url: "https://lab.example.com/gpt-proxy",
+          api_key: apiKey,
+        },
+      },
+    },
+  },
+})
+
+/** Capture the error message a resolve call produces, or "" if it did not throw. */
+function messageFrom(apiKey: string, env: Record<string, string>): string {
+  try {
+    resolveConfig(configWith(apiKey), env)
+    return ""
+  } catch (error) {
+    return error instanceof DelphiSetupError ? error.message : `NOT-A-SETUP-ERROR: ${String(error)}`
+  }
+}
+
+describe("expandEnvDetailed keeps the three outcomes apart (#576)", () => {
+  it("anti-vacuity: the detailed form exists and expands a present variable", () => {
+    // If this fails, every case below would pass against a stub.
+    const result = expandEnvDetailed("Bearer ${TOK}!", { TOK: "secret" })
+    expect(result.value).toBe("Bearer secret!")
+    expect(result.missing).toEqual([])
+    expect(result.empty).toEqual([])
+  })
+
+  it("reports a variable that the environment does not define as missing", () => {
+    const result = expandEnvDetailed("${NOPE}", {})
+    expect(result.value).toBe("")
+    expect(result.missing).toEqual(["NOPE"])
+    expect(result.empty).toEqual([])
+  })
+
+  it("reports a variable that is defined but empty as empty, not missing", () => {
+    // "" is a CONFIGURATION error (someone set it wrong). Absent is an
+    // ENVIRONMENT error (nobody set it). Conflating them sends the reader to the
+    // wrong file (#576).
+    const result = expandEnvDetailed("${TOK}", { TOK: "" })
+    expect(result.value).toBe("")
+    expect(result.missing).toEqual([])
+    expect(result.empty).toEqual(["TOK"])
+  })
+
+  it("handles both placeholder spellings in one value", () => {
+    const result = expandEnvDetailed("{env:A}-${B}-${C}", { A: "x", B: "" })
+    expect(result.value).toBe("x--")
+    expect(result.missing).toEqual(["C"])
+    expect(result.empty).toEqual(["B"])
+  })
+
+  it("does not repeat a variable referenced twice", () => {
+    const result = expandEnvDetailed("${DUP}${DUP}", {})
+    expect(result.missing).toEqual(["DUP"])
+  })
+
+  it("expandEnv still returns just the string for existing callers", () => {
+    expect(expandEnv("${NOPE}", {})).toBe("")
+    expect(expandEnv("${TOK}", { TOK: "v" })).toBe("v")
+  })
+})
+
+describe("the missing-key message names the actual situation (#576)", () => {
+  it("says the variable is not set when it is absent", () => {
+    const message = messageFrom("${WHALECLOUD_API_KEY}", {})
+    expect(message).toContain("WHALECLOUD_API_KEY")
+    expect(message).toMatch(/not set/i)
+    // The remedy has to be reachable from the message alone.
+    expect(message).toMatch(/set|export|environment/i)
+  })
+
+  it("does NOT claim the variable is unset when it is set to an empty string", () => {
+    const message = messageFrom("${WHALECLOUD_API_KEY}", { WHALECLOUD_API_KEY: "" })
+    expect(message).toContain("WHALECLOUD_API_KEY")
+    // The false statement this issue is about.
+    expect(message).not.toMatch(/is not set in the environment/i)
+    expect(message).toMatch(/empty/i)
+  })
+
+  it("names the placeholder spelling used in the config", () => {
+    // Which spelling appears in the config is the first thing a reader needs:
+    // `${VAR}` and `{env:VAR}` expand through different code paths, and a typo
+    // in the spelling looks exactly like an unset variable.
+    expect(messageFrom("${WHALECLOUD_API_KEY}", {})).toMatch(/\$\{WHALECLOUD_API_KEY\}/)
+    expect(messageFrom("{env:WHALECLOUD_API_KEY}", {})).toContain("{env:WHALECLOUD_API_KEY}")
+  })
+
+  it("points at a same-name variable whose case differs", () => {
+    // Windows env vars are case-insensitive but a POSIX shell's are not, so a
+    // value can be present under a different case and silently not match. The
+    // message must surface the near-miss instead of reporting "not set".
+    const message = messageFrom("${WHALECLOUD_API_KEY}", { whalecloud_api_key: "k" })
+    expect(message).toContain("whalecloud_api_key")
+    expect(message).toMatch(/case/i)
+  })
+
+  it("says nothing about case when there is no near-miss", () => {
+    const message = messageFrom("${WHALECLOUD_API_KEY}", { OTHER: "x" })
+    expect(message).not.toMatch(/case/i)
+  })
+
+  it("never echoes a literal api_key that is present", () => {
+    // A literal key in the config is valid and resolves; it must not appear in
+    // any diagnostic produced for OTHER providers.
+    const secret = "sk-live-DO-NOT-LEAK-42"
+    const config = {
+      ...baseConfig,
+      profiles: {
+        whalecloud: {
+          ...baseConfig.profiles.whalecloud,
+          providers: {
+            // Declared first so a later failure has already seen this value.
+            literal: { base_url: "https://literal.example.com", api_key: secret },
+            whalecloud: { base_url: "https://lab.example.com/gpt-proxy", api_key: "${WHALECLOUD_API_KEY}" },
+          },
+        },
+      },
+    }
+    let message = ""
+    try {
+      resolveConfig(config, {})
+    } catch (error) {
+      message = String(error)
+    }
+    expect(message).toContain("WHALECLOUD_API_KEY")
+    expect(message).not.toContain(secret)
+  })
+
+  it("names the literal-value case when api_key is an empty literal", () => {
+    // `api_key: ""` references no variable, so no variable should be blamed.
+    const message = messageFrom("", {})
+    expect(message).toMatch(/no api_key/i)
+    expect(message).not.toMatch(/WHALECLOUD_API_KEY/)
+  })
+
+  it("a provider with no api_key at all keeps its direct message", () => {
+    const message = messageFrom("", {})
+    expect(message).toMatch(/no api_key/i)
+  })
+
+  it("the diagnostic never turns into a failure of its own", () => {
+    // A hostile/odd environment must degrade to a plain message, not throw
+    // something that is not a DelphiSetupError.
+    const weird = new Proxy(
+      {},
+      {
+        get() {
+          throw new Error("environment read exploded")
+        },
+        ownKeys() {
+          throw new Error("environment enumeration exploded")
+        },
+      },
+    ) as unknown as NodeJS.ProcessEnv
+    let thrown: unknown
+    try {
+      resolveConfig(baseConfig, weird)
+    } catch (error) {
+      thrown = error
+    }
+    expect(thrown).toBeInstanceOf(DelphiSetupError)
+  })
+})