gitnexus 1.6.8-rc.3 → 1.6.8-rc.30

package/README.md

@@ -34,7 +34,7 @@ That's it. This indexes the codebase, installs agent skills, registers Claude Co
 
 To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
 
-`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
+`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once. To configure only selected integrations, pass `--coding-agent`/`-c` with a comma-separated list or repeat the option, for example `gitnexus setup -c cursor,codex`.
 
 ### Editor Support
 
@@ -134,7 +134,7 @@ Your AI agent gets these tools automatically:
 | `rename`         | Multi-file coordinated rename with graph + text search           | Optional     |
 | `cypher`         | Raw Cypher graph queries                                         | Optional     |
 
-> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({query: "auth", repo: "my-app"})`.
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`.
 
 ## MCP Resources
 
@@ -158,7 +158,7 @@ Your AI agent gets these tools automatically:
 ## CLI Commands
 
 ```bash
-gitnexus setup                   # Configure MCP for your editors (one-time)
+gitnexus setup                   # Configure MCP for detected editors (one-time; use -c to select)
 gitnexus uninstall               # Preview removal of GitNexus MCP/skills/hooks (add --force to apply)
 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
@@ -436,6 +436,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
+
+The Claude Code / Antigravity hooks intentionally stay **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:
+
+```bash
+GITNEXUS_DEBUG=1 <your command>   # surfaces hook skip/diagnostic reasons on stderr
+```
+
+Only `GITNEXUS_DEBUG=1` and `GITNEXUS_DEBUG=true` enable diagnostics; every other
+value (including `0` and `false`) is treated as off. Diagnostics go to stderr
+only — the hook's structured stdout (the JSON the agent consumes) is unaffected.
+
 ## Privacy
 
 - All processing happens locally on your machine

package/dist/_shared/scope-resolution/parsed-file.d.ts

@@ -96,5 +96,26 @@ export interface ParsedFile {
      * side effects — the contract default) leave this undefined.
      */
     readonly captureSideChannel?: unknown;
+    /**
+     * Per-function control-flow graphs for this file (#2081 M1, PDG/taint
+     * substrate). A DISTINCT field from {@link captureSideChannel} — different
+     * producer, consumer, and lifecycle: the worker builds it from the
+     * tree-sitter AST via `LanguageProvider.cfgVisitor` (only on a `--pdg` run),
+     * and scope-resolution emits BasicBlock nodes + CFG edges from it while the
+     * disk-backed ParsedFile store is still live (it is NOT a capture-time
+     * marker the resolver restores into module maps). Kept separate so a future
+     * change to either channel's shape invalidates independently.
+     *
+     * Shared / ingestion code treats this as opaque (`unknown`) per AGENTS.md.
+     * Concretely it is a `readonly FunctionCfg[]` (see
+     * `core/ingestion/cfg/types.ts`) — plain JSON-serializable data (no AST
+     * refs, no class instances) so it round-trips through the parse cache and
+     * the `parsedfile-store` (whose interning reviver keys on `nodeId`, which
+     * these blocks/edges deliberately lack).
+     *
+     * Optional: `undefined` on non-`--pdg` runs and for languages with no
+     * `cfgVisitor` — the default for every run today.
+     */
+    readonly cfgSideChannel?: unknown;
 }
 //# sourceMappingURL=parsed-file.d.ts.map

package/dist/_shared/scope-resolution/parsed-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parsed-file.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/parsed-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC"}
+{"version":3,"file":"parsed-file.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/parsed-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC"}

package/dist/_shared/scope-resolution/symbol-definition.d.ts

@@ -54,6 +54,10 @@ export interface SymbolDefinition {
      *  Currently used by C++ overload ranking to exclude explicit constructors
      *  from implicit user-defined conversion candidates. */
     isExplicit?: boolean;
+    /** True when the callable is declared unavailable (for example C++ `= delete`).
+     *  Unavailable callables still participate in overload selection, but a
+     *  selected unavailable target must suppress edge emission. */
+    isDeleted?: boolean;
     /** Links Method/Constructor/Property to owning Class/Struct/Trait nodeId */
     ownerId?: string;
     /** #1982/#1993: bridge-held enclosing-namespace path (e.g. `NS1`, `Outer.Inner`)

package/dist/_shared/scope-resolution/symbol-definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-definition.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/symbol-definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACjE,4CAA4C;IAC5C,WAAW,EAAE,OAAO,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;IAC3E,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB;;+FAE2F;IAC3F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;iHAC6G;IAC7G,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;uFACmF;IACnF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;4FACwF;IACxF,oBAAoB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC5C,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;;;;;yEAKqE;IACrE,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;4DAEwD;IACxD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;iEAO6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B"}
+{"version":3,"file":"symbol-definition.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/symbol-definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACjE,4CAA4C;IAC5C,WAAW,EAAE,OAAO,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;IAC3E,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB;;+FAE2F;IAC3F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;iHAC6G;IAC7G,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;uFACmF;IACnF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;4FACwF;IACxF,oBAAoB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC5C,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;;;;;yEAKqE;IACrE,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;4DAEwD;IACxD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;mEAE+D;IAC/D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;iEAO6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B"}

package/dist/cli/ai-context.js

@@ -134,8 +134,9 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 - **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
 - **MUST run \`detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: \`detect_changes({scope: "compare", base_ref: ${JSON.stringify(markdownSafeBranch(defaultBranch))}})\`.
 - **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
-- When exploring unfamiliar code, use \`query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When exploring unfamiliar code, use \`query({search_query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
 - When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`context({name: "symbolName"})\`.
+- For security review, \`explain({target: "fileOrSymbol"})\` lists taint findings (source→sink flows; needs \`analyze --pdg\`).
 
 ## Never Do
 

package/dist/cli/analyze-config.js

@@ -63,6 +63,7 @@ const KEY_SPECS = {
     skipContextFiles: { target: 'skipAgentsMd', kind: 'boolean' },
     skipAiContext: { target: 'skipAgentsMd', kind: 'boolean' },
     skipSkills: { target: 'skipSkills', kind: 'boolean' },
+    pdg: { target: 'pdg', kind: 'boolean' },
     indexOnly: { target: 'indexOnly', kind: 'boolean' },
     stats: { target: 'stats', kind: 'boolean' },
     noStats: { target: 'stats', kind: 'boolean-negate' },
@@ -78,6 +79,22 @@ const KEY_SPECS = {
     embeddingBatchSize: { target: 'embeddingBatchSize', kind: 'numeric-string' },
     embeddingSubBatchSize: { target: 'embeddingSubBatchSize', kind: 'numeric-string' },
     embeddingDevice: { target: 'embeddingDevice', kind: 'string' },
+    // #1589/#1852 residual — extra fetch-wrapper function names to treat as HTTP
+    // consumers. The auto-detector only flags functions that call the bare global
+    // `fetch()`; a wrapper built on axios / a custom client, or named outside the
+    // built-in convention set, is otherwise invisible to route_map consumers.
+    // Listing it here adds it to the cross-file consumer scan.
+    fetchWrappers: { target: 'fetchWrappers', kind: 'string-array' },
+    // Auth token AND dims are intentionally CLI/env-only — no embeddingAuthToken
+    // or embeddingDims key here:
+    //   - the token keeps secrets out of a committed .gitnexusrc;
+    //   - dims cannot take effect from .gitnexusrc anyway — schema.ts reads
+    //     GITNEXUS_EMBEDDING_DIMS at module-load (before .gitnexusrc is loaded in
+    //     analyzeCommandImpl), so a config value would size nothing and silently
+    //     mismatch the vector column. Use --embedding-dims or GITNEXUS_EMBEDDING_DIMS.
+    // (URL/MODEL are safe as config keys: they are read lazily at runtime, not at module-load.)
+    embeddingBaseUrl: { target: 'embeddingBaseUrl', kind: 'string' },
+    embeddingModel: { target: 'embeddingModel', kind: 'string' },
 };
 /** Top-level container key for the nested form; not itself an `AnalyzeOptions` field. */
 const NESTED_KEY = 'analyze';
@@ -195,6 +212,39 @@ const normalizeValue = (kind, value, key) => {
             }
             return trimmed;
         }
+        case 'string-array': {
+            // Generic shared validator — `source` already names the config key, so
+            // messages here stay key-agnostic (no fetch-wrapper coupling in the
+            // shared normalizer; #1589/#1852 review F7).
+            if (!Array.isArray(value)) {
+                throw new GitNexusRcError(`${source} must be an array of strings.`);
+            }
+            const names = [];
+            for (const item of value) {
+                if (typeof item !== 'string') {
+                    throw new GitNexusRcError(`${source} entries must all be strings.`);
+                }
+                const trimmed = item.trim();
+                if (!trimmed) {
+                    throw new GitNexusRcError(`${source} entries must not be empty.`);
+                }
+                assertNoHiddenChars(trimmed, source);
+                // Values may be interpolated into a RegExp downstream. Restrict to
+                // identifier / member-access shapes so a config value can never smuggle
+                // regex metacharacters into a consumer.
+                if (!/^[A-Za-z_$][A-Za-z0-9_$.]*$/.test(trimmed)) {
+                    throw new GitNexusRcError(`${source} entry "${trimmed}" must be an identifier or member name ` +
+                        `(letters, digits, _, $, . — e.g. "client.get").`);
+                }
+                names.push(trimmed);
+            }
+            if (names.length === 0) {
+                throw new GitNexusRcError(`${source} must list at least one string.`);
+            }
+            // De-duplicate and cap to a sane bound so a pathological config cannot
+            // blow up the consumer scan's alternation.
+            return Array.from(new Set(names)).slice(0, 100);
+        }
         case 'numeric-string': {
             // Mirror Commander's contract: these options reach the existing CLI
             // validation as strings. Accept a JSON number or a string; normalize to a

package/dist/cli/analyze.d.ts

@@ -37,6 +37,12 @@ export interface AnalyzeOptions {
     verbose?: boolean;
     /** Skip AGENTS.md and CLAUDE.md gitnexus block updates. */
     skipAgentsMd?: boolean;
+    /**
+     * Build the control-flow-graph / PDG substrate (#2081 M1). Opt-in; off by
+     * default. Threaded to both the worker (CFG build) and scope-resolution
+     * (BasicBlock/CFG emit).
+     */
+    pdg?: boolean;
     /**
      * Stats inclusion in AGENTS.md and CLAUDE.md.
      *
@@ -58,6 +64,14 @@ export interface AnalyzeOptions {
      * before being threaded into the generated AGENTS.md / CLAUDE.md content.
      */
     defaultBranch?: string;
+    /**
+     * Index-branch selector (#2106). From `--branch`. Distinct from
+     * `defaultBranch` (cosmetic base_ref): this routes the index to a per-branch
+     * slot. NOT sourced from `.gitnexusrc` — the `.gitnexusrc` `branch` key is an
+     * alias for `defaultBranch` and must not change index placement. Defaults to
+     * the checked-out branch inside `runFullAnalysis` when omitted.
+     */
+    branch?: string;
     /** Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills). */
     indexOnly?: boolean;
     /** Index the folder even when no .git directory is present. */
@@ -93,6 +107,22 @@ export interface AnalyzeOptions {
     embeddingBatchSize?: string;
     embeddingSubBatchSize?: string;
     embeddingDevice?: string;
+    /**
+     * Extra fetch-wrapper function names to treat as HTTP consumers (#1589/#1852
+     * residual). Supplied via `.gitnexusrc` `fetchWrappers: [...]`. Threaded into
+     * the routes phase, where the cross-file consumer scan unions them with the
+     * auto-detected `fetch()` wrappers so a custom/axios-based wrapper named
+     * outside the built-in convention still produces `route_map` consumers.
+     */
+    fetchWrappers?: string[];
+    /** OpenAI-compatible embeddings base URL (incl. /v1). Overrides GITNEXUS_EMBEDDING_URL. */
+    embeddingBaseUrl?: string;
+    /** Embedding model name. Overrides GITNEXUS_EMBEDDING_MODEL. */
+    embeddingModel?: string;
+    /** Bearer token for the embeddings endpoint. Overrides GITNEXUS_EMBEDDING_API_KEY. Never logged. */
+    embeddingAuthToken?: string;
+    /** Embedding vector dimensions (positive integer string). Overrides GITNEXUS_EMBEDDING_DIMS. */
+    embeddingDims?: string;
 }
 /**
  * Whether the post-index skill step should run.

package/dist/cli/analyze.js

@@ -23,8 +23,10 @@ import { warnMissingOptionalGrammars, getOptionalGrammarExtensions } from './opt
 import { glob } from 'glob';
 import fs from 'fs/promises';
 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 { warnIfNpm11NpxRisk } from './resolve-invocation.js';
 // Capture stderr.write at module load BEFORE anything (LadybugDB native
@@ -446,6 +448,10 @@ const ANALYZE_CLI_ENV_KEYS = [
     'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
     'GITNEXUS_EMBEDDING_DEVICE',
     'GITNEXUS_ANALYZE_PROGRESS_ACTIVE',
+    'GITNEXUS_EMBEDDING_URL',
+    'GITNEXUS_EMBEDDING_MODEL',
+    'GITNEXUS_EMBEDDING_API_KEY',
+    'GITNEXUS_EMBEDDING_DIMS',
 ];
 const snapshotAnalyzeEnv = () => {
     const snap = {};
@@ -551,6 +557,21 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             return;
         }
     }
+    // Validate the index-branch selector (#2106) the same way, so a malformed
+    // `--branch` exits before any expensive analysis starts. Capture the TRIMMED
+    // return so a whitespace-padded value (e.g. " feature" from shell completion)
+    // normalizes before the checked-out-branch mismatch guard and slug — otherwise
+    // it would false-reject on-branch or create a ghost index when detached.
+    if (cliOptions?.branch !== undefined) {
+        try {
+            cliOptions.branch = validateBranchName(cliOptions.branch, '--branch');
+        }
+        catch (err) {
+            cliError(`  ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+    }
     // ── Load .gitnexusrc and merge: CLI flags override config (#243) ───
     // Parse/validate before the progress bar so a malformed config produces an
     // actionable error and exits before any expensive analysis starts.
@@ -675,6 +696,95 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         }
         process.env.GITNEXUS_EMBEDDING_DEVICE = options.embeddingDevice;
     }
+    // --- Custom HTTP embedding endpoint flags (override GITNEXUS_EMBEDDING_* env vars) ---
+    const anyHttpEmbedFlag = options.embeddingBaseUrl !== undefined ||
+        options.embeddingModel !== undefined ||
+        options.embeddingAuthToken !== undefined ||
+        options.embeddingDims !== undefined;
+    if (options.embeddingBaseUrl !== undefined) {
+        const url = options.embeddingBaseUrl.trim();
+        if (url.length === 0) {
+            cliError('  --embedding-base-url must not be empty.\n');
+            process.exitCode = 1;
+            return;
+        }
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            cliError(`  --embedding-base-url is not a valid URL: "${url}".\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            cliError('  --embedding-base-url must use http:// or https://.\n');
+            process.exitCode = 1;
+            return;
+        }
+        // http-client strips trailing slashes; store as given (trimmed).
+        process.env.GITNEXUS_EMBEDDING_URL = url;
+    }
+    if (options.embeddingModel !== undefined) {
+        const model = options.embeddingModel.trim();
+        if (model.length === 0) {
+            cliError('  --embedding-model must not be empty.\n');
+            process.exitCode = 1;
+            return;
+        }
+        process.env.GITNEXUS_EMBEDDING_MODEL = model;
+    }
+    if (options.embeddingAuthToken !== undefined) {
+        const token = options.embeddingAuthToken.trim();
+        if (token.length === 0) {
+            cliError('  --embedding-auth-token must not be empty.\n');
+            process.exitCode = 1;
+            return;
+        }
+        // Never log the token value.
+        process.env.GITNEXUS_EMBEDDING_API_KEY = token;
+    }
+    // Validate + normalize dims through the same shared helper the preAction
+    // hook uses, so the CLI path, this direct/programmatic-call path, schema.ts
+    // (parseInt) and http-client (/^\d+$/) all agree on one canonical value.
+    if (options.embeddingDims !== undefined) {
+        const dims = normalizeEmbeddingDims(options.embeddingDims);
+        if (dims === null) {
+            cliError(`  ${EMBEDDING_DIMS_ERROR}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        process.env.GITNEXUS_EMBEDDING_DIMS = dims;
+    }
+    // Custom-endpoint UX, emitting at most ONE message that reflects THIS run's
+    // intent (not ambient env). Order matters — the first matching branch wins:
+    //   1. flags given but --embeddings absent: the endpoint won't be used, so
+    //      say only that (no contradictory "Using…" line).
+    //   2. embeddings enabled + a complete endpoint (flags or env): confirm it,
+    //      masking the URL via safeUrl() since a base URL may carry credentials
+    //      in userinfo (http://user:pass@host) or a query token (?api_key=…)
+    //      that must not land in stdout/CI logs. The auth token is never printed.
+    //   3. embeddings enabled but only one of URL/MODEL supplied via flags:
+    //      http-client.isHttpMode() needs BOTH, so warn about the fallback.
+    // Gating on embeddingsEnabled also stops the old behaviour of printing
+    // "Using custom embedding endpoint" on every analyze run whenever the env
+    // vars happened to be set.
+    if (anyHttpEmbedFlag && !embeddingsEnabled) {
+        console.log('  Note: --embedding-* flags only apply when --embeddings is also passed; ' +
+            'no embeddings will be generated this run.\n');
+    }
+    else if (embeddingsEnabled &&
+        process.env.GITNEXUS_EMBEDDING_URL &&
+        process.env.GITNEXUS_EMBEDDING_MODEL) {
+        console.log(`  Using custom embedding endpoint: ${safeUrl(process.env.GITNEXUS_EMBEDDING_URL)} ` +
+            `(model: ${process.env.GITNEXUS_EMBEDDING_MODEL})\n`);
+    }
+    else if (embeddingsEnabled &&
+        anyHttpEmbedFlag &&
+        (process.env.GITNEXUS_EMBEDDING_URL || process.env.GITNEXUS_EMBEDDING_MODEL)) {
+        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');
+    }
     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');
@@ -826,9 +936,15 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             skipGit: options.skipGit,
             skipAgentsMd,
             skipSkills,
+            // CFG/PDG substrate opt-in (#2081 M1) — threaded to both sinks downstream.
+            pdg: options.pdg === true,
             // Resolved default branch (CLI > .gitnexusrc > auto-detect > "main")
             // threaded into the generated regression-compare example (#243).
             defaultBranch: resolvedDefaultBranch,
+            // Index-branch selector (#2106). Read straight from the CLI flag (not
+            // the .gitnexusrc-merged options) so the cosmetic defaultBranch config
+            // can never change index placement. Undefined → auto-detect in pipeline.
+            branch: cliOptions?.branch,
             // commander.js `.option('--no-stats', …)` registers the flag as
             // `options.stats` (boolean, default true; `false` when the user
             // passed --no-stats). Reading `options.noStats` here returns
@@ -845,6 +961,9 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             // GITNEXUS_WORKER_POOL_SIZE env mutation. `undefined` defers to the
             // env / auto-formula fallback inside the pipeline.
             workerPoolSize,
+            // Extra fetch-wrapper names from `.gitnexusrc` (#1589/#1852 residual);
+            // forwarded to the routes phase consumer scan.
+            fetchWrappers: options.fetchWrappers,
         }, {
             onProgress: (_phase, percent, message) => {
                 updateBar(percent, message);
@@ -863,13 +982,19 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             // preserving the rest of the block (incl. --skills community rows). No-op
             // when the value already matches, so a routine up-to-date run is silent
             // (#1996 tri-review P2).
+            // Only refresh the repo-root AGENTS.md/CLAUDE.md base_ref for the
+            // PRIMARY/flat index (#2106 R2). A non-primary branch's up-to-date
+            // analyze must not churn the committed AGENTS.md — this mirrors the
+            // in-pipeline `if (!placement.branch)` gate around generateAIContextFiles.
             let baseRefRefreshed = [];
-            try {
-                const { refreshBaseRefLine } = await import('./ai-context.js');
-                baseRefRefreshed = (await refreshBaseRefLine(repoPath, resolvedDefaultBranch, { skipAgentsMd })).files;
-            }
-            catch {
-                /* best-effort — never fail the fast path over a context refresh */
+            if (result.isPrimaryBranch !== false) {
+                try {
+                    const { refreshBaseRefLine } = await import('./ai-context.js');
+                    baseRefRefreshed = (await refreshBaseRefLine(repoPath, resolvedDefaultBranch, { skipAgentsMd })).files;
+                }
+                catch {
+                    /* best-effort — never fail the fast path over a context refresh */
+                }
             }
             clearInterval(elapsedTimer);
             process.removeListener('SIGINT', sigintHandler);

package/dist/cli/clean.d.ts

@@ -8,4 +8,5 @@ export declare const cleanCommand: (options?: {
     force?: boolean;
     all?: boolean;
     lbugSidecars?: boolean;
+    branch?: string;
 }) => Promise<void>;

package/dist/cli/clean.js

@@ -7,10 +7,52 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { logger } from '../core/logger.js';
-import { findRepo, unregisterRepo, listRegisteredRepos, assertSafeStoragePath, UnsafeStoragePathError, } from '../storage/repo-manager.js';
+import { findRepo, unregisterRepo, listRegisteredRepos, assertSafeStoragePath, getStoragePaths, removeBranchIndex, UnsafeStoragePathError, } from '../storage/repo-manager.js';
 import { cleanQuarantinedMissingShadowWals, inspectLbugSidecars, listQuarantinedMissingShadowWals, } from '../core/lbug/sidecar-recovery.js';
 import { t } from './i18n/index.js';
 export const cleanCommand = async (options) => {
+    // --branch <name>: remove a single non-primary branch's index (#2106 R7).
+    // Resolve against the RECORDED branches[] summary (never by slugging the
+    // user's raw input, which can disagree with the index-time-sanitized label).
+    if (options?.branch) {
+        const cwd = process.cwd();
+        const repo = await findRepo(cwd);
+        if (!repo) {
+            console.log(t('clean.notFoundHere'));
+            return;
+        }
+        const entries = await listRegisteredRepos();
+        const entry = entries.find((e) => path.resolve(e.path) === path.resolve(repo.repoPath));
+        const summary = entry?.branches?.find((b) => b.branch === options.branch);
+        if (!summary) {
+            console.log(t('clean.branchNotIndexed', { branch: options.branch }));
+            return;
+        }
+        const { storagePath, lbugPath } = getStoragePaths(repo.repoPath, summary.branch);
+        const branchDir = path.dirname(lbugPath);
+        // Safety guard: the target MUST live under <repo>/.gitnexus/branches/.
+        // assertSafeStoragePath only validates the flat `<repo>/.gitnexus`, so this
+        // is a dedicated branches-sub-dir check before any destructive fs.rm.
+        const branchesRoot = path.join(storagePath, 'branches') + path.sep;
+        if (!branchDir.startsWith(branchesRoot)) {
+            logger.error(`Refusing to clean branch index outside .gitnexus/branches: ${branchDir}`);
+            return;
+        }
+        if (!options.force) {
+            console.log(t('clean.deleteBranch', { branch: summary.branch, path: branchDir }));
+            console.log(`\n${t('common.runForceConfirm')}`);
+            return;
+        }
+        try {
+            await fs.rm(branchDir, { recursive: true, force: true });
+            await removeBranchIndex(repo.repoPath, summary.branch);
+            console.log(t('clean.deletedBranch', { branch: summary.branch }));
+        }
+        catch (err) {
+            logger.error({ err }, 'Failed to delete branch index:');
+        }
+        return;
+    }
     if (options?.lbugSidecars) {
         const cwd = process.cwd();
         const repo = await findRepo(cwd);

package/dist/cli/embedding-dims.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Strict positive-integer normalization for the `--embedding-dims` flag /
+ * `GITNEXUS_EMBEDDING_DIMS` value.
+ *
+ * Single source of truth shared by two write paths:
+ *   1. the `analyze` `preAction` hook (CLI path) — it must set the env var
+ *      BEFORE `schema.ts` reads `GITNEXUS_EMBEDDING_DIMS` at module-load time
+ *      (the static import chain `analyze.ts → run-analyze.ts → schema.ts`
+ *      bakes `FLOAT[dims]` into the vector-table DDL), and
+ *   2. `analyzeCommandImpl` (direct / programmatic-call path, which bypasses
+ *      the commander hook).
+ *
+ * Keep this module dependency-free. `index.ts` imports it eagerly, so pulling
+ * in anything that transitively loads `schema.ts` (e.g. `analyze.ts`) — or
+ * even `cli-message.ts`, which drags in the logger + i18n — would defeat the
+ * lazy `import('./analyze.js')` the hook exists to enable. Callers print the
+ * error themselves (the hook to stderr, the impl via `cliError`).
+ *
+ * Trim-then-validate, matching the sibling URL/MODEL/TOKEN flags: surrounding
+ * whitespace is tolerated, but the remaining value must be all digits and
+ * `> 0`. This rejects scientific notation (`1e3`), hex (`0x10`), fractions
+ * (`3.5`), signs (`+5`/`-5`), and trailing junk (`4096x`) so the three
+ * downstream readers — `schema.ts` (`parseInt`), `http-client.ts` (`/^\d+$/`),
+ * and this helper — all agree on one canonical value. Without it, `1e3` parsed
+ * to `FLOAT[1]` at module-load but requested 1000-dim vectors at runtime.
+ */
+/** Shared error message so both call sites surface identical wording. */
+export declare const EMBEDDING_DIMS_ERROR = "--embedding-dims must be a positive integer.";
+/**
+ * Returns the canonical positive-integer string (e.g. `"007"` → `"7"`), or
+ * `null` when the input is not a strict positive integer.
+ */
+export declare const normalizeEmbeddingDims: (raw: string) => string | null;

package/dist/cli/embedding-dims.js

@@ -0,0 +1,39 @@
+/**
+ * Strict positive-integer normalization for the `--embedding-dims` flag /
+ * `GITNEXUS_EMBEDDING_DIMS` value.
+ *
+ * Single source of truth shared by two write paths:
+ *   1. the `analyze` `preAction` hook (CLI path) — it must set the env var
+ *      BEFORE `schema.ts` reads `GITNEXUS_EMBEDDING_DIMS` at module-load time
+ *      (the static import chain `analyze.ts → run-analyze.ts → schema.ts`
+ *      bakes `FLOAT[dims]` into the vector-table DDL), and
+ *   2. `analyzeCommandImpl` (direct / programmatic-call path, which bypasses
+ *      the commander hook).
+ *
+ * Keep this module dependency-free. `index.ts` imports it eagerly, so pulling
+ * in anything that transitively loads `schema.ts` (e.g. `analyze.ts`) — or
+ * even `cli-message.ts`, which drags in the logger + i18n — would defeat the
+ * lazy `import('./analyze.js')` the hook exists to enable. Callers print the
+ * error themselves (the hook to stderr, the impl via `cliError`).
+ *
+ * Trim-then-validate, matching the sibling URL/MODEL/TOKEN flags: surrounding
+ * whitespace is tolerated, but the remaining value must be all digits and
+ * `> 0`. This rejects scientific notation (`1e3`), hex (`0x10`), fractions
+ * (`3.5`), signs (`+5`/`-5`), and trailing junk (`4096x`) so the three
+ * downstream readers — `schema.ts` (`parseInt`), `http-client.ts` (`/^\d+$/`),
+ * and this helper — all agree on one canonical value. Without it, `1e3` parsed
+ * to `FLOAT[1]` at module-load but requested 1000-dim vectors at runtime.
+ */
+/** Shared error message so both call sites surface identical wording. */
+export const EMBEDDING_DIMS_ERROR = '--embedding-dims must be a positive integer.';
+/**
+ * Returns the canonical positive-integer string (e.g. `"007"` → `"7"`), or
+ * `null` when the input is not a strict positive integer.
+ */
+export const normalizeEmbeddingDims = (raw) => {
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed) || parseInt(trimmed, 10) <= 0) {
+        return null;
+    }
+    return String(parseInt(trimmed, 10));
+};

package/dist/cli/eval-server.js

@@ -155,7 +155,43 @@ export function formatImpactResult(result) {
     const direction = result.direction;
     const byDepth = result.byDepth || {};
     const total = result.impactedCount || 0;
+    // #2129 — an ambiguous bare name must not print the "isolated / safe to
+    // refactor" headline. Surface the per-candidate blast radius + the maximum,
+    // mirroring formatContextResult, so the real impact under whichever symbol the
+    // caller meant is visible on the text surface, not just in the JSON.
+    if (result.status === 'ambiguous') {
+        // #2129 review F11 — report the FULL match count (`totalCandidates`), not the
+        // truncated `candidates[]` length; note when the candidate list is capped.
+        const shown = result.candidates?.length ?? 0;
+        const total = result.totalCandidates ?? shown;
+        const countPhrase = total > shown ? `${total} symbols (showing ${shown})` : `${total} symbols`;
+        const lines = [
+            `${target?.name || '?'}: AMBIGUOUS — ${countPhrase} share this name. ` +
+                `Max blast radius ${result.maxImpactedCount ?? 0} (${result.maxRisk ?? 'UNKNOWN'} risk). ` +
+                `Disambiguate with --uid for one authoritative result:`,
+        ];
+        for (const c of result.candidates || []) {
+            lines.push(`  ${c.kind} ${c.name} → ${c.filePath}:${c.line || '?'}  ` +
+                `[${c.impactedCount ?? 0} ${direction}, risk ${c.risk ?? 'UNKNOWN'}]  (uid: ${c.uid})`);
+        }
+        // #2129 review F1 — a failed per-candidate probe makes the max a lower bound.
+        if (result.partialProbe) {
+            lines.push('  ⚠️  One or more candidate probes failed — max blast radius / risk are lower bounds.');
+        }
+        return lines.join('\n');
+    }
     if (total === 0) {
+        // #1858 — "isolated" is a confident claim. If an interface / indirection
+        // boundary is on the path, the true count is a lower bound, not zero;
+        // callers binding via DI / dynamic dispatch were not traced. Say so instead.
+        if (result.epistemic === 'lower-bound') {
+            const lines = [
+                `${target?.name || '?'}: no direct ${direction} dependencies traced, but this is a LOWER BOUND — unresolved indirection on the path (actual impact may be higher):`,
+            ];
+            for (const b of result.boundaries || [])
+                lines.push(`    • ${b}`);
+            return lines.join('\n');
+        }
         return `${target?.name || '?'}: No ${direction} dependencies found. This symbol appears isolated.`;
     }
     const lines = [];
@@ -164,6 +200,13 @@ export function formatImpactResult(result) {
     if (result.partial) {
         lines.push('⚠️  Partial results — graph traversal was interrupted. Deeper impacts may exist.');
     }
+    // #1858 — an interface / indirection boundary on the path makes this a lower
+    // bound; surface it so the count is not read as exhaustive.
+    if (result.epistemic === 'lower-bound') {
+        lines.push('⚠️  Lower bound — unresolved indirection on the path (callers binding via DI / dynamic dispatch are not traced; actual impact may be higher):');
+        for (const b of result.boundaries || [])
+            lines.push(`    • ${b}`);
+    }
     lines.push('');
     const depthLabels = {
         1: 'WILL BREAK (direct)',