@boyingliu01/xp-gate 0.35.12 → 0.35.14

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

@@ -0,0 +1,116 @@
+/**
+ * @test REQ-646
+ * @intent 通道偏好必须**真正改变行为**，而不只是被读进来。这里跑的是真实的
+ *         `doctorDelphi()`，检查它输出的 Qoder agent bindings 那一行。
+ *
+ *         问题原状：外部通道用户删掉三个 agent 之后得到 `✗ Qoder Delphi agent
+ *         bindings: ... missing (run: xp-gate init --global)`。那是一条**会把机制
+ *         重新装回来**的修复提示，而且判它 FAIL 等于告诉用户"你的可用配置坏了"。
+ *
+ *         所以这里钉的是两种状态的**区分**：配置关掉 -> SKIP 且理由写清来源；
+ *         没配置 -> 该 FAIL 的照旧 FAIL。只钉前者会造出一个"永远跳过"的守卫，
+ *         那和永远通过没有区别。
+ * @covers AC-646-02, AC-646-04
+ */
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+const doctor = require(path.join(REPO_ROOT, 'src/npm-package/lib/doctor.js'));
+
+/** The single check whose behaviour #646 changes. */
+const BINDING_CHECK = 'Qoder Delphi agent bindings';
+
+describe('doctor 在 external-only 通道下的判定 (#646)', () => {
+  let tmpDir;
+  let originalEnv;
+
+  beforeEach(() => {
+    originalEnv = { ...process.env };
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-doctor-channel-'));
+    // Point both the home dir and the XDG config root at the sandbox so the real
+    // machine configuration can never leak into these assertions.
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+    process.env.XDG_CONFIG_HOME = path.join(tmpDir, '.config');
+    delete process.env.XP_GATE_DELPHI_CHANNEL;
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function writeMachineConfig(body) {
+    const dir = path.join(tmpDir, '.config', 'xp-gate');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, '.delphi-config.json'), JSON.stringify(body), 'utf8');
+  }
+
+  /**
+   * Run the real `doctorDelphi()` and capture the line it prints.
+   *
+   * The function prints its own report and returns an exit code, so the assertion has
+   * to go through stdout -- that is also the surface a user actually reads, which is
+   * what #646 is about. Returns `undefined` when the check is absent from the report.
+   */
+  async function runChecks() {
+    const written = [];
+    const originalLog = console.log;
+    const originalWarn = console.warn;
+    console.log = (...args) => written.push(args.join(' '));
+    console.warn = (...args) => written.push(args.join(' '));
+    try {
+      await doctor.doctorDelphi({ projectDir: tmpDir });
+    } finally {
+      console.log = originalLog;
+      console.warn = originalWarn;
+    }
+    const line = written.find((l) => l.includes(BINDING_CHECK));
+    if (line === undefined) return undefined;
+    // doctor prints a GLYPH, never the status word: "✓" PASS, "✗" FAIL, "○" SKIP.
+    // Matching on the word "SKIP" instead would read the ○ line as PASS, since its
+    // detail sentence contains no FAIL marker -- i.e. the assertion would pass for
+    // exactly the wrong reason.
+    let status = 'PASS';
+    if (line.includes('○')) status = 'SKIP';
+    else if (line.includes('✗')) status = 'FAIL';
+    return { status, detail: line };
+  }
+
+  it('AC-646-02: external-only reports SKIP, not FAIL, and names the source', async () => {
+    writeMachineConfig({ channels: ['external'] });
+    const check = await runChecks();
+    expect(check).toBeDefined();
+    expect(check.status).toBe('SKIP');
+    expect(check.detail).toMatch(/native channel disabled/);
+    // The reason must name where the setting came from: an unexplained SKIP is
+    // indistinguishable from a broken install.
+    expect(check.detail).toMatch(/via config/);
+  });
+
+  it('AC-646-02: the environment override is honoured by doctor too', async () => {
+    process.env.XP_GATE_DELPHI_CHANNEL = 'external';
+    const check = await runChecks();
+    expect(check.status).toBe('SKIP');
+    expect(check.detail).toMatch(/via env/);
+  });
+
+  it('AC-646-04: with no preference the check still FAILs — the guard is not a permanent skip', async () => {
+    // No agent files exist in the sandbox, and no channel preference disables the
+    // native path, so the original FAIL must survive. If this ever turns SKIP, the
+    // #646 fix has swallowed the check instead of gating it.
+    const check = await runChecks();
+    expect(check).toBeDefined();
+    expect(check.status).toBe('FAIL');
+  });
+
+  it('AC-646-02: an explicit native channel keeps the check active', async () => {
+    writeMachineConfig({ channels: ['native', 'external'] });
+    const check = await runChecks();
+    expect(check.status).toBe('FAIL');
+  });
+});

package/lib/__tests__/delphi-channel-uninstall.test.js

@@ -0,0 +1,128 @@
+/**
+ * @test REQ-646
+ * @intent `--uninstall` 是唯一一个**会删文件**的 Delphi 命令，所以它的测试必须
+ *         只在沙箱里跑，而且必须钉住"删掉之后 init 不会再装回来"这条闭环——
+ *         否则用户删一次、升级一次、机制又回来了，#646 原样复发。
+ *
+ *         另一个必须钉住的性质是**幂等**：第二次运行不能报错。
+ *         一个"没有东西可删"就失败的命令没法放进 bootstrap 脚本，
+ *         而 bootstrap 正是这个开关的主要用途。
+ *
+ *         写在测试里的教训：本命令默认作用于真实的 `~/.qoder/agents/`。
+ *         实现完成后我直接跑了一次冒烟测试，把本机三个 agent 文件删掉了。
+ *         所以下面每个用例都把 HOME 指向临时目录，不依赖调用者记得加沙箱。
+ * @covers AC-646-03, AC-646-05
+ */
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+
+describe('delphi-setup --uninstall (#646)', () => {
+  let tmpHome;
+  let originalEnv;
+  let projectDir;
+
+  beforeEach(() => {
+    originalEnv = { ...process.env };
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-uninstall-'));
+    projectDir = path.join(tmpHome, 'project');
+    // HOME_DIR() resolves from these; pointing them at the sandbox is what keeps
+    // this suite from deleting the developer's real agent files.
+    process.env.HOME = tmpHome;
+    process.env.USERPROFILE = tmpHome;
+    process.env.XDG_CONFIG_HOME = path.join(tmpHome, '.config');
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  function seedAgents(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+    for (const role of ['architecture', 'technical', 'feasibility']) {
+      fs.writeFileSync(path.join(dir, `delphi-${role}.md`), `model: "[x](x)"\n`, 'utf8');
+    }
+  }
+
+  function agentNames(dir) {
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir).filter((f) => f.startsWith('delphi-')).sort();
+  }
+
+  it('AC-646-03: removes all three user-level agents', async () => {
+    const { delphiSetup } = require(path.join(REPO_ROOT, 'src/npm-package/lib/delphi-setup.js'));
+    const dir = path.join(tmpHome, '.qoder', 'agents');
+    seedAgents(dir);
+    expect(agentNames(dir)).toHaveLength(3);
+
+    const code = await delphiSetup(['--uninstall', '--global']);
+
+    expect(code).toBe(0);
+    expect(agentNames(dir)).toEqual([]);
+  });
+
+  it('AC-646-03: removes project-level agents with --local --project', async () => {
+    const { delphiSetup } = require(path.join(REPO_ROOT, 'src/npm-package/lib/delphi-setup.js'));
+    const dir = path.join(projectDir, '.qoder', 'agents');
+    seedAgents(dir);
+
+    const code = await delphiSetup(['--uninstall', '--local', '--project', projectDir]);
+
+    expect(code).toBe(0);
+    expect(agentNames(dir)).toEqual([]);
+  });
+
+  it('AC-646-03: a second run still succeeds -- idempotence is the point', async () => {
+    const { delphiSetup } = require(path.join(REPO_ROOT, 'src/npm-package/lib/delphi-setup.js'));
+    const dir = path.join(tmpHome, '.qoder', 'agents');
+    seedAgents(dir);
+
+    expect(await delphiSetup(['--uninstall', '--global'])).toBe(0);
+    // Nothing left to delete. "Nothing to do" is success, not failure: a command
+    // that errors here cannot be called from a bootstrap script twice.
+    expect(await delphiSetup(['--uninstall', '--global'])).toBe(0);
+  });
+
+  it('AC-646-03: refuses to combine --uninstall with --model', async () => {
+    const { delphiSetup } = require(path.join(REPO_ROOT, 'src/npm-package/lib/delphi-setup.js'));
+    const dir = path.join(tmpHome, '.qoder', 'agents');
+    seedAgents(dir);
+
+    const code = await delphiSetup([
+      '--uninstall',
+      '--model', 'architecture=qfmodel',
+      '--model', 'technical=gfmodel',
+      '--model', 'feasibility=dfmodel',
+    ]);
+
+    // Rebinding and uninstalling are opposite verbs; guessing which one wins would
+    // silently discard the other intent.
+    expect(code).toBe(1);
+    expect(agentNames(dir)).toHaveLength(3);
+  });
+
+  it('AC-646-05: doctor flips to SKIP once the channel preference is set', async () => {
+    // The closed loop: uninstall removes the files, the preference keeps `init` from
+    // putting them back, and doctor must read that as configured-not-broken.
+    const { delphiSetup } = require(path.join(REPO_ROOT, 'src/npm-package/lib/delphi-setup.js'));
+    const dir = path.join(tmpHome, '.qoder', 'agents');
+    seedAgents(dir);
+    await delphiSetup(['--uninstall', '--global']);
+
+    const cfgDir = path.join(tmpHome, '.config', 'xp-gate');
+    fs.mkdirSync(cfgDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(cfgDir, '.delphi-config.json'),
+      JSON.stringify({ channels: ['external'] }),
+      'utf8',
+    );
+
+    const channel = require(path.join(REPO_ROOT, 'src/npm-package/lib/delphi-channel.js'));
+    expect(channel.nativeAgentDeploymentIsWanted({ home: tmpHome })).toBe(false);
+  });
+});

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

@@ -0,0 +1,109 @@
+/**
+ * @test REQ-646
+ * @intent native Delphi 通道在 Qoder 上**已被实测证伪**：subagent 派发采纳 agent 的提示词，
+ *         却丢弃 model 绑定，三席永远跑会话模型。2026-09-23 复测记录写在
+ *         `skills/delphi-review/SKILL.md` 里——三份 agent 分别绑 qfmodel / dfmodel / gfmodel，
+ *         新会话后 `turn.started` / `model.request.started` / `model.response.completed`
+ *         三处的 model **全为会话模型**，dfmodel / gfmodel 出现 0 次。
+ *
+ *         结论：native 通道只能产出"同模型三角色自查"，**不构成多模型交叉验证证据**，
+ *         也不能用作 Gate MW 的三模型凭据。
+ *
+ *         然而安装路径无条件部署它、doctor 强制要求它存在。于是外部通道用户删掉三个
+ *         agent 换来的是一盏红灯 + 一条会把机制重新装回来的修复提示。"关掉它"在产品层面
+ *         无路可走——这是本测试要钉住的东西。
+ *
+ *         设计要点：偏好读 #541 确立的**机器级唯一事实源**，不是项目文件。通道选择是
+ *         "这台机器上 Delphi 怎么跑"，与具体仓库无关；放进项目 files 会让每个仓库各写一遍。
+ * @covers AC-646-01, AC-646-02, AC-646-03
+ */
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+
+describe('Delphi 通道偏好 (#646)', () => {
+  let channel;
+  let tmpHome;
+  let originalEnv;
+
+  beforeAll(() => {
+    channel = require(path.join(REPO_ROOT, 'src/npm-package/lib/delphi-channel.js'));
+  });
+
+  beforeEach(() => {
+    originalEnv = { ...process.env };
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-channel-'));
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  /** Writes a machine-level config file the way #541 lays it out. */
+  function writeMachineConfig(body) {
+    const dir = path.join(tmpHome, '.config', 'xp-gate');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, '.delphi-config.json'), JSON.stringify(body), 'utf8');
+    return dir;
+  }
+
+  it('AC-646-01: an explicit channels preference is honoured', () => {
+    writeMachineConfig({ channels: ['external'] });
+    expect(channel.resolveChannels({ home: tmpHome })).toEqual({
+      channels: ['external'],
+      source: 'config',
+      nativeEnabled: false,
+    });
+  });
+
+  it('AC-646-01: the environment variable wins over the config file', () => {
+    // The env var is the escape hatch for CI and one-off runs; a file cannot be
+    // changed from a test harness, so it must lose to an explicit env setting.
+    writeMachineConfig({ channels: ['native', 'external'] });
+    process.env.XP_GATE_DELPHI_CHANNEL = 'external';
+    const resolved = channel.resolveChannels({ home: tmpHome });
+    expect(resolved.channels).toEqual(['external']);
+    expect(resolved.source).toBe('env');
+    expect(resolved.nativeEnabled).toBe(false);
+  });
+
+  it('AC-646-01: with no preference, both channels stay enabled and the source says why', () => {
+    // Defaulting to external-only would silently change behaviour for everyone who
+    // never asked. Defaulting to native-only would keep the disproved path in front.
+    const resolved = channel.resolveChannels({ home: tmpHome });
+    expect(resolved.channels).toEqual(['native', 'external']);
+    expect(resolved.source).toBe('default');
+    expect(resolved.nativeEnabled).toBe(true);
+  });
+
+  it('AC-646-01: an unrecognised value falls back loudly instead of guessing', () => {
+    writeMachineConfig({ channels: ['nonsense'] });
+    const resolved = channel.resolveChannels({ home: tmpHome });
+    expect(resolved.source).toBe('default');
+    expect(resolved.channels).toEqual(['native', 'external']);
+    expect(resolved.warning).toMatch(/nonsense/);
+  });
+
+  it('AC-646-01: a corrupt config file does not crash and does not pretend to be configured', () => {
+    const dir = path.join(tmpHome, '.config', 'xp-gate');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, '.delphi-config.json'), '{ not json', 'utf8');
+    const resolved = channel.resolveChannels({ home: tmpHome });
+    expect(resolved.source).toBe('default');
+    expect(resolved.warning).toBeTruthy();
+  });
+
+  it('AC-646-02: nativeAgentDeploymentIsWanted() is what init must consult', () => {
+    writeMachineConfig({ channels: ['external'] });
+    expect(channel.nativeAgentDeploymentIsWanted({ home: tmpHome })).toBe(false);
+
+    fs.rmSync(path.join(tmpHome, '.config'), { recursive: true, force: true });
+    delete process.env.XP_GATE_DELPHI_CHANNEL;
+    expect(channel.nativeAgentDeploymentIsWanted({ home: tmpHome })).toBe(true);
+  });
+});

package/lib/delphi-channel.js

@@ -0,0 +1,181 @@
+/**
+ * Delphi 通道偏好 — 这台机器上 Delphi 评审走哪条路（#646）
+ *
+ * ## 为什么需要这个文件
+ *
+ * Qoder 的 native 通道**已被实测证伪**，证据就写在自家技能里
+ * （`skills/delphi-review/SKILL.md`）：subagent 派发采纳 agent 的提示词，却丢弃
+ * model 绑定，三席永远跑会话模型。所以 native 只能产出"同模型三角色自查"，
+ * 不构成多模型交叉验证证据，也不能用作 Gate MW 的三模型凭据。
+ *
+ * 但安装路径无条件部署它，doctor 强制要求它存在。于是只用外部通道的用户删掉三个
+ * agent 之后，得到的是一盏红灯 + 一条会把机制重新装回来的修复提示——"关掉它"
+ * 在产品层面无路可走。
+ *
+ * ## 为什么偏好放在机器级
+ *
+ * 通道选择是"这台机器上 Delphi 怎么跑"，与具体仓库无关。放进项目文件会让每个仓库
+ * 各写一遍，而且换仓库时要重配一次。#541 已经把机器级 Delphi 配置收敛到
+ * `~/.config/xp-gate/.delphi-config.json`，偏好作为其中的 `channels` 字段。
+ *
+ * ## 为什么默认是两条都开
+ *
+ * 默认 external-only 会悄悄改掉所有没提要求的人的行为；默认 native-only 则把已被
+ * 证伪的路径摆在最前面。默认保持"两条都可用"，由用户显式关掉。
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+/** The channels this product knows about, in the order they are tried. */
+const KNOWN_CHANNELS = ['native', 'external'];
+
+/** Both enabled — see "为什么默认是两条都开" above. */
+const DEFAULT_CHANNELS = ['native', 'external'];
+
+/** Environment override. Beats the config file, for CI and one-off runs. */
+const CHANNEL_ENV = 'XP_GATE_DELPHI_CHANNEL';
+
+/**
+ * Normalise a user-supplied channel list.
+ *
+ * Accepts an array or a comma/space separated string (the env var spelling).
+ * Unknown names are dropped and reported rather than silently ignored: a typo that
+ * quietly leaves native enabled is exactly the failure this file exists to prevent.
+ *
+ * @param {unknown} raw
+ * @returns {{ channels: string[], unknown: string[] }}
+ */
+function normaliseChannels(raw) {
+  let parts;
+  if (Array.isArray(raw)) {
+    parts = raw;
+  } else if (typeof raw === 'string') {
+    parts = raw.split(/[,\s]+/);
+  } else {
+    return { channels: [], unknown: [] };
+  }
+
+  const seen = new Set();
+  const unknown = [];
+  for (const part of parts) {
+    if (typeof part !== 'string') continue;
+    const name = part.trim().toLowerCase();
+    if (name === '') continue;
+    if (!KNOWN_CHANNELS.includes(name)) {
+      unknown.push(part);
+      continue;
+    }
+    seen.add(name);
+  }
+
+  // Preserve KNOWN_CHANNELS order so resolution is deterministic regardless of how
+  // the user wrote the list.
+  return { channels: KNOWN_CHANNELS.filter((c) => seen.has(c)), unknown };
+}
+
+/**
+ * Read the machine-level Delphi config, if any.
+ *
+ * Deliberately tolerant: a hand-edited or corrupt file must not make `init` or
+ * `doctor` crash. It returns `undefined` and the caller falls back to defaults with
+ * a warning, because "I could not read your preference" and "you asked for both"
+ * look identical downstream and the message is what tells them apart.
+ *
+ * @param {string} [home]
+ * @returns {{ config?: object, error?: string }}
+ */
+function readMachineConfig(home) {
+  const root = home || os.homedir();
+  const file = path.join(root, '.config', 'xp-gate', '.delphi-config.json');
+  if (!fs.existsSync(file)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { error: `${file} is not a JSON object` };
+    }
+    return { config: parsed };
+  } catch (err) {
+    return { error: `${file} is unreadable: ${err && err.message ? err.message : String(err)}` };
+  }
+}
+
+/**
+ * Resolve which Delphi channels are enabled on this machine.
+ *
+ * @param {{ home?: string }} [opts]
+ * @returns {{ channels: string[], source: 'env'|'config'|'default', nativeEnabled: boolean, warning?: string }}
+ */
+function resolveChannels(opts = {}) {
+  const envRaw = process.env[CHANNEL_ENV];
+  if (envRaw !== undefined && envRaw.trim() !== '') {
+    const { channels, unknown } = normaliseChannels(envRaw);
+    if (channels.length > 0) {
+      return {
+        channels,
+        source: 'env',
+        nativeEnabled: channels.includes('native'),
+        ...(unknown.length > 0
+          ? { warning: `${CHANNEL_ENV} ignored unknown channel(s): ${unknown.join(', ')}` }
+          : {}),
+      };
+    }
+    // Every value was unknown -> fall through to the file/default rather than
+    // resolving to "no channels at all", which would disable Delphi entirely on a typo.
+  }
+
+  const { config, error } = readMachineConfig(opts.home);
+  if (error) {
+    return { channels: DEFAULT_CHANNELS, source: 'default', nativeEnabled: true, warning: error };
+  }
+
+  if (config && Object.prototype.hasOwnProperty.call(config, 'channels')) {
+    const { channels, unknown } = normaliseChannels(config.channels);
+    if (channels.length > 0) {
+      const notes = [];
+      if (unknown.length > 0) notes.push(`ignored unknown channel(s): ${unknown.join(', ')}`);
+      return {
+        channels,
+        source: 'config',
+        nativeEnabled: channels.includes('native'),
+        ...(notes.length > 0 ? { warning: notes.join('; ') } : {}),
+      };
+    }
+    return {
+      channels: DEFAULT_CHANNELS,
+      source: 'default',
+      nativeEnabled: true,
+      warning: `config "channels" had no recognised value (got ${
+        JSON.stringify(config.channels)
+      }); known: ${KNOWN_CHANNELS.join(', ')} — using defaults`,
+    };
+  }
+
+  return { channels: DEFAULT_CHANNELS, source: 'default', nativeEnabled: true };
+}
+
+/**
+ * Should `xp-gate init` deploy the Qoder native Delphi agents?
+ *
+ * One named predicate rather than an inline `resolveChannels().nativeEnabled` at the
+ * call site, so the decision has a single testable home and reads as a question.
+ *
+ * @param {{ home?: string }} [opts]
+ * @returns {boolean}
+ */
+function nativeAgentDeploymentIsWanted(opts = {}) {
+  return resolveChannels(opts).nativeEnabled;
+}
+
+module.exports = {
+  CHANNEL_ENV,
+  DEFAULT_CHANNELS,
+  KNOWN_CHANNELS,
+  nativeAgentDeploymentIsWanted,
+  normaliseChannels,
+  readMachineConfig,
+  resolveChannels,
+};

package/lib/delphi-setup.js

@@ -20,8 +20,11 @@ function parseSetupArgs(args) {
   const models = {};
   let scope = 'global';
   let projectDir;
+  let uninstall = false;
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--model') {
+    if (args[i] === '--uninstall') {
+      uninstall = true;
+    } else if (args[i] === '--model') {
       const spec = args[++i];
       const eq = typeof spec === 'string' ? spec.indexOf('=') : -1;
       if (eq === -1) {
@@ -55,6 +58,20 @@ function parseSetupArgs(args) {
     }
   }
 
+  // #646: --uninstall is a different verb, not a modifier -- it removes the native
+  // agents instead of rebinding them, so it must not demand --model.
+  if (uninstall) {
+    if (Object.keys(models).length > 0) {
+      console.error('[delphi-setup] ERROR: --uninstall cannot be combined with --model (remove or rebind, not both).');
+      return { error: true };
+    }
+    if (scope === 'local' && projectDir === undefined) {
+      console.error('[delphi-setup] ERROR: --uninstall --local requires --project <dir>.');
+      return { error: true };
+    }
+    return { models, scope, projectDir, uninstall };
+  }
+
   const missing = DELPHI_ROLES.filter((role) => !models[role]);
   if (missing.length > 0) {
     console.error(`[delphi-setup] ERROR: missing --model for: ${missing.join(', ')}.`);
@@ -95,9 +112,57 @@ function rebindTemplate(templateBody, modelId) {
   return lines.join('\n');
 }
 
+/**
+ * Remove the native Delphi agent files for one scope (#646).
+ *
+ * Idempotent by design: the point is to let a user stop the native path and KEEP it
+ * stopped across upgrades. A command that errors "nothing to remove" the second time
+ * is a command you cannot put in a bootstrap script.
+ *
+ * Reports what it actually removed rather than a bare "done" -- after this, `doctor`
+ * flips the binding check to SKIP, and the user needs to see that the state changed
+ * because of them, not because something broke.
+ *
+ * @param {'global'|'local'} scope
+ * @param {string|undefined} projectDir
+ * @returns {number} exit code
+ */
+function uninstallDelphiAgents(scope, projectDir) {
+  const targetDir = scope === 'local'
+    ? path.join(projectDir, '.qoder', 'agents')
+    : path.join(HOME_DIR, '.qoder', 'agents');
+
+  const removed = [];
+  const absent = [];
+  for (const role of DELPHI_ROLES) {
+    const targetPath = path.join(targetDir, `delphi-${role}.md`);
+    if (fs.existsSync(targetPath)) {
+      fs.unlinkSync(targetPath);
+      removed.push(`delphi-${role}.md`);
+    } else {
+      absent.push(`delphi-${role}.md`);
+    }
+  }
+
+  console.log(`  scope: ${scope === 'local' ? `project-level ${targetDir}` : `user-level ${targetDir}`}`);
+  if (removed.length > 0) console.log(`  removed: ${removed.join(', ')}`);
+  if (absent.length > 0) console.log(`  already absent: ${absent.join(', ')}`);
+  console.log('');
+  console.log('✓ Native Delphi agents are gone. The native channel is a same-model');
+  console.log('  three-persona self-check and never satisfied the three-distinct-model');
+  console.log('  contract, so this loses no review evidence.');
+  console.log('');
+  console.log('  To stop `xp-gate init` from reinstalling them, set the machine-level channel');
+  console.log('  preference once:');
+  console.log(`    ${path.join(CONFIG_DIR, '.delphi-config.json')}`);
+  console.log('    { "channels": ["external"] }');
+  return 0;
+}
+
 async function delphiSetup(args) {
   const parsed = parseSetupArgs(args || []);
   if (parsed.error) return 1;
+  if (parsed.uninstall) return uninstallDelphiAgents(parsed.scope, parsed.projectDir);
   const { models, scope, projectDir } = parsed;
 
   const templatesDir = path.join(__dirname, '..', 'plugins', 'qoder', 'agents');