@boyingliu01/xp-gate 0.23.0 → 0.24.0

package/bin/xp-gate.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 const path = require('path');
 const { init } = require('../lib/init.js');
+const { delphiSetup } = require('../lib/delphi-setup.js');
 const { installSkill } = require('../lib/install-skill.js');
 const { updateSkill } = require('../lib/update-skill.js');
 const { uninstallSkill } = require('../lib/uninstall-skill.js');
@@ -80,6 +81,11 @@ const COMMANDS = {
     run: () => init(['--global']).then(code => process.exit(code)),
     usage: 'xp-gate setup-global'
   },
+  'delphi-setup': {
+    description: 'Rebind the three Qoder Delphi expert agents to distinct built-in models (#414)',
+    run: subargs => delphiSetup(subargs).then(code => process.exit(code)),
+    usage: 'xp-gate delphi-setup --model architecture=<id> --model technical=<id> --model feasibility=<id> [--global|--local --project <dir>]'
+  },
   'install-skill': {
     description: 'Install a xp-gate skill from the package bundle',
     run: subargs => {
@@ -139,7 +145,15 @@ const COMMANDS = {
   },
   'doctor': {
     description: 'Diagnose xp-gate installation health',
-    run: subargs => doctor(subargs).then(code => process.exit(code)),
+    run: subargs => {
+      // `xp-gate doctor delphi` is a dedicated chain diagnosis (#414 REQ-3),
+      // not a flag of the generic doctor run.
+      if (subargs[0] === 'delphi') {
+        const { doctorDelphi } = require('../lib/doctor.js');
+        return doctorDelphi({}).then(code => process.exit(code));
+      }
+      return doctor(subargs).then(code => process.exit(code));
+    },
     usage: 'xp-gate doctor [--fix [--install-tools] | --sync-hooks [--force]] | --json | --format json  (the two machine-readable modes print one JSON document and refuse --fix/--sync-hooks)'
   },
   'ui-review': {

package/lib/__tests__/delphi-setup.test.js

@@ -0,0 +1,203 @@
+/**
+ * @test delphi-setup
+ * @intent Guard #414 REQ-4: `xp-gate delphi-setup` is the repair path for
+ * drifted Qoder agent bindings. `xp-gate init` deliberately never overwrites
+ * an existing agent file, so a stale binding could previously never be fixed
+ * without hand-editing. delphi-setup must write three distinct, quoted model
+ * bindings, refuse duplicates and junk, and always demand an IDE reload —
+ * Qoder caches agent definitions at session start, so a skipped reload looks
+ * exactly like a fix that did not work.
+ */
+const fs = require('fs');
+const path = require('path');
+const { resetLibModules, muteConsole, makeTempDirs, removeTempDirs } = require('./helpers/lib-sandbox.cjs');
+
+const LIB_MODULES = ['../init', '../detect-deps.js', '../shared-paths', '../delphi-setup'].map(name => require.resolve(name));
+
+function repoRoot() {
+  return path.join(__dirname, '..', '..', '..', '..');
+}
+
+describe('delphi-setup (#414 REQ-4)', () => {
+  let tmpDirs;
+  let tmpHome;
+  let originalHome;
+
+  beforeEach(() => {
+    tmpDirs = makeTempDirs(['delphi-setup-home']);
+    tmpHome = tmpDirs['delphi-setup-home'];
+    originalHome = process.env.HOME;
+    process.env.HOME = tmpHome;
+    fs.mkdirSync(path.join(tmpHome, '.qoder'), { recursive: true });
+    resetLibModules(vi, LIB_MODULES);
+    muteConsole(vi);
+  });
+
+  afterEach(() => {
+    if (originalHome === undefined) delete process.env.HOME; else process.env.HOME = originalHome;
+    removeTempDirs(tmpDirs);
+    vi.restoreAllMocks();
+  });
+
+  function agentsDir() {
+    return path.join(tmpHome, '.qoder', 'agents');
+  }
+
+  it('writes three agent files with the requested distinct bindings', async () => {
+    const { delphiSetup } = require('../delphi-setup');
+    const code = await delphiSetup([
+      '--model', 'architecture=qwen-max',
+      '--model', 'technical=deepseek-v3.2',
+      '--model', 'feasibility=glm-5.2',
+    ]);
+    expect(code).toBe(0);
+    const { readQoderModelId } = require('../init');
+    expect(readQoderModelId(path.join(agentsDir(), 'delphi-architecture.md'))).toBe('qwen-max');
+    expect(readQoderModelId(path.join(agentsDir(), 'delphi-technical.md'))).toBe('deepseek-v3.2');
+    expect(readQoderModelId(path.join(agentsDir(), 'delphi-feasibility.md'))).toBe('glm-5.2');
+  });
+
+  it('preserves the rest of the bundled template body when rebinding', async () => {
+    const { delphiSetup } = require('../delphi-setup');
+    await delphiSetup([
+      '--model', 'architecture=qwen-max',
+      '--model', 'technical=deepseek-v3.2',
+      '--model', 'feasibility=glm-5.2',
+    ]);
+    const body = fs.readFileSync(path.join(agentsDir(), 'delphi-architecture.md'), 'utf8');
+    const shippedBody = fs.readFileSync(path.join(repoRoot(), 'plugins', 'qoder', 'agents', 'delphi-architecture.md'), 'utf8');
+    // The name line is template identity; only the binding may change.
+    expect(body).toMatch(/^name: delphi-architecture$/m);
+    expect(body).not.toBe('');
+    expect(shippedBody).toMatch(/^name: delphi-architecture$/m);
+  });
+
+  it('repairs a stale binding by overwriting it (this is the point of the command)', async () => {
+    const { delphiSetup } = require('../delphi-setup');
+    fs.mkdirSync(agentsDir(), { recursive: true });
+    fs.writeFileSync(
+      path.join(agentsDir(), 'delphi-architecture.md'),
+      '---\nname: delphi-architecture\nmodel: "[Retired-Model](dead-model-id)"\n---\n# body\n',
+    );
+    const code = await delphiSetup([
+      '--model', 'architecture=qwen-max',
+      '--model', 'technical=deepseek-v3.2',
+      '--model', 'feasibility=glm-5.2',
+    ]);
+    expect(code).toBe(0);
+    const { readQoderModelId } = require('../init');
+    expect(readQoderModelId(path.join(agentsDir(), 'delphi-architecture.md'))).toBe('qwen-max');
+  });
+
+  // R1 FC-04: a repair without a rollback is a second way to lose a working
+  // binding — existing files are backed up before the first write.
+  it('backs up existing agent files before overwriting them', async () => {
+    const { delphiSetup } = require('../delphi-setup');
+    fs.mkdirSync(agentsDir(), { recursive: true });
+    const staleBody = '---\nname: delphi-architecture\nmodel: "[Retired-Model](dead-model-id)"\n---\n# body\n';
+    fs.writeFileSync(path.join(agentsDir(), 'delphi-architecture.md'), staleBody);
+    const code = await delphiSetup([
+      '--model', 'architecture=qwen-max',
+      '--model', 'technical=deepseek-v3.2',
+      '--model', 'feasibility=glm-5.2',
+    ]);
+    expect(code).toBe(0);
+    // Some backup copy of the stale file must exist somewhere under the
+    // sandbox HOME config dir; the exact timestamped dir is intentional.
+    const backupRoot = path.join(tmpHome, '.config', 'xp-gate', 'backup');
+    const found = (function find(dir) {
+      for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        const p = path.join(dir, e.name);
+        if (e.isDirectory()) {
+          const hit = find(p);
+          if (hit) return hit;
+        } else if (e.name === 'delphi-architecture.md') {
+          return p;
+        }
+      }
+      return null;
+    })(backupRoot);
+    expect(found).not.toBeNull();
+    expect(fs.readFileSync(found, 'utf8')).toBe(staleBody);
+  });
+
+  // R1 MN-05: a BOM in front of '---' must not read as a missing frontmatter.
+  it('rebinds a template carrying a UTF-8 BOM', async () => {
+    const { delphiSetup } = require('../delphi-setup');
+    fs.mkdirSync(agentsDir(), { recursive: true });
+    fs.writeFileSync(
+      path.join(agentsDir(), 'delphi-architecture.md'),
+      '\uFEFF---\nname: delphi-architecture\nmodel: "[Old](old-id)"\n---\n# body\n',
+    );
+    const code = await delphiSetup([
+      '--model', 'architecture=qwen-max',
+      '--model', 'technical=deepseek-v3.2',
+      '--model', 'feasibility=glm-5.2',
+    ]);
+    expect(code).toBe(0);
+    const { readQoderModelId } = require('../init');
+    expect(readQoderModelId(path.join(agentsDir(), 'delphi-architecture.md'))).toBe('qwen-max');
+  });
+
+  it('rejects duplicate model IDs — three distinct models are the invariant being set up', async () => {
+    const { delphiSetup } = require('../delphi-setup');
+    const code = await delphiSetup([
+      '--model', 'architecture=same-model',
+      '--model', 'technical=same-model',
+      '--model', 'feasibility=other',
+    ]);
+    expect(code).toBe(1);
+    expect(fs.existsSync(agentsDir())).toBe(false);
+  });
+
+  it('rejects an unknown role and a bare model id without a role=', async () => {
+    const { delphiSetup } = require('../delphi-setup');
+    expect(await delphiSetup(['--model', 'critic=x'])).toBe(1);
+    expect(await delphiSetup(['--model', 'just-a-model'])).toBe(1);
+    expect(fs.existsSync(agentsDir())).toBe(false);
+  });
+
+  it('rejects a model id outside the platform binding charset', async () => {
+    const { delphiSetup } = require('../delphi-setup');
+    const code = await delphiSetup([
+      '--model', 'architecture=has space',
+      '--model', 'technical=deepseek-v3.2',
+      '--model', 'feasibility=glm-5.2',
+    ]);
+    expect(code).toBe(1);
+    expect(fs.existsSync(agentsDir())).toBe(false);
+  });
+
+  it('demands an IDE reload on success — the registry only loads at session start', async () => {
+    const { delphiSetup } = require('../delphi-setup');
+    const logs = [];
+    const logSpy = vi.spyOn(console, 'log').mockImplementation((...args) => logs.push(args.join(' ')));
+    await delphiSetup([
+      '--model', 'architecture=qwen-max',
+      '--model', 'technical=deepseek-v3.2',
+      '--model', 'feasibility=glm-5.2',
+    ]);
+    logSpy.mockRestore();
+    const out = logs.join('\n');
+    expect(out).toMatch(/重载|reload|新会话|restart/i);
+  });
+
+  it('--local --project targets the project .qoder/agents instead of HOME', async () => {
+    const { delphiSetup } = require('../delphi-setup');
+    const projectDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'delphi-setup-proj-'));
+    try {
+      const code = await delphiSetup([
+        '--local', '--project', projectDir,
+        '--model', 'architecture=qwen-max',
+        '--model', 'technical=deepseek-v3.2',
+        '--model', 'feasibility=glm-5.2',
+      ]);
+      expect(code).toBe(0);
+      const { readQoderModelId } = require('../init');
+      expect(readQoderModelId(path.join(projectDir, '.qoder', 'agents', 'delphi-architecture.md'))).toBe('qwen-max');
+      expect(fs.existsSync(path.join(tmpHome, '.qoder', 'agents'))).toBe(false);
+    } finally {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+});

package/lib/__tests__/doctor-delphi.test.js

@@ -0,0 +1,244 @@
+/**
+ * @test doctor-delphi
+ * @intent Guard #414 REQ-3/REQ-6: `xp-gate doctor delphi` turns the failure
+ * modes measured on real machines into diagnosable checks — drifted agent
+ * bindings (B2), a skill install that silently lagged the published package
+ * (B4), a runner script nobody can find (B3), and a config that cannot serve
+ * three distinct models. Every check must be assertable in isolation, and the
+ * npm-latest probe must be skippable so the doctor never needs the network.
+ */
+const fs = require('fs');
+const path = require('path');
+const { resetLibModules, muteConsole, makeTempDirs, removeTempDirs } = require('./helpers/lib-sandbox.cjs');
+
+const LIB_MODULES = ['../init', '../detect-deps.js', '../shared-paths', '../doctor', '../delphi-setup'].map(name => require.resolve(name));
+
+function repoRoot() {
+  return path.join(__dirname, '..', '..', '..', '..');
+}
+
+function bundledSkillDir() {
+  return path.join(repoRoot(), 'src', 'npm-package', 'skills', 'delphi-review');
+}
+
+describe('doctor delphi (#414 REQ-3/REQ-6)', () => {
+  let tmpDirs;
+  let tmpHome;
+  let originalHome;
+
+  beforeEach(() => {
+    tmpDirs = makeTempDirs(['doctor-delphi-home']);
+    tmpHome = tmpDirs['doctor-delphi-home'];
+    originalHome = process.env.HOME;
+    process.env.HOME = tmpHome;
+    fs.mkdirSync(path.join(tmpHome, '.qoder'), { recursive: true });
+    resetLibModules(vi, LIB_MODULES);
+    muteConsole(vi);
+  });
+
+  afterEach(() => {
+    if (originalHome === undefined) delete process.env.HOME; else process.env.HOME = originalHome;
+    removeTempDirs(tmpDirs);
+    vi.restoreAllMocks();
+  });
+
+  function healthyHome() {
+    // A home that would pass the agent + skill-parity checks.
+    fs.mkdirSync(path.join(tmpHome, '.qoder', 'agents'), { recursive: true });
+    fs.mkdirSync(path.join(tmpHome, '.qoder', 'skills', 'delphi-review'), { recursive: true });
+    for (const role of ['architecture', 'technical', 'feasibility']) {
+      fs.copyFileSync(
+        path.join(repoRoot(), 'plugins', 'qoder', 'agents', `delphi-${role}.md`),
+        path.join(tmpHome, '.qoder', 'agents', `delphi-${role}.md`),
+      );
+    }
+    for (const f of fs.readdirSync(bundledSkillDir(), { withFileTypes: true })) {
+      const dest = path.join(tmpHome, '.qoder', 'skills', 'delphi-review', f.name);
+      if (f.isDirectory()) {
+        fs.mkdirSync(dest, { recursive: true });
+        for (const inner of fs.readdirSync(path.join(bundledSkillDir(), f.name))) {
+          if (fs.statSync(path.join(bundledSkillDir(), f.name, inner)).isFile()) {
+            fs.copyFileSync(path.join(bundledSkillDir(), f.name, inner), path.join(dest, inner));
+          }
+        }
+      } else if (f.isFile()) {
+        fs.copyFileSync(path.join(bundledSkillDir(), f.name), dest);
+      }
+    }
+  }
+
+  function writeConfig(configPath) {
+    fs.writeFileSync(configPath, JSON.stringify({
+      active_profile: 'default',
+      profiles: {
+        default: {
+          providers: {
+            gw: { base_url: 'https://gw.example/v1', api_key: 'k' },
+          },
+          experts: {
+            architecture: { provider: 'gw', model: 'model-a' },
+            technical: { provider: 'gw', model: 'model-b' },
+            feasibility: { provider: 'gw', model: 'model-c' },
+          },
+        },
+      },
+    }));
+    return configPath;
+  }
+
+  it('a fully healthy environment PASSes every check and exits 0', async () => {
+    healthyHome();
+    const { doctorDelphi } = require('../doctor');
+    const configPath = writeConfig(path.join(tmpDirs['doctor-delphi-home'], '.delphi-config.json'));
+    const localVersion = require('../../package.json').version;
+    const code = await doctorDelphi({ projectDir: tmpHome, configPath, npmLatest: localVersion });
+    expect(code).toBe(0);
+  });
+
+  it('a stale agent binding FAILs and names delphi-setup as the repair path', async () => {
+    healthyHome();
+    fs.writeFileSync(
+      path.join(tmpHome, '.qoder', 'agents', 'delphi-technical.md'),
+      '---\nname: delphi-technical\nmodel: "[Retired](retired-id)"\n---\n# body\n',
+    );
+    const { doctorDelphi } = require('../doctor');
+    const code = await doctorDelphi({ projectDir: tmpHome, configPath: path.join(tmpHome, 'absent.json'), npmLatest: null });
+    expect(code).toBe(1);
+  });
+
+  it('a skill install that drifted from the bundled copy FAILs with a reinstall hint', async () => {
+    healthyHome();
+    const installed = path.join(tmpHome, '.qoder', 'skills', 'delphi-review', 'SKILL.md');
+    fs.appendFileSync(installed, '\ndrifted line\n');
+    const logs = [];
+    const logSpy = vi.spyOn(console, 'log').mockImplementation((...args) => logs.push(args.join(' ')));
+    const { doctorDelphi } = require('../doctor');
+    await doctorDelphi({ projectDir: tmpHome, configPath: path.join(tmpHome, 'absent.json'), npmLatest: null });
+    logSpy.mockRestore();
+    expect(logs.join('\n')).toMatch(/install-skill|reinstall/i);
+  });
+
+  it('a duplicate-model config FAILs instead of promising a review that will BLOCK', async () => {
+    healthyHome();
+    const configPath = path.join(tmpHome, '.delphi-config.json');
+    fs.writeFileSync(configPath, JSON.stringify({
+      active_profile: 'default',
+      profiles: {
+        default: {
+          providers: { gw: { base_url: 'https://gw.example/v1', api_key: 'k' } },
+          experts: {
+            architecture: { provider: 'gw', model: 'same' },
+            technical: { provider: 'gw', model: 'same' },
+            feasibility: { provider: 'gw', model: 'model-c' },
+          },
+        },
+      },
+    }));
+    const { doctorDelphi } = require('../doctor');
+    const code = await doctorDelphi({ projectDir: tmpHome, configPath, npmLatest: null });
+    expect(code).toBe(1);
+  });
+
+  it('a missing config FAILs with the copy-the-example hint', async () => {
+    healthyHome();
+    const logs = [];
+    const logSpy = vi.spyOn(console, 'log').mockImplementation((...args) => logs.push(args.join(' ')));
+    const { doctorDelphi } = require('../doctor');
+    await doctorDelphi({ projectDir: tmpHome, configPath: path.join(tmpHome, 'absent.json'), npmLatest: null });
+    logSpy.mockRestore();
+    expect(logs.join('\n')).toMatch(/\.delphi-config\.json/);
+  });
+
+  it('npmLatest=null skips the version check without failing the run', async () => {
+    healthyHome();
+    const { doctorDelphi } = require('../doctor');
+    const configPath = writeConfig(path.join(tmpHome, '.delphi-config.json'));
+    const code = await doctorDelphi({ projectDir: tmpHome, configPath, npmLatest: null });
+    expect(code).toBe(0);
+  });
+
+  // R1 FC-07: the switch shipping off is the platform default, not a defect —
+  // only enabled-but-underprovisioned is a real FAIL.
+  it('DSH with subagentModelSelection absent is SKIP, not FAIL', async () => {
+    healthyHome();
+    fs.mkdirSync(path.join(tmpHome, '.dsh'), { recursive: true });
+    fs.writeFileSync(path.join(tmpHome, '.dsh', 'settings.json'), JSON.stringify({ other: true }));
+    const { doctorDelphi } = require('../doctor');
+    const configPath = writeConfig(path.join(tmpHome, '.delphi-config.json'));
+    const code = await doctorDelphi({ projectDir: tmpHome, configPath, npmLatest: null });
+    expect(code).toBe(0);
+  });
+
+  // R1 FC-09: a project-level agent set (delphi-setup --local --project) is
+  // what the doctor reads, so the repair loop closes.
+  it('a complete project-level agent set takes precedence over the HOME set', async () => {
+    healthyHome();
+    const projDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'doctor-delphi-proj-'));
+    try {
+      fs.mkdirSync(path.join(projDir, '.qoder', 'agents'), { recursive: true });
+      for (const role of ['architecture', 'technical', 'feasibility']) {
+        fs.copyFileSync(
+          path.join(repoRoot(), 'plugins', 'qoder', 'agents', `delphi-${role}.md`),
+          path.join(projDir, '.qoder', 'agents', `delphi-${role}.md`),
+        );
+      }
+      // Corrupt the HOME set; the project set must win and the run stays green.
+      fs.writeFileSync(
+        path.join(tmpHome, '.qoder', 'agents', 'delphi-technical.md'),
+        '---\nname: delphi-technical\nmodel: "[Retired](retired-id)"\n---\n# body\n',
+      );
+      const { doctorDelphi } = require('../doctor');
+      const configPath = writeConfig(path.join(tmpHome, '.delphi-config.json'));
+      const code = await doctorDelphi({
+        projectDir: projDir, configPath, npmLatest: null,
+      });
+      expect(code).toBe(0);
+    } finally {
+      fs.rmSync(projDir, { recursive: true, force: true });
+    }
+  });
+
+  // R1 MI-03: parity covers the whole bundled file set, so a stale references/
+  // copy cannot hide behind a matching SKILL.md.
+  it('a drifted references file FAILs parity even when SKILL.md matches', async () => {
+    healthyHome();
+    // R2 MJ-R2-01: the assertion must be the ONLY way this test can fail. An
+    // absent config would exit 1 regardless of parity, so the fixture supplies
+    // a valid one and lets the drifted file carry the verdict.
+    const configPath = writeConfig(path.join(tmpHome, '.delphi-config.json'));
+    const refsDir = path.join(bundledSkillDir(), 'references');
+    const refFile = fs.existsSync(refsDir)
+      ? fs.readdirSync(refsDir).find((f) => f.endsWith('.md'))
+      : null;
+    expect(refFile).toBeTruthy(); // explicit: without a bundled reference this test has nothing to say
+    fs.mkdirSync(path.join(tmpHome, '.qoder', 'skills', 'delphi-review', 'references'), { recursive: true });
+    fs.appendFileSync(
+      path.join(tmpHome, '.qoder', 'skills', 'delphi-review', 'references', refFile),
+      '\ndrift\n',
+    );
+    const { doctorDelphi } = require('../doctor');
+    const code = await doctorDelphi({ projectDir: tmpHome, configPath, npmLatest: null });
+    expect(code).toBe(1);
+  });
+
+  // R3 FC-01/FC-02: the empty-bundle branch is driven directly through the
+  // injectable bundledSkillDir — the healthy fixture cannot exercise it, and
+  // an indirect output-shape assertion would pass even without the fix.
+  it('an empty bundled skill directory FAILs parity instead of passing vacuously', async () => {
+    healthyHome();
+    const emptyBundle = fs.mkdtempSync(path.join(require('os').tmpdir(), 'doctor-empty-bundle-'));
+    try {
+      const logs = [];
+      const logSpy = vi.spyOn(console, 'log').mockImplementation((...args) => logs.push(args.join(' ')));
+      const { doctorDelphi } = require('../doctor');
+      const configPath = writeConfig(path.join(tmpHome, '.delphi-config.json'));
+      const code = await doctorDelphi({ projectDir: tmpHome, configPath, npmLatest: null, bundledSkillDir: emptyBundle });
+      logSpy.mockRestore();
+      expect(code).toBe(1);
+      const parityLine = logs.find((l) => l.includes('Delphi skill install parity'));
+      expect(parityLine).toContain('missing or empty');
+    } finally {
+      fs.rmSync(emptyBundle, { recursive: true, force: true });
+    }
+  });
+});

package/lib/__tests__/qoder-delphi-agents.test.js

@@ -282,4 +282,35 @@ describe('Qoder Delphi agent templates (#417)', () => {
       expect(warned()).not.toContain('templates not bundled');
     });
   });
+
+  // #429 item 5: the local-install path had direct test coverage, but the
+  // global wiring (`setupGlobal` -> `deployQoderDelphiAgents(srcDir, HOME_DIR)`)
+  // was only audited at "file exists" level — and the historical miss (#417) was
+  // exactly "local deployed, global did not". This test drives the real
+  // `setupGlobal` under a sandboxed HOME and asserts all three agents land in
+  // `~/.qoder/agents/` bound to the models this version ships. The missing-env
+  // regression it guards: someone re-pointing setupGlobal at a literal path, or
+  // dropping the call entirely, fails here instead of shipping silently.
+  it('deploys all three agents to the real HOME with this version\'s bindings after global setup', async () => {
+    // doctor.js/doctor-tui.js derive their HOME-dependent paths at module load;
+    // dropping them from the cache makes ensureTuiRegistration write inside the
+    // sandbox instead of the developer's real ~/.config/opencode/tui.json.
+    for (const name of ['../doctor.js', '../doctor-tui.js']) {
+      delete require.cache[require.resolve(name)];
+    }
+    const { setupGlobal, readQoderModelId } = require('../init');
+    // setupGlobal consumes the CLI argv array (flag checks downstream).
+    await setupGlobal([]);
+
+    const agentsDir = path.join(tmpHome, '.qoder', 'agents');
+    const shipped = path.join(repoRoot(), 'plugins', 'qoder', 'agents');
+    for (const name of ['delphi-architecture', 'delphi-technical', 'delphi-feasibility']) {
+      const deployed = path.join(agentsDir, `${name}.md`);
+      expect(fs.existsSync(deployed)).toBe(true);
+      // Identical to the bundled template's binding, not merely present: a
+      // stale global copy is the exact failure mode this audit exists for.
+      expect(readQoderModelId(deployed))
+        .toBe(readQoderModelId(path.join(shipped, `${name}.md`)));
+    }
+  });
 });

package/lib/delphi-setup.js

@@ -0,0 +1,155 @@
+'use strict';
+
+// xp-gate delphi-setup (#414 REQ-4) — the repair path for Qoder Delphi agent
+// bindings. `xp-gate init` deploys the bundled templates but deliberately
+// never overwrites an existing file, which is the right safety default for
+// installs and exactly the wrong behavior once a binding has drifted or the
+// platform retired a model id. This command exists to rebind on purpose.
+
+const fs = require('fs');
+const path = require('path');
+const { HOME_DIR, CONFIG_DIR } = require('./shared-paths.js');
+
+const DELPHI_ROLES = ['architecture', 'technical', 'feasibility'];
+// Mirrors QODER_MODEL_BINDING in init.js: the model id must survive
+// `"[DisplayName](modelId)"`, so the platform-visible charset is enforced here
+// rather than discovered as a silently-ignored binding later.
+const MODEL_ID_PATTERN = /^[A-Za-z0-9_.-]+$/;
+
+function parseSetupArgs(args) {
+  const models = {};
+  let scope = 'global';
+  let projectDir;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--model') {
+      const spec = args[++i];
+      const eq = typeof spec === 'string' ? spec.indexOf('=') : -1;
+      if (eq === -1) {
+        console.error(`[delphi-setup] ERROR: --model expects <role>=<modelId>, got "${spec}".`);
+        return { error: true };
+      }
+      const role = spec.slice(0, eq).trim();
+      const modelId = spec.slice(eq + 1).trim();
+      if (!DELPHI_ROLES.includes(role)) {
+        console.error(`[delphi-setup] ERROR: unknown expert role "${role}". Must be one of: ${DELPHI_ROLES.join(', ')}.`);
+        return { error: true };
+      }
+      if (modelId === '' || !MODEL_ID_PATTERN.test(modelId)) {
+        console.error(`[delphi-setup] ERROR: model id for ${role} must match [A-Za-z0-9_.-]+ (it becomes "[id](id)" in the agent frontmatter).`);
+        return { error: true };
+      }
+      models[role] = modelId;
+    } else if (args[i] === '--local') {
+      scope = 'local';
+    } else if (args[i] === '--global') {
+      scope = 'global';
+    } else if (args[i] === '--project') {
+      projectDir = args[++i];
+      if (typeof projectDir !== 'string' || projectDir.trim() === '') {
+        console.error('[delphi-setup] ERROR: --project expects a directory path.');
+        return { error: true };
+      }
+    } else {
+      console.error(`[delphi-setup] ERROR: unknown argument "${args[i]}".`);
+      return { error: true };
+    }
+  }
+
+  const missing = DELPHI_ROLES.filter((role) => !models[role]);
+  if (missing.length > 0) {
+    console.error(`[delphi-setup] ERROR: missing --model for: ${missing.join(', ')}.`);
+    console.error('Usage: xp-gate delphi-setup --model architecture=<id> --model technical=<id> --model feasibility=<id> [--global|--local [--project <dir>]]');
+    return { error: true };
+  }
+  if (scope === 'local' && projectDir === undefined) {
+    console.error('[delphi-setup] ERROR: --local requires --project <dir> (the CLI process may not run inside the project).');
+    return { error: true };
+  }
+  const duplicates = (() => {
+    // Set-based check (#414 R1 FC-16): readable at any future role count.
+    const ids = Object.values(models);
+    return ids.length !== new Set(ids).size;
+  })();
+  if (duplicates) {
+    console.error('[delphi-setup] ERROR: the three experts must bind three DISTINCT model ids — a duplicate defeats the multi-model invariant before any review starts.');
+    return { error: true };
+  }
+  return { models, scope, projectDir };
+}
+
+// Rebind only the model line; the rest of the bundled template (persona,
+// tools, skills) stays authoritative from this version of xp-gate.
+function rebindTemplate(templateBody, modelId) {
+  // Strip a UTF-8 BOM if present: lines[0] would otherwise be "\uFEFF---" and
+  // the frontmatter would read as missing, producing a misleading error.
+  if (templateBody.charCodeAt(0) === 0xfeff) templateBody = templateBody.slice(1);
+  const bindingLine = `model: "[${modelId}](${modelId})"`;
+  const lines = templateBody.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === '---');
+  if (start !== 0) return null;
+  const end = lines.indexOf('---', 1);
+  if (end === -1) return null;
+  const bindingIndex = lines.findIndex((l, idx) => idx > start && idx < end && /^model:[ \t]/.test(l));
+  if (bindingIndex === -1) return null;
+  lines[bindingIndex] = bindingLine;
+  return lines.join('\n');
+}
+
+async function delphiSetup(args) {
+  const parsed = parseSetupArgs(args || []);
+  if (parsed.error) return 1;
+  const { models, scope, projectDir } = parsed;
+
+  const templatesDir = path.join(__dirname, '..', 'plugins', 'qoder', 'agents');
+  const targetDir = scope === 'local'
+    ? path.join(projectDir, '.qoder', 'agents')
+    : path.join(HOME_DIR, '.qoder', 'agents');
+
+  // Validate every template BEFORE writing anything: a half-rebound set would
+  // leave the registry with a mix of old and new bindings on next session load.
+  const rebound = {};
+  for (const role of DELPHI_ROLES) {
+    const templatePath = path.join(templatesDir, `delphi-${role}.md`);
+    if (!fs.existsSync(templatePath)) {
+      console.error(`[delphi-setup] ERROR: bundled template missing: ${templatePath} — reinstall xp-gate.`);
+      return 1;
+    }
+    const body = rebindTemplate(fs.readFileSync(templatePath, 'utf8'), models[role]);
+    if (body === null) {
+      console.error(`[delphi-setup] ERROR: bundled template for ${role} has no model binding line to replace.`);
+      return 1;
+    }
+    rebound[role] = body;
+  }
+
+  // Back up existing agents before the first write (#414 R1 FC-04): this is
+  // the repair path, and a repair without a rollback is just a second way to
+  // lose a working binding.
+  const backupDir = path.join(CONFIG_DIR, 'backup', `delphi-setup-${Date.now()}`);
+  const backedUp = [];
+  for (const role of DELPHI_ROLES) {
+    const targetPath = path.join(targetDir, `delphi-${role}.md`);
+    if (fs.existsSync(targetPath)) {
+      fs.mkdirSync(backupDir, { recursive: true });
+      fs.copyFileSync(targetPath, path.join(backupDir, `delphi-${role}.md`));
+      backedUp.push(role);
+    }
+  }
+  if (backedUp.length > 0) {
+    console.log(`  backed up existing agents -> ${backupDir} (${backedUp.join(', ')})`);
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const role of DELPHI_ROLES) {
+    const targetPath = path.join(targetDir, `delphi-${role}.md`);
+    fs.writeFileSync(targetPath, rebound[role]);
+    console.log(`  delphi-${role} -> ${targetPath} (model: ${models[role]})`);
+  }
+
+  console.log('');
+  console.log('✓ Delphi agents rebound. NOW RELOAD: Qoder loads agent definitions only at');
+  console.log('  session start — 重开 Qoder 会话（或重启 IDE）后新绑定才生效，否则看起来像没修好。');
+  return 0;
+}
+
+module.exports = { delphiSetup, parseSetupArgs, rebindTemplate };