@boyingliu01/xp-gate 0.31.1 → 0.31.2

package/lib/doctor.js

@@ -4,15 +4,22 @@ const { execSync, execFileSync, spawnSync } = require('child_process');
 const { exec } = require('child_process');
 const util = require('util');
 const execAsync = util.promisify(exec);
-const {
-  HOME_DIR,
-  CONFIG_DIR,
-  CONFIG_FILE,
-  GLOBAL_HOOKS_DIR,
-  GLOBAL_ADAPTERS_DIR,
-  detectPlatform,
-  getTemplateDir,
-} = require('./shared-paths.js');
+const sharedPaths = require('./shared-paths.js');
+const { detectPlatform, getTemplateDir } = sharedPaths;
+
+// #599: the filesystem roots below are DERIVED FROM process.env.HOME, so they
+// must not be captured at require() time. doctor.js is routinely loaded by a
+// test run BEFORE that run sets HOME -- doctor.test.js loads detect-deps.js
+// (which loads shared-paths.js) in beforeAll, before any test assigns HOME --
+// and a require-time capture froze CONFIG_FILE to the REAL home directory. That
+// made `doctor` report `Config file: Not found` for fixtures that had in fact
+// written the config, and `--fix` returned 1 on a healthy installation.
+//
+// These are therefore read through the module at each use, not destructured.
+const HOME_DIR = () => sharedPaths.HOME_DIR;
+const CONFIG_FILE = () => sharedPaths.CONFIG_FILE;
+const GLOBAL_HOOKS_DIR = () => sharedPaths.GLOBAL_HOOKS_DIR;
+const GLOBAL_ADAPTERS_DIR = () => sharedPaths.GLOBAL_ADAPTERS_DIR;
 const { checkUpgrade, formatUpgradeMsg } = require('./check-version.js');
 const { GATE_CLI_TOOLS, checkCliTool, getToolInstallCmd, checkBash } = require('./detect-deps.js');
 // #505: the single source of truth for module resolution order. The hook reads a
@@ -214,16 +221,16 @@ function isXpGateFile(filePath, signature) {
 }
 
 function getConfig() {
-  if (!fs.existsSync(CONFIG_FILE)) return null;
+  if (!fs.existsSync(CONFIG_FILE())) return null;
   try {
-    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    return JSON.parse(fs.readFileSync(CONFIG_FILE(), 'utf8'));
   } catch {
     return 'corrupt';
   }
 }
 
 function saveConfig(config) {
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+  fs.writeFileSync(CONFIG_FILE(), JSON.stringify(config, null, 2));
 }
 
 async function getGitDir() {
@@ -339,12 +346,12 @@ function checkConfig() {
   }
   if (config.mode !== 'local' && config.mode !== 'global') {
     return { config: null, checks: [
-      { name: 'Config file', status: 'PASS', detail: CONFIG_FILE },
+      { name: 'Config file', status: 'PASS', detail: CONFIG_FILE() },
       { name: 'Install mode', status: 'FAIL', detail: `Unknown: ${config.mode}` }
     ], issues: 1 };
   }
   return { config, checks: [
-    { name: 'Config file', status: 'PASS', detail: CONFIG_FILE },
+    { name: 'Config file', status: 'PASS', detail: CONFIG_FILE() },
     { name: 'Install mode', status: 'PASS', detail: config.mode }
   ], issues: 0 };
 }
@@ -365,19 +372,19 @@ async function checkLocalHooks(checks) {
 
 async function checkGlobalHooks(checks) {
   let issues = 0;
-  issues += checkSingleHook(GLOBAL_HOOKS_DIR, 'pre-commit', SIGNATURES['pre-commit'], 'Global hooks', checks);
-  issues += checkSingleHook(GLOBAL_HOOKS_DIR, 'pre-push', SIGNATURES['pre-push'], 'Global hooks', checks);
-  issues += checkSingleHook(GLOBAL_HOOKS_DIR, 'post-merge', SIGNATURES['post-merge'], 'Global hooks', checks);
+  issues += checkSingleHook(GLOBAL_HOOKS_DIR(), 'pre-commit', SIGNATURES['pre-commit'], 'Global hooks', checks);
+  issues += checkSingleHook(GLOBAL_HOOKS_DIR(), 'pre-push', SIGNATURES['pre-push'], 'Global hooks', checks);
+  issues += checkSingleHook(GLOBAL_HOOKS_DIR(), 'post-merge', SIGNATURES['post-merge'], 'Global hooks', checks);
 
   const hooksPath = await getCurrentHooksPath();
   if (hooksPath === null || hooksPath === '') {
     checks.push({ name: 'Git core.hooksPath', status: 'FAIL', detail: 'Not set' });
     issues++;
-  } else if (!pathsEquivalent(hooksPath, GLOBAL_HOOKS_DIR)) {
-    checks.push({ name: 'Git core.hooksPath', status: 'FAIL', detail: `Expected ${GLOBAL_HOOKS_DIR}, got ${hooksPath}` });
+  } else if (!pathsEquivalent(hooksPath, GLOBAL_HOOKS_DIR())) {
+    checks.push({ name: 'Git core.hooksPath', status: 'FAIL', detail: `Expected ${GLOBAL_HOOKS_DIR()}, got ${hooksPath}` });
     issues++;
   } else {
-    checks.push({ name: 'Git core.hooksPath', status: 'PASS', detail: GLOBAL_HOOKS_DIR });
+    checks.push({ name: 'Git core.hooksPath', status: 'PASS', detail: GLOBAL_HOOKS_DIR() });
   }
   return issues;
 }
@@ -443,7 +450,7 @@ function diagnoseHookDrift(ctx = {}) {
   // explicitly instead of inferring it from the process cwd.
   const repoRoot = ctx.repoRoot || process.env.XP_GATE_REPO_ROOT || process.cwd();
   const repoHooks = ctx.repoHooks || path.join(repoRoot, 'githooks');
-  const installedHooks = ctx.installedHooks || GLOBAL_HOOKS_DIR;
+  const installedHooks = ctx.installedHooks || GLOBAL_HOOKS_DIR();
 
   // Nothing to compare when the project carries no canonical *hook* source, or
   // when no global copy exists at all. Both must stay completely silent.
@@ -817,7 +824,7 @@ function syncModulesFromRepo(ctx = {}) {
 
   if (!hasCanonicalHooks(repoHooks)) {
     errors.push(`no canonical githooks/ source at ${repoHooks} -- nothing was synced`);
-    return { synced, skipped, refused, errors, installedAdapters: ctx.installedAdapters || ctx.globalAdapterDir || GLOBAL_ADAPTERS_DIR, sourceMissing: true };
+    return { synced, skipped, refused, errors, installedAdapters: ctx.installedAdapters || ctx.globalAdapterDir || GLOBAL_ADAPTERS_DIR(), sourceMissing: true };
   }
 
   // Same resolution the diagnosis used, so a FAIL the diagnosis can produce is a
@@ -884,9 +891,9 @@ function syncModulesFromRepo(ctx = {}) {
  * @returns {{adapterDir: string, gateDir: string, globalAdapterDir: string, projectGithooks: string, scriptDir: string}}
  */
 function resolveExecutedModuleDirs(ctx = {}) {
-  const globalAdapterDir = ctx.globalAdapterDir || ctx.installedAdapters || GLOBAL_ADAPTERS_DIR;
+  const globalAdapterDir = ctx.globalAdapterDir || ctx.installedAdapters || GLOBAL_ADAPTERS_DIR();
   const projectGithooks = ctx.projectGithooks || defaultProjectGithooks();
-  const scriptDir = ctx.scriptDir || GLOBAL_HOOKS_DIR;
+  const scriptDir = ctx.scriptDir || GLOBAL_HOOKS_DIR();
 
   const has = (dir, file) => fs.existsSync(path.join(dir, file));
 
@@ -1115,6 +1122,94 @@ function printEffectiveHooks() {
   console.log(`  source: ${source}`);
 }
 
+/**
+ * Keep a copy of an installed file before `--sync-hooks` overwrites it (#566).
+ *
+ * #566 was a hook that existed on exactly one machine and in no commit: a local
+ * edit to the installed `pre-push` that `--sync-hooks` replaced silently. The
+ * repo side then looked correct and the work was gone -- unrecoverable, because
+ * nothing had recorded that the installed copy held anything more.
+ *
+ * The refusal path already protects files whose content diverges. This covers the
+ * remaining cases, where the overwrite is legitimate but still destroys the
+ * previous version: `--force`, and files that differ only in whitespace.
+ *
+ * Copies land in a sibling `backups/` directory with a timestamp, so repeated
+ * syncs never overwrite an older backup. The target's own directory is used
+ * rather than the user's work tree, so this never litters a repository.
+ *
+ * @param {string} target existing file about to be overwritten
+ * @param {string} backupsDir directory to place the copy in
+ * @returns {string|null} path of the backup, or null when there was nothing to back up
+ */
+function backupBeforeOverwrite(target, backupsDir) {
+  if (!fs.existsSync(target)) return null;
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  try {
+    fs.mkdirSync(backupsDir, { recursive: true });
+    // The stamp has millisecond resolution, so two syncs inside the same
+    // millisecond produce the same name and the second copy destroys the first —
+    // the backup is worth nothing exactly when it is needed most (a rapid
+    // "edit, sync, edit, sync" repair loop). Disambiguate instead of overwriting:
+    // the first backup of a burst must survive the rest.
+    let backup = path.join(backupsDir, `${path.basename(target)}.${stamp}.bak`);
+    for (let n = 1; fs.existsSync(backup); n += 1) {
+      backup = path.join(backupsDir, `${path.basename(target)}.${stamp}-${n}.bak`);
+    }
+    fs.copyFileSync(target, backup);
+    return backup;
+  } catch {
+    // A backup that cannot be written must not abort the sync; the caller
+    // reports the file it overwrote either way.
+    return null;
+  }
+}
+
+/**
+ * Read a VERSION file, returning '' when it is missing or empty.
+ *
+ * Kept local and silent: the deploy log's version field must never be the reason
+ * a sync fails, and "unknown" is a truthful value.
+ *
+ * @param {string} versionPath
+ * @returns {string}
+ */
+function readVersionFile(versionPath) {
+  try {
+    return fs.readFileSync(versionPath, 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Append one line to the deploy log beside the installed hooks (#583).
+ *
+ * The backup (#566) makes a damaged file recoverable; it does not answer the
+ * question a downstream actually has — "was my patch eaten, and by which
+ * version?". A directory of timestamped `.bak` files is readable only by someone
+ * who already suspects an overwrite. #583 records three silent overwrites in one
+ * day, one of which reverted a fail-open fix that had already been filed, fixed
+ * and tested.
+ *
+ * One line per overwritten file, appended — never rewritten, because "three times
+ * today" is exactly what the log exists to show.
+ *
+ * @param {string} logPath deploy log path
+ * @param {{file: string, version: string, backup: string|null}} entry
+ */
+function appendDeployLogEntry(logPath, entry) {
+  const stamp = new Date().toISOString();
+  const backup = entry.backup ? path.basename(entry.backup) : '(no previous content)';
+  const line = `${stamp} overwrote ${entry.file} from xp-gate ${entry.version} (previous saved as ${backup})\n`;
+  try {
+    fs.appendFileSync(logPath, line);
+  } catch {
+    // Same rule as the backup itself: a log that cannot be written must not
+    // abort the sync. The overwrite still happens and still reports its name.
+  }
+}
+
 /**
  * Copy the repository's `githooks/` over the installed global hooks (#451 REQ-2).
  *
@@ -1123,33 +1218,45 @@ function printEffectiveHooks() {
  * directory are left alone.
  *
  * @param {{repoRoot?: string, repoHooks?: string, installedHooks?: string}} [ctx]
- * @returns {{synced: string[], skipped: string[], refused: Array<{name: string, repoOnly: number, installedOnly: number}>, errors: string[], installedHooks: string}}
+ * Every overwrite is preceded by a backup (#566): the previous version is copied
+ * to `backups/` beside the installed hooks before it is replaced.
+ *
+ * @returns {{synced: string[], skipped: string[], refused: Array<{name: string, repoOnly: number, installedOnly: number}>, errors: string[], installedHooks: string, backups: string[]}}
  */
 function syncGlobalHooksFromRepo(ctx = {}) {
   const repoRoot = ctx.repoRoot || process.env.XP_GATE_REPO_ROOT || process.cwd();
   const repoHooks = ctx.repoHooks || path.join(repoRoot, 'githooks');
-  const installedHooks = ctx.installedHooks || GLOBAL_HOOKS_DIR;
+  const installedHooks = ctx.installedHooks || GLOBAL_HOOKS_DIR();
+  // #583: the version that performs the overwrite is part of the record. Read the
+  // repo's VERSION beside the hooks, so the log answers "which release did this"
+  // without the caller having to remember to pass it.
+  const version = ctx.version
+    || readVersionFile(path.join(repoRoot, 'VERSION'))
+    || 'unknown';
 
   const synced = [];
   const skipped = [];
   const refused = [];
   const errors = [];
+  const backups = [];
+  const backupsDir = path.join(installedHooks, 'backups');
+  const deployLog = path.join(installedHooks, 'deploy.log');
 
   if (!fs.existsSync(repoHooks)) {
     errors.push(`no githooks/ directory at ${repoHooks}`);
-    return { synced, skipped, refused, errors, installedHooks };
+    return { synced, skipped, refused, errors, installedHooks, backups };
   }
 
   if (!hasCanonicalHooks(repoHooks)) {
     errors.push(`no hook files in ${repoHooks} (only adapters?) -- nothing to sync from`);
-    return { synced, skipped, refused, errors, installedHooks };
+    return { synced, skipped, refused, errors, installedHooks, backups };
   }
 
   try {
     fs.mkdirSync(installedHooks, { recursive: true });
   } catch (err) {
     errors.push(`cannot create ${installedHooks}: ${err.message}`);
-    return { synced, skipped, refused, errors, installedHooks };
+    return { synced, skipped, refused, errors, installedHooks, backups };
   }
 
   for (const name of DRIFT_COMPARED_HOOKS) {
@@ -1164,10 +1271,17 @@ function syncGlobalHooksFromRepo(ctx = {}) {
         skipped.push(name);
         continue;
       }
+      // #566: the previous version is kept, because this overwrite is the moment
+      // machine-only work is lost.
+      const backup = backupBeforeOverwrite(target, backupsDir);
+      if (backup) backups.push(backup);
       // copyFileSync preserves content; the exec bit is re-applied explicitly
       // because a copied hook that is not executable silently never runs.
       fs.copyFileSync(source, target);
       fs.chmodSync(target, 0o755);
+      // #583: record it, so a downstream can tell an overwrite from a fresh
+      // install without having to diff checksums first.
+      appendDeployLogEntry(deployLog, { file: name, version, backup });
       synced.push(name);
     } catch (err) {
       errors.push(`${name}: ${err.message}`);
@@ -1187,7 +1301,10 @@ function syncGlobalHooksFromRepo(ctx = {}) {
         skipped.push(name);
         continue;
       }
+      const backup = backupBeforeOverwrite(target, backupsDir);
+      if (backup) backups.push(backup);
       fs.copyFileSync(source, target);
+      appendDeployLogEntry(deployLog, { file: name, version, backup });
       synced.push(name);
     } catch (err) {
       errors.push(`${name}: ${err.message}`);
@@ -1203,14 +1320,14 @@ function syncGlobalHooksFromRepo(ctx = {}) {
       fs.mkdirSync(installedLib, { recursive: true });
     } catch (err) {
       errors.push(`cannot create ${installedLib}: ${err.message}`);
-      return { synced, skipped, refused, errors, installedHooks };
+      return { synced, skipped, refused, errors, installedHooks, backups };
     }
     let libEntries = [];
     try {
       libEntries = fs.readdirSync(repoLib, { withFileTypes: true });
     } catch (err) {
       errors.push(`cannot read ${repoLib}: ${err.message}`);
-      return { synced, skipped, refused, errors, installedHooks };
+      return { synced, skipped, refused, errors, installedHooks, backups };
     }
     for (const entry of libEntries) {
       if (!entry.isFile()) continue;
@@ -1243,8 +1360,11 @@ function syncGlobalHooksFromRepo(ctx = {}) {
             continue;
           }
         }
+        const backup = backupBeforeOverwrite(target, backupsDir);
+        if (backup) backups.push(backup);
         fs.copyFileSync(source, target);
         fs.chmodSync(target, 0o755);
+        appendDeployLogEntry(deployLog, { file: rel, version, backup });
         synced.push(rel);
       } catch (err) {
         errors.push(`${rel}: ${err.message}`);
@@ -1252,7 +1372,7 @@ function syncGlobalHooksFromRepo(ctx = {}) {
     }
   }
 
-  return { synced, skipped, refused, errors, installedHooks };
+  return { synced, skipped, refused, errors, installedHooks, backups };
 }
 
 /**
@@ -1322,7 +1442,7 @@ async function checkAdapters(checks, mode, gitDirPromise) {
   let issues = 0;
   const adaptersDir = mode === 'local'
     ? path.join(path.dirname(gitDir || ''), 'githooks', 'adapters')
-    : GLOBAL_ADAPTERS_DIR;
+    : GLOBAL_ADAPTERS_DIR();
 
   if (!adaptersDir || !fs.existsSync(adaptersDir)) {
     checks.push({ name: 'Adapters directory', status: 'FAIL', detail: 'Missing' });
@@ -2122,7 +2242,7 @@ function fixHooksByMode(config, srcDir) {
       fixed = fixMissingHooks('local', srcDir, hooksDir) || fixed;
     }
   } else {
-    fixed = fixMissingHooks('global', srcDir, GLOBAL_HOOKS_DIR) || fixed;
+    fixed = fixMissingHooks('global', srcDir, GLOBAL_HOOKS_DIR()) || fixed;
   }
   return fixed;
 }
@@ -2130,8 +2250,8 @@ function fixHooksByMode(config, srcDir) {
 function fixGlobalHooksPath(config) {
   if (config.mode !== 'global') return false;
   const hooksPath = getCurrentHooksPathSync();
-  if (!pathsEquivalent(hooksPath, GLOBAL_HOOKS_DIR)) {
-    return fixCoreHooksPath(GLOBAL_HOOKS_DIR);
+  if (!pathsEquivalent(hooksPath, GLOBAL_HOOKS_DIR())) {
+    return fixCoreHooksPath(GLOBAL_HOOKS_DIR());
   }
   return false;
 }
@@ -2139,7 +2259,7 @@ function fixGlobalHooksPath(config) {
 function getAdaptersDirByMode(config) {
   return config.mode === 'local'
     ? path.join(path.dirname(getGitDirSync() || ''), 'githooks', 'adapters')
-    : GLOBAL_ADAPTERS_DIR;
+    : GLOBAL_ADAPTERS_DIR();
 }
 
 /**
@@ -2200,7 +2320,7 @@ function fixHookDriftFromRepo() {
   }
   if (synced.length === 0) return false;
 
-  console.log(`  ✓ Synced ${synced.join(', ')} from githooks/ to ${GLOBAL_HOOKS_DIR}`);
+  console.log(`  ✓ Synced ${synced.join(', ')} from githooks/ to ${GLOBAL_HOOKS_DIR()}`);
   return true;
 }
 
@@ -2219,8 +2339,8 @@ function fixStaleHooks(config) {
 
     let hooksDestDir, adaptersDestDir;
     if (isGlobal) {
-      hooksDestDir = GLOBAL_HOOKS_DIR;
-      adaptersDestDir = GLOBAL_ADAPTERS_DIR;
+      hooksDestDir = GLOBAL_HOOKS_DIR();
+      adaptersDestDir = GLOBAL_ADAPTERS_DIR();
     } else {
       const gitDir = getGitDirSync();
       if (!gitDir) return false;
@@ -2397,7 +2517,7 @@ async function diagnoseUpgrade() {
  * @returns {number} issue count
  */
 function diagnoseOpenCodePlugin(checks) {
-  const pluginPath = path.join(HOME_DIR, '.config', 'opencode', 'node_modules', '@boyingliu01', 'opencode-plugin', 'package.json');
+  const pluginPath = path.join(HOME_DIR(), '.config', 'opencode', 'node_modules', '@boyingliu01', 'opencode-plugin', 'package.json');
   if (fs.existsSync(pluginPath)) {
     try {
       const pluginPkg = JSON.parse(fs.readFileSync(pluginPath, 'utf8'));
@@ -2566,7 +2686,7 @@ async function doctor(args) {
 
   // §4.13 (#451 REQ-2): explicit one-command sync from the repo's githooks/.
   if (syncHooks) {
-    const { synced, skipped, refused, errors, installedHooks } = syncGlobalHooksFromRepo({ force });
+    const { synced, skipped, refused, errors, installedHooks, backups } = syncGlobalHooksFromRepo({ force });
     if (errors.length > 0) {
       for (const err of errors) console.log(`  ✗ ${err}`);
       return 1;
@@ -2577,6 +2697,11 @@ async function doctor(args) {
     } else {
       console.log(`  ✓ Global hooks already match githooks/ (${skipped.join(', ') || 'nothing to sync'})`);
     }
+    // #566: replacing an installed hook discards whatever was in it. Say where
+    // the previous version went, so a machine-only fix stays recoverable.
+    if (backups.length > 0) {
+      console.log(`    Previous version(s) saved under ${path.join(installedHooks, 'backups')}/ (${backups.length} file(s)).`);
+    }
     if (refused.length > 0) {
       console.log('');
       console.log(`  ⚠️  ${refused.length} shared library file(s) NOT synced — the installed copy`);
@@ -2585,7 +2710,7 @@ async function doctor(args) {
         console.log(`     - ${r.name}: install has ${r.installedOnly} unique line(s), githooks/ has ${r.repoOnly}`);
       }
       console.log('     Review them, then either fold the hardening into githooks/ or re-run --sync-hooks --force.');
-      console.log('     Forcing overwrites the installed file with no backup: copy it aside first.');
+      console.log('     Forcing overwrites the installed file, whose previous version is saved under backups/.');
     }
 
     // #495: the gate modules are what the hook sources for Gates 3/4/7/8/9/10,
@@ -2607,7 +2732,7 @@ async function doctor(args) {
         console.log(`     - ${r.name}: install has ${r.installedOnly} unique line(s), githooks/ has ${r.repoOnly}`);
       }
       console.log('     Review them, then either fold the hardening into githooks/ or re-run --sync-hooks --force.');
-      console.log('     Forcing overwrites the installed file with no backup: copy it aside first.');
+      console.log('     Forcing overwrites the installed file, whose previous version is saved under backups/.');
     }
   }
 
@@ -2785,7 +2910,7 @@ async function doctorDelphi(options = {}) {
   // exists there, so the doctor agrees with the repair command (#414 R1 FC-09).
   const { readQoderModelId } = require('./init.js');
   const roles = ['architecture', 'technical', 'feasibility'];
-  const homeAgentsDir = path.join(HOME_DIR, '.qoder', 'agents');
+  const homeAgentsDir = path.join(HOME_DIR(), '.qoder', 'agents');
   // Injectable for tests; defaults to the cwd the doctor runs from.
   const projectAgentsDir = path.join(options.projectDir || process.cwd(), '.qoder', 'agents');
   const homeComplete = roles.every((r) => fs.existsSync(path.join(homeAgentsDir, `delphi-${r}.md`)));
@@ -2841,10 +2966,10 @@ async function doctorDelphi(options = {}) {
   // references/ too, and B4-style drift hits those equally (#414 R1 MI-03).
   const platform = detectPlatform();
   const installedSkillDir = platform === 'qoder'
-    ? path.join(HOME_DIR, '.qoder', 'skills', 'delphi-review')
+    ? path.join(HOME_DIR(), '.qoder', 'skills', 'delphi-review')
     : platform === 'claude-code'
-      ? path.join(HOME_DIR, '.claude', 'skills', 'delphi-review')
-      : path.join(HOME_DIR, '.config', 'opencode', 'skills', 'delphi-review');
+      ? path.join(HOME_DIR(), '.claude', 'skills', 'delphi-review')
+      : path.join(HOME_DIR(), '.config', 'opencode', 'skills', 'delphi-review');
   // Injectable for tests (#414 R3 FC-01/FC-02): the empty-bundle branch is a
   // real failure mode and must be drivable without mutating the package.
   const bundledSkillDir = options.bundledSkillDir || path.join(PKG_DIR, 'skills', 'delphi-review');
@@ -2941,6 +3066,26 @@ async function doctorDelphi(options = {}) {
         } else {
           add('Delphi config (.delphi-config.json)', 'PASS',
             `profile "${profileName}": ${models.join(' / ')}`);
+          // #574: non-local seats are reported, not blocked. The local-only rule
+          // is an operator preference (the 2026-10-03 quota burn), so doctor
+          // surfaces the cost exposure without failing a deliberately hosted
+          // seat. The HARD enforcement lives in Gate MW, which binds evidence to
+          // whatever this file declares rather than to a local- prefix.
+          // `scripts/check_delphi_local_models.py` holds the same rule with the
+          // same allowlist and exit code; doctor reports it here so the guard
+          // finally has a caller (`xp-gate doctor delphi`) instead of existing
+          // only in its own docstring.
+          const hostedSeats = roles.filter((r) => {
+            const m = models[roles.indexOf(r)];
+            return m && !String(m).toLowerCase().startsWith('local-');
+          });
+          if (hostedSeats.length > 0) {
+            add('Delphi local-model guard (#574)', 'WARN',
+              `hosted (non local-*) seats: ${hostedSeats.map((r) => `${r}=${models[roles.indexOf(r)]}`).join(', ')} — `
+                + 'local-only review is the standing rule; run: python scripts/check_delphi_local_models.py --probe');
+          } else {
+            add('Delphi local-model guard (#574)', 'PASS', `all ${roles.length} seats are local-*`);
+          }
         }
         // #541 follow-up: shadow detection. Loaders fall back to the global
         // config ONLY on ENOENT, so this project file always wins here. If the
@@ -3008,7 +3153,7 @@ async function doctorDelphi(options = {}) {
   // home exists. The two-layer switch (preset capability + host setting)
   // defaults to disabled, and a review that assumes native will silently run
   // three same-model seats.
-  const dshHome = path.join(HOME_DIR, '.dsh');
+  const dshHome = path.join(HOME_DIR(), '.dsh');
   if (!fs.existsSync(dshHome)) {
     add('DSH subagent model selection', 'SKIP', `no ${dshHome} — not a DSH environment`);
   } else {