diff --git a/.github/scripts/check-tree-sitter-upgrade-readiness.py b/.github/scripts/check-tree-sitter-upgrade-readiness.py
index f54afd7f08..5b0fad09e5 100644
--- a/.github/scripts/check-tree-sitter-upgrade-readiness.py
+++ b/.github/scripts/check-tree-sitter-upgrade-readiness.py
@@ -32,6 +32,7 @@
 import re
 import sys
 import urllib.error
+import urllib.parse
 import urllib.request
 
 REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
@@ -190,7 +191,17 @@ def fetch_text(url: str, timeout: int = 8) -> str | None:
     set (raises the rate limit from 60 to 5 000 requests/hour).
     """
     headers: dict[str, str] = {}
-    if _GITHUB_TOKEN and ("github.com" in url or "githubusercontent.com" in url):
+    # Parse the URL and check the hostname rather than substring-matching
+    # on the full URL string (CodeQL py/incomplete-url-substring-sanitization).
+    # `https://evil.com/?u=github.com` would have passed the substring check.
+    try:
+        parsed_host = urllib.parse.urlparse(url).hostname or ""
+    except ValueError:
+        parsed_host = ""
+    is_github_host = parsed_host == "github.com" or parsed_host.endswith(
+        (".github.com", ".githubusercontent.com")
+    ) or parsed_host == "githubusercontent.com"
+    if _GITHUB_TOKEN and is_github_host:
         headers["Authorization"] = f"Bearer {_GITHUB_TOKEN}"
     try:
         req = urllib.request.Request(url, headers=headers)
diff --git a/.github/workflows/ci-report.yml b/.github/workflows/ci-report.yml
index ab8d8362c4..03908bb2ba 100644
--- a/.github/workflows/ci-report.yml
+++ b/.github/workflows/ci-report.yml
@@ -138,14 +138,15 @@ jobs:
             const fs = require('fs');
             const path = require('path');
 
-            // Find the latest successful CI run on main
+            // Find recent successful CI runs on main (check several in case
+            // the most recent artifact has expired).
             const runs = await github.rest.actions.listWorkflowRuns({
               owner: context.repo.owner,
               repo: context.repo.repo,
               workflow_id: 'ci.yml',
               branch: 'main',
               status: 'success',
-              per_page: 1,
+              per_page: 5,
             });
 
             if (runs.data.workflow_runs.length === 0) {
@@ -154,32 +155,47 @@ jobs:
               return;
             }
 
-            const mainRunId = runs.data.workflow_runs[0].id;
-            const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              run_id: mainRunId,
-            });
+            // Try each run until we find a downloadable test-reports artifact
+            for (const run of runs.data.workflow_runs) {
+              const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                run_id: run.id,
+              });
 
-            const testReports = artifacts.data.artifacts.find(a => a.name === 'test-reports');
-            if (!testReports) {
-              core.setOutput('found', 'false');
-              core.info('No test-reports artifact on main branch');
-              return;
-            }
+              const testReports = artifacts.data.artifacts.find(a => a.name === 'test-reports');
+              if (!testReports) {
+                core.info(`Run ${run.id}: no test-reports artifact, trying next`);
+                continue;
+              }
 
-            const zip = await github.rest.actions.downloadArtifact({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              artifact_id: testReports.id,
-              archive_format: 'zip',
-            });
+              try {
+                const zip = await github.rest.actions.downloadArtifact({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  artifact_id: testReports.id,
+                  archive_format: 'zip',
+                });
+
+                const dest = path.join(process.env.RUNNER_TEMP, 'base-coverage');
+                fs.mkdirSync(dest, { recursive: true });
+                fs.writeFileSync(path.join(dest, 'base.zip'), Buffer.from(zip.data));
+                core.setOutput('found', 'true');
+                core.setOutput('dir', dest);
+                return;
+              } catch (err) {
+                // 410 Gone means the artifact expired; try the next run
+                if (err.status === 410 || err.response?.status === 410) {
+                  core.info(`Run ${run.id}: artifact expired, trying next`);
+                  continue;
+                }
+                throw err;
+              }
+            }
 
-            const dest = path.join(process.env.RUNNER_TEMP, 'base-coverage');
-            fs.mkdirSync(dest, { recursive: true });
-            fs.writeFileSync(path.join(dest, 'base.zip'), Buffer.from(zip.data));
-            core.setOutput('found', 'true');
-            core.setOutput('dir', dest);
+            // All attempts exhausted — no usable base coverage
+            core.setOutput('found', 'false');
+            core.info('No downloadable test-reports artifact found on main (all expired or missing)');
 
       - name: Extract base coverage
         if: steps.meta.outputs.skip != 'true' && steps.base-coverage.outputs.found == 'true'
@@ -234,7 +250,7 @@ jobs:
               printf -v "${prefix}_BRANCH_COV" '%s' ""
               printf -v "${prefix}_FUNCS_COV" '%s' ""
               printf -v "${prefix}_LINES_COV" '%s' ""
-              return 1
+              return 0
             fi
           }
 
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 9100256833..f377cba6c3 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -4,6 +4,38 @@ import unusedImports from 'eslint-plugin-unused-imports';
 import reactHooks from 'eslint-plugin-react-hooks';
 import prettierConfig from 'eslint-config-prettier';
 
+// Selectors that protect MCP-reachable code from corrupting the JSON-RPC
+// stdio frame stream. The MCP-reachable block below uses these directly;
+// the lbug-adapter file-specific block must spread them in too because
+// ESLint flat config REPLACES (not merges) `no-restricted-syntax` when
+// multiple matching configs target the same file. Extracting to a const
+// makes the dependency mechanical instead of documentation-enforced.
+const mcpStdoutWriteSelectors = [
+  {
+    selector:
+      "MemberExpression[object.type='MemberExpression'][object.object.name='process'][object.property.name='stdout'][property.name='write']",
+    message:
+      'Direct process.stdout.write is forbidden in MCP-reachable code. Route diagnostics through console.error or process.stderr.write — the MCP stdio transport owns stdout for JSON-RPC frames.',
+  },
+  {
+    selector:
+      "CallExpression[callee.type='MemberExpression'][callee.object.type='MemberExpression'][callee.object.object.name='process'][callee.object.property.name='stdout'][callee.property.name='write']",
+    message:
+      'Direct process.stdout.write is forbidden in MCP-reachable code. Route diagnostics through console.error or process.stderr.write — the MCP stdio transport owns stdout for JSON-RPC frames.',
+  },
+  {
+    // Catches the canonical destructuring shape:
+    //   const { write } = process.stdout;
+    // (and any other ObjectPattern destructure rooted at process.stdout)
+    // which would otherwise capture a reference to the original write
+    // and bypass the sentinel.
+    selector:
+      "VariableDeclarator[init.type='MemberExpression'][init.object.name='process'][init.property.name='stdout'] > ObjectPattern",
+    message:
+      'Destructuring process.stdout is forbidden in MCP-reachable code — bypasses the sentinel. Use process.stderr.write for diagnostics.',
+  },
+];
+
 export default [
   // Global ignores
   {
@@ -59,11 +91,26 @@ export default [
     },
   },
 
-  // CLI package — allow console.log (it's a CLI tool)
+  // CLI/server packages — `console.log` IS the contract (CLI tool data output
+  // on stdout, e.g. `gitnexus query | jq`; server pretty-printed banners).
+  // Diagnostic logging (`warn`/`error`/`debug`/`info`) goes through pino like
+  // the rest of the codebase.
   {
     files: ['gitnexus/src/cli/**/*.ts', 'gitnexus/src/server/**/*.ts'],
     rules: {
-      'no-console': 'off',
+      'no-console': ['error', { allow: ['log'] }],
+    },
+  },
+
+  // Forcing function for the pino migration. Severity is `error` — the
+  // codebase-wide migration is complete; new `console.*` in core source
+  // must fail lint. CLI/server are exempt above (legitimate stdout output).
+  // Tests, bin scripts, and the logger module itself remain exempt.
+  {
+    files: ['gitnexus/src/**/*.ts'],
+    ignores: ['gitnexus/src/cli/**', 'gitnexus/src/server/**', 'gitnexus/src/core/logger.ts'],
+    rules: {
+      'no-console': 'error',
     },
   },
 
@@ -84,32 +131,7 @@ export default [
     ],
     rules: {
       'no-console': ['error', { allow: ['error'] }],
-      'no-restricted-syntax': [
-        'error',
-        {
-          selector:
-            "MemberExpression[object.type='MemberExpression'][object.object.name='process'][object.property.name='stdout'][property.name='write']",
-          message:
-            'Direct process.stdout.write is forbidden in MCP-reachable code. Route diagnostics through console.error or process.stderr.write — the MCP stdio transport owns stdout for JSON-RPC frames.',
-        },
-        {
-          selector:
-            "CallExpression[callee.type='MemberExpression'][callee.object.type='MemberExpression'][callee.object.object.name='process'][callee.object.property.name='stdout'][callee.property.name='write']",
-          message:
-            'Direct process.stdout.write is forbidden in MCP-reachable code. Route diagnostics through console.error or process.stderr.write — the MCP stdio transport owns stdout for JSON-RPC frames.',
-        },
-        {
-          // Catches the canonical destructuring shape:
-          //   const { write } = process.stdout;
-          // (and any other ObjectPattern destructure rooted at process.stdout)
-          // which would otherwise capture a reference to the original write
-          // and bypass the sentinel.
-          selector:
-            "VariableDeclarator[init.type='MemberExpression'][init.object.name='process'][init.property.name='stdout'] > ObjectPattern",
-          message:
-            'Destructuring process.stdout is forbidden in MCP-reachable code — bypasses the sentinel. Use process.stderr.write for diagnostics.',
-        },
-      ],
+      'no-restricted-syntax': ['error', ...mcpStdoutWriteSelectors],
     },
   },
 
@@ -129,11 +151,18 @@ export default [
   // All close operations must go through safeClose() so the WAL is always
   // flushed before the connection is released. The sole authorised call site
   // inside safeClose itself uses an eslint-disable-next-line override.
+  //
+  // ESLint flat config REPLACES (not merges) `no-restricted-syntax` when
+  // multiple matching configs target the same file. lbug-adapter.ts is also
+  // covered by the MCP-reachable block above, so we spread the shared
+  // mcpStdoutWriteSelectors here alongside the safeClose selectors. Without
+  // this, lbug-adapter would silently lose its MCP stdout-write protection.
   {
     files: ['gitnexus/src/core/lbug/lbug-adapter.ts'],
     rules: {
       'no-restricted-syntax': [
         'error',
+        ...mcpStdoutWriteSelectors,
         {
           selector: "CallExpression[callee.object.name='conn'][callee.property.name='close']",
           message: 'Use safeClose() instead of calling conn.close() directly (#1376).',
diff --git a/gitnexus-web/src/core/llm/agent.ts b/gitnexus-web/src/core/llm/agent.ts
index c8cfa8d7cc..49862a9e6a 100644
--- a/gitnexus-web/src/core/llm/agent.ts
+++ b/gitnexus-web/src/core/llm/agent.ts
@@ -277,8 +277,10 @@ const extractInstanceName = (endpoint: string): string => {
   try {
     const url = new URL(endpoint);
     const hostname = url.hostname;
-    // Extract the first part before .openai.azure.com
-    const match = hostname.match(/^([^.]+)\.openai\.azure\.com/);
+    // Extract the first part before .openai.azure.com. The trailing `$`
+    // anchor is required (CodeQL js/regex/missing-regexp-anchor): without
+    // it `evil.openai.azure.com.attacker.tld` would match.
+    const match = hostname.match(/^([^.]+)\.openai\.azure\.com$/);
     if (match) {
       return match[1];
     }
diff --git a/gitnexus-web/src/core/llm/tools.ts b/gitnexus-web/src/core/llm/tools.ts
index cd0b5a8008..5a595049e0 100644
--- a/gitnexus-web/src/core/llm/tools.ts
+++ b/gitnexus-web/src/core/llm/tools.ts
@@ -278,8 +278,11 @@ export const createGraphRAGTools = (backend: GraphRAGBackend) => {
                 const val = row[col];
                 if (val === null || val === undefined) return '';
                 if (typeof val === 'object') return JSON.stringify(val);
-                // Truncate long values and escape pipe characters
-                const str = String(val).replace(/\|/g, '\\|');
+                // Truncate long values and escape pipe characters. Escape
+                // backslashes FIRST so the subsequent pipe escape isn't
+                // unescaped by a trailing backslash (CodeQL
+                // js/incomplete-sanitization).
+                const str = String(val).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
                 return str.length > 60 ? str.slice(0, 57) + '...' : str;
               });
               return `| ${values.join(' | ')} |`;
diff --git a/gitnexus/package-lock.json b/gitnexus/package-lock.json
index ccc61bc5b2..b07ccd7cb8 100644
--- a/gitnexus/package-lock.json
+++ b/gitnexus/package-lock.json
@@ -30,6 +30,8 @@
         "mnemonist": "^0.40.3",
         "onnxruntime-node": "^1.24.0",
         "pandemonium": "^2.4.0",
+        "pino": "^10.3.1",
+        "pino-pretty": "^13.1.3",
         "tree-sitter": "^0.21.1",
         "tree-sitter-c": "0.21.4",
         "tree-sitter-c-sharp": "0.23.1",
@@ -1579,6 +1581,12 @@
         "url": "https://github.com/sponsors/Boshen"
       }
     },
+    "node_modules/@pinojs/redact": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/@pinojs/redact/-/redact-0.4.0.tgz",
+      "integrity": "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg==",
+      "license": "MIT"
+    },
     "node_modules/@protobufjs/aspromise": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
@@ -2057,9 +2065,9 @@
       "license": "MIT"
     },
     "node_modules/@types/node": {
-      "version": "25.6.0",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.0.tgz",
-      "integrity": "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ==",
+      "version": "25.6.1",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.1.tgz",
+      "integrity": "sha512-coJCN8O1q4AGyyqCAUSP06P+SrMTu18BkEj3NVAK07q6QUneD2wzj3CLv9+yP+BMeZQlMvneXqqvDe3w+xcq7g==",
       "license": "MIT",
       "dependencies": {
         "undici-types": "~7.19.0"
@@ -2380,6 +2388,15 @@
         "js-tokens": "^10.0.0"
       }
     },
+    "node_modules/atomic-sleep": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/atomic-sleep/-/atomic-sleep-1.0.0.tgz",
+      "integrity": "sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.0.0"
+      }
+    },
     "node_modules/balanced-match": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
@@ -2579,6 +2596,12 @@
       "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
       "license": "MIT"
     },
+    "node_modules/colorette": {
+      "version": "2.0.20",
+      "resolved": "https://registry.npmjs.org/colorette/-/colorette-2.0.20.tgz",
+      "integrity": "sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==",
+      "license": "MIT"
+    },
     "node_modules/commander": {
       "version": "14.0.3",
       "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
@@ -2683,6 +2706,15 @@
         "node": ">= 8"
       }
     },
+    "node_modules/dateformat": {
+      "version": "4.6.3",
+      "resolved": "https://registry.npmjs.org/dateformat/-/dateformat-4.6.3.tgz",
+      "integrity": "sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA==",
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
     "node_modules/debug": {
       "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
@@ -2806,6 +2838,15 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/end-of-stream": {
+      "version": "1.4.5",
+      "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
+      "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
+      "license": "MIT",
+      "dependencies": {
+        "once": "^1.4.0"
+      }
+    },
     "node_modules/es-define-property": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
@@ -3050,12 +3091,24 @@
       "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==",
       "license": "MIT"
     },
+    "node_modules/fast-copy": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/fast-copy/-/fast-copy-4.0.3.tgz",
+      "integrity": "sha512-58apWr0GUiDFM8+3afrO6eYwJBn9ZAhDOzG3L+/9llab/haCARS2UIfffmOurYLwbgDRs8n0rfr6qAAPEAuAQw==",
+      "license": "MIT"
+    },
     "node_modules/fast-deep-equal": {
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
       "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
       "license": "MIT"
     },
+    "node_modules/fast-safe-stringify": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz",
+      "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==",
+      "license": "MIT"
+    },
     "node_modules/fast-uri": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
@@ -3416,6 +3469,12 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/help-me": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/help-me/-/help-me-5.0.0.tgz",
+      "integrity": "sha512-7xgomUX6ADmcYzFik0HzAxh/73YlKR9bmFzf51CZwR+b6YtzU2m0u49hQCqV6SvlqIqsaxovfwdvbnsw3b/zpg==",
+      "license": "MIT"
+    },
     "node_modules/hono": {
       "version": "4.12.16",
       "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.16.tgz",
@@ -3575,6 +3634,15 @@
         "url": "https://github.com/sponsors/panva"
       }
     },
+    "node_modules/joycon": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/joycon/-/joycon-3.1.1.tgz",
+      "integrity": "sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/js-tokens": {
       "version": "10.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-10.0.0.tgz",
@@ -4183,6 +4251,15 @@
       ],
       "license": "MIT"
     },
+    "node_modules/on-exit-leak-free": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/on-exit-leak-free/-/on-exit-leak-free-2.1.2.tgz",
+      "integrity": "sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
     "node_modules/on-finished": {
       "version": "2.4.1",
       "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
@@ -4332,6 +4409,79 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/pino": {
+      "version": "10.3.1",
+      "resolved": "https://registry.npmjs.org/pino/-/pino-10.3.1.tgz",
+      "integrity": "sha512-r34yH/GlQpKZbU1BvFFqOjhISRo1MNx1tWYsYvmj6KIRHSPMT2+yHOEb1SG6NMvRoHRF0a07kCOox/9yakl1vg==",
+      "license": "MIT",
+      "dependencies": {
+        "@pinojs/redact": "^0.4.0",
+        "atomic-sleep": "^1.0.0",
+        "on-exit-leak-free": "^2.1.0",
+        "pino-abstract-transport": "^3.0.0",
+        "pino-std-serializers": "^7.0.0",
+        "process-warning": "^5.0.0",
+        "quick-format-unescaped": "^4.0.3",
+        "real-require": "^0.2.0",
+        "safe-stable-stringify": "^2.3.1",
+        "sonic-boom": "^4.0.1",
+        "thread-stream": "^4.0.0"
+      },
+      "bin": {
+        "pino": "bin.js"
+      }
+    },
+    "node_modules/pino-abstract-transport": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/pino-abstract-transport/-/pino-abstract-transport-3.0.0.tgz",
+      "integrity": "sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg==",
+      "license": "MIT",
+      "dependencies": {
+        "split2": "^4.0.0"
+      }
+    },
+    "node_modules/pino-pretty": {
+      "version": "13.1.3",
+      "resolved": "https://registry.npmjs.org/pino-pretty/-/pino-pretty-13.1.3.tgz",
+      "integrity": "sha512-ttXRkkOz6WWC95KeY9+xxWL6AtImwbyMHrL1mSwqwW9u+vLp/WIElvHvCSDg0xO/Dzrggz1zv3rN5ovTRVowKg==",
+      "license": "MIT",
+      "dependencies": {
+        "colorette": "^2.0.7",
+        "dateformat": "^4.6.3",
+        "fast-copy": "^4.0.0",
+        "fast-safe-stringify": "^2.1.1",
+        "help-me": "^5.0.0",
+        "joycon": "^3.1.1",
+        "minimist": "^1.2.6",
+        "on-exit-leak-free": "^2.1.0",
+        "pino-abstract-transport": "^3.0.0",
+        "pump": "^3.0.0",
+        "secure-json-parse": "^4.0.0",
+        "sonic-boom": "^4.0.1",
+        "strip-json-comments": "^5.0.2"
+      },
+      "bin": {
+        "pino-pretty": "bin.js"
+      }
+    },
+    "node_modules/pino-pretty/node_modules/strip-json-comments": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-5.0.3.tgz",
+      "integrity": "sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/pino-std-serializers": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/pino-std-serializers/-/pino-std-serializers-7.1.0.tgz",
+      "integrity": "sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw==",
+      "license": "MIT"
+    },
     "node_modules/pkce-challenge": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz",
@@ -4376,6 +4526,22 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/process-warning": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/process-warning/-/process-warning-5.0.0.tgz",
+      "integrity": "sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/protobufjs": {
       "version": "7.5.5",
       "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.5.tgz",
@@ -4413,6 +4579,16 @@
         "node": ">= 0.10"
       }
     },
+    "node_modules/pump": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
+      "integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==",
+      "license": "MIT",
+      "dependencies": {
+        "end-of-stream": "^1.1.0",
+        "once": "^1.3.1"
+      }
+    },
     "node_modules/qs": {
       "version": "6.14.2",
       "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.2.tgz",
@@ -4428,6 +4604,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/quick-format-unescaped": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/quick-format-unescaped/-/quick-format-unescaped-4.0.4.tgz",
+      "integrity": "sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg==",
+      "license": "MIT"
+    },
     "node_modules/range-parser": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz",
@@ -4483,6 +4665,15 @@
         "rc": "cli.js"
       }
     },
+    "node_modules/real-require": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/real-require/-/real-require-0.2.0.tgz",
+      "integrity": "sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12.13.0"
+      }
+    },
     "node_modules/require-directory": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
@@ -4591,12 +4782,37 @@
       ],
       "license": "MIT"
     },
+    "node_modules/safe-stable-stringify": {
+      "version": "2.5.0",
+      "resolved": "https://registry.npmjs.org/safe-stable-stringify/-/safe-stable-stringify-2.5.0.tgz",
+      "integrity": "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/safer-buffer": {
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
       "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
       "license": "MIT"
     },
+    "node_modules/secure-json-parse": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/secure-json-parse/-/secure-json-parse-4.1.0.tgz",
+      "integrity": "sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
     "node_modules/semver": {
       "version": "7.7.4",
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
@@ -4828,6 +5044,15 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/sonic-boom": {
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/sonic-boom/-/sonic-boom-4.2.1.tgz",
+      "integrity": "sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q==",
+      "license": "MIT",
+      "dependencies": {
+        "atomic-sleep": "^1.0.0"
+      }
+    },
     "node_modules/source-map-js": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -4838,6 +5063,15 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/split2": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz",
+      "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">= 10.x"
+      }
+    },
     "node_modules/stackback": {
       "version": "0.0.2",
       "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
@@ -4925,6 +5159,18 @@
         "node": ">=18"
       }
     },
+    "node_modules/thread-stream": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-4.0.0.tgz",
+      "integrity": "sha512-4iMVL6HAINXWf1ZKZjIPcz5wYaOdPhtO8ATvZ+Xqp3BTdaqtAwQkNmKORqcIo5YkQqGXq5cwfswDwMqqQNrpJA==",
+      "license": "MIT",
+      "dependencies": {
+        "real-require": "^0.2.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/tinybench": {
       "version": "2.9.0",
       "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
diff --git a/gitnexus/package.json b/gitnexus/package.json
index 6aa5f59b7d..84f7027627 100644
--- a/gitnexus/package.json
+++ b/gitnexus/package.json
@@ -73,6 +73,8 @@
     "mnemonist": "^0.40.3",
     "onnxruntime-node": "^1.24.0",
     "pandemonium": "^2.4.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
     "tree-sitter": "^0.21.1",
     "tree-sitter-c": "0.21.4",
     "tree-sitter-c-sharp": "0.23.1",
diff --git a/gitnexus/src/cli/ai-context.ts b/gitnexus/src/cli/ai-context.ts
index 1b83963017..41ba6c73e9 100644
--- a/gitnexus/src/cli/ai-context.ts
+++ b/gitnexus/src/cli/ai-context.ts
@@ -10,6 +10,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { type GeneratedSkillInfo } from './skill-gen.js';
+import { logger } from '../core/logger.js';
 
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url);
@@ -293,7 +294,7 @@ Use GitNexus tools to accomplish this task.
       installedSkills.push(skill.name);
     } catch (err) {
       // Skip on error, don't fail the whole process
-      console.warn(`Warning: Could not install skill ${skill.name}:`, err);
+      logger.warn({ err }, `Warning: Could not install skill ${skill.name}:`);
     }
   }
 
diff --git a/gitnexus/src/cli/analyze.ts b/gitnexus/src/cli/analyze.ts
index 90b8c9a433..47745c5752 100644
--- a/gitnexus/src/cli/analyze.ts
+++ b/gitnexus/src/cli/analyze.ts
@@ -26,6 +26,8 @@ import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-si
 import { warnMissingOptionalGrammars } from './optional-grammars.js';
 import { glob } from 'glob';
 import fs from 'fs/promises';
+import { cliError } from './cli-message.js';
+import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
 
 // Capture stderr.write at module load BEFORE anything (LadybugDB native
 // init, progress bar, console redirection) can monkey-patch it. The
@@ -167,7 +169,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
   if (options?.workerTimeout) {
     const workerTimeoutSeconds = Number(options.workerTimeout);
     if (!Number.isFinite(workerTimeoutSeconds) || workerTimeoutSeconds < 1) {
-      console.error('  --worker-timeout must be at least 1 second.\n');
+      cliError('  --worker-timeout must be at least 1 second.\n');
       process.exitCode = 1;
       return;
     }
@@ -184,7 +186,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
   if (typeof options?.embeddings === 'string') {
     const parsed = Number(options.embeddings);
     if (!Number.isInteger(parsed) || parsed < 0) {
-      console.error(
+      cliError(
         `  --embeddings expects a non-negative integer (got "${options.embeddings}"). ` +
           `Pass 0 to disable the safety cap, or omit the value to keep the default.\n`,
       );
@@ -203,7 +205,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     if (value === undefined) return true;
     const parsed = Number(value);
     if (!Number.isInteger(parsed) || parsed <= 0) {
-      console.error(`  ${optionName} must be a positive integer.\n`);
+      cliError(`  ${optionName} must be a positive integer.\n`);
       process.exitCode = 1;
       return false;
     }
@@ -234,7 +236,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
   if (options?.embeddingDevice) {
     const allowed = new Set(['auto', 'cpu', 'dml', 'cuda', 'wasm']);
     if (!allowed.has(options.embeddingDevice)) {
-      console.error('  --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
+      cliError('  --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
       process.exitCode = 1;
       return;
     }
@@ -330,7 +332,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
 
   bar.start(100, 0, { phase: 'Initializing...' });
 
-  // Graceful SIGINT handling
+  // Graceful SIGINT handling. Pino's default destination is `sync: false`
+  // (buffered) — flush before exit so in-flight records reach stderr.
+  // See `gitnexus/src/core/logger.ts:flushLoggerSync`.
   let aborted = false;
   const sigintHandler = () => {
     if (aborted) process.exit(1);
@@ -339,13 +343,23 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     console.log('\n  Interrupted — cleaning up...');
     closeLbug()
       .catch(() => {})
-      .finally(() => process.exit(130));
+      .finally(async () => {
+        const { flushLoggerSync } = await import('../core/logger.js');
+        flushLoggerSync();
+        process.exit(130);
+      });
   };
   process.on('SIGINT', sigintHandler);
 
-  // Route console output through bar.log() to prevent progress bar corruption
+  // Route console output through bar.log() to prevent progress bar corruption.
+  // This is a deliberate UI pattern (not a logging concern): analyze runs a
+  // long-lived progress bar on stdout; any concurrent console.* write would
+  // overwrite the bar mid-render. We capture originals, swap to barLog for
+  // the lifetime of the run, and restore on completion/error/SIGINT.
   const origLog = console.log.bind(console);
+  // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
   const origWarn = console.warn.bind(console);
+  // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
   const origError = console.error.bind(console);
   let barCurrentValue = 0;
   const barLog = (...args: any[]) => {
@@ -354,7 +368,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     bar.update(barCurrentValue);
   };
   console.log = barLog;
+  // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
   console.warn = barLog;
+  // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
   console.error = barLog;
 
   // Track elapsed time per phase
@@ -420,7 +436,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
       clearInterval(elapsedTimer);
       process.removeListener('SIGINT', sigintHandler);
       console.log = origLog;
+      // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
       console.warn = origWarn;
+      // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
       console.error = origError;
       bar.stop();
       console.log('  Already up to date\n');
@@ -493,7 +511,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     process.removeListener('SIGINT', sigintHandler);
 
     console.log = origLog;
+    // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
     console.warn = origWarn;
+    // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
     console.error = origError;
 
     bar.update(100, { phase: 'Done' });
@@ -518,7 +538,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     clearInterval(elapsedTimer);
     process.removeListener('SIGINT', sigintHandler);
     console.log = origLog;
+    // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
     console.warn = origWarn;
+    // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
     console.error = origError;
     bar.stop();
 
@@ -527,14 +549,14 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     // Registry name-collision from --name (#829) — surface as an
     // actionable error rather than a generic stack-trace.
     if (err instanceof RegistryNameCollisionError) {
-      console.error(`\n  Registry name collision:\n`);
-      console.error(`    "${err.registryName}" is already used by "${err.existingPath}".\n`);
-      console.error(`  Options:`);
-      console.error(`    • Pick a different alias:  gitnexus analyze --name <alias>`);
-      console.error(
-        `    • Allow the duplicate:     gitnexus analyze --allow-duplicate-name  (leaves "-r ${err.registryName}" ambiguous)`,
+      cliError(
+        `\n  Registry name collision:\n` +
+          `    "${err.registryName}" is already used by "${err.existingPath}".\n\n` +
+          `  Options:\n` +
+          `    • Pick a different alias:  gitnexus analyze --name <alias>\n` +
+          `    • Allow the duplicate:     gitnexus analyze --allow-duplicate-name  (leaves "-r ${err.registryName}" ambiguous)\n`,
+        { registryName: err.registryName, existingPath: err.existingPath },
       );
-      console.error('');
       process.exitCode = 1;
       return;
     }
@@ -555,6 +577,26 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
       return;
     }
 
+    // HF download failure — show clean guidance without the raw stack trace.
+    // Checked before writeFatalToStderr so the user sees one focused message
+    // rather than a stack-trace dump followed by a second remediation block.
+    if (isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) {
+      cliError(
+        `  The embedding model could not be downloaded.\n` +
+          `  huggingface.co may be unreachable from your network\n` +
+          `  (e.g. behind a corporate proxy or a regional firewall).\n` +
+          `  Suggestions:\n` +
+          `    1. Set HF_ENDPOINT to a mirror and retry:\n` +
+          `         HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
+          `         (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)\n` +
+          `    2. Check your proxy / VPN settings.\n` +
+          `    3. Once downloaded the model is cached — future runs work offline.\n`,
+        { recoveryHint: 'hf-endpoint-unreachable' },
+      );
+      process.exitCode = 1;
+      return;
+    }
+
     // Bypass the redirected console.error and write the full stack to
     // the real stderr captured at module load. The redirected
     // console.error wraps every line with `\\x1b[2K\\r` (ANSI clear-line)
@@ -574,34 +616,40 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
       msg.includes('heap out of memory') ||
       msg.includes('JavaScript heap')
     ) {
-      console.error('  This error typically occurs on very large repositories.');
-      console.error('  Suggestions:');
-      console.error('    1. Add large vendored/generated directories to .gitnexusignore');
-      console.error('    2. Increase Node.js heap: NODE_OPTIONS="--max-old-space-size=16384"');
-      console.error('    3. Increase stack size: NODE_OPTIONS="--stack-size=4096"');
-      console.error('');
+      cliError(
+        `  This error typically occurs on very large repositories.\n` +
+          `  Suggestions:\n` +
+          `    1. Add large vendored/generated directories to .gitnexusignore\n` +
+          `    2. Increase Node.js heap: NODE_OPTIONS="--max-old-space-size=16384"\n` +
+          `    3. Increase stack size: NODE_OPTIONS="--stack-size=4096"\n`,
+        { recoveryHint: 'large-repo' },
+      );
     } else if (msg.includes('ERESOLVE') || msg.includes('Could not resolve dependency')) {
       // Note: the original arborist "Cannot destructure property 'package' of
       // 'node.target'" crash happens inside npm *before* gitnexus code runs,
       // so it can't be caught here.  This branch handles dependency-resolution
       // errors that surface at runtime (e.g. dynamic require failures).
-      console.error('  This looks like an npm dependency resolution issue.');
-      console.error('  Suggestions:');
-      console.error('    1. Clear the npm cache:    npm cache clean --force');
-      console.error('    2. Update npm:             npm install -g npm@latest');
-      console.error('    3. Reinstall gitnexus:     npm install -g gitnexus@latest');
-      console.error('    4. Or try npx directly:    npx gitnexus@latest analyze');
-      console.error('');
+      cliError(
+        `  This looks like an npm dependency resolution issue.\n` +
+          `  Suggestions:\n` +
+          `    1. Clear the npm cache:    npm cache clean --force\n` +
+          `    2. Update npm:             npm install -g npm@latest\n` +
+          `    3. Reinstall gitnexus:     npm install -g gitnexus@latest\n` +
+          `    4. Or try npx directly:    npx gitnexus@latest analyze\n`,
+        { recoveryHint: 'npm-resolution' },
+      );
     } else if (
       msg.includes('MODULE_NOT_FOUND') ||
       msg.includes('Cannot find module') ||
       msg.includes('ERR_MODULE_NOT_FOUND')
     ) {
-      console.error('  A required module could not be loaded. The installation may be corrupt.');
-      console.error('  Suggestions:');
-      console.error('    1. Reinstall:   npm install -g gitnexus@latest');
-      console.error('    2. Clear cache: npm cache clean --force && npx gitnexus@latest analyze');
-      console.error('');
+      cliError(
+        `  A required module could not be loaded. The installation may be corrupt.\n` +
+          `  Suggestions:\n` +
+          `    1. Reinstall:   npm install -g gitnexus@latest\n` +
+          `    2. Clear cache: npm cache clean --force && npx gitnexus@latest analyze\n`,
+        { recoveryHint: 'module-not-found' },
+      );
     }
 
     process.exitCode = 1;
diff --git a/gitnexus/src/cli/clean.ts b/gitnexus/src/cli/clean.ts
index 4681508fb3..2bbc32aef1 100644
--- a/gitnexus/src/cli/clean.ts
+++ b/gitnexus/src/cli/clean.ts
@@ -6,6 +6,7 @@
  */
 
 import fs from 'fs/promises';
+import { logger } from '../core/logger.js';
 import {
   findRepo,
   unregisterRepo,
@@ -45,7 +46,7 @@ export const cleanCommand = async (options?: { force?: boolean; all?: boolean })
         assertSafeStoragePath(entry);
       } catch (err) {
         if (err instanceof UnsafeStoragePathError) {
-          console.error(`Refusing to clean ${entry.name}: ${err.message}`);
+          logger.error(`Refusing to clean ${entry.name}: ${err.message}`);
           continue;
         }
         throw err;
@@ -56,7 +57,7 @@ export const cleanCommand = async (options?: { force?: boolean; all?: boolean })
         await unregisterRepo(entry.path);
         console.log(`Deleted: ${entry.name} (${entry.storagePath})`);
       } catch (err) {
-        console.error(`Failed to delete ${entry.name}:`, err);
+        logger.error({ err }, `Failed to delete ${entry.name}:`);
       }
     }
     return;
@@ -85,6 +86,6 @@ export const cleanCommand = async (options?: { force?: boolean; all?: boolean })
     await unregisterRepo(repo.repoPath);
     console.log(`Deleted: ${repo.storagePath}`);
   } catch (err) {
-    console.error('Failed to delete:', err);
+    logger.error({ err }, 'Failed to delete:');
   }
 };
diff --git a/gitnexus/src/cli/cli-message.ts b/gitnexus/src/cli/cli-message.ts
new file mode 100644
index 0000000000..db5f51fab5
--- /dev/null
+++ b/gitnexus/src/cli/cli-message.ts
@@ -0,0 +1,65 @@
+/**
+ * CLI message helpers — for user-facing banners, error guidance, and
+ * recovery hints emitted by `gitnexus` subcommands.
+ *
+ * These functions write **plain text** directly to `process.stderr` AND
+ * tee a structured pino record through the singleton `logger`. Plain text
+ * preserves the human-readable contract for users running `gitnexus`
+ * interactively, redirecting to a file, or piping to `cat`/`grep`. The
+ * structured tee keeps log aggregators happy.
+ *
+ * **Use these for:**
+ *   - User-facing banners ("Server listening on http://...:N")
+ *   - Validation errors ("--worker-timeout must be at least 1 second")
+ *   - Recovery hints ("Suggestions: 1. Clear the npm cache, 2. ...")
+ *   - One-line user notices ("No indexed repositories found.")
+ *
+ * **Do NOT use these for:**
+ *   - Internal diagnostics (worker progress, retry counts, telemetry)
+ *     — use `logger.info`/`warn`/`error` directly. Internal logs only
+ *     need structured fields, not double-output to stderr.
+ *   - High-volume hot paths — every `cliMessage` call writes twice (raw
+ *     + structured). Acceptable for user-facing messages, wasteful for
+ *     ingestion pipeline events.
+ *
+ * Design note: stderr is the right channel even for non-error messages
+ * because GitNexus CLI tools (`query`, `cypher`, `impact`) emit JSON
+ * data on stdout for piping (`gitnexus query | jq`). User banners on
+ * stdout would corrupt that pipeline.
+ */
+import { logger } from '../core/logger.js';
+
+function writeStderr(msg: string): void {
+  // Direct write — bypassing `console.*` so it cannot be intercepted by
+  // progress-bar redirection (see `cli/analyze.ts:barLog`) or other
+  // routing. The structured tee below still goes through the logger so
+  // log aggregation works either way.
+  process.stderr.write(msg.endsWith('\n') ? msg : msg + '\n');
+}
+
+/**
+ * User-facing informational message. Use for banners, listening URLs,
+ * and any message the user expects to read in plain text.
+ */
+export function cliInfo(msg: string, fields?: Record<string, unknown>): void {
+  writeStderr(msg);
+  logger.info(fields ?? {}, msg);
+}
+
+/**
+ * User-facing warning. Operator-actionable but non-fatal — `cliWarn`
+ * indicates the command can still proceed in some form.
+ */
+export function cliWarn(msg: string, fields?: Record<string, unknown>): void {
+  writeStderr(msg);
+  logger.warn(fields ?? {}, msg);
+}
+
+/**
+ * User-facing error. Indicates the command cannot proceed; usually
+ * paired with a non-zero exit code at the call site.
+ */
+export function cliError(msg: string, fields?: Record<string, unknown>): void {
+  writeStderr(msg);
+  logger.error(fields ?? {}, msg);
+}
diff --git a/gitnexus/src/cli/eval-server.ts b/gitnexus/src/cli/eval-server.ts
index cf9013d63e..0819c33e81 100644
--- a/gitnexus/src/cli/eval-server.ts
+++ b/gitnexus/src/cli/eval-server.ts
@@ -27,6 +27,8 @@
 import http from 'http';
 import { writeSync } from 'node:fs';
 import { LocalBackend } from '../mcp/local/local-backend.js';
+import { logger } from '../core/logger.js';
+import { cliInfo, cliWarn } from './cli-message.js';
 
 export interface EvalServerOptions {
   port?: string;
@@ -332,13 +334,19 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
   const ok = await backend.init();
 
   if (!ok) {
-    console.error('GitNexus eval-server: No indexed repositories found. Run: gitnexus analyze');
+    // Operator-actionable but the server cannot start; warn-level so log
+    // aggregators don't trip error alerts on a configuration miss. Use
+    // cliWarn so the diagnostic reaches stderr synchronously before
+    // process.exit() — direct logger.warn would be lost to the buffered
+    // pino destination on hard exit (skips beforeExit flush).
+    cliWarn('GitNexus eval-server: No indexed repositories found. Run: gitnexus analyze');
     process.exit(1);
   }
 
   const repos = await backend.listRepos();
-  console.error(
-    `GitNexus eval-server: ${repos.length} repo(s) loaded: ${repos.map((r) => r.name).join(', ')}`,
+  logger.info(
+    { repoCount: repos.length, repos: repos.map((r) => r.name) },
+    'GitNexus eval-server: repos loaded',
   );
 
   let idleTimer: ReturnType<typeof setTimeout> | null = null;
@@ -347,7 +355,7 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
     if (idleTimeoutSec <= 0) return;
     if (idleTimer) clearTimeout(idleTimer);
     idleTimer = setTimeout(async () => {
-      console.error('GitNexus eval-server: Idle timeout reached, shutting down');
+      logger.info({ idleTimeoutSec }, 'GitNexus eval-server: idle timeout reached, shutting down');
       await backend.disconnect();
       process.exit(0);
     }, idleTimeoutSec * 1000);
@@ -419,16 +427,34 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
   });
 
   server.listen(port, '127.0.0.1', () => {
-    console.error(`GitNexus eval-server: listening on http://127.0.0.1:${port}`);
-    console.error(`  POST /tool/query    — search execution flows`);
-    console.error(`  POST /tool/context  — 360-degree symbol view`);
-    console.error(`  POST /tool/impact   — blast radius analysis`);
-    console.error(`  POST /tool/cypher   — raw Cypher query`);
-    console.error(`  GET  /health        — health check`);
-    console.error(`  POST /shutdown      — graceful shutdown`);
+    // Plain-text banner for the human watching stderr; structured record
+    // for log aggregation (split into two so the user sees a real banner
+    // not `{"level":30,"msg":"...","port":4747,"endpoints":[...]}`).
+    const bannerLines = [
+      `GitNexus eval-server: listening on http://127.0.0.1:${port}`,
+      `  POST /tool/query    — search execution flows`,
+      `  POST /tool/context  — 360-degree symbol view`,
+      `  POST /tool/impact   — blast radius analysis`,
+      `  POST /tool/cypher   — raw Cypher query`,
+      `  GET  /health        — health check`,
+      `  POST /shutdown      — graceful shutdown`,
+    ];
     if (idleTimeoutSec > 0) {
-      console.error(`  Auto-shutdown after ${idleTimeoutSec}s idle`);
+      bannerLines.push(`  Auto-shutdown after ${idleTimeoutSec}s idle`);
     }
+    cliInfo(bannerLines.join('\n'), {
+      port,
+      host: '127.0.0.1',
+      idleTimeoutSec: idleTimeoutSec > 0 ? idleTimeoutSec : undefined,
+      endpoints: [
+        'POST /tool/query',
+        'POST /tool/context',
+        'POST /tool/impact',
+        'POST /tool/cypher',
+        'GET  /health',
+        'POST /shutdown',
+      ],
+    });
     try {
       // Use fd 1 directly — LadybugDB captures process.stdout (#324)
       writeSync(1, `GITNEXUS_EVAL_SERVER_READY:${port}\n`);
@@ -440,7 +466,7 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
   resetIdleTimer();
 
   const shutdown = async () => {
-    console.error('GitNexus eval-server: shutting down...');
+    logger.info('GitNexus eval-server: shutting down...');
     await backend.disconnect();
     server.close();
     process.exit(0);
diff --git a/gitnexus/src/cli/group.ts b/gitnexus/src/cli/group.ts
index eb0dffc3d3..0053099b70 100644
--- a/gitnexus/src/cli/group.ts
+++ b/gitnexus/src/cli/group.ts
@@ -1,6 +1,7 @@
 // gitnexus/src/cli/group.ts
 import { createRequire } from 'node:module';
 import type { Command } from 'commander';
+import { logger } from '../core/logger.js';
 
 const _require = createRequire(import.meta.url);
 const yaml = _require('js-yaml') as typeof import('js-yaml');
@@ -51,7 +52,7 @@ export function registerGroupCommands(program: Command): void {
       const groupDir = getGroupDir(getDefaultGitnexusDir(), groupName);
       const config = await loadGroupConfig(groupDir);
       if (!(repoPath in config.repos)) {
-        console.error(`Repo path "${repoPath}" not found in group "${groupName}"`);
+        logger.error(`Repo path "${repoPath}" not found in group "${groupName}"`);
         process.exitCode = 1;
         return;
       }
@@ -239,7 +240,7 @@ export function registerGroupCommands(program: Command): void {
 
         const raw = await backend.getGroupService().groupImpact(payload);
         if (raw && typeof raw === 'object' && 'error' in raw) {
-          console.error(String((raw as { error: string }).error));
+          logger.error(String((raw as { error: string }).error));
           process.exitCode = 1;
           return;
         }
@@ -333,7 +334,7 @@ export function registerGroupCommands(program: Command): void {
         });
 
         if (raw && typeof raw === 'object' && 'error' in raw) {
-          console.error(String((raw as { error: string }).error));
+          logger.error(String((raw as { error: string }).error));
           process.exitCode = 1;
           return;
         }
diff --git a/gitnexus/src/cli/mcp.ts b/gitnexus/src/cli/mcp.ts
index e69ce0eb05..056b12591f 100644
--- a/gitnexus/src/cli/mcp.ts
+++ b/gitnexus/src/cli/mcp.ts
@@ -41,11 +41,17 @@ export const mcpCommand = async () => {
   // path runs cleanly with full stack traces. Registering duplicates here
   // would only produce noisy double-logging on the same exception.
 
-  // Now safe to dynamically import the heavy backend modules. Anything
-  // they emit to stdout during evaluation will route through the sentinel.
-  const [{ startMCPServer }, { LocalBackend }] = await Promise.all([
+  // Dynamically import heavy backend modules AND the pino logger AFTER
+  // the sentinel installs. The logger is dynamic-imported (rather than
+  // static) to preserve the leaf-only static-import closure documented at
+  // the top of this file — `core/logger.js` itself doesn't write to
+  // stdout at module init, but transitive deps (pino, pino-pretty, the
+  // worker-thread transport) could in theory, and the import-closure
+  // regression test enforces the leaf invariant.
+  const [{ startMCPServer }, { LocalBackend }, { logger }] = await Promise.all([
     import('../mcp/server.js'),
     import('../mcp/local/local-backend.js'),
+    import('../core/logger.js'),
   ]);
 
   // Missing-optional-grammar warnings are intentionally NOT emitted here.
@@ -62,12 +68,15 @@ export const mcpCommand = async () => {
 
   const repos = await backend.listRepos();
   if (repos.length === 0) {
-    console.error(
+    // Operator-actionable but the server still starts and serves; warn-level,
+    // not error. Tools will discover newly-analyzed repos via lazy refresh.
+    logger.warn(
       'GitNexus: No indexed repos yet. Run `gitnexus analyze` in a git repo — the server will pick it up automatically.',
     );
   } else {
-    console.error(
-      `GitNexus: MCP server starting with ${repos.length} repo(s): ${repos.map((r) => r.name).join(', ')}`,
+    logger.info(
+      { repoCount: repos.length, repos: repos.map((r) => r.name) },
+      'GitNexus: MCP server starting',
     );
   }
 
diff --git a/gitnexus/src/cli/optional-grammars.ts b/gitnexus/src/cli/optional-grammars.ts
index c6e239b563..14f6c3c5ea 100644
--- a/gitnexus/src/cli/optional-grammars.ts
+++ b/gitnexus/src/cli/optional-grammars.ts
@@ -13,6 +13,7 @@
  */
 
 import { createRequire } from 'module';
+import { cliWarn } from './cli-message.js';
 
 const _require = createRequire(import.meta.url);
 
@@ -65,9 +66,14 @@ export function detectMissingOptionalGrammars(): MissingGrammar[] {
         /could not find|no native build|prebuilds/i.test(msg);
       if (!looksMissing) {
         // Present but broken — surface so the user doesn't get a misleading
-        // "reinstall" recovery message that wouldn't actually help.
-        console.error(
+        // "reinstall" recovery message that wouldn't actually help. cliWarn
+        // writes plain text to stderr AND tees a structured logger.warn
+        // record; the merged repo-wide ESLint pino-migration rule forbids
+        // direct `console.error` in CLI code (only `console.log` is allowed
+        // there for tool-data stdout output).
+        cliWarn(
           `GitNexus: optional grammar "${g.name}" is installed but failed to load (${msg.slice(0, 200)}). ${g.extensions.join('/')} files will not be parsed.`,
+          { grammar: g.name, extensions: g.extensions, error: msg },
         );
       }
       missing.push({ name: g.name, extensions: g.extensions });
@@ -92,12 +98,17 @@ export function warnMissingOptionalGrammars(opts?: {
   const missing = detectMissingOptionalGrammars();
   if (missing.length === 0) return;
   const ctx = opts?.context ? ` [${opts.context}]` : '';
+  // Hoist the optional set into a local so the closure below can narrow
+  // its type; references to `opts?.relevantExtensions` inside `.some()`
+  // lose the outer null-check narrowing and require a non-null assertion.
+  const relevantExtensions = opts?.relevantExtensions;
   for (const g of missing) {
-    if (opts?.relevantExtensions && !g.extensions.some((e) => opts.relevantExtensions!.has(e))) {
+    if (relevantExtensions && !g.extensions.some((e) => relevantExtensions.has(e))) {
       continue;
     }
-    console.error(
+    cliWarn(
       `GitNexus${ctx}: optional grammar "${g.name}" is unavailable — ${g.extensions.join('/')} files will not be parsed. Reinstall without GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (and ensure python3, make, g++) to enable.`,
+      { grammar: g.name, extensions: g.extensions, context: opts?.context },
     );
   }
 }
diff --git a/gitnexus/src/cli/remove.ts b/gitnexus/src/cli/remove.ts
index 4d2ce0771d..18d2a340d0 100644
--- a/gitnexus/src/cli/remove.ts
+++ b/gitnexus/src/cli/remove.ts
@@ -27,6 +27,8 @@
  */
 
 import fs from 'fs/promises';
+import { logger } from '../core/logger.js';
+import { cliError } from './cli-message.js';
 import {
   readRegistry,
   resolveRegistryEntry,
@@ -51,14 +53,14 @@ export const removeCommand = async (target: string, options?: { force?: boolean
       // Idempotent: missing target is a no-op warning, not an error.
       // The `availableNames` hint comes from the error itself so users
       // can see what they might have meant.
-      console.warn(`Nothing to remove: ${err.message}`);
+      logger.warn(`Nothing to remove: ${err.message}`);
       return;
     }
     if (err instanceof RegistryAmbiguousTargetError) {
       // Duplicate aliases are allowed via --allow-duplicate-name (#829);
       // refuse to guess which one the user meant — surface the full list
       // and exit non-zero so scripts don't silently pick the wrong repo.
-      console.error(`Error: ${err.message}`);
+      cliError(`Error: ${err.message}`);
       process.exit(1);
     }
     throw err;
@@ -86,7 +88,7 @@ export const removeCommand = async (target: string, options?: { force?: boolean
     assertSafeStoragePath(entry);
   } catch (err) {
     if (err instanceof UnsafeStoragePathError) {
-      console.error(`Error: ${err.message}`);
+      cliError(`Error: ${err.message}`);
       process.exit(1);
     }
     throw err;
@@ -104,7 +106,8 @@ export const removeCommand = async (target: string, options?: { force?: boolean
     console.log(`   Path:    ${entry.path}`);
     console.log(`   Storage: ${entry.storagePath}`);
   } catch (err) {
-    console.error(`Failed to remove ${entry.name}:`, err);
+    const msg = err instanceof Error ? err.message : String(err);
+    cliError(`Failed to remove ${entry.name}: ${msg}`, { err });
     process.exit(1);
   }
 };
diff --git a/gitnexus/src/cli/serve.ts b/gitnexus/src/cli/serve.ts
index 9f03793060..9356b5bab1 100644
--- a/gitnexus/src/cli/serve.ts
+++ b/gitnexus/src/cli/serve.ts
@@ -1,14 +1,26 @@
 import { createServer } from '../server/api.js';
+import { logger, flushLoggerSync } from '../core/logger.js';
+import { cliError } from './cli-message.js';
 
-// Catch anything that would cause a silent exit
+// Catch anything that would cause a silent exit. Pino v10's default
+// destination is `sync: false` (SonicBoom buffered) — call
+// `flushLoggerSync()` between the log and `process.exit(1)` so the crash
+// record is not lost to the unflushed buffer. Worker-thread transports
+// (pino-pretty under TTY) handle their own flush on process exit in v10,
+// so no separate `pino.final` integration is needed (the API was removed
+// in v10 because the transport architecture made it unnecessary).
+//
+// We pass the Error itself in `{ err }` so pino's built-in err serializer
+// captures `type`, `message`, and `stack` as structured fields.
 process.on('uncaughtException', (err) => {
-  console.error('\n[gitnexus serve] Uncaught exception:', err.message);
-  if (process.env.DEBUG) console.error(err.stack);
+  logger.error({ err }, '[gitnexus serve] Uncaught exception');
+  flushLoggerSync();
   process.exit(1);
 });
-process.on('unhandledRejection', (reason: any) => {
-  console.error('\n[gitnexus serve] Unhandled rejection:', reason?.message || reason);
-  if (process.env.DEBUG) console.error(reason?.stack);
+process.on('unhandledRejection', (reason) => {
+  const err = reason instanceof Error ? reason : new Error(String(reason));
+  logger.error({ err }, '[gitnexus serve] Unhandled rejection');
+  flushLoggerSync();
   process.exit(1);
 });
 
@@ -22,16 +34,26 @@ export const serveCommand = async (options?: { port?: string; host?: string }) =
   try {
     await createServer(port, host);
   } catch (err: any) {
-    console.error(`\nFailed to start GitNexus server:\n`);
-    console.error(`  ${err.message || err}\n`);
     if (err.code === 'EADDRINUSE') {
-      console.error(`  Port ${port} is already in use. Either:`);
-      console.error(`    1. Stop the other process using port ${port}`);
-      console.error(`    2. Use a different port: gitnexus serve --port 4748\n`);
+      cliError(
+        `\nFailed to start GitNexus server:\n` +
+          `  ${err.message || err}\n\n` +
+          `  Port ${port} is already in use. Either:\n` +
+          `    1. Stop the other process using port ${port}\n` +
+          `    2. Use a different port: gitnexus serve --port 4748\n`,
+        { code: err.code, port, host },
+      );
+    } else {
+      cliError(`\nFailed to start GitNexus server:\n  ${err.message || err}\n`, {
+        code: err.code,
+        port,
+        host,
+      });
     }
     if (err.stack && process.env.DEBUG) {
-      console.error(err.stack);
+      logger.debug({ stack: err.stack }, 'serve start error stack');
     }
+    flushLoggerSync();
     process.exit(1);
   }
 };
diff --git a/gitnexus/src/cli/setup.ts b/gitnexus/src/cli/setup.ts
index 1238e65275..af3c4737a7 100644
--- a/gitnexus/src/cli/setup.ts
+++ b/gitnexus/src/cli/setup.ts
@@ -365,7 +365,12 @@ async function installClaudeCodeHooks(result: SetupResult): Promise<void> {
     }
 
     const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
-    const hookCmd = `node "${hookPath.replace(/"/g, '\\"')}"`;
+    // Escape backslashes FIRST, then quotes (CodeQL js/incomplete-sanitization).
+    // The previous shape `replace(/"/g, '\\"')` alone would let `path\with"quote`
+    // become `path\with\"quote`, where the trailing `\` before `"` could
+    // unescape the quote inside the surrounding double-quoted shell context.
+    const escapedHookPath = hookPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    const hookCmd = `node "${escapedHookPath}"`;
 
     // Check which hook events need entries (idempotent: skip if already registered)
     const parsed = await (async () => {
@@ -622,7 +627,7 @@ async function installOpenCodeSkills(result: SetupResult): Promise<void> {
     const installed = await installSkillsTo(skillsDir);
     if (installed.length > 0) {
       result.configured.push(
-        `OpenCode skills (${installed.length} skills → ~/.config/opencode/skill/)`,
+        `OpenCode skills (${installed.length} skills → ~/.config/opencode/skills/)`,
       );
     }
   } catch (err: any) {
diff --git a/gitnexus/src/cli/tool.ts b/gitnexus/src/cli/tool.ts
index 443f12f4cc..b40ffdd259 100644
--- a/gitnexus/src/cli/tool.ts
+++ b/gitnexus/src/cli/tool.ts
@@ -17,6 +17,7 @@
 
 import { writeSync } from 'node:fs';
 import { LocalBackend } from '../mcp/local/local-backend.js';
+import { cliError } from './cli-message.js';
 
 let _backend: LocalBackend | null = null;
 
@@ -25,7 +26,7 @@ async function getBackend(): Promise<LocalBackend> {
   _backend = new LocalBackend();
   const ok = await _backend.init();
   if (!ok) {
-    console.error('GitNexus: No indexed repositories found. Run: gitnexus analyze');
+    cliError('GitNexus: No indexed repositories found. Run: gitnexus analyze');
     process.exit(1);
   }
   return _backend;
@@ -67,7 +68,7 @@ export async function queryCommand(
   },
 ): Promise<void> {
   if (!queryText?.trim()) {
-    console.error('Usage: gitnexus query <search_query>');
+    cliError('Usage: gitnexus query <search_query>');
     process.exit(1);
   }
 
@@ -93,7 +94,7 @@ export async function contextCommand(
   },
 ): Promise<void> {
   if (!name?.trim() && !options?.uid) {
-    console.error('Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]');
+    cliError('Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]');
     process.exit(1);
   }
 
@@ -118,7 +119,7 @@ export async function impactCommand(
   },
 ): Promise<void> {
   if (!target?.trim()) {
-    console.error('Usage: gitnexus impact <symbol_name> [--direction upstream|downstream]');
+    cliError('Usage: gitnexus impact <symbol_name> [--direction upstream|downstream]');
     process.exit(1);
   }
 
@@ -153,7 +154,7 @@ export async function cypherCommand(
   },
 ): Promise<void> {
   if (!query?.trim()) {
-    console.error('Usage: gitnexus cypher <cypher_query>');
+    cliError('Usage: gitnexus cypher <cypher_query>');
     process.exit(1);
   }
 
diff --git a/gitnexus/src/cli/wiki.ts b/gitnexus/src/cli/wiki.ts
index ccd1cae4ec..38a0f82a69 100644
--- a/gitnexus/src/cli/wiki.ts
+++ b/gitnexus/src/cli/wiki.ts
@@ -19,6 +19,7 @@ import {
 import { WikiGenerator, type WikiOptions } from '../core/wiki/generator.js';
 import { resolveLLMConfig, type LLMProvider } from '../core/wiki/llm-client.js';
 import { detectCursorCLI } from '../core/wiki/cursor-client.js';
+import { logger } from '../core/logger.js';
 
 export interface WikiCommandOptions {
   force?: boolean;
@@ -583,7 +584,7 @@ export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptio
     } else {
       console.log(`\n  Error: ${err.message}\n`);
       if (process.env.GITNEXUS_VERBOSE) {
-        console.error(err);
+        logger.error({ err }, 'wiki command failed');
       }
     }
     process.exitCode = 1;
@@ -601,6 +602,38 @@ function hasGhCLI(): boolean {
   }
 }
 
+/**
+ * Strict Gist URL predicate. Rejects:
+ *   - any URL that does not parse (URL constructor throws)
+ *   - schemes other than https (drops `http:`, `file:`, `gist:`-style spoofs)
+ *   - hostnames that are not exactly `gist.github.com` (drops substring spoofs
+ *     like `https://evil.com/?u=gist.github.com` and userinfo-prefixed shapes
+ *     like `https://[email protected]/...` — note that URL.hostname
+ *     strips userinfo, so the equality check rejects the userinfo-prefixed
+ *     spoof if the actual host differs from gist.github.com)
+ *   - any URL containing userinfo (`username[:password]@`), which the URL
+ *     parser exposes via `.username` / `.password`. Defense-in-depth: even
+ *     when hostname matches, a credential-bearing URL is suspect and not
+ *     produced by `gh gist create`.
+ *
+ * Closes the substring-bypass class CodeQL `js/incomplete-url-substring-
+ * sanitization` flags.
+ */
+function isGistUrl(line: string): boolean {
+  const trimmed = line.trim();
+  try {
+    const u = new URL(trimmed);
+    return (
+      u.protocol === 'https:' &&
+      u.hostname === 'gist.github.com' &&
+      u.username === '' &&
+      u.password === ''
+    );
+  } catch {
+    return false;
+  }
+}
+
 function publishGist(htmlPath: string): { url: string; rawUrl: string } | null {
   try {
     const output = execFileSync(
@@ -609,13 +642,14 @@ function publishGist(htmlPath: string): { url: string; rawUrl: string } | null {
       { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
     ).trim();
 
-    // gh gist create prints the gist URL as the last line
-    const lines = output.split('\n');
-    const gistUrl = lines.find((l) => l.includes('gist.github.com')) || lines[lines.length - 1];
-
-    if (!gistUrl || !gistUrl.includes('gist.github.com')) return null;
+    // `gh gist create` prints the gist URL as a line in the output. Find the
+    // first parseable Gist URL — if no line is a valid Gist URL, fail closed
+    // (do NOT fall back to lines[last]: a non-Gist last line would propagate
+    // through the regex below and produce a malformed `rawUrl`).
+    const gistUrl = output.split('\n').find(isGistUrl);
+    if (!gistUrl) return null;
 
-    // Build a raw viewer URL via gist.githack.com
+    // Build a raw viewer URL via gist.githack.com.
     // gist URL format: https://gist.github.com/{user}/{id}
     const match = gistUrl.match(/gist\.github\.com\/([^/]+)\/([a-f0-9]+)/);
     let rawUrl = gistUrl;
diff --git a/gitnexus/src/config/ignore-service.ts b/gitnexus/src/config/ignore-service.ts
index ff61f0eb31..ce1fda9133 100644
--- a/gitnexus/src/config/ignore-service.ts
+++ b/gitnexus/src/config/ignore-service.ts
@@ -2,6 +2,7 @@ import ignore, { type Ignore } from 'ignore';
 import fs from 'fs/promises';
 import nodePath from 'path';
 import type { Path } from 'path-scurry';
+import { logger } from '../core/logger.js';
 
 const DEFAULT_IGNORE_LIST = new Set([
   // Version Control
@@ -365,7 +366,7 @@ export const loadIgnoreRules = async (
     } catch (err: unknown) {
       const code = (err as NodeJS.ErrnoException).code;
       if (code !== 'ENOENT') {
-        console.warn(`  Warning: could not read ${filename}: ${(err as Error).message}`);
+        logger.warn(`  Warning: could not read ${filename}: ${(err as Error).message}`);
       }
     }
   }
diff --git a/gitnexus/src/core/embeddings/embedder.ts b/gitnexus/src/core/embeddings/embedder.ts
index 993c418839..72ddcbd707 100644
--- a/gitnexus/src/core/embeddings/embedder.ts
+++ b/gitnexus/src/core/embeddings/embedder.ts
@@ -14,7 +14,12 @@ if (!process.env.ORT_LOG_LEVEL) {
   process.env.ORT_LOG_LEVEL = '3';
 }
 
-import { pipeline, env, type FeatureExtractionPipeline } from '@huggingface/transformers';
+import {
+  pipeline,
+  env,
+  type FeatureExtractionPipeline,
+  type ProgressInfo,
+} from '@huggingface/transformers';
 import { existsSync } from 'fs';
 import { execFileSync } from 'child_process';
 import { join, dirname } from 'path';
@@ -22,7 +27,8 @@ import { createRequire } from 'module';
 import { DEFAULT_EMBEDDING_CONFIG, type EmbeddingConfig, type ModelProgress } from './types.js';
 import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.js';
 import { resolveEmbeddingConfig } from './config.js';
-import { applyHfEnvOverrides } from './hf-env.js';
+import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry } from './hf-env.js';
+import { logger } from '../logger.js';
 
 /**
  * Check whether the onnxruntime-node package that @huggingface/transformers
@@ -166,17 +172,22 @@ export const initEmbedder = async (
 
       const isDev = process.env.NODE_ENV === 'development';
       if (isDev) {
-        console.error(`🧠 Loading embedding model: ${finalConfig.modelId}`);
+        logger.info(`🧠 Loading embedding model: ${finalConfig.modelId}`);
       }
 
       const progressCallback = onProgress
-        ? (data: any) => {
+        ? (data: ProgressInfo) => {
             const progress: ModelProgress = {
-              status: data.status || 'progress',
-              file: data.file,
-              progress: data.progress,
-              loaded: data.loaded,
-              total: data.total,
+              // Map the `progress_total` aggregate event (not in ModelProgress.status)
+              // back to 'progress' so callers don't need to handle it separately.
+              status:
+                data.status === 'progress_total'
+                  ? 'progress'
+                  : ((data.status as ModelProgress['status']) ?? 'progress'),
+              file: 'file' in data ? data.file : undefined,
+              progress: 'progress' in data ? data.progress : undefined,
+              loaded: 'loaded' in data ? data.loaded : undefined,
+              total: 'total' in data ? data.total : undefined,
             };
             onProgress(progress);
           }
@@ -192,26 +203,38 @@ export const initEmbedder = async (
       for (const device of devicesToTry) {
         try {
           if (isDev && device === 'dml') {
-            console.error('🔧 Trying DirectML (DirectX12) GPU backend...');
+            logger.info('🔧 Trying DirectML (DirectX12) GPU backend...');
           } else if (isDev && device === 'cuda') {
-            console.error('🔧 Trying CUDA GPU backend...');
+            logger.info('🔧 Trying CUDA GPU backend...');
           } else if (isDev && device === 'cpu') {
-            console.error('🔧 Using CPU backend...');
+            logger.info('🔧 Using CPU backend...');
           } else if (isDev && device === 'wasm') {
-            console.error('🔧 Using WASM backend (slower)...');
+            logger.info('🔧 Using WASM backend (slower)...');
           }
 
-          embedderInstance = await (pipeline as any)('feature-extraction', finalConfig.modelId, {
-            device: device,
-            dtype: 'fp32',
-            progress_callback: progressCallback,
-            session_options: {
-              logSeverityLevel: 3,
-              intraOpNumThreads: finalConfig.threads,
-              interOpNumThreads: 1,
-              executionMode: 'sequential',
+          embedderInstance = await withHfDownloadRetry(
+            () =>
+              pipeline('feature-extraction', finalConfig.modelId, {
+                device: device,
+                dtype: 'fp32',
+                progress_callback: progressCallback,
+                session_options: {
+                  logSeverityLevel: 3,
+                  intraOpNumThreads: finalConfig.threads,
+                  interOpNumThreads: 1,
+                  executionMode: 'sequential',
+                },
+              }),
+            {
+              onRetry: isDev
+                ? (attempt, max, err) =>
+                    logger.warn(
+                      { attempt, max, err: err.message },
+                      `⚠️  Model download network error (attempt ${attempt}/${max}), retrying…`,
+                    )
+                : undefined,
             },
-          });
+          );
           currentDevice = device;
 
           if (isDev) {
@@ -221,15 +244,29 @@ export const initEmbedder = async (
                 : device === 'cuda'
                   ? 'GPU (CUDA)'
                   : device.toUpperCase();
-            console.error(`✅ Using ${label} backend`);
-            console.error('✅ Embedding model loaded successfully');
+            logger.info(`✅ Using ${label} backend`);
+            logger.info('✅ Embedding model loaded successfully');
           }
 
           return embedderInstance!;
         } catch (deviceError) {
+          // Network errors and circuit-open errors are not device-specific —
+          // they will fail the same way on every device. Rethrow immediately
+          // with actionable HF_ENDPOINT guidance rather than silently falling
+          // back to the next device.
+          const errMsg = deviceError instanceof Error ? deviceError.message : String(deviceError);
+          if (isHfDownloadFailure(errMsg)) {
+            const endpointHint = process.env.HF_ENDPOINT
+              ? `The configured endpoint (${process.env.HF_ENDPOINT}) may be unreachable.`
+              : `huggingface.co may be unreachable from your network.\n` +
+                `  Set HF_ENDPOINT to a mirror and retry:\n` +
+                `    HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
+                `    (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)`;
+            throw new Error(`Failed to download embedding model: ${errMsg}\n  ${endpointHint}`);
+          }
           if (isDev && (device === 'cuda' || device === 'dml')) {
             const gpuType = device === 'dml' ? 'DirectML' : 'CUDA';
-            console.error(`⚠️  ${gpuType} not available, falling back to CPU...`);
+            logger.info(`⚠️  ${gpuType} not available, falling back to CPU...`);
           }
           // Continue to next device in list
           if (device === devicesToTry[devicesToTry.length - 1]) {
diff --git a/gitnexus/src/core/embeddings/embedding-pipeline.ts b/gitnexus/src/core/embeddings/embedding-pipeline.ts
index 9d4f982818..cc2d38d9b0 100644
--- a/gitnexus/src/core/embeddings/embedding-pipeline.ts
+++ b/gitnexus/src/core/embeddings/embedding-pipeline.ts
@@ -44,6 +44,7 @@ import {
 } from '../lbug/schema.js';
 import { loadVectorExtension } from '../lbug/lbug-adapter.js';
 import { getExactScanLimit } from '../platform/capabilities.js';
+import { logger } from '../logger.js';
 
 const isDev = process.env.NODE_ENV === 'development';
 
@@ -157,7 +158,7 @@ const queryEmbeddableNodes = async (
       }
     } catch (error) {
       if (isDev) {
-        console.error(`Query for ${label} nodes failed:`, error);
+        logger.warn({ error }, `Query for ${label} nodes failed:`);
       }
     }
   }
@@ -212,7 +213,7 @@ const createVectorIndex = async (
     return true;
   } catch (error) {
     if (isDev) {
-      console.error('Vector index creation warning:', error);
+      logger.warn({ error }, 'Vector index creation warning:');
     }
     return false;
   }
@@ -256,7 +257,9 @@ export const runEmbeddingPipeline = async (
 
   try {
     const vectorAvailable = await ensureVectorExtensionAvailable();
-    if (!vectorAvailable && isDev) console.error(vectorUnavailableMessage);
+    if (!vectorAvailable && isDev) {
+      logger.warn(vectorUnavailableMessage);
+    }
 
     // Phase 1: Load embedding model
     onProgress({
@@ -283,7 +286,7 @@ export const runEmbeddingPipeline = async (
     });
 
     if (isDev) {
-      console.error('🔍 Querying embeddable nodes...');
+      logger.info('🔍 Querying embeddable nodes...');
     }
 
     // Phase 2: Query embeddable nodes
@@ -325,7 +328,7 @@ export const runEmbeddingPipeline = async (
       // (Kuzu forbids SET on vector-indexed properties; DELETE-then-INSERT is the sanctioned pattern)
       if (staleNodeIds.length > 0) {
         if (isDev) {
-          console.error(`🔄 Deleting ${staleNodeIds.length} stale embedding rows for re-embed`);
+          logger.info(`🔄 Deleting ${staleNodeIds.length} stale embedding rows for re-embed`);
         }
         try {
           await executeWithReusedStatement(
@@ -346,7 +349,7 @@ export const runEmbeddingPipeline = async (
       }
 
       if (isDev) {
-        console.error(
+        logger.info(
           `📦 Incremental embeddings: ${beforeCount} total, ${existingEmbeddings.size} cached, ${staleNodeIds.length} stale, ${nodes.length} to embed`,
         );
       }
@@ -355,7 +358,7 @@ export const runEmbeddingPipeline = async (
     const totalNodes = nodes.length;
 
     if (isDev) {
-      console.error(`📊 Found ${totalNodes} embeddable nodes`);
+      logger.info(`📊 Found ${totalNodes} embeddable nodes`);
     }
 
     if (totalNodes === 0) {
@@ -442,9 +445,9 @@ export const runEmbeddingPipeline = async (
             );
           } catch (chunkErr) {
             if (isDev) {
-              console.error(
+              logger.warn(
+                { chunkErr },
                 `⚠️ AST chunking failed for ${node.label} "${node.name}" (${node.filePath}), falling back to character-based chunking:`,
-                chunkErr,
               );
             }
             chunks = characterChunk(node.content, startLine, endLine, chunkSize, overlap);
@@ -482,9 +485,9 @@ export const runEmbeddingPipeline = async (
         try {
           embeddings = await embedBatch(subTexts);
         } catch (embedErr) {
-          console.error(
+          logger.error(
+            { embedErr },
             `❌ embedBatch failed for ${subTexts.length} texts (first: "${subTexts[0]?.substring(0, 80)}..."):`,
-            embedErr,
           );
           throw embedErr;
         }
@@ -520,7 +523,7 @@ export const runEmbeddingPipeline = async (
     });
 
     if (isDev) {
-      console.error('📇 Creating vector index...');
+      logger.info('📇 Creating vector index...');
     }
 
     const vectorIndexReady = await createVectorIndex(executeQuery);
@@ -533,7 +536,7 @@ export const runEmbeddingPipeline = async (
     });
 
     if (isDev) {
-      console.error(
+      logger.info(
         `✅ Embedding pipeline complete! (${totalChunks} chunks from ${totalNodes} nodes)`,
       );
     }
@@ -547,7 +550,7 @@ export const runEmbeddingPipeline = async (
     const errorMessage = error instanceof Error ? error.message : 'Unknown error';
 
     if (isDev) {
-      console.error('❌ Embedding pipeline error:', error);
+      logger.error({ error }, '❌ Embedding pipeline error:');
     }
 
     onProgress({
diff --git a/gitnexus/src/core/embeddings/hf-env.ts b/gitnexus/src/core/embeddings/hf-env.ts
index 6a977a76db..95548fff2a 100644
--- a/gitnexus/src/core/embeddings/hf-env.ts
+++ b/gitnexus/src/core/embeddings/hf-env.ts
@@ -1,6 +1,25 @@
 import os from 'node:os';
 import { join } from 'node:path';
 
+// ---------------------------------------------------------------------------
+// Download resilience defaults
+// ---------------------------------------------------------------------------
+
+/** Per-attempt timeout for the full model download (5 minutes). */
+export const HF_DOWNLOAD_TIMEOUT_MS = 5 * 60 * 1_000;
+/** Maximum total download attempts (1 initial + N-1 retries). */
+export const HF_MAX_ATTEMPTS = 3;
+/** Initial delay between retry attempts; doubles on each subsequent retry. */
+export const HF_BASE_DELAY_MS = 2_000;
+/** Number of consecutive failures required to open the circuit. */
+export const CB_FAILURE_THRESHOLD = 3;
+/** How long the circuit stays open before transitioning to half-open. */
+export const CB_RESET_TIMEOUT_MS = 60_000;
+/** Upper bound clamped on the env-override per-attempt timeout (30 minutes). */
+export const HF_MAX_TIMEOUT_MS = 30 * 60 * 1_000;
+/** Upper bound clamped on the env-override attempt count. */
+export const HF_MAX_ATTEMPTS_CAP = 10;
+
 /**
  * @internal Exported only for unit tests and the two embedder entry points
  * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Not part of the
@@ -60,3 +79,265 @@ export function applyHfEnvOverrides(env: HfEnvSubset): void {
     env.remoteHost = endpoint.endsWith('/') ? endpoint : endpoint + '/';
   }
 }
+
+/**
+ * @internal Exported for unit tests and the two embedder entry points.
+ *
+ * Returns true when an error message indicates a network-level fetch failure
+ * during HuggingFace model download (e.g. `TypeError: fetch failed`,
+ * `ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`, `ECONNRESET`).
+ *
+ * These errors are not device-specific and cannot be fixed by falling back to
+ * a different ONNX device — the caller should rethrow immediately with
+ * guidance about `HF_ENDPOINT`.
+ */
+export function isNetworkFetchError(message: string): boolean {
+  return (
+    message.includes('fetch failed') ||
+    message.includes('ECONNREFUSED') ||
+    message.includes('ENOTFOUND') ||
+    message.includes('ETIMEDOUT') ||
+    message.includes('ECONNRESET')
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Circuit breaker
+// ---------------------------------------------------------------------------
+
+/** @internal Used by `withHfDownloadRetry` to mark a circuit-open rejection. */
+export const CIRCUIT_OPEN_TAG = 'hf-circuit-open';
+
+/** Circuit-breaker states. */
+type CircuitState = 'closed' | 'open' | 'half-open';
+
+/**
+ * Circuit breaker for HuggingFace model downloads.
+ *
+ * After `failureThreshold` consecutive network failures the circuit opens and
+ * all subsequent calls to `withHfDownloadRetry` fail immediately without
+ * issuing any network requests. After `resetTimeoutMs` the circuit enters the
+ * half-open state and the next call is attempted — if it succeeds the circuit
+ * closes again; if it fails the circuit re-opens.
+ *
+ * Exported for unit-testing; production code should use the module-level
+ * `hfDownloadCircuit` singleton.
+ */
+export class HfDownloadCircuitBreaker {
+  private _state: CircuitState = 'closed';
+  private _failures = 0;
+  /** Timestamp of the last recorded failure (ms since epoch). */
+  lastFailureAt = 0;
+
+  constructor(
+    readonly failureThreshold: number = CB_FAILURE_THRESHOLD,
+    readonly resetTimeoutMs: number = CB_RESET_TIMEOUT_MS,
+  ) {}
+
+  /** Effective state, factoring in the reset-timeout transition. */
+  get state(): CircuitState {
+    if (this._state === 'open' && Date.now() - this.lastFailureAt > this.resetTimeoutMs) {
+      this._state = 'half-open';
+    }
+    return this._state;
+  }
+
+  /** Returns true when the circuit is open and calls should be rejected. */
+  isOpen(): boolean {
+    return this.state === 'open';
+  }
+
+  /** Record a successful call — resets the failure counter and closes the circuit. */
+  recordSuccess(): void {
+    this._failures = 0;
+    this._state = 'closed';
+  }
+
+  /** Record a failed call — increments the counter and opens the circuit when the threshold is reached. */
+  recordFailure(): void {
+    this._failures++;
+    this.lastFailureAt = Date.now();
+    if (this._failures >= this.failureThreshold) {
+      this._state = 'open';
+    }
+  }
+
+  /** @internal Reset to initial state (used in tests). */
+  reset(): void {
+    this._failures = 0;
+    this._state = 'closed';
+    this.lastFailureAt = 0;
+  }
+}
+
+/** Module-level singleton shared by both embedder entry points. */
+export const hfDownloadCircuit = new HfDownloadCircuitBreaker();
+
+// ---------------------------------------------------------------------------
+// Retry + timeout wrapper
+// ---------------------------------------------------------------------------
+
+/** @internal Returns true for errors that should abort without retry (circuit-open). */
+export function isHfCircuitOpenError(message: string): boolean {
+  return message.includes(CIRCUIT_OPEN_TAG);
+}
+
+/**
+ * Returns true for any HuggingFace download failure that warrants showing the
+ * `HF_ENDPOINT` remediation hint: either a raw network error or a
+ * circuit-open rejection (which itself was caused by repeated network errors).
+ */
+export function isHfDownloadFailure(message: string): boolean {
+  return isNetworkFetchError(message) || isHfCircuitOpenError(message);
+}
+
+/** @internal Wraps `fn` in a hard time-limit. The timeout error contains
+ *  `ETIMEDOUT` so that `isNetworkFetchError` classifies it correctly.
+ */
+export function withDownloadTimeout<T>(fn: () => Promise<T>, timeoutMs: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () =>
+        reject(
+          new Error(
+            `ETIMEDOUT: model download timed out after ${Math.round(timeoutMs / 1000)}s — ` +
+              `check your network speed or set HF_ENDPOINT to a faster mirror`,
+          ),
+        ),
+      timeoutMs,
+    );
+    fn().then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      },
+    );
+  });
+}
+
+/** @internal Async sleep (exposed for testing). */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export interface HfRetryOptions {
+  /** Maximum total attempts including the initial one (default: `HF_MAX_ATTEMPTS`). */
+  maxAttempts?: number;
+  /** Delay before the first retry; doubles on each subsequent attempt (default: `HF_BASE_DELAY_MS`). */
+  baseDelayMs?: number;
+  /** Per-attempt wall-clock timeout in ms (default: `HF_DOWNLOAD_TIMEOUT_MS`). */
+  timeoutMs?: number;
+  /**
+   * Circuit-breaker instance to use. Defaults to the module-level
+   * `hfDownloadCircuit` singleton. Pass a fresh instance in tests.
+   */
+  circuit?: HfDownloadCircuitBreaker;
+  /**
+   * Optional callback invoked before each retry (not the initial attempt).
+   * @param attempt - 1-based retry number
+   * @param max - total allowed attempts
+   * @param error - the error that triggered the retry
+   */
+  onRetry?: (attempt: number, max: number, error: Error) => void;
+}
+
+/**
+ * Retry wrapper for HuggingFace model downloads with per-attempt timeout and
+ * circuit-breaker protection.
+ *
+ * Behaviour:
+ * - If the circuit is **open**, fails immediately with a `CIRCUIT_OPEN_TAG`
+ *   message (so `isHfDownloadFailure` still returns true and the caller can
+ *   show `HF_ENDPOINT` guidance).
+ * - Each attempt is wrapped in `withDownloadTimeout`.
+ * - On a network-level error (`isNetworkFetchError`) the attempt is retried
+ *   with exponential back-off; non-network errors (e.g. ONNX device failure)
+ *   are rethrown immediately without retry.
+ * - Every network failure is recorded on the circuit breaker; a success resets
+ *   it.
+ * - After all attempts are exhausted, the last network error is rethrown
+ *   so the existing `isNetworkFetchError` / `isHfDownloadFailure` guards in
+ *   the calling code still fire.
+ */
+export async function withHfDownloadRetry<T>(
+  fn: () => Promise<T>,
+  options: HfRetryOptions = {},
+): Promise<T> {
+  // Resolve effective values — explicit options take precedence over env vars,
+  // which take precedence over built-in defaults. This lets users lower the
+  // per-attempt timeout without rebuilding (e.g.
+  //   HF_DOWNLOAD_TIMEOUT_MS=60000 npx gitnexus analyze --embeddings
+  // reduces the worst-case wait from 15 minutes to ~3 minutes).
+  //
+  // Upper bounds are clamped to prevent accidental runaway configuration:
+  //   - timeoutMs is capped at HF_MAX_TIMEOUT_MS (30 min)
+  //   - maxAttempts is floored (fractional values → integer) and capped at
+  //     HF_MAX_ATTEMPTS_CAP (10).  Values ≤ 0, NaN, or Infinity fall back to
+  //     the built-in defaults.
+  const envTimeout = Number(process.env.HF_DOWNLOAD_TIMEOUT_MS);
+  const envMaxAttempts = Number(process.env.HF_MAX_ATTEMPTS);
+  const resolvedTimeout =
+    Number.isFinite(envTimeout) && envTimeout > 0
+      ? Math.min(envTimeout, HF_MAX_TIMEOUT_MS)
+      : HF_DOWNLOAD_TIMEOUT_MS;
+  const resolvedMaxAttempts =
+    Number.isFinite(envMaxAttempts) && envMaxAttempts > 0
+      ? Math.min(Math.floor(envMaxAttempts), HF_MAX_ATTEMPTS_CAP)
+      : HF_MAX_ATTEMPTS;
+  const {
+    maxAttempts = resolvedMaxAttempts,
+    baseDelayMs = HF_BASE_DELAY_MS,
+    timeoutMs = resolvedTimeout,
+    circuit = hfDownloadCircuit,
+    onRetry,
+  } = options;
+  if (circuit.isOpen()) {
+    const secsUntilReset = Math.ceil(
+      (circuit.resetTimeoutMs - (Date.now() - circuit.lastFailureAt)) / 1000,
+    );
+    throw new Error(
+      `${CIRCUIT_OPEN_TAG}: HuggingFace download circuit is open after repeated network failures` +
+        (secsUntilReset > 0 ? ` — will reset in ~${secsUntilReset}s` : ''),
+    );
+  }
+
+  let lastError: Error = new Error('unknown error');
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      const result = await withDownloadTimeout(fn, timeoutMs);
+      circuit.recordSuccess();
+      return result;
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+
+      if (!isNetworkFetchError(lastError.message)) {
+        // Non-network error (e.g. CUDA unavailable) — propagate without retry
+        throw lastError;
+      }
+
+      circuit.recordFailure();
+
+      if (circuit.isOpen()) {
+        // Circuit just tripped — fail fast, no more retries
+        throw new Error(
+          `${CIRCUIT_OPEN_TAG}: HuggingFace download circuit opened after ${circuit.failureThreshold} consecutive failures`,
+        );
+      }
+
+      if (attempt < maxAttempts - 1) {
+        const delay = baseDelayMs * Math.pow(2, attempt);
+        onRetry?.(attempt + 1, maxAttempts, lastError);
+        await sleep(delay);
+      }
+    }
+  }
+
+  // All retries exhausted — throw the last network error so isNetworkFetchError
+  // patterns in the calling code still match and surface HF_ENDPOINT guidance.
+  throw lastError;
+}
diff --git a/gitnexus/src/core/git-staleness.ts b/gitnexus/src/core/git-staleness.ts
index 96f70ddd65..c90cef85ea 100644
--- a/gitnexus/src/core/git-staleness.ts
+++ b/gitnexus/src/core/git-staleness.ts
@@ -3,11 +3,14 @@
  * Lives in core/ so application code does not depend on the MCP package layer.
  */
 
-import { execFileSync } from 'node:child_process';
+import { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
 import path from 'path';
 import { readRegistry, type RegistryEntry, type CwdMatch } from '../storage/repo-manager.js';
 import { findGitRootByDotGit, getCurrentCommit, getRemoteUrl } from '../storage/git.js';
 
+const execFileAsync = promisify(execFile);
+
 export interface StalenessInfo {
   isStale: boolean;
   commitsBehind: number;
@@ -41,6 +44,39 @@ export function checkStaleness(repoPath: string, lastCommit: string): StalenessI
   }
 }
 
+/**
+ * Async variant of {@link checkStaleness} — spawns git as a child process
+ * instead of blocking the event loop.  Used by `listRepos()` to check many
+ * repos in parallel (issue #1363: 200 repos × sync spawn ≈ 50 s).
+ */
+export async function checkStalenessAsync(
+  repoPath: string,
+  lastCommit: string,
+): Promise<StalenessInfo> {
+  try {
+    // Note: promisified execFile captures stdout/stderr by default (no stdio option needed,
+    // unlike the sync variant which requires explicit stdio: ['pipe','pipe','pipe']).
+    const { stdout } = await execFileAsync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
+      cwd: repoPath,
+      encoding: 'utf-8',
+    });
+
+    const commitsBehind = parseInt(stdout.trim(), 10) || 0;
+
+    if (commitsBehind > 0) {
+      return {
+        isStale: true,
+        commitsBehind,
+        hint: `⚠️ Index is ${commitsBehind} commit${commitsBehind > 1 ? 's' : ''} behind HEAD. Run analyze tool to update.`,
+      };
+    }
+
+    return { isStale: false, commitsBehind: 0 };
+  } catch {
+    return { isStale: false, commitsBehind: 0 };
+  }
+}
+
 /**
  * Compare a sibling-clone HEAD against an indexed `lastCommit`. Returns
  * `undefined` when the indexed commit is not reachable from the sibling
diff --git a/gitnexus/src/core/group/bridge-db.ts b/gitnexus/src/core/group/bridge-db.ts
index ef45d68190..ef6244b22a 100644
--- a/gitnexus/src/core/group/bridge-db.ts
+++ b/gitnexus/src/core/group/bridge-db.ts
@@ -11,6 +11,9 @@ import {
   type LbugConnectionHandle,
 } from '../lbug/lbug-config.js';
 import { dedupeContracts, dedupeCrossLinks } from './normalization.js';
+import { createLogger } from '../logger.js';
+
+const bridgeLogger = createLogger('bridge-db', { debugEnvVar: 'GITNEXUS_DEBUG_BRIDGE' });
 
 /**
  * Sidecar files that LadybugDB creates next to a `bridge.lbug` file.
@@ -41,26 +44,6 @@ async function removeLbugFile(basePath: string): Promise<void> {
   }
 }
 
-/**
- * Remove all stale `bridge.lbug.tmp.*` files (and their sidecars) from a
- * group directory.  With randomBytes-based temp names, a crashed writeBridge
- * leaves behind a uniquely-named tmp file that no future run will target by
- * name — so we glob for the prefix and clean up everything matching.
- */
-async function cleanStaleBridgeTmpFiles(groupDir: string): Promise<void> {
-  try {
-    const entries = await fsp.readdir(groupDir);
-    const staleBases = entries.filter(
-      (e) => e.startsWith('bridge.lbug.tmp.') && !LBUG_SIDECAR_SUFFIXES.some((s) => e.endsWith(s)),
-    );
-    for (const name of staleBases) {
-      await removeLbugFile(path.join(groupDir, name));
-    }
-  } catch {
-    /* best-effort: directory may not exist yet */
-  }
-}
-
 export function contractNodeId(
   repo: string,
   contractId: string,
@@ -296,8 +279,24 @@ export async function retryRename(src: string, dst: string, attempts = 3): Promi
 
 export async function writeBridgeMeta(groupDir: string, meta: BridgeMeta): Promise<void> {
   const target = path.join(groupDir, 'meta.json');
+  // Unpredictable suffix + O_EXCL via `'wx'` flag closes the symlink/
+  // pre-create attack window. The third argument `0o600` is the
+  // user-only mode mask — CodeQL's `js/insecure-temporary-file` query
+  // sources its verdict from the `mode` argument, NOT from `flags`:
+  // its `isSecureMode(mode)` predicate requires the low 6 bits to be
+  // zero (no group/world bits). Without an explicit mode the file is
+  // created with the process umask (typically 0o644 = group/world
+  // readable), which the query treats as the actual vulnerability.
+  // Both `'wx'` (runtime O_EXCL) AND `0o600` (CodeQL-credited mode)
+  // are needed: one closes the symlink race, the other closes the
+  // permissions exposure.
   const tmp = `${target}.tmp.${randomBytes(8).toString('hex')}`;
-  await fsp.writeFile(tmp, JSON.stringify(meta, null, 2), 'utf-8');
+  const handle = await fsp.open(tmp, 'wx', 0o600);
+  try {
+    await handle.writeFile(JSON.stringify(meta, null, 2), 'utf-8');
+  } finally {
+    await handle.close();
+  }
   // Use retryRename for consistency with writeBridge's atomic swap — on
   // Windows a concurrent reader can cause EBUSY/EPERM even on a tiny
   // meta.json, and we don't want meta write to be less robust than the
@@ -366,7 +365,19 @@ export async function writeBridge(
   const crossLinks = dedupeCrossLinks(input.crossLinks);
 
   const finalPath = path.join(groupDir, 'bridge.lbug');
-  const tmpPath = path.join(groupDir, `bridge.lbug.tmp.${randomBytes(8).toString('hex')}`);
+  // Stage the temp database inside a unique mkdtemp directory rather than
+  // a fixed `bridge.lbug.tmp` name. The previous shape was flagged by
+  // CodeQL js/insecure-temporary-file as a predictable path: a co-located
+  // attacker (or a parallel writeBridge call into the same group) could
+  // pre-create or symlink that path before this writer opens it. mkdtemp
+  // returns a directory whose suffix is filled with cryptographically
+  // random bytes, so the staging path is unguessable AND collision-free
+  // across parallel callers. We anchor the staging directory inside
+  // `groupDir` so the subsequent rename of `bridge.lbug` (and its
+  // `.wal` / `.shadow` sidecars) into place stays on the same filesystem
+  // and remains atomic — moving across `os.tmpdir()` could trip EXDEV.
+  const stagingDir = await fsp.mkdtemp(path.join(groupDir, 'bridge-tmp-'));
+  const tmpPath = path.join(stagingDir, 'bridge.lbug');
   const bakPath = path.join(groupDir, 'bridge.lbug.bak');
 
   const report: WriteBridgeReport = {
@@ -386,43 +397,42 @@ export async function writeBridge(
     }
   };
 
-  // Clean up stale tmp files left behind by previously crashed writeBridge
-  // runs.  With randomBytes-based names each run picks a unique path, so
-  // the old fixed-name `removeLbugFile(tmpPath)` was a no-op — stale
-  // artifacts accumulated.  The glob-based helper finds *all* leftover
-  // `bridge.lbug.tmp.*` entries and removes them (including sidecars).
-  await cleanStaleBridgeTmpFiles(groupDir);
-
-  // 1. Create temp DB, insert all data.
-  //
-  // Everything after `openBridgeDb` must run inside a try/finally so that
-  // if ANY step before the explicit `closeBridgeDb` throws — schema
-  // creation, a contract insert loop that rethrows, a snapshot write, the
-  // cross-link loop, or anything else — the handle is still released. A
-  // leaked handle holds the native LadybugDB file lock on tmpPath, which
-  // (a) leaks a FD and (b) prevents the next writeBridge call from
-  // reusing the same tmp slot.
-  const handle = await openBridgeDb(tmpPath);
-  let handleClosed = false;
+  // The mkdtemp staging directory above is freshly created with a unique
+  // random suffix, so there are no leftover `bridge.lbug.tmp` / `.wal` /
+  // `.shadow` sidecars from a previous crashed run to clean up here — the
+  // directory is empty by construction.
+
   try {
-    await ensureBridgeSchema(handle);
-
-    // Build the lookup index incrementally as contracts are inserted, so
-    // failed inserts are never in the index (and therefore never resolved
-    // by the cross-link loop below). This replaces a previous N+1 query
-    // pattern where each link made up to 6 DB round-trips to find its
-    // endpoints — see ContractLookupIndex.
-    const lookupIndex = createContractLookupIndex();
-
-    // Insert contracts — tolerate individual failures (e.g., a corrupt meta
-    // that can't be serialized). The whole sync must not fail because one
-    // contract is broken.
-    for (const c of contracts) {
-      const id = contractNodeId(c.repo, c.contractId, c.role, c.symbolRef.filePath);
-      try {
-        await queryBridge(
-          handle,
-          `CREATE (n:Contract {
+    // 1. Create temp DB, insert all data.
+    //
+    // Everything after `openBridgeDb` must run inside a try/finally so that
+    // if ANY step before the explicit `closeBridgeDb` throws — schema
+    // creation, a contract insert loop that rethrows, a snapshot write, the
+    // cross-link loop, or anything else — the handle is still released. A
+    // leaked handle holds the native LadybugDB file lock on tmpPath, which
+    // (a) leaks a FD and (b) prevents the next writeBridge call from
+    // reusing the same tmp slot.
+    const handle = await openBridgeDb(tmpPath);
+    let handleClosed = false;
+    try {
+      await ensureBridgeSchema(handle);
+
+      // Build the lookup index incrementally as contracts are inserted, so
+      // failed inserts are never in the index (and therefore never resolved
+      // by the cross-link loop below). This replaces a previous N+1 query
+      // pattern where each link made up to 6 DB round-trips to find its
+      // endpoints — see ContractLookupIndex.
+      const lookupIndex = createContractLookupIndex();
+
+      // Insert contracts — tolerate individual failures (e.g., a corrupt meta
+      // that can't be serialized). The whole sync must not fail because one
+      // contract is broken.
+      for (const c of contracts) {
+        const id = contractNodeId(c.repo, c.contractId, c.role, c.symbolRef.filePath);
+        try {
+          await queryBridge(
+            handle,
+            `CREATE (n:Contract {
       id: $id,
       contractId: $contractId,
       type: $type,
@@ -435,91 +445,91 @@ export async function writeBridge(
       confidence: $confidence,
       meta: $meta
     })`,
-          {
-            id,
-            contractId: c.contractId,
-            type: c.type,
-            role: c.role,
-            repo: c.repo,
-            service: c.service ?? '',
-            symbolUid: c.symbolUid,
-            filePath: c.symbolRef.filePath,
-            symbolName: c.symbolName,
-            confidence: c.confidence,
-            meta: JSON.stringify(c.meta),
-          },
-        );
-        report.contractsInserted++;
-        // Only index on successful insert — the cross-link loop must never
-        // resolve to a row that isn't actually in the DB.
-        indexContract(lookupIndex, c, id);
-      } catch (err) {
-        report.contractsFailed++;
-        recordError('contract', id, err);
+            {
+              id,
+              contractId: c.contractId,
+              type: c.type,
+              role: c.role,
+              repo: c.repo,
+              service: c.service ?? '',
+              symbolUid: c.symbolUid,
+              filePath: c.symbolRef.filePath,
+              symbolName: c.symbolName,
+              confidence: c.confidence,
+              meta: JSON.stringify(c.meta),
+            },
+          );
+          report.contractsInserted++;
+          // Only index on successful insert — the cross-link loop must never
+          // resolve to a row that isn't actually in the DB.
+          indexContract(lookupIndex, c, id);
+        } catch (err) {
+          report.contractsFailed++;
+          recordError('contract', id, err);
+        }
       }
-    }
 
-    // Insert repo snapshots
-    for (const [repoId, snap] of Object.entries(input.repoSnapshots)) {
-      try {
-        await queryBridge(
-          handle,
-          `CREATE (s:RepoSnapshot {
+      // Insert repo snapshots
+      for (const [repoId, snap] of Object.entries(input.repoSnapshots)) {
+        try {
+          await queryBridge(
+            handle,
+            `CREATE (s:RepoSnapshot {
       id: $id,
       indexedAt: $indexedAt,
       lastCommit: $lastCommit
     })`,
-          {
-            id: repoId,
-            indexedAt: snap.indexedAt,
-            lastCommit: snap.lastCommit,
-          },
-        );
-        report.snapshotsInserted++;
-      } catch (err) {
-        report.snapshotsFailed++;
-        recordError('snapshot', repoId, err);
+            {
+              id: repoId,
+              indexedAt: snap.indexedAt,
+              lastCommit: snap.lastCommit,
+            },
+          );
+          report.snapshotsInserted++;
+        } catch (err) {
+          report.snapshotsFailed++;
+          recordError('snapshot', repoId, err);
+        }
       }
-    }
 
-    // Insert cross-links (tolerating missing nodes).
-    //
-    // `findContractNode` consults the in-memory lookup index built above,
-    // not the DB — that's an O(1) pure-function lookup per endpoint instead
-    // of the previous 2-3 DB queries. For M cross-links, the previous code
-    // issued up to 6M round-trips; this version issues zero.
-    //
-    // `link.contractId` may differ between the consumer and provider sides
-    // (e.g. wildcard consumer `grpc::Service/*` → method-level provider
-    // `grpc::Service/Method`) — that's why we resolve each endpoint
-    // independently via its own `(repo, role, symbolUid, filePath, symbolName)`
-    // tuple rather than matching on contractId.
-    for (const link of crossLinks) {
-      const linkId = `${link.from.repo}::${link.contractId}->${link.to.repo}::${link.contractId}`;
-      try {
-        const fromId = findContractNode(
-          lookupIndex,
-          link.from.repo,
-          'consumer',
-          link.from.symbolUid,
-          link.from.symbolRef.filePath,
-          link.from.symbolRef.name,
-        );
-        const toId = findContractNode(
-          lookupIndex,
-          link.to.repo,
-          'provider',
-          link.to.symbolUid,
-          link.to.symbolRef.filePath,
-          link.to.symbolRef.name,
-        );
-        if (!fromId || !toId) {
-          report.linksDroppedMissingNode++;
-          continue;
-        }
-        await queryBridge(
-          handle,
-          `
+      // Insert cross-links (tolerating missing nodes).
+      //
+      // `findContractNode` consults the in-memory lookup index built above,
+      // not the DB — that's an O(1) pure-function lookup per endpoint instead
+      // of the previous 2-3 DB queries. For M cross-links, the previous code
+      // issued up to 6M round-trips; this version issues zero.
+      //
+      // `link.contractId` may differ between the consumer and provider sides
+      // (e.g. wildcard consumer `grpc::Service/*` → method-level provider
+      // `grpc::Service/Method`) — that's why we resolve each endpoint
+      // independently via its own `(repo, role, symbolUid, filePath, symbolName)`
+      // tuple rather than matching on contractId.
+      for (const link of crossLinks) {
+        const linkId = `${link.from.repo}::${link.contractId}->${link.to.repo}::${link.contractId}`;
+        try {
+          const fromId = findContractNode(
+            lookupIndex,
+            link.from.repo,
+            'consumer',
+            link.from.symbolUid,
+            link.from.symbolRef.filePath,
+            link.from.symbolRef.name,
+          );
+          const toId = findContractNode(
+            lookupIndex,
+            link.to.repo,
+            'provider',
+            link.to.symbolUid,
+            link.to.symbolRef.filePath,
+            link.to.symbolRef.name,
+          );
+          if (!fromId || !toId) {
+            report.linksDroppedMissingNode++;
+            continue;
+          }
+          await queryBridge(
+            handle,
+            `
       MATCH (a:Contract), (b:Contract)
       WHERE a.id = $fromId AND b.id = $toId
       CREATE (a)-[:ContractLink {
@@ -530,83 +540,93 @@ export async function writeBridge(
         toRepo: $toRepo
       }]->(b)
     `,
-          {
-            fromId,
-            toId,
-            matchType: link.matchType,
-            confidence: link.confidence,
-            contractId: link.contractId,
-            fromRepo: link.from.repo,
-            toRepo: link.to.repo,
-          },
-        );
-        report.linksInserted++;
-      } catch (err) {
-        report.linksFailed++;
-        recordError('link', linkId, err);
+            {
+              fromId,
+              toId,
+              matchType: link.matchType,
+              confidence: link.confidence,
+              contractId: link.contractId,
+              fromRepo: link.from.repo,
+              toRepo: link.to.repo,
+            },
+          );
+          report.linksInserted++;
+        } catch (err) {
+          report.linksFailed++;
+          recordError('link', linkId, err);
+        }
       }
-    }
 
-    // 2. Close temp DB (happy path). The finally block also calls
-    //    closeBridgeDb if we threw above; `handleClosed` prevents a
-    //    double-close on the native handle.
-    await closeBridgeDb(handle);
-    handleClosed = true;
-  } finally {
-    if (!handleClosed) {
-      await closeBridgeDb(handle).catch(() => {
-        /* ignore: cleanup path, best effort */
-      });
+      // 2. Close temp DB (happy path). The finally block also calls
+      //    closeBridgeDb if we threw above; `handleClosed` prevents a
+      //    double-close on the native handle.
+      await closeBridgeDb(handle);
+      handleClosed = true;
+    } finally {
+      if (!handleClosed) {
+        await closeBridgeDb(handle).catch(() => {
+          /* ignore: cleanup path, best effort */
+        });
+      }
     }
-  }
 
-  // 3. Atomic swap: old→.bak, tmp→final, rm .bak
-  //
-  // The current database file (with its `.wal` / `.shadow` sidecars) is
-  // moved aside, then the freshly built tmp database takes its place.
-  // We move the sidecars together with the main file so the open below
-  // and any external readers see a consistent set; orphan sidecars from
-  // the tmp namespace are then removed because LadybugDB looks for them
-  // under the renamed-to base name and would reject mismatching IDs.
-  try {
-    await fsp.access(finalPath);
-    await retryRename(finalPath, bakPath);
+    // 3. Atomic swap: old→.bak, tmp→final, rm .bak
+    //
+    // The current database file (with its `.wal` / `.shadow` sidecars) is
+    // moved aside, then the freshly built tmp database takes its place.
+    // We move the sidecars together with the main file so the open below
+    // and any external readers see a consistent set; orphan sidecars from
+    // the tmp namespace are then removed because LadybugDB looks for them
+    // under the renamed-to base name and would reject mismatching IDs.
+    try {
+      await fsp.access(finalPath);
+      await retryRename(finalPath, bakPath);
+      for (const suffix of LBUG_SIDECAR_SUFFIXES) {
+        try {
+          await fsp.access(`${finalPath}${suffix}`);
+          await retryRename(`${finalPath}${suffix}`, `${bakPath}${suffix}`);
+        } catch {
+          /* sidecar absent — nothing to move */
+        }
+      }
+    } catch {
+      /* no existing db */
+    }
+    await retryRename(tmpPath, finalPath);
     for (const suffix of LBUG_SIDECAR_SUFFIXES) {
+      // Rename — not delete — so the WAL (which may carry uncommitted-at-
+      // close-time pages on a graceful close, depending on
+      // `autoCheckpoint` / `checkpointThreshold`) and the `.shadow`
+      // checkpoint snapshot stay paired with the database file under its
+      // final name. LadybugDB 0.16.0's database-id check rejects an open
+      // when the sidecars belong to a different base name.
       try {
-        await fsp.access(`${finalPath}${suffix}`);
-        await retryRename(`${finalPath}${suffix}`, `${bakPath}${suffix}`);
+        await fsp.access(`${tmpPath}${suffix}`);
+        await retryRename(`${tmpPath}${suffix}`, `${finalPath}${suffix}`);
       } catch {
         /* sidecar absent — nothing to move */
       }
     }
-  } catch {
-    /* no existing db */
-  }
-  await retryRename(tmpPath, finalPath);
-  for (const suffix of LBUG_SIDECAR_SUFFIXES) {
-    // Rename — not delete — so the WAL (which may carry uncommitted-at-
-    // close-time pages on a graceful close, depending on
-    // `autoCheckpoint` / `checkpointThreshold`) and the `.shadow`
-    // checkpoint snapshot stay paired with the database file under its
-    // final name. LadybugDB 0.16.0's database-id check rejects an open
-    // when the sidecars belong to a different base name.
-    try {
-      await fsp.access(`${tmpPath}${suffix}`);
-      await retryRename(`${tmpPath}${suffix}`, `${finalPath}${suffix}`);
-    } catch {
-      /* sidecar absent — nothing to move */
-    }
-  }
-  await removeLbugFile(bakPath);
+    await removeLbugFile(bakPath);
 
-  // 4. Write meta.json
-  await writeBridgeMeta(groupDir, {
-    version: BRIDGE_SCHEMA_VERSION,
-    generatedAt: new Date().toISOString(),
-    missingRepos: input.missingRepos,
-  });
+    // 4. Write meta.json
+    await writeBridgeMeta(groupDir, {
+      version: BRIDGE_SCHEMA_VERSION,
+      generatedAt: new Date().toISOString(),
+      missingRepos: input.missingRepos,
+    });
 
-  return report;
+    return report;
+  } finally {
+    // Always remove the mkdtemp staging directory. On the happy path the
+    // main file and sidecars have been renamed out of it, so it's empty;
+    // on any error path it may still contain a partial database — either
+    // way `recursive: true, force: true` removes it without surfacing
+    // "directory not empty" or ENOENT.
+    await fsp.rm(stagingDir, { recursive: true, force: true }).catch(() => {
+      /* best-effort cleanup */
+    });
+  }
 }
 
 /* ------------------------------------------------------------------ */
@@ -702,14 +722,15 @@ export async function openBridgeDbReadOnly(groupDir: string): Promise<BridgeHand
       await new Promise((r) => setTimeout(r, delay));
     }
   }
-  if (process.env.GITNEXUS_DEBUG_BRIDGE) {
-    console.warn(
-      `[bridge-db] openBridgeDbReadOnly(${groupDir}) gave up after ` +
-        `${LBUG_OPEN_RETRY_ATTEMPTS} attempts: ${
-          lastErr instanceof Error ? lastErr.message : String(lastErr)
-        }`,
-    );
-  }
+  // Pino's NDJSON serialization is structurally injection-resistant
+  // (CodeQL js/log-injection): groupDir and err.message are JSON-escaped
+  // by the serializer, so no manual CRLF / U+2028 / ANSI sanitization is
+  // needed. Demoted to debug — only fires when the bridge truly gave up
+  // after retries, and operators only need it at debug verbosity.
+  bridgeLogger.debug(
+    { groupDir, err: lastErr, attempts: LBUG_OPEN_RETRY_ATTEMPTS },
+    'openBridgeDbReadOnly gave up',
+  );
   return null;
 }
 
diff --git a/gitnexus/src/core/group/config-parser.ts b/gitnexus/src/core/group/config-parser.ts
index 73a9021b9e..d4f6ffff9d 100644
--- a/gitnexus/src/core/group/config-parser.ts
+++ b/gitnexus/src/core/group/config-parser.ts
@@ -4,7 +4,15 @@ import type { GroupConfig, GroupManifestLink, ContractType, ContractRole } from
 const _require = createRequire(import.meta.url);
 const yaml = _require('js-yaml') as typeof import('js-yaml');
 
-const VALID_CONTRACT_TYPES: ContractType[] = ['http', 'grpc', 'thrift', 'topic', 'lib', 'custom'];
+const VALID_CONTRACT_TYPES: ContractType[] = [
+  'http',
+  'grpc',
+  'thrift',
+  'topic',
+  'lib',
+  'custom',
+  'include',
+];
 const VALID_ROLES: ContractRole[] = ['provider', 'consumer'];
 
 const DEFAULT_DETECT = {
@@ -14,6 +22,7 @@ const DEFAULT_DETECT = {
   topics: true,
   shared_libs: true,
   embedding_fallback: true,
+  includes: true,
   workspace_deps: false,
 };
 
diff --git a/gitnexus/src/core/group/cross-impact.ts b/gitnexus/src/core/group/cross-impact.ts
index f8625cdc5f..eab942a62d 100644
--- a/gitnexus/src/core/group/cross-impact.ts
+++ b/gitnexus/src/core/group/cross-impact.ts
@@ -91,6 +91,25 @@ function clampCrossDepth(raw: unknown): { depth: number; warning?: string } {
   return { depth: d };
 }
 
+/**
+ * Clamp the impact timeout to a sane bounded range. Callers can feed this
+ * via tool params, so an unclamped value lets a single request hold a
+ * timer slot for an arbitrarily long duration (CodeQL js/resource-
+ * exhaustion). 100ms lower bound preserves test-suite scenarios that
+ * exercise tight timeouts; 5min upper bound is well above any legitimate
+ * single-impact compute. Applied at the validate boundary so the
+ * downstream `deadline` (Date.now() + timeoutMs) and the local-leg
+ * `setTimeout` see the same clamped value — earlier shapes had a 1hr
+ * outer cap and a 5min inner clamp that disagreed.
+ */
+export const IMPACT_TIMEOUT_MIN_MS = 100;
+export const IMPACT_TIMEOUT_MAX_MS = 5 * 60 * 1_000;
+
+export function clampTimeout(timeoutMs: number): number {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return IMPACT_TIMEOUT_MIN_MS;
+  return Math.min(IMPACT_TIMEOUT_MAX_MS, Math.max(IMPACT_TIMEOUT_MIN_MS, Math.trunc(timeoutMs)));
+}
+
 export function validateGroupImpactParams(params: Record<string, unknown>):
   | {
       ok: true;
@@ -143,13 +162,19 @@ export function validateGroupImpactParams(params: Record<string, unknown>):
   const service = normalizeServicePrefix(params.service);
   const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
 
-  let timeoutMs =
+  // Clamp at the validate boundary so the downstream `deadline` (line
+  // ~366) and `safeLocalImpact`'s `setTimeout` both see a single
+  // bounded value. Without this, the outer deadline budgeted Phase-2
+  // cross-repo fanout up to 1hr while only the inner setTimeout was
+  // capped to 5min — the two halves of CodeQL #184's mitigation
+  // disagreed.
+  const rawTimeoutMs =
     typeof params.timeoutMs === 'number' && params.timeoutMs > 0
       ? params.timeoutMs
       : typeof params.timeout === 'number' && params.timeout > 0
         ? params.timeout
         : DEFAULT_LOCAL_IMPACT_TIMEOUT_MS;
-  if (timeoutMs > 3_600_000) timeoutMs = 3_600_000;
+  const timeoutMs = clampTimeout(rawTimeoutMs);
 
   return {
     ok: true,
@@ -191,12 +216,13 @@ async function safeLocalImpact(
   impactParams: Parameters<GroupToolPort['impact']>[1],
   timeoutMs: number,
 ): Promise<{ value: unknown; timedOut: boolean }> {
+  const safeTimeoutMs = clampTimeout(timeoutMs);
   let timer: ReturnType<typeof setTimeout> | undefined;
   const impactP = port.impact(repo, impactParams).catch((err) => ({
     error: err instanceof Error ? err.message : String(err),
   }));
   const timeoutP = new Promise<'timeout'>((resolve) => {
-    timer = setTimeout(() => resolve('timeout'), timeoutMs);
+    timer = setTimeout(() => resolve('timeout'), safeTimeoutMs);
   });
   const won = await Promise.race([
     impactP.then((v) => ({ tag: 'impact' as const, v })),
@@ -212,6 +238,65 @@ async function safeLocalImpact(
   return { value: won.v, timedOut: false };
 }
 
+/**
+ * Race a single Phase-2 `impactByUid` call against a remaining-budget
+ * timer. The Codex adversarial review on PR #1331 surfaced that the
+ * fanout loop only checked `Date.now() > deadline` *between* neighbor
+ * calls — once `await port.impactByUid(...)` was reached, a hung
+ * neighbor could pin the request indefinitely, and slow neighbors
+ * could compound past the 5-min `IMPACT_TIMEOUT_MAX_MS` cap.
+ *
+ * This helper wraps each call: a `setTimeout(remainingMs)` aborts an
+ * `AbortController` whose signal is forwarded to `impactByUid`, and a
+ * `Promise.race` resolves to `{ timedOut: true }` when the timer
+ * fires before the call completes. Implementors that ignore the
+ * signal (current local backend) still see their await resolved by
+ * the race; full cooperative cancellation inside the BFS is a future
+ * follow-up. On rejection, the value is `null` (matching the
+ * fanout's existing `if (fan == null)` truncation contract).
+ *
+ * Exported for direct unit testing — the helper IS the load-bearing
+ * mitigation surface, so the U3 regression test pins it directly
+ * rather than driving the full `runGroupImpact` path.
+ */
+export async function safeNeighborImpact(
+  port: GroupToolPort,
+  repoId: string,
+  uid: string,
+  direction: string,
+  opts: {
+    maxDepth: number;
+    relationTypes: string[];
+    minConfidence: number;
+    includeTests: boolean;
+  },
+  remainingMs: number,
+): Promise<{ value: unknown; timedOut: boolean }> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const callP = port
+    .impactByUid(repoId, uid, direction, { ...opts, signal: controller.signal })
+    .catch(() => null);
+  const timeoutP = new Promise<'timeout'>((resolve) => {
+    timer = setTimeout(
+      () => {
+        controller.abort();
+        resolve('timeout');
+      },
+      Math.max(0, remainingMs),
+    );
+  });
+  const won = await Promise.race([
+    callP.then((v) => ({ tag: 'impact' as const, v })),
+    timeoutP.then(() => ({ tag: 'timeout' as const })),
+  ]);
+  if (timer !== undefined) clearTimeout(timer);
+  if (won.tag === 'timeout') {
+    return { value: null, timedOut: true };
+  }
+  return { value: won.v, timedOut: false };
+}
+
 export function collectImpactSymbolUids(
   local: unknown,
   servicePrefix: string | undefined,
@@ -476,7 +561,8 @@ export async function runGroupImpact(
       if (seen.has(key)) continue;
       seen.add(key);
 
-      if (Date.now() > deadline) {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
         truncatedRepos.push(n.neighborRepo);
         continue;
       }
@@ -492,13 +578,25 @@ export async function runGroupImpact(
         continue;
       }
 
-      const fan = await deps.port.impactByUid(neighborHandle.id, n.neighborUid, direction, {
-        maxDepth,
-        relationTypes: relationTypes ?? [],
-        minConfidence,
-        includeTests,
-      });
-      if (fan == null) {
+      // Phase-2 hardening: race each impactByUid against a per-call
+      // timeout derived from the remaining budget. Without this wrap a
+      // single hung neighbor would pin the request past the clamped
+      // timeout, which Codex's adversarial review on PR #1331 flagged
+      // as the still-open half of CodeQL #184 / js/resource-exhaustion.
+      const { value: fan, timedOut: neighborTimedOut } = await safeNeighborImpact(
+        deps.port,
+        neighborHandle.id,
+        n.neighborUid,
+        direction,
+        {
+          maxDepth,
+          relationTypes: relationTypes ?? [],
+          minConfidence,
+          includeTests,
+        },
+        remainingMs,
+      );
+      if (neighborTimedOut || fan == null) {
         truncatedRepos.push(n.neighborRepo);
         continue;
       }
diff --git a/gitnexus/src/core/group/extractors/elixir-workspace-extractor.ts b/gitnexus/src/core/group/extractors/elixir-workspace-extractor.ts
index 33afcaed9f..7c184ba96b 100644
--- a/gitnexus/src/core/group/extractors/elixir-workspace-extractor.ts
+++ b/gitnexus/src/core/group/extractors/elixir-workspace-extractor.ts
@@ -4,6 +4,7 @@ import type { CypherExecutor } from '../contract-extractor.js';
 import type { GroupManifestLink, ContractRole } from '../types.js';
 import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
 
+import { logger } from '../../logger.js';
 interface ElixirAppMeta {
   appName: string;
   modulePrefix: string;
@@ -202,7 +203,7 @@ export async function extractElixirWorkspaceLinks(
     };
     const existing = appsByName.get(manifest.appName);
     if (existing) {
-      console.warn(
+      logger.warn(
         `[elixir-workspace-extractor] duplicate app "${manifest.appName}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
       );
       continue;
diff --git a/gitnexus/src/core/group/extractors/go-workspace-extractor.ts b/gitnexus/src/core/group/extractors/go-workspace-extractor.ts
index fbdf0e450c..55e8700900 100644
--- a/gitnexus/src/core/group/extractors/go-workspace-extractor.ts
+++ b/gitnexus/src/core/group/extractors/go-workspace-extractor.ts
@@ -4,6 +4,7 @@ import type { CypherExecutor } from '../contract-extractor.js';
 import type { GroupManifestLink, ContractRole } from '../types.js';
 import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
 
+import { logger } from '../../logger.js';
 interface GoModuleMeta {
   modulePath: string;
   groupPath: string;
@@ -211,7 +212,7 @@ export async function extractGoWorkspaceLinks(
     };
     const existing = modulesByPath.get(manifest.modulePath);
     if (existing) {
-      console.warn(
+      logger.warn(
         `[go-workspace-extractor] duplicate module "${manifest.modulePath}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
       );
       continue;
diff --git a/gitnexus/src/core/group/extractors/grpc-extractor.ts b/gitnexus/src/core/group/extractors/grpc-extractor.ts
index b5782d9b34..c08ba7c367 100644
--- a/gitnexus/src/core/group/extractors/grpc-extractor.ts
+++ b/gitnexus/src/core/group/extractors/grpc-extractor.ts
@@ -5,6 +5,7 @@ import { createIgnoreFilter } from '../../../config/ignore-service.js';
 import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
 import type { ExtractedContract, RepoHandle } from '../types.js';
 import { readSafe } from './fs-utils.js';
+import { logger } from '../../logger.js';
 import {
   GRPC_SCAN_GLOB,
   getPluginForFile,
@@ -344,7 +345,7 @@ export function resolveProtoConflict(
   // services under a fabricated package-qualified contract id.
   if (winners.length !== 1) {
     const paths = candidates.map((c) => c.protoPath).join(', ');
-    console.warn(
+    logger.warn(
       `[grpc-extractor] Ambiguous proto resolution for service "${serviceName}" from ${sourceFilePath}: ${winners.length} candidates tied at score ${maxScore} among [${paths}] — skipping canonical contract`,
     );
     return null;
diff --git a/gitnexus/src/core/group/extractors/include-extractor.ts b/gitnexus/src/core/group/extractors/include-extractor.ts
new file mode 100644
index 0000000000..f3c54b464c
--- /dev/null
+++ b/gitnexus/src/core/group/extractors/include-extractor.ts
@@ -0,0 +1,514 @@
+import * as path from 'node:path';
+import { glob } from 'glob';
+import Parser from 'tree-sitter';
+import C from 'tree-sitter-c';
+import Cpp from 'tree-sitter-cpp';
+import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
+import type { ExtractedContract, RepoHandle } from '../types.js';
+import { readSafe } from './fs-utils.js';
+import { buildSuffixIndex, type SuffixIndex } from '../../ingestion/import-resolvers/utils.js';
+
+/**
+ * Cross-repo C/C++ `#include` dependency extractor.
+ *
+ * **Provider side:** registers every `.h/.hpp/.hxx/.hh` file in the repo
+ * as a provider contract with `include::<relative-path>`.
+ *
+ * **Consumer side:** parses all C/C++ source/header files for `#include "…"`
+ * directives, attempts suffix-based resolution against the repo's own file
+ * list (reusing the same algorithm as the single-repo ingestion pipeline),
+ * and emits unresolved include paths as consumer contracts.
+ *
+ * Matching: a consumer's `include::map/base/dice_map_view.h` in repo A
+ * matches a provider's `include::map/base/dice_map_view.h` in repo B via
+ * exact contract-id equality in `runExactMatch`.
+ */
+
+// ---------- constants ----------
+
+const HEADER_EXTENSIONS = new Set(['.h', '.hpp', '.hxx', '.hh']);
+
+const SOURCE_GLOB = '**/*.{c,cpp,cc,cxx,h,hpp,hxx,hh}';
+
+const STANDARD_IGNORES = [
+  '**/node_modules/**',
+  '**/.git/**',
+  '**/vendor/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.gitnexus/**',
+  '**/third_party/**',
+  '**/3rdparty/**',
+  '**/external/**',
+];
+
+const INCLUDE_QUERY_SRC = '(preproc_include path: (_) @import.source) @import';
+
+/**
+ * Well-known C/C++ standard library headers that can appear in `#include "…"`
+ * form (some projects use quotes for system headers).
+ */
+const SYSTEM_HEADERS = new Set([
+  // C standard
+  'assert.h',
+  'complex.h',
+  'ctype.h',
+  'errno.h',
+  'fenv.h',
+  'float.h',
+  'inttypes.h',
+  'iso646.h',
+  'limits.h',
+  'locale.h',
+  'math.h',
+  'setjmp.h',
+  'signal.h',
+  'stdalign.h',
+  'stdarg.h',
+  'stdatomic.h',
+  'stdbool.h',
+  'stddef.h',
+  'stdint.h',
+  'stdio.h',
+  'stdlib.h',
+  'stdnoreturn.h',
+  'string.h',
+  'tgmath.h',
+  'threads.h',
+  'time.h',
+  'uchar.h',
+  'wchar.h',
+  'wctype.h',
+  // C++ standard (extensionless)
+  'algorithm',
+  'any',
+  'array',
+  'atomic',
+  'barrier',
+  'bit',
+  'bitset',
+  'cassert',
+  'cctype',
+  'cerrno',
+  'cfenv',
+  'cfloat',
+  'charconv',
+  'chrono',
+  'cinttypes',
+  'climits',
+  'clocale',
+  'cmath',
+  'codecvt',
+  'compare',
+  'complex',
+  'concepts',
+  'condition_variable',
+  'coroutine',
+  'csetjmp',
+  'csignal',
+  'cstdarg',
+  'cstddef',
+  'cstdint',
+  'cstdio',
+  'cstdlib',
+  'cstring',
+  'ctime',
+  'cuchar',
+  'cwchar',
+  'cwctype',
+  'deque',
+  'exception',
+  'execution',
+  'expected',
+  'filesystem',
+  'format',
+  'forward_list',
+  'fstream',
+  'functional',
+  'future',
+  'generator',
+  'initializer_list',
+  'iomanip',
+  'ios',
+  'iosfwd',
+  'iostream',
+  'istream',
+  'iterator',
+  'latch',
+  'limits',
+  'list',
+  'locale',
+  'map',
+  'mdspan',
+  'memory',
+  'memory_resource',
+  'mutex',
+  'new',
+  'numbers',
+  'numeric',
+  'optional',
+  'ostream',
+  'print',
+  'queue',
+  'random',
+  'ranges',
+  'ratio',
+  'regex',
+  'scoped_allocator',
+  'semaphore',
+  'set',
+  'shared_mutex',
+  'source_location',
+  'span',
+  'spanstream',
+  'sstream',
+  'stack',
+  'stacktrace',
+  'stdexcept',
+  'stdfloat',
+  'stop_token',
+  'streambuf',
+  'string',
+  'string_view',
+  'strstream',
+  'syncstream',
+  'system_error',
+  'thread',
+  'tuple',
+  'type_traits',
+  'typeindex',
+  'typeinfo',
+  'unordered_map',
+  'unordered_set',
+  'utility',
+  'valarray',
+  'variant',
+  'vector',
+  'version',
+]);
+
+/** Path prefixes that indicate system/kernel headers. */
+const SYSTEM_PATH_PREFIXES = [
+  'sys/',
+  'net/',
+  'netinet/',
+  'arpa/',
+  'linux/',
+  'asm/',
+  'bits/',
+  'gnu/',
+  'mach/',
+  'machine/',
+  'xlocale/',
+];
+
+/** Regex fallback for files that exceed tree-sitter's 32 KB parse limit. */
+const INCLUDE_REGEX = /^[ \t]*#\s*include\s*"([^"]+)"/gm;
+
+// ---------- helpers ----------
+
+/**
+ * Normalize an include path to a canonical lowercase forward-slash form.
+ *
+ * IMPORTANT — case-folding caveat (PR #1156 review finding #3):
+ *   Header paths are lowercased so consumer `#include "Foo/Bar.h"` and
+ *   provider file `Foo/Bar.h` normalize to the same contract-id. This is
+ *   the right trade-off on case-insensitive filesystems (macOS, Windows)
+ *   but on case-sensitive Linux filesystems two distinct headers `Foo.h`
+ *   and `foo.h` in the same repo will collide onto the same provider
+ *   contract-id; only one survives `dedupe()`. The gain (reliable
+ *   cross-platform matching) outweighs the cost (extremely rare header
+ *   casing collisions inside a single repo).
+ */
+function normalizeIncludePath(raw: string): string {
+  return raw.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+/g, '/').toLowerCase();
+}
+
+/**
+ * Strip C/C++ block comments from a source blob. Used only by the
+ * regex-fallback path to avoid emitting consumer contracts for
+ * commented-out #include directives. Line comments (`// …`) cannot hide
+ * #include directives because the regex anchors on start-of-line.
+ * See PR #1156 review finding #5.
+ */
+function stripBlockComments(src: string): string {
+  return src.replace(/\/\*[\s\S]*?\*\//g, '');
+}
+
+function isAngleBracketInclude(rawNodeText: string): boolean {
+  const trimmed = rawNodeText.trim();
+  return trimmed.startsWith('<') && trimmed.endsWith('>');
+}
+
+function isSystemHeader(cleanedPath: string): boolean {
+  // Check well-known standard headers
+  if (SYSTEM_HEADERS.has(cleanedPath)) return true;
+  // Check system path prefixes
+  const lower = cleanedPath.toLowerCase();
+  return SYSTEM_PATH_PREFIXES.some((prefix) => lower.startsWith(prefix));
+}
+
+function isHeaderFile(filePath: string): boolean {
+  return HEADER_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+
+function getLanguageForFile(filePath: string): unknown | null {
+  const ext = path.extname(filePath).toLowerCase();
+  switch (ext) {
+    case '.c':
+    case '.h':
+      return C;
+    case '.cpp':
+    case '.cc':
+    case '.cxx':
+    case '.hpp':
+    case '.hxx':
+    case '.hh':
+      return Cpp;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Check whether an include path resolves to a file inside the local repo.
+ *
+ * Uses *exact full-path* matching on the suffix index — we never accept a
+ * truncated suffix match. For `#include "foo/bar.h"` this checks:
+ *   (a) a file whose path ends with the full `foo/bar.h`
+ *   (b) if the include omitted the extension, a file whose path ends with
+ *       the include + one of the C/C++ header extensions
+ *
+ * Returns `true` when a local file matches — caller should suppress the
+ * cross-repo consumer contract.
+ *
+ * See PR #1156 review finding #4 (suffixResolve ambiguity).
+ */
+function isLocalInclude(cleaned: string, suffixIndex: SuffixIndex): boolean {
+  const candidates = [cleaned];
+  if (!/\.[a-zA-Z0-9]+$/.test(cleaned)) {
+    for (const ext of ['.h', '.hpp', '.hxx', '.hh']) candidates.push(cleaned + ext);
+  }
+  for (const c of candidates) {
+    if (suffixIndex.get(c) || suffixIndex.getInsensitive(c)) return true;
+  }
+  return false;
+}
+
+// ---------- main class ----------
+
+export class IncludeExtractor implements ContractExtractor {
+  type = 'include' as const;
+
+  async canExtract(_repo: RepoHandle): Promise<boolean> {
+    return true;
+  }
+
+  async extract(
+    dbExecutor: CypherExecutor | null,
+    repoPath: string,
+    _repo: RepoHandle,
+  ): Promise<ExtractedContract[]> {
+    // 1. Build the local file list (for suffix resolution)
+    const allFiles = await glob('**/*', {
+      cwd: repoPath,
+      ignore: STANDARD_IGNORES,
+      nodir: true,
+    });
+    const normalizedFiles = allFiles.map((f) => f.replace(/\\/g, '/'));
+    const suffixIndex = buildSuffixIndex(normalizedFiles, allFiles);
+
+    // 2. Provider: register all header files
+    const providers = await this.extractProviders(dbExecutor, repoPath, allFiles);
+
+    // 3. Consumer: find unresolved #include directives
+    const consumers = await this.extractConsumers(repoPath, normalizedFiles, allFiles, suffixIndex);
+
+    return this.dedupe([...providers, ...consumers]);
+  }
+
+  // ---------- provider extraction ----------
+
+  private async extractProviders(
+    dbExecutor: CypherExecutor | null,
+    repoPath: string,
+    allFiles: string[],
+  ): Promise<ExtractedContract[]> {
+    // Strategy A: graph-assisted
+    if (dbExecutor) {
+      const graphProviders = await this.extractProvidersGraph(dbExecutor);
+      if (graphProviders.length > 0) return graphProviders;
+    }
+    // Strategy B: filesystem fallback
+    return this.extractProvidersFallback(repoPath, allFiles);
+  }
+
+  private async extractProvidersGraph(db: CypherExecutor): Promise<ExtractedContract[]> {
+    try {
+      const rows = await db(
+        `MATCH (f:File)
+         WHERE f.filePath =~ '.*\\\\.(h|hpp|hxx|hh)$'
+         RETURN f.filePath AS filePath, f.id AS fileId`,
+      );
+      return rows
+        .filter((r) => typeof r.filePath === 'string' && r.filePath)
+        .map((r) => {
+          const filePath = (r.filePath as string).replace(/\\/g, '/');
+          return {
+            contractId: `include::${normalizeIncludePath(filePath)}`,
+            type: 'include' as const,
+            role: 'provider' as const,
+            symbolUid: String(r.fileId ?? ''),
+            symbolRef: { filePath, name: path.basename(filePath) },
+            symbolName: path.basename(filePath),
+            confidence: 1.0,
+            meta: { source: 'graph' },
+          };
+        });
+    } catch {
+      return [];
+    }
+  }
+
+  private extractProvidersFallback(_repoPath: string, allFiles: string[]): ExtractedContract[] {
+    return allFiles
+      .filter((f) => isHeaderFile(f))
+      .map((f) => {
+        const filePath = f.replace(/\\/g, '/');
+        return {
+          contractId: `include::${normalizeIncludePath(filePath)}`,
+          type: 'include' as const,
+          role: 'provider' as const,
+          symbolUid: `File:${filePath}`,
+          symbolRef: { filePath, name: path.basename(filePath) },
+          symbolName: path.basename(filePath),
+          confidence: 0.95,
+          meta: { source: 'filesystem' },
+        };
+      });
+  }
+
+  // ---------- consumer extraction ----------
+
+  private async extractConsumers(
+    repoPath: string,
+    normalizedFiles: string[],
+    allFiles: string[],
+    suffixIndex: SuffixIndex,
+  ): Promise<ExtractedContract[]> {
+    const sourceFiles = await glob(SOURCE_GLOB, {
+      cwd: repoPath,
+      ignore: STANDARD_IGNORES,
+      nodir: true,
+    });
+
+    const parser = new Parser();
+    const out: ExtractedContract[] = [];
+    // Compile the include query once per grammar to avoid re-compilation per file
+    const queryCache = new Map<unknown, Parser.Query>();
+
+    for (const rel of sourceFiles) {
+      const lang = getLanguageForFile(rel);
+      if (!lang) continue;
+
+      const content = readSafe(repoPath, rel);
+      if (!content) continue;
+
+      let query = queryCache.get(lang);
+      if (!query) {
+        try {
+          query = new Parser.Query(lang, INCLUDE_QUERY_SRC);
+          queryCache.set(lang, query);
+        } catch {
+          continue;
+        }
+      }
+
+      // Collect raw include paths: tree-sitter first, regex fallback for large files.
+      // `extractionSource` is stamped on each emitted consumer contract so
+      // regex-fallback contracts stay auditable post-hoc (PR #1156 review finding #6).
+      let rawIncludes: string[];
+      let extractionSource: 'tree_sitter' | 'regex_fallback';
+      try {
+        parser.setLanguage(lang);
+        const tree = parser.parse(content);
+        let matches: Parser.QueryMatch[];
+        try {
+          matches = query.matches(tree.rootNode);
+        } catch {
+          matches = [];
+        }
+        rawIncludes = [];
+        extractionSource = 'tree_sitter';
+        for (const match of matches) {
+          const sourceNode = match.captures.find((c) => c.name === 'import.source');
+          if (!sourceNode) continue;
+          const rawText = sourceNode.node.text;
+          if (isAngleBracketInclude(rawText)) continue;
+          const cleaned = rawText.replace(/['"<>]/g, '');
+          if (cleaned && cleaned.length <= 2048) rawIncludes.push(cleaned);
+        }
+      } catch {
+        // tree-sitter failed (e.g. file > 32 KB) — fall back to regex.
+        // Strip block comments first so we don't emit a consumer contract
+        // for a commented-out #include (PR #1156 review finding #5).
+        rawIncludes = [];
+        extractionSource = 'regex_fallback';
+        const scanTarget = stripBlockComments(content);
+        INCLUDE_REGEX.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = INCLUDE_REGEX.exec(scanTarget)) !== null) {
+          if (m[1] && m[1].length <= 2048) rawIncludes.push(m[1]);
+        }
+      }
+
+      for (const cleaned of rawIncludes) {
+        // Filter: skip known system headers and system path prefixes
+        if (isSystemHeader(cleaned)) continue;
+
+        // Local resolution (PR #1156 review finding #4): only accept an
+        // exact-suffix match on the *full* include path. The generic
+        // suffixResolve() iterates all truncated suffixes, which would
+        // silently suppress a cross-repo `#include "map/base/view.h"`
+        // when the local repo has any `internal/view.h` — a realistic
+        // false-negative in large C++ codebases. Here we only resolve
+        // locally if a file path ends with the complete include string
+        // (optionally re-appending one of the C/C++ header extensions
+        // when the include already omits it).
+        if (isLocalInclude(cleaned, suffixIndex)) continue;
+
+        // Unresolved: emit as consumer contract
+        const normalizedRel = rel.replace(/\\/g, '/');
+        out.push({
+          contractId: `include::${normalizeIncludePath(cleaned)}`,
+          type: 'include' as const,
+          role: 'consumer' as const,
+          symbolUid: `File:${normalizedRel}`,
+          symbolRef: { filePath: normalizedRel, name: cleaned },
+          symbolName: cleaned,
+          confidence: 0.85,
+          meta: {
+            source: extractionSource,
+            includePath: cleaned,
+          },
+        });
+      }
+    }
+
+    return out;
+  }
+
+  // ---------- deduplication ----------
+
+  private dedupe(items: ExtractedContract[]): ExtractedContract[] {
+    const seen = new Set<string>();
+    const out: ExtractedContract[] = [];
+    for (const c of items) {
+      const k = `${c.contractId}|${c.role}|${c.symbolRef.filePath}`;
+      if (seen.has(k)) continue;
+      seen.add(k);
+      out.push(c);
+    }
+    return out;
+  }
+}
diff --git a/gitnexus/src/core/group/extractors/java-workspace-extractor.ts b/gitnexus/src/core/group/extractors/java-workspace-extractor.ts
index 66ee35ee59..b6beed71c9 100644
--- a/gitnexus/src/core/group/extractors/java-workspace-extractor.ts
+++ b/gitnexus/src/core/group/extractors/java-workspace-extractor.ts
@@ -4,6 +4,7 @@ import type { CypherExecutor } from '../contract-extractor.js';
 import type { GroupManifestLink, ContractRole } from '../types.js';
 import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
 
+import { logger } from '../../logger.js';
 interface JavaProjectMeta {
   groupId: string;
   artifactId: string;
@@ -213,7 +214,7 @@ export async function extractJavaWorkspaceLinks(
     };
     const existing = projectsByKey.get(key);
     if (existing) {
-      console.warn(
+      logger.warn(
         `[java-workspace-extractor] duplicate artifact "${key}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
       );
       continue;
diff --git a/gitnexus/src/core/group/extractors/manifest-extractor.ts b/gitnexus/src/core/group/extractors/manifest-extractor.ts
index 0c3cd20ca0..f4d0f77cff 100644
--- a/gitnexus/src/core/group/extractors/manifest-extractor.ts
+++ b/gitnexus/src/core/group/extractors/manifest-extractor.ts
@@ -1,6 +1,7 @@
 import type { ContractType, CrossLink, GroupManifestLink, StoredContract } from '../types.js';
 import type { CypherExecutor } from '../contract-extractor.js';
 
+import { logger } from '../../logger.js';
 export interface ManifestExtractResult {
   contracts: StoredContract[];
   crossLinks: CrossLink[];
@@ -273,6 +274,14 @@ export class ManifestExtractor {
            LIMIT 1`,
           { contract: link.contract },
         );
+      } else if (link.type === 'include') {
+        rows = await executor(
+          `MATCH (f:File) WHERE f.filePath = $contract
+           RETURN f.id AS uid, f.name AS name, f.filePath AS filePath
+           ORDER BY f.filePath ASC
+           LIMIT 1`,
+          { contract: link.contract },
+        );
       } else if (link.type === 'custom') {
         // Workspace extractors produce qualified contracts like "mathlex::Expression".
         // Graph nodes store the unqualified symbol name ("Expression"), so strip
@@ -303,7 +312,7 @@ export class ManifestExtractor {
       // fail the whole manifest extraction. Unresolved contracts still
       // get a synthetic symbolUid below, so cross-impact can proceed.
       const message = err instanceof Error ? err.message : String(err);
-      console.warn(
+      logger.warn(
         `[manifest-extractor] resolveSymbol failed for ${link.type}:${link.contract} ` +
           `in ${repoPathKey}: ${message}`,
       );
@@ -357,6 +366,8 @@ export class ManifestExtractor {
         return `lib::${contract}`;
       case 'custom':
         return `custom::${contract}`;
+      case 'include':
+        return `include::${contract}`;
       default: {
         const _exhaustive: never = type;
         throw new Error(`Unhandled ContractType: ${String(_exhaustive)}`);
diff --git a/gitnexus/src/core/group/extractors/node-workspace-extractor.ts b/gitnexus/src/core/group/extractors/node-workspace-extractor.ts
index 05a7c95dd5..aa40ac088c 100644
--- a/gitnexus/src/core/group/extractors/node-workspace-extractor.ts
+++ b/gitnexus/src/core/group/extractors/node-workspace-extractor.ts
@@ -4,6 +4,7 @@ import type { CypherExecutor } from '../contract-extractor.js';
 import type { GroupManifestLink, ContractRole } from '../types.js';
 import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
 
+import { logger } from '../../logger.js';
 interface PackageMeta {
   name: string;
   groupPath: string;
@@ -205,7 +206,7 @@ export async function extractNodeWorkspaceLinks(
     };
     const existing = packagesByName.get(manifest.name);
     if (existing) {
-      console.warn(
+      logger.warn(
         `[node-workspace-extractor] duplicate package name "${manifest.name}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
       );
       continue;
diff --git a/gitnexus/src/core/group/extractors/python-workspace-extractor.ts b/gitnexus/src/core/group/extractors/python-workspace-extractor.ts
index 5930808af1..4453852a63 100644
--- a/gitnexus/src/core/group/extractors/python-workspace-extractor.ts
+++ b/gitnexus/src/core/group/extractors/python-workspace-extractor.ts
@@ -4,6 +4,7 @@ import type { CypherExecutor } from '../contract-extractor.js';
 import type { GroupManifestLink, ContractRole } from '../types.js';
 import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
 
+import { logger } from '../../logger.js';
 interface PythonPackageMeta {
   name: string;
   importName: string;
@@ -204,7 +205,7 @@ export async function extractPythonWorkspaceLinks(
     };
     const existing = packagesByImportName.get(manifest.importName);
     if (existing) {
-      console.warn(
+      logger.warn(
         `[python-workspace-extractor] duplicate package "${manifest.name}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
       );
       continue;
diff --git a/gitnexus/src/core/group/extractors/rust-workspace-extractor.ts b/gitnexus/src/core/group/extractors/rust-workspace-extractor.ts
index c19af07caa..d58c3e08f6 100644
--- a/gitnexus/src/core/group/extractors/rust-workspace-extractor.ts
+++ b/gitnexus/src/core/group/extractors/rust-workspace-extractor.ts
@@ -5,6 +5,7 @@ import type { GroupManifestLink, ContractRole } from '../types.js';
 import { shouldIgnorePath } from '../../../config/ignore-service.js';
 import { loadIgnoreRules } from '../../../config/ignore-service.js';
 
+import { logger } from '../../logger.js';
 /**
  * Discover cross-crate contracts in a Rust workspace by reading each
  * member's `Cargo.toml` dependencies and scanning source files for
@@ -30,6 +31,32 @@ interface ImportedSymbol {
   filePath: string;
 }
 
+/**
+ * Linear-time `[package].name = "..."` lookup. The previous regex
+ * `^\[package\]\s*\n(?:[^\[]*?\n)*?name\s*=\s*"([^"]+)"` had a nested
+ * lazy quantifier on `\n` that CodeQL js/redos flagged as exponential
+ * on inputs like `[package]\n` + many bare `\n`. We walk lines
+ * explicitly: scan from the first `[package]` header until we hit the
+ * next `[...]` section header, looking for the `name = "..."` line.
+ * O(n) with the line count.
+ *
+ * Exported so the U8 ReDoS regression test can drive the production
+ * line-walk directly with adversarial fixtures (multi-line strings,
+ * trailing sections, etc.) instead of duplicating it inline.
+ */
+export function parseCargoPackageName(content: string): string | null {
+  const lines = content.split('\n');
+  const packageStart = lines.findIndex((l) => l.trim() === '[package]');
+  if (packageStart < 0) return null;
+  for (let i = packageStart + 1; i < lines.length; i++) {
+    const line = lines[i].trimStart();
+    if (line.startsWith('[')) break; // hit the next section header
+    const m = /^name\s*=\s*"([^"]+)"/.exec(line);
+    if (m) return m[1];
+  }
+  return null;
+}
+
 /**
  * Parse a Cargo.toml to extract the crate name and workspace dependency
  * names. Uses simple line-based parsing — no TOML library needed for
@@ -46,12 +73,9 @@ async function parseCrateManifest(
     return null;
   }
 
-  let name = '';
+  const name = parseCargoPackageName(content) ?? '';
   const workspaceDeps: string[] = [];
 
-  const nameMatch = content.match(/^\[package\]\s*\n(?:[^\[]*?\n)*?name\s*=\s*"([^"]+)"/m);
-  if (nameMatch) name = nameMatch[1];
-
   // Match dependencies that use workspace = true, which indicates they
   // are workspace-internal deps:
   //   dep_name = { workspace = true }
@@ -224,7 +248,7 @@ export async function extractRustWorkspaceLinks(
     };
     const existing = cratesByName.get(manifest.name);
     if (existing) {
-      console.warn(
+      logger.warn(
         `[rust-workspace-extractor] duplicate crate name "${manifest.name}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
       );
       continue;
diff --git a/gitnexus/src/core/group/matching.ts b/gitnexus/src/core/group/matching.ts
index 3431f8ddf8..0b27655c62 100644
--- a/gitnexus/src/core/group/matching.ts
+++ b/gitnexus/src/core/group/matching.ts
@@ -107,6 +107,8 @@ export function normalizeContractId(id: string): string {
       return `topic::${rest.trim().toLowerCase()}`;
     case 'lib':
       return `lib::${rest.toLowerCase()}`;
+    case 'include':
+      return `include::${rest.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+/g, '/').toLowerCase()}`;
     default:
       return id;
   }
diff --git a/gitnexus/src/core/group/service.ts b/gitnexus/src/core/group/service.ts
index a412ceaa82..d0473048fc 100644
--- a/gitnexus/src/core/group/service.ts
+++ b/gitnexus/src/core/group/service.ts
@@ -14,6 +14,7 @@ import {
 } from './group-path-utils.js';
 import { getDefaultGitnexusDir, getGroupDir, listGroups, readContractRegistry } from './storage.js';
 import { syncGroup } from './sync.js';
+import { logger } from '../logger.js';
 import type {
   ContractRegistry,
   CrossLink,
@@ -64,6 +65,15 @@ export interface GroupToolPort {
       relationTypes: string[];
       minConfidence: number;
       includeTests: boolean;
+      // Optional cancellation signal. Callers (notably the cross-impact
+      // Phase-2 fanout) wrap this call in a Promise.race against a
+      // setTimeout-driven AbortController so a single hung neighbor
+      // cannot exceed the request's clamped timeout budget. Implementors
+      // may honor the signal cooperatively or simply let the caller's
+      // race resolve the await — the latter is sufficient for the
+      // resource-exhaustion mitigation. When the signal is absent or
+      // already aborted at call time, behavior is unchanged.
+      signal?: AbortSignal;
     },
   ): Promise<unknown | null>;
   context(
@@ -170,11 +180,11 @@ async function loadContractRegistryResilient(
           contracts.push(row);
         } else {
           skippedCorrupt++;
-          console.warn('[group] skipping corrupt contract row in contracts.json');
+          logger.warn('[group] skipping corrupt contract row in contracts.json');
         }
       } catch {
         skippedCorrupt++;
-        console.warn('[group] skipping corrupt contract row in contracts.json');
+        logger.warn('[group] skipping corrupt contract row in contracts.json');
       }
     }
   }
@@ -187,11 +197,11 @@ async function loadContractRegistryResilient(
           crossLinks.push(row);
         } else {
           skippedCorrupt++;
-          console.warn('[group] skipping corrupt crossLinks row in contracts.json');
+          logger.warn('[group] skipping corrupt crossLinks row in contracts.json');
         }
       } catch {
         skippedCorrupt++;
-        console.warn('[group] skipping corrupt crossLinks row in contracts.json');
+        logger.warn('[group] skipping corrupt crossLinks row in contracts.json');
       }
     }
   }
diff --git a/gitnexus/src/core/group/storage.ts b/gitnexus/src/core/group/storage.ts
index 99bf27fbd9..cc3dbfdc93 100644
--- a/gitnexus/src/core/group/storage.ts
+++ b/gitnexus/src/core/group/storage.ts
@@ -5,6 +5,15 @@ import * as os from 'node:os';
 import { randomBytes } from 'node:crypto';
 import type { ContractRegistry } from './types.js';
 
+/**
+ * Build an unpredictable suffix for atomic-write tmp files. Replaces the
+ * previous `Date.now()` pattern which CodeQL flagged as
+ * js/insecure-temporary-file: a guessable suffix in a writable directory
+ * lets a co-located attacker pre-create or symlink the tmp path before the
+ * write lands.
+ */
+const tmpSuffix = (): string => randomBytes(8).toString('hex');
+
 const CONTRACTS_FILE = 'contracts.json';
 
 export function getDefaultGitnexusDir(): string {
@@ -35,9 +44,21 @@ export async function writeContractRegistry(
   registry: ContractRegistry,
 ): Promise<void> {
   const targetPath = path.join(groupDir, CONTRACTS_FILE);
-  const tmpPath = `${targetPath}.tmp.${randomBytes(8).toString('hex')}`;
-
-  await fsp.writeFile(tmpPath, JSON.stringify(registry, null, 2), 'utf-8');
+  const tmpPath = `${targetPath}.tmp.${tmpSuffix()}`;
+
+  // O_EXCL via `'wx'` flag + explicit `0o600` mode — closes both halves
+  // of the CodeQL js/insecure-temporary-file finding: `'wx'` rejects a
+  // pre-planted symlink at the path, and `0o600` (user-only) prevents
+  // the file from being created group/world readable while it briefly
+  // contains contract data en route to the rename. The query's
+  // `isSecureMode` predicate inspects ONLY the mode argument, not the
+  // flags, so the explicit mode is what credits the fix.
+  const handle = await fsp.open(tmpPath, 'wx', 0o600);
+  try {
+    await handle.writeFile(JSON.stringify(registry, null, 2), 'utf-8');
+  } finally {
+    await handle.close();
+  }
   await fsp.rename(tmpPath, targetPath);
 }
 
@@ -107,6 +128,38 @@ matching:
   # exclude_links_paths: [/ping, /health, /healthcheck]
   # exclude_links_param_only_paths: false
 `;
-  await fsp.writeFile(path.join(groupDir, 'group.yaml'), template, 'utf-8');
+  // Always write group.yaml with O_EXCL via `fsp.open(..., 'wx')` —
+  // refuses to follow a pre-planted symlink at the target path, closing
+  // the TOCTOU window between the existence check (line ~98) and the
+  // write that CodeQL js/insecure-temporary-file flags. Under
+  // `force=true` we unlink the existing file first (best-effort, no-op
+  // when absent) so the subsequent O_EXCL open succeeds AND the same
+  // symlink-rejection guarantee holds — this is strictly safer than
+  // the previous `flag: force ? 'w' : 'wx'` shape, which silently
+  // followed symlinks under force. CodeQL's rule does not recognize
+  // the `writeFile(path, content, { flag: 'wx' })` shape as O_EXCL;
+  // the explicit open() handle below is what credits the mitigation.
+  const yamlPath = path.join(groupDir, 'group.yaml');
+  if (force) {
+    try {
+      await fsp.unlink(yamlPath);
+    } catch (err) {
+      // ENOENT (file absent) is expected on first run; rethrow anything
+      // else so we don't silently mask permission/EBUSY failures.
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    }
+  }
+  // `'wx'` rejects a pre-planted symlink at the path; `0o600` is
+  // user-only (no group/world bits) — gitnexus storage is per-user
+  // (`~/.gitnexus/...`), so any "other user wants to read this" case is
+  // a misconfiguration, not a feature. Keeping the file user-only also
+  // satisfies CodeQL's `isSecureMode` predicate (low 6 bits == 0) and
+  // closes the js/insecure-temporary-file alert at this site.
+  const handle = await fsp.open(yamlPath, 'wx', 0o600);
+  try {
+    await handle.writeFile(template, 'utf-8');
+  } finally {
+    await handle.close();
+  }
   return groupDir;
 }
diff --git a/gitnexus/src/core/group/sync.ts b/gitnexus/src/core/group/sync.ts
index 9a77df22a6..9b18d828fc 100644
--- a/gitnexus/src/core/group/sync.ts
+++ b/gitnexus/src/core/group/sync.ts
@@ -8,14 +8,17 @@ import { HttpRouteExtractor } from './extractors/http-route-extractor.js';
 import { GrpcExtractor } from './extractors/grpc-extractor.js';
 import { ThriftExtractor } from './extractors/thrift-extractor.js';
 import { TopicExtractor } from './extractors/topic-extractor.js';
+import { IncludeExtractor } from './extractors/include-extractor.js';
 import { ManifestExtractor } from './extractors/manifest-extractor.js';
 import { discoverWorkspaceLinks } from './extractors/workspace-extractor.js';
 import { buildProviderIndex, runExactMatch, runWildcardMatch } from './matching.js';
 import { detectServiceBoundaries, assignService } from './service-boundary-detector.js';
 import type { CypherExecutor } from './contract-extractor.js';
 import { writeContractRegistry } from './storage.js';
+import { writeBridge } from './bridge-db.js';
 import type { ContractRegistry } from './types.js';
 
+import { logger } from '../logger.js';
 export interface SyncOptions {
   extractorOverride?:
     | ((repo: RepoHandle) => Promise<StoredContract[]>)
@@ -99,6 +102,7 @@ export async function syncGroup(config: GroupConfig, opts?: SyncOptions): Promis
     const grpcEx = new GrpcExtractor();
     const thriftEx = new ThriftExtractor();
     const topicEx = new TopicExtractor();
+    const includeEx = new IncludeExtractor();
     dbExecutors = new Map<string, CypherExecutor>();
     const openPoolIds: string[] = [];
 
@@ -167,6 +171,17 @@ export async function syncGroup(config: GroupConfig, opts?: SyncOptions): Promis
             }
           }
 
+          if (config.detect.includes) {
+            const extracted = await includeEx.extract(executor, handle.repoPath, handle);
+            for (const c of extracted) {
+              autoContracts.push({
+                ...c,
+                repo: groupPath,
+                service: assignService(c.symbolRef.filePath, boundaries),
+              });
+            }
+          }
+
           const metaPath = path.join(handle.storagePath, 'meta.json');
           try {
             const raw = await fs.readFile(metaPath, 'utf-8');
@@ -211,7 +226,7 @@ export async function syncGroup(config: GroupConfig, opts?: SyncOptions): Promis
       allLinks = [...allLinks, ...wsResult.links];
       if (opts?.verbose) {
         for (const s of wsResult.stats) {
-          console.log(
+          logger.info(
             `  workspace-deps: discovered ${s.linkCount} cross-${s.ecosystem.toLowerCase()} links from ${s.projectCount} ${s.ecosystem} projects`,
           );
         }
@@ -230,7 +245,7 @@ export async function syncGroup(config: GroupConfig, opts?: SyncOptions): Promis
     for (const link of allLinks) {
       const dangling = [link.from, link.to].filter((r) => !knownRepos.has(r));
       if (dangling.length > 0) {
-        console.warn(
+        logger.warn(
           `[group/sync] manifest link ${link.type}:${link.contract} references repos not in config.repos: ${dangling.join(', ')} — cross-links will use synthetic UIDs`,
         );
       }
@@ -241,7 +256,7 @@ export async function syncGroup(config: GroupConfig, opts?: SyncOptions): Promis
     autoContracts.push(...manifestResult.contracts);
     manifestCrossLinks = manifestResult.crossLinks;
     if (opts?.verbose) {
-      console.log(
+      logger.info(
         `  manifest: ${manifestCrossLinks.length} cross-links from ${allLinks.length} links (${config.links.length} declared + ${allLinks.length - config.links.length} discovered)`,
       );
     }
@@ -269,6 +284,12 @@ export async function syncGroup(config: GroupConfig, opts?: SyncOptions): Promis
 
   if (opts?.groupDir && !opts.skipWrite) {
     await writeContractRegistry(opts.groupDir, registry);
+    await writeBridge(opts.groupDir, {
+      contracts: allContracts,
+      crossLinks,
+      repoSnapshots,
+      missingRepos,
+    });
   }
 
   return {
diff --git a/gitnexus/src/core/group/types.ts b/gitnexus/src/core/group/types.ts
index 7d0a142511..8e43ff78f0 100644
--- a/gitnexus/src/core/group/types.ts
+++ b/gitnexus/src/core/group/types.ts
@@ -1,4 +1,4 @@
-export type ContractType = 'http' | 'grpc' | 'thrift' | 'topic' | 'lib' | 'custom';
+export type ContractType = 'http' | 'grpc' | 'thrift' | 'topic' | 'lib' | 'custom' | 'include';
 export type MatchType = 'exact' | 'manifest' | 'wildcard' | 'bm25' | 'embedding';
 export type ContractRole = 'provider' | 'consumer';
 
@@ -28,6 +28,7 @@ export interface DetectConfig {
   topics: boolean;
   shared_libs: boolean;
   embedding_fallback: boolean;
+  includes: boolean;
   workspace_deps: boolean;
 }
 
diff --git a/gitnexus/src/core/ingestion/ast-cache.ts b/gitnexus/src/core/ingestion/ast-cache.ts
index 65da46ab88..454c60df2e 100644
--- a/gitnexus/src/core/ingestion/ast-cache.ts
+++ b/gitnexus/src/core/ingestion/ast-cache.ts
@@ -1,6 +1,7 @@
 import { LRUCache } from 'lru-cache';
 import Parser from 'tree-sitter';
 
+import { logger } from '../logger.js';
 /**
  * Minimal structural shape consumers need when reading Trees back
  * through a phase-dependency boundary. Declared here so phases that
@@ -49,7 +50,7 @@ export const createASTCache = (maxSize: number = 50): ASTCache => {
         // will hand freed memory to scope-resolution.
         (tree as unknown as { delete?: () => void }).delete?.();
       } catch (e) {
-        console.warn('Failed to delete tree from WASM memory', e);
+        logger.warn({ e }, 'Failed to delete tree from WASM memory');
       }
     },
   });
diff --git a/gitnexus/src/core/ingestion/call-processor.ts b/gitnexus/src/core/ingestion/call-processor.ts
index 1871d06057..6c59578b05 100644
--- a/gitnexus/src/core/ingestion/call-processor.ts
+++ b/gitnexus/src/core/ingestion/call-processor.ts
@@ -75,6 +75,7 @@ import { extractReturnTypeName, stripNullable } from './type-extractors/shared.j
 import type { LiteralTypeInferrer } from './type-extractors/types.js';
 import type { SyntaxNode } from './utils/ast-helpers.js';
 
+import { logger } from '../logger.js';
 /** Per-file resolved type bindings for exported symbols.
  *  Populated during call processing, consumed by Phase 14 re-resolution pass. */
 export type ExportedTypeMap = Map<string, Map<string, string>>;
@@ -784,7 +785,7 @@ export const processCalls = async (
       const query = new Parser.Query(lang, queryStr);
       matches = query.matches(tree.rootNode);
     } catch (queryError) {
-      console.warn(`Query error for ${file.path}:`, queryError);
+      logger.warn({ queryError }, `Query error for ${file.path}:`);
       continue;
     }
 
@@ -1391,7 +1392,7 @@ export const processCalls = async (
 
   if (skippedByLang && skippedByLang.size > 0) {
     for (const [lang, count] of skippedByLang.entries()) {
-      console.warn(
+      logger.warn(
         `[ingestion] Skipped ${count} ${lang} file(s) in call processing — ${lang} parser not available.`,
       );
     }
diff --git a/gitnexus/src/core/ingestion/cluster-enricher.ts b/gitnexus/src/core/ingestion/cluster-enricher.ts
index b20ed2bad9..06cd4d0cd0 100644
--- a/gitnexus/src/core/ingestion/cluster-enricher.ts
+++ b/gitnexus/src/core/ingestion/cluster-enricher.ts
@@ -7,6 +7,7 @@
 
 import { CommunityNode } from './community-processor.js';
 
+import { logger } from '../logger.js';
 // ============================================================================
 // TYPES
 // ============================================================================
@@ -128,7 +129,7 @@ export const enrichClusters = async (
       enrichments.set(community.id, enrichment);
     } catch (error) {
       // On error, fallback to heuristic
-      console.warn(`Failed to enrich cluster ${community.id}:`, error);
+      logger.warn({ error }, `Failed to enrich cluster ${community.id}:`);
       enrichments.set(community.id, {
         name: community.heuristicLabel,
         keywords: [],
@@ -210,7 +211,7 @@ Output JSON array:
         }
       }
     } catch (error) {
-      console.warn('Batch enrichment failed, falling back to heuristics:', error);
+      logger.warn({ error }, 'Batch enrichment failed, falling back to heuristics:');
       // Fallback for this batch
       for (const community of batch) {
         enrichments.set(community.id, {
diff --git a/gitnexus/src/core/ingestion/cobol/cobol-copy-expander.ts b/gitnexus/src/core/ingestion/cobol/cobol-copy-expander.ts
index 46a33001df..dda135b127 100644
--- a/gitnexus/src/core/ingestion/cobol/cobol-copy-expander.ts
+++ b/gitnexus/src/core/ingestion/cobol/cobol-copy-expander.ts
@@ -1,3 +1,4 @@
+import { logger } from '../../logger.js';
 /**
  * COBOL COPY statement expansion engine.
  *
@@ -454,7 +455,7 @@ export function expandCopies(
       if (visited.has(resolvedPath)) {
         if (!warnedCircular.has(resolvedPath)) {
           warnedCircular.add(resolvedPath);
-          console.warn(
+          logger.warn(
             `[cobol-copy-expander] Circular COPY detected: ${cs.target} (${resolvedPath}) ` +
               `includes itself. Skipping expansion.`,
           );
@@ -464,7 +465,7 @@ export function expandCopies(
 
       // Max depth exceeded — keep unexpanded
       if (depth >= maxDepth) {
-        console.warn(
+        logger.warn(
           `[cobol-copy-expander] Max expansion depth (${maxDepth}) reached for ` +
             `COPY ${cs.target} in ${srcPath}. Skipping expansion.`,
         );
@@ -475,7 +476,7 @@ export function expandCopies(
       if (++totalExpansions > MAX_TOTAL_EXPANSIONS) {
         if (!warnedCircular.has('__max_total__')) {
           warnedCircular.add('__max_total__');
-          console.warn(
+          logger.warn(
             `[cobol-copy-expander] Max total expansions (${MAX_TOTAL_EXPANSIONS}) reached ` +
               `in ${srcPath}. Skipping further expansions.`,
           );
diff --git a/gitnexus/src/core/ingestion/cobol/cobol-preprocessor.ts b/gitnexus/src/core/ingestion/cobol/cobol-preprocessor.ts
index 23cedb99b4..34be6bc032 100644
--- a/gitnexus/src/core/ingestion/cobol/cobol-preprocessor.ts
+++ b/gitnexus/src/core/ingestion/cobol/cobol-preprocessor.ts
@@ -369,9 +369,20 @@ const RE_USE_AFTER =
   /\bUSE\s+(?:AFTER\s+)?(?:STANDARD\s+)?(?:EXCEPTION|ERROR)\s+ON\s+([A-Z][A-Z0-9-]+|INPUT|OUTPUT|I-O|EXTEND)\b/i;
 
 // SET statement (condition, index)
-const RE_SET_TO_TRUE = /\bSET\s+((?:[A-Z][A-Z0-9-]+(?:\s+OF\s+[A-Z][A-Z0-9-]+)?\s+)+)TO\s+TRUE\b/i;
-const RE_SET_INDEX =
-  /\bSET\s+((?:[A-Z][A-Z0-9-]+\s+)+)(TO|UP\s+BY|DOWN\s+BY)\s+(\d+|[A-Z][A-Z0-9-]+)/i;
+//
+// Catastrophic-backtracking note (CodeQL js/redos): the previous shape
+// `((?:[A-Z][A-Z0-9-]+(?:\s+OF\s+[A-Z][A-Z0-9-]+)?\s+)+)TO\s+TRUE`
+// nested `\s+` quantifiers across alternations and was exponential on
+// inputs like "SET a OF a OF a ... TO TRUE". Replaced with a lazy
+// dot-match bounded by the explicit `\s+TO\s+TRUE` suffix — `.+?` is
+// O(n) with the trailing anchor, and the captured group is parsed
+// downstream the same way as before.
+// Exported so the U8 ReDoS regression test can pin the exact production
+// pattern. Direct import is the only way to ensure the test's
+// pathological-input timing assertion exercises the production regex
+// instead of an inline copy that drifts.
+export const RE_SET_TO_TRUE = /\bSET\s+(.+?)\s+TO\s+TRUE\b/i;
+export const RE_SET_INDEX = /\bSET\s+(.+?)\s+(TO|UP\s+BY|DOWN\s+BY)\s+(\d+|[A-Z][A-Z0-9-]+)/i;
 
 // INITIALIZE statement — data reset (captures targets before REPLACING/WITH clause)
 const RE_INITIALIZE = /\bINITIALIZE\s+([\s\S]*?)(?=\bREPLACING\b|\bWITH\b|\.\s*$|$)/i;
diff --git a/gitnexus/src/core/ingestion/filesystem-walker.ts b/gitnexus/src/core/ingestion/filesystem-walker.ts
index 71a4046f2b..4d6725e246 100644
--- a/gitnexus/src/core/ingestion/filesystem-walker.ts
+++ b/gitnexus/src/core/ingestion/filesystem-walker.ts
@@ -5,6 +5,7 @@ import path from 'path';
 import { glob } from 'glob';
 import { createIgnoreFilter } from '../../config/ignore-service.js';
 
+import { logger } from '../logger.js';
 export interface FileEntry {
   path: string;
   content: string;
@@ -74,10 +75,10 @@ export const walkRepositoryPaths = async (
   if (skippedLarge > 0) {
     const isDefault = maxFileSizeBytes === DEFAULT_MAX_FILE_SIZE_BYTES;
     const suffix = isDefault ? ', likely generated/vendored' : '';
-    console.warn(`  Skipped ${skippedLarge} large files (>${maxFileSizeBytes / 1024}KB${suffix})`);
+    logger.warn(`  Skipped ${skippedLarge} large files (>${maxFileSizeBytes / 1024}KB${suffix})`);
     if (isVerboseIngestionEnabled()) {
       for (const p of skippedLargePaths) {
-        console.warn(`  - ${p}`);
+        logger.warn(`  - ${p}`);
       }
     }
   }
diff --git a/gitnexus/src/core/ingestion/heritage-processor.ts b/gitnexus/src/core/ingestion/heritage-processor.ts
index 12e59a19ac..2c973ad8ec 100644
--- a/gitnexus/src/core/ingestion/heritage-processor.ts
+++ b/gitnexus/src/core/ingestion/heritage-processor.ts
@@ -34,6 +34,7 @@ import type { ResolutionContext } from './model/resolution-context.js';
 import { TIER_CONFIDENCE } from './model/resolution-context.js';
 import type { HeritageInfo } from './heritage-types.js';
 
+import { logger } from '../logger.js';
 /**
  * Derive the heritage-resolution strategy for a language from its
  * `LanguageProvider`. This is the production wiring that `buildHeritageMap`
@@ -237,7 +238,7 @@ export const processHeritage = async (
       query = new Parser.Query(treeSitterLang, queryStr);
       matches = query.matches(tree.rootNode);
     } catch (queryError) {
-      console.warn(`Heritage query error for ${file.path}:`, queryError);
+      logger.warn({ queryError }, `Heritage query error for ${file.path}:`);
       continue;
     }
 
@@ -267,7 +268,7 @@ export const processHeritage = async (
 
   if (skippedByLang && skippedByLang.size > 0) {
     for (const [lang, count] of skippedByLang.entries()) {
-      console.warn(
+      logger.warn(
         `[ingestion] Skipped ${count} ${lang} file(s) in heritage processing — ${lang} parser not available.`,
       );
     }
diff --git a/gitnexus/src/core/ingestion/import-processor.ts b/gitnexus/src/core/ingestion/import-processor.ts
index b669d27445..03cbed5b79 100644
--- a/gitnexus/src/core/ingestion/import-processor.ts
+++ b/gitnexus/src/core/ingestion/import-processor.ts
@@ -27,6 +27,7 @@ import type { SyntaxNode } from './utils/ast-helpers.js';
 import { isDev } from './utils/env.js';
 import { isRegistryPrimary } from './registry-primary-flag.js';
 
+import { logger } from '../logger.js';
 // Type: Map<FilePath, Set<ResolvedFilePath>>
 // Stores all files that a given file imports from
 export type ImportMap = Map<string, Set<string>>;
@@ -324,14 +325,18 @@ export const processImports = async (
       matches = query.matches(tree.rootNode);
     } catch (queryError: any) {
       if (isDev) {
-        console.group(`🔴 Query Error: ${file.path}`);
-        console.log('Language:', language);
-        console.log('Query (first 200 chars):', queryStr.substring(0, 200) + '...');
-        console.log('Error:', queryError?.message || queryError);
-        console.log('File content (first 300 chars):', file.content.substring(0, 300));
-        console.log('AST root type:', tree.rootNode?.type);
-        console.log('AST has errors:', tree.rootNode?.hasError);
-        console.groupEnd();
+        logger.error(
+          {
+            file: file.path,
+            language,
+            err: queryError?.message || queryError,
+            queryPreview: queryStr.substring(0, 200) + '...',
+            contentPreview: file.content.substring(0, 300),
+            astRootType: tree.rootNode?.type,
+            astHasError: tree.rootNode?.hasError,
+          },
+          'tree-sitter query error',
+        );
       }
 
       if (wasReparsed) (tree as unknown as { delete?: () => void }).delete?.();
@@ -346,7 +351,7 @@ export const processImports = async (
         const sourceNode = captureMap['import.source'];
         if (!sourceNode) {
           if (isDev) {
-            console.log(`⚠️ Import captured but no source node in ${file.path}`);
+            logger.info(`⚠️ Import captured but no source node in ${file.path}`);
           }
           return;
         }
@@ -399,14 +404,14 @@ export const processImports = async (
 
   if (skippedByLang && skippedByLang.size > 0) {
     for (const [lang, count] of skippedByLang.entries()) {
-      console.warn(
+      logger.warn(
         `[ingestion] Skipped ${count} ${lang} file(s) in import processing — ${lang} parser not available.`,
       );
     }
   }
 
   if (isDev) {
-    console.log(
+    logger.info(
       `📊 Import processing complete: ${getResolvedCount()}/${totalImportsFound} imports resolved to graph edges`,
     );
   }
@@ -498,7 +503,7 @@ export const processImportsFromExtracted = async (
   );
 
   if (isDev) {
-    console.log(
+    logger.info(
       `📊 Import processing (fast path): ${getResolvedCount()}/${totalImportsFound} imports resolved to graph edges`,
     );
   }
diff --git a/gitnexus/src/core/ingestion/language-config.ts b/gitnexus/src/core/ingestion/language-config.ts
index 682d7b190d..f51ef57c67 100644
--- a/gitnexus/src/core/ingestion/language-config.ts
+++ b/gitnexus/src/core/ingestion/language-config.ts
@@ -4,6 +4,7 @@ import type { ImportConfigs } from './import-resolvers/types.js';
 
 import { isDev } from './utils/env.js';
 
+import { logger } from '../logger.js';
 // ============================================================================
 // LANGUAGE-SPECIFIC CONFIG TYPES
 // ============================================================================
@@ -82,7 +83,7 @@ export async function loadTsconfigPaths(repoRoot: string): Promise<TsconfigPaths
 
       if (aliases.size > 0) {
         if (isDev) {
-          console.log(`📦 Loaded ${aliases.size} path aliases from ${filename}`);
+          logger.info(`📦 Loaded ${aliases.size} path aliases from ${filename}`);
         }
         return { aliases, baseUrl };
       }
@@ -104,7 +105,7 @@ export async function loadGoModulePath(repoRoot: string): Promise<GoModuleConfig
     const match = content.match(/^module\s+(\S+)/m);
     if (match) {
       if (isDev) {
-        console.log(`📦 Loaded Go module path: ${match[1]}`);
+        logger.info(`📦 Loaded Go module path: ${match[1]}`);
       }
       return { modulePath: match[1] };
     }
@@ -132,7 +133,7 @@ export async function loadComposerConfig(repoRoot: string): Promise<ComposerConf
     }
 
     if (isDev) {
-      console.log(`📦 Loaded ${psr4.size} PSR-4 mappings from composer.json`);
+      logger.info(`📦 Loaded ${psr4.size} PSR-4 mappings from composer.json`);
     }
     return { psr4 };
   } catch {
@@ -178,7 +179,7 @@ export async function loadCSharpProjectConfig(repoRoot: string): Promise<CSharpP
             const projectDir = path.relative(repoRoot, dir).replace(/\\/g, '/');
             configs.push({ rootNamespace, projectDir });
             if (isDev) {
-              console.log(
+              logger.info(
                 `📦 Loaded C# project: ${entry.name} (namespace: ${rootNamespace}, dir: ${projectDir})`,
               );
             }
@@ -217,7 +218,7 @@ export async function loadSwiftPackageConfig(repoRoot: string): Promise<SwiftPac
 
   if (targets.size > 0) {
     if (isDev) {
-      console.log(`📦 Loaded ${targets.size} Swift package targets`);
+      logger.info(`📦 Loaded ${targets.size} Swift package targets`);
     }
     return { targets };
   }
diff --git a/gitnexus/src/core/ingestion/method-extractors/generic.ts b/gitnexus/src/core/ingestion/method-extractors/generic.ts
index 7e15f24587..f02faef359 100644
--- a/gitnexus/src/core/ingestion/method-extractors/generic.ts
+++ b/gitnexus/src/core/ingestion/method-extractors/generic.ts
@@ -8,6 +8,7 @@
  */
 
 import type { SyntaxNode } from '../utils/ast-helpers.js';
+import { logger } from '../../logger.js';
 import type {
   MethodExtractor,
   MethodExtractorContext,
@@ -158,7 +159,7 @@ function findBodies(node: SyntaxNode, bodyNodeSet: Set<string>): SyntaxNode[] {
     // Fallback: body field exists but its type is not in bodyNodeTypes.
     // This may indicate a config typo — log for debugging if NODE_ENV is development.
     if (process.env.NODE_ENV === 'development') {
-      console.warn(
+      logger.warn(
         `[MethodExtractor] body field type '${bodyField.type}' not in bodyNodeTypes for node '${node.type}'`,
       );
     }
diff --git a/gitnexus/src/core/ingestion/parsing-processor.ts b/gitnexus/src/core/ingestion/parsing-processor.ts
index 86b4199904..8803ec023a 100644
--- a/gitnexus/src/core/ingestion/parsing-processor.ts
+++ b/gitnexus/src/core/ingestion/parsing-processor.ts
@@ -34,6 +34,7 @@ import {
 import type { LanguageProvider } from './language-provider.js';
 import type { ParsedFile } from 'gitnexus-shared';
 import { WorkerPool } from './workers/worker-pool.js';
+import { logger } from '../logger.js';
 import type {
   ParseWorkerResult,
   ParseWorkerInput,
@@ -191,7 +192,7 @@ const processParsingWithWorkers = async (
     const summary = Array.from(skippedLanguages.entries())
       .map(([lang, count]) => `${lang}: ${count}`)
       .join(', ');
-    console.warn(`  Skipped unsupported languages: ${summary}`);
+    logger.warn(`  Skipped unsupported languages: ${summary}`);
   }
 
   // Final progress
@@ -382,7 +383,7 @@ const processParsingSequential = async (
         bufferSize: getTreeSitterBufferSize(parseContent),
       });
     } catch (parseError) {
-      console.warn(`Skipping unparseable file: ${file.path}`);
+      logger.warn(`Skipping unparseable file: ${file.path}`);
       continue;
     }
 
@@ -408,7 +409,7 @@ const processParsingSequential = async (
       query = new Parser.Query(language, queryString);
       matches = query.matches(tree.rootNode);
     } catch (queryError) {
-      console.warn(`Query error for ${file.path}:`, queryError);
+      logger.warn({ queryError }, `Query error for ${file.path}:`);
       continue;
     }
 
@@ -701,7 +702,7 @@ const processParsingSequential = async (
 
   if (skippedByLang && skippedByLang.size > 0) {
     for (const [lang, count] of skippedByLang.entries()) {
-      console.warn(
+      logger.warn(
         `[ingestion] Skipped ${count} ${lang} file(s) in parsing processing — ${lang} parser not available.`,
       );
     }
@@ -742,7 +743,7 @@ export const processParsing = async (
       // in scope-resolution with an empty cache and get re-parsed.
       // Surfacing this in PROF mode prevents silent perf cliffs when
       // a repo crosses the worker-pool threshold.
-      console.warn(
+      logger.warn(
         `[scope-resolution prof] worker pool engaged for ${files.length} files — cross-phase tree cache will be empty; scope-resolution re-parses.`,
       );
     }
@@ -757,7 +758,7 @@ export const processParsing = async (
       );
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      console.warn('Worker pool parsing stopped; continuing with sequential parser:', message);
+      logger.warn({ message }, 'Worker pool parsing stopped; continuing with sequential parser:');
       reportProgress?.(
         lastProgress,
         files.length,
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/cobol.ts b/gitnexus/src/core/ingestion/pipeline-phases/cobol.ts
index cfe6b6ce29..c9332aabce 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/cobol.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/cobol.ts
@@ -15,6 +15,7 @@ import { readFileContents } from '../filesystem-walker.js';
 import type { StructureOutput } from './structure.js';
 import { isDev } from '../utils/env.js';
 
+import { logger } from '../../logger.js';
 export interface CobolOutput {
   programs: number;
   paragraphs: number;
@@ -47,7 +48,7 @@ export const cobolPhase: PipelinePhase<CobolOutput> = {
     const cobolResult = processCobol(ctx.graph, cobolFiles, allPathSet);
 
     if (isDev) {
-      console.log(
+      logger.info(
         `  COBOL: ${cobolResult.programs} programs, ${cobolResult.paragraphs} paragraphs, ${cobolResult.sections} sections from ${cobolFiles.length} files`,
       );
       if (
@@ -55,12 +56,12 @@ export const cobolPhase: PipelinePhase<CobolOutput> = {
         cobolResult.execCicsBlocks > 0 ||
         cobolResult.entryPoints > 0
       ) {
-        console.log(
+        logger.info(
           `  COBOL enriched: ${cobolResult.execSqlBlocks} SQL blocks, ${cobolResult.execCicsBlocks} CICS blocks, ${cobolResult.entryPoints} entry points, ${cobolResult.moves} moves, ${cobolResult.fileDeclarations} file declarations`,
         );
       }
       if (cobolResult.jclJobs > 0) {
-        console.log(`  JCL: ${cobolResult.jclJobs} jobs, ${cobolResult.jclSteps} steps`);
+        logger.info(`  JCL: ${cobolResult.jclJobs} jobs, ${cobolResult.jclSteps} steps`);
       }
     }
 
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/communities.ts b/gitnexus/src/core/ingestion/pipeline-phases/communities.ts
index 6a302b8b9f..0e29b6cc27 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/communities.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/communities.ts
@@ -15,6 +15,7 @@ import type { StructureOutput } from './structure.js';
 import { processCommunities, type CommunityDetectionResult } from '../community-processor.js';
 import { isDev } from '../utils/env.js';
 
+import { logger } from '../../logger.js';
 export interface CommunitiesOutput {
   communityResult: CommunityDetectionResult;
 }
@@ -47,7 +48,7 @@ export const communitiesPhase: PipelinePhase<CommunitiesOutput> = {
     });
 
     if (isDev) {
-      console.log(
+      logger.info(
         `🏘️ Community detection: ${communityResult.stats.totalCommunities} communities found (modularity: ${communityResult.stats.modularity.toFixed(3)})`,
       );
     }
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/cross-file-impl.ts b/gitnexus/src/core/ingestion/pipeline-phases/cross-file-impl.ts
index 334ff57df6..5c014ed736 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/cross-file-impl.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/cross-file-impl.ts
@@ -23,6 +23,7 @@ import { topologicalLevelSort } from '../utils/graph-sort.js';
 import type { KnowledgeGraph } from '../../graph/types.js';
 import { isDev } from '../utils/env.js';
 
+import { logger } from '../../logger.js';
 /** Max AST trees to keep in LRU cache for cross-file binding propagation. */
 const AST_CACHE_CAP = 50;
 
@@ -60,7 +61,7 @@ export async function runCrossFileBindingPropagation(
   const { levels, cycleCount } = topologicalLevelSort(ctx.importMap);
 
   if (isDev && cycleCount > 0) {
-    console.log(`🔄 ${cycleCount} files in import cycles (processed last in undefined order)`);
+    logger.info(`🔄 ${cycleCount} files in import cycles (processed last in undefined order)`);
   }
 
   let filesWithGaps = 0;
@@ -88,7 +89,7 @@ export async function runCrossFileBindingPropagation(
   const gapRatio = totalFiles > 0 ? filesWithGaps / totalFiles : 0;
   if (gapRatio < CROSS_FILE_SKIP_THRESHOLD && filesWithGaps < gapThreshold) {
     if (isDev) {
-      console.log(
+      logger.info(
         `⏭️ Cross-file re-resolution skipped (${filesWithGaps}/${totalFiles} files, ${(gapRatio * 100).toFixed(1)}% < ${CROSS_FILE_SKIP_THRESHOLD * 100}% threshold)`,
       );
     }
@@ -193,7 +194,7 @@ export async function runCrossFileBindingPropagation(
 
     if (crossFileResolved >= MAX_CROSS_FILE_REPROCESS) {
       if (isDev)
-        console.log(`⚠️ Cross-file re-resolution capped at ${MAX_CROSS_FILE_REPROCESS} files`);
+        logger.info(`⚠️ Cross-file re-resolution capped at ${MAX_CROSS_FILE_REPROCESS} files`);
       break;
     }
   }
@@ -204,7 +205,7 @@ export async function runCrossFileBindingPropagation(
     const elapsed = Date.now() - crossFileStart;
     const totalElapsed = Date.now() - pipelineStart;
     const reResolutionPct = totalElapsed > 0 ? ((elapsed / totalElapsed) * 100).toFixed(1) : '0';
-    console.log(
+    logger.info(
       `🔗 Cross-file re-resolution: ${crossFileResolved} candidates re-processed` +
         ` in ${elapsed}ms (${reResolutionPct}% of total ingestion time so far)`,
     );
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/cross-file.ts b/gitnexus/src/core/ingestion/pipeline-phases/cross-file.ts
index e1e907a0bb..3ea604b4dc 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/cross-file.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/cross-file.ts
@@ -36,6 +36,7 @@ import type { ParseOutput } from './parse.js';
 import { runCrossFileBindingPropagation } from './cross-file-impl.js';
 import { isDev } from '../utils/env.js';
 
+import { logger } from '../../logger.js';
 export interface CrossFileOutput {
   /** Number of files re-processed during cross-file propagation. */
   filesReprocessed: number;
@@ -59,11 +60,11 @@ export const crossFilePhase: PipelinePhase<CrossFileOutput> = {
       if (isDev) {
         if (bindingAccumulator.totalBindings > 0) {
           const memKB = Math.round(bindingAccumulator.estimateMemoryBytes() / 1024);
-          console.log(
+          logger.info(
             `📦 BindingAccumulator: ${bindingAccumulator.totalBindings} bindings across ${bindingAccumulator.fileCount} files (~${memKB} KB)`,
           );
         } else if (totalFiles > 0) {
-          console.log(
+          logger.info(
             `📦 BindingAccumulator: EMPTY — 0 bindings across 0 files despite ${totalFiles} parsed files. If the codebase has typed bindings, this indicates an upstream regression.`,
           );
         }
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/markdown.ts b/gitnexus/src/core/ingestion/pipeline-phases/markdown.ts
index 6b3853b9dc..dd57518c15 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/markdown.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/markdown.ts
@@ -15,6 +15,7 @@ import { readFileContents } from '../filesystem-walker.js';
 import type { StructureOutput } from './structure.js';
 import { isDev } from '../utils/env.js';
 
+import { logger } from '../../logger.js';
 export interface MarkdownOutput {
   /** Number of markdown sections extracted. */
   sections: number;
@@ -48,7 +49,7 @@ export const markdownPhase: PipelinePhase<MarkdownOutput> = {
     const mdResult = processMarkdown(ctx.graph, mdFiles, allPathSet);
 
     if (isDev) {
-      console.log(
+      logger.info(
         `  Markdown: ${mdResult.sections} sections, ${mdResult.links} cross-links from ${mdFiles.length} files`,
       );
     }
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/mro.ts b/gitnexus/src/core/ingestion/pipeline-phases/mro.ts
index 372ae32b09..c098f2b7bf 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/mro.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/mro.ts
@@ -15,6 +15,7 @@ import type { StructureOutput } from './structure.js';
 import { computeMRO } from '../mro-processor.js';
 import { isDev } from '../utils/env.js';
 
+import { logger } from '../../logger.js';
 export interface MROOutput {
   entries: number;
   ambiguityCount: number;
@@ -42,7 +43,7 @@ export const mroPhase: PipelinePhase<MROOutput> = {
     const mroResult = computeMRO(ctx.graph);
 
     if (isDev && mroResult.entries.length > 0) {
-      console.log(
+      logger.info(
         `🔀 MRO: ${mroResult.entries.length} classes analyzed, ${mroResult.ambiguityCount} ambiguities, ${mroResult.overrideEdges} METHOD_OVERRIDES, ${mroResult.methodImplementsEdges} METHOD_IMPLEMENTS`,
       );
     }
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/orm.ts b/gitnexus/src/core/ingestion/pipeline-phases/orm.ts
index ebdac018ac..4e6021efa7 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/orm.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/orm.ts
@@ -16,6 +16,7 @@ import type { ExtractedORMQuery } from '../workers/parse-worker.js';
 import type { KnowledgeGraph } from '../../graph/types.js';
 import { isDev } from '../utils/env.js';
 
+import { logger } from '../../logger.js';
 export interface ORMOutput {
   edgesCreated: number;
   modelCount: number;
@@ -91,7 +92,7 @@ function processORMQueries(
   }
 
   if (isDev) {
-    console.log(
+    logger.info(
       `ORM dataflow: ${edgesCreated} QUERIES edges, ${modelNodes.size} models (${queries.length} total calls)`,
     );
   }
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts b/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts
index 025bdbeb7c..bd39a43301 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts
@@ -69,6 +69,7 @@ import { isDev } from '../utils/env.js';
 import { synthesizeWildcardImportBindings, needsSynthesis } from './wildcard-synthesis.js';
 import { extractORMQueriesInline } from './orm-extraction.js';
 
+import { logger } from '../../logger.js';
 // ── Constants ──────────────────────────────────────────────────────────────
 
 /** Max bytes of source content to load per parse chunk. */
@@ -136,7 +137,7 @@ export async function runChunkedParseAndResolve(
     }
   }
   for (const [lang, count] of skippedByLang) {
-    console.warn(
+    logger.warn(
       `Skipping ${count} ${lang} file(s) — ${lang} parser not available (native binding may not have built). Try: npm rebuild tree-sitter-${lang}`,
     );
   }
@@ -171,7 +172,7 @@ export async function runChunkedParseAndResolve(
 
   if (isDev) {
     const totalMB = parseableScanned.reduce((s, f) => s + f.size, 0) / (1024 * 1024);
-    console.log(
+    logger.info(
       `📂 Scan: ${totalFiles} paths, ${totalParseable} parseable (${totalMB.toFixed(0)}MB), ${numChunks} chunks @ ${CHUNK_BYTE_BUDGET / (1024 * 1024)}MB budget`,
     );
   }
@@ -220,9 +221,9 @@ export async function runChunkedParseAndResolve(
       }
       workerPool = createWorkerPool(workerUrl);
     } catch (err) {
-      console.warn(
+      logger.warn(
+        { err: (err as Error).message },
         'Worker pool creation failed, using sequential fallback:',
-        (err as Error).message,
       );
     }
   }
@@ -339,7 +340,7 @@ export async function runChunkedParseAndResolve(
             exportedTypeMap,
           );
           if (isDev && enrichedCount > 0) {
-            console.log(
+            logger.info(
               `🔗 E1: Seeded ${enrichedCount} cross-file receiver types (chunk ${chunkIdx + 1})`,
             );
           }
@@ -538,7 +539,7 @@ export async function runChunkedParseAndResolve(
       const rcStats = ctx.getStats();
       const total = rcStats.cacheHits + rcStats.cacheMisses;
       const hitRate = total > 0 ? ((rcStats.cacheHits / total) * 100).toFixed(1) : '0';
-      console.log(
+      logger.info(
         `🔍 Resolution cache: ${rcStats.cacheHits} hits, ${rcStats.cacheMisses} misses (${hitRate}% hit rate)`,
       );
     }
@@ -554,15 +555,15 @@ export async function runChunkedParseAndResolve(
       bindingAccumulator.finalize();
       const enriched = enrichExportedTypeMap(bindingAccumulator, graph, exportedTypeMap);
       if (isDev && enriched > 0) {
-        console.log(
+        logger.info(
           `🔗 Worker TypeEnv enrichment: ${enriched} fixpoint-inferred exports added to ExportedTypeMap`,
         );
       }
     } catch (enrichErr) {
       if (isDev) {
-        console.warn(
+        logger.warn(
+          { err: (enrichErr as Error).message },
           'Post-fallback finalize/enrich failed during cleanup:',
-          (enrichErr as Error).message,
         );
       }
     }
@@ -571,7 +572,7 @@ export async function runChunkedParseAndResolve(
   if (!hasSynthesized) {
     const synthesized = synthesizeWildcardImportBindings(graph, ctx);
     if (isDev && synthesized > 0) {
-      console.log(
+      logger.info(
         `🔗 Synthesized ${synthesized} additional wildcard import bindings (Go/Ruby/C++/Swift/Python)`,
       );
     }
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/processes.ts b/gitnexus/src/core/ingestion/pipeline-phases/processes.ts
index 209906cfba..166faea200 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/processes.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/processes.ts
@@ -19,6 +19,7 @@ import { processProcesses, type ProcessDetectionResult } from '../process-proces
 import { generateId } from '../../../lib/utils.js';
 import { isDev } from '../utils/env.js';
 
+import { logger } from '../../logger.js';
 export interface ProcessesOutput {
   processResult: ProcessDetectionResult;
 }
@@ -67,7 +68,7 @@ export const processesPhase: PipelinePhase<ProcessesOutput> = {
     );
 
     if (isDev) {
-      console.log(
+      logger.info(
         `🔄 Process detection: ${processResult.stats.totalProcesses} processes found (${processResult.stats.crossCommunityCount} cross-community)`,
       );
     }
@@ -167,7 +168,7 @@ export const processesPhase: PipelinePhase<ProcessesOutput> = {
         }
       }
       if (isDev && linked > 0) {
-        console.log(`🔗 Linked ${linked} Route/Tool nodes to execution flows`);
+        logger.info(`🔗 Linked ${linked} Route/Tool nodes to execution flows`);
       }
     }
 
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/routes.ts b/gitnexus/src/core/ingestion/pipeline-phases/routes.ts
index cd0a65f9d3..de3a8ddb88 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/routes.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/routes.ts
@@ -32,6 +32,7 @@ import { generateId } from '../../../lib/utils.js';
 import { readFileContents } from '../filesystem-walker.js';
 import { isDev } from '../utils/env.js';
 
+import { logger } from '../../logger.js';
 const EXPO_NAV_PATTERNS = [
   /router\.(push|replace|navigate)\(\s*['"`]([^'"`]+)['"`]/g,
   /<Link\s+[^>]*href=\s*['"`]([^'"`]+)['"`]/g,
@@ -174,7 +175,7 @@ export const routesPhase: PipelinePhase<RoutesOutput> = {
       }
 
       if (isDev) {
-        console.log(
+        logger.info(
           `🗺️ Route registry: ${routeRegistry.size} routes${duplicateRoutes > 0 ? ` (${duplicateRoutes} duplicate URLs skipped)` : ''}`,
         );
       }
@@ -224,7 +225,7 @@ export const routesPhase: PipelinePhase<RoutesOutput> = {
             linkedCount++;
           }
           if (isDev && linkedCount > 0) {
-            console.log(
+            logger.info(
               `🛡️ Linked ${mwPath} middleware [${mwLabel.join(', ')}] to ${linkedCount} routes`,
             );
           }
@@ -290,7 +291,7 @@ export const routesPhase: PipelinePhase<RoutesOutput> = {
 
       processNextjsFetchRoutes(ctx.graph, allFetchCalls, routeURLToFile, consumerContents);
       if (isDev) {
-        console.log(
+        logger.info(
           `🔗 Processed ${allFetchCalls.length} fetch() calls against ${routeRegistry.size} routes`,
         );
       }
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/runner.ts b/gitnexus/src/core/ingestion/pipeline-phases/runner.ts
index 89543e049d..0bfc45bd4d 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/runner.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/runner.ts
@@ -15,6 +15,7 @@
 import type { PipelinePhase, PipelineContext, PhaseResult } from './types.js';
 import { isDev } from '../utils/env.js';
 
+import { logger } from '../../logger.js';
 /**
  * Validate that the phases form a valid dependency graph (no cycles, all deps present).
  * Returns phases in topological execution order.
@@ -176,7 +177,7 @@ export async function runPipeline(
     const start = Date.now();
 
     if (isDev) {
-      console.log(`▶ Phase: ${phase.name}`);
+      logger.info(`▶ Phase: ${phase.name}`);
     }
 
     // Only expose declared dependencies — prevents hidden coupling to undeclared phases.
@@ -220,7 +221,7 @@ export async function runPipeline(
     });
 
     if (isDev) {
-      console.log(`✓ Phase: ${phase.name} (${durationMs}ms)`);
+      logger.info(`✓ Phase: ${phase.name} (${durationMs}ms)`);
     }
   }
 
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/tools.ts b/gitnexus/src/core/ingestion/pipeline-phases/tools.ts
index 023c8a1aff..32a0ae71fb 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/tools.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/tools.ts
@@ -16,6 +16,7 @@ import { generateId } from '../../../lib/utils.js';
 import { readFileContents } from '../filesystem-walker.js';
 import { isDev } from '../utils/env.js';
 
+import { logger } from '../../logger.js';
 export interface ToolDef {
   name: string;
   filePath: string;
@@ -104,7 +105,7 @@ export const toolsPhase: PipelinePhase<ToolsOutput> = {
       }
 
       if (isDev) {
-        console.log(`🔧 Tool registry: ${toolDefs.length} tools detected`);
+        logger.info(`🔧 Tool registry: ${toolDefs.length} tools detected`);
       }
     }
 
diff --git a/gitnexus/src/core/ingestion/process-processor.ts b/gitnexus/src/core/ingestion/process-processor.ts
index a12378c981..aa744e54da 100644
--- a/gitnexus/src/core/ingestion/process-processor.ts
+++ b/gitnexus/src/core/ingestion/process-processor.ts
@@ -17,6 +17,7 @@ import { calculateEntryPointScore, isTestFile } from './entry-point-scoring.js';
 import { SupportedLanguages } from 'gitnexus-shared';
 import { isDev } from './utils/env.js';
 
+import { logger } from '../logger.js';
 // ============================================================================
 // CONFIGURATION
 // ============================================================================
@@ -319,13 +320,13 @@ const findEntryPoints = (
 
   // DEBUG: Log top candidates with new scoring details
   if (sorted.length > 0 && isDev) {
-    console.log(`[Process] Top 10 entry point candidates (new scoring):`);
+    logger.info(`[Process] Top 10 entry point candidates (new scoring):`);
     sorted.slice(0, 10).forEach((c, i) => {
       const node = graph.getNode(c.id);
       const exported = node?.properties.isExported ? '✓' : '✗';
       const shortPath = node?.properties.filePath?.split('/').slice(-2).join('/') || '';
-      console.log(`  ${i + 1}. ${node?.properties.name} [exported:${exported}] (${shortPath})`);
-      console.log(`     score: ${c.score.toFixed(2)} = [${c.reasons.join(' × ')}]`);
+      logger.info(`  ${i + 1}. ${node?.properties.name} [exported:${exported}] (${shortPath})`);
+      logger.info(`     score: ${c.score.toFixed(2)} = [${c.reasons.join(' × ')}]`);
     });
   }
 
diff --git a/gitnexus/src/core/ingestion/scope-extractor-bridge.ts b/gitnexus/src/core/ingestion/scope-extractor-bridge.ts
index 1774cefcac..41a50193de 100644
--- a/gitnexus/src/core/ingestion/scope-extractor-bridge.ts
+++ b/gitnexus/src/core/ingestion/scope-extractor-bridge.ts
@@ -28,6 +28,7 @@ import type { ParsedFile } from 'gitnexus-shared';
 import { extract as extractScope } from './scope-extractor.js';
 import type { LanguageProvider } from './language-provider.js';
 
+import { logger } from '../logger.js';
 /** Callback used to report scope-extraction warnings to the host (worker or direct). */
 export type ScopeBridgeWarn = (message: string) => void;
 
@@ -53,7 +54,7 @@ export function extractParsedFile(
       err instanceof Error ? err.message : String(err)
     }`;
     if (onWarn !== undefined) onWarn(message);
-    else console.warn(message);
+    logger.warn(message);
     return undefined;
   }
 }
diff --git a/gitnexus/src/core/ingestion/scope-resolution/pipeline/phase.ts b/gitnexus/src/core/ingestion/scope-resolution/pipeline/phase.ts
index 5dbb3715fb..c2fda97776 100644
--- a/gitnexus/src/core/ingestion/scope-resolution/pipeline/phase.ts
+++ b/gitnexus/src/core/ingestion/scope-resolution/pipeline/phase.ts
@@ -38,6 +38,7 @@ import { runScopeResolution } from './run.js';
 import { SCOPE_RESOLVERS } from './registry.js';
 import { isDev, isSemanticModelValidatorEnabled } from '../../utils/env.js';
 
+import { logger } from '../../../logger.js';
 export interface ScopeResolutionOutput {
   /** True when at least one language ran. */
   readonly ran: boolean;
@@ -144,7 +145,7 @@ export const scopeResolutionPhase: PipelinePhase<ScopeResolutionOutput> = {
           resolutionConfig,
           onWarn: (msg) => {
             if (isSemanticModelValidatorEnabled()) {
-              console.warn(`[scope-resolution:${lang}] ${msg}`);
+              logger.warn(`[scope-resolution:${lang}] ${msg}`);
             }
           },
         },
@@ -162,7 +163,7 @@ export const scopeResolutionPhase: PipelinePhase<ScopeResolutionOutput> = {
       });
 
       if (isDev) {
-        console.log(
+        logger.info(
           `[scope-resolution:${lang}] ${stats.filesProcessed} files → ${stats.importsEmitted} IMPORTS + ${stats.referenceEdgesEmitted} reference edges (${stats.resolve.unresolved} unresolved sites, ${stats.referenceSkipped} skipped)`,
         );
       }
diff --git a/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts b/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts
index b069f0dd17..558c9ef303 100644
--- a/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts
+++ b/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts
@@ -41,6 +41,7 @@ import { emitImportEdges } from '../graph-bridge/imports-to-edges.js';
 import type { ScopeResolver } from '../contract/scope-resolver.js';
 import { buildWorkspaceResolutionIndex } from '../workspace-index.js';
 
+import { logger } from '../../../logger.js';
 interface RunScopeResolutionInput {
   readonly graph: KnowledgeGraph;
   /**
@@ -279,7 +280,7 @@ export function runScopeResolution(
   if (PROF) {
     const tEnd = process.hrtime.bigint();
     const ns = (a: bigint, b: bigint): number => Number(b - a) / 1_000_000;
-    console.warn(
+    logger.warn(
       `[scope-resolution prof] extract=${ns(tStart, tExtract).toFixed(0)}ms` +
         ` finalize=${ns(tExtract, tFinalize).toFixed(0)}ms` +
         ` propagate=${ns(tFinalize, tPropagate).toFixed(0)}ms` +
diff --git a/gitnexus/src/core/ingestion/type-env.ts b/gitnexus/src/core/ingestion/type-env.ts
index 998e7a59ea..a38df617b3 100644
--- a/gitnexus/src/core/ingestion/type-env.ts
+++ b/gitnexus/src/core/ingestion/type-env.ts
@@ -24,6 +24,7 @@ import {
 import type { SemanticModel } from './model/index.js';
 import type { NodeLabel } from 'gitnexus-shared';
 
+import { logger } from '../logger.js';
 /**
  * Per-file scoped type environment: maps (scope, variableName) → typeName.
  * Scope-aware: variables inside functions are keyed by function name,
@@ -769,7 +770,7 @@ const resolveFixpointBindings = (
     if (iter === MAX_FIXPOINT_ITERATIONS - 1 && process.env.GITNEXUS_DEBUG) {
       const unresolved = pendingItems.length - resolved.size;
       if (unresolved > 0) {
-        console.warn(
+        logger.warn(
           `[type-env] fixpoint hit iteration cap (${MAX_FIXPOINT_ITERATIONS}), ${unresolved} items unresolved`,
         );
       }
diff --git a/gitnexus/src/core/ingestion/utils/max-file-size.ts b/gitnexus/src/core/ingestion/utils/max-file-size.ts
index 0c418bfd47..82013783ac 100644
--- a/gitnexus/src/core/ingestion/utils/max-file-size.ts
+++ b/gitnexus/src/core/ingestion/utils/max-file-size.ts
@@ -1,5 +1,6 @@
 import { TREE_SITTER_MAX_BUFFER } from '../constants.js';
 
+import { logger } from '../../logger.js';
 /** Default threshold (512 KB). Files larger than this are skipped by the walker. */
 export const DEFAULT_MAX_FILE_SIZE_BYTES = 512 * 1024;
 
@@ -11,7 +12,7 @@ const warned = new Set<string>();
 const warnOnce = (key: string, message: string): void => {
   if (warned.has(key)) return;
   warned.add(key);
-  console.warn(message);
+  logger.warn(message);
 };
 
 /**
diff --git a/gitnexus/src/core/ingestion/vue-sfc-extractor.ts b/gitnexus/src/core/ingestion/vue-sfc-extractor.ts
index 382417c566..f36a85ab41 100644
--- a/gitnexus/src/core/ingestion/vue-sfc-extractor.ts
+++ b/gitnexus/src/core/ingestion/vue-sfc-extractor.ts
@@ -23,7 +23,24 @@ interface ScriptBlock {
   lang: string;
 }
 
-const SCRIPT_RE = /<script(\s[^>]*)?>([^]*?)<\/script>/g;
+// Closing-tag pattern accepts:
+//   - whitespace before `>`            — `</script >`, `</script\t\n>`
+//   - attribute-like junk after `script` — `</script foo="bar">`,
+//                                          `</script\t\n bar>`
+//   - any case                          — `</SCRIPT>`, `</Script>`
+//
+// HTML5 parses `</script foo>` as a valid close tag (attributes on
+// close tags are ignored by the parser but still terminate the script
+// block). A strict `<\/script\s*>` would miss those forms and let a
+// crafted Vue file hide content from this extractor — exactly the
+// CodeQL `js/bad-tag-filter` failure mode (the published test cases
+// it checks include `</script foo="bar">` and `</script\t\n bar>`).
+//
+// `[^>]*` after `</script` accepts everything up to the next `>`,
+// matching the HTML parser's actual close-tag behaviour. The `i` flag
+// covers the case axis. PR #1330 CI surfaced both the case and
+// attribute axes; this expression closes both at once.
+const SCRIPT_RE = /<script(\s[^>]*)?>([^]*?)<\/script[^>]*>/gi;
 const TEMPLATE_COMPONENT_RE = /<([A-Z][A-Za-z0-9]+)/g;
 // Greedy: matches from the first <template> to the *last* </template>.
 // This is intentional — nested <template v-slot:...> tags are valid Vue
diff --git a/gitnexus/src/core/ingestion/workers/parse-worker.ts b/gitnexus/src/core/ingestion/workers/parse-worker.ts
index 669465fe27..5c67125622 100644
--- a/gitnexus/src/core/ingestion/workers/parse-worker.ts
+++ b/gitnexus/src/core/ingestion/workers/parse-worker.ts
@@ -85,6 +85,7 @@ import type { LanguageProvider } from '../language-provider.js';
 import type { ParsedFile } from 'gitnexus-shared';
 import { extractParsedFile } from '../scope-extractor-bridge.js';
 
+import { logger } from '../../logger.js';
 // ============================================================================
 // Types for serializable results
 // ============================================================================
@@ -1385,7 +1386,7 @@ const processFileGroup = (
     if (parentPort) {
       parentPort.postMessage({ type: 'warning', message });
     } else {
-      console.warn(message);
+      logger.warn(message);
     }
     return;
   }
@@ -1414,7 +1415,7 @@ const processFileGroup = (
         bufferSize: getTreeSitterBufferSize(parseContent),
       });
     } catch (err) {
-      console.warn(
+      logger.warn(
         `Failed to parse file ${file.path}: ${err instanceof Error ? err.message : String(err)}`,
       );
       continue;
@@ -1427,7 +1428,7 @@ const processFileGroup = (
     try {
       matches = query.matches(tree.rootNode);
     } catch (err) {
-      console.warn(
+      logger.warn(
         `Query execution failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`,
       );
       continue;
@@ -1447,7 +1448,7 @@ const processFileGroup = (
       file.path,
       (message) => {
         if (parentPort) parentPort.postMessage({ type: 'warning', message });
-        else console.warn(message);
+        else logger.warn(message);
       },
       tree,
     );
diff --git a/gitnexus/src/core/ingestion/workers/worker-pool.ts b/gitnexus/src/core/ingestion/workers/worker-pool.ts
index d06b2b38cd..2113685676 100644
--- a/gitnexus/src/core/ingestion/workers/worker-pool.ts
+++ b/gitnexus/src/core/ingestion/workers/worker-pool.ts
@@ -3,6 +3,7 @@ import os from 'node:os';
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
+import { logger } from '../../logger.js';
 export interface WorkerPool {
   /**
    * Dispatch items across workers. Items are split into bounded jobs, each job
@@ -297,11 +298,18 @@ export const createWorkerPool = (
             splitDepth: job.splitDepth + 1,
             timeoutMs: nextTimeout,
           };
-          console.warn(
-            `Worker ${workerIndex} parse job idle timeout after ${job.timeoutMs / 1000}s ` +
-              `(${job.items.length} items, ${job.estimatedBytes} bytes, last progress: ${lastProgress}). ` +
-              `Splitting into ${first.items.length}/${second.items.length} item jobs with ` +
-              `${nextTimeout / 1000}s timeout.`,
+          logger.warn(
+            {
+              workerIndex,
+              timeoutSec: job.timeoutMs / 1000,
+              items: job.items.length,
+              estimatedBytes: job.estimatedBytes,
+              lastProgress,
+              firstSplitItems: first.items.length,
+              secondSplitItems: second.items.length,
+              nextTimeoutSec: nextTimeout / 1000,
+            },
+            `Worker ${workerIndex} parse job idle timeout. Splitting into ${first.items.length}/${second.items.length} item jobs.`,
           );
           // Preserve intuitive retry order; final result order is still enforced by startIndex sort.
           jobs.unshift(first, second);
@@ -310,10 +318,15 @@ export const createWorkerPool = (
 
         const nextAttempt = job.attempt + 1;
         if (nextAttempt <= poolOptions.maxTimeoutRetries) {
-          console.warn(
-            `Worker ${workerIndex} parse job idle timeout after ${job.timeoutMs / 1000}s ` +
-              `(single item, attempt ${nextAttempt}/${poolOptions.maxTimeoutRetries + 1}). ` +
-              `Retrying with ${nextTimeout / 1000}s timeout.`,
+          logger.warn(
+            {
+              workerIndex,
+              timeoutSec: job.timeoutMs / 1000,
+              attempt: nextAttempt,
+              maxAttempts: poolOptions.maxTimeoutRetries + 1,
+              nextTimeoutSec: nextTimeout / 1000,
+            },
+            `Worker ${workerIndex} parse job idle timeout (single item). Retrying with ${nextTimeout / 1000}s timeout.`,
           );
           jobs.unshift({
             ...job,
@@ -402,7 +415,7 @@ export const createWorkerPool = (
             reportProgress();
           } else if (msg.type === 'warning') {
             resetIdleTimer();
-            console.warn(msg.message);
+            logger.warn(msg.message);
           } else if (msg.type === 'sub-batch-done') {
             waitingForFlush = true;
             resetIdleTimer();
diff --git a/gitnexus/src/core/lbug/extension-loader.ts b/gitnexus/src/core/lbug/extension-loader.ts
index b925c5f881..582541942c 100644
--- a/gitnexus/src/core/lbug/extension-loader.ts
+++ b/gitnexus/src/core/lbug/extension-loader.ts
@@ -1,6 +1,7 @@
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'node:url';
 import { LBUG_MAX_DB_SIZE } from './lbug-config.js';
+import { logger } from '../logger.js';
 
 const DEFAULT_EXTENSION_INSTALL_TIMEOUT_MS = 15_000;
 const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
@@ -188,7 +189,7 @@ export class ExtensionManager {
     const policy = opts.policy ?? this.options.policy ?? resolvePolicyFromEnv();
     const timeoutMs =
       opts.installTimeoutMs ?? this.options.installTimeoutMs ?? getExtensionInstallTimeoutMs();
-    const warn = this.options.warn ?? console.error;
+    const warn = this.options.warn ?? ((msg: string) => logger.warn(msg));
 
     if (policy === 'never') {
       this.markUnavailable(name, label, 'extension install policy is "never"', warn);
diff --git a/gitnexus/src/core/lbug/lbug-adapter.ts b/gitnexus/src/core/lbug/lbug-adapter.ts
index a4559436a1..fb4cf76de1 100644
--- a/gitnexus/src/core/lbug/lbug-adapter.ts
+++ b/gitnexus/src/core/lbug/lbug-adapter.ts
@@ -19,11 +19,15 @@ import type { CachedEmbedding } from '../embeddings/types.js';
 import { extensionManager, type ExtensionEnsureOptions } from './extension-loader.js';
 import {
   closeLbugConnection,
+  isDbBusyError,
+  isOpenRetryExhausted,
   openLbugConnection,
+  waitForWindowsHandleRelease,
   type LbugConnectionHandle,
 } from './lbug-config.js';
 import { isVectorExtensionSupportedByPlatform } from '../platform/capabilities.js';
 
+import { logger } from '../logger.js';
 // ---------------------------------------------------------------------------
 // Relationship CSV splitting — extracted for testability (PR #818)
 // ---------------------------------------------------------------------------
@@ -184,21 +188,6 @@ const DB_LOCK_RETRY_ATTEMPTS = 3;
 /** Base back-off in ms between BUSY retries (multiplied by attempt number). */
 const DB_LOCK_RETRY_DELAY_MS = 500;
 
-/**
- * Return true when the error message indicates that another process holds
- * an exclusive lock on the LadybugDB file (e.g. `gitnexus analyze` or
- * `gitnexus serve` running at the same time).
- */
-export const isDbBusyError = (err: unknown): boolean => {
-  const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
-  return (
-    msg.includes('busy') ||
-    msg.includes('lock') ||
-    msg.includes('already in use') ||
-    msg.includes('could not set lock')
-  );
-};
-
 /**
  * Return true when the error message indicates a write was attempted against
  * a read-only LadybugDB connection. The MCP query pool opens DBs read-only,
@@ -251,7 +240,11 @@ export const withLbugDb = async <T>(dbPath: string, operation: () => Promise<T>)
       });
     } catch (err) {
       lastError = err;
-      if (!isDbBusyError(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
+      // Skip outer retry when the inner open-retry already exhausted: the
+      // ~1.5s open-time budget was just spent, repeating the full reset+
+      // reopen cycle would only add 4-5s of tail latency without changing
+      // the outcome (both layers consult the same isDbBusyError matcher).
+      if (!isDbBusyError(err) || isOpenRetryExhausted(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
         throw err;
       }
       // Close stale connection inside the session lock to prevent race conditions
@@ -329,8 +322,17 @@ const doInitLbug = async (dbPath: string) => {
       await conn.query(schemaQuery);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      if (!msg.includes('already exists')) {
-        console.error(`[gitnexus:lbug] schema creation warning: ${msg.slice(0, 120)}`);
+      // Suppression list:
+      //   - "already exists": expected idempotent re-create on existing DBs
+      //   - "could not set lock on file": LadybugDB v0.16.1 emits this on
+      //     Windows when CREATE NODE TABLE runs against a path that was
+      //     just opened (the WAL handle from a fresh Database briefly
+      //     contests the table's first-write lock). The table is created
+      //     anyway and any genuine cross-process lock contention surfaces
+      //     on the next operation via withLbugDb's retry. Logging it here
+      //     would just be noise in CI.
+      if (!msg.includes('already exists') && !isDbBusyError(err)) {
+        logger.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
       }
     }
   }
@@ -683,7 +685,7 @@ export const insertNodeToLbug = async (
     return false;
   } catch (e: any) {
     // Node may already exist or other error
-    console.error(`Failed to insert ${label} node:`, e.message);
+    logger.error({ err: e.message }, `Failed to insert ${label} node:`);
     return false;
   }
 };
@@ -1010,15 +1012,15 @@ export const fetchExistingEmbeddingHashes = async (
           const nodeId = r.nodeId ?? r[0];
           if (nodeId) map.set(nodeId, STALE_HASH_SENTINEL);
         }
-        console.error(
-          `[gitnexus:embed] ${map.size} nodes in legacy DB (missing chunk-aware columns) — all treated as stale`,
+        logger.info(
+          `[embed] ${map.size} nodes in legacy DB (missing chunk-aware columns) — all treated as stale`,
         );
         return map;
       } catch (fallbackErr: any) {
         const fallbackMsg = fallbackErr?.message ?? '';
         if (isMissingColumnOrTableError(fallbackMsg)) {
-          console.error(
-            `[gitnexus:embed] CodeEmbedding table not yet present — full embedding run (${fallbackMsg})`,
+          logger.info(
+            `[embed] CodeEmbedding table not yet present — full embedding run (${fallbackMsg})`,
           );
           return undefined;
         }
@@ -1063,6 +1065,9 @@ export const flushWAL = async (): Promise<void> => {
  */
 export const safeClose = async (): Promise<void> => {
   await flushWAL();
+  // Capture before close — currentDbPath stays set so the Windows post-close
+  // probe below knows which file to wait on.
+  const closingDbPath = currentDbPath;
   if (conn) {
     try {
       // eslint-disable-next-line no-restricted-syntax -- sole authorised close site
@@ -1081,6 +1086,24 @@ export const safeClose = async (): Promise<void> => {
     }
     db = null;
   }
+  // Windows: libuv reports `db.close()` resolved before the kernel has
+  // released the file handle. A subsequent `new Database(samePath)` in
+  // the same process can race the release. The probe (lbug-config.ts)
+  // forces any residual lock to surface as EBUSY/EPERM/EACCES so the
+  // open-time retry absorbs the lag.
+  if (process.platform === 'win32' && closingDbPath) {
+    const released = await waitForWindowsHandleRelease(closingDbPath);
+    if (!released) {
+      // Probe exhausted with a lock code still in flight. The next
+      // openLbugConnection will absorb whatever residual lag remains, but
+      // a chronic warning helps operators spot AV interference (Windows
+      // Defender holding the file far past the 250ms budget).
+      logger.warn(
+        { dbPath: closingDbPath },
+        '⚠️ LadybugDB file handle still locked after close (Windows). If this repeats, check antivirus/Defender exclusions for the GitNexus storage directory.',
+      );
+    }
+  }
 };
 
 export const closeLbug = async (): Promise<void> => {
diff --git a/gitnexus/src/core/lbug/lbug-config.ts b/gitnexus/src/core/lbug/lbug-config.ts
index 5534f7d8b7..ceb4456932 100644
--- a/gitnexus/src/core/lbug/lbug-config.ts
+++ b/gitnexus/src/core/lbug/lbug-config.ts
@@ -1,3 +1,6 @@
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
 import type lbug from '@ladybugdb/core';
 
 /**
@@ -42,10 +45,23 @@ export const LBUG_MAX_DB_SIZE: number = (() => {
   return 16 * 1024 * 1024 * 1024;
 })();
 
+/** Matches WAL corruption errors from the LadybugDB engine. */
+const WAL_CORRUPTION_RE = /corrupt(ed)?\s+wal|invalid\s+wal\s+record|wal.*corrupt|checksum.*wal/i;
+
+export const WAL_RECOVERY_SUGGESTION =
+  'WAL corruption detected. Run `gitnexus analyze` to rebuild the index.';
+
+export function isWalCorruptionError(err: unknown): boolean {
+  if (!err) return false;
+  const msg = err instanceof Error ? err.message : String(err);
+  return WAL_CORRUPTION_RE.test(msg);
+}
+
 type LbugModule = typeof lbug;
 
 export interface LbugDatabaseOptions {
   readOnly?: boolean;
+  throwOnWalReplayFailure?: boolean;
 }
 
 export interface LbugConnectionHandle {
@@ -53,20 +69,200 @@ export interface LbugConnectionHandle {
   conn: lbug.Connection;
 }
 
+/**
+ * Return true when the error message indicates that a LadybugDB file lock
+ * could not be acquired — either at construction time
+ * (`new lbug.Database(...)` raises from `local_file_system.cpp`) or during
+ * a query (another writer holds the exclusive lock).
+ *
+ * Lives here (not in `lbug-adapter.ts`) so both the construction-time
+ * retry (`openWithLockRetry` in this file) and the query-time retry
+ * (`withLbugDb` in `lbug-adapter.ts`) consult the same matcher. Callers
+ * import directly from this module — no re-export to keep in sync.
+ */
+export const isDbBusyError = (err: unknown): boolean => {
+  const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+  // `lock` already subsumes `could not set lock`; the broader term is kept
+  // because graph-DB transient errors include "deadlock", "lock contention",
+  // and the LadybugDB native module's "could not set lock on file" — all of
+  // which deserve a retry. If a non-transient lock-shaped error ever
+  // surfaces (e.g., "lock file missing" during recovery), tighten this
+  // matcher rather than raising the retry budget.
+  return msg.includes('busy') || msg.includes('lock') || msg.includes('already in use');
+};
+
 export function createLbugDatabase(
   lbugModule: LbugModule,
   databasePath: string,
   options: LbugDatabaseOptions = {},
 ): lbug.Database {
-  return new lbugModule.Database(
+  // .d.ts declares fewer args than the native constructor accepts.
+  return new (lbugModule.Database as any)(
     databasePath,
-    0,
-    false,
+    0, // bufferManagerSize
+    false, // enableCompression (pinned for v0.16.0)
     options.readOnly ?? false,
     LBUG_MAX_DB_SIZE,
-  );
+    true, // autoCheckpoint
+    -1, // checkpointThreshold
+    options.throwOnWalReplayFailure ?? true,
+    true, // enableChecksums
+  ) as lbug.Database;
 }
 
+// ─── Lock-busy retry tuning knobs ───────────────────────────────────────────
+//
+// All four GitNexus retry pairs that touch native LadybugDB locks live with
+// a comment cross-reference here so an SRE tuning Windows flakes finds them
+// in one grep:
+//
+//   1. OPEN_LOCK_RETRY_ATTEMPTS / OPEN_LOCK_RETRY_DELAY_MS  (this file)
+//      → `new lbug.Database()` constructor lock failures
+//   2. HANDLE_RELEASE_PROBE_ATTEMPTS / HANDLE_RELEASE_PROBE_DELAY_MS  (this file)
+//      → post-close fs.open probe to absorb Windows handle-release lag
+//   3. DB_LOCK_RETRY_ATTEMPTS / DB_LOCK_RETRY_DELAY_MS  (lbug-adapter.ts withLbugDb)
+//      → query-time busy/lock retry around already-open connections
+//
+// `new lbug.Database()` calls into the native module which performs an
+// OS-level exclusive lock on `<dbPath>`. On Windows that lock can fail
+// for reasons specific to the OS (Defender briefly opens new files,
+// libuv handle release lags the JS-side close). 5 attempts × 100ms
+// linear back-off (max sleep 100+200+300+400 = 1s, plus 5 ctor RTTs
+// of 10–50ms each = ~1.0–1.2s worst case) clears the typical
+// AV-scanner hold without masking real cross-process conflicts.
+//
+// Source: https://github.com/LadybugDB/ladybug/blob/v0.16.1/src/common/file_system/local_file_system.cpp#L126
+const OPEN_LOCK_RETRY_ATTEMPTS = 5;
+const OPEN_LOCK_RETRY_DELAY_MS = 100;
+
+const HANDLE_RELEASE_PROBE_ATTEMPTS = 5;
+const HANDLE_RELEASE_PROBE_DELAY_MS = 50;
+const HANDLE_RELEASE_LOCK_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
+
+/**
+ * Test-fixture directory prefixes recognized by `isTestFixturePath`.
+ *
+ * IMPORTANT: this list must stay in sync with the prefixes passed to
+ * `createTempDir` in `gitnexus/test/helpers/test-db.ts` and the prefixes
+ * used by `withTestLbugDB` (`gitnexus/test/helpers/test-indexed-db.ts`).
+ * If you add a new test that passes a custom prefix to `createTempDir`,
+ * add it here too — otherwise the stale-sidecar sweep silently won't
+ * fire for that fixture and CI flakes return.
+ *
+ * The default `createTempDir('gitnexus-test-')` and the lbug variant
+ * `'gitnexus-lbug-'` cover today's call sites.
+ */
+const TEST_FIXTURE_PREFIXES = ['gitnexus-lbug-', 'gitnexus-test-'];
+
+/**
+ * Marker symbol attached to lock errors after `openWithLockRetry` exhausts
+ * its budget. `withLbugDb`'s outer query-time retry consults this so it
+ * does not re-retry a path that just spent up to ~1.5s in the open-time
+ * loop — preventing 6s tail latencies (3× outer × 5× inner attempts).
+ *
+ * The symbol is internal to GitNexus; consumers should treat the underlying
+ * error message as the user-visible signal.
+ */
+export const LBUG_OPEN_RETRY_EXHAUSTED = Symbol.for('gitnexus.lbug.openRetryExhausted');
+
+export const isOpenRetryExhausted = (err: unknown): boolean => {
+  if (err === null || err === undefined || typeof err !== 'object') return false;
+  return (err as { [LBUG_OPEN_RETRY_EXHAUSTED]?: boolean })[LBUG_OPEN_RETRY_EXHAUSTED] === true;
+};
+
+const tagOpenRetryExhausted = (err: unknown): unknown => {
+  if (err && typeof err === 'object') {
+    (err as { [LBUG_OPEN_RETRY_EXHAUSTED]?: boolean })[LBUG_OPEN_RETRY_EXHAUSTED] = true;
+  }
+  return err;
+};
+
+/**
+ * True when `dbPath` resolves to a recognized test fixture under the OS
+ * temp directory. Used to gate the stale-sidecar sweep so production
+ * paths never have their `.wal` / `.lock` files deleted.
+ *
+ * Defensive shape:
+ *   - `path.resolve` normalizes `..` segments before the prefix check, so
+ *     `<tmp>/gitnexus-lbug-x/../../etc/passwd` is rejected.
+ *   - The tmpRoot check trims any trailing separator returned by some
+ *     Windows TMP configurations (`C:\Users\X\Temp\`) so the startsWith
+ *     comparison stays correct.
+ *   - Only the IMMEDIATE parent directory is matched against the prefix
+ *     list. An ancestor walk would let a tmpdir whose own basename starts
+ *     with `gitnexus-lbug-` accept arbitrary nested paths under it.
+ */
+const isTestFixturePath = (dbPath: string): boolean => {
+  const tmpRoot = os.tmpdir().replace(new RegExp(`${path.sep === '\\' ? '\\\\' : path.sep}+$`), '');
+  const resolved = path.resolve(dbPath);
+  if (!resolved.startsWith(tmpRoot + path.sep) && resolved !== tmpRoot) return false;
+  const parentBase = path.basename(path.dirname(resolved));
+  return TEST_FIXTURE_PREFIXES.some((p) => parentBase.startsWith(p));
+};
+
+/** Exported only for direct unit testing — production callers use `openWithLockRetry`. */
+export const _isTestFixturePathForTest = isTestFixturePath;
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Attempt to remove stale `.wal` / `.lock` sidecars that a previous aborted
+ * test run may have left behind. Best-effort: ENOENT is normal, anything
+ * else is swallowed so the caller's retry can surface the original error.
+ */
+const sweepStaleSidecars = async (dbPath: string): Promise<void> => {
+  for (const suffix of ['.wal', '.lock']) {
+    try {
+      await fs.unlink(dbPath + suffix);
+    } catch {
+      /* missing sidecar or permission error — let the open retry surface it */
+    }
+  }
+};
+
+/**
+ * Run `construct` with bounded retries when `new lbug.Database(...)` throws
+ * a busy/lock error. The original (loop-captured) error is preferred over
+ * any post-sweep error so triage sees the real LadybugDB lock message.
+ * On exhaustion the rethrown error is tagged via
+ * `LBUG_OPEN_RETRY_EXHAUSTED` so the outer query-time retry in
+ * `withLbugDb` skips re-retrying a freshly-exhausted path.
+ */
+const openWithLockRetry = async (
+  construct: () => lbug.Database,
+  dbPath: string,
+): Promise<lbug.Database> => {
+  let originalLockError: unknown;
+  for (let attempt = 1; attempt <= OPEN_LOCK_RETRY_ATTEMPTS; attempt++) {
+    try {
+      return construct();
+    } catch (err) {
+      if (!isDbBusyError(err)) throw err;
+      originalLockError = err;
+      if (attempt === OPEN_LOCK_RETRY_ATTEMPTS) break;
+      await sleep(OPEN_LOCK_RETRY_DELAY_MS * attempt);
+    }
+  }
+
+  // Final defense: only for recognized test fixtures, sweep stale sidecars
+  // (a prior aborted test run can leave a `.wal` lock that survives the
+  // tmp dir cleanup). Production paths never reach this branch — the guard
+  // requires the immediate parent dir to match a test prefix AND the
+  // resolved path to live under the OS temp directory.
+  if (isTestFixturePath(dbPath)) {
+    await sweepStaleSidecars(dbPath);
+    try {
+      return construct();
+    } catch {
+      // Intentionally do NOT overwrite originalLockError. The user-actionable
+      // signal is "we exhausted lock retries" — a different error from the
+      // post-sweep attempt is less useful than the lock failure that drove
+      // the sweep in the first place.
+    }
+  }
+  throw tagOpenRetryExhausted(originalLockError);
+};
+
 export async function openLbugConnection(
   lbugModule: LbugModule,
   databasePath: string,
@@ -74,7 +270,10 @@ export async function openLbugConnection(
 ): Promise<LbugConnectionHandle> {
   let db: lbug.Database | undefined;
   try {
-    db = createLbugDatabase(lbugModule, databasePath, options);
+    db = await openWithLockRetry(
+      () => createLbugDatabase(lbugModule, databasePath, options),
+      databasePath,
+    );
     return { db, conn: new lbugModule.Connection(db) };
   } catch (err) {
     if (db) await db.close().catch(() => {});
@@ -86,3 +285,60 @@ export async function closeLbugConnection(handle: LbugConnectionHandle): Promise
   await handle.conn.close().catch(() => {});
   await handle.db.close().catch(() => {});
 }
+
+/**
+ * Probe `dbPath` AND its `.wal` sidecar after `db.close()` so any
+ * residual native file handle surfaces as EBUSY/EPERM/EACCES and the
+ * bounded retry absorbs the release lag. Windows-only — Linux/macOS do
+ * not exhibit this race.
+ *
+ * Both files matter. Empirically, on rapid open→close→reopen cycles the
+ * main `dbPath` handle releases first; the `.wal` handle from the
+ * previous Database lingers and the new Database's first write (CREATE
+ * NODE TABLE during schema init) fails with "Could not set lock on
+ * file". Probing both makes safeClose actually return when the kernel
+ * is fully done with the path.
+ *
+ * Returns `true` when both probes succeeded (or skipped on non-lock
+ * errors / missing files). Returns `false` when either probe exhausted
+ * its budget with a lock code still in flight.
+ *
+ * Defensive shape:
+ *   - Opens read+write (`'r+'`) so the probe actually surfaces exclusive
+ *     locks held by the previous Database. A read-only probe (`'r'`) is
+ *     insufficient — Windows will grant read access while the previous
+ *     handle's exclusive write lock is still in flight, which lets
+ *     `safeClose` return before the next CREATE NODE TABLE can lock the
+ *     file.
+ *   - `try/finally` around `handle.close()` guarantees no fd leak even
+ *     if close itself throws.
+ */
+export const waitForWindowsHandleRelease = async (dbPath: string): Promise<boolean> => {
+  const mainReleased = await probeSinglePath(dbPath);
+  const walReleased = await probeSinglePath(dbPath + '.wal');
+  return mainReleased && walReleased;
+};
+
+const probeSinglePath = async (filePath: string): Promise<boolean> => {
+  for (let attempt = 1; attempt <= HANDLE_RELEASE_PROBE_ATTEMPTS; attempt++) {
+    let handle: fs.FileHandle | undefined;
+    try {
+      handle = await fs.open(filePath, 'r+');
+      return true;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException | undefined)?.code;
+      if (!code || !HANDLE_RELEASE_LOCK_CODES.has(code)) return true; // ENOENT / unrelated → not our problem
+      if (attempt === HANDLE_RELEASE_PROBE_ATTEMPTS) return false;
+      await sleep(HANDLE_RELEASE_PROBE_DELAY_MS * attempt);
+    } finally {
+      if (handle) {
+        try {
+          await handle.close();
+        } catch {
+          /* swallow — caller cannot do anything useful with a probe-close failure */
+        }
+      }
+    }
+  }
+  return false;
+};
diff --git a/gitnexus/src/core/lbug/pool-adapter.ts b/gitnexus/src/core/lbug/pool-adapter.ts
index ca1c456112..ed999907eb 100644
--- a/gitnexus/src/core/lbug/pool-adapter.ts
+++ b/gitnexus/src/core/lbug/pool-adapter.ts
@@ -18,7 +18,7 @@
 import fs from 'fs/promises';
 import lbug from '@ladybugdb/core';
 import { loadFTSExtension } from './lbug-adapter.js';
-import { createLbugDatabase } from './lbug-config.js';
+import { createLbugDatabase, isWalCorruptionError } from './lbug-config.js';
 
 /** Per-repo pool: one Database, many Connections */
 interface PoolEntry {
@@ -97,7 +97,7 @@ let idleTimer: ReturnType<typeof setInterval> | null = null;
 // @ladybugdb/core), corrupting stdout in the pre-sentinel window. Routing
 // through the leaf breaks that chain.
 export { realStdoutWrite, realStderrWrite, setActiveStdoutWrite } from '../../mcp/stdio-capture.js';
-import { getActiveStdoutWrite } from '../../mcp/stdio-capture.js';
+import { getActiveStdoutWrite, realStderrWrite } from '../../mcp/stdio-capture.js';
 
 let stdoutSilenceCount = 0;
 /** True while pre-warming connections — prevents watchdog from prematurely restoring stdout */
@@ -263,6 +263,46 @@ const WAITER_TIMEOUT_MS = 15_000;
 const LOCK_RETRY_ATTEMPTS = 3;
 const LOCK_RETRY_DELAY_MS = 2000;
 
+async function openReadOnlyDatabase(dbPath: string): Promise<lbug.Database> {
+  let db: lbug.Database | undefined;
+  silenceStdout();
+  try {
+    db = createLbugDatabase(lbug, dbPath, {
+      readOnly: true,
+      throwOnWalReplayFailure: false,
+    });
+    await db.init();
+    return db;
+  } catch (err) {
+    if (db) await db.close().catch(() => {});
+    throw err;
+  } finally {
+    restoreStdout();
+  }
+}
+
+/**
+ * Quarantine the .wal file and retry opening the database.
+ * Used when the initial open fails with a WAL corruption error.
+ */
+async function tryQuarantineAndReopen(dbPath: string, repoId: string): Promise<lbug.Database> {
+  const walPath = dbPath + '.wal';
+  const quarantineName = `${walPath}.corrupt.${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  try {
+    await fs.rename(walPath, quarantineName);
+  } catch {
+    throw new Error(
+      `LadybugDB WAL corruption detected for ${repoId}. ` +
+        `Run \`gitnexus analyze\` to rebuild the index. (quarantine failed)`,
+    );
+  }
+  realStderrWrite(
+    `GitNexus: LadybugDB WAL quarantined for ${repoId}; graph may be stale. ` +
+      `Run \`gitnexus analyze\` to rebuild the index.\n`,
+  );
+  return await openReadOnlyDatabase(dbPath);
+}
+
 /** Deduplicates concurrent initLbug calls for the same repoId */
 const initPromises = new Map<string, Promise<void>>();
 
@@ -319,16 +359,29 @@ async function doInitLbug(repoId: string, dbPath: string): Promise<void> {
     // avoids lock conflicts when `gitnexus analyze` is writing.
     let lastError: Error | null = null;
     for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
-      silenceStdout();
       try {
-        const db = createLbugDatabase(lbug, dbPath, { readOnly: true });
-        restoreStdout();
+        const db = await openReadOnlyDatabase(dbPath);
         shared = { db, refCount: 0, ftsLoaded: false };
         dbCache.set(dbPath, shared);
         break;
       } catch (err: any) {
-        restoreStdout();
         lastError = err instanceof Error ? err : new Error(String(err));
+
+        if (isWalCorruptionError(lastError)) {
+          try {
+            const db = await tryQuarantineAndReopen(dbPath, repoId);
+            shared = { db, refCount: 0, ftsLoaded: false };
+            dbCache.set(dbPath, shared);
+            break;
+          } catch (retryErr) {
+            throw new Error(
+              `LadybugDB WAL corruption detected for ${repoId}. ` +
+                `Run \`gitnexus analyze\` to rebuild the index. ` +
+                `(${retryErr instanceof Error ? retryErr.message : String(retryErr)})`,
+            );
+          }
+        }
+
         const isLockError =
           lastError.message.includes('Could not set lock') || lastError.message.includes('lock');
         if (!isLockError || attempt === LOCK_RETRY_ATTEMPTS) break;
diff --git a/gitnexus/src/core/logger.ts b/gitnexus/src/core/logger.ts
new file mode 100644
index 0000000000..3fd39193bb
--- /dev/null
+++ b/gitnexus/src/core/logger.ts
@@ -0,0 +1,375 @@
+/**
+ * Centralized structured logger for GitNexus.
+ *
+ * Wraps `pino` so the rest of the codebase imports from one place. Pino's
+ * NDJSON output is structurally log-injection-resistant (CWE-117 / CodeQL
+ * `js/log-injection`): each record is a single JSON object on its own line,
+ * with all string field values JSON-escaped. This replaces hand-rolled
+ * sanitizers (see PR #1329 history) that had recurring edge-case gaps
+ * (undefined Error.message, U+2028/U+2029, ANSI/C0).
+ *
+ * Usage:
+ *   import { logger, createLogger } from '../core/logger.js';
+ *   logger.warn({ groupDir }, 'msg');
+ *   const childLogger = createLogger('bridge-db', { debugEnvVar: 'GITNEXUS_DEBUG_BRIDGE' });
+ *
+ * Operator semantics:
+ *   - Default level: 'info' (matches pino default; preserves visibility of
+ *     existing `console.log` migrations)
+ *   - When `opts.debugEnvVar` is set and that env var is truthy at
+ *     createLogger time, that named child logs at level 'debug'
+ *   - Output is NDJSON in production / CI / vitest. pino-pretty is used only
+ *     when stdout is a TTY AND CI is unset AND VITEST is unset, so test
+ *     and pipeline output stay parseable.
+ *
+ * Test capture:
+ *   The exported `logger` singleton is a Proxy that forwards every call to a
+ *   lazily-built pino instance. Tests use `_captureLogger()` to redirect that
+ *   inner instance to a memory stream so they can assert on records the
+ *   production code logged. See `gitnexus/test/unit/logger.test.ts` for the
+ *   pattern.
+ */
+import pino, { type Logger, type LoggerOptions, type DestinationStream } from 'pino';
+import { Writable } from 'node:stream';
+import { createRequire } from 'node:module';
+
+export interface CreateLoggerOptions {
+  /** When set, this env var (truthy at construction time) bumps level to 'debug'. */
+  debugEnvVar?: string;
+  /** Override destination stream — primarily for tests. */
+  destination?: DestinationStream;
+}
+
+function isTruthyEnv(value: string | undefined): boolean {
+  if (!value) return false;
+  const v = value.toLowerCase();
+  return v !== '' && v !== '0' && v !== 'false' && v !== 'no' && v !== 'off';
+}
+
+function shouldUsePretty(): boolean {
+  // Logger writes to stderr (fd 2) so CLI data on stdout (fd 1) stays clean.
+  // Pretty-print only when stderr is a TTY and not in CI/test environments.
+  return (
+    process.stderr.isTTY === true &&
+    !isTruthyEnv(process.env.CI) &&
+    !isTruthyEnv(process.env.VITEST)
+  );
+}
+
+/**
+ * Default pino destination — writes to stderr (fd 2) so CLI commands can
+ * keep stdout (fd 1) clean for tool data output (#324). Pino defaults to
+ * stdout; we override here.
+ *
+ * `sync: false` (SonicBoom buffered writes) so logger calls don't issue a
+ * blocking `write(2)` syscall on every record. Hot paths (parse-impl,
+ * ingestion phases, per-query backend calls) pay the cost without it.
+ *
+ * The buffered-write trade-off is record loss on hard exit. We mitigate via:
+ *   - A `process.on('beforeExit')` hook below that calls `flushSync()` on
+ *     normal exits.
+ *   - The exported `flushLoggerSync()` helper, which entry-point shutdown
+ *     handlers (SIGINT/SIGTERM) MUST call before `process.exit(N)` so
+ *     in-flight buffered records still reach stderr.
+ *   - `pino.final(...)` integration in `uncaughtException` / `unhandledRejection`
+ *     handlers (see `gitnexus/src/cli/serve.ts` and `gitnexus/src/server/api.ts`).
+ *
+ * Skipped under `VITEST` so vitest's between-test cleanup doesn't fight
+ * `_captureLogger()`'s lifecycle. Tests use an in-memory destination via
+ * `_captureLogger()` and never reach this branch.
+ */
+let _dest: ReturnType<typeof pino.destination> | undefined;
+
+function defaultDestination(): DestinationStream {
+  if (_dest) return _dest;
+  _dest = pino.destination({ dest: 2, sync: false });
+  return _dest;
+}
+
+/**
+ * Flush any buffered records on the default destination. Entry-point
+ * shutdown handlers (`SIGINT` / `SIGTERM`) MUST call this before
+ * `process.exit(N)` — otherwise async-buffered records are lost on hard
+ * exit. No-op when the destination hasn't been constructed yet (logger
+ * module imported but never emitted) or when called from `_captureLogger`
+ * test mode (tests use an in-memory destination).
+ */
+export function flushLoggerSync(): void {
+  if (!_dest) return;
+  try {
+    _dest.flushSync();
+  } catch {
+    // Defend against a destination that has already been closed (e.g.,
+    // double-flush on rapid shutdown). Losing the flush attempt is the
+    // correct trade-off vs. throwing during shutdown.
+  }
+}
+
+/**
+ * Idempotent registration: `process.on('beforeExit')` flushes the buffered
+ * destination before normal exit. Skipped under VITEST to avoid interfering
+ * with `_captureLogger()`'s lifecycle and vitest's per-worker cleanup.
+ */
+let _flushHookInstalled = false;
+function installFlushHook(): void {
+  if (_flushHookInstalled) return;
+  if (isTruthyEnv(process.env.VITEST)) return;
+  _flushHookInstalled = true;
+  process.on('beforeExit', () => {
+    flushLoggerSync();
+  });
+}
+
+/**
+ * Probe whether `pino-pretty` is resolvable from this module. Cached for
+ * the lifetime of the process — the resolve cost only happens once, and
+ * the one-time stderr warning on miss only fires once.
+ *
+ * Production installs ship pino-pretty as a runtime dependency (see
+ * gitnexus/package.json). The probe is the safety net for `--omit=optional`,
+ * `--no-package-lock` style installs and for any environment where the
+ * module turns out to be missing for reasons we can't predict — pino's
+ * own transport-resolution path resolves the target lazily at FIRST log
+ * write, so without this probe a missing module would throw deep inside
+ * the pino call site rather than at logger construction.
+ */
+let _prettyAvailable: boolean | null = null;
+const _require = createRequire(import.meta.url);
+
+function isPrettyAvailable(): boolean {
+  if (_prettyAvailable !== null) return _prettyAvailable;
+  try {
+    _require.resolve('pino-pretty');
+    _prettyAvailable = true;
+  } catch {
+    _prettyAvailable = false;
+    // One-time stderr warning so operators learn why TTY output is plain
+    // NDJSON instead of pretty-printed. Use realStderrWrite-style direct
+    // write — going through `logger` here would recurse.
+    process.stderr.write(
+      '[gitnexus:logger] pino-pretty unavailable; falling back to NDJSON on stderr\n',
+    );
+  }
+  return _prettyAvailable;
+}
+
+/**
+ * @internal Test-only reset for the pino-pretty availability cache. Lets
+ * unit tests exercise both resolve outcomes within the same vitest worker.
+ */
+export function _resetPrettyAvailableCache(): void {
+  _prettyAvailable = null;
+}
+
+/**
+ * Build the pino-pretty transport options. Internal — exported only so unit
+ * tests can exercise the probe path without going through `shouldUsePretty()`
+ * (which is structurally false under vitest).
+ */
+export function _tryBuildPrettyTransport(): LoggerOptions['transport'] | undefined {
+  if (!isPrettyAvailable()) return undefined;
+  return {
+    target: 'pino-pretty',
+    options: {
+      // Route to stderr (fd 2) so pretty output doesn't contaminate
+      // CLI tool data on stdout (fd 1). pino-pretty's default is fd 1,
+      // which would interleave with `gitnexus query | jq` output.
+      destination: 2,
+      colorize: true,
+      translateTime: 'SYS:HH:MM:ss.l',
+      ignore: 'pid,hostname',
+    },
+  };
+}
+
+/**
+ * Pino accepts `'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent'`.
+ * Anything else is silently ignored at runtime; we narrow here so a typo in
+ * the env var produces the documented default rather than masking the issue.
+ */
+const PINO_LEVELS = new Set(['fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent']);
+
+function resolveBaseLevel(): string {
+  const fromEnv = process.env.GITNEXUS_LOG_LEVEL;
+  if (fromEnv && PINO_LEVELS.has(fromEnv.toLowerCase())) {
+    return fromEnv.toLowerCase();
+  }
+  return 'info';
+}
+
+function buildBaseOptions(): LoggerOptions {
+  const opts: LoggerOptions = {
+    level: resolveBaseLevel(),
+    base: undefined,
+  };
+  if (shouldUsePretty()) {
+    const transport = _tryBuildPrettyTransport();
+    if (transport) opts.transport = transport;
+  }
+  return opts;
+}
+
+/**
+ * Create a named child logger. When `opts.destination` is provided it bypasses
+ * the default stdout sink (useful for test capture). When `opts.debugEnvVar` is
+ * set and truthy at call time, the child runs at 'debug' level.
+ */
+export function createLogger(name: string, opts?: CreateLoggerOptions): Logger {
+  const debugRequested = opts?.debugEnvVar ? isTruthyEnv(process.env[opts.debugEnvVar]) : false;
+
+  if (opts?.destination) {
+    return pino(
+      { level: debugRequested ? 'debug' : 'info', base: undefined, name },
+      opts.destination,
+    );
+  }
+
+  const base = buildBaseOptions();
+  // When using a transport (pino-pretty), pino manages the destination
+  // internally and we cannot pass one explicitly. When transport is absent,
+  // route to stderr so stdout stays clean for CLI data output.
+  let root: Logger;
+  if (base.transport) {
+    root = pino({ ...base, level: debugRequested ? 'debug' : base.level });
+  } else {
+    root = pino({ ...base, level: debugRequested ? 'debug' : base.level }, defaultDestination());
+    // The default destination is buffered (`sync: false`); register the
+    // graceful-exit flush hook now that we know the destination will be
+    // used. Idempotent — runs at most once per process. Skipped under
+    // VITEST so test cleanup doesn't fight `_captureLogger`.
+    installFlushHook();
+  }
+  return root.child({ name });
+}
+
+/* ------------------------------------------------------------------ */
+/*  Default singleton (Proxy-backed for test capture)                  */
+/* ------------------------------------------------------------------ */
+
+let _activeDestination: DestinationStream | undefined;
+let _cached: Logger | undefined;
+
+function _getInner(): Logger {
+  if (_cached) return _cached;
+  // Always go through createLogger so future defaults (serializers, redaction,
+  // formatters) apply uniformly. The destination override is honored when set
+  // by `_captureLogger()` below.
+  _cached = createLogger(
+    'gitnexus',
+    _activeDestination ? { destination: _activeDestination } : undefined,
+  );
+  return _cached;
+}
+
+/**
+ * Default singleton logger (`name: 'gitnexus'`). Backed by a Proxy so test
+ * capture (`_captureLogger()`) can redirect output without breaking modules
+ * that already imported the singleton at module-load time.
+ */
+export const logger = new Proxy({} as Logger, {
+  get(_target, prop) {
+    const inner = _getInner();
+    // Reflect.get keeps symbol-keyed lookups (e.g. Symbol.toPrimitive) intact;
+    // a `prop as string` cast would silently coerce them to the wrong key.
+    const value = Reflect.get(inner as object, prop, inner);
+    if (typeof value === 'function') {
+      return (value as (...a: unknown[]) => unknown).bind(inner);
+    }
+    return value;
+  },
+}) as Logger;
+
+/**
+ * Shape of a parsed pino record. `level`, `time`, and `msg` are always
+ * present; `name` is set when emitted from a named child logger; arbitrary
+ * additional fields appear when callers pass a structured first arg.
+ *
+ * Exported so test helpers and downstream skills can type-narrow capture
+ * results without inline `Record<string, unknown>` casts.
+ */
+export interface PinoLogRecord {
+  level: number;
+  time: number;
+  msg: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * In-memory Writable used by `_captureLogger()` and by tests that build
+ * their own pino destination. Exported so the shape lives in one place
+ * (previously duplicated between this module and `logger.test.ts`).
+ *
+ * `text()` and `records()` are convenience helpers test code calls. They
+ * don't appear in production hot paths — only test destinations capture
+ * here — so the surface is intentionally small.
+ */
+export class MemoryWritable extends Writable {
+  chunks: string[] = [];
+  _write(chunk: Buffer | string, _enc: BufferEncoding, cb: (err?: Error | null) => void): void {
+    this.chunks.push(typeof chunk === 'string' ? chunk : chunk.toString('utf-8'));
+    cb();
+  }
+  /** Concatenate every captured write back into a single string. */
+  text(): string {
+    return this.chunks.join('');
+  }
+  /** Parse captured writes as one NDJSON record per non-empty line. */
+  records(): PinoLogRecord[] {
+    return this.text()
+      .split('\n')
+      .filter((l) => l.length > 0)
+      .map((l) => JSON.parse(l) as PinoLogRecord);
+  }
+}
+
+export interface LoggerCapture {
+  records(): PinoLogRecord[];
+  text(): string;
+  restore(): void;
+}
+
+/**
+ * Test helper. Redirects the default `logger` singleton to an in-memory
+ * stream and returns a capture object plus a restore function.
+ *
+ * Pattern:
+ *   let cap: LoggerCapture;
+ *   beforeEach(() => { cap = _captureLogger(); });
+ *   afterEach(() => { cap.restore(); });
+ *   it('warns', () => {
+ *     fnUnderTest();
+ *     expect(cap.records().some(r => r.msg?.includes('clamping'))).toBe(true);
+ *   });
+ *
+ * Not a public API; underscore-prefixed and called only from test code.
+ * Throws if a previous capture is still active — see the body for context.
+ */
+export function _captureLogger(): LoggerCapture {
+  // Guard against double-capture: forgetting `restore()` between two
+  // `_captureLogger()` calls silently abandoned the previous capture and
+  // corrupted logger state for the rest of the vitest worker. Throwing here
+  // surfaces the bug at the moment of misuse instead of as inscrutable
+  // missing-records assertions in unrelated tests.
+  if (_activeDestination !== undefined) {
+    throw new Error(
+      '_captureLogger: a previous capture is still active — call restore() before starting a new one.',
+    );
+  }
+  const w = new MemoryWritable();
+  _activeDestination = w;
+  _cached = undefined;
+  return {
+    records: () =>
+      w.chunks
+        .join('')
+        .split('\n')
+        .filter((l) => l.length > 0)
+        .map((l) => JSON.parse(l) as PinoLogRecord),
+    text: () => w.chunks.join(''),
+    restore: () => {
+      _activeDestination = undefined;
+      _cached = undefined;
+    },
+  };
+}
diff --git a/gitnexus/src/core/tree-sitter/parser-loader.ts b/gitnexus/src/core/tree-sitter/parser-loader.ts
index 0ec958e365..8057e77957 100644
--- a/gitnexus/src/core/tree-sitter/parser-loader.ts
+++ b/gitnexus/src/core/tree-sitter/parser-loader.ts
@@ -2,6 +2,7 @@ import Parser from 'tree-sitter';
 import { createRequire } from 'node:module';
 import { SupportedLanguages } from 'gitnexus-shared';
 
+import { logger } from '../logger.js';
 const _require = createRequire(import.meta.url);
 
 /**
@@ -175,10 +176,14 @@ const logFailure = (key: string, result: LoadResult): void => {
   logged.add(key);
   const message = `[gitnexus] ${result.note} (${result.error.message})`;
 
-  // Both severities go to stderr — console.warn writes to stderr too, but
-  // console.error is the stdout-safe channel we standardize on across
-  // MCP-reachable code so the ESLint rule covers this directory.
-  console.error(message);
+  // Severity routes to the correct pino level. Both go to stderr (pino's
+  // default destination), so MCP stdio framing is preserved either way —
+  // the level tag drives log filtering, not channel selection.
+  if (result.severity === 'error') {
+    logger.error(message);
+  } else {
+    logger.warn(message);
+  }
 };
 
 export const resolveLanguageKey = (language: SupportedLanguages, filePath?: string): string =>
diff --git a/gitnexus/src/core/wiki/cursor-client.ts b/gitnexus/src/core/wiki/cursor-client.ts
index 707f8e293c..bf85f4183e 100644
--- a/gitnexus/src/core/wiki/cursor-client.ts
+++ b/gitnexus/src/core/wiki/cursor-client.ts
@@ -10,6 +10,7 @@
 import { spawn, execSync } from 'child_process';
 import type { LLMResponse, CallLLMOptions } from './llm-client.js';
 
+import { logger } from '../logger.js';
 export interface CursorConfig {
   model?: string;
   workingDirectory?: string;
@@ -21,7 +22,7 @@ function isVerbose(): boolean {
 
 function verboseLog(...args: unknown[]): void {
   if (isVerbose()) {
-    console.log('[cursor-cli]', ...args);
+    logger.info({ args }, '[cursor-cli]');
   }
 }
 
diff --git a/gitnexus/src/core/wiki/llm-client.ts b/gitnexus/src/core/wiki/llm-client.ts
index 6f446be152..172b8b00f7 100644
--- a/gitnexus/src/core/wiki/llm-client.ts
+++ b/gitnexus/src/core/wiki/llm-client.ts
@@ -1,3 +1,4 @@
+import { logger } from '../logger.js';
 /**
  * LLM Client for Wiki Generation
  *
@@ -85,8 +86,10 @@ export function isAzureProvider(baseUrl: string): boolean {
     const { hostname } = new URL(baseUrl);
     return hostname.endsWith('.openai.azure.com') || hostname.endsWith('.services.ai.azure.com');
   } catch {
-    // If URL is malformed, fall back to substring check
-    return baseUrl.includes('.openai.azure.com') || baseUrl.includes('.services.ai.azure.com');
+    // Malformed URL — refuse to call this Azure rather than fall back to a
+    // substring check, which is bypassable by `https://evil.com/?u=.openai.azure.com`
+    // (CodeQL js/incomplete-url-substring-sanitization).
+    return false;
   }
 }
 
@@ -135,7 +138,7 @@ export async function callLLM(
 
   // Warn when using Azure legacy deployment URL without api-version
   if (azure && !config.apiVersion && config.baseUrl.includes('/deployments/')) {
-    console.warn(
+    logger.warn(
       '[gitnexus] Warning: Azure legacy deployment URL detected but no api-version set. Add --api-version 2024-10-21 or use the v1 API format.',
     );
   }
diff --git a/gitnexus/src/mcp/core/embedder.ts b/gitnexus/src/mcp/core/embedder.ts
index f506cdeadf..f529f28054 100644
--- a/gitnexus/src/mcp/core/embedder.ts
+++ b/gitnexus/src/mcp/core/embedder.ts
@@ -12,9 +12,14 @@ import {
   httpEmbedQuery,
 } from '../../core/embeddings/http-client.js';
 import { resolveEmbeddingConfig } from '../../core/embeddings/config.js';
-import { applyHfEnvOverrides } from '../../core/embeddings/hf-env.js';
+import {
+  applyHfEnvOverrides,
+  isHfDownloadFailure,
+  withHfDownloadRetry,
+} from '../../core/embeddings/hf-env.js';
 import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/lbug/pool-adapter.js';
 
+import { logger } from '../../core/logger.js';
 // Model config
 const MODEL_ID = 'Snowflake/snowflake-arctic-embed-xs';
 
@@ -51,7 +56,7 @@ export const initEmbedder = async (): Promise<FeatureExtractionPipeline> => {
       applyHfEnvOverrides(env);
       const embeddingConfig = resolveEmbeddingConfig();
 
-      console.error('GitNexus: Loading embedding model (first search may take a moment)...');
+      logger.info('GitNexus: Loading embedding model (first search may take a moment)...');
 
       const devicesToTry: Array<'dml' | 'cuda' | 'cpu'> =
         embeddingConfig.device === 'dml' || embeddingConfig.device === 'cuda'
@@ -68,23 +73,39 @@ export const initEmbedder = async (): Promise<FeatureExtractionPipeline> => {
           silenceStdout();
           process.stderr.write = (() => true) as any;
           try {
-            embedderInstance = await (pipeline as any)('feature-extraction', MODEL_ID, {
-              device: device,
-              dtype: 'fp32',
-              session_options: {
-                logSeverityLevel: 3,
-                intraOpNumThreads: embeddingConfig.threads,
-                interOpNumThreads: 1,
-                executionMode: 'sequential',
-              },
-            });
+            embedderInstance = await withHfDownloadRetry(() =>
+              pipeline('feature-extraction', MODEL_ID, {
+                device: device,
+                dtype: 'fp32',
+                session_options: {
+                  logSeverityLevel: 3,
+                  intraOpNumThreads: embeddingConfig.threads,
+                  interOpNumThreads: 1,
+                  executionMode: 'sequential',
+                },
+              }),
+            );
           } finally {
             restoreStdout();
             process.stderr.write = realStderrWrite;
           }
-          console.error(`GitNexus: Embedding model loaded (${device})`);
+          logger.info({ device }, 'GitNexus: Embedding model loaded');
           return embedderInstance!;
-        } catch {
+        } catch (deviceError) {
+          // Network errors and circuit-open errors are not device-specific —
+          // they will fail the same way on every device. Rethrow immediately
+          // with actionable HF_ENDPOINT guidance rather than silently falling
+          // back to the next device.
+          const errMsg = deviceError instanceof Error ? deviceError.message : String(deviceError);
+          if (isHfDownloadFailure(errMsg)) {
+            const endpointHint = process.env.HF_ENDPOINT
+              ? `The configured endpoint (${process.env.HF_ENDPOINT}) may be unreachable.`
+              : `huggingface.co may be unreachable from your network.\n` +
+                `  Set HF_ENDPOINT to a mirror and retry:\n` +
+                `    HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
+                `    (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)`;
+            throw new Error(`Failed to download embedding model: ${errMsg}\n  ${endpointHint}`);
+          }
           if (device === 'cpu') throw new Error('Failed to load embedding model');
         }
       }
diff --git a/gitnexus/src/mcp/local/local-backend.ts b/gitnexus/src/mcp/local/local-backend.ts
index 68df9feaac..2f16c1fb20 100644
--- a/gitnexus/src/mcp/local/local-backend.ts
+++ b/gitnexus/src/mcp/local/local-backend.ts
@@ -16,6 +16,7 @@ import {
   isLbugReady,
   isWriteQuery,
 } from '../../core/lbug/pool-adapter.js';
+import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/lbug-config.js';
 export { isWriteQuery };
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
@@ -40,7 +41,8 @@ import {
   isVectorExtensionSupportedByPlatform,
 } from '../../core/platform/capabilities.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
-import { checkStaleness, checkCwdMatch } from '../../core/git-staleness.js';
+import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
+import { logger } from '../../core/logger.js';
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 
@@ -164,29 +166,27 @@ const confidenceForRelType = (relType: string | undefined): number =>
 /** Structured error logging for query failures — replaces empty catch blocks */
 function logQueryError(context: string, err: unknown): void {
   const msg = err instanceof Error ? err.message : String(err);
-  console.error(`GitNexus [${context}]: ${msg}`);
+  logger.error({ context, err: msg }, 'GitNexus query failed');
 }
 
 /**
- * Structured per-query latency log for production aggregation (#553).
+ * Per-query latency telemetry for production aggregation (#553).
  *
- * Emitted on stderr — NOT stdout — because the MCP stdio transport uses
- * stdout exclusively for JSON-RPC responses (#324), and the CLI e2e test
- * `tool output goes to stdout via fd 1` asserts that stdout parses cleanly
- * as JSON. Any `console.log` from inside a tool handler would corrupt the
- * protocol. Matches the existing `logQueryError` convention above, which
- * uses stderr for the same reason.
+ * Logged at `debug` level — timing is observability/telemetry, not an
+ * error. Operators wanting per-query timing set `GITNEXUS_LOG_LEVEL=debug`
+ * (or equivalent). Emitting at `error` level (the original migration
+ * artifact) caused alerting rules to fire on every successful query and
+ * inflated stderr noise for every MCP/CLI invocation.
  *
- * The `GitNexus [query:timing] …` prefix keeps lines greppable; the
- * `phases` payload is JSON so log-scraping pipelines can parse it
- * without custom format knowledge.
+ * Emitted via the project logger which routes to stderr — never stdout —
+ * because the MCP stdio transport uses stdout exclusively for JSON-RPC
+ * responses (#324) and the CLI e2e test `tool output goes to stdout via
+ * fd 1` asserts stdout parses cleanly as JSON.
  */
 function logQueryTiming(query: string, phases: Record<string, number>): void {
   const totalMs = phases.wall ?? Object.values(phases).reduce((a, b) => a + b, 0);
   const truncated = query.length > 80 ? `${query.slice(0, 80)}…` : query;
-  console.error(
-    `GitNexus [query:timing] query=${JSON.stringify(truncated)} totalMs=${totalMs} phases=${JSON.stringify(phases)}`,
-  );
+  logger.debug({ query: truncated, totalMs, phases }, 'GitNexus query timing');
 }
 
 export interface CodebaseContext {
@@ -287,7 +287,7 @@ export class LocalBackend {
       // If kuzu exists but lbug doesn't, warn so the user knows to re-analyze.
       const kuzu = await cleanupOldKuzuFiles(storagePath);
       if (kuzu.found && kuzu.needsReindex) {
-        console.error(
+        logger.error(
           `GitNexus: "${entry.name}" has a stale KuzuDB index. Run: gitnexus analyze ${entry.path}`,
         );
       }
@@ -555,8 +555,15 @@ export class LocalBackend {
       byRemote.set(h.remoteUrl, list);
     }
 
-    return handles.map((h) => {
-      const stale = checkStaleness(h.repoPath, h.lastCommit);
+    // Check staleness for all repos in parallel instead of sequentially.
+    // Each check spawns an async `git rev-list` — with 200 repos the sync
+    // variant took ~50 s; parallel async brings it under a second (#1363).
+    const stalenessResults = await Promise.all(
+      handles.map((h) => checkStalenessAsync(h.repoPath, h.lastCommit)),
+    );
+
+    return handles.map((h, i) => {
+      const stale = stalenessResults[i];
       const selfNorm = norm(h.repoPath);
       const siblings = h.remoteUrl
         ? (byRemote.get(h.remoteUrl) ?? []).filter((e) => norm(e.repoPath) !== selfNorm)
@@ -637,7 +644,7 @@ export class LocalBackend {
     }
 
     this.warnedSiblingDrift.add(cacheKey);
-    console.error(`GitNexus: ${match.hint}`);
+    logger.error(`GitNexus: ${match.hint}`);
   }
 
   // ─── Tool Dispatch ───────────────────────────────────────────────
@@ -990,7 +997,10 @@ export class LocalBackend {
     try {
       bm25Results = await searchFTSFromLbug(query, limit, repo.id);
     } catch (err: any) {
-      console.error('GitNexus: BM25/FTS search failed (FTS indexes may not exist) -', err.message);
+      logger.error(
+        { err: err.message },
+        'GitNexus: BM25/FTS search failed (FTS indexes may not exist) -',
+      );
       return { results: [], ftsUsed: false };
     }
 
@@ -1114,7 +1124,7 @@ export class LocalBackend {
         // policy. Emitted once per `LocalBackend` instance lifetime to avoid
         // noisy stderr on hot semantic-search paths (DoD §2.8).
         this.warnedVectorUnsupported = true;
-        console.error(
+        logger.warn(
           'GitNexus [query:vector]: VECTOR extension not supported on this platform; using exact scan fallback',
         );
       }
@@ -1216,7 +1226,14 @@ export class LocalBackend {
       const result = await executeQuery(repo.id, params.query);
       return result;
     } catch (err: any) {
-      return { error: err.message || 'Query failed' };
+      const msg = err.message || 'Query failed';
+      if (isWalCorruptionError(err)) {
+        return {
+          error: msg,
+          recoverySuggestion: WAL_RECOVERY_SUGGESTION,
+        };
+      }
+      return { error: msg };
     }
   }
 
@@ -1670,6 +1687,30 @@ export class LocalBackend {
       kind?: string;
       include_content?: boolean;
     },
+  ): Promise<any> {
+    try {
+      return await this._contextImpl(repo, params);
+    } catch (err: any) {
+      const msg = (err instanceof Error ? err.message : String(err)) || 'Context query failed';
+      if (isWalCorruptionError(err)) {
+        return {
+          error: msg,
+          recoverySuggestion: WAL_RECOVERY_SUGGESTION,
+        };
+      }
+      throw err;
+    }
+  }
+
+  private async _contextImpl(
+    repo: RepoHandle,
+    params: {
+      name?: string;
+      uid?: string;
+      file_path?: string;
+      kind?: string;
+      include_content?: boolean;
+    },
   ): Promise<any> {
     await this.ensureInitialized(repo.id);
 
@@ -2431,6 +2472,7 @@ export class LocalBackend {
         impactedCount: 0,
         risk: 'UNKNOWN',
         suggestion: 'The graph query failed — try gitnexus context <symbol> as a fallback',
+        ...(isWalCorruptionError(err) ? { recoverySuggestion: WAL_RECOVERY_SUGGESTION } : {}),
       };
     }
   }
@@ -2982,8 +3024,14 @@ export class LocalBackend {
       relationTypes: string[];
       minConfidence: number;
       includeTests: boolean;
+      signal?: AbortSignal;
     },
   ): Promise<any | null> {
+    // Honor an already-aborted signal at the entry boundary as a fast
+    // path. Cooperative cancellation inside _runImpactBFS is out of
+    // scope — the caller's Promise.race against the same signal
+    // resolves the await regardless of how long this body runs.
+    if (opts.signal?.aborted) return null;
     try {
       await this.refreshRepos();
       await this.ensureInitialized(repoId);
diff --git a/gitnexus/src/mcp/server.ts b/gitnexus/src/mcp/server.ts
index f7193c4846..5159b12d99 100644
--- a/gitnexus/src/mcp/server.ts
+++ b/gitnexus/src/mcp/server.ts
@@ -312,7 +312,11 @@ export async function startMCPServer(backend: LocalBackend): Promise<void> {
   // stray writes even when individual payloads were truncated/suppressed.
   process.on('exit', () => sentinel.flushSummary());
 
-  // Graceful shutdown helper
+  // Graceful shutdown helper. Pino's default destination is `sync: false`
+  // (buffered), so we must `flushLoggerSync()` before `process.exit` —
+  // otherwise records emitted during disconnect/close are lost. The flush
+  // is a no-op when the singleton was never used or when running under
+  // vitest. See `gitnexus/src/core/logger.ts`.
   let shuttingDown = false;
   const shutdown = async (exitCode = 0) => {
     if (shuttingDown) return;
@@ -323,6 +327,8 @@ export async function startMCPServer(backend: LocalBackend): Promise<void> {
     try {
       await server.close();
     } catch {}
+    const { flushLoggerSync } = await import('../core/logger.js');
+    flushLoggerSync();
     process.exit(exitCode);
   };
 
diff --git a/gitnexus/src/server/api.ts b/gitnexus/src/server/api.ts
index a8f784630a..7731907856 100644
--- a/gitnexus/src/server/api.ts
+++ b/gitnexus/src/server/api.ts
@@ -27,8 +27,6 @@ import { isWriteQuery } from '../core/lbug/pool-adapter.js';
 import { NODE_TABLES, type GraphNode, type GraphRelationship } from 'gitnexus-shared';
 import { searchFTSFromLbug } from '../core/search/bm25-index.js';
 import { hybridSearch } from '../core/search/hybrid-search.js';
-// Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
-// at server startup — crashes on unsupported Node ABI versions (#89)
 import { LocalBackend } from '../mcp/local/local-backend.js';
 import { mountMCPEndpoints } from './mcp-http.js';
 import { fork } from 'child_process';
@@ -36,6 +34,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { JobManager } from './analyze-job.js';
 import { assertString, escapeRegExp, BadRequestError, createRouteLimiter } from './validation.js';
 import { extractRepoName, getCloneDir, cloneOrPull } from './git-clone.js';
+import { logger, flushLoggerSync } from '../core/logger.js';
 
 const _require = createRequire(import.meta.url);
 const pkg = _require('../../package.json');
@@ -143,7 +142,7 @@ export const resolveWebDistDir = async (
       return dir;
     } catch (err: any) {
       if (err?.code !== 'ENOENT') {
-        console.warn(`[serve] could not access web UI dir ${dir}:`, err.message);
+        logger.warn({ err: err.message }, `[serve] could not access web UI dir ${dir}:`);
       }
     }
   }
@@ -1490,7 +1489,7 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
                     });
                   })
                   .catch((err) => {
-                    console.error('backend.init() failed after analyze:', err);
+                    logger.error({ err }, 'backend.init() failed after analyze:');
                     jobManager.updateJob(job.id, {
                       status: 'failed',
                       error: 'Server failed to reload after analysis. Try again.',
@@ -1522,7 +1521,7 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
                 j.retryCount++;
                 const delay = 1000 * Math.pow(2, j.retryCount - 1); // 1s, 2s
                 const lastErr = stderrChunks.trim().split('\n').pop() || '';
-                console.warn(
+                logger.warn(
                   `Analyze worker crashed (code ${code}), retry ${j.retryCount}/${MAX_WORKER_RETRIES} in ${delay}ms` +
                     (lastErr ? `: ${lastErr}` : ''),
                 );
@@ -1790,7 +1789,7 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
 
   // Global error handler — catch anything the route handlers miss
   app.use((err: any, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
-    console.error('Unhandled error:', err);
+    logger.error({ err }, 'Unhandled error:');
     res.status(500).json({ error: 'Internal server error' });
   });
 
@@ -1804,7 +1803,9 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
     });
     server.on('error', (err) => reject(err));
 
-    // Graceful shutdown — close Express + LadybugDB cleanly
+    // Graceful shutdown — close Express + LadybugDB cleanly. Pino's default
+    // destination is `sync: false` (buffered); `flushLoggerSync()` before
+    // `process.exit` so records emitted during cleanup reach stderr.
     const shutdown = async () => {
       console.log('\nShutting down...');
       server.close();
@@ -1813,22 +1814,33 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
       await cleanupMcp();
       await closeLbug();
       await backend.disconnect();
+      const { flushLoggerSync } = await import('../core/logger.js');
+      flushLoggerSync();
       process.exit(0);
     };
     process.once('SIGINT', shutdown);
     process.once('SIGTERM', shutdown);
 
-    // Catch-all crash guards (mirrors startMCPServer in mcp/server.ts)
+    // Catch-all crash guards (mirrors startMCPServer in mcp/server.ts).
+    // Pino v10's default destination is buffered (`sync: false`) — call
+    // `flushLoggerSync()` after logging and before triggering shutdown
+    // so the crash record reaches stderr regardless of how cleanup goes.
+    // Worker-thread transports (pino-pretty under TTY) handle their own
+    // flush on process exit in v10. `pino.final` was removed in v10
+    // because the new transport architecture made it unnecessary.
     let shuttingDown = false;
     process.on('uncaughtException', (err) => {
-      console.error('GitNexus uncaughtException:', err?.stack || err);
+      logger.error({ err }, 'GitNexus uncaughtException');
+      flushLoggerSync();
       if (!shuttingDown) {
         shuttingDown = true;
         shutdown().catch(() => {});
       }
     });
-    process.on('unhandledRejection', (reason: any) => {
-      console.error('GitNexus unhandledRejection:', reason?.stack || reason);
+    process.on('unhandledRejection', (reason: unknown) => {
+      // Availability-first: log the rejection without exiting.
+      const err = reason instanceof Error ? reason : new Error(String(reason));
+      logger.error({ err }, 'GitNexus unhandledRejection');
     });
   });
 };
diff --git a/gitnexus/src/server/git-clone.ts b/gitnexus/src/server/git-clone.ts
index b1f369dd7e..861a166484 100644
--- a/gitnexus/src/server/git-clone.ts
+++ b/gitnexus/src/server/git-clone.ts
@@ -10,6 +10,7 @@ import path from 'path';
 import os from 'os';
 import fs from 'fs/promises';
 import { isIP } from 'net';
+import { logger } from '../core/logger.js';
 
 /** Root directory for all cloned repositories. Targets must resolve inside this. */
 const CLONE_ROOT = path.resolve(path.join(os.homedir(), '.gitnexus', 'repos'));
@@ -446,7 +447,7 @@ function runGit(args: string[], cwd?: string): Promise<void> {
       if (code === 0) resolve();
       else {
         // Log full stderr internally but don't expose it to API callers (SSRF mitigation)
-        if (stderr.trim()) console.error(`git ${args[0]} stderr: ${stderr.trim()}`);
+        if (stderr.trim()) logger.error(`git ${args[0]} stderr: ${stderr.trim()}`);
         reject(new Error(`git ${args[0]} failed (exit code ${code})`));
       }
     });
diff --git a/gitnexus/src/server/mcp-http.ts b/gitnexus/src/server/mcp-http.ts
index 0bc086360f..67ec947085 100644
--- a/gitnexus/src/server/mcp-http.ts
+++ b/gitnexus/src/server/mcp-http.ts
@@ -15,6 +15,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { createMCPServer } from '../mcp/server.js';
 import type { LocalBackend } from '../mcp/local/local-backend.js';
 import { randomUUID } from 'crypto';
+import { logger } from '../core/logger.js';
 
 interface MCPSession {
   server: Server;
@@ -87,7 +88,7 @@ export function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Pr
 
   app.all('/api/mcp', (req: Request, res: Response) => {
     void handleMcpRequest(req, res).catch((err: any) => {
-      console.error('MCP HTTP request failed:', err);
+      logger.error({ err }, 'MCP HTTP request failed:');
       if (res.headersSent) return;
       res.status(500).json({
         jsonrpc: '2.0',
diff --git a/gitnexus/test/helpers/test-db.ts b/gitnexus/test/helpers/test-db.ts
index 5818fdc8e1..37032ebc8b 100644
--- a/gitnexus/test/helpers/test-db.ts
+++ b/gitnexus/test/helpers/test-db.ts
@@ -37,6 +37,13 @@ export async function cleanupTempDir(tmpDir: string): Promise<void> {
 /**
  * Create a temporary directory for LadybugDB tests.
  * Returns the path and a cleanup function.
+ *
+ * IMPORTANT: when adding a new test that passes a custom `prefix`, also add
+ * the prefix to `TEST_FIXTURE_PREFIXES` in
+ * `gitnexus/src/core/lbug/lbug-config.ts`. The stale-sidecar sweep relies
+ * on the prefix list to recognize test fixtures; an unknown prefix means
+ * the sweep silently won't fire for that fixture and Windows CI flakes
+ * return.
  */
 export async function createTempDir(prefix: string = 'gitnexus-test-'): Promise<TestDBHandle> {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
diff --git a/gitnexus/test/integration/cli/tool-no-index-stderr.test.ts b/gitnexus/test/integration/cli/tool-no-index-stderr.test.ts
new file mode 100644
index 0000000000..baf8178fd6
--- /dev/null
+++ b/gitnexus/test/integration/cli/tool-no-index-stderr.test.ts
@@ -0,0 +1,122 @@
+/**
+ * Regression test for the buffered-pino + hard-exit diagnostic-loss bug
+ * (Codex adversarial review on PR #1336, plan 002).
+ *
+ * Symptom before the fix: `gitnexus tool query <foo>` with no indexed
+ * repos exits non-zero with EMPTY stderr — the `logger.error()` call was
+ * routed through pino's `sync: false` SonicBoom buffer, and the
+ * subsequent synchronous `process.exit(1)` killed the process before the
+ * buffer could drain. Operators saw a silent failure.
+ *
+ * The fix routes user-facing CLI diagnostics through `cliError` (in
+ * `gitnexus/src/cli/cli-message.ts`), which writes plain text directly
+ * to `process.stderr` AND tees a structured pino record. Direct stderr
+ * writes don't go through the buffer, so they survive `process.exit`.
+ *
+ * This test spawns the built CLI in a child process and asserts the
+ * diagnostic line reaches stderr before exit. Without the fix it fails;
+ * with the fix it passes. Characterization-first contract, locked in
+ * end-to-end against `dist/`.
+ */
+import { describe, it, expect } from 'vitest';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const DIST_CLI = path.join(REPO_ROOT, 'dist', 'cli', 'index.js');
+
+const CHILD_TIMEOUT_MS = process.env.CI ? 20_000 : 10_000;
+
+interface ChildResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Spawn the built `gitnexus` CLI with arguments, wait for exit, and
+ * return captured streams + exit code. Pin GITNEXUS_HOME to a fresh
+ * empty temp dir so the LocalBackend init reliably finds zero indexed
+ * repos. Force NODE_OPTIONS empty to prevent host-environment overrides
+ * from changing buffer / heap behavior (plan 001 U3 added the buffered
+ * destination, which is what this test guards against).
+ */
+function runCli(args: string[]): Promise<ChildResult> {
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-cli-no-index-'));
+  return new Promise<ChildResult>((resolve, reject) => {
+    const proc = spawn(process.execPath, [DIST_CLI, ...args], {
+      cwd: REPO_ROOT,
+      env: {
+        ...process.env,
+        GITNEXUS_HOME: tmpHome,
+        NODE_OPTIONS: '',
+        // Force NDJSON path: pino-pretty only activates when stderr is a
+        // TTY and !CI && !VITEST. spawn() pipes stderr, so it's not a
+        // TTY in this child anyway, but the explicit env is defense-in-depth.
+        CI: '1',
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+
+    proc.stdout.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
+    proc.stderr.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
+
+    const timer = setTimeout(() => {
+      proc.kill('SIGKILL');
+      reject(new Error(`child process exceeded ${CHILD_TIMEOUT_MS}ms timeout`));
+    }, CHILD_TIMEOUT_MS);
+
+    proc.on('close', (code) => {
+      clearTimeout(timer);
+      // Best-effort cleanup of the empty temp home; ignore errors so they
+      // don't mask test failures.
+      try {
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+      resolve({
+        exitCode: code,
+        stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+        stderr: Buffer.concat(stderrChunks).toString('utf8'),
+      });
+    });
+    proc.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+describe('CLI tool query — diagnostic survives hard exit (plan 002)', () => {
+  it('emits the no-index diagnostic to stderr before exit code 1', async () => {
+    if (!fs.existsSync(DIST_CLI)) {
+      throw new Error(
+        `dist/cli/index.js missing — run \`npm run build\` first (or use \`npm run test:integration\` which builds via pretest:integration).`,
+      );
+    }
+
+    const result = await runCli(['query', 'whatever']);
+
+    // Without the plan-002 fix, stderr was empty. The diagnostic must be
+    // visible regardless of how `process.exit(1)` interacts with the
+    // buffered pino destination.
+    expect(result.stderr).toContain('No indexed repositories found');
+    expect(result.stderr).toContain('gitnexus analyze');
+
+    // Exit code stays 1 — we're only changing the message channel, not
+    // the failure semantics.
+    expect(result.exitCode).toBe(1);
+
+    // Stdout should not carry the diagnostic. CLI tool data is reserved
+    // for stdout (e.g., `gitnexus query | jq`); diagnostics are stderr.
+    expect(result.stdout).not.toContain('No indexed repositories found');
+  }, 30_000);
+});
diff --git a/gitnexus/test/integration/filesystem-walker.test.ts b/gitnexus/test/integration/filesystem-walker.test.ts
index accb24e374..2a1257ccc0 100644
--- a/gitnexus/test/integration/filesystem-walker.test.ts
+++ b/gitnexus/test/integration/filesystem-walker.test.ts
@@ -8,6 +8,7 @@ import {
 } from '../../src/core/ingestion/filesystem-walker.js';
 import { _resetMaxFileSizeWarnings } from '../../src/core/ingestion/utils/max-file-size.js';
 
+import { _captureLogger } from '../../src/core/logger.js';
 describe('filesystem-walker', () => {
   let tmpDir: string;
 
@@ -328,7 +329,7 @@ describe('filesystem-walker', () => {
     const BIG_FILE = 'src/big.ts';
     const BIG_FILE_BYTES = 600 * 1024;
     const ORIGINAL_ENV = process.env.GITNEXUS_MAX_FILE_SIZE;
-    let warnSpy: ReturnType<typeof vi.spyOn>;
+    let cap: ReturnType<typeof _captureLogger>;
 
     beforeAll(async () => {
       sizeDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-walker-size-test-'));
@@ -344,7 +345,7 @@ describe('filesystem-walker', () => {
     beforeEach(() => {
       delete process.env.GITNEXUS_MAX_FILE_SIZE;
       _resetMaxFileSizeWarnings();
-      warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      cap = _captureLogger();
     });
 
     afterEach(() => {
@@ -353,7 +354,7 @@ describe('filesystem-walker', () => {
       } else {
         process.env.GITNEXUS_MAX_FILE_SIZE = ORIGINAL_ENV;
       }
-      warnSpy.mockRestore();
+      cap.restore();
     });
 
     it('skips a 600KB file by default', async () => {
@@ -375,27 +376,27 @@ describe('filesystem-walker', () => {
       const files = await walkRepositoryPaths(sizeDir);
       const paths = files.map((f) => f.path.replace(/\\/g, '/'));
       expect(paths).not.toContain(BIG_FILE);
-      const invalidWarnings = warnSpy.mock.calls.filter((c) =>
-        String(c[0]).includes('must be a positive integer'),
-      );
+      const invalidWarnings = cap
+        .records()
+        .filter((r) => String(r.msg ?? '').includes('must be a positive integer'));
       expect(invalidWarnings).toHaveLength(1);
     });
 
     it('omits the "generated/vendored" suffix when threshold is overridden', async () => {
       process.env.GITNEXUS_MAX_FILE_SIZE = '1';
       await walkRepositoryPaths(sizeDir);
-      const skipWarnings = warnSpy.mock.calls.filter((c) => String(c[0]).includes('Skipped '));
+      const skipWarnings = cap.records().filter((r) => String(r.msg ?? '').includes('Skipped '));
       expect(skipWarnings.length).toBeGreaterThan(0);
-      for (const call of skipWarnings) {
-        expect(String(call[0])).not.toContain('generated/vendored');
+      for (const r of skipWarnings) {
+        expect(String(r.msg ?? '')).not.toContain('generated/vendored');
       }
     });
 
     it('keeps the "generated/vendored" suffix under the default threshold', async () => {
       await walkRepositoryPaths(sizeDir);
-      const skipWarnings = warnSpy.mock.calls.filter((c) => String(c[0]).includes('Skipped '));
+      const skipWarnings = cap.records().filter((r) => String(r.msg ?? '').includes('Skipped '));
       expect(skipWarnings.length).toBeGreaterThan(0);
-      expect(String(skipWarnings[0][0])).toContain('generated/vendored');
+      expect(String(skipWarnings[0].msg ?? '')).toContain('generated/vendored');
     });
   });
 });
diff --git a/gitnexus/test/integration/group/include-extractor-sync.test.ts b/gitnexus/test/integration/group/include-extractor-sync.test.ts
new file mode 100644
index 0000000000..908664bdc0
--- /dev/null
+++ b/gitnexus/test/integration/group/include-extractor-sync.test.ts
@@ -0,0 +1,195 @@
+/**
+ * Integration test: IncludeExtractor output → group matching → bridge DB.
+ *
+ * Covers PR #1156 review finding #7: verifies that the full runtime path
+ * (IncludeExtractor → StoredContract → runExactMatch → CrossLinks → writeBridge)
+ * stays wired up. A regression in either normalizeContractId or the include
+ * branch of ManifestExtractor.resolveSymbol would produce 0 cross-links and
+ * fail this test.
+ */
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { parseGroupConfig } from '../../../src/core/group/config-parser.js';
+import { syncGroup } from '../../../src/core/group/sync.js';
+import type { StoredContract } from '../../../src/core/group/types.js';
+import { IncludeExtractor } from '../../../src/core/group/extractors/include-extractor.js';
+import { normalizeContractId } from '../../../src/core/group/matching.js';
+
+const GROUP_YAML = [
+  'version: 1',
+  'name: include-test-group',
+  'description: "IncludeExtractor integration test"',
+  '',
+  'repos:',
+  '  app/provider: include-provider',
+  '  app/consumer: include-consumer',
+  '',
+  'links: []',
+  'packages: {}',
+  '',
+  'detect:',
+  '  http: false',
+  '  grpc: false',
+  '  topics: false',
+  '  shared_libs: false',
+  '  includes: true',
+  '  embedding_fallback: false',
+  '',
+  'matching:',
+  '  bm25_threshold: 0.7',
+  '  embedding_threshold: 0.65',
+  '  max_candidates_per_step: 3',
+].join('\n');
+
+describe('IncludeExtractor → syncGroup integration (finding #7)', () => {
+  it('produces a CrossLink when provider and consumer emit the same include contract-id', async () => {
+    const config = parseGroupConfig(GROUP_YAML);
+
+    // Mock the IncludeExtractor output directly — a header provider in one
+    // repo and a quoted #include consumer in the other, both normalized to
+    // the same include::map/base/view.h contract-id.
+    const mockContracts: StoredContract[] = [
+      {
+        contractId: 'include::map/base/view.h',
+        type: 'include',
+        role: 'provider',
+        symbolUid: 'File:map/base/view.h',
+        symbolRef: { filePath: 'map/base/view.h', name: 'view.h' },
+        symbolName: 'view.h',
+        confidence: 0.95,
+        meta: { source: 'filesystem' },
+        repo: 'app/provider',
+      },
+      {
+        contractId: 'include::map/base/view.h',
+        type: 'include',
+        role: 'consumer',
+        symbolUid: 'File:src/controller.cpp',
+        symbolRef: { filePath: 'src/controller.cpp', name: 'map/base/view.h' },
+        symbolName: 'map/base/view.h',
+        confidence: 0.85,
+        meta: { source: 'tree_sitter', includePath: 'map/base/view.h' },
+        repo: 'app/consumer',
+      },
+    ];
+
+    const result = await syncGroup(config, {
+      extractorOverride: async () => mockContracts,
+      skipWrite: true,
+    });
+
+    const includeLinks = result.crossLinks.filter((l) => l.type === 'include');
+    expect(includeLinks.length).toBeGreaterThanOrEqual(1);
+
+    const link = includeLinks[0];
+    expect(link.contractId).toBe('include::map/base/view.h');
+    expect(link.matchType).toBe('exact');
+    expect(link.from.repo).toBe('app/consumer');
+    expect(link.to.repo).toBe('app/provider');
+  });
+
+  it('normalizes mixed-case / backslash include paths to the same contract-id end-to-end', async () => {
+    const config = parseGroupConfig(GROUP_YAML);
+
+    // Provider writes the canonical form; consumer's include has mixed case
+    // and a backslash. After normalizeContractId they must still match.
+    const providerId = 'include::map/base/view.h';
+    const rawConsumerId = 'include::Map\\Base\\View.h';
+
+    // Sanity — normalizeContractId must collapse them.
+    expect(normalizeContractId(rawConsumerId)).toBe(providerId);
+
+    const mockContracts: StoredContract[] = [
+      {
+        contractId: providerId,
+        type: 'include',
+        role: 'provider',
+        symbolUid: 'File:map/base/view.h',
+        symbolRef: { filePath: 'map/base/view.h', name: 'view.h' },
+        symbolName: 'view.h',
+        confidence: 0.95,
+        meta: { source: 'filesystem' },
+        repo: 'app/provider',
+      },
+      {
+        contractId: rawConsumerId,
+        type: 'include',
+        role: 'consumer',
+        symbolUid: 'File:src/controller.cpp',
+        symbolRef: { filePath: 'src/controller.cpp', name: 'Map/Base/View.h' },
+        symbolName: 'Map/Base/View.h',
+        confidence: 0.85,
+        meta: { source: 'tree_sitter', includePath: 'Map\\Base\\View.h' },
+        repo: 'app/consumer',
+      },
+    ];
+
+    const result = await syncGroup(config, {
+      extractorOverride: async () => mockContracts,
+      skipWrite: true,
+    });
+
+    const includeLinks = result.crossLinks.filter((l) => l.type === 'include');
+    expect(includeLinks.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('round-trip: extractor output from two real temp repos produces matching contract-ids', async () => {
+    // Drives the extractor directly (no `syncGroup`) against two on-disk
+    // fixture repos, then hands the StoredContract-shaped output to
+    // syncGroup via extractorOverride. This exercises the real extraction
+    // code + the matching pipeline together.
+    const providerDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-include-int-provider-'));
+    const consumerDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-include-int-consumer-'));
+    try {
+      fs.mkdirSync(path.join(providerDir, 'shared/api'), { recursive: true });
+      fs.writeFileSync(
+        path.join(providerDir, 'shared/api/client.h'),
+        '#pragma once\nstruct Client {};',
+      );
+      fs.mkdirSync(path.join(consumerDir, 'src'), { recursive: true });
+      fs.writeFileSync(
+        path.join(consumerDir, 'src/main.cpp'),
+        '#include "shared/api/client.h"\nint main(){return 0;}',
+      );
+
+      const extractor = new IncludeExtractor();
+      const providerOutput = await extractor.extract(null, providerDir, {
+        id: 'provider',
+        path: 'app/provider',
+        repoPath: providerDir,
+        storagePath: path.join(providerDir, '.gitnexus'),
+      });
+      const consumerOutput = await extractor.extract(null, consumerDir, {
+        id: 'consumer',
+        path: 'app/consumer',
+        repoPath: consumerDir,
+        storagePath: path.join(consumerDir, '.gitnexus'),
+      });
+
+      const stored: StoredContract[] = [
+        ...providerOutput
+          .filter((c) => c.role === 'provider')
+          .map((c) => ({ ...c, repo: 'app/provider' })),
+        ...consumerOutput
+          .filter((c) => c.role === 'consumer')
+          .map((c) => ({ ...c, repo: 'app/consumer' })),
+      ];
+
+      const config = parseGroupConfig(GROUP_YAML);
+      const result = await syncGroup(config, {
+        extractorOverride: async () => stored,
+        skipWrite: true,
+      });
+
+      const includeLinks = result.crossLinks.filter((l) => l.type === 'include');
+      expect(includeLinks.length).toBeGreaterThanOrEqual(1);
+      expect(includeLinks[0].contractId).toBe('include::shared/api/client.h');
+      expect(includeLinks[0].matchType).toBe('exact');
+    } finally {
+      fs.rmSync(providerDir, { recursive: true, force: true });
+      fs.rmSync(consumerDir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/gitnexus/test/integration/lbug-close-handle-release.test.ts b/gitnexus/test/integration/lbug-close-handle-release.test.ts
new file mode 100644
index 0000000000..c0a3b87580
--- /dev/null
+++ b/gitnexus/test/integration/lbug-close-handle-release.test.ts
@@ -0,0 +1,41 @@
+/**
+ * Integration test: safeClose's Windows post-close handle-release wait.
+ *
+ * On Windows, libuv reports `db.close()` resolved before the kernel has
+ * released the file handle. A subsequent open of the same path can then
+ * race the release and surface "Could not set lock on file". `safeClose`
+ * probes the file with `fs.open` to force the residual lock to surface,
+ * absorbed by the open-time retry in `lbug-config.ts`.
+ */
+import path from 'path';
+import { describe, it } from 'vitest';
+import { createTempDir } from '../helpers/test-db.js';
+
+describe('safeClose — close + reopen does not surface lock errors', () => {
+  it('survives 10 sequential open/close/reopen cycles on the same path', async () => {
+    const tmp = await createTempDir('gitnexus-lbug-close-cycle-');
+    const dbPath = path.join(tmp.dbPath, 'lbug');
+    try {
+      const adapter = await import('../../src/core/lbug/lbug-adapter.js');
+      for (let i = 0; i < 10; i++) {
+        await adapter.initLbug(dbPath);
+        await adapter.closeLbug();
+      }
+    } finally {
+      await tmp.cleanup();
+    }
+  });
+
+  it('safeClose is idempotent — calling twice in a row does not throw', async () => {
+    const tmp = await createTempDir('gitnexus-lbug-idempotent-');
+    const dbPath = path.join(tmp.dbPath, 'lbug');
+    try {
+      const adapter = await import('../../src/core/lbug/lbug-adapter.js');
+      await adapter.initLbug(dbPath);
+      await adapter.closeLbug();
+      await adapter.closeLbug();
+    } finally {
+      await tmp.cleanup();
+    }
+  });
+});
diff --git a/gitnexus/test/integration/lbug-lock-retry.test.ts b/gitnexus/test/integration/lbug-lock-retry.test.ts
index 1279c77fbe..b95092e2d8 100644
--- a/gitnexus/test/integration/lbug-lock-retry.test.ts
+++ b/gitnexus/test/integration/lbug-lock-retry.test.ts
@@ -14,7 +14,7 @@ import { withTestLbugDB } from '../helpers/test-indexed-db.js';
 
 // Pure-function tests — no DB needed, but grouped here for cohesion
 // with the retry logic they guard.
-import { isDbBusyError } from '../../src/core/lbug/lbug-adapter.js';
+import { isDbBusyError } from '../../src/core/lbug/lbug-config.js';
 
 describe('isDbBusyError', () => {
   it('returns true for "busy" errors (case-insensitive)', () => {
@@ -46,6 +46,18 @@ describe('isDbBusyError', () => {
     expect(isDbBusyError(undefined)).toBe(false);
   });
 
+  // Documented behavior for lock-shaped strings: the matcher is intentionally
+  // broad because in graph-DB contexts these are all transient. If LadybugDB
+  // ever surfaces a non-transient lock-shaped error (e.g., a recovery-time
+  // "lock file missing"), tighten the matcher and add a negative test here
+  // rather than raising the retry budget.
+  it('treats other lock-shaped errors as transient (current intentional behavior)', () => {
+    expect(isDbBusyError(new Error('deadlock detected'))).toBe(true);
+    expect(isDbBusyError(new Error('unlock failed'))).toBe(true);
+    expect(isDbBusyError(new Error('lock contention'))).toBe(true);
+    expect(isDbBusyError(new Error('Could not open lock file'))).toBe(true);
+  });
+
   it('handles non-Error values gracefully', () => {
     expect(isDbBusyError('BUSY error')).toBe(true);
     expect(isDbBusyError(42)).toBe(false);
diff --git a/gitnexus/test/integration/lbug-open-retry.test.ts b/gitnexus/test/integration/lbug-open-retry.test.ts
new file mode 100644
index 0000000000..80e68617d1
--- /dev/null
+++ b/gitnexus/test/integration/lbug-open-retry.test.ts
@@ -0,0 +1,310 @@
+/**
+ * Integration tests: open-time lock-busy retry in `lbug-config.ts`.
+ *
+ * The lock IO exception raised by `local_file_system.cpp` happens
+ * synchronously inside `new lbug.Database(...)`, before any query is
+ * issued — so `withLbugDb`'s query-time retry cannot see it. These tests
+ * exercise the construction-time retry wrapper directly by stubbing the
+ * `Database` constructor.
+ *
+ * See: docs/plans/2026-05-08-002-fix-windows-lbug-lock-ci-flakes-plan.md
+ */
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  _isTestFixturePathForTest as isTestFixturePath,
+  isDbBusyError,
+  isOpenRetryExhausted,
+  openLbugConnection,
+  waitForWindowsHandleRelease,
+} from '../../src/core/lbug/lbug-config.js';
+
+// ─── Minimal stub of the `lbug` module surface used by openLbugConnection ──
+
+interface StubModuleControl {
+  /** Errors thrown by sequential `new Database(...)` calls. `null` = success. */
+  databaseThrows: Array<Error | null>;
+  /** Number of times the `Database` constructor was invoked. */
+  databaseCallCount: number;
+  /** Number of times `db.close()` was called. */
+  closeCallCount: number;
+}
+
+const makeStubLbug = (control: StubModuleControl) => {
+  class FakeDatabase {
+    constructor(_path: string, ..._rest: unknown[]) {
+      control.databaseCallCount++;
+      const next = control.databaseThrows.shift();
+      if (next instanceof Error) throw next;
+    }
+    async close(): Promise<void> {
+      control.closeCallCount++;
+    }
+  }
+  class FakeConnection {
+    constructor(_db: FakeDatabase) {}
+    async close(): Promise<void> {}
+  }
+  return { Database: FakeDatabase, Connection: FakeConnection } as any;
+};
+
+describe('isDbBusyError', () => {
+  it('matches the documented Windows lock-error wording', () => {
+    expect(isDbBusyError(new Error('Could not set lock on file foo.lbug'))).toBe(true);
+    expect(isDbBusyError(new Error('database is locked'))).toBe(true);
+  });
+  it('does not match unrelated errors', () => {
+    expect(isDbBusyError(new Error('Cypher syntax error'))).toBe(false);
+    expect(isDbBusyError(null)).toBe(false);
+  });
+});
+
+describe('openLbugConnection — open-time lock-busy retry', () => {
+  it('returns a handle when the constructor succeeds on the first try', async () => {
+    const control: StubModuleControl = {
+      databaseThrows: [null],
+      databaseCallCount: 0,
+      closeCallCount: 0,
+    };
+    const stub = makeStubLbug(control);
+    const handle = await openLbugConnection(stub, '/some/path/lbug');
+    expect(handle.db).toBeDefined();
+    expect(handle.conn).toBeDefined();
+    expect(control.databaseCallCount).toBe(1);
+  });
+
+  it('retries on busy/lock errors and succeeds on a later attempt', async () => {
+    const control: StubModuleControl = {
+      databaseThrows: [new Error('Could not set lock on file'), null],
+      databaseCallCount: 0,
+      closeCallCount: 0,
+    };
+    const stub = makeStubLbug(control);
+    const handle = await openLbugConnection(stub, '/some/path/lbug');
+    expect(handle.db).toBeDefined();
+    expect(control.databaseCallCount).toBe(2);
+  });
+
+  it('exhausts the retry budget and rethrows the last error preserving its message', async () => {
+    const lockErr = new Error('Could not set lock on file foo.lbug');
+    const control: StubModuleControl = {
+      // 5 attempts + production paths get no sweep retry, so 5 throws total.
+      databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr],
+      databaseCallCount: 0,
+      closeCallCount: 0,
+    };
+    const stub = makeStubLbug(control);
+    await expect(openLbugConnection(stub, '/var/data/non-test/lbug')).rejects.toThrow(
+      'Could not set lock on file foo.lbug',
+    );
+    expect(control.databaseCallCount).toBe(5);
+  });
+
+  it('tags the exhausted error so withLbugDb skips its outer retry', async () => {
+    const lockErr = new Error('Could not set lock on file');
+    const control: StubModuleControl = {
+      databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr],
+      databaseCallCount: 0,
+      closeCallCount: 0,
+    };
+    const stub = makeStubLbug(control);
+    let caught: unknown;
+    try {
+      await openLbugConnection(stub, '/var/data/non-test/lbug');
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeDefined();
+    expect(isOpenRetryExhausted(caught)).toBe(true);
+    expect(isOpenRetryExhausted(new Error('plain error'))).toBe(false);
+    expect(isOpenRetryExhausted(null)).toBe(false);
+    expect(isOpenRetryExhausted(undefined)).toBe(false);
+  });
+
+  it('does not retry non-busy errors', async () => {
+    const syntaxErr = new Error('Cypher syntax error');
+    const control: StubModuleControl = {
+      databaseThrows: [syntaxErr],
+      databaseCallCount: 0,
+      closeCallCount: 0,
+    };
+    const stub = makeStubLbug(control);
+    await expect(openLbugConnection(stub, '/some/path/lbug')).rejects.toThrow(
+      'Cypher syntax error',
+    );
+    expect(control.databaseCallCount).toBe(1);
+  });
+});
+
+describe('openLbugConnection — stale-sidecar sweep (test fixtures only)', () => {
+  let fixtureDir: string;
+  let dbPath: string;
+
+  beforeEach(async () => {
+    fixtureDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-lbug-sweep-'));
+    dbPath = path.join(fixtureDir, 'lbug');
+  });
+
+  afterEach(async () => {
+    await fs.rm(fixtureDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('sweeps stale .wal/.lock for a recognized test fixture path and retries once', async () => {
+    await fs.writeFile(dbPath + '.wal', 'stale');
+    await fs.writeFile(dbPath + '.lock', 'stale');
+
+    const lockErr = new Error('Could not set lock on file');
+    const control: StubModuleControl = {
+      // 5 retries throw, then sweep + 1 final attempt succeeds (6 total).
+      databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr, null],
+      databaseCallCount: 0,
+      closeCallCount: 0,
+    };
+    const stub = makeStubLbug(control);
+
+    const handle = await openLbugConnection(stub, dbPath);
+    expect(handle.db).toBeDefined();
+    expect(control.databaseCallCount).toBe(6);
+
+    // Sidecars removed by the sweep
+    await expect(fs.access(dbPath + '.wal')).rejects.toThrow();
+    await expect(fs.access(dbPath + '.lock')).rejects.toThrow();
+  });
+
+  it('does not sweep production paths even if they share the prefix', async () => {
+    // A non-tmp dir that *starts* with the prefix must still be rejected.
+    const lockErr = new Error('Could not set lock on file');
+    const control: StubModuleControl = {
+      databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr],
+      databaseCallCount: 0,
+      closeCallCount: 0,
+    };
+    const stub = makeStubLbug(control);
+
+    // Path is outside os.tmpdir() so the predicate must reject it.
+    await expect(openLbugConnection(stub, '/var/data/gitnexus-lbug-fake/lbug')).rejects.toThrow(
+      'Could not set lock on file',
+    );
+    expect(control.databaseCallCount).toBe(5); // no sweep retry
+  });
+
+  it('handles missing sidecars gracefully (ENOENT swallowed, retry runs)', async () => {
+    // No .wal or .lock pre-created — sweep ENOENTs both, then succeeds.
+    const lockErr = new Error('Could not set lock on file');
+    const control: StubModuleControl = {
+      databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr, null],
+      databaseCallCount: 0,
+      closeCallCount: 0,
+    };
+    const stub = makeStubLbug(control);
+
+    const handle = await openLbugConnection(stub, dbPath);
+    expect(handle.db).toBeDefined();
+    expect(control.databaseCallCount).toBe(6);
+  });
+
+  it('sweep retry that throws a different error preserves the original lock error', async () => {
+    // 5 lock errors, then sweep fires, then post-sweep throws an unrelated
+    // error. The user-actionable signal is "lock retries exhausted" — the
+    // post-sweep error must NOT shadow the original lock message.
+    const lockErr = new Error('Could not set lock on file foo.lbug');
+    const unrelatedErr = new Error('Schema validation error during open');
+    const control: StubModuleControl = {
+      databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr, unrelatedErr],
+      databaseCallCount: 0,
+      closeCallCount: 0,
+    };
+    const stub = makeStubLbug(control);
+
+    let caught: Error | undefined;
+    try {
+      await openLbugConnection(stub, dbPath);
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught?.message).toBe('Could not set lock on file foo.lbug');
+    expect(control.databaseCallCount).toBe(6); // sweep retry did fire
+  });
+});
+
+describe('isTestFixturePath — production-safety guard', () => {
+  it('accepts a fixture under os.tmpdir with a recognized prefix on the immediate parent', () => {
+    const tmp = os.tmpdir();
+    expect(isTestFixturePath(path.join(tmp, 'gitnexus-lbug-XXX', 'lbug'))).toBe(true);
+    expect(isTestFixturePath(path.join(tmp, 'gitnexus-test-YYY', 'lbug'))).toBe(true);
+  });
+
+  it('rejects production paths even with a matching prefix', () => {
+    expect(isTestFixturePath('/var/data/gitnexus-lbug-fake/lbug')).toBe(false);
+    expect(isTestFixturePath('/home/user/gitnexus-test-foo/lbug')).toBe(false);
+  });
+
+  it('rejects path traversal attempts that resolve outside tmpdir', () => {
+    const tmp = os.tmpdir();
+    const traversal = path.join(tmp, 'gitnexus-lbug-x', '..', '..', 'etc', 'passwd');
+    expect(isTestFixturePath(traversal)).toBe(false);
+  });
+
+  it('rejects when the immediate parent does not match even if a deeper ancestor does', () => {
+    // Tightening: ancestor walk would have allowed nested paths under
+    // `<tmp>/gitnexus-lbug-x/inner/lbug` to satisfy the predicate. We
+    // require the immediate parent to match.
+    const tmp = os.tmpdir();
+    expect(isTestFixturePath(path.join(tmp, 'gitnexus-lbug-x', 'inner', 'lbug'))).toBe(false);
+  });
+
+  it('handles tmpdir trailing-separator gracefully', () => {
+    // Some Windows TMP configs return a trailing separator; the predicate
+    // strips it before the prefix check so fixtures still match.
+    const tmp = os.tmpdir();
+    const fixture = path.join(tmp, 'gitnexus-lbug-trailing', 'lbug');
+    // Whether or not os.tmpdir() itself has a trailing separator,
+    // the predicate must accept legit fixtures.
+    expect(isTestFixturePath(fixture)).toBe(true);
+  });
+
+  it('rejects unrelated prefixes in tmpdir', () => {
+    const tmp = os.tmpdir();
+    expect(isTestFixturePath(path.join(tmp, 'random-dir', 'lbug'))).toBe(false);
+    expect(isTestFixturePath(path.join(tmp, 'malicious', 'lbug'))).toBe(false);
+  });
+});
+
+describe('waitForWindowsHandleRelease', () => {
+  let fixtureDir: string;
+  let dbPath: string;
+
+  beforeEach(async () => {
+    fixtureDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-lbug-probe-'));
+    dbPath = path.join(fixtureDir, 'lbug');
+  });
+
+  afterEach(async () => {
+    await fs.rm(fixtureDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('returns true when the file exists and is openable', async () => {
+    await fs.writeFile(dbPath, 'fake-db-content');
+    const released = await waitForWindowsHandleRelease(dbPath);
+    expect(released).toBe(true);
+  });
+
+  it('returns true when the file does not exist (ENOENT is non-lock)', async () => {
+    // No fs.writeFile — path does not exist. Probe should bail to true,
+    // not retry, since ENOENT is not a lock code.
+    const released = await waitForWindowsHandleRelease(dbPath);
+    expect(released).toBe(true);
+  });
+
+  it('does not leak the file handle when close succeeds', async () => {
+    // Smoke test: 50 sequential probes with a real file. If close were
+    // skipped, fd usage would climb. We rely on test process not OOMing
+    // as the simplest indicator; fd table caps catch egregious leaks.
+    await fs.writeFile(dbPath, 'fake-db-content');
+    for (let i = 0; i < 50; i++) {
+      await waitForWindowsHandleRelease(dbPath);
+    }
+  });
+});
diff --git a/gitnexus/test/integration/setup-skills.test.ts b/gitnexus/test/integration/setup-skills.test.ts
index 339820ba56..defe6771c4 100644
--- a/gitnexus/test/integration/setup-skills.test.ts
+++ b/gitnexus/test/integration/setup-skills.test.ts
@@ -52,6 +52,21 @@ describe('setupCommand skills integration', () => {
     await fs.rm(tempHome, { recursive: true, force: true });
   });
 
+  it('reports the OpenCode skills install path with the plural skills directory', async () => {
+    await fs.mkdir(path.join(tempHome, '.config', 'opencode'), { recursive: true });
+    await setupCommand();
+
+    const installedSkill = await fs.readFile(
+      path.join(tempHome, '.config', 'opencode', 'skills', 'gitnexus-cli', 'SKILL.md'),
+      'utf-8',
+    );
+
+    expect(installedSkill).toContain('GitNexus CLI Commands');
+    await expect(
+      fs.access(path.join(tempHome, '.config', 'opencode', 'skill', 'gitnexus-cli', 'SKILL.md')),
+    ).rejects.toThrow();
+  });
+
   it('installs packaged, flat-file, and directory skills into cursor skills directory', async () => {
     await setupCommand();
 
diff --git a/gitnexus/test/integration/worker-pool.test.ts b/gitnexus/test/integration/worker-pool.test.ts
index b6e3a023cb..845c1cfbab 100644
--- a/gitnexus/test/integration/worker-pool.test.ts
+++ b/gitnexus/test/integration/worker-pool.test.ts
@@ -6,13 +6,14 @@
  * This is critical for cross-platform CI where vitest runs from src/
  * but workers need compiled .js files.
  */
-import { describe, it, expect, afterEach, vi } from 'vitest';
+import { describe, it, expect, afterEach } from 'vitest';
 import { createWorkerPool, WorkerPool } from '../../src/core/ingestion/workers/worker-pool.js';
 import { pathToFileURL } from 'node:url';
 import path from 'node:path';
 import fs from 'node:fs';
 import os from 'node:os';
 
+import { _captureLogger } from '../../src/core/logger.js';
 const DIST_WORKER = path.resolve(
   __dirname,
   '..',
@@ -211,7 +212,7 @@ describe('worker pool integration', () => {
     `,
     );
 
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const cap = _captureLogger();
     const workerUrl = pathToFileURL(workerPath) as URL;
     pool = createWorkerPool(workerUrl, 1);
 
@@ -221,9 +222,9 @@ describe('worker pool integration', () => {
       ]);
       expect(results).toHaveLength(1);
       expect(results[0].fileCount).toBe(1);
-      expect(warnSpy).toHaveBeenCalledWith('warning before result');
+      expect(cap.records().some((r) => r.msg === 'warning before result')).toBe(true);
     } finally {
-      warnSpy.mockRestore();
+      cap.restore();
       fs.rmSync(tempDir, { recursive: true, force: true });
     }
   });
@@ -298,7 +299,7 @@ describe('worker pool integration', () => {
     `,
     );
 
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const cap = _captureLogger();
     pool = createWorkerPool(pathToFileURL(workerPath) as URL, 1, {
       subBatchIdleTimeoutMs: 500,
       maxTimeoutRetries: 1,
@@ -308,9 +309,12 @@ describe('worker pool integration', () => {
     try {
       const results = await pool.dispatch<any, any>([{ path: 'retry.ts', content: '' }]);
       expect(results).toEqual([{ fileCount: 1, recovered: true }]);
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Retrying with 2s timeout'));
+      // 500ms idle timeout × 4 backoff factor = 2000ms = "2s" in the retry log.
+      expect(
+        cap.records().some((r) => String(r.msg ?? '').includes('Retrying with 2s timeout')),
+      ).toBe(true);
     } finally {
-      warnSpy.mockRestore();
+      cap.restore();
       fs.rmSync(tempDir, { recursive: true, force: true });
     }
   });
@@ -337,7 +341,11 @@ describe('worker pool integration', () => {
     `,
     );
 
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    // Capture pino output AND assert on it: the worker pool should emit a
+    // warn-level record naming the crash before rejecting, so an operator
+    // can tell a startup-crash from a stalled-worker rejection. Asserting
+    // here keeps coverage parity with the prior console.warn spy version.
+    const cap = _captureLogger();
     pool = createWorkerPool(pathToFileURL(workerPath) as URL, 1, {
       subBatchIdleTimeoutMs: 150,
       maxTimeoutRetries: 1,
@@ -348,8 +356,10 @@ describe('worker pool integration', () => {
       await expect(pool.dispatch<any, any>([{ path: 'crash.ts', content: '' }])).rejects.toThrow(
         /simulated startup crash|exited with code/,
       );
+      const warnRecords = cap.records().filter((r) => Number(r.level) >= 40 /* warn or above */);
+      expect(warnRecords.length).toBeGreaterThan(0);
     } finally {
-      warnSpy.mockRestore();
+      cap.restore();
       fs.rmSync(tempDir, { recursive: true, force: true });
     }
   });
@@ -383,7 +393,7 @@ describe('worker pool integration', () => {
     `,
     );
 
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const cap = _captureLogger();
     pool = createWorkerPool(pathToFileURL(workerPath) as URL, 1, {
       subBatchSize: 2,
       subBatchIdleTimeoutMs: 150,
@@ -411,9 +421,11 @@ describe('worker pool integration', () => {
       ]);
       expect(progressCalls).toEqual([...progressCalls].sort((a, b) => a - b));
       expect(progressCalls.at(-1)).toBe(4);
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Splitting into 1/1 item jobs'));
+      expect(
+        cap.records().some((r) => String(r.msg ?? '').includes('Splitting into 1/1 item jobs')),
+      ).toBe(true);
     } finally {
-      warnSpy.mockRestore();
+      cap.restore();
       fs.rmSync(tempDir, { recursive: true, force: true });
     }
   });
@@ -479,7 +491,7 @@ describe('worker pool integration', () => {
     `,
     );
 
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const cap = _captureLogger();
     pool = createWorkerPool(pathToFileURL(workerPath) as URL, 2, {
       subBatchSize: 2,
       subBatchIdleTimeoutMs: 150,
@@ -505,9 +517,11 @@ describe('worker pool integration', () => {
         'tail-a.ts',
         'tail-b.ts',
       ]);
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Splitting into 1/1 item jobs'));
+      expect(
+        cap.records().some((r) => String(r.msg ?? '').includes('Splitting into 1/1 item jobs')),
+      ).toBe(true);
     } finally {
-      warnSpy.mockRestore();
+      cap.restore();
       fs.rmSync(tempDir, { recursive: true, force: true });
     }
   });
@@ -543,7 +557,7 @@ describe('worker pool integration', () => {
     `,
     );
 
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const cap = _captureLogger();
     // 2 workers but subBatchSize=4 means all 4 items form 1 job; second worker stays idle.
     pool = createWorkerPool(pathToFileURL(workerPath) as URL, 2, {
       subBatchSize: 4,
@@ -562,9 +576,9 @@ describe('worker pool integration', () => {
 
       const allPaths = results.flatMap((r: any) => r.paths);
       expect(allPaths.sort()).toEqual(['a.ts', 'b.ts', 'c.ts', 'd.ts']);
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Splitting into'));
+      expect(cap.records().some((r) => String(r.msg ?? '').includes('Splitting into'))).toBe(true);
     } finally {
-      warnSpy.mockRestore();
+      cap.restore();
       fs.rmSync(tempDir, { recursive: true, force: true });
     }
   }, 15_000);
diff --git a/gitnexus/test/unit/analyze-embeddings-limit.test.ts b/gitnexus/test/unit/analyze-embeddings-limit.test.ts
index 93978ad9d0..6fbc5af569 100644
--- a/gitnexus/test/unit/analyze-embeddings-limit.test.ts
+++ b/gitnexus/test/unit/analyze-embeddings-limit.test.ts
@@ -44,17 +44,23 @@ describe('analyzeCommand --embeddings [limit] parsing', () => {
   it.each(['abc', '-1', '1.5', 'NaN', 'Infinity'])(
     'rejects invalid --embeddings value %s before analysis starts',
     async (embeddings) => {
-      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+      // The validator routes through cli-message (`cliError`), which
+      // writes plain text directly to process.stderr. Spy on the raw
+      // stderr handle rather than `console.error`, since the migration
+      // bypasses console entirely.
+      const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
       const { analyzeCommand } = await import('../../src/cli/analyze.js');
 
       await analyzeCommand(undefined, { embeddings });
 
       expect(process.exitCode).toBe(1);
       expect(runFullAnalysisMock).not.toHaveBeenCalled();
-      const msg = errorSpy.mock.calls[0]?.[0] ?? '';
-      expect(msg).toContain('--embeddings expects a non-negative integer');
-      expect(msg).toContain(`got "${embeddings}"`);
-      errorSpy.mockRestore();
+      const allWrites = stderrSpy.mock.calls
+        .map(([chunk]) => (typeof chunk === 'string' ? chunk : chunk.toString()))
+        .join('');
+      expect(allWrites).toContain('--embeddings expects a non-negative integer');
+      expect(allWrites).toContain(`got "${embeddings}"`);
+      stderrSpy.mockRestore();
     },
   );
 
diff --git a/gitnexus/test/unit/analyze-worker-timeout.test.ts b/gitnexus/test/unit/analyze-worker-timeout.test.ts
index dcf5a9dce4..3ed3a3d5ed 100644
--- a/gitnexus/test/unit/analyze-worker-timeout.test.ts
+++ b/gitnexus/test/unit/analyze-worker-timeout.test.ts
@@ -39,15 +39,20 @@ describe('analyzeCommand worker timeout validation', () => {
   it.each(['0', 'abc', '-5', 'Infinity'])(
     'rejects invalid --worker-timeout value %s before analysis starts',
     async (workerTimeout) => {
-      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+      // Import _captureLogger from the SAME module instance analyze.js will
+      // see — vi.resetModules() in beforeEach invalidates the singleton.
+      const { _captureLogger } = await import('../../src/core/logger.js');
+      const cap = _captureLogger();
       const { analyzeCommand } = await import('../../src/cli/analyze.js');
 
       await analyzeCommand(undefined, { workerTimeout });
 
       expect(process.exitCode).toBe(1);
-      expect(errorSpy).toHaveBeenCalledWith('  --worker-timeout must be at least 1 second.\n');
+      expect(
+        cap.records().some((r) => r.msg === '  --worker-timeout must be at least 1 second.\n'),
+      ).toBe(true);
       expect(runFullAnalysisMock).not.toHaveBeenCalled();
-      errorSpy.mockRestore();
+      cap.restore();
     },
   );
 
diff --git a/gitnexus/test/unit/calltool-dispatch.test.ts b/gitnexus/test/unit/calltool-dispatch.test.ts
index aa422327be..6b13cacfa0 100644
--- a/gitnexus/test/unit/calltool-dispatch.test.ts
+++ b/gitnexus/test/unit/calltool-dispatch.test.ts
@@ -48,6 +48,7 @@ vi.mock('../../src/storage/repo-manager.js', () => ({
 // tests don't shell out to git.
 vi.mock('../../src/core/git-staleness.js', () => ({
   checkStaleness: vi.fn().mockReturnValue({ isStale: false, commitsBehind: 0 }),
+  checkStalenessAsync: vi.fn().mockResolvedValue({ isStale: false, commitsBehind: 0 }),
   checkCwdMatch: vi.fn().mockResolvedValue({ match: 'none' }),
 }));
 
@@ -71,6 +72,7 @@ vi.mock('../../src/mcp/core/embedder.js', () => ({
 
 import { LocalBackend } from '../../src/mcp/local/local-backend.js';
 import { listRegisteredRepos, cleanupOldKuzuFiles } from '../../src/storage/repo-manager.js';
+import { _captureLogger } from '../../src/core/logger.js';
 import {
   initLbug,
   executeQuery,
@@ -194,7 +196,7 @@ describe('LocalBackend.callTool', () => {
   });
 
   it('skips vector index query when VECTOR is unsupported by the platform', async () => {
-    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const cap = _captureLogger();
     platformMocks.isVectorExtensionSupportedByPlatform.mockReturnValue(false);
     (executeQuery as any).mockImplementation(async (_repoId: string, cypher: string) => {
       if (cypher.includes('COUNT(*) AS cnt')) return [{ cnt: 1 }];
@@ -217,13 +219,17 @@ describe('LocalBackend.callTool', () => {
             cypher.includes('e.embedding AS embedding'),
         ),
       ).toBe(true);
-      expect(consoleError).toHaveBeenCalledWith(
-        expect.stringContaining(
-          'GitNexus [query:vector]: VECTOR extension not supported on this platform',
-        ),
-      );
+      expect(
+        cap
+          .records()
+          .some((r) =>
+            String(r.msg ?? '').includes(
+              'GitNexus [query:vector]: VECTOR extension not supported on this platform',
+            ),
+          ),
+      ).toBe(true);
     } finally {
-      consoleError.mockRestore();
+      cap.restore();
     }
   });
 
@@ -835,7 +841,7 @@ describe('LocalBackend.resolveRepo', () => {
       hint: '⚠️ stale sibling clone',
     });
 
-    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const cap = _captureLogger();
     try {
       await backend.init();
 
@@ -846,13 +852,15 @@ describe('LocalBackend.resolveRepo', () => {
       await backend.resolveRepo();
       await backend.resolveRepo();
 
-      const drift = errSpy.mock.calls.filter((c) => String(c[0]).includes('stale sibling clone'));
+      const drift = cap
+        .records()
+        .filter((r) => String(r.msg ?? '').includes('stale sibling clone'));
       expect(drift).toHaveLength(1);
       // checkCwdMatch should also only run once — the cache check
       // happens BEFORE the shellout-heavy match call.
       expect(checkCwdMatch).toHaveBeenCalledTimes(1);
     } finally {
-      errSpy.mockRestore();
+      cap.restore();
       (checkCwdMatch as any).mockResolvedValue({ match: 'none' });
     }
   });
diff --git a/gitnexus/test/unit/cli-message.test.ts b/gitnexus/test/unit/cli-message.test.ts
new file mode 100644
index 0000000000..321485c378
--- /dev/null
+++ b/gitnexus/test/unit/cli-message.test.ts
@@ -0,0 +1,99 @@
+/**
+ * Unit tests for `gitnexus/src/cli/cli-message.ts`.
+ *
+ * cli-message is the helper for user-facing CLI banners and error guidance.
+ * The contract: each call writes plain text to stderr AND emits a
+ * structured pino record through the singleton logger.
+ *
+ * Tests verify both halves of the tee, plus shape contracts (newline
+ * handling, structured fields, tee survival across messages with
+ * embedded newlines).
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { cliInfo, cliWarn, cliError } from '../../src/cli/cli-message.js';
+import { _captureLogger, type LoggerCapture } from '../../src/core/logger.js';
+
+describe('cli-message — stderr + logger tee', () => {
+  let cap: LoggerCapture;
+  let stderrSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    cap = _captureLogger();
+    stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    stderrSpy.mockRestore();
+    cap.restore();
+  });
+
+  it('cliInfo writes plain text to stderr and emits a structured info record', () => {
+    cliInfo('hello');
+    // Plain stderr write
+    const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
+      typeof chunk === 'string' ? chunk : chunk.toString(),
+    );
+    expect(stderrCalls).toContain('hello\n');
+    // Structured logger record
+    const records = cap.records();
+    expect(records.some((r) => r.msg === 'hello' && r.level === 30)).toBe(true);
+  });
+
+  it('cliWarn writes to stderr and emits at warn level (40)', () => {
+    cliWarn('caution');
+    const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
+      typeof chunk === 'string' ? chunk : chunk.toString(),
+    );
+    expect(stderrCalls).toContain('caution\n');
+    const records = cap.records();
+    expect(records.some((r) => r.msg === 'caution' && r.level === 40)).toBe(true);
+  });
+
+  it('cliError writes to stderr and emits at error level (50) with structured fields', () => {
+    cliError('boom', { code: 'EADDRINUSE', port: 4747 });
+    const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
+      typeof chunk === 'string' ? chunk : chunk.toString(),
+    );
+    expect(stderrCalls).toContain('boom\n');
+    const records = cap.records();
+    const errorRecord = records.find((r) => r.msg === 'boom' && r.level === 50);
+    expect(errorRecord).toBeDefined();
+    expect(errorRecord?.code).toBe('EADDRINUSE');
+    expect(errorRecord?.port).toBe(4747);
+  });
+
+  it('does not double-newline an already-newlined message', () => {
+    cliInfo('already-terminated\n');
+    const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
+      typeof chunk === 'string' ? chunk : chunk.toString(),
+    );
+    // Exactly one trailing \n, not two.
+    expect(stderrCalls).toContain('already-terminated\n');
+    expect(stderrCalls.includes('already-terminated\n\n')).toBe(false);
+  });
+
+  it('preserves embedded newlines in multi-line messages (does not split into multiple records)', () => {
+    cliError('line one\nline two\nline three');
+    const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
+      typeof chunk === 'string' ? chunk : chunk.toString(),
+    );
+    // The whole multi-line block goes to stderr in one write, with a
+    // trailing newline appended.
+    expect(stderrCalls).toContain('line one\nline two\nline three\n');
+    // The structured record carries the full message as a single field.
+    const records = cap.records();
+    expect(records.some((r) => r.msg === 'line one\nline two\nline three' && r.level === 50)).toBe(
+      true,
+    );
+  });
+
+  it('handles an empty message — stderr gets a bare newline, logger gets msg:""', () => {
+    cliInfo('');
+    const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
+      typeof chunk === 'string' ? chunk : chunk.toString(),
+    );
+    expect(stderrCalls).toContain('\n');
+    const records = cap.records();
+    expect(records.some((r) => r.msg === '' && r.level === 30)).toBe(true);
+  });
+});
diff --git a/gitnexus/test/unit/group/bridge-storage-tempfile.test.ts b/gitnexus/test/unit/group/bridge-storage-tempfile.test.ts
new file mode 100644
index 0000000000..ab539207a1
--- /dev/null
+++ b/gitnexus/test/unit/group/bridge-storage-tempfile.test.ts
@@ -0,0 +1,90 @@
+/**
+ * Regression tests for U6 — closes CodeQL js/insecure-temporary-file
+ * (#191/#192/#193) and js/log-injection (#188) in core/group.
+ *
+ * The fixes replace `Date.now()` suffix tmp files with crypto.randomBytes
+ * suffixes + open the tmp file with `flag: 'wx'` (O_EXCL). These tests
+ * pin both behaviors so a future refactor that drops either signal
+ * regenerates the CodeQL alert AND fails a test.
+ */
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import { writeContractRegistry, createGroupDir } from '../../../src/core/group/storage.js';
+import { writeBridgeMeta } from '../../../src/core/group/bridge-db.js';
+import type { ContractRegistry } from '../../../src/core/group/types.js';
+
+/**
+ * Build a minimal `ContractRegistry` literal with overridable fields.
+ * Replaces the `as never` cast that bypassed the type entirely — keeps
+ * the test free of unrelated boilerplate while still type-checking the
+ * fields under test.
+ */
+function makeRegistry(overrides: Partial<ContractRegistry> = {}): ContractRegistry {
+  return {
+    version: 1,
+    generatedAt: '2026-05-07T00:00:00Z',
+    repoSnapshots: {},
+    missingRepos: [],
+    contracts: [],
+    crossLinks: [],
+    ...overrides,
+  };
+}
+
+let tmpRoot: string;
+let groupDir: string;
+
+beforeAll(async () => {
+  tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-u6-'));
+  groupDir = path.join(tmpRoot, 'fixture-group');
+  await fs.mkdir(groupDir, { recursive: true });
+});
+
+afterAll(async () => {
+  await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+describe('writeContractRegistry — tempfile hardening', () => {
+  it('back-to-back writes within the same ms do not collide on the tmp path', async () => {
+    // The previous `${path}.tmp.${Date.now()}` shape collided when two writers
+    // landed in the same millisecond. crypto.randomBytes makes the suffix
+    // essentially-unique. Sequential writes here pin the unique-suffix
+    // property without depending on Windows-specific concurrent-rename
+    // behavior (which has its own pre-existing retry pattern in the
+    // sibling `writeBridge` function and is out of scope for this test).
+    await writeContractRegistry(groupDir, makeRegistry({ version: 1 }));
+    await writeContractRegistry(groupDir, makeRegistry({ version: 2 }));
+    const written = await fs.readFile(path.join(groupDir, 'contracts.json'), 'utf-8');
+    const parsed = JSON.parse(written);
+    expect(parsed.version).toBe(2);
+  });
+});
+
+describe('writeBridgeMeta — tempfile hardening', () => {
+  it('back-to-back writes do not collide on the tmp path', async () => {
+    await writeBridgeMeta(groupDir, { version: 1, generatedAt: 'a', missingRepos: [] });
+    await writeBridgeMeta(groupDir, { version: 2, generatedAt: 'b', missingRepos: [] });
+    const meta = JSON.parse(await fs.readFile(path.join(groupDir, 'meta.json'), 'utf-8'));
+    expect(meta.version).toBe(2);
+  });
+});
+
+describe('createGroupDir — exclusive-create on group.yaml', () => {
+  it('refuses to overwrite an existing group without force', async () => {
+    const gnxDir = path.join(tmpRoot, 'gnx-existing');
+    await createGroupDir(gnxDir, 'mygroup');
+    // Second call without force should throw — same behavior as before this
+    // commit, but now backed by O_EXCL at the writeFile level rather than
+    // only the up-front existence check (closes the TOCTOU CodeQL flagged).
+    await expect(createGroupDir(gnxDir, 'mygroup')).rejects.toThrow(/already exists/);
+  });
+
+  it('overwrites with force=true', async () => {
+    const gnxDir = path.join(tmpRoot, 'gnx-force');
+    await createGroupDir(gnxDir, 'mygroup');
+    // Should succeed without throwing.
+    await expect(createGroupDir(gnxDir, 'mygroup', true)).resolves.toBeTruthy();
+  });
+});
diff --git a/gitnexus/test/unit/group/cross-impact-phase2-timeout.test.ts b/gitnexus/test/unit/group/cross-impact-phase2-timeout.test.ts
new file mode 100644
index 0000000000..90b8a80a2b
--- /dev/null
+++ b/gitnexus/test/unit/group/cross-impact-phase2-timeout.test.ts
@@ -0,0 +1,121 @@
+/**
+ * Phase-2 fanout timeout regression test.
+ *
+ * Codex adversarial review on PR #1331 surfaced that `validateGroupImpactParams`
+ * clamps `timeoutMs` and `safeLocalImpact` enforces it on the local leg, but
+ * the Phase-2 cross-repo fanout (`cross-impact.ts:521-526`) awaits each
+ * `port.impactByUid(...)` call without a per-call timeout. A single hung
+ * neighbor pins the request indefinitely; multiple slow neighbors compound
+ * past the clamped budget because each starts before `Date.now() > deadline`.
+ *
+ * This test pins the contract of the mitigation: a `safeNeighborImpact`
+ * helper that races `port.impactByUid` against a remaining-budget timer
+ * and returns `{ value: null, timedOut: true }` when the call cannot
+ * complete in time.
+ *
+ * Direct import + named symbol so this is a real regression net — no
+ * `??`-fallback or dynamic-import dance (the U8 false-green pattern).
+ */
+import { describe, expect, it } from 'vitest';
+import { safeNeighborImpact } from '../../../src/core/group/cross-impact.js';
+import type { GroupToolPort } from '../../../src/core/group/service.js';
+
+const minimalOpts = {
+  maxDepth: 3,
+  relationTypes: [] as string[],
+  minConfidence: 0,
+  includeTests: false,
+};
+
+function makePort(impactByUid: GroupToolPort['impactByUid']): GroupToolPort {
+  return {
+    resolveRepo: async () => {
+      throw new Error('not used');
+    },
+    impact: async () => {
+      throw new Error('not used');
+    },
+    query: async () => {
+      throw new Error('not used');
+    },
+    context: async () => {
+      throw new Error('not used');
+    },
+    impactByUid,
+  };
+}
+
+describe('safeNeighborImpact — Phase-2 fanout per-call timeout', () => {
+  it('returns timedOut=true when impactByUid never resolves, within ~remainingMs', async () => {
+    // Hung neighbor: the promise never resolves. Without the timeout wrap
+    // this would hang the test runner.
+    const port = makePort(() => new Promise(() => {}));
+    const start = performance.now();
+    const result = await safeNeighborImpact(port, 'repo-id', 'uid:1', 'upstream', minimalOpts, 150);
+    const elapsedMs = performance.now() - start;
+    expect(result.timedOut).toBe(true);
+    expect(result.value).toBeNull();
+    // Allow generous slack for slow CI; the contract is "bounded", not
+    // "exactly remainingMs". A regression that drops the timeout entirely
+    // would hang far past 1500ms; a regression that uses the wrong unit
+    // (seconds vs ms) would fire much faster.
+    expect(elapsedMs).toBeGreaterThanOrEqual(140);
+    expect(elapsedMs).toBeLessThan(1500);
+  });
+
+  it('returns the resolved value and timedOut=false on a fast happy path', async () => {
+    const fakeFan = { byDepth: { 1: [{ id: 'u1' }] } };
+    const port = makePort(async () => fakeFan);
+    const result = await safeNeighborImpact(
+      port,
+      'repo-id',
+      'uid:1',
+      'upstream',
+      minimalOpts,
+      1000,
+    );
+    expect(result.timedOut).toBe(false);
+    expect(result.value).toBe(fakeFan);
+  });
+
+  it('returns timedOut=true immediately when remainingMs is 0 and the call still hangs', async () => {
+    // Defensive: even if the caller passes 0, the helper must not block.
+    const port = makePort(() => new Promise(() => {}));
+    const start = performance.now();
+    const result = await safeNeighborImpact(port, 'repo-id', 'uid:1', 'upstream', minimalOpts, 0);
+    const elapsedMs = performance.now() - start;
+    expect(result.timedOut).toBe(true);
+    expect(result.value).toBeNull();
+    // 0ms timeout fires on the next tick — should be well under 50ms even on slow CI.
+    expect(elapsedMs).toBeLessThan(50);
+  });
+
+  it('does not compound across calls — two hung neighbors complete within ~2× remainingMs total', async () => {
+    // The contract is per-call timeout. Two sequential hung calls should
+    // total ~2× remainingMs, not (numNeighbors × remainingMs² / 2) or
+    // anything compounding. A regression that shares one timer across
+    // calls would pass the first test but fail this one.
+    const port = makePort(() => new Promise(() => {}));
+    const start = performance.now();
+    const r1 = await safeNeighborImpact(port, 'repo', 'u1', 'upstream', minimalOpts, 100);
+    const r2 = await safeNeighborImpact(port, 'repo', 'u2', 'upstream', minimalOpts, 100);
+    const elapsedMs = performance.now() - start;
+    expect(r1.timedOut).toBe(true);
+    expect(r2.timedOut).toBe(true);
+    expect(elapsedMs).toBeGreaterThanOrEqual(180);
+    expect(elapsedMs).toBeLessThan(1000);
+  });
+
+  it('propagates an immediate rejection from impactByUid as timedOut=false with null value', async () => {
+    // If the port itself rejects (rather than hangs), the helper should
+    // surface that as a non-timeout failure — the existing fanout block
+    // already handles `if (fan == null)` truncation, so returning null
+    // here keeps that path intact.
+    const port = makePort(async () => {
+      throw new Error('connection refused');
+    });
+    const result = await safeNeighborImpact(port, 'repo', 'u1', 'upstream', minimalOpts, 1000);
+    expect(result.timedOut).toBe(false);
+    expect(result.value).toBeNull();
+  });
+});
diff --git a/gitnexus/test/unit/group/grpc-extractor.test.ts b/gitnexus/test/unit/group/grpc-extractor.test.ts
index a586b5c0d4..b128c6ddfa 100644
--- a/gitnexus/test/unit/group/grpc-extractor.test.ts
+++ b/gitnexus/test/unit/group/grpc-extractor.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import * as path from 'node:path';
@@ -11,6 +11,7 @@ import {
 } from '../../../src/core/group/extractors/grpc-extractor.js';
 import type { ProtoServiceInfo } from '../../../src/core/group/extractors/grpc-extractor.js';
 import type { RepoHandle } from '../../../src/core/group/types.js';
+import { _captureLogger } from '../../../src/core/logger.js';
 
 describe('GrpcExtractor', () => {
   let tmpDir: string;
@@ -797,18 +798,18 @@ describe('resolveProtoConflict', () => {
   });
 
   it('test_all_zero_tie_returns_null', () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const cap = _captureLogger();
     const candidates = [
       makeInfo('pkgA', 'totally/unrelated/a/svc.proto'),
       makeInfo('pkgB', 'completely/different/b/svc.proto'),
     ];
     const result = resolveProtoConflict('Svc', 'src/main.go', candidates);
     expect(result).toBeNull();
-    warnSpy.mockRestore();
+    cap.restore();
   });
 
   it('test_positive_score_tie_returns_null', () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const cap = _captureLogger();
     // Both candidates share `src/proto` with the source dir — equal shared runs.
     const candidates = [
       makeInfo('pkgA', 'src/proto/a/svc.proto'),
@@ -816,11 +817,11 @@ describe('resolveProtoConflict', () => {
     ];
     const result = resolveProtoConflict('Svc', 'src/proto/main.go', candidates);
     expect(result).toBeNull();
-    warnSpy.mockRestore();
+    cap.restore();
   });
 
   it('test_three_way_zero_tie_returns_null', () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const cap = _captureLogger();
     const candidates = [
       makeInfo('pkgA', 'aaa/svc.proto'),
       makeInfo('pkgB', 'bbb/svc.proto'),
@@ -828,7 +829,7 @@ describe('resolveProtoConflict', () => {
     ];
     const result = resolveProtoConflict('Svc', 'src/main.go', candidates);
     expect(result).toBeNull();
-    warnSpy.mockRestore();
+    cap.restore();
   });
 
   it('test_unique_winner_among_ties', () => {
@@ -843,19 +844,19 @@ describe('resolveProtoConflict', () => {
   });
 
   it('test_ambiguous_emits_single_warn_with_service_and_paths', () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const cap = _captureLogger();
     const candidates = [
       makeInfo('pkgA', 'totally/unrelated/a/svc.proto'),
       makeInfo('pkgB', 'completely/different/b/svc.proto'),
     ];
     resolveProtoConflict('MyService', 'src/main.go', candidates);
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    const msg = String(warnSpy.mock.calls[0][0]);
+    expect(cap.records().length).toBe(1);
+    const msg = String(String(cap.records()[0]?.msg ?? ''));
     expect(msg).toContain('MyService');
     expect(msg).toContain('src/main.go');
     expect(msg).toContain('totally/unrelated/a/svc.proto');
     expect(msg).toContain('completely/different/b/svc.proto');
-    warnSpy.mockRestore();
+    cap.restore();
   });
 });
 
@@ -879,7 +880,7 @@ describe('GrpcExtractor.extract ambiguous proto resolution', () => {
   });
 
   it('test_ambiguous_short_name_across_unrelated_protos_yields_no_source_contract', async () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const cap = _captureLogger();
     // Two unrelated proto files defining the same short name `UserService` in
     // unrelated directories, neither sharing path segments with the Go source.
     await fsp.mkdir(path.join(tmpDir, 'billing-team', 'proto'), { recursive: true });
@@ -906,8 +907,8 @@ describe('GrpcExtractor.extract ambiguous proto resolution', () => {
       (c) => c.meta.source === 'go_client' && c.meta.service === 'UserService',
     );
     expect(sourceContracts).toHaveLength(0);
-    expect(warnSpy).toHaveBeenCalled();
-    warnSpy.mockRestore();
+    expect(cap.records().length).toBeGreaterThan(0);
+    cap.restore();
   });
 });
 
diff --git a/gitnexus/test/unit/group/include-extractor.test.ts b/gitnexus/test/unit/group/include-extractor.test.ts
new file mode 100644
index 0000000000..3855a2f60b
--- /dev/null
+++ b/gitnexus/test/unit/group/include-extractor.test.ts
@@ -0,0 +1,362 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { IncludeExtractor } from '../../../src/core/group/extractors/include-extractor.js';
+import type { RepoHandle } from '../../../src/core/group/types.js';
+import { normalizeContractId } from '../../../src/core/group/matching.js';
+
+describe('IncludeExtractor', () => {
+  let tmpDir: string;
+  let extractor: IncludeExtractor;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-include-'));
+    extractor = new IncludeExtractor();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function writeFile(relPath: string, content: string): void {
+    const full = path.join(tmpDir, relPath);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+  }
+
+  const makeRepo = (repoPath: string): RepoHandle => ({
+    id: 'test-repo',
+    path: 'test/app',
+    repoPath,
+    storagePath: path.join(repoPath, '.gitnexus'),
+  });
+
+  // ---- Provider detection ----
+
+  describe('provider extraction', () => {
+    it('registers .h files as providers', async () => {
+      writeFile('map/base/view.h', '#pragma once\nclass View {};');
+      writeFile('map/base/types.h', '#pragma once\nstruct Point {};');
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter((c) => c.role === 'provider');
+
+      expect(providers).toHaveLength(2);
+      const ids = providers.map((p) => p.contractId).sort();
+      expect(ids).toEqual(['include::map/base/types.h', 'include::map/base/view.h']);
+      expect(providers[0].type).toBe('include');
+      expect(providers[0].confidence).toBeGreaterThanOrEqual(0.95);
+    });
+
+    it('registers .hpp files as providers', async () => {
+      writeFile('utils/helper.hpp', '#pragma once\ntemplate<class T> T id(T x) { return x; }');
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter((c) => c.role === 'provider');
+
+      expect(providers).toHaveLength(1);
+      expect(providers[0].contractId).toBe('include::utils/helper.hpp');
+    });
+
+    it('does not register .cpp files as providers', async () => {
+      writeFile('src/main.cpp', 'int main() { return 0; }');
+      writeFile('src/utils.h', '#pragma once');
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter((c) => c.role === 'provider');
+
+      expect(providers).toHaveLength(1);
+      expect(providers[0].contractId).toBe('include::src/utils.h');
+    });
+  });
+
+  // ---- Consumer detection ----
+
+  describe('consumer extraction', () => {
+    it('emits unresolved includes as consumers', async () => {
+      writeFile(
+        'src/main.cpp',
+        `#include "map/base/view.h"
+#include "map/base/types.h"
+int main() { return 0; }`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      expect(consumers).toHaveLength(2);
+      const ids = consumers.map((c) => c.contractId).sort();
+      expect(ids).toEqual(['include::map/base/types.h', 'include::map/base/view.h']);
+      expect(consumers[0].type).toBe('include');
+      expect(consumers[0].confidence).toBe(0.85);
+    });
+
+    it('skips locally resolved includes', async () => {
+      writeFile('map/base/view.h', '#pragma once\nclass View {};');
+      writeFile(
+        'src/main.cpp',
+        `#include "map/base/view.h"
+#include "external/lib.h"
+int main() { return 0; }`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      // Only external/lib.h should be a consumer — map/base/view.h resolves locally
+      expect(consumers).toHaveLength(1);
+      expect(consumers[0].contractId).toBe('include::external/lib.h');
+    });
+
+    it('skips angle-bracket includes', async () => {
+      writeFile(
+        'src/main.cpp',
+        `#include <stdio.h>
+#include <vector>
+#include "app/interface.h"
+int main() { return 0; }`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      expect(consumers).toHaveLength(1);
+      expect(consumers[0].contractId).toBe('include::app/interface.h');
+    });
+
+    it('skips well-known system headers in quotes', async () => {
+      writeFile(
+        'src/main.cpp',
+        `#include "stdio.h"
+#include "stdlib.h"
+#include "app/config.h"
+int main() { return 0; }`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      expect(consumers).toHaveLength(1);
+      expect(consumers[0].contractId).toBe('include::app/config.h');
+    });
+
+    it('skips system path prefixes', async () => {
+      writeFile(
+        'src/main.c',
+        `#include "sys/types.h"
+#include "linux/input.h"
+#include "mylib/types.h"
+int main() { return 0; }`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      expect(consumers).toHaveLength(1);
+      expect(consumers[0].contractId).toBe('include::mylib/types.h');
+    });
+  });
+
+  // ---- Cross-repo matching scenario ----
+
+  describe('cross-repo matching', () => {
+    it('provider and consumer produce matching contractIds', async () => {
+      // Simulate provider repo (header-only)
+      const providerDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-include-provider-'));
+      const providerFile = path.join(providerDir, 'map/base/dice_map_view.h');
+      fs.mkdirSync(path.dirname(providerFile), { recursive: true });
+      fs.writeFileSync(providerFile, '#pragma once\nclass DiceMapView {};');
+
+      // Simulate consumer repo
+      const consumerDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-include-consumer-'));
+      const consumerFile = path.join(consumerDir, 'src/controller.cpp');
+      fs.mkdirSync(path.dirname(consumerFile), { recursive: true });
+      fs.writeFileSync(consumerFile, '#include "map/base/dice_map_view.h"\nvoid init() {}');
+
+      try {
+        const providerContracts = await extractor.extract(null, providerDir, makeRepo(providerDir));
+        const consumerContracts = await extractor.extract(null, consumerDir, makeRepo(consumerDir));
+
+        const providers = providerContracts.filter((c) => c.role === 'provider');
+        const consumers = consumerContracts.filter((c) => c.role === 'consumer');
+
+        expect(providers.length).toBeGreaterThanOrEqual(1);
+        expect(consumers.length).toBeGreaterThanOrEqual(1);
+
+        const providerIds = new Set(providers.map((p) => normalizeContractId(p.contractId)));
+        const consumerIds = consumers.map((c) => normalizeContractId(c.contractId));
+
+        // The consumer's include path should match a provider's file path
+        expect(providerIds.has(consumerIds[0])).toBe(true);
+      } finally {
+        fs.rmSync(providerDir, { recursive: true, force: true });
+        fs.rmSync(consumerDir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  // ---- Review finding #4: suffixResolve ambiguity ----
+
+  describe('finding #4: suffix-ambiguity does not silently suppress cross-repo include', () => {
+    it('emits a cross-repo contract when the include path does not match any local file (even if a shorter suffix does)', async () => {
+      // local repo has `internal/api.h` but NOT `ext/api.h`
+      writeFile('internal/api.h', '#pragma once');
+      writeFile(
+        'src/main.cpp',
+        `#include "ext/api.h"
+int main() { return 0; }`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      // Previously suffixResolve would match `api.h` against `internal/api.h`
+      // and drop the cross-repo contract. After finding #4 fix, we only
+      // accept exact full-path matches — so `ext/api.h` must still be
+      // emitted as a consumer contract.
+      expect(consumers).toHaveLength(1);
+      expect(consumers[0].contractId).toBe('include::ext/api.h');
+    });
+
+    it('still suppresses a local include when the FULL path matches', async () => {
+      writeFile('ext/api.h', '#pragma once');
+      writeFile('src/main.cpp', '#include "ext/api.h"\nint main(){return 0;}');
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      expect(consumers).toHaveLength(0);
+    });
+
+    it('resolves locally when include omits extension and a matching .h exists', async () => {
+      writeFile('foo/bar.h', '#pragma once');
+      writeFile('src/main.cpp', '#include "foo/bar"\nint main(){return 0;}');
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      expect(consumers).toHaveLength(0);
+    });
+  });
+
+  // ---- Review finding #5: regex fallback must strip block comments ----
+
+  describe('finding #5: regex fallback ignores block-commented includes', () => {
+    it('does not emit a contract for an #include inside /* ... */', async () => {
+      // Force regex fallback by producing a file larger than tree-sitter's
+      // 32 KB hard cap. The include we care about lives inside a block
+      // comment that spans the file.
+      const filler = 'int dummy_' + 'x'.repeat(32) + ' = 0;\n'.repeat(1200);
+      const content = `/*
+ * Historical include, kept for reference only:
+ * #include "legacy/old-api.h"
+ */
+${filler}
+#include "real/api.h"
+int main(){return 0;}`;
+      writeFile('src/huge.cpp', content);
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+      const ids = consumers.map((c) => c.contractId);
+
+      // The live include should appear; the commented-out one must NOT.
+      expect(ids).toContain('include::real/api.h');
+      expect(ids).not.toContain('include::legacy/old-api.h');
+    });
+  });
+
+  // ---- Review finding #6: meta.source must reflect which extraction path ran ----
+
+  describe('finding #6: meta.source reflects extraction path', () => {
+    it('stamps `tree_sitter` on contracts produced via AST walking', async () => {
+      writeFile('src/main.cpp', '#include "app/small.h"\nint main(){return 0;}');
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      expect(consumers).toHaveLength(1);
+      expect((consumers[0].meta as { source?: string } | undefined)?.source).toBe('tree_sitter');
+    });
+
+    it('meta.source is one of the two documented values (tree_sitter | regex_fallback)', async () => {
+      // Regex fallback is a defensive branch that only fires if
+      // parser.setLanguage() or parser.parse() throws. In practice
+      // tree-sitter-c/cpp handles realistic inputs, so we only assert
+      // the meta.source contract: it is always present and always one of
+      // the two documented values. This guards against future regressions
+      // that might hard-code the wrong string.
+      writeFile('src/main.cpp', '#include "ext/whatever.h"\nint main(){return 0;}');
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumer = contracts.find((c) => c.role === 'consumer');
+      expect(consumer).toBeDefined();
+      const src = (consumer?.meta as { source?: string } | undefined)?.source;
+      expect(['tree_sitter', 'regex_fallback']).toContain(src);
+    });
+  });
+
+  // ---- Review finding #3: provider id collision on case-sensitive FS ----
+
+  describe('finding #3: case-folding is documented and deterministic', () => {
+    it('collapses `Foo.h` and `foo.h` onto the same provider contract-id (documented trade-off)', async () => {
+      writeFile('Foo.h', '#pragma once\n// Capital Foo');
+      // On case-insensitive filesystems (macOS default) the second writeFile
+      // will overwrite the first, so we only create this when distinct files
+      // can coexist (case-sensitive FS, e.g. Linux CI).
+      try {
+        fs.writeFileSync(path.join(tmpDir, 'foo.h'), '#pragma once\n// lowercase foo');
+      } catch {
+        // Ignore — some FS won't allow both names to coexist.
+      }
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter((c) => c.role === 'provider');
+      const ids = providers.map((p) => p.contractId);
+
+      // Both files (if they coexist) must normalize to the same id.
+      // dedupe() keeps only one; caller code must be aware of this.
+      expect(ids).toContain('include::foo.h');
+      // Never see a mixed-case contract-id leak out.
+      expect(ids.every((id) => id === id.toLowerCase())).toBe(true);
+    });
+  });
+
+  // ---- Deduplication ----
+
+  describe('deduplication', () => {
+    it('deduplicates same include from multiple source files', async () => {
+      writeFile('src/a.cpp', '#include "ext/api.h"\nvoid a() {}');
+      writeFile('src/b.cpp', '#include "ext/api.h"\nvoid b() {}');
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      // Both files include "ext/api.h" — each should produce a separate
+      // consumer contract (different symbolRef.filePath)
+      expect(consumers).toHaveLength(2);
+      const files = consumers.map((c) => c.symbolRef.filePath).sort();
+      expect(files).toEqual(['src/a.cpp', 'src/b.cpp']);
+    });
+  });
+
+  // ---- normalizeContractId ----
+
+  describe('normalizeContractId for include', () => {
+    it('lowercases the path', () => {
+      expect(normalizeContractId('include::Map/Base/Foo.h')).toBe('include::map/base/foo.h');
+    });
+
+    it('normalizes backslashes', () => {
+      expect(normalizeContractId('include::map\\base\\foo.h')).toBe('include::map/base/foo.h');
+    });
+
+    it('strips leading ./', () => {
+      expect(normalizeContractId('include::./foo.h')).toBe('include::foo.h');
+    });
+
+    it('collapses consecutive slashes', () => {
+      expect(normalizeContractId('include::map//base///foo.h')).toBe('include::map/base/foo.h');
+    });
+  });
+});
diff --git a/gitnexus/test/unit/group/insecure-tempfile.test.ts b/gitnexus/test/unit/group/insecure-tempfile.test.ts
index 17798a1994..a2ea148cda 100644
--- a/gitnexus/test/unit/group/insecure-tempfile.test.ts
+++ b/gitnexus/test/unit/group/insecure-tempfile.test.ts
@@ -43,45 +43,65 @@ describe('insecure tempfile — structural guards (#1318 U6)', () => {
     expect(bridgeSource).toMatch(/import\s*\{[^}]*randomBytes[^}]*\}\s*from\s*'node:crypto'/);
   });
 
-  it('bridge-db.ts uses randomBytes for bridge.lbug temp path', () => {
-    expect(bridgeSource).toMatch(/bridge\.lbug\.tmp\.\$\{randomBytes/);
+  it('bridge-db.ts uses mkdtemp staging directory for bridge.lbug', () => {
+    // Follow-up to the original randomBytes pattern: stage inside a
+    // mkdtemp-created directory so the suffix is OS-supplied, the
+    // directory contents are empty by construction, and concurrent
+    // writers cannot collide. The bridge.lbug filename inside that
+    // directory is fixed; uniqueness comes from the directory name.
+    expect(bridgeSource).toMatch(/fsp\.mkdtemp\(path\.join\(groupDir,\s*['"]bridge-tmp-['"]\)\)/);
+    expect(bridgeSource).toMatch(/path\.join\(stagingDir,\s*['"]bridge\.lbug['"]\)/);
   });
 
   it('bridge-db.ts uses randomBytes for meta.json temp path', () => {
     expect(bridgeSource).toMatch(/\.tmp\.\$\{randomBytes\(8\)\.toString\('hex'\)\}/);
   });
 
-  it('bridge-db.ts does not use Date.now() in any temp path', () => {
-    // Match Date.now() specifically in tmp-path contexts — not in unrelated code.
-    const tmpDateNow = bridgeSource.match(/\.tmp\.\$\{Date\.now\(\)\}/g) ?? [];
-    expect(tmpDateNow.length).toBe(0);
+  it('bridge-db.ts opens meta.json tmp file via fsp.open(..., "wx", 0o600)', () => {
+    // O_EXCL via `'wx'` flag closes the symlink-race; explicit `0o600`
+    // mode closes the permissions exposure CodeQL's
+    // `isSecureMode` predicate inspects (low 6 bits must be zero).
+    // Both arguments are required to fully clear the
+    // `js/insecure-temporary-file` alert — flags alone are ignored by
+    // the analyzer, mode alone leaves the symlink window open.
+    expect(bridgeSource).toMatch(/fsp\.open\(tmp,\s*['"]wx['"],\s*0o600\)/);
   });
 
-  it('bridge-db.ts uses readdir-based cleanup for stale bridge tmp files', () => {
-    expect(bridgeSource).toMatch(/cleanStaleBridgeTmpFiles/);
-    expect(bridgeSource).toMatch(/readdir\(groupDir\)/);
-    expect(bridgeSource).toMatch(/startsWith\('bridge\.lbug\.tmp\.'\)/);
+  it('bridge-db.ts does not use Date.now() in any active temp path', () => {
+    // Strip block AND line comments first so the historical
+    // "prior `${target}.tmp.${Date.now()}` shape." explanation does not
+    // register as an active call site. Block strip runs first so a future
+    // multi-line `/* ...Date.now()... */` doc comment is also handled.
+    const codeOnly = bridgeSource.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+    const tmpDateNow = codeOnly.match(/\.tmp\.\$\{Date\.now\(\)\}/g) ?? [];
+    expect(tmpDateNow.length).toBe(0);
   });
 
-  it('bridge-db.ts calls cleanStaleBridgeTmpFiles before openBridgeDb in writeBridge', () => {
-    // Ensure cleanup happens before the DB is opened with the new random path.
-    const cleanIdx = bridgeSource.indexOf('cleanStaleBridgeTmpFiles(groupDir)');
-    const openIdx = bridgeSource.indexOf('openBridgeDb(tmpPath)');
-    expect(cleanIdx).toBeGreaterThan(-1);
-    expect(openIdx).toBeGreaterThan(-1);
-    expect(cleanIdx).toBeLessThan(openIdx);
+  it('bridge-db.ts removes the mkdtemp staging directory in finally', () => {
+    // Whether writeBridge succeeds or throws, the random staging dir
+    // must be cleaned up — otherwise the group dir accumulates
+    // bridge-tmp-* directories. The removal is idempotent (force: true).
+    expect(bridgeSource).toMatch(
+      /fsp\.rm\(stagingDir,\s*\{[^}]*recursive:\s*true[^}]*force:\s*true/,
+    );
   });
 
   it('storage.ts imports randomBytes from node:crypto', () => {
     expect(storageSource).toMatch(/import\s*\{[^}]*randomBytes[^}]*\}\s*from\s*'node:crypto'/);
   });
 
-  it('storage.ts uses randomBytes for contracts.json temp path', () => {
-    expect(storageSource).toMatch(/\.tmp\.\$\{randomBytes\(8\)\.toString\('hex'\)\}/);
+  it('storage.ts uses tmpSuffix() helper backed by randomBytes', () => {
+    // The helper is a thin wrapper that DRYs the randomBytes call across
+    // multiple temp-path sites in this module. Its definition must use
+    // randomBytes, and the temp path must call it.
+    expect(storageSource).toMatch(/const\s+tmpSuffix\s*=.*randomBytes\(8\)\.toString\('hex'\)/);
+    expect(storageSource).toMatch(/\.tmp\.\$\{tmpSuffix\(\)\}/);
   });
 
-  it('storage.ts does not use Date.now() in any temp path', () => {
-    const tmpDateNow = storageSource.match(/\.tmp\.\$\{Date\.now\(\)\}/g) ?? [];
+  it('storage.ts does not use Date.now() in any active temp path', () => {
+    // Same comment-strip trick as bridge-db.ts above (block + line).
+    const codeOnly = storageSource.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+    const tmpDateNow = codeOnly.match(/\.tmp\.\$\{Date\.now\(\)\}/g) ?? [];
     expect(tmpDateNow.length).toBe(0);
   });
 });
diff --git a/gitnexus/test/unit/group/rust-workspace-extractor.test.ts b/gitnexus/test/unit/group/rust-workspace-extractor.test.ts
index a9e277c361..3dd958ebf2 100644
--- a/gitnexus/test/unit/group/rust-workspace-extractor.test.ts
+++ b/gitnexus/test/unit/group/rust-workspace-extractor.test.ts
@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import { extractRustWorkspaceLinks } from '../../../src/core/group/extractors/rust-workspace-extractor.js';
+import { _captureLogger } from '../../../src/core/logger.js';
 
 describe('RustWorkspaceExtractor', () => {
   let tmpDir: string;
@@ -229,19 +230,17 @@ describe('RustWorkspaceExtractor', () => {
       ['consumer', path.join(tmpDir, 'consumer')],
     ]);
 
-    const warnings: string[] = [];
-    const origWarn = console.warn;
-    console.warn = (...args: unknown[]) => {
-      warnings.push(String(args[0]));
-    };
+    const cap = _captureLogger();
     try {
       const result = await extractRustWorkspaceLinks(repos, repoPaths);
 
-      expect(warnings.some((w) => w.includes('duplicate crate name "shared"'))).toBe(true);
+      expect(
+        cap.records().some((r) => String(r.msg ?? '').includes('duplicate crate name "shared"')),
+      ).toBe(true);
       expect(result.links).toHaveLength(1);
       expect(result.links[0].from).toBe('a');
     } finally {
-      console.warn = origWarn;
+      cap.restore();
     }
   });
 
diff --git a/gitnexus/test/unit/group/sync.test.ts b/gitnexus/test/unit/group/sync.test.ts
index 17bd1c45d6..88bc3af2dc 100644
--- a/gitnexus/test/unit/group/sync.test.ts
+++ b/gitnexus/test/unit/group/sync.test.ts
@@ -3,6 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { syncGroup, stableRepoPoolId } from '../../../src/core/group/sync.js';
+import { _captureLogger } from '../../../src/core/logger.js';
 import type {
   GroupConfig,
   StoredContract,
@@ -650,9 +651,7 @@ service OrderService {
       matching: { bm25_threshold: 0.7, embedding_threshold: 0.65, max_candidates_per_step: 3 },
     };
 
-    const warnings: string[] = [];
-    const origWarn = console.warn;
-    console.warn = (msg: string) => warnings.push(String(msg));
+    const cap = _captureLogger();
     try {
       const result = await syncGroup(config, {
         extractorOverride: async () => [],
@@ -664,9 +663,9 @@ service OrderService {
       expect(result.crossLinks[0].to.symbolUid).toBe(
         'manifest::app/dangling::http::POST::/api/missing',
       );
-      expect(warnings.some((w) => w.includes('app/dangling'))).toBe(true);
+      expect(cap.records().some((r) => String(r.msg ?? '').includes('app/dangling'))).toBe(true);
     } finally {
-      console.warn = origWarn;
+      cap.restore();
     }
   });
 
diff --git a/gitnexus/test/unit/hf-env.test.ts b/gitnexus/test/unit/hf-env.test.ts
index 6a56970592..fa8f23bd34 100644
--- a/gitnexus/test/unit/hf-env.test.ts
+++ b/gitnexus/test/unit/hf-env.test.ts
@@ -1,7 +1,20 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import os from 'node:os';
 import { join } from 'node:path';
-import { applyHfEnvOverrides, type HfEnvSubset } from '../../src/core/embeddings/hf-env.js';
+import {
+  applyHfEnvOverrides,
+  isNetworkFetchError,
+  isHfDownloadFailure,
+  isHfCircuitOpenError,
+  HfDownloadCircuitBreaker,
+  withDownloadTimeout,
+  withHfDownloadRetry,
+  CIRCUIT_OPEN_TAG,
+  HF_MAX_ATTEMPTS,
+  HF_MAX_TIMEOUT_MS,
+  HF_MAX_ATTEMPTS_CAP,
+  type HfEnvSubset,
+} from '../../src/core/embeddings/hf-env.js';
 
 describe('applyHfEnvOverrides', () => {
   let envStub: HfEnvSubset;
@@ -82,3 +95,399 @@ describe('applyHfEnvOverrides', () => {
     expect(envStub.remoteHost).toBe('https://hf-mirror.com/');
   });
 });
+
+describe('isNetworkFetchError', () => {
+  it('returns true for "fetch failed" (the undici error seen on macOS/Node 24)', () => {
+    expect(isNetworkFetchError('fetch failed')).toBe(true);
+  });
+
+  it('returns true for ECONNREFUSED', () => {
+    expect(isNetworkFetchError('connect ECONNREFUSED 13.45.67.89:443')).toBe(true);
+  });
+
+  it('returns true for ENOTFOUND (DNS failure)', () => {
+    expect(isNetworkFetchError('getaddrinfo ENOTFOUND huggingface.co')).toBe(true);
+  });
+
+  it('returns true for ETIMEDOUT', () => {
+    expect(isNetworkFetchError('connect ETIMEDOUT 13.45.67.89:443')).toBe(true);
+  });
+
+  it('returns true for ECONNRESET', () => {
+    expect(isNetworkFetchError('read ECONNRESET')).toBe(true);
+  });
+
+  it('returns false for generic model-load errors (ONNX device failure)', () => {
+    expect(isNetworkFetchError('Failed to initialize CUDA backend')).toBe(false);
+  });
+
+  it('returns false for empty string', () => {
+    expect(isNetworkFetchError('')).toBe(false);
+  });
+
+  it('returns false for module-not-found errors', () => {
+    expect(isNetworkFetchError('Cannot find module onnxruntime-node')).toBe(false);
+  });
+});
+
+describe('isHfCircuitOpenError', () => {
+  it('returns true for a circuit-open tag message', () => {
+    expect(isHfCircuitOpenError(`${CIRCUIT_OPEN_TAG}: circuit is open`)).toBe(true);
+  });
+
+  it('returns false for a plain network error', () => {
+    expect(isHfCircuitOpenError('fetch failed')).toBe(false);
+  });
+});
+
+describe('isHfDownloadFailure', () => {
+  it('returns true for network fetch errors', () => {
+    expect(isHfDownloadFailure('ECONNREFUSED 127.0.0.1:443')).toBe(true);
+  });
+
+  it('returns true for circuit-open errors', () => {
+    expect(isHfDownloadFailure(`${CIRCUIT_OPEN_TAG}: open`)).toBe(true);
+  });
+
+  it('returns false for ONNX device errors', () => {
+    expect(isHfDownloadFailure('Failed to initialize CUDA')).toBe(false);
+  });
+});
+
+describe('HfDownloadCircuitBreaker', () => {
+  it('starts in closed state', () => {
+    const cb = new HfDownloadCircuitBreaker();
+    expect(cb.isOpen()).toBe(false);
+    expect(cb.state).toBe('closed');
+  });
+
+  it('opens after reaching the failure threshold', () => {
+    const cb = new HfDownloadCircuitBreaker(3);
+    cb.recordFailure();
+    cb.recordFailure();
+    expect(cb.isOpen()).toBe(false);
+    cb.recordFailure(); // threshold reached
+    expect(cb.isOpen()).toBe(true);
+    expect(cb.state).toBe('open');
+  });
+
+  it('closes on recordSuccess after being open', () => {
+    const cb = new HfDownloadCircuitBreaker(1);
+    cb.recordFailure();
+    expect(cb.isOpen()).toBe(true);
+    cb.recordSuccess();
+    expect(cb.isOpen()).toBe(false);
+    expect(cb.state).toBe('closed');
+  });
+
+  it('transitions to half-open after the reset timeout', () => {
+    vi.useFakeTimers();
+    try {
+      const cb = new HfDownloadCircuitBreaker(1, 100 /* 100ms */);
+      cb.recordFailure();
+      expect(cb.isOpen()).toBe(true);
+      vi.advanceTimersByTime(200);
+      expect(cb.isOpen()).toBe(false);
+      expect(cb.state).toBe('half-open');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('reset() restores closed state', () => {
+    const cb = new HfDownloadCircuitBreaker(1);
+    cb.recordFailure();
+    expect(cb.isOpen()).toBe(true);
+    cb.reset();
+    expect(cb.isOpen()).toBe(false);
+    expect(cb.state).toBe('closed');
+  });
+
+  it('re-opens when a failure is recorded in half-open state', () => {
+    vi.useFakeTimers();
+    try {
+      const cb = new HfDownloadCircuitBreaker(1, 100 /* 100ms */);
+      cb.recordFailure(); // opens the circuit
+      vi.advanceTimersByTime(200); // advance past reset timeout
+      expect(cb.state).toBe('half-open'); // getter transitions _state to half-open
+      cb.recordFailure(); // failure in half-open → re-opens
+      expect(cb.isOpen()).toBe(true);
+      expect(cb.state).toBe('open');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('closes the circuit when success is recorded in half-open state', () => {
+    vi.useFakeTimers();
+    try {
+      const cb = new HfDownloadCircuitBreaker(1, 100 /* 100ms */);
+      cb.recordFailure(); // opens the circuit
+      vi.advanceTimersByTime(200); // advance past reset timeout
+      expect(cb.state).toBe('half-open');
+      cb.recordSuccess(); // success in half-open → closes
+      expect(cb.isOpen()).toBe(false);
+      expect(cb.state).toBe('closed');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe('withDownloadTimeout', () => {
+  it('resolves when fn completes before the timeout', async () => {
+    const result = await withDownloadTimeout(() => Promise.resolve(42), 1_000);
+    expect(result).toBe(42);
+  });
+
+  it('rejects with ETIMEDOUT when fn takes too long', async () => {
+    vi.useFakeTimers();
+    try {
+      const neverResolves = () => new Promise<never>(() => {});
+      const promise = withDownloadTimeout(neverResolves, 20);
+      vi.advanceTimersByTime(30);
+      await expect(promise).rejects.toThrow('ETIMEDOUT');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('propagates non-timeout errors from fn', async () => {
+    await expect(
+      withDownloadTimeout(() => Promise.reject(new Error('download error')), 1_000),
+    ).rejects.toThrow('download error');
+  });
+});
+
+describe('withHfDownloadRetry', () => {
+  it('returns the result on first success', async () => {
+    const fn = vi.fn().mockResolvedValue('ok');
+    const cb = new HfDownloadCircuitBreaker();
+    const result = await withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 });
+    expect(result).toBe('ok');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries on network errors and succeeds on second attempt', async () => {
+    const fn = vi.fn().mockRejectedValueOnce(new Error('fetch failed')).mockResolvedValue('ok');
+    const cb = new HfDownloadCircuitBreaker();
+    const result = await withHfDownloadRetry(fn, {
+      circuit: cb,
+      maxAttempts: 3,
+      baseDelayMs: 0,
+    });
+    expect(result).toBe('ok');
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('throws the last network error after all attempts are exhausted', async () => {
+    const fn = vi.fn().mockRejectedValue(new Error('ECONNREFUSED 127.0.0.1:443'));
+    const cb = new HfDownloadCircuitBreaker(99 /* high threshold */);
+    await expect(
+      withHfDownloadRetry(fn, { circuit: cb, maxAttempts: 3, baseDelayMs: 0 }),
+    ).rejects.toThrow('ECONNREFUSED');
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+
+  it('does not retry non-network errors', async () => {
+    const fn = vi.fn().mockRejectedValue(new Error('Failed to initialize CUDA backend'));
+    const cb = new HfDownloadCircuitBreaker();
+    await expect(
+      withHfDownloadRetry(fn, { circuit: cb, maxAttempts: 3, baseDelayMs: 0 }),
+    ).rejects.toThrow('Failed to initialize CUDA backend');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('fails immediately when the circuit is already open', async () => {
+    const fn = vi.fn().mockResolvedValue('ok');
+    const cb = new HfDownloadCircuitBreaker(1);
+    cb.recordFailure(); // open the circuit
+    await expect(withHfDownloadRetry(fn, { circuit: cb })).rejects.toThrow(CIRCUIT_OPEN_TAG);
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('opens the circuit after failureThreshold failures and throws a circuit-open error', async () => {
+    const fn = vi.fn().mockRejectedValue(new Error('ENOTFOUND huggingface.co'));
+    const cb = new HfDownloadCircuitBreaker(2 /* threshold */, 60_000);
+    // First call: 2 attempts, threshold=2 → circuit opens on 2nd failure
+    await expect(
+      withHfDownloadRetry(fn, { circuit: cb, maxAttempts: 2, baseDelayMs: 0 }),
+    ).rejects.toThrow(CIRCUIT_OPEN_TAG);
+    expect(cb.isOpen()).toBe(true);
+  });
+
+  it('calls onRetry with correct arguments on each retry', async () => {
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('fetch failed'))
+      .mockRejectedValueOnce(new Error('fetch failed'))
+      .mockResolvedValue('ok');
+    const cb = new HfDownloadCircuitBreaker(99);
+    const onRetry = vi.fn();
+    await withHfDownloadRetry(fn, { circuit: cb, maxAttempts: 3, baseDelayMs: 0, onRetry });
+    expect(onRetry).toHaveBeenCalledTimes(2);
+    expect(onRetry).toHaveBeenNthCalledWith(
+      1,
+      1,
+      3,
+      expect.objectContaining({ message: 'fetch failed' }),
+    );
+    expect(onRetry).toHaveBeenNthCalledWith(
+      2,
+      2,
+      3,
+      expect.objectContaining({ message: 'fetch failed' }),
+    );
+  });
+
+  it('resets the circuit on success', async () => {
+    const fn = vi.fn().mockResolvedValue('value');
+    const cb = new HfDownloadCircuitBreaker(5);
+    cb.recordFailure();
+    cb.recordFailure(); // 2 failures, circuit still closed
+    await withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 });
+    expect(cb.state).toBe('closed');
+  });
+});
+
+describe('withHfDownloadRetry env overrides', () => {
+  let originalTimeout: string | undefined;
+  let originalMaxAttempts: string | undefined;
+
+  beforeEach(() => {
+    originalTimeout = process.env.HF_DOWNLOAD_TIMEOUT_MS;
+    originalMaxAttempts = process.env.HF_MAX_ATTEMPTS;
+    delete process.env.HF_DOWNLOAD_TIMEOUT_MS;
+    delete process.env.HF_MAX_ATTEMPTS;
+  });
+
+  afterEach(() => {
+    if (originalTimeout === undefined) delete process.env.HF_DOWNLOAD_TIMEOUT_MS;
+    else process.env.HF_DOWNLOAD_TIMEOUT_MS = originalTimeout;
+    if (originalMaxAttempts === undefined) delete process.env.HF_MAX_ATTEMPTS;
+    else process.env.HF_MAX_ATTEMPTS = originalMaxAttempts;
+  });
+
+  it('HF_MAX_ATTEMPTS=1 gives exactly 1 attempt', async () => {
+    process.env.HF_MAX_ATTEMPTS = '1';
+    const fn = vi.fn().mockRejectedValue(new Error('ECONNREFUSED 127.0.0.1:443'));
+    const cb = new HfDownloadCircuitBreaker(99_999 /* high threshold */);
+    await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
+      'ECONNREFUSED',
+    );
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('HF_MAX_ATTEMPTS=2 gives exactly 2 attempts', async () => {
+    process.env.HF_MAX_ATTEMPTS = '2';
+    const fn = vi.fn().mockRejectedValue(new Error('ENOTFOUND huggingface.co'));
+    const cb = new HfDownloadCircuitBreaker(99_999);
+    await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
+      'ENOTFOUND',
+    );
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('HF_MAX_ATTEMPTS=abc falls back to the built-in default', async () => {
+    process.env.HF_MAX_ATTEMPTS = 'abc';
+    const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
+    const cb = new HfDownloadCircuitBreaker(99_999);
+    await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
+      'fetch failed',
+    );
+    expect(fn).toHaveBeenCalledTimes(HF_MAX_ATTEMPTS);
+  });
+
+  it('HF_MAX_ATTEMPTS=0 falls back to the built-in default', async () => {
+    process.env.HF_MAX_ATTEMPTS = '0';
+    const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
+    const cb = new HfDownloadCircuitBreaker(99_999);
+    await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
+      'fetch failed',
+    );
+    expect(fn).toHaveBeenCalledTimes(HF_MAX_ATTEMPTS);
+  });
+
+  it('HF_MAX_ATTEMPTS=-1 falls back to the built-in default', async () => {
+    process.env.HF_MAX_ATTEMPTS = '-1';
+    const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
+    const cb = new HfDownloadCircuitBreaker(99_999);
+    await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
+      'fetch failed',
+    );
+    expect(fn).toHaveBeenCalledTimes(HF_MAX_ATTEMPTS);
+  });
+
+  it('HF_MAX_ATTEMPTS is clamped to HF_MAX_ATTEMPTS_CAP', async () => {
+    process.env.HF_MAX_ATTEMPTS = '9999';
+    const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
+    const cb = new HfDownloadCircuitBreaker(99_999 /* very high threshold */);
+    await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
+      'fetch failed',
+    );
+    expect(fn).toHaveBeenCalledTimes(HF_MAX_ATTEMPTS_CAP);
+  });
+
+  it('HF_MAX_ATTEMPTS=2.9 is floored to 2', async () => {
+    process.env.HF_MAX_ATTEMPTS = '2.9';
+    const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
+    const cb = new HfDownloadCircuitBreaker(99_999);
+    await expect(withHfDownloadRetry(fn, { circuit: cb, baseDelayMs: 0 })).rejects.toThrow(
+      'fetch failed',
+    );
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('HF_DOWNLOAD_TIMEOUT_MS is used as the per-attempt timeout when valid', async () => {
+    vi.useFakeTimers();
+    try {
+      process.env.HF_DOWNLOAD_TIMEOUT_MS = '50';
+      const neverResolves = () => new Promise<never>(() => {});
+      const cb = new HfDownloadCircuitBreaker(99);
+      const promise = withHfDownloadRetry(neverResolves, { circuit: cb, maxAttempts: 1 });
+      vi.advanceTimersByTime(100);
+      await expect(promise).rejects.toThrow('ETIMEDOUT');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('HF_DOWNLOAD_TIMEOUT_MS=-1 falls back to the built-in default', async () => {
+    process.env.HF_DOWNLOAD_TIMEOUT_MS = '-1';
+    // Passing explicit timeoutMs=0 (no real wait) so the test doesn't block;
+    // we just verify that the env var rejection causes options.timeoutMs to be
+    // the default constant (not -1) by confirming the resolved value is used.
+    const fn = vi.fn().mockResolvedValue('ok');
+    const cb = new HfDownloadCircuitBreaker(99);
+    // Provide explicit timeoutMs to avoid the default 5-minute wait
+    const result = await withHfDownloadRetry(fn, { circuit: cb, timeoutMs: 100 });
+    expect(result).toBe('ok');
+  });
+
+  it('HF_DOWNLOAD_TIMEOUT_MS is clamped to HF_MAX_TIMEOUT_MS', async () => {
+    vi.useFakeTimers();
+    try {
+      // Set an env value exceeding the 30-minute cap
+      process.env.HF_DOWNLOAD_TIMEOUT_MS = String(HF_MAX_TIMEOUT_MS + 60_000);
+      const neverResolves = () => new Promise<never>(() => {});
+      const cb = new HfDownloadCircuitBreaker(99);
+      const promise = withHfDownloadRetry(neverResolves, { circuit: cb, maxAttempts: 1 });
+      // Advance just past the 30-minute cap
+      vi.advanceTimersByTime(HF_MAX_TIMEOUT_MS + 1);
+      await expect(promise).rejects.toThrow('ETIMEDOUT');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('explicit options override env vars', async () => {
+    process.env.HF_MAX_ATTEMPTS = '5';
+    const fn = vi.fn().mockRejectedValue(new Error('fetch failed'));
+    const cb = new HfDownloadCircuitBreaker(99);
+    // explicit maxAttempts: 2 must win over HF_MAX_ATTEMPTS=5
+    await expect(
+      withHfDownloadRetry(fn, { circuit: cb, maxAttempts: 2, baseDelayMs: 0 }),
+    ).rejects.toThrow('fetch failed');
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/gitnexus/test/unit/ignore-service.test.ts b/gitnexus/test/unit/ignore-service.test.ts
index de32eb8d99..b4e5cdca18 100644
--- a/gitnexus/test/unit/ignore-service.test.ts
+++ b/gitnexus/test/unit/ignore-service.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeAll, beforeEach, afterAll, afterEach, vi } from 'vitest';
+import { describe, it, expect, beforeAll, beforeEach, afterAll, afterEach } from 'vitest';
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
@@ -8,6 +8,7 @@ import {
   loadIgnoreRules,
   createIgnoreFilter,
 } from '../../src/config/ignore-service.js';
+import { _captureLogger } from '../../src/core/logger.js';
 
 describe('shouldIgnorePath', () => {
   describe('version control directories', () => {
@@ -574,13 +575,13 @@ describe('loadIgnoreRules — error handling', () => {
       await fs.writeFile(gitignorePath, 'data/\n');
       await fs.chmod(gitignorePath, 0o000);
 
-      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const cap = _captureLogger();
       const result = await loadIgnoreRules(tmpDir);
       // Should still return (null or partial), not throw
       expect(result).toBeNull();
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('.gitignore'));
+      expect(cap.records().some((r) => String(r.msg ?? '').includes('.gitignore'))).toBe(true);
 
-      warnSpy.mockRestore();
+      cap.restore();
       await fs.chmod(gitignorePath, 0o644);
       await fs.unlink(gitignorePath);
     },
diff --git a/gitnexus/test/unit/lbug-config-wal.test.ts b/gitnexus/test/unit/lbug-config-wal.test.ts
new file mode 100644
index 0000000000..6baea3621b
--- /dev/null
+++ b/gitnexus/test/unit/lbug-config-wal.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createLbugDatabase, isWalCorruptionError } from '../../src/core/lbug/lbug-config.js';
+
+describe('isWalCorruptionError', () => {
+  it.each([
+    [
+      'Corrupted wal file',
+      'Runtime exception: Corrupted wal file. Read out invalid WAL record type.',
+    ],
+    ['invalid WAL record', 'Error: invalid WAL record type'],
+    ['WAL checksum', 'Checksum verification failed, the WAL file is corrupted.'],
+    ['WAL + corrupt', 'the WAL file is corrupted'],
+  ])('matches WAL corruption: %s', (_label, msg) => {
+    expect(isWalCorruptionError(msg)).toBe(true);
+    expect(isWalCorruptionError(new Error(msg))).toBe(true);
+  });
+
+  it.each([
+    ['lock error', 'Could not set lock on file : /path/to/db'],
+    ['generic', 'Query failed'],
+    ['not found', 'LadybugDB not found at /path'],
+    ['checksum without WAL', 'Checksum verification failed for parquet file'],
+    ['permission path with WAL', "EACCES: permission denied '/path/to/wal'"],
+    ['schema mismatch WAL', 'schema version mismatch in WAL'],
+  ])('does not match non-WAL error: %s', (_label, msg) => {
+    expect(isWalCorruptionError(msg)).toBe(false);
+  });
+
+  it('handles non-string input', () => {
+    expect(isWalCorruptionError(undefined)).toBe(false);
+    expect(isWalCorruptionError(null)).toBe(false);
+    expect(isWalCorruptionError(42)).toBe(false);
+    expect(isWalCorruptionError(new Error('ok'))).toBe(false);
+  });
+});
+
+describe('createLbugDatabase WAL replay option', () => {
+  it('passes throwOnWalReplayFailure and checksum constructor args explicitly', () => {
+    const Database = vi.fn(function (this: any) {});
+    const lbugModule = { Database } as any;
+
+    createLbugDatabase(lbugModule, '/tmp/lbug', {
+      readOnly: true,
+      throwOnWalReplayFailure: false,
+    });
+
+    expect(Database).toHaveBeenCalledWith(
+      '/tmp/lbug',
+      0,
+      false,
+      true,
+      expect.any(Number),
+      true,
+      -1,
+      false,
+      true,
+    );
+  });
+});
diff --git a/gitnexus/test/unit/logger.test.ts b/gitnexus/test/unit/logger.test.ts
new file mode 100644
index 0000000000..7d92d40c5d
--- /dev/null
+++ b/gitnexus/test/unit/logger.test.ts
@@ -0,0 +1,279 @@
+/**
+ * Unit tests for src/core/logger.ts.
+ *
+ * Asserts the wiring rather than re-deriving pino's output format:
+ *   - createLogger returns level-method API
+ *   - debugEnvVar opt promotes level to 'debug' when env truthy
+ *   - destination opt redirects output (test-capture pattern)
+ *   - Error.message === undefined does not throw
+ *   - CR/LF/U+2028/ANSI in field values produce a single NDJSON line
+ *
+ * The pretty-printing branch is exercised indirectly: VITEST=true (which
+ * vitest sets automatically) means shouldUsePretty() returns false, so
+ * tests run with raw NDJSON — exactly the operator-CI behavior.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  createLogger,
+  logger,
+  MemoryWritable,
+  _captureLogger,
+  _tryBuildPrettyTransport,
+  _resetPrettyAvailableCache,
+  flushLoggerSync,
+} from '../../src/core/logger.js';
+
+describe('createLogger — API surface', () => {
+  it('returns an object with the standard level methods', () => {
+    const dest = new MemoryWritable();
+    const log = createLogger('test', { destination: dest });
+    expect(typeof log.warn).toBe('function');
+    expect(typeof log.error).toBe('function');
+    expect(typeof log.debug).toBe('function');
+    expect(typeof log.info).toBe('function');
+    expect(typeof log.fatal).toBe('function');
+    expect(typeof log.trace).toBe('function');
+  });
+
+  it('default singleton logger exposes the same API', () => {
+    expect(typeof logger.warn).toBe('function');
+    expect(typeof logger.error).toBe('function');
+  });
+});
+
+describe('createLogger — debugEnvVar gating', () => {
+  const ENV = 'TEST_PINO_DEBUG_VAR';
+
+  beforeEach(() => {
+    delete process.env[ENV];
+  });
+
+  afterEach(() => {
+    delete process.env[ENV];
+  });
+
+  it('without debugEnvVar, .debug() emits nothing (default info level)', () => {
+    const dest = new MemoryWritable();
+    const log = createLogger('t', { destination: dest });
+    log.debug('should not appear');
+    expect(dest.records()).toEqual([]);
+  });
+
+  it('with debugEnvVar set but env unset, .debug() emits nothing', () => {
+    const dest = new MemoryWritable();
+    const log = createLogger('t', { debugEnvVar: ENV, destination: dest });
+    log.debug('should not appear');
+    expect(dest.records()).toEqual([]);
+  });
+
+  it('with debugEnvVar set and env truthy, .debug() emits a record', () => {
+    process.env[ENV] = '1';
+    const dest = new MemoryWritable();
+    const log = createLogger('t', { debugEnvVar: ENV, destination: dest });
+    log.debug({ key: 'value' }, 'debug-msg');
+    const records = dest.records() as Array<Record<string, unknown>>;
+    expect(records.length).toBe(1);
+    expect(records[0].msg).toBe('debug-msg');
+    expect(records[0].key).toBe('value');
+    expect(records[0].name).toBe('t');
+  });
+
+  it('treats env values "0", "false", "no", "off" as falsy', () => {
+    for (const falsy of ['0', 'false', 'FALSE', 'no', 'off', '']) {
+      process.env[ENV] = falsy;
+      const dest = new MemoryWritable();
+      const log = createLogger('t', { debugEnvVar: ENV, destination: dest });
+      log.debug('hidden');
+      expect(dest.records(), `value=${JSON.stringify(falsy)}`).toEqual([]);
+    }
+  });
+});
+
+describe('createLogger — structured output safety', () => {
+  it('captures .warn output as parseable NDJSON in destination', () => {
+    const dest = new MemoryWritable();
+    const log = createLogger('cap', { destination: dest });
+    log.warn({ groupDir: '/tmp/x', attempts: 3 }, 'gave up');
+    const records = dest.records() as Array<Record<string, unknown>>;
+    expect(records.length).toBe(1);
+    expect(records[0].msg).toBe('gave up');
+    expect(records[0].name).toBe('cap');
+    expect(records[0].groupDir).toBe('/tmp/x');
+    expect(records[0].attempts).toBe(3);
+    expect(records[0].level).toBe(40); // pino's numeric warn level
+  });
+
+  it('handles Error with undefined message without throwing', () => {
+    const dest = new MemoryWritable();
+    const log = createLogger('cap', { destination: dest });
+    const err = new Error('original');
+    Object.assign(err, { message: undefined });
+    expect(() => log.warn({ err }, 'with bad error')).not.toThrow();
+    const records = dest.records();
+    expect(records.length).toBe(1);
+  });
+
+  it('CR/LF in a string field stays inside one NDJSON record', () => {
+    const dest = new MemoryWritable();
+    const log = createLogger('cap', { destination: dest });
+    const evil = '/tmp/group\r\n2026-01-01 [bridge-db] FAKE INJECTED LINE';
+    log.warn({ groupDir: evil }, 'msg');
+    // Exactly one record. The internal \r\n is JSON-escaped, not a record boundary.
+    expect(dest.records().length).toBe(1);
+    // Raw text has trailing newline as record terminator — count of \n == 1.
+    expect(
+      dest
+        .text()
+        .split('\n')
+        .filter((l) => l.length > 0).length,
+    ).toBe(1);
+  });
+
+  it('U+2028 / U+2029 in a string field stays inside one NDJSON record', () => {
+    const dest = new MemoryWritable();
+    const log = createLogger('cap', { destination: dest });
+    const evil = 'before
after
more';
+    log.warn({ field: evil }, 'msg');
+    // Same record-count invariant. JSON.parse round-trips the codepoints.
+    expect(dest.records().length).toBe(1);
+    const rec = dest.records()[0] as Record<string, unknown>;
+    expect(rec.field).toBe(evil);
+  });
+
+  it('ANSI escape sequence in a string field stays inside one NDJSON record', () => {
+    const dest = new MemoryWritable();
+    const log = createLogger('cap', { destination: dest });
+    const ansi = 'RED';
+    log.warn({ msg2: ansi }, 'msg');
+    expect(dest.records().length).toBe(1);
+  });
+});
+
+describe('_captureLogger — lifecycle', () => {
+  it('captures records emitted via the default logger singleton', () => {
+    const cap = _captureLogger();
+    try {
+      logger.warn({ k: 'v' }, 'captured');
+      const recs = cap.records();
+      expect(recs.length).toBe(1);
+      expect(recs[0].msg).toBe('captured');
+      expect(recs[0].k).toBe('v');
+    } finally {
+      cap.restore();
+    }
+  });
+
+  it('restore() stops further writes from reaching the captured stream', () => {
+    const cap = _captureLogger();
+    logger.warn('first');
+    cap.restore();
+    // After restore, the singleton routes back to the real (stderr)
+    // destination. The captured stream should still hold only the first
+    // record — the second logger.warn must not show up here.
+    logger.warn('second');
+    const recs = cap.records();
+    expect(recs.length).toBe(1);
+    expect(recs[0].msg).toBe('first');
+  });
+
+  it('throws when called twice without restore() — guards against silent state corruption', () => {
+    const cap = _captureLogger();
+    try {
+      expect(() => _captureLogger()).toThrow(/previous capture is still active/);
+    } finally {
+      cap.restore();
+    }
+  });
+
+  it('can re-capture after restore()', () => {
+    const cap1 = _captureLogger();
+    cap1.restore();
+    const cap2 = _captureLogger();
+    try {
+      logger.warn('after-recapture');
+      expect(cap2.records().some((r) => r.msg === 'after-recapture')).toBe(true);
+    } finally {
+      cap2.restore();
+    }
+  });
+});
+
+describe('_tryBuildPrettyTransport — pino-pretty availability probe', () => {
+  beforeEach(() => {
+    _resetPrettyAvailableCache();
+  });
+
+  afterEach(() => {
+    _resetPrettyAvailableCache();
+  });
+
+  it('returns transport options when pino-pretty resolves (the production install path)', () => {
+    // pino-pretty is a runtime dep (PR #1336 Codex P1 fix), so under any
+    // normal vitest run the probe should succeed and yield a target +
+    // destination:2 transport spec. This is the happy path.
+    const transport = _tryBuildPrettyTransport();
+    expect(transport).toBeDefined();
+    // Pino accepts a single transport object or a multi-target shape; we
+    // emit the single-target form, so narrow before asserting.
+    if (transport && typeof transport === 'object' && 'target' in transport) {
+      expect(transport.target).toBe('pino-pretty');
+      expect(transport.options).toMatchObject({
+        destination: 2,
+        colorize: true,
+      });
+    } else {
+      throw new Error('expected single-target transport options shape with target=pino-pretty');
+    }
+  });
+
+  it('memoizes the resolve result — repeat calls do not re-probe', () => {
+    // Probe once, then again — both should return the same shape and the
+    // cache should make the second call zero-cost. We can't observe the
+    // resolve count from outside, but we can assert the second call's
+    // result is structurally identical and that the warning is not
+    // double-emitted (covered by the next test).
+    const first = _tryBuildPrettyTransport();
+    const second = _tryBuildPrettyTransport();
+    expect(second).toEqual(first);
+  });
+
+  it('flushLoggerSync is callable without throwing whether or not the destination has been used', () => {
+    // The contract: shutdown handlers can call this unconditionally before
+    // process.exit and it is safe even when no logger has emitted yet.
+    expect(() => flushLoggerSync()).not.toThrow();
+    // After a logger emit, still safe to call.
+    logger.info('warm the destination');
+    expect(() => flushLoggerSync()).not.toThrow();
+  });
+
+  it('emits at most one stderr warning across many calls when pino-pretty is missing', () => {
+    // Simulate the missing-module path by stubbing process.stderr.write
+    // and forcing the cache to "not available". This validates the
+    // one-time-warning contract: 100 calls produce 0 or 1 warning lines,
+    // never 100.
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    try {
+      // Inject negative cache state by monkey-patching require.resolve
+      // would be brittle. Instead, exercise the actual cache: after a
+      // successful resolve, no warning fires. Then for the missing path,
+      // we rely on the structural guarantee that warningEmitted state is
+      // module-level and only one branch can fire it. This test asserts
+      // the upper bound: even under heavy call volume, stderr writes
+      // attributable to the probe never exceed 1 per process lifetime.
+      for (let i = 0; i < 100; i++) {
+        _tryBuildPrettyTransport();
+      }
+      const probeWarnings = stderrSpy.mock.calls.filter(([chunk]) => {
+        const s = typeof chunk === 'string' ? chunk : chunk.toString();
+        return s.includes('pino-pretty unavailable');
+      });
+      // pino-pretty IS installed in the test env, so the warning never
+      // fires. The assertion is "<= 1" rather than "=== 0" so the test
+      // also passes in a future env where pino-pretty is intentionally
+      // stripped (the contract still holds).
+      expect(probeWarnings.length).toBeLessThanOrEqual(1);
+    } finally {
+      stderrSpy.mockRestore();
+    }
+  });
+});
diff --git a/gitnexus/test/unit/max-file-size.test.ts b/gitnexus/test/unit/max-file-size.test.ts
index 074e148e7c..569b41eab5 100644
--- a/gitnexus/test/unit/max-file-size.test.ts
+++ b/gitnexus/test/unit/max-file-size.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import {
   DEFAULT_MAX_FILE_SIZE_BYTES,
   MAX_FILE_SIZE_UPPER_BOUND_BYTES,
@@ -6,15 +6,16 @@ import {
   getMaxFileSizeBannerMessage,
   _resetMaxFileSizeWarnings,
 } from '../../src/core/ingestion/utils/max-file-size.js';
+import { _captureLogger } from '../../src/core/logger.js';
 
 describe('getMaxFileSizeBytes', () => {
   const ORIGINAL = process.env.GITNEXUS_MAX_FILE_SIZE;
-  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let cap: ReturnType<typeof _captureLogger>;
 
   beforeEach(() => {
     delete process.env.GITNEXUS_MAX_FILE_SIZE;
     _resetMaxFileSizeWarnings();
-    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    cap = _captureLogger();
   });
 
   afterEach(() => {
@@ -23,43 +24,43 @@ describe('getMaxFileSizeBytes', () => {
     } else {
       process.env.GITNEXUS_MAX_FILE_SIZE = ORIGINAL;
     }
-    warnSpy.mockRestore();
+    cap.restore();
   });
 
   it('returns the default when the env var is unset', () => {
     expect(getMaxFileSizeBytes()).toBe(DEFAULT_MAX_FILE_SIZE_BYTES);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(cap.records().length).toBe(0);
   });
 
   it('parses a positive integer value as KB', () => {
     process.env.GITNEXUS_MAX_FILE_SIZE = '1024';
     expect(getMaxFileSizeBytes()).toBe(1024 * 1024);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(cap.records().length).toBe(0);
   });
 
   it('clamps values above the tree-sitter ceiling', () => {
-    // One KB above the 32 MB ceiling.
     const aboveCeilingKb = MAX_FILE_SIZE_UPPER_BOUND_BYTES / 1024 + 1;
     process.env.GITNEXUS_MAX_FILE_SIZE = String(aboveCeilingKb);
     expect(getMaxFileSizeBytes()).toBe(MAX_FILE_SIZE_UPPER_BOUND_BYTES);
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    expect(warnSpy.mock.calls[0][0]).toContain('clamping');
+    const records = cap.records();
+    expect(records.length).toBe(1);
+    expect(String(records[0].msg)).toContain('clamping');
   });
 
   it.each(['abc', '0', '-512', '1.5', 'NaN', ''])(
     'falls back to the default and warns on invalid value %s',
     (raw) => {
       if (raw === '') {
-        // Empty string is treated as unset by the util (raw falsy check).
         process.env.GITNEXUS_MAX_FILE_SIZE = raw;
         expect(getMaxFileSizeBytes()).toBe(DEFAULT_MAX_FILE_SIZE_BYTES);
-        expect(warnSpy).not.toHaveBeenCalled();
+        expect(cap.records().length).toBe(0);
         return;
       }
       process.env.GITNEXUS_MAX_FILE_SIZE = raw;
       expect(getMaxFileSizeBytes()).toBe(DEFAULT_MAX_FILE_SIZE_BYTES);
-      expect(warnSpy).toHaveBeenCalledTimes(1);
-      expect(warnSpy.mock.calls[0][0]).toContain('must be a positive integer');
+      const records = cap.records();
+      expect(records.length).toBe(1);
+      expect(String(records[0].msg)).toContain('must be a positive integer');
     },
   );
 
@@ -68,7 +69,7 @@ describe('getMaxFileSizeBytes', () => {
     getMaxFileSizeBytes();
     getMaxFileSizeBytes();
     getMaxFileSizeBytes();
-    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(cap.records().length).toBe(1);
   });
 
   it('warns separately for distinct invalid values', () => {
@@ -76,20 +77,20 @@ describe('getMaxFileSizeBytes', () => {
     getMaxFileSizeBytes();
     process.env.GITNEXUS_MAX_FILE_SIZE = 'xyz';
     getMaxFileSizeBytes();
-    expect(warnSpy).toHaveBeenCalledTimes(2);
+    expect(cap.records().length).toBe(2);
   });
 
   it('_resetMaxFileSizeWarnings re-enables warnings after reset', () => {
     process.env.GITNEXUS_MAX_FILE_SIZE = 'abc';
     getMaxFileSizeBytes();
-    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(cap.records().length).toBe(1);
 
     getMaxFileSizeBytes();
-    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(cap.records().length).toBe(1);
 
     _resetMaxFileSizeWarnings();
     getMaxFileSizeBytes();
-    expect(warnSpy).toHaveBeenCalledTimes(2);
+    expect(cap.records().length).toBe(2);
   });
 
   it('DEFAULT_MAX_FILE_SIZE_BYTES is 512 KB', () => {
@@ -99,12 +100,12 @@ describe('getMaxFileSizeBytes', () => {
 
 describe('getMaxFileSizeBannerMessage', () => {
   const ORIGINAL = process.env.GITNEXUS_MAX_FILE_SIZE;
-  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let cap: ReturnType<typeof _captureLogger>;
 
   beforeEach(() => {
     delete process.env.GITNEXUS_MAX_FILE_SIZE;
     _resetMaxFileSizeWarnings();
-    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    cap = _captureLogger();
   });
 
   afterEach(() => {
@@ -113,7 +114,7 @@ describe('getMaxFileSizeBannerMessage', () => {
     } else {
       process.env.GITNEXUS_MAX_FILE_SIZE = ORIGINAL;
     }
-    warnSpy.mockRestore();
+    cap.restore();
   });
 
   it('returns null when the env var is unset (default threshold)', () => {
diff --git a/gitnexus/test/unit/mcp-wal-feedback.test.ts b/gitnexus/test/unit/mcp-wal-feedback.test.ts
new file mode 100644
index 0000000000..e387e0b97f
--- /dev/null
+++ b/gitnexus/test/unit/mcp-wal-feedback.test.ts
@@ -0,0 +1,160 @@
+/**
+ * Tests for WAL corruption feedback in MCP error responses (#1402).
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { lbugMocks, platformMocks, repoMocks } = vi.hoisted(() => ({
+  lbugMocks: {
+    initLbug: vi.fn().mockResolvedValue(undefined),
+    executeQuery: vi.fn(),
+    executeParameterized: vi.fn(),
+    closeLbug: vi.fn().mockResolvedValue(undefined),
+    isLbugReady: vi.fn().mockReturnValue(true),
+    isWriteQuery: vi.fn().mockReturnValue(false),
+  },
+  platformMocks: {
+    isVectorExtensionSupportedByPlatform: vi.fn().mockReturnValue(true),
+  },
+  repoMocks: {
+    listRegisteredRepos: vi.fn(),
+  },
+}));
+
+vi.mock('../../src/core/lbug/pool-adapter.js', async (importOriginal) => {
+  const actual = await importOriginal();
+  return { ...actual, ...lbugMocks };
+});
+
+vi.mock('../../src/mcp/core/lbug-adapter.js', async (importOriginal) => {
+  const actual = await importOriginal();
+  return { ...actual, ...lbugMocks };
+});
+
+vi.mock('../../src/storage/repo-manager.js', () => ({
+  listRegisteredRepos: repoMocks.listRegisteredRepos,
+  cleanupOldKuzuFiles: vi.fn().mockResolvedValue({ found: false, needsReindex: false }),
+  findSiblingClones: vi.fn().mockResolvedValue([]),
+}));
+
+vi.mock('../../src/core/git-staleness.js', () => ({
+  checkStaleness: vi.fn().mockReturnValue({ isStale: false, commitsBehind: 0 }),
+  checkCwdMatch: vi.fn().mockResolvedValue({ match: 'none' }),
+}));
+
+vi.mock('../../src/core/platform/capabilities.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../src/core/platform/capabilities.js')>();
+  return {
+    ...actual,
+    isVectorExtensionSupportedByPlatform: platformMocks.isVectorExtensionSupportedByPlatform,
+  };
+});
+
+vi.mock('../../src/core/search/bm25-index.js', () => ({
+  searchFTSFromLbug: vi.fn().mockResolvedValue([]),
+}));
+
+vi.mock('../../src/mcp/core/embedder.js', () => ({
+  embedQuery: vi.fn().mockResolvedValue([]),
+  getEmbeddingDims: vi.fn().mockReturnValue(384),
+}));
+
+import { LocalBackend } from '../../src/mcp/local/local-backend.js';
+
+const MOCK_REPO_ENTRY = {
+  name: 'test-repo',
+  path: '/tmp/test',
+  storagePath: '/tmp/test/.gitnexus',
+  indexedAt: '2026-05-01T00:00:00Z',
+  lastCommit: 'abc1234',
+};
+
+async function makeBackend(): Promise<LocalBackend> {
+  const backend = new LocalBackend();
+  await backend.init();
+  return backend;
+}
+
+describe('WAL corruption feedback in MCP responses (#1402)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    lbugMocks.initLbug.mockResolvedValue(undefined);
+    lbugMocks.executeQuery.mockResolvedValue([]);
+    lbugMocks.executeParameterized.mockResolvedValue([]);
+    lbugMocks.isLbugReady.mockReturnValue(true);
+    lbugMocks.isWriteQuery.mockReturnValue(false);
+    repoMocks.listRegisteredRepos.mockResolvedValue([MOCK_REPO_ENTRY]);
+  });
+
+  it('impact returns WAL suggestion on corrupted WAL error', async () => {
+    const backend = await makeBackend();
+    lbugMocks.executeParameterized.mockRejectedValueOnce(
+      new Error('Runtime exception: Corrupted wal file. Read out invalid WAL record type.'),
+    );
+
+    const result = await backend.callTool('impact', {
+      repo: 'test-repo',
+      target: 'MyClass',
+      direction: 'upstream',
+    });
+
+    expect(result.error).toBeDefined();
+    expect(result.suggestion).toBe(
+      'The graph query failed — try gitnexus context <symbol> as a fallback',
+    );
+    expect(result.recoverySuggestion).toBeDefined();
+  });
+
+  it('cypher returns WAL recoverySuggestion on corrupted WAL error', async () => {
+    const backend = await makeBackend();
+    lbugMocks.executeQuery.mockRejectedValueOnce(new Error('Corrupted wal file'));
+
+    const result = await backend.callTool('cypher', {
+      repo: 'test-repo',
+      query: 'MATCH (n) RETURN n LIMIT 1',
+    });
+
+    expect(result.error).toBe('Corrupted wal file');
+    expect(result.recoverySuggestion).toBeDefined();
+  });
+
+  it('context returns WAL recoverySuggestion on corrupted WAL error', async () => {
+    const backend = await makeBackend();
+    lbugMocks.executeParameterized.mockRejectedValueOnce(new Error('Corrupted wal file'));
+
+    const result = await backend.callTool('context', {
+      repo: 'test-repo',
+      name: 'MyClass',
+    });
+
+    expect(result.error).toBe('Corrupted wal file');
+    expect(result.recoverySuggestion).toBeDefined();
+  });
+
+  it('non-WAL errors do not include WAL suggestion', async () => {
+    const backend = await makeBackend();
+    lbugMocks.executeParameterized.mockRejectedValueOnce(new Error('Some other error'));
+
+    const result = await backend.callTool('impact', {
+      repo: 'test-repo',
+      target: 'MyClass',
+      direction: 'upstream',
+    });
+
+    expect(result.error).toBeDefined();
+    expect(result.suggestion).toBe(
+      'The graph query failed — try gitnexus context <symbol> as a fallback',
+    );
+  });
+
+  it('context preserves non-WAL throw behavior', async () => {
+    const backend = await makeBackend();
+    lbugMocks.executeParameterized.mockRejectedValueOnce(new Error('Some other error'));
+
+    await expect(
+      backend.callTool('context', {
+        repo: 'test-repo',
+        name: 'MyClass',
+      }),
+    ).rejects.toThrow('Some other error');
+  });
+});
diff --git a/gitnexus/test/unit/pool-wal-recovery.test.ts b/gitnexus/test/unit/pool-wal-recovery.test.ts
new file mode 100644
index 0000000000..19b24c5833
--- /dev/null
+++ b/gitnexus/test/unit/pool-wal-recovery.test.ts
@@ -0,0 +1,177 @@
+/**
+ * Tests for WAL corruption recovery in the connection pool (#1402).
+ *
+ * Mocks createLbugDatabase and fs to verify quarantine + retry behavior
+ * without needing a real LadybugDB instance or corrupted WAL file.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { stderrWriteMock } = vi.hoisted(() => ({
+  stderrWriteMock: vi.fn(),
+}));
+
+vi.mock('fs/promises', () => ({
+  default: {
+    stat: vi.fn().mockResolvedValue({}),
+    unlink: vi.fn().mockResolvedValue(undefined),
+    rename: vi.fn().mockResolvedValue(undefined),
+  },
+}));
+
+vi.mock('@ladybugdb/core', () => ({
+  default: {
+    Database: vi.fn(),
+    Connection: vi.fn(function (this: any) {
+      this.close = vi.fn().mockResolvedValue(undefined);
+    }),
+  },
+}));
+
+vi.mock('../../src/core/lbug/lbug-adapter.js', () => ({
+  loadFTSExtension: vi.fn().mockResolvedValue(true),
+}));
+
+vi.mock('../../src/core/lbug/lbug-config.js', () => ({
+  createLbugDatabase: vi.fn(),
+  LBUG_MAX_DB_SIZE: 1024,
+  isWalCorruptionError: vi.fn((err: unknown) => {
+    const msg = err instanceof Error ? err.message : String(err ?? '');
+    return /corrupt(ed)?\s+wal|invalid\s+wal\s+record/i.test(msg);
+  }),
+}));
+
+vi.mock('../../src/mcp/stdio-capture.js', () => ({
+  realStdoutWrite: vi.fn(),
+  realStderrWrite: stderrWriteMock,
+  setActiveStdoutWrite: vi.fn(),
+  getActiveStdoutWrite: vi.fn(() => vi.fn()),
+}));
+
+import fs from 'fs/promises';
+import { createLbugDatabase } from '../../src/core/lbug/lbug-config.js';
+
+const { closeLbug } = await import('../../src/core/lbug/pool-adapter.js');
+
+const mockInit = vi.fn().mockResolvedValue(undefined);
+const mockClose = vi.fn().mockResolvedValue(undefined);
+
+function makeMockDb() {
+  return { init: mockInit, close: mockClose, _isClosed: false } as any;
+}
+
+describe('WAL corruption recovery in doInitLbug (#1402)', () => {
+  beforeEach(() => {
+    (createLbugDatabase as any).mockReset();
+    (fs.stat as any).mockReset();
+    (fs.rename as any).mockReset();
+    mockInit.mockReset();
+    mockClose.mockReset();
+    mockInit.mockResolvedValue(undefined);
+    mockClose.mockResolvedValue(undefined);
+    (fs.stat as any).mockResolvedValue({});
+    (fs.rename as any).mockResolvedValue(undefined);
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    await closeLbug().catch(() => {});
+    vi.clearAllMocks();
+  });
+
+  it('retries with WAL quarantine on corrupted WAL init error', async () => {
+    const { initLbug } = await import('../../src/core/lbug/pool-adapter.js');
+    const dbPath = '/tmp/test-wal-recovery/lbug';
+
+    const badDb = makeMockDb();
+    const goodDb = makeMockDb();
+    badDb.init = vi.fn().mockRejectedValueOnce(new Error('Corrupted wal file'));
+    (createLbugDatabase as any).mockReturnValueOnce(badDb).mockReturnValueOnce(goodDb);
+
+    await initLbug('test-repo-init', dbPath);
+
+    expect(badDb.init).toHaveBeenCalledTimes(1);
+    expect(createLbugDatabase).toHaveBeenCalledTimes(2);
+    expect(createLbugDatabase).toHaveBeenCalledWith(
+      expect.anything(),
+      dbPath,
+      expect.objectContaining({
+        readOnly: true,
+        throwOnWalReplayFailure: false,
+      }),
+    );
+    expect(fs.rename).toHaveBeenCalledWith(
+      dbPath + '.wal',
+      expect.stringContaining('.wal.corrupt.'),
+    );
+    expect(stderrWriteMock).toHaveBeenCalledWith(
+      expect.stringContaining('WAL quarantined for test-repo-init'),
+    );
+  });
+
+  it('does not quarantine on lock error (preserves existing lock retry)', async () => {
+    const { initLbug } = await import('../../src/core/lbug/pool-adapter.js');
+    const setTimeoutSpy = vi.spyOn(global, 'setTimeout').mockImplementation((callback: any) => {
+      callback();
+      return 0 as any;
+    });
+    const dbPath = '/tmp/test-wal-recovery/lbug';
+
+    (createLbugDatabase as any).mockImplementation(() => {
+      throw new Error('Could not set lock on file');
+    });
+
+    try {
+      await expect(initLbug('test-repo-lock', dbPath)).rejects.toThrow();
+    } finally {
+      setTimeoutSpy.mockRestore();
+    }
+
+    expect(fs.rename).not.toHaveBeenCalled();
+  });
+
+  it('throws with analyze suggestion after retry also fails', async () => {
+    const { initLbug } = await import('../../src/core/lbug/pool-adapter.js');
+    const dbPath = '/tmp/test-wal-recovery/lbug';
+
+    (createLbugDatabase as any)
+      .mockImplementationOnce(() => {
+        throw new Error('Corrupted wal file');
+      })
+      .mockImplementationOnce(() => {
+        throw new Error('Still broken');
+      });
+
+    await expect(initLbug('test-repo-fail', dbPath)).rejects.toThrow(/gitnexus analyze/);
+    expect(createLbugDatabase).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not reuse poisoned state after WAL failure', async () => {
+    const { initLbug, isLbugReady: ready } = await import('../../src/core/lbug/pool-adapter.js');
+    const dbPath = '/tmp/test-wal-recovery/lbug';
+
+    (createLbugDatabase as any)
+      .mockImplementationOnce(() => {
+        throw new Error('Corrupted wal file');
+      })
+      .mockImplementationOnce(() => {
+        throw new Error('Still broken');
+      });
+
+    await expect(initLbug('test-repo-nocache', dbPath)).rejects.toThrow();
+
+    expect(ready('test-repo-nocache')).toBe(false);
+  });
+
+  it('handles quarantine gracefully when .wal file does not exist', async () => {
+    const { initLbug } = await import('../../src/core/lbug/pool-adapter.js');
+    const dbPath = '/tmp/test-wal-recovery/lbug';
+
+    (fs.rename as any).mockRejectedValueOnce(new Error('ENOENT: no such file'));
+
+    (createLbugDatabase as any).mockImplementationOnce(() => {
+      throw new Error('Corrupted wal file');
+    });
+
+    await expect(initLbug('test-repo-enoent', dbPath)).rejects.toThrow(/gitnexus analyze/);
+  });
+});
diff --git a/gitnexus/test/unit/sequential-language-availability.test.ts b/gitnexus/test/unit/sequential-language-availability.test.ts
index f48db5778a..bd0e4d4d6f 100644
--- a/gitnexus/test/unit/sequential-language-availability.test.ts
+++ b/gitnexus/test/unit/sequential-language-availability.test.ts
@@ -19,6 +19,7 @@ import { createSymbolTable } from '../../src/core/ingestion/model/symbol-table.j
 import { createResolutionContext } from '../../src/core/ingestion/model/resolution-context.js';
 import * as parserLoader from '../../src/core/tree-sitter/parser-loader.js';
 
+import { _captureLogger } from '../../src/core/logger.js';
 describe('sequential native parser availability', () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -43,7 +44,7 @@ describe('sequential native parser availability', () => {
   });
 
   it('warns when processImports skips files in verbose mode', async () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const cap = _captureLogger();
     const previous = process.env.GITNEXUS_VERBOSE;
     process.env.GITNEXUS_VERBOSE = '1';
     vi.mocked(parserLoader.isLanguageAvailable).mockReturnValue(false);
@@ -58,11 +59,17 @@ describe('sequential native parser availability', () => {
       ['App.swift'],
     );
 
-    expect(warnSpy).toHaveBeenCalledWith(
-      '[ingestion] Skipped 1 swift file(s) in import processing — swift parser not available.',
-    );
-
-    warnSpy.mockRestore();
+    expect(
+      cap
+        .records()
+        .some(
+          (r) =>
+            r.msg ===
+            '[ingestion] Skipped 1 swift file(s) in import processing — swift parser not available.',
+        ),
+    ).toBe(true);
+
+    cap.restore();
     if (previous === undefined) {
       delete process.env.GITNEXUS_VERBOSE;
     } else {
@@ -86,7 +93,7 @@ describe('sequential native parser availability', () => {
   });
 
   it('warns when processCalls skips files in verbose mode', async () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const cap = _captureLogger();
     const previous = process.env.GITNEXUS_VERBOSE;
     process.env.GITNEXUS_VERBOSE = '1';
     vi.mocked(parserLoader.isLanguageAvailable).mockReturnValue(false);
@@ -98,11 +105,17 @@ describe('sequential native parser availability', () => {
       createResolutionContext(),
     );
 
-    expect(warnSpy).toHaveBeenCalledWith(
-      '[ingestion] Skipped 1 swift file(s) in call processing — swift parser not available.',
-    );
-
-    warnSpy.mockRestore();
+    expect(
+      cap
+        .records()
+        .some(
+          (r) =>
+            r.msg ===
+            '[ingestion] Skipped 1 swift file(s) in call processing — swift parser not available.',
+        ),
+    ).toBe(true);
+
+    cap.restore();
     if (previous === undefined) {
       delete process.env.GITNEXUS_VERBOSE;
     } else {
@@ -126,7 +139,7 @@ describe('sequential native parser availability', () => {
   });
 
   it('warns when processHeritage skips files in verbose mode', async () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const cap = _captureLogger();
     const previous = process.env.GITNEXUS_VERBOSE;
     process.env.GITNEXUS_VERBOSE = '1';
     vi.mocked(parserLoader.isLanguageAvailable).mockReturnValue(false);
@@ -138,11 +151,17 @@ describe('sequential native parser availability', () => {
       createResolutionContext(),
     );
 
-    expect(warnSpy).toHaveBeenCalledWith(
-      '[ingestion] Skipped 1 swift file(s) in heritage processing — swift parser not available.',
-    );
-
-    warnSpy.mockRestore();
+    expect(
+      cap
+        .records()
+        .some(
+          (r) =>
+            r.msg ===
+            '[ingestion] Skipped 1 swift file(s) in heritage processing — swift parser not available.',
+        ),
+    ).toBe(true);
+
+    cap.restore();
     if (previous === undefined) {
       delete process.env.GITNEXUS_VERBOSE;
     } else {
@@ -166,7 +185,7 @@ describe('sequential native parser availability', () => {
   });
 
   it('warns when processParsing skips files in verbose mode', async () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const cap = _captureLogger();
     const previous = process.env.GITNEXUS_VERBOSE;
     process.env.GITNEXUS_VERBOSE = '1';
     vi.mocked(parserLoader.isLanguageAvailable).mockReturnValue(false);
@@ -178,11 +197,17 @@ describe('sequential native parser availability', () => {
       createASTCache(),
     );
 
-    expect(warnSpy).toHaveBeenCalledWith(
-      '[ingestion] Skipped 1 swift file(s) in parsing processing — swift parser not available.',
-    );
-
-    warnSpy.mockRestore();
+    expect(
+      cap
+        .records()
+        .some(
+          (r) =>
+            r.msg ===
+            '[ingestion] Skipped 1 swift file(s) in parsing processing — swift parser not available.',
+        ),
+    ).toBe(true);
+
+    cap.restore();
     if (previous === undefined) {
       delete process.env.GITNEXUS_VERBOSE;
     } else {
diff --git a/gitnexus/test/unit/staleness.test.ts b/gitnexus/test/unit/staleness.test.ts
index b8ea398ff2..1645d99871 100644
--- a/gitnexus/test/unit/staleness.test.ts
+++ b/gitnexus/test/unit/staleness.test.ts
@@ -8,7 +8,7 @@
  */
 import { describe, it, expect } from 'vitest';
 import { execFileSync } from 'child_process';
-import { checkStaleness } from '../../src/core/git-staleness.js';
+import { checkStaleness, checkStalenessAsync } from '../../src/core/git-staleness.js';
 
 // We test checkStaleness with a real git repo (the project itself)
 // since mocking execFileSync across ESM modules is complex.
@@ -65,3 +65,82 @@ describe('checkStaleness', () => {
     expect(result.commitsBehind).toBe(0);
   });
 });
+
+describe('checkStalenessAsync', () => {
+  it('returns not stale when HEAD matches lastCommit', async () => {
+    let headCommit: string;
+    try {
+      headCommit = execFileSync('git', ['rev-parse', 'HEAD'], {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+    } catch {
+      return;
+    }
+
+    const result = await checkStalenessAsync(process.cwd(), headCommit);
+    expect(result.isStale).toBe(false);
+    expect(result.commitsBehind).toBe(0);
+    expect(result.hint).toBeUndefined();
+  });
+
+  it('returns stale when lastCommit is behind HEAD', async () => {
+    let previousCommit: string;
+    try {
+      previousCommit = execFileSync('git', ['rev-parse', 'HEAD~1'], {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+    } catch {
+      return;
+    }
+
+    if (!previousCommit) return;
+
+    const result = await checkStalenessAsync(process.cwd(), previousCommit);
+    expect(result.isStale).toBe(true);
+    expect(result.commitsBehind).toBeGreaterThan(0);
+    expect(result.hint).toContain('behind HEAD');
+  });
+
+  it('fails open when git command fails (e.g., invalid path)', async () => {
+    const result = await checkStalenessAsync('/nonexistent/path', 'abc123');
+    expect(result.isStale).toBe(false);
+    expect(result.commitsBehind).toBe(0);
+  });
+
+  it('fails open with invalid commit hash', async () => {
+    const result = await checkStalenessAsync(process.cwd(), 'not-a-real-commit-hash');
+    expect(result.isStale).toBe(false);
+    expect(result.commitsBehind).toBe(0);
+  });
+
+  it('parallel calls complete faster than sequential', async () => {
+    let headCommit: string;
+    try {
+      headCommit = execFileSync('git', ['rev-parse', 'HEAD'], {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+    } catch {
+      return;
+    }
+
+    const cwd = process.cwd();
+    const N = 10;
+
+    // Parallel
+    const t0 = performance.now();
+    await Promise.all(Array.from({ length: N }, () => checkStalenessAsync(cwd, headCommit)));
+    const parallelMs = performance.now() - t0;
+
+    // Sequential sync
+    const t1 = performance.now();
+    for (let i = 0; i < N; i++) checkStaleness(cwd, headCommit);
+    const sequentialMs = performance.now() - t1;
+
+    // Parallel should be meaningfully faster than sequential.
+    // Use a generous ratio to avoid flakiness on slow CI machines.
+    expect(parallelMs).toBeLessThan(sequentialMs * 1.5);
+  });
+});
diff --git a/gitnexus/test/unit/u8-redos-resource-exhaustion.test.ts b/gitnexus/test/unit/u8-redos-resource-exhaustion.test.ts
new file mode 100644
index 0000000000..6dd6d99552
--- /dev/null
+++ b/gitnexus/test/unit/u8-redos-resource-exhaustion.test.ts
@@ -0,0 +1,196 @@
+/**
+ * Regression tests for U8 — closes:
+ *   #186 js/redos             rust-workspace-extractor.ts
+ *   #187 js/redos             cobol-preprocessor.ts
+ *   #184 js/resource-exhaustion cross-impact.ts
+ *
+ * These tests import the production symbols directly. A previous shape
+ * dynamic-imported names that did not exist (`extractRustWorkspace` vs.
+ * the real `extractRustWorkspaceLinks`) and `??`-fell-back to inline
+ * regex copies, so the tests stayed green even when the production
+ * fixes regressed. Static imports + named symbols make a regression in
+ * any of the three sites a hard test failure.
+ */
+import { describe, expect, it } from 'vitest';
+import { RE_SET_TO_TRUE, RE_SET_INDEX } from '../../src/core/ingestion/cobol/cobol-preprocessor.js';
+import { parseCargoPackageName } from '../../src/core/group/extractors/rust-workspace-extractor.js';
+import {
+  clampTimeout,
+  IMPACT_TIMEOUT_MIN_MS,
+  IMPACT_TIMEOUT_MAX_MS,
+} from '../../src/core/group/cross-impact.js';
+
+/**
+ * Time a single regex.exec call. Used by the linearity tests below to
+ * compute a 10k/5k ratio in addition to the absolute <500ms bound.
+ *
+ * Ratio assertions catch sub-exponential O(n²) regressions that fit
+ * inside the absolute cap on warm CI; the absolute cap catches
+ * catastrophic backtracking on cold CI. Two complementary signals.
+ */
+function timeRegex(re: RegExp, input: string): number {
+  // Reset regex.lastIndex for global/sticky regexes — ours are not, but
+  // be defensive in case future shape changes add the `g` flag.
+  re.lastIndex = 0;
+  const start = performance.now();
+  re.exec(input);
+  return performance.now() - start;
+}
+
+function timeFn<T>(fn: () => T): number {
+  const start = performance.now();
+  fn();
+  return performance.now() - start;
+}
+
+// Linear scaling is ~2.0× when input doubles; 3.0× allows generous
+// slack for CI-runner GC and tier-up jitter. An O(n²) regression on a
+// 2× input takes ~4× as long, well outside this bound.
+const LINEAR_RATIO_BOUND = 3.0;
+
+/**
+ * Minimum elapsed time (in ms) below which `performance.now()` ratios
+ * are dominated by scheduler jitter and become meaningless. When both
+ * timed runs come in below this floor, we skip the ratio assertion —
+ * the absolute <500ms bound still catches catastrophic backtracking,
+ * and the next CI run will measure higher absolute times that the
+ * ratio assertion can evaluate reliably.
+ *
+ * Calibrated empirically: a flake on macOS reported ratio 5.29×
+ * between two sub-millisecond measurements (~0.5ms vs ~2.6ms), both
+ * genuinely linear but indistinguishable from noise. 5ms is a
+ * comfortable floor where individual measurements are well-separated
+ * from the ~10-100µs `performance.now()` resolution band.
+ */
+const RATIO_MEASUREMENT_FLOOR_MS = 5;
+
+/**
+ * Assert linear scaling between two timed runs on inputs that differ
+ * by 2×. When measurements are too small to be reliable, the ratio
+ * assertion is skipped (the absolute bound still fires elsewhere).
+ */
+function assertSubLinearRatio(elapsedSmall: number, elapsedLarge: number, label: string): void {
+  if (elapsedSmall < RATIO_MEASUREMENT_FLOOR_MS && elapsedLarge < RATIO_MEASUREMENT_FLOOR_MS) {
+    // Both runs completed faster than the noise floor — the ratio is
+    // not meaningful. The absolute <500ms bound elsewhere in this
+    // describe block still pins linearity; we skip rather than risk a
+    // flake on a genuinely-linear implementation.
+    return;
+  }
+  const ratio = elapsedLarge / Math.max(elapsedSmall, 0.001);
+  if (ratio >= LINEAR_RATIO_BOUND) {
+    throw new Error(
+      `${label}: ratio ${ratio.toFixed(2)}× exceeds bound ${LINEAR_RATIO_BOUND}× ` +
+        `(small=${elapsedSmall.toFixed(2)}ms, large=${elapsedLarge.toFixed(2)}ms)`,
+    );
+  }
+}
+
+describe('cobol-preprocessor RE_SET_TO_TRUE — linear time on pathological input', () => {
+  it('matches in <500ms on 50k repetitions of "A OF A " AND 100k/50k ratio is sub-linear when measurable', () => {
+    // 50k/100k repetitions chosen so timings exceed the
+    // RATIO_MEASUREMENT_FLOOR_MS noise floor on typical CI hardware.
+    // Pre-fix nested-quantifier shape would be exponential here; the
+    // post-fix `.+?` shape is linear (~2× when input doubles).
+    const inputSmall = 'SET ' + 'A OF A '.repeat(50_000) + 'TO TRUE';
+    const inputLarge = 'SET ' + 'A OF A '.repeat(100_000) + 'TO TRUE';
+    const elapsedSmall = timeRegex(RE_SET_TO_TRUE, inputSmall);
+    const elapsedLarge = timeRegex(RE_SET_TO_TRUE, inputLarge);
+    expect(RE_SET_TO_TRUE.exec(inputSmall)).not.toBeNull();
+    expect(elapsedSmall).toBeLessThan(500);
+    expect(elapsedLarge).toBeLessThan(500);
+    assertSubLinearRatio(elapsedSmall, elapsedLarge, 'RE_SET_TO_TRUE');
+  });
+
+  it('still matches a normal SET ... TO TRUE statement', () => {
+    const m = RE_SET_TO_TRUE.exec('SET WS-FLAG TO TRUE');
+    expect(m).not.toBeNull();
+    expect(m?.[1]).toBe('WS-FLAG');
+  });
+});
+
+describe('cobol-preprocessor RE_SET_INDEX — linear time on pathological input', () => {
+  it('rejects in <500ms on 50k tokens with no valid suffix AND 100k/50k ratio is sub-linear when measurable', () => {
+    // Forces backtracking against the (TO|UP\s+BY|DOWN\s+BY) alternation
+    // — the richer pathological surface of the two regexes.
+    const inputSmall = 'SET ' + 'A '.repeat(50_000) + 'X';
+    const inputLarge = 'SET ' + 'A '.repeat(100_000) + 'X';
+    const elapsedSmall = timeRegex(RE_SET_INDEX, inputSmall);
+    const elapsedLarge = timeRegex(RE_SET_INDEX, inputLarge);
+    expect(RE_SET_INDEX.exec(inputSmall)).toBeNull();
+    expect(elapsedSmall).toBeLessThan(500);
+    expect(elapsedLarge).toBeLessThan(500);
+    assertSubLinearRatio(elapsedSmall, elapsedLarge, 'RE_SET_INDEX');
+  });
+
+  it('still matches a normal SET INDEX statement', () => {
+    const m = RE_SET_INDEX.exec('SET WS-IDX TO 5');
+    expect(m).not.toBeNull();
+    expect(m?.[1]).toBe('WS-IDX');
+    expect(m?.[2]).toBe('TO');
+    expect(m?.[3]).toBe('5');
+  });
+});
+
+describe('rust-workspace parseCargoPackageName — linear-time line walk', () => {
+  it('extracts the package name in <500ms on 100k blank lines AND 200k/100k ratio is sub-linear when measurable', () => {
+    // 100k/200k blank lines chosen so timings exceed the
+    // RATIO_MEASUREMENT_FLOOR_MS noise floor. Earlier 10k/20k pairing
+    // produced sub-millisecond measurements where scheduler jitter
+    // dominated and the ratio became meaningless (a real macOS run
+    // saw 5.29× between two genuinely-linear sub-ms measurements).
+    const cargoTomlSmall =
+      '[package]\n' + '\n'.repeat(100_000) + 'name = "myrepo"\nversion = "0.1.0"\n';
+    const cargoTomlLarge =
+      '[package]\n' + '\n'.repeat(200_000) + 'name = "myrepo"\nversion = "0.1.0"\n';
+    const elapsedSmall = timeFn(() => parseCargoPackageName(cargoTomlSmall));
+    const elapsedLarge = timeFn(() => parseCargoPackageName(cargoTomlLarge));
+    expect(parseCargoPackageName(cargoTomlSmall)).toBe('myrepo');
+    expect(elapsedSmall).toBeLessThan(500);
+    expect(elapsedLarge).toBeLessThan(500);
+    assertSubLinearRatio(elapsedSmall, elapsedLarge, 'parseCargoPackageName');
+  });
+
+  it('returns null when [package] section is absent', () => {
+    expect(parseCargoPackageName('[workspace]\nmembers = ["a"]\n')).toBeNull();
+  });
+
+  it('stops at the next section header (does not pick up a name= from a later section)', () => {
+    const toml = '[package]\nversion = "1.0"\n[other]\nname = "wrong"\n';
+    expect(parseCargoPackageName(toml)).toBeNull();
+  });
+
+  it('extracts the name from a normal [package] section', () => {
+    const toml = '[package]\nname = "real-crate"\nversion = "0.1.0"\n';
+    expect(parseCargoPackageName(toml)).toBe('real-crate');
+  });
+});
+
+describe('cross-impact clampTimeout — bounds user-supplied impact timeouts', () => {
+  it('rejects negative and zero timeouts, returning MIN', () => {
+    expect(clampTimeout(0)).toBe(IMPACT_TIMEOUT_MIN_MS);
+    expect(clampTimeout(-1)).toBe(IMPACT_TIMEOUT_MIN_MS);
+    expect(clampTimeout(-999_999)).toBe(IMPACT_TIMEOUT_MIN_MS);
+  });
+
+  it('rejects NaN/Infinity, returning MIN', () => {
+    expect(clampTimeout(NaN)).toBe(IMPACT_TIMEOUT_MIN_MS);
+    expect(clampTimeout(Infinity)).toBe(IMPACT_TIMEOUT_MIN_MS);
+    expect(clampTimeout(-Infinity)).toBe(IMPACT_TIMEOUT_MIN_MS);
+  });
+
+  it('caps very large timeouts at MAX (5 minutes)', () => {
+    expect(clampTimeout(999_999_999)).toBe(IMPACT_TIMEOUT_MAX_MS);
+    expect(clampTimeout(IMPACT_TIMEOUT_MAX_MS + 1)).toBe(IMPACT_TIMEOUT_MAX_MS);
+  });
+
+  it('passes through a reasonable timeout unchanged (truncated to integer)', () => {
+    expect(clampTimeout(30_000)).toBe(30_000);
+    expect(clampTimeout(30_500.7)).toBe(30_500);
+  });
+
+  it('floors below-MIN positive values to MIN', () => {
+    expect(clampTimeout(50)).toBe(IMPACT_TIMEOUT_MIN_MS);
+    expect(clampTimeout(0.1)).toBe(IMPACT_TIMEOUT_MIN_MS);
+  });
+});
diff --git a/gitnexus/test/unit/vue-sfc-extractor.test.ts b/gitnexus/test/unit/vue-sfc-extractor.test.ts
index 5da73477b6..d26f2b9164 100644
--- a/gitnexus/test/unit/vue-sfc-extractor.test.ts
+++ b/gitnexus/test/unit/vue-sfc-extractor.test.ts
@@ -186,3 +186,55 @@ const x = 1;
     expect(components).toEqual(['MyComponent']);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Case-insensitive script-tag matching (CodeQL js/bad-tag-filter, PR #1330)
+// ---------------------------------------------------------------------------
+
+describe('extractVueScript — case-insensitive script-tag matching', () => {
+  it('extracts content from <SCRIPT> ... </SCRIPT> (uppercase)', () => {
+    // HTML tag names are case-insensitive per the spec; browsers and
+    // Vue's SFC parser accept any case. The extractor MUST mirror that
+    // — a strict lowercase regex would miss valid SFC content and
+    // re-open the CodeQL js/bad-tag-filter alert PR #1330 closed.
+    const vue = `<template>
+  <div>Hello</div>
+</template>
+
+<SCRIPT setup lang="ts">
+const greeting = 'hi';
+</SCRIPT>
+`;
+    const result = extractVueScript(vue);
+    expect(result).not.toBeNull();
+    expect(result!.scriptContent).toContain("const greeting = 'hi'");
+  });
+
+  it('extracts content from mixed-case <Script> ... </Script>', () => {
+    const vue = `<template>
+  <div>Hello</div>
+</template>
+
+<Script lang="ts">
+export default { name: 'Mixed' };
+</Script>
+`;
+    const result = extractVueScript(vue);
+    expect(result).not.toBeNull();
+    expect(result!.scriptContent).toContain("name: 'Mixed'");
+  });
+
+  it('handles whitespace AND uppercase together: </SCRIPT >', () => {
+    const vue = `<template>
+  <div>Hi</div>
+</template>
+
+<SCRIPT setup>
+const x = 1;
+</SCRIPT >
+`;
+    const result = extractVueScript(vue);
+    expect(result).not.toBeNull();
+    expect(result!.scriptContent).toContain('const x = 1');
+  });
+});
diff --git a/gitnexus/test/unit/web-ui-serving.test.ts b/gitnexus/test/unit/web-ui-serving.test.ts
index d3f0854227..bd1c7faaf2 100644
--- a/gitnexus/test/unit/web-ui-serving.test.ts
+++ b/gitnexus/test/unit/web-ui-serving.test.ts
@@ -2,6 +2,7 @@ import path from 'node:path';
 import http from 'node:http';
 import express from 'express';
 import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { _captureLogger } from '../../src/core/logger.js';
 
 const { accessMock } = vi.hoisted(() => ({
   accessMock: vi.fn(),
@@ -213,7 +214,7 @@ describe('resolveWebDistDir', () => {
   });
 
   it('warns on non-ENOENT errors but continues', async () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const cap = _captureLogger();
     accessMock.mockImplementation(async (p: string) => {
       if (p.includes('primary'))
         throw Object.assign(new Error('permission denied'), { code: 'EACCES' });
@@ -222,11 +223,16 @@ describe('resolveWebDistDir', () => {
     });
     const result = await resolveWebDistDir('/primary', '/fallback');
     expect(result).toBe('/fallback');
-    expect(warnSpy).toHaveBeenCalledWith(
-      expect.stringContaining('could not access web UI dir /primary'),
-      'permission denied',
-    );
-    warnSpy.mockRestore();
+    expect(
+      cap
+        .records()
+        .some(
+          (r) =>
+            String(r.msg ?? '').includes('could not access web UI dir /primary') &&
+            r.err === 'permission denied',
+        ),
+    ).toBe(true);
+    cap.restore();
   });
 
   it('prefers GITNEXUS_WEB_DIST env var when set', async () => {
diff --git a/gitnexus/vitest.config.ts b/gitnexus/vitest.config.ts
index 9330e86a5c..862357668c 100644
--- a/gitnexus/vitest.config.ts
+++ b/gitnexus/vitest.config.ts
@@ -60,6 +60,8 @@ export default defineConfig({
             'test/integration/augmentation.test.ts',
             'test/integration/staleness-and-stability.test.ts',
             'test/integration/lbug-lock-retry.test.ts',
+            'test/integration/lbug-open-retry.test.ts',
+            'test/integration/lbug-close-handle-release.test.ts',
             'test/integration/api-impact-e2e.test.ts',
             'test/integration/shape-check-regression.test.ts',
             'test/integration/java-class-impact.test.ts',
@@ -87,6 +89,8 @@ export default defineConfig({
             'test/integration/augmentation.test.ts',
             'test/integration/staleness-and-stability.test.ts',
             'test/integration/lbug-lock-retry.test.ts',
+            'test/integration/lbug-open-retry.test.ts',
+            'test/integration/lbug-close-handle-release.test.ts',
             'test/integration/api-impact-e2e.test.ts',
             'test/integration/shape-check-regression.test.ts',
             'test/integration/java-class-impact.test.ts',