@boyingliu01/xp-gate 0.19.2 → 0.20.0

package/hooks/pre-push

@@ -89,13 +89,40 @@ while read local_ref local_sha remote_ref remote_sha; do
     echo "   ℹ️  Branch deletion detected ($local_ref). Skipping validation."
     continue
   elif [ "$remote_sha" = "0000000000000000000000000000000000000000" ]; then
-    # New branch - compare cumulative diff vs base branch
-    # Use git merge-base HEAD main/master to find the branch point,
-    # then diff the full branch range. Falls back to HEAD-only diff if no base found.
+    # New ref — a branch or a tag.
+    # Base-branch resolution shared by the tag check below (#491) and the
+    # cumulative new-branch diff.
     BASE_BRANCH="origin/main"
     if ! git rev-parse --verify "$BASE_BRANCH" >/dev/null 2>&1; then
       BASE_BRANCH="origin/master"
     fi
+    # Tag push (#491): a tag carries no code beyond the commit it points at.
+    # If that commit is already published on the base branch, its content
+    # passed these gates when the base ref was pushed. Re-validating it here
+    # false-blocked every release: GATE MW binds evidence to the local HEAD,
+    # and a squash merge rewrote the reviewed commit's hash, so no genuine
+    # evidence could ever match. The scope is deliberately the PROTECTED base
+    # ref, not "any remote-tracking branch": a commit that only ever lived on
+    # a side branch still gets the full gates. A tag on a NOT-yet-published
+    # commit falls through to the cumulative validation below — creating a
+    # tag must not become a path around review. Threat model: like any
+    # client-side hook this bounds honest workflows and accidents, not an
+    # adversary with write access to this repository — such an actor could
+    # forge refs AND the walkthrough evidence file itself; server-side branch
+    # protection remains the real boundary.
+    if [[ "$local_ref" == refs/tags/* ]]; then
+      _tag_commit=$(git rev-parse --verify "${local_sha}^{commit}" 2>/dev/null || true)
+      if [ -z "$_tag_commit" ]; then
+        echo "   ⚠️  Could not dereference $local_ref to a commit — treating it as un-published."
+      elif git rev-parse --verify "$BASE_BRANCH" >/dev/null 2>&1 \
+           && git merge-base --is-ancestor "$_tag_commit" "$BASE_BRANCH" 2>/dev/null; then
+        echo "   ℹ️  Tag $local_ref points at a commit already published on $BASE_BRANCH — no new code content."
+        continue
+      fi
+    fi
+    # New branch (or tag on un-published work) - compare cumulative diff vs base branch
+    # Use git merge-base HEAD main/master to find the branch point,
+    # then diff the full branch range. Falls back to HEAD-only diff if no base found.
     if git rev-parse --verify "$BASE_BRANCH" >/dev/null 2>&1; then
       MERGE_BASE=$(git merge-base HEAD "$BASE_BRANCH" 2>/dev/null)
       if [ -n "$MERGE_BASE" ] && [ "$MERGE_BASE" != "$(git rev-parse HEAD)" ]; then
@@ -123,7 +150,7 @@ fi
 
 # Determine if pushed files contain ONLY documentation/non-source files
 DOC_ONLY=true
-SOURCE_EXTENSIONS="\.py$|\.js$|\.ts$|\.tsx$|\.java$|\.go$|\.rs$|\.cpp$|\.c$|\.swift$|\.kt$|\.sh$|\.dart$|\.ps1$|\.m$|\.mm$|\.h$|\.hpp$"
+SOURCE_EXTENSIONS="\.py$|\.js$|\.cjs$|\.mjs$|\.ts$|\.tsx$|\.java$|\.go$|\.rs$|\.cpp$|\.c$|\.swift$|\.kt$|\.sh$|\.dart$|\.ps1$|\.m$|\.mm$|\.h$|\.hpp$"
 
 for file in $PUSHED_FILES; do
   if echo "$file" | grep -qE "$SOURCE_EXTENSIONS"; then
@@ -152,6 +179,26 @@ echo "Files changed: $FILES_CHANGED"
 echo "Lines: +$LINES_ADDED -$LINES_DELETED"
 echo ""
 
+# Run a TypeScript entrypoint under tsx without routing arguments through the
+# npx shim: Windows cmd.exe caps command lines at 8191 chars and long changed-file
+# lists overflow it, turning a healthy run into a false BLOCK. Prefer the
+# repo-local tsx CLI driven by node directly; keep npx as fallback for consumer
+# repos relying on a global install. RUN_TSX_TIMEOUT (e.g. "120s") wraps the
+# invocation in `timeout`.
+if ! declare -F run_tsx >/dev/null 2>&1; then
+  run_tsx() {
+    local _root="${PROJECT_ROOT:-$(pwd)}" _timeout=()
+    if [ -n "${RUN_TSX_TIMEOUT:-}" ]; then
+      _timeout=(timeout "$RUN_TSX_TIMEOUT")
+    fi
+    if [ -f "$_root/node_modules/tsx/dist/cli.mjs" ] && command -v node >/dev/null 2>&1; then
+      "${_timeout[@]}" node "$_root/node_modules/tsx/dist/cli.mjs" "$@"
+    else
+      "${_timeout[@]}" npx tsx "$@"
+    fi
+  }
+fi
+
 # ============================================================================
 # GATE S: SPRINT FLOW ENFORCEMENT
 # Validates sprint state consistency before push
@@ -161,11 +208,17 @@ GATE_S_STATUS="PASS"
 PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo ".")"
 SPRINT_GATE_SCRIPT=""
 
-if [ -f "$PROJECT_ROOT/githooks/sprint-gate.sh" ]; then
-  SPRINT_GATE_SCRIPT="$PROJECT_ROOT/githooks/sprint-gate.sh"
-elif [ -f "$(dirname "$0")/sprint-gate.sh" ]; then
-  SPRINT_GATE_SCRIPT="$(dirname "$0")/sprint-gate.sh"
-fi
+# Same chain as pre-commit's Gate 11 (#476). The two tiers here both point at
+# gate-script directories, while update-hooks installs sprint-gate.sh under
+# ~/.config/xp-gate/hooks -- a correctly installed machine was told the file was
+# missing here too. Nothing is sourced for this: pre-push resolves its libraries
+# further down (ADAPTER_COMMON), and this gate must decide before that.
+for _sprint_gate_dir in "$PROJECT_ROOT/githooks" "$(dirname "$0")" "$HOME/.config/xp-gate/hooks"; do
+  if [ -n "$_sprint_gate_dir" ] && [ -f "$_sprint_gate_dir/sprint-gate.sh" ]; then
+    SPRINT_GATE_SCRIPT="$_sprint_gate_dir/sprint-gate.sh"
+    break
+  fi
+done
 
 if [ -n "$SPRINT_GATE_SCRIPT" ]; then
   if ! bash "$SPRINT_GATE_SCRIPT" --pre-push; then
@@ -174,7 +227,7 @@ if [ -n "$SPRINT_GATE_SCRIPT" ]; then
     exit 1
   fi
 else
-  echo "⏭️  SKIPPED - Gate MS: Sprint Flow (sprint-gate.sh not found)"
+  echo "⏭️  SKIPPED - Gate MS: Sprint Flow (sprint-gate.sh not found; searched: $PROJECT_ROOT/githooks, $(dirname "$0"), $HOME/.config/xp-gate/hooks)"
   GATE_S_STATUS="SKIP"
 fi
 echo ""
@@ -210,7 +263,7 @@ if [[ -f "package.json" ]] && [[ -f "tsconfig.json" ]] && [[ -n "$TS_FILES" ]];
     done <<< "$TS_FILES"
 
     GATE_10_OUTPUT=$(mktemp)
-    if timeout 120s npx tsx "$GATE_10_SCRIPT" --changed-files "$GATE_10_FILE_LIST" --project-root "$PROJECT_ROOT" > "$GATE_10_OUTPUT" 2>&1; then
+    if RUN_TSX_TIMEOUT=120s run_tsx "$GATE_10_SCRIPT" --changed-files "$GATE_10_FILE_LIST" --project-root "$PROJECT_ROOT" > "$GATE_10_OUTPUT" 2>&1; then
       cat "$GATE_10_OUTPUT"
       GATE_10_STATUS="PASS"
       echo "✅ Gate 10: PASS"
@@ -274,8 +327,11 @@ else
     echo "⚠️ Stryker config not found or @stryker-mutator not installed."
     echo "   SKIP — Gate M mutation testing."
   else
-    # Filter to source files (exclude tests)
-    CHANGED_SOURCE_FILES=$(echo "$TS_FILES" | grep -v '__tests__' | grep -v '\.test\.' | grep -v '\.spec\.' | grep -v '\.d\.ts$' || true)
+    # Filter to source files (exclude tests). The tree-segment grep excludes
+    # test infrastructure (helpers/fixtures under tests/, test/, __tests__/)
+    # that is not named *.test.* -- it must be judged by the suites that run
+    # it, not by a mutation score budgeted for production code (#480).
+    CHANGED_SOURCE_FILES=$(echo "$TS_FILES" | grep -v '__tests__' | grep -v '\.test\.' | grep -v '\.spec\.' | grep -v '\.d\.ts$' | grep -v -E '(^|/)(tests?|__tests__)/' || true)
 
     if [ -z "$CHANGED_SOURCE_FILES" ]; then
       echo "📚 No changed TypeScript source files. SKIP — Gate M."
@@ -298,7 +354,7 @@ else
       else
         # Run mutation gate with timeout matching stryker.conf.json (timeoutMS: 600000 = 10min)
         MUTATION_OUTPUT=$(mktemp)
-        timeout 600s npx tsx $MUTATION_SCRIPT --changed-files "$CHANGED_SOURCE_FILES" > "$MUTATION_OUTPUT" 2>&1
+        RUN_TSX_TIMEOUT=600s run_tsx $MUTATION_SCRIPT --changed-files "$CHANGED_SOURCE_FILES" > "$MUTATION_OUTPUT" 2>&1
         MUTATION_EXIT=$?
 
         case $MUTATION_EXIT in
@@ -361,7 +417,7 @@ else
   if detect_python_mutation_testable 2>/dev/null; then
     if [ -f "src/mutation/gate-m.ts" ]; then
       MUTATION_OUTPUT=$(mktemp)
-      timeout 120s npx tsx src/mutation/gate-m.ts --changed-files "$PYTHON_FILE_LIST" > "$MUTATION_OUTPUT" 2>&1
+      RUN_TSX_TIMEOUT=120s run_tsx src/mutation/gate-m.ts --changed-files "$PYTHON_FILE_LIST" > "$MUTATION_OUTPUT" 2>&1
       MUTATION_EXIT=$?
 
       case $MUTATION_EXIT in
@@ -430,7 +486,7 @@ else
       echo "⚠ Gate M script not found. SKIP — Gate M (Go)."
     else
       MUTATION_OUTPUT=$(mktemp)
-      timeout 120s npx tsx "$MUTATION_SCRIPT" --changed-files "$GO_FILE_LIST" --timeout-ms 120000 > "$MUTATION_OUTPUT" 2>&1
+      RUN_TSX_TIMEOUT=120s run_tsx "$MUTATION_SCRIPT" --changed-files "$GO_FILE_LIST" --timeout-ms 120000 > "$MUTATION_OUTPUT" 2>&1
       MUTATION_EXIT=$?
 
       case $MUTATION_EXIT in
@@ -500,7 +556,7 @@ else
       echo "⚠ Gate M script not found. SKIP — Gate M (Java)."
     else
       MUTATION_OUTPUT=$(mktemp)
-      timeout 600s npx tsx "$MUTATION_SCRIPT" --changed-files "$JAVA_FILE_LIST" --timeout-ms 600000 > "$MUTATION_OUTPUT" 2>&1
+      RUN_TSX_TIMEOUT=600s run_tsx "$MUTATION_SCRIPT" --changed-files "$JAVA_FILE_LIST" --timeout-ms 600000 > "$MUTATION_OUTPUT" 2>&1
       MUTATION_EXIT=$?
 
       case $MUTATION_EXIT in
@@ -570,7 +626,7 @@ else
       echo "⚠ Gate M script not found. SKIP — Gate M (Kotlin)."
     else
       MUTATION_OUTPUT=$(mktemp)
-      timeout 600s npx tsx "$MUTATION_SCRIPT" --changed-files "$KT_FILE_LIST" --timeout-ms 600000 > "$MUTATION_OUTPUT" 2>&1
+      RUN_TSX_TIMEOUT=600s run_tsx "$MUTATION_SCRIPT" --changed-files "$KT_FILE_LIST" --timeout-ms 600000 > "$MUTATION_OUTPUT" 2>&1
       MUTATION_EXIT=$?
 
       case $MUTATION_EXIT in
@@ -752,7 +808,7 @@ run_gate_m3() {
     [[ -n "$f" ]] && args+=("$f")
   done <<< "$test_files"
 
-  if npx tsx "$GATE_M3_SCRIPT" "${args[@]}"; then
+  if run_tsx "$GATE_M3_SCRIPT" "${args[@]}"; then
     echo "✅ Gate ML: PASS"
     return 0
   else

package/lib/__tests__/bootstrap.test.js

@@ -1,78 +1,60 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
 const { bootstrap } = require('../bootstrap.js');
 
+const GATE_TOOLS = ['jscpd', 'lizard', 'checkov', 'hadolint', 'gitleaks', 'semgrep', 'npx', 'jq'];
+
 describe('bootstrap', () => {
   let consoleLogSpy;
-
+  let realPath;
+  let stubDir;
+
+  // The module mocks these tests used to declare were never applied: bootstrap.js
+  // is CommonJS, so its internal require of detect-deps.js bypasses the mock
+  // registry and every case fell through to the real installer (global npm/pip
+  // installs, ~60s in CI). Stubbing the tools on PATH exercises the real
+  // detection path without touching the environment.
   beforeEach(() => {
     consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    realPath = process.env.PATH;
+    stubDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-gate-bootstrap-'));
+    for (const tool of GATE_TOOLS) {
+      const stub = path.join(stubDir, process.platform === 'win32' ? `${tool}.cmd` : tool);
+      fs.writeFileSync(stub, process.platform === 'win32' ? '@echo 1.0.0\r\n' : '#!/bin/sh\necho 1.0.0\n');
+      if (process.platform !== 'win32') fs.chmodSync(stub, 0o755);
+    }
+    process.env.PATH = `${stubDir}${path.delimiter}${realPath}`;
   });
 
   afterEach(() => {
+    process.env.PATH = realPath;
+    fs.rmSync(stubDir, { recursive: true, force: true });
     vi.restoreAllMocks();
   });
 
   it('returns 0 when --dry-run given with no missing tools', () => {
-    vi.mock('../detect-deps.js', () => ({
-      GATE_CLI_TOOLS: [],
-      checkCliTool: () => ({ available: true }),
-      getToolInstallCmd: () => 'echo done',
-    }));
-
-    const { bootstrap } = require('../bootstrap.js');
     const code = bootstrap(['--dry-run']);
     expect(code).toBe(0);
-    vi.restoreAllMocks();
   });
 
   it('returns 0 when all CLI tools are available', () => {
-    vi.mock('../detect-deps.js', () => ({
-      GATE_CLI_TOOLS: [{ tool: 'testtool', gates: ['Gate 1'], install: { linux: 'echo ok' } }],
-      checkCliTool: () => ({ available: true, version: '1.0' }),
-      getToolInstallCmd: () => 'echo ok',
-    }));
-
-    const { bootstrap } = require('../bootstrap.js');
     const code = bootstrap([]);
     expect(code).toBe(0);
-    vi.restoreAllMocks();
   });
 
   it('accepts --lang ts parameter', () => {
-    vi.mock('../detect-deps.js', () => ({
-      GATE_CLI_TOOLS: [],
-      checkCliTool: () => ({ available: true }),
-      getToolInstallCmd: () => 'echo done',
-    }));
-
-    const { bootstrap } = require('../bootstrap.js');
     const code = bootstrap(['--lang', 'ts']);
     expect(code).toBe(0);
-    vi.restoreAllMocks();
   });
 
   it('accepts --lang ts,py parameter', () => {
-    vi.mock('../detect-deps.js', () => ({
-      GATE_CLI_TOOLS: [],
-      checkCliTool: () => ({ available: true }),
-      getToolInstallCmd: () => 'echo done',
-    }));
-
-    const { bootstrap } = require('../bootstrap.js');
     const code = bootstrap(['--lang', 'ts,py']);
     expect(code).toBe(0);
-    vi.restoreAllMocks();
   });
 
   it('recognizes --verbose flag without error', () => {
-    vi.mock('../detect-deps.js', () => ({
-      GATE_CLI_TOOLS: [],
-      checkCliTool: () => ({ available: true }),
-      getToolInstallCmd: () => 'echo done',
-    }));
-
-    const { bootstrap } = require('../bootstrap.js');
     const code = bootstrap(['--verbose']);
     expect(code).toBe(0);
-    vi.restoreAllMocks();
   });
 });

package/lib/__tests__/check-version.test.js

@@ -318,7 +318,14 @@ describe('check-version.js — REQ-001-01', () => {
       const r = await mod.getRemoteVersion('@nonexistent/pkg-test-only');
       // Without network: null. With network (npm registry proxy): object.
       expect(r === null || (typeof r.latest === 'string')).toBe(true);
-    });
+      // This case performs a real registry lookup, so it must be given a budget
+      // ABOVE the module's own NETWORK_TIMEOUT_MS (5000). At vitest's 5000ms
+      // default the two race, and on a machine where the registry is slow or
+      // unreachable the test failed as "Test timed out" -- reporting a stuck test
+      // rather than the graceful degradation it exists to verify. Raised here
+      // rather than lowering the module timeout, which is deliberate production
+      // behaviour.
+    }, 20000);
 
     // AC-001-02-A: writeCache rejects non-semver versions from registry response
     function evictCache() {

package/lib/__tests__/detect-deps.test.js

@@ -285,6 +285,22 @@ describe('detect-deps', () => {
       const { detectPlatform } = require('../detect-deps');
       expect(detectPlatform()).toBe('qoder');
     });
+
+    // ── #424: brand-new Qoder installs have no skills/ subdirectory yet, so a
+    // skills-only marker misdetects them as opencode and configureQoderDelphiAgents
+    // deploys zero Delphi agents. Any ~/.qoder content must count as qoder. ──
+
+    it('returns "qoder" when only ~/.qoder exists (brand-new install, no skills dir)', () => {
+      fs.mkdirSync(path.join(tmpHome, '.qoder'), { recursive: true });
+      const { detectPlatform } = require('../detect-deps');
+      expect(detectPlatform()).toBe('qoder');
+    });
+
+    it('returns "qoder" when only ~/.qoder/agents exists (no skills dir)', () => {
+      fs.mkdirSync(path.join(tmpHome, '.qoder', 'agents'), { recursive: true });
+      const { detectPlatform } = require('../detect-deps');
+      expect(detectPlatform()).toBe('qoder');
+    });
   });
 
   // ── getSkillsDirs tests ──

package/lib/__tests__/doctor-drift-round2.test.js

@@ -0,0 +1,212 @@
+/**
+ * @test REQ-495 Round 2: the drift surface must not lie in either direction
+ * @intent 三位专家对 origin/main..HEAD 的走查给出三条同族判定：(1) 字节不同但行集
+ *         相同（仅行尾/缩进差异）落入 moduleDriftDetail 兜底分支，报 FAIL 却写着
+ *         "0 line(s) absent from the repo"，方向断言为伪且 --fix 清不掉；(2)
+ *         diagnoseModuleDrift 认 XP_GATE_REPO_ROOT 而 syncModulesFromRepo 只认
+ *         process.cwd()，在仓库外带 env 运行 --sync-hooks 时诊断报 FAIL、同步静默
+ *         空转（#488/#416 已明令禁止的"被忽略的选项"缺陷类）；(3) drift 结果被
+ *         Promise.race 的全局 10s 超时整份丢弃并返回 issues:0，doctor 随即打印
+ *         "✓ All checks passed" —— 正是 #495 要消灭的"模块陈旧但 doctor 全绿"。
+ *         外加 lib/ 通道：syncGlobalHooksFromRepo 对 githooks/lib/*.sh 无条件覆盖，
+ *         而同一次发布里模块同步对同类风险显式拒绝，破坏性写入标准不对称。
+ * @covers AC-495-07, AC-495-08, AC-495-09, AC-495-10, AC-495-13, AC-488-05
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+function fixture(spec) {
+  const root = mkdtempSync(join(tmpdir(), 'xp-gate-r2-'));
+  const repoHooks = join(root, 'githooks');
+  const installedHooks = join(root, 'hooks');
+  const installedAdapters = join(root, 'adapters');
+  mkdirSync(join(repoHooks, 'adapters'), { recursive: true });
+  mkdirSync(join(repoHooks, 'lib'), { recursive: true });
+  mkdirSync(installedHooks, { recursive: true });
+  mkdirSync(installedHooks + '/lib', { recursive: true });
+  mkdirSync(installedAdapters, { recursive: true });
+
+  const write = (file, text) => {
+    mkdirSync(join(file, '..'), { recursive: true });
+    writeFileSync(file, text);
+  };
+
+  for (const [name, sides] of Object.entries(spec)) {
+    const rootLevel = name.startsWith('gate-') || name === 'adapter-common.sh' || name.startsWith('lib/');
+    if (sides.repo !== null) {
+      write(join(repoHooks, rootLevel ? name : join('adapters', name)), sides.repo);
+    }
+    if (sides.installed !== undefined && sides.installed !== null) {
+      write(join(installedAdapters, name), sides.installed);
+    }
+    // lib/ lives under hooks/, not under the adapters dir, so it needs its own pair.
+    if (sides.installedLib !== undefined) {
+      write(join(installedHooks, name), sides.installedLib);
+    }
+  }
+
+  write(join(repoHooks, 'pre-commit'), '#!/bin/bash\necho repo\n');
+  write(join(installedHooks, 'pre-commit'), '#!/bin/bash\necho repo\n');
+
+  // Resolution anchors: the installed dir only becomes ADAPTER_DIR / GATE_DIR if
+  // adapter-common.sh (githooks/pre-commit:34) and gate-3.sh (:80) live in it.
+  // Without them the fixture describes a tier the hook never resolves to, and the
+  // comparison silently targets a directory outside the test (#495 Round 3).
+  const ANCHOR = '#!/bin/bash\nanchor\n';
+  for (const anchor of ['adapter-common.sh', 'gate-3.sh']) {
+    if (spec[anchor]) continue;
+    write(join(repoHooks, anchor), ANCHOR);
+    write(join(installedAdapters, anchor), ANCHOR);
+  }
+
+  return { root, repoHooks, installedHooks, installedAdapters, write };
+}
+
+/**
+ * Name every tier the hook can resolve into so no fixture can reach this
+ * machine's real `~/.config/xp-gate`.
+ */
+function ctxFor(f, extra = {}) {
+  return {
+    repoRoot: f.root,
+    repoHooks: f.repoHooks,
+    installedAdapters: f.installedAdapters,
+    scriptDir: f.installedHooks,
+    ...extra,
+  };
+}
+
+describe('doctor drift Round 2 (#495)', () => {
+  it('AC-495-07: a line-ending-only difference is not reported as drift, and never claims zero unique lines', () => {
+    const { diagnoseModuleDrift } = require('../doctor');
+    const repo = '#!/bin/bash\ngate_line_one\ngate_line_two\n';
+    const f = fixture({
+      'gate-4.sh': { repo, installed: repo.replace(/\n/g, '\r\n') },
+    });
+
+    const result = diagnoseModuleDrift(ctxFor(f));
+    const check = result.checks.find((c) => c.name === 'Module drift: gate-4.sh');
+    expect(check).toBeDefined();
+    expect(check.status).not.toBe('FAIL');
+    expect(result.issues).toBe(0);
+    // The self-contradicting verdict ("newer ... 0 line(s) absent") must be gone.
+    expect(check.detail).not.toMatch(/0 line\(s\)/);
+  });
+
+  it('AC-495-08: sync resolves the repo root the same way the diagnosis does', () => {
+    const { syncModulesFromRepo, diagnoseModuleDrift } = require('../doctor');
+    const f = fixture({
+      'gate-4.sh': { repo: '#!/bin/bash\nline_a\nline_b\n', installed: '#!/bin/bash\nline_a\n' },
+    });
+
+    // Run from OUTSIDE the repository with the repo located by env only.
+    const previous = process.env.XP_GATE_REPO_ROOT;
+    process.env.XP_GATE_REPO_ROOT = f.root;
+    try {
+      const diagnosis = diagnoseModuleDrift(ctxFor(f));
+      expect(diagnosis.issues).toBe(1);
+
+      // Only the install target is named: the repo must come from the same env
+      // the diagnosis used, or the FAIL this produces can never be cleared.
+      const synced = syncModulesFromRepo({ installedAdapters: f.installedAdapters, scriptDir: f.installedHooks });
+      expect(synced.synced).toContain('gate-4.sh');
+      expect(readFileSync(join(f.installedAdapters, 'gate-4.sh'), 'utf8')).toContain('line_b');
+      expect(diagnoseModuleDrift(ctxFor(f)).issues).toBe(0);
+    } finally {
+      if (previous === undefined) delete process.env.XP_GATE_REPO_ROOT;
+      else process.env.XP_GATE_REPO_ROOT = previous;
+    }
+  });
+
+  it('AC-495-09: sync with no canonical repo source says so instead of returning an empty success', () => {
+    const { syncModulesFromRepo } = require('../doctor');
+    const root = mkdtempSync(join(tmpdir(), 'xp-gate-r2-nosource-'));
+    const installedAdapters = join(root, 'adapters');
+    mkdirSync(installedAdapters, { recursive: true });
+    writeFileSync(join(installedAdapters, 'gate-4.sh'), '#!/bin/bash\ninstalled\n');
+
+    const previous = process.env.XP_GATE_REPO_ROOT;
+    process.env.XP_GATE_REPO_ROOT = root; // no githooks/ under here at all
+    try {
+      const result = syncModulesFromRepo({ repoRoot: root, installedAdapters });
+      expect(result.sourceMissing).toBe(true);
+      expect(result.errors.join('\n')).toMatch(/no (canonical )?githooks/i);
+    } finally {
+      if (previous === undefined) delete process.env.XP_GATE_REPO_ROOT;
+      else process.env.XP_GATE_REPO_ROOT = previous;
+    }
+  });
+
+  it('AC-495-10: a timed-out diagnosis can never print "All checks passed"', () => {
+    const source = readFileSync(join(__dirname, '..', 'doctor.js'), 'utf8');
+
+    // The race outcome must carry timedOut out of the destructuring...
+    expect(source).toMatch(/const \{[^}]*timedOut[^}]*\} = await Promise\.race/);
+    // ...and branch on it, because a timeout discards every computed FAIL.
+    expect(source).toMatch(/if \(timedOut\)[\s\S]{0,200}issues\s*(\+\+|\+=|= Math\.max)/);
+  });
+
+  it('AC-495-13: a flat copy inside the project githooks/ is diagnosed when the project tier is what executes', () => {
+    const { diagnoseModuleDrift } = require('../doctor');
+    // Project mode (no global install): pre-commit:36-37 resolves ADAPTER_DIR to
+    // <repo>/githooks, and resolve_adapter_path() then tries $ADAPTER_DIR/<lang>.sh
+    // before the nested source. The installer wrote those flat copies once and
+    // .gitignore:42 keeps them out of the repo, so a later repo fix that only
+    // touches adapters/<lang>.sh leaves the stale flat copy executing -- a
+    // #493-class repair inert in the very repository that shipped it.
+    const root = mkdtempSync(join(tmpdir(), 'xp-gate-project-tier-'));
+    const repoHooks = join(root, 'githooks');
+    mkdirSync(join(repoHooks, 'adapters'), { recursive: true });
+    writeFileSync(join(repoHooks, 'pre-commit'), '#!/bin/bash\necho repo\n');
+    writeFileSync(join(repoHooks, 'adapter-common.sh'), '#!/bin/bash\nshared\n');
+    writeFileSync(join(repoHooks, 'gate-3.sh'), '#!/bin/bash\ngate3\n');
+    writeFileSync(join(repoHooks, 'adapters', 'iac.sh'), '#!/bin/bash\nfixed_count_guard\n');
+    writeFileSync(join(repoHooks, 'iac.sh'), '#!/bin/bash\nstale_echo_zero\n');
+
+    const result = diagnoseModuleDrift({
+      repoRoot: root,
+      installedAdapters: join(root, 'nothing-installed-globally'),
+      scriptDir: join(root, 'nothing-installed-hooks'),
+    });
+
+    const projectCheck = result.checks.find((c) => /Module drift \(project\): iac\.sh/.test(c.name));
+    expect(projectCheck, 'the executed project-tier flat copy is invisible to doctor').toBeDefined();
+    expect(projectCheck.status).toBe('FAIL');
+    // The verdict has to say what to do with a gitignored installer residue.
+    expect(projectCheck.detail).toMatch(/flat|shadow/i);
+    expect(result.issues).toBe(1);
+  });
+
+  it('AC-488-05: lib/ sync refuses an installed library the repo does not have lines for', () => {
+    const { syncGlobalHooksFromRepo } = require('../doctor');
+    const f = fixture({
+      'lib/test-failure.sh': {
+        repo: '#!/bin/bash\nrepo_shared_helper\n',
+        installedLib: '#!/bin/bash\ninstalled_machine_hardening\n',
+      },
+    });
+
+    const result = syncGlobalHooksFromRepo({
+      repoHooks: f.repoHooks,
+      installedHooks: f.installedHooks,
+    });
+
+    expect(result.refused.map((r) => r.name)).toContain('lib/test-failure.sh');
+    expect(readFileSync(join(f.installedHooks, 'lib', 'test-failure.sh'), 'utf8'))
+      .toContain('installed_machine_hardening');
+    expect(existsSync(join(f.installedHooks, 'lib', 'test-failure.sh'))).toBe(true);
+
+    // A one-way-stale library still syncs: the guard is for divergence, not staleness.
+    const stale = fixture({
+      'lib/test-failure.sh': {
+        repo: '#!/bin/bash\nshared_a\nshared_b\n',
+        installedLib: '#!/bin/bash\nshared_a\n',
+      },
+    });
+    const second = syncGlobalHooksFromRepo({ repoHooks: stale.repoHooks, installedHooks: stale.installedHooks });
+    expect(second.synced).toContain('lib/test-failure.sh');
+    expect(readFileSync(join(stale.installedHooks, 'lib', 'test-failure.sh'), 'utf8')).toContain('shared_b');
+  });
+});