gitnexus 1.6.10-rc.1 → 1.6.10-rc.11

package/README.md

@@ -43,13 +43,13 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 | **Claude Code**          | Yes | Yes    | Yes (PreToolUse + PostToolUse)                                                             | **Full**     |
 | **Cursor**               | Yes | Yes    | Yes (postToolUse, [manual install](../gitnexus-cursor-integration/README.md#hook-install)) | **Full**     |
 | **Antigravity** (Google) | Yes | Yes    | Yes (AfterTool, [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/))    | **Full**     |
-| **Codex**                | Yes | Yes    | —                                                                                          | MCP + Skills |
+| **Codex**                | Yes | Yes    | Yes (PreToolUse + PostToolUse, [Codex hooks](https://developers.openai.com/codex/hooks))   | **Full**     |
 | **OpenCode**             | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **CodeBuddy** (Tencent)  | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **Qoder** (Alibaba)      | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **Windsurf**             | Yes | —      | —                                                                                          | MCP          |
 
-> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
+> **Claude Code** and **Codex** get the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
 
 ### Community Integrations
 
@@ -71,12 +71,23 @@ claude mcp add gitnexus -- npx -y gitnexus@latest mcp
 claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp
 ```
 
-### Codex (full support — MCP + skills)
+### Codex (full support — MCP + skills + hooks)
 
 ```bash
 codex mcp add gitnexus -- npx -y gitnexus@latest mcp
 ```
 
+Codex hooks (PreToolUse graph enrichment + PostToolUse stale-index detection in `~/.codex/hooks.json`, [same schema as Claude Code](https://developers.openai.com/codex/hooks)) need the bundled adapter script, so they are installed by `gitnexus setup -c codex` rather than manually.
+
+Alternatively, install everything as a [Codex plugin](https://developers.openai.com/codex/plugins/build) (MCP + skills + hooks in one step):
+
+```bash
+codex plugin marketplace add abhigyanpatwari/GitNexus
+# then inside Codex: /plugins → install "GitNexus"
+```
+
+> **Codex notes:** SessionStart is intentionally not registered — Codex reads [AGENTS.md natively](https://developers.openai.com/codex/guides/agents-md), which already carries the GitNexus context block. Newly installed hooks need a one-time approval in Codex via `/hooks` before they run. Pick **one** install route (`gitnexus setup -c codex` **or** the plugin): plugin hooks load alongside `~/.codex/hooks.json`, so installing both can fire duplicate hooks per tool call.
+
 ### Cursor / Windsurf
 
 Add to `~/.cursor/mcp.json` (global — works for all projects):
@@ -152,6 +163,16 @@ GitNexus builds a complete knowledge graph of your codebase through a multi-phas
 
 The result is a **LadybugDB graph database** stored locally in `.gitnexus/` with full-text search and semantic embeddings.
 
+### Experimental community detection engine
+
+Community detection uses the bundled Graphology Leiden implementation by default. To test the #2337 Icebug migration path without changing default analyze behavior, set:
+
+```bash
+GITNEXUS_COMMUNITY_ENGINE=icebug npx gitnexus analyze
+```
+
+Supported values are `graphology`, `icebug`, and `auto`. The Icebug path is an experimental probe: GitNexus does not bundle an Icebug native package yet, and if a separately resolvable module is unavailable or its API does not match the expected `Graph.fromCSR` / `ParallelLeidenView` shape, analyze falls back to Graphology and reports the fallback in progress output. Today `auto` is behaviorally identical to `icebug`: both try Icebug and fall back to Graphology, while `graphology` skips the Icebug probe entirely.
+
 ## MCP Tools
 
 Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically:
@@ -209,6 +230,7 @@ gitnexus analyze [path]          # Index a repository (or update stale index)
 gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
 gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
+gitnexus embeddings install      # Fetch the optional local embedding stack on demand (--cuda, --force)
 gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
 gitnexus analyze --skip-skills   # Skip installing .claude/skills/gitnexus/ skill files
@@ -409,18 +431,40 @@ If `npm install -g gitnexus` fails on native modules:
 npm install -g gitnexus
 ```
 
+### Installation fails behind an HTTP proxy (`onnxruntime-node` postinstall)
+
+`onnxruntime-node`'s postinstall downloads optional CUDA GPU binaries from `api.nuget.org` — outside the npm registry, so registry mirrors don't cover it, and its proxy layer (`global-agent`) ignores the standard `HTTP_PROXY`/`HTTPS_PROXY` variables and rejects 302 redirects ([#2370](https://github.com/abhigyanpatwari/GitNexus/issues/2370)).
+
+Since the packages are optional dependencies, a failed download no longer breaks `npm install -g gitnexus` — npm skips the embedding stack and everything else works. The stack then **self-heals on demand**: the first `gitnexus analyze --embeddings` (or an explicit `gitnexus embeddings install`) fetches it through your configured npm registry — mirrors and proxies apply, no NuGet download involved — into `~/.gitnexus/embedding-runtime`.
+
+```bash
+# heal a proxy-degraded install manually (CPU embeddings; registry-only)
+gitnexus embeddings install
+
+# reinstall into the prefix even when the stack already resolves
+gitnexus embeddings install --force
+
+# CUDA GPU hosts: also fetch GPU binaries (NuGet; set the proxy global-agent reads)
+GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> gitnexus embeddings install --cuda
+```
+
+The prefix defaults to `~/.gitnexus/embedding-runtime`; set `GITNEXUS_EMBEDDING_RUNTIME_DIR` to install it elsewhere (e.g. a writable path in a container).
+
+> **Node requirement for the on-demand prefix:** the self-heal loads the prefixed packages via `module.registerHooks`, available on Node **≥ 22.15** (on the 22.x line) or **≥ 23.5** (on the 23.x line). On an older Node the packages install but can't be loaded from the prefix — reinstall them into the install itself instead (works on every supported Node): `ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus` (Windows: `set ONNXRUNTIME_NODE_INSTALL=skip && npm install -g gitnexus`). Skipping only the CUDA download keeps full CPU embeddings (CPU embeddings don't need it). Check the result any time with `gitnexus doctor` (Embeddings → Support line).
+
 ### Analyze warns about unavailable FTS or VECTOR extensions
 
-GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process `INSTALL` if `LOAD` fails and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
+GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process install if `LOAD` fails (a plain `INSTALL` to download a missing extension, escalating to `FORCE INSTALL` only when the `LOAD` error shows the existing file is broken or truncated, so a permanent non-file failure does not re-download on every run) and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
 
 Configure the behavior with these environment variables:
 
 | Variable                                     | Values                       | Default             | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | -------------------------------------------- | ---------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never` | `auto`              | `auto` runs one bounded INSTALL if LOAD fails. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer             | `15000`             | Wall-clock budget for the out-of-process `INSTALL` child before it is killed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never` | `auto`              | `auto` runs one bounded install if LOAD fails — a plain `INSTALL`, escalating to `FORCE INSTALL` only when the LOAD error shows the present extension file is broken. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely.                                                                                                                                                                                                                                                                                                                                                                               |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer             | `15000`             | Wall-clock budget for the out-of-process extension-install child before it is killed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `GITNEXUS_FTS_STEMMER`                       | supported LadybugDB stemmer  | `porter`            | Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` when that better matches repository comments and identifiers. Re-run `gitnexus analyze --repair-fts` after changing it.                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `GITNEXUS_FTS_CJK_SEGMENTATION`              | `none`, `bigram`             | `none`              | `bigram` inserts overlapping character-bigram boundaries into Chinese/Japanese Han-ideograph spans in `content`/`description` before FTS indexing, so LadybugDB's space-only tokenizer can see sub-phrase word boundaries. Scoped to CJK Unified Ideographs only — Japanese Hiragana/Katakana and Korean Hangul are not currently segmented. Unlike `GITNEXUS_FTS_STEMMER`, this rewrites stored text — enabling it on an already-indexed repo requires a full `gitnexus analyze --force`; neither `--repair-fts` nor a plain incremental `analyze` applies it to previously-indexed files. Set the same value wherever `analyze` and search-serving processes (CLI query, MCP server, web server) run. |
+| `GITNEXUS_COMMUNITY_ENGINE`                  | `graphology`, `icebug`, `auto` | `graphology`        | Community-detection engine used during analyze. `graphology` uses the bundled default path. `icebug` and `auto` currently behave identically: both try the experimental Icebug CSR path and fall back to Graphology if the optional native module is unavailable or incompatible.                                                                                                                                                                                                                                                                                                                                                         |
 | `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`          | integer `>= -1`              | `67108864` (64 MiB) | LadybugDB WAL auto-checkpoint threshold during analyze (bytes). Auto-checkpoint remains enabled; `-1` keeps Ladybug's stock ~16 MiB. Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments.                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 ```bash
@@ -502,17 +546,26 @@ After scope resolution, analyze prunes inert block-local value symbols (a functi
 
 Programmatic callers can pass `keepLocalValueSymbols: true` in `PipelineOptions` instead of setting the env var.
 
-### Hook augmentation/notifications are silently skipped
+### Hook augmentation and skip diagnostics
 
-The Claude Code / Antigravity hooks intentionally stay **silent** on normal skip
+The Claude Code / Antigravity hooks keep their **stderr** silent on normal skip
 paths so strict hook runners (e.g. Codex `PreToolUse`) never see unexpected
-output. A search may not be augmented — or a stale-index reminder may not appear
-on stderr — when the GitNexus MCP server owns the repo DB, when the DB-lock probe
-times out and fails closed, or when the index is already current.
-
-To see why a hook skipped, set `GITNEXUS_DEBUG=1` and re-run the action — the hook
-writes the reason (e.g. `[GitNexus] augment skipped: MCP server owns DB`) and the
-stale-index hint to its stderr:
+diagnostic output.
+
+When a GitNexus process holds the repo DB write lock (the common case — the MCP
+server is running, or the DB-lock probe timed out and failed closed), the local
+CLI `augment` can't run (LadybugDB is single-writer). Rather than drop the
+augmentation, the hook hands the agent a short, conditional MCP-query hint on
+stdout (the sanctioned `additionalContext` channel) — _"if the GitNexus MCP tools
+are live in this session, call `query` …"_ — so an agent that has the tools can
+still fetch graph-ranked context. The hint is throttled to at most once per repo
+per window (`GITNEXUS_MCP_HINT_THROTTLE_MS`, default 10 min; `0` disables), so an
+owner-locked session isn't nudged on every search. A stale-index reminder, or an
+already-current index, stays silent.
+
+To see why a hook skipped the CLI augment, set `GITNEXUS_DEBUG=1` and re-run the
+action — the hook writes the reason (e.g. `[GitNexus] augment skipped: MCP server
+owns DB`) and the stale-index hint to its stderr:
 
 ```bash
 GITNEXUS_DEBUG=1 <your command>   # surfaces hook skip/diagnostic reasons on stderr

package/dist/cli/analyze.js

@@ -27,8 +27,9 @@ import { cliError } from './cli-message.js';
 import { EMBEDDING_DIMS_ERROR, normalizeEmbeddingDims } from './embedding-dims.js';
 import { formatElapsed } from './format-elapsed.js';
 import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
-import { safeUrl } from '../core/embeddings/http-client.js';
-import { isLocalEmbeddingRuntimeBlockerMessage } from '../core/embeddings/runtime-support.js';
+import { isHttpEmbeddingDimsError, isHttpEmbeddingError, isHttpMode, safeUrl, } from '../core/embeddings/http-client.js';
+import { isLocalEmbeddingRuntimeBlockerMessage, isMissingLocalEmbeddingStackMessage, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
+import { ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS, getEmbeddingInstallTimeoutMs, getEmbeddingRuntimeDir, installEmbeddingRuntime, isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { warnIfNpm11NpxRisk } from './resolve-invocation.js';
 // Capture stderr.write at module load BEFORE anything (LadybugDB native
 // init, progress bar, console redirection) can monkey-patch it. The
@@ -797,6 +798,52 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         console.log('  Note: custom HTTP embeddings require BOTH --embedding-base-url and --embedding-model ' +
             '(or the matching env vars). Falling back to local ONNX embeddings.\n');
     }
+    // On-demand embedding runtime (#2370): when the optional stack was pruned at
+    // install time (proxy-blocked NuGet download in onnxruntime-node's
+    // postinstall), heal it here instead of failing later in the pipeline. The
+    // install goes through the user's npm registry config (mirrors/proxies
+    // apply) with --ignore-scripts, so no NuGet download is attempted. Runs
+    // before bar.start() like the sibling validations above.
+    if (embeddingsEnabled && !isHttpMode()) {
+        const resolved = resolveEmbeddingRuntime();
+        // Resolved-but-unloadable (a populated prefix on a Node with no
+        // module.registerHooks), or nothing installed on such a Node: fail fast with
+        // capability guidance instead of dying mid-pipeline over an unusable prefix
+        // or downloading a runtime the loader can't reach. A package-sourced stack
+        // never needs the hook, so it is excluded. --embeddings was explicitly
+        // requested and this failure is deterministic, so fail fast rather than
+        // silently degrading to BM25 (distinct from a transient install timeout).
+        if (!isPrefixRuntimeLoadable() && (resolved === null || resolved.source === 'runtime-prefix')) {
+            cliError(`  ${localEmbeddingPrefixUnloadableMessage().replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'local-embedding-stack-missing',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // On-demand embedding runtime (#2370): when the optional stack was pruned at
+        // install time (proxy-blocked NuGet download in onnxruntime-node's
+        // postinstall), heal it here instead of failing later in the pipeline. The
+        // install goes through the user's npm registry config (mirrors/proxies
+        // apply) with --ignore-scripts, so no NuGet download is attempted.
+        if (resolved === null) {
+            console.log(`  Local embedding runtime is not installed (optional packages were skipped at install time).\n` +
+                `  Downloading it now from your npm registry into ${getEmbeddingRuntimeDir()} …\n` +
+                `  (one-time; rerun manually anytime with \`gitnexus embeddings install\`)\n`);
+            try {
+                // Short deadline (env override still wins): analyze is interactive, so a
+                // blackholed proxy must not stall the whole index run for the 10-minute
+                // default — fail over to the guidance below instead.
+                await installEmbeddingRuntime({}, getEmbeddingInstallTimeoutMs(ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS));
+                console.log('  Embedding runtime installed.\n');
+            }
+            catch (err) {
+                cliError(`  Could not install the embedding runtime: ${err instanceof Error ? err.message : String(err)}\n\n` +
+                    `  ${localEmbeddingStackMissingMessage().replace(/\n/g, '\n  ')}\n`, { recoveryHint: 'local-embedding-stack-missing' });
+                process.exitCode = 1;
+                return;
+            }
+        }
+    }
     if (options.repairFts && options.force) {
         cliError('  Cannot combine `--repair-fts` with `--force`. ' +
             'Use `--repair-fts` for fast FTS-only repair, or `--force` for a full rebuild.\n');
@@ -1203,10 +1250,66 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             process.exitCode = 1;
             return;
         }
+        // The optional embedding stack (@huggingface/transformers → onnxruntime-node)
+        // was pruned at install time — usually a proxy-blocked NuGet download during
+        // onnxruntime-node's postinstall (#2370). Checked before the generic
+        // module-not-found "installation may be corrupt" hint below, which would
+        // otherwise misdiagnose a deliberate optional-dependency skip.
+        if (isMissingLocalEmbeddingStackMessage(msg)) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'local-embedding-stack-missing',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // Malformed GITNEXUS_EMBEDDING_DIMS env var (#2385). readConfig() throws a
+        // plain Error (a config mistake, not an endpoint failure), surfacing here from
+        // httpEmbed()->readConfig() inside the analysis run. Show a clean config
+        // message rather than a raw stack dump. The --embedding-dims CLI flag is
+        // validated up front (EMBEDDING_DIMS_ERROR); this covers the env-var path.
+        // Checked before the endpoint/HF branches: it is a plain Error, so
+        // isHttpEmbeddingError() is false and the HF network heuristic must not claim it.
+        if (isHttpEmbeddingDimsError(msg)) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'embedding-dims-invalid',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // Custom HTTP embedding endpoint failure (#2385). When a `--embedding-base-url`
+        // is configured, HTTP mode never downloads a model — so a failure talking to
+        // that endpoint must NOT show the huggingface-download guidance. Keyed on the
+        // error *type* (HttpEmbeddingError), not its message text, so it stays correct
+        // regardless of locale or wording. Checked before the HF branch, whose network
+        // heuristic (`fetch failed` / `ECONNREFUSED`) would otherwise also match a
+        // wrapped endpoint-connection error. The header is deliberately neutral: this
+        // type covers both never-reached failures (connection/timeout/DNS) and
+        // reached-but-failed ones (4xx/5xx, dimension/shape mismatch), so it must not
+        // assert "unreachable". The thrown `msg` carries the specific reason (and the
+        // masked URL where one applies), so it is surfaced verbatim.
+        if (isHttpEmbeddingError(err)) {
+            cliError(`  The custom embedding endpoint request failed.\n` +
+                `  ${msg.replace(/\n/g, '\n  ')}\n` +
+                `  Suggestions:\n` +
+                `    1. Verify the endpoint URL is reachable and running ` +
+                `(--embedding-base-url / GITNEXUS_EMBEDDING_URL: host, port, /v1 path).\n` +
+                `    2. Confirm the model name and embedding dimensions match what the endpoint serves.\n` +
+                `    3. Re-run without --embeddings to index without vectors.\n`, { recoveryHint: 'http-embedding-endpoint-error' });
+            process.exitCode = 1;
+            return;
+        }
+        // isHttpMode() is a pure presence probe (URL+MODEL) that never throws — a
+        // malformed GITNEXUS_EMBEDDING_DIMS is handled by the dims branch above — so
+        // no defensive try/catch is needed here (#2385).
+        const inHttpMode = isHttpMode();
         // 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')) {
+        // Gated on !inHttpMode: with a custom endpoint configured no model download
+        // is ever attempted, so a network error there is the endpoint's, handled by
+        // the HttpEmbeddingError branch above — never HF's (#2385).
+        if ((isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) &&
+            !inHttpMode) {
             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` +

package/dist/cli/cli-message.d.ts

@@ -12,7 +12,7 @@ import { type CliMessageKey, type CliMessageVars } from './i18n/index.js';
  * Consumers can import this type to narrow log-record `recoveryHint`
  * fields without restating the literal list.
  */
-export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'local-embedding-unsupported' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

package/dist/cli/doctor.d.ts

@@ -1,3 +1,4 @@
+import { type EmbeddingRuntimeResolution } from '../core/embeddings/runtime-install.js';
 export declare function displayWidth(value: string): number;
 export declare function padDisplayEnd(value: string, columns: number): string;
 /**
@@ -14,6 +15,10 @@ export declare function localEmbeddingDoctorStatus(opts: {
     httpMode: boolean;
     platform?: NodeJS.Platform;
     arch?: NodeJS.Architecture;
+    /** Injectable for tests; defaults to probing the real install. */
+    resolution?: EmbeddingRuntimeResolution | null;
+    /** Injectable for tests; defaults to this Node's registerHooks capability. */
+    prefixLoadable?: boolean;
 }): {
     status: string;
     detail: string | null;

package/dist/cli/doctor.js

@@ -1,9 +1,11 @@
 import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/capabilities.js';
 import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
 import { isHttpMode } from '../core/embeddings/http-client.js';
-import { getLocalEmbeddingRuntimeBlocker } from '../core/embeddings/runtime-support.js';
+import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
+import { isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { cudaRedirectDoctorStatus } from '../core/embeddings/onnxruntime-node-resolver.js';
-import { checkLbugNative } from '../core/lbug/native-check.js';
+import { checkLbugNative, probeFtsExtensionLoad } from '../core/lbug/native-check.js';
+import { diagnoseExtensionLoad } from '../core/lbug/extension-load-error.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
 function isCombiningMark(codePoint) {
@@ -64,6 +66,25 @@ export function localEmbeddingDoctorStatus(opts) {
     if (blocker) {
         return { status: `✗ local embeddings unavailable on ${platform}/${arch}`, detail: blocker };
     }
+    // The stack is an optionalDependency — npm prunes it when onnxruntime-node's
+    // postinstall can't download its CUDA binaries (proxy/firewall, #2370).
+    const resolution = opts.resolution !== undefined ? opts.resolution : resolveEmbeddingRuntime();
+    if (resolution === null) {
+        return {
+            status: '✗ optional embedding stack not installed',
+            detail: localEmbeddingStackMissingMessage(),
+        };
+    }
+    // A prefix-sourced stack needs module.registerHooks to load; on Node < 22.15 /
+    // < 23.5 it is present but unreachable (#2372). Report loadability, not bare
+    // presence, so the diagnostic stops claiming a ✓ the loader can't honour.
+    const prefixLoadable = opts.prefixLoadable ?? isPrefixRuntimeLoadable();
+    if (resolution.source === 'runtime-prefix' && !prefixLoadable) {
+        return {
+            status: '✗ embedding stack installed in the prefix but not loadable on this Node',
+            detail: localEmbeddingPrefixUnloadableMessage(),
+        };
+    }
     return { status: '✓ local embeddings supported', detail: null };
 }
 export const doctorCommand = async () => {
@@ -88,7 +109,24 @@ export const doctorCommand = async () => {
     console.log('');
     console.log(t('doctor.capabilities'));
     console.log(`  ${label('doctor.labels.graphStore', 18)}${capabilities.graph}`);
-    console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${capabilities.fts}`);
+    // Live LOAD probe, not the static platform capability — the static value
+    // said "available" while analyze failed to load the extension (#2374).
+    const ftsProbe = nativeCheck.ok
+        ? await probeFtsExtensionLoad()
+        : { loaded: false, reason: 'LadybugDB native module (lbugjs.node) failed to load' };
+    console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${ftsProbe.loaded ? 'available' : 'unavailable'}`);
+    if (!ftsProbe.loaded && ftsProbe.reason) {
+        console.log(`  ${padDisplayEnd('', 18)}${ftsProbe.reason}`);
+        // Add an actionable remedy for recognized failure classes (#2374). The
+        // Windows missing-dependency case is the point of this: the raw error 126
+        // ("specified module could not be found") is opaque, so name the fix (VC++
+        // redist, then OpenSSL) instead of leaving the user to reinstall in vain.
+        // `unknown`'s remedy is "run doctor", which would be circular here.
+        const { kind, remedy } = diagnoseExtensionLoad(ftsProbe.reason);
+        if (kind !== 'unknown') {
+            console.log(`  ${padDisplayEnd('', 18)}${remedy}`);
+        }
+    }
     console.log(`  ${label('doctor.labels.vectorIndex', 18)}${capabilities.vector}`);
     console.log(`  ${label('doctor.labels.semanticMode', 18)}${capabilities.semanticMode}`);
     // Surface the optional-extension install policy so offline users can see

package/dist/cli/editor-targets.js

@@ -102,6 +102,17 @@ export function getEditorTargets(home = os.homedir()) {
             needle: 'gitnexus-hook',
             scriptDir: path.join(home, '.claude', 'hooks', 'gitnexus'),
         },
+        {
+            id: 'codex',
+            label: 'Codex',
+            // Codex hooks use Claude Code's exact {hooks: {Event: [...]}} JSON shape
+            // and hookSpecificOutput response contract, in a dedicated hooks.json
+            // (https://developers.openai.com/codex/hooks).
+            settingsFile: path.join(home, '.codex', 'hooks.json'),
+            events: ['PreToolUse', 'PostToolUse'],
+            needle: 'gitnexus-hook',
+            scriptDir: path.join(home, '.codex', 'hooks', 'gitnexus'),
+        },
         {
             id: 'antigravity',
             label: 'Antigravity',

package/dist/cli/embeddings.d.ts

@@ -0,0 +1,12 @@
+export interface EmbeddingsInstallOptions {
+    cuda?: boolean;
+    force?: boolean;
+}
+/**
+ * `gitnexus embeddings install [--cuda] [--force]` — fetch the optional local
+ * embedding stack on demand (#2370). Goes through the user's npm registry
+ * config (mirrors/proxies apply); with --cuda it additionally runs
+ * onnxruntime-node's postinstall to download the CUDA GPU binaries from NuGet
+ * (set GLOBAL_AGENT_HTTPS_PROXY behind a proxy).
+ */
+export declare const embeddingsInstallCommand: (options?: EmbeddingsInstallOptions) => Promise<void>;

package/dist/cli/embeddings.js

@@ -0,0 +1,49 @@
+import { cliError, cliInfo, cliWarn } from './cli-message.js';
+import { getEmbeddingRuntimeDir, getEmbeddingStackSpecs, installEmbeddingRuntime, isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
+import { localEmbeddingPrefixUnloadableMessage } from '../core/embeddings/runtime-support.js';
+/**
+ * `gitnexus embeddings install [--cuda] [--force]` — fetch the optional local
+ * embedding stack on demand (#2370). Goes through the user's npm registry
+ * config (mirrors/proxies apply); with --cuda it additionally runs
+ * onnxruntime-node's postinstall to download the CUDA GPU binaries from NuGet
+ * (set GLOBAL_AGENT_HTTPS_PROXY behind a proxy).
+ */
+export const embeddingsInstallCommand = async (options = {}) => {
+    const resolved = resolveEmbeddingRuntime();
+    if (resolved?.source === 'package' && !options.force) {
+        cliInfo('The embedding stack is already installed with gitnexus itself — nothing to do.\n' +
+            '(Use --force to install a copy into the runtime prefix anyway.)');
+        return;
+    }
+    const specs = Object.entries(getEmbeddingStackSpecs())
+        .map(([name, spec]) => `${name}@${spec}`)
+        .join(', ');
+    cliInfo(`Installing ${specs} into ${getEmbeddingRuntimeDir()} …`);
+    cliInfo(options.cuda
+        ? 'CUDA mode: onnxruntime-node will download GPU binaries from NuGet ' +
+            '(set GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> behind a proxy).'
+        : 'CPU mode: install scripts are skipped — only your npm registry is contacted.');
+    try {
+        await installEmbeddingRuntime({ cuda: options.cuda, onOutput: (line) => cliInfo(`  ${line}`) });
+    }
+    catch (err) {
+        cliError(`${err instanceof Error ? err.message : String(err)}\n`, {
+            recoveryHint: 'local-embedding-stack-missing',
+        });
+        process.exitCode = 1;
+        return;
+    }
+    const postInstall = resolveEmbeddingRuntime();
+    if (postInstall === null) {
+        cliInfo('✗ Install completed but the stack still does not resolve — check the output above.');
+        process.exitCode = 1;
+        return;
+    }
+    if (postInstall.source === 'runtime-prefix' && !isPrefixRuntimeLoadable()) {
+        // The packages are in the prefix, but this Node has no module.registerHooks
+        // to load them — don't claim readiness the loader can't honour.
+        cliWarn(`${localEmbeddingPrefixUnloadableMessage()}\n`);
+        return;
+    }
+    cliInfo('✓ Embedding runtime installed. `gitnexus analyze --embeddings` is ready.');
+};

package/dist/cli/help-i18n.js

@@ -17,6 +17,8 @@ const COMMAND_DESCRIPTION_KEYS = {
     list: 'help.command.list.description',
     status: 'help.command.status.description',
     doctor: 'help.command.doctor.description',
+    embeddings: 'help.command.embeddings.description',
+    'embeddings install': 'help.command.embeddings.install.description',
     clean: 'help.command.clean.description',
     remove: 'help.command.remove.description',
     wiki: 'help.command.wiki.description',
@@ -143,6 +145,8 @@ const OPTION_DESCRIPTION_KEYS = {
     'eval-server|-p, --port <port>': 'help.option.port',
     'eval-server|--host <host>': 'help.option.evalServer.host',
     'eval-server|--idle-timeout <seconds>': 'help.option.evalServer.idleTimeout',
+    'embeddings install|--cuda': 'help.option.embeddings.install.cuda',
+    'embeddings install|--force': 'help.option.embeddings.install.force',
     'group create|--force': 'help.option.group.create.force',
     'group sync|--skip-embeddings': 'help.option.group.sync.skipEmbeddings',
     'group sync|--exact-only': 'help.option.group.sync.exactOnly',

package/dist/cli/i18n/en.d.ts

@@ -117,6 +117,8 @@ export declare const en: {
     readonly 'help.command.list.description': "List all indexed repositories";
     readonly 'help.command.status.description': "Show index status for current repo";
     readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+    readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
+    readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
     readonly 'help.command.clean.description': "Delete GitNexus index for current repo";
     readonly 'help.command.remove.description': "Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.";
     readonly 'help.command.wiki.description': "Generate repository wiki from knowledge graph";
@@ -220,6 +222,8 @@ export declare const en: {
     readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
     readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
     readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
+    readonly 'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)";
+    readonly 'help.option.embeddings.install.force': "Install into the runtime prefix even when the stack already resolves";
     readonly 'help.option.group.create.force': "Overwrite existing group";
     readonly 'help.option.group.sync.skipEmbeddings': "Exact + BM25 only (no embedding fallback)";
     readonly 'help.option.group.sync.exactOnly': "Exact match only";

package/dist/cli/i18n/en.js

@@ -117,6 +117,8 @@ export const en = {
     'help.command.list.description': 'List all indexed repositories',
     'help.command.status.description': 'Show index status for current repo',
     'help.command.doctor.description': 'Show runtime platform capabilities and embedding configuration',
+    'help.command.embeddings.description': 'Manage the on-demand local embedding runtime',
+    'help.command.embeddings.install.description': 'Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.',
     'help.command.clean.description': 'Delete GitNexus index for current repo',
     'help.command.remove.description': 'Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.',
     'help.command.wiki.description': 'Generate repository wiki from knowledge graph',
@@ -220,6 +222,8 @@ export const en = {
     'help.option.check.cycles': 'Detect circular imports and fail when any are found',
     'help.option.evalServer.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)',
     'help.option.evalServer.idleTimeout': 'Auto-shutdown after N seconds idle (0 = disabled)',
+    'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)",
+    'help.option.embeddings.install.force': 'Install into the runtime prefix even when the stack already resolves',
     'help.option.group.create.force': 'Overwrite existing group',
     'help.option.group.sync.skipEmbeddings': 'Exact + BM25 only (no embedding fallback)',
     'help.option.group.sync.exactOnly': 'Exact match only',

package/dist/cli/i18n/resources.d.ts

@@ -118,6 +118,8 @@ export declare const cliResources: {
         readonly 'help.command.list.description': "List all indexed repositories";
         readonly 'help.command.status.description': "Show index status for current repo";
         readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+        readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
+        readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
         readonly 'help.command.clean.description': "Delete GitNexus index for current repo";
         readonly 'help.command.remove.description': "Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.";
         readonly 'help.command.wiki.description': "Generate repository wiki from knowledge graph";
@@ -221,6 +223,8 @@ export declare const cliResources: {
         readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
         readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
         readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
+        readonly 'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)";
+        readonly 'help.option.embeddings.install.force': "Install into the runtime prefix even when the stack already resolves";
         readonly 'help.option.group.create.force': "Overwrite existing group";
         readonly 'help.option.group.sync.skipEmbeddings': "Exact + BM25 only (no embedding fallback)";
         readonly 'help.option.group.sync.exactOnly': "Exact match only";
@@ -360,6 +364,8 @@ export declare const cliResources: {
         'help.command.list.description': string;
         'help.command.status.description': string;
         'help.command.doctor.description': string;
+        'help.command.embeddings.description': string;
+        'help.command.embeddings.install.description': string;
         'help.command.clean.description': string;
         'help.command.remove.description': string;
         'help.command.wiki.description': string;
@@ -463,6 +469,8 @@ export declare const cliResources: {
         'help.option.check.cycles': string;
         'help.option.evalServer.host': string;
         'help.option.evalServer.idleTimeout': string;
+        'help.option.embeddings.install.cuda': string;
+        'help.option.embeddings.install.force': string;
         'help.option.group.create.force': string;
         'help.option.group.sync.skipEmbeddings': string;
         'help.option.group.sync.exactOnly': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -117,6 +117,8 @@ export declare const zhCN: {
     'help.command.list.description': string;
     'help.command.status.description': string;
     'help.command.doctor.description': string;
+    'help.command.embeddings.description': string;
+    'help.command.embeddings.install.description': string;
     'help.command.clean.description': string;
     'help.command.remove.description': string;
     'help.command.wiki.description': string;
@@ -220,6 +222,8 @@ export declare const zhCN: {
     'help.option.check.cycles': string;
     'help.option.evalServer.host': string;
     'help.option.evalServer.idleTimeout': string;
+    'help.option.embeddings.install.cuda': string;
+    'help.option.embeddings.install.force': string;
     'help.option.group.create.force': string;
     'help.option.group.sync.skipEmbeddings': string;
     'help.option.group.sync.exactOnly': string;

package/dist/cli/i18n/zh-CN.js

@@ -117,6 +117,8 @@ export const zhCN = {
     'help.command.list.description': '列出所有已索引仓库',
     'help.command.status.description': '显示当前仓库的索引状态',
     'help.command.doctor.description': '显示运行平台能力和嵌入配置',
+    'help.command.embeddings.description': '管理按需安装的本地嵌入运行时',
+    'help.command.embeddings.install.description': '按需安装本地嵌入组件（@huggingface/transformers + onnxruntime-node）。修复 npm 跳过可选包的安装（例如在 HTTP 代理后，#2370）。仅从你配置的 npm registry 下载 — 镜像和代理均生效。',
     'help.command.clean.description': '删除当前仓库的 GitNexus 索引',
     'help.command.remove.description': '删除已注册仓库的 GitNexus 索引（按别名、名称或绝对路径）。与 `clean` 不同，不要求位于仓库内；未知目标会幂等处理。',
     'help.command.wiki.description': '从知识图谱生成仓库 Wiki',
@@ -220,6 +222,8 @@ export const zhCN = {
     'help.option.check.cycles': '检测循环导入，并在发现循环时失败',
     'help.option.evalServer.host': '绑定地址（默认：127.0.0.1；用 0.0.0.0 暴露到所有网卡）',
     'help.option.evalServer.idleTimeout': '空闲 N 秒后自动关闭（0 = 禁用）',
+    'help.option.embeddings.install.cuda': '同时下载 CUDA GPU 二进制文件（运行 onnxruntime-node 的 NuGet postinstall；代理后请设置 GLOBAL_AGENT_HTTPS_PROXY）',
+    'help.option.embeddings.install.force': '即使嵌入组件已可解析，也强制安装到运行时目录',
     'help.option.group.create.force': '覆盖现有仓库组',
     'help.option.group.sync.skipEmbeddings': '仅使用 exact + BM25（不使用嵌入回退）',
     'help.option.group.sync.exactOnly': '仅精确匹配',