gitnexus 1.6.8-rc.5 → 1.6.8-rc.7

package/dist/cli/analyze-config.js

@@ -78,6 +78,12 @@ 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' },
 };
 /** Top-level container key for the nested form; not itself an `AnalyzeOptions` field. */
 const NESTED_KEY = 'analyze';
@@ -195,6 +201,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

@@ -58,6 +58,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 +101,14 @@ 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[];
 }
 /**
  * Whether the post-index skill step should run.

package/dist/cli/analyze.js

@@ -551,6 +551,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.
@@ -829,6 +844,10 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             // 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 +864,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 +885,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/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)',

package/dist/cli/help-i18n.js

@@ -69,6 +69,7 @@ const OPTION_DESCRIPTION_KEYS = {
     'uninstall|-f, --force': 'help.option.uninstall.force',
     'clean|-f, --force': 'help.option.force.confirmation',
     'clean|--all': 'help.option.clean.all',
+    'clean|--branch <name>': 'help.option.clean.branch',
     'clean|--lbug-sidecars': 'help.option.clean.lbugSidecars',
     'remove|-f, --force': 'help.option.force.confirmation',
     'wiki|-f, --force': 'help.option.wiki.force',
@@ -89,16 +90,19 @@ const OPTION_DESCRIPTION_KEYS = {
     'publish|--id <owner/repo>': 'help.option.publish.id',
     'publish|--skip-git': 'help.option.skipGit',
     'query|-r, --repo <name>': 'help.option.repo.targetOmitOne',
+    'query|--branch <name>': 'help.option.branch',
     'query|-c, --context <text>': 'help.option.query.context',
     'query|-g, --goal <text>': 'help.option.query.goal',
     'query|-l, --limit <n>': 'help.option.query.limit',
     'query|--content': 'help.option.content',
     'context|-r, --repo <name>': 'help.option.repo.target',
+    'context|--branch <name>': 'help.option.branch',
     'context|-u, --uid <uid>': 'help.option.context.uid',
     'context|-f, --file <path>': 'help.option.context.file',
     'context|--content': 'help.option.content',
     'impact|-d, --direction <dir>': 'help.option.impact.direction',
     'impact|-r, --repo <name>': 'help.option.repo.target',
+    'impact|--branch <name>': 'help.option.branch',
     'impact|-u, --uid <uid>': 'help.option.context.uid',
     'impact|-f, --file <path>': 'help.option.context.file',
     'impact|--kind <kind>': 'help.option.impact.kind',
@@ -108,9 +112,11 @@ const OPTION_DESCRIPTION_KEYS = {
     'impact|--offset <n>': 'help.option.impact.offset',
     'impact|--summary-only': 'help.option.impact.summaryOnly',
     'cypher|-r, --repo <name>': 'help.option.repo.target',
+    'cypher|--branch <name>': 'help.option.branch',
     'detect-changes|-s, --scope <scope>': 'help.option.detectChanges.scope',
     'detect-changes|-b, --base-ref <ref>': 'help.option.detectChanges.baseRef',
     'detect-changes|-r, --repo <name>': 'help.option.repo.target',
+    'detect-changes|--branch <name>': 'help.option.branch',
     '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',

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

@@ -10,6 +10,9 @@ export declare const en: {
     readonly 'list.title': "Indexed Repositories ({{count}})";
     readonly 'list.indexed': "Indexed";
     readonly 'list.commit': "Commit";
+    readonly 'list.branch': "Branch";
+    readonly 'list.branchIndexes': "Branch indexes";
+    readonly 'list.branchLine': "{{branch}} ({{commit}}, {{indexed}})";
     readonly 'list.stats': "Stats";
     readonly 'list.statsValue': "{{files}} files, {{symbols}} symbols, {{edges}} edges";
     readonly 'list.clusters': "Clusters";
@@ -23,6 +26,9 @@ export declare const en: {
     readonly 'status.indexed': "Indexed";
     readonly 'status.indexedCommit': "Indexed commit";
     readonly 'status.currentCommit': "Current commit";
+    readonly 'status.branch': "Branch";
+    readonly 'status.detached': "(detached HEAD)";
+    readonly 'status.branchNotIndexed': "⚠️ current branch not indexed (primary index is for '{{primary}}'; run gitnexus analyze)";
     readonly 'status.status': "Status";
     readonly 'status.upToDate': "✅ up-to-date";
     readonly 'status.stale': "⚠️ stale (re-run gitnexus analyze)";
@@ -30,6 +36,9 @@ export declare const en: {
     readonly 'clean.deletedRepo': "Deleted: {{name}} ({{storagePath}})";
     readonly 'clean.notFoundHere': "No indexed repository found in this directory.";
     readonly 'clean.deleteCurrent': "This will delete the GitNexus index for: {{repoName}}";
+    readonly 'clean.branchNotIndexed': "No indexed branch named \"{{branch}}\" for this repository.";
+    readonly 'clean.deleteBranch': "This will delete the branch index \"{{branch}}\" at: {{path}}";
+    readonly 'clean.deletedBranch': "Deleted branch index: {{branch}}";
     readonly 'clean.lbugSidecars.state': "LadybugDB sidecar state: {{state}}";
     readonly 'clean.lbugSidecars.none': "No quarantined LadybugDB missing-shadow WAL sidecars found.";
     readonly 'clean.lbugSidecars.preview': "This will delete {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s):";
@@ -156,6 +165,7 @@ export declare const en: {
     readonly 'help.option.force.confirmation': "Skip confirmation prompt";
     readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
     readonly 'help.option.clean.all': "Clean all indexed repos";
+    readonly 'help.option.clean.branch': "Delete only the named branch index (not the primary)";
     readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
     readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
     readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)";
@@ -178,6 +188,7 @@ export declare const en: {
     readonly 'help.option.query.limit': "Max processes to return (default: 5)";
     readonly 'help.option.content': "Include full symbol source code";
     readonly 'help.option.repo.target': "Target repository";
+    readonly 'help.option.branch': "Scope to a specific branch index (multi-branch repos)";
     readonly 'help.option.context.uid': "Direct symbol UID (zero-ambiguity lookup)";
     readonly 'help.option.context.file': "File path to disambiguate common names";
     readonly 'help.option.impact.kind': "Kind filter to disambiguate common names (e.g. Function, Class, Method)";

package/dist/cli/i18n/en.js

@@ -10,6 +10,9 @@ export const en = {
     'list.title': 'Indexed Repositories ({{count}})',
     'list.indexed': 'Indexed',
     'list.commit': 'Commit',
+    'list.branch': 'Branch',
+    'list.branchIndexes': 'Branch indexes',
+    'list.branchLine': '{{branch}} ({{commit}}, {{indexed}})',
     'list.stats': 'Stats',
     'list.statsValue': '{{files}} files, {{symbols}} symbols, {{edges}} edges',
     'list.clusters': 'Clusters',
@@ -23,6 +26,9 @@ export const en = {
     'status.indexed': 'Indexed',
     'status.indexedCommit': 'Indexed commit',
     'status.currentCommit': 'Current commit',
+    'status.branch': 'Branch',
+    'status.detached': '(detached HEAD)',
+    'status.branchNotIndexed': "⚠️ current branch not indexed (primary index is for '{{primary}}'; run gitnexus analyze)",
     'status.status': 'Status',
     'status.upToDate': '✅ up-to-date',
     'status.stale': '⚠️ stale (re-run gitnexus analyze)',
@@ -30,6 +36,9 @@ export const en = {
     'clean.deletedRepo': 'Deleted: {{name}} ({{storagePath}})',
     'clean.notFoundHere': 'No indexed repository found in this directory.',
     'clean.deleteCurrent': 'This will delete the GitNexus index for: {{repoName}}',
+    'clean.branchNotIndexed': 'No indexed branch named "{{branch}}" for this repository.',
+    'clean.deleteBranch': 'This will delete the branch index "{{branch}}" at: {{path}}',
+    'clean.deletedBranch': 'Deleted branch index: {{branch}}',
     'clean.lbugSidecars.state': 'LadybugDB sidecar state: {{state}}',
     'clean.lbugSidecars.none': 'No quarantined LadybugDB missing-shadow WAL sidecars found.',
     'clean.lbugSidecars.preview': 'This will delete {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s):',
@@ -156,6 +165,7 @@ export const en = {
     'help.option.force.confirmation': 'Skip confirmation prompt',
     'help.option.uninstall.force': 'Apply the changes (default is a dry-run preview)',
     'help.option.clean.all': 'Clean all indexed repos',
+    'help.option.clean.branch': 'Delete only the named branch index (not the primary)',
     'help.option.clean.lbugSidecars': 'Clean quarantined LadybugDB missing-shadow WAL sidecars',
     'help.option.wiki.force': 'Force full regeneration even if up to date',
     'help.option.wiki.provider': 'LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)',
@@ -178,6 +188,7 @@ export const en = {
     'help.option.query.limit': 'Max processes to return (default: 5)',
     'help.option.content': 'Include full symbol source code',
     'help.option.repo.target': 'Target repository',
+    'help.option.branch': 'Scope to a specific branch index (multi-branch repos)',
     'help.option.context.uid': 'Direct symbol UID (zero-ambiguity lookup)',
     'help.option.context.file': 'File path to disambiguate common names',
     'help.option.impact.kind': 'Kind filter to disambiguate common names (e.g. Function, Class, Method)',

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

@@ -11,6 +11,9 @@ export declare const cliResources: {
         readonly 'list.title': "Indexed Repositories ({{count}})";
         readonly 'list.indexed': "Indexed";
         readonly 'list.commit': "Commit";
+        readonly 'list.branch': "Branch";
+        readonly 'list.branchIndexes': "Branch indexes";
+        readonly 'list.branchLine': "{{branch}} ({{commit}}, {{indexed}})";
         readonly 'list.stats': "Stats";
         readonly 'list.statsValue': "{{files}} files, {{symbols}} symbols, {{edges}} edges";
         readonly 'list.clusters': "Clusters";
@@ -24,6 +27,9 @@ export declare const cliResources: {
         readonly 'status.indexed': "Indexed";
         readonly 'status.indexedCommit': "Indexed commit";
         readonly 'status.currentCommit': "Current commit";
+        readonly 'status.branch': "Branch";
+        readonly 'status.detached': "(detached HEAD)";
+        readonly 'status.branchNotIndexed': "⚠️ current branch not indexed (primary index is for '{{primary}}'; run gitnexus analyze)";
         readonly 'status.status': "Status";
         readonly 'status.upToDate': "✅ up-to-date";
         readonly 'status.stale': "⚠️ stale (re-run gitnexus analyze)";
@@ -31,6 +37,9 @@ export declare const cliResources: {
         readonly 'clean.deletedRepo': "Deleted: {{name}} ({{storagePath}})";
         readonly 'clean.notFoundHere': "No indexed repository found in this directory.";
         readonly 'clean.deleteCurrent': "This will delete the GitNexus index for: {{repoName}}";
+        readonly 'clean.branchNotIndexed': "No indexed branch named \"{{branch}}\" for this repository.";
+        readonly 'clean.deleteBranch': "This will delete the branch index \"{{branch}}\" at: {{path}}";
+        readonly 'clean.deletedBranch': "Deleted branch index: {{branch}}";
         readonly 'clean.lbugSidecars.state': "LadybugDB sidecar state: {{state}}";
         readonly 'clean.lbugSidecars.none': "No quarantined LadybugDB missing-shadow WAL sidecars found.";
         readonly 'clean.lbugSidecars.preview': "This will delete {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s):";
@@ -157,6 +166,7 @@ export declare const cliResources: {
         readonly 'help.option.force.confirmation': "Skip confirmation prompt";
         readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
         readonly 'help.option.clean.all': "Clean all indexed repos";
+        readonly 'help.option.clean.branch': "Delete only the named branch index (not the primary)";
         readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
         readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
         readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)";
@@ -179,6 +189,7 @@ export declare const cliResources: {
         readonly 'help.option.query.limit': "Max processes to return (default: 5)";
         readonly 'help.option.content': "Include full symbol source code";
         readonly 'help.option.repo.target': "Target repository";
+        readonly 'help.option.branch': "Scope to a specific branch index (multi-branch repos)";
         readonly 'help.option.context.uid': "Direct symbol UID (zero-ambiguity lookup)";
         readonly 'help.option.context.file': "File path to disambiguate common names";
         readonly 'help.option.impact.kind': "Kind filter to disambiguate common names (e.g. Function, Class, Method)";
@@ -224,6 +235,9 @@ export declare const cliResources: {
         'list.title': string;
         'list.indexed': string;
         'list.commit': string;
+        'list.branch': string;
+        'list.branchIndexes': string;
+        'list.branchLine': string;
         'list.stats': string;
         'list.statsValue': string;
         'list.clusters': string;
@@ -237,6 +251,9 @@ export declare const cliResources: {
         'status.indexed': string;
         'status.indexedCommit': string;
         'status.currentCommit': string;
+        'status.branch': string;
+        'status.detached': string;
+        'status.branchNotIndexed': string;
         'status.status': string;
         'status.upToDate': string;
         'status.stale': string;
@@ -244,6 +261,9 @@ export declare const cliResources: {
         'clean.deletedRepo': string;
         'clean.notFoundHere': string;
         'clean.deleteCurrent': string;
+        'clean.branchNotIndexed': string;
+        'clean.deleteBranch': string;
+        'clean.deletedBranch': string;
         'clean.lbugSidecars.state': string;
         'clean.lbugSidecars.none': string;
         'clean.lbugSidecars.preview': string;
@@ -370,6 +390,7 @@ export declare const cliResources: {
         'help.option.force.confirmation': string;
         'help.option.uninstall.force': string;
         'help.option.clean.all': string;
+        'help.option.clean.branch': string;
         'help.option.clean.lbugSidecars': string;
         'help.option.wiki.force': string;
         'help.option.wiki.provider': string;
@@ -392,6 +413,7 @@ export declare const cliResources: {
         'help.option.query.limit': string;
         'help.option.content': string;
         'help.option.repo.target': string;
+        'help.option.branch': string;
         'help.option.context.uid': string;
         'help.option.context.file': string;
         'help.option.impact.kind': string;

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

@@ -10,6 +10,9 @@ export declare const zhCN: {
     'list.title': string;
     'list.indexed': string;
     'list.commit': string;
+    'list.branch': string;
+    'list.branchIndexes': string;
+    'list.branchLine': string;
     'list.stats': string;
     'list.statsValue': string;
     'list.clusters': string;
@@ -23,6 +26,9 @@ export declare const zhCN: {
     'status.indexed': string;
     'status.indexedCommit': string;
     'status.currentCommit': string;
+    'status.branch': string;
+    'status.detached': string;
+    'status.branchNotIndexed': string;
     'status.status': string;
     'status.upToDate': string;
     'status.stale': string;
@@ -30,6 +36,9 @@ export declare const zhCN: {
     'clean.deletedRepo': string;
     'clean.notFoundHere': string;
     'clean.deleteCurrent': string;
+    'clean.branchNotIndexed': string;
+    'clean.deleteBranch': string;
+    'clean.deletedBranch': string;
     'clean.lbugSidecars.state': string;
     'clean.lbugSidecars.none': string;
     'clean.lbugSidecars.preview': string;
@@ -156,6 +165,7 @@ export declare const zhCN: {
     'help.option.force.confirmation': string;
     'help.option.uninstall.force': string;
     'help.option.clean.all': string;
+    'help.option.clean.branch': string;
     'help.option.clean.lbugSidecars': string;
     'help.option.wiki.force': string;
     'help.option.wiki.provider': string;
@@ -178,6 +188,7 @@ export declare const zhCN: {
     'help.option.query.limit': string;
     'help.option.content': string;
     'help.option.repo.target': string;
+    'help.option.branch': string;
     'help.option.context.uid': string;
     'help.option.context.file': string;
     'help.option.impact.kind': string;

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

@@ -10,6 +10,9 @@ export const zhCN = {
     'list.title': '已索引仓库（{{count}}）',
     'list.indexed': '索引时间',
     'list.commit': '提交',
+    'list.branch': '分支',
+    'list.branchIndexes': '分支索引',
+    'list.branchLine': '{{branch}}（{{commit}}，{{indexed}}）',
     'list.stats': '统计',
     'list.statsValue': '{{files}} 个文件，{{symbols}} 个符号，{{edges}} 条边',
     'list.clusters': '聚类',
@@ -23,6 +26,9 @@ export const zhCN = {
     'status.indexed': '索引时间',
     'status.indexedCommit': '索引提交',
     'status.currentCommit': '当前提交',
+    'status.branch': '分支',
+    'status.detached': '（分离 HEAD）',
+    'status.branchNotIndexed': "⚠️ 当前分支未索引（主索引对应 '{{primary}}'；请运行 gitnexus analyze）",
     'status.status': '状态',
     'status.upToDate': '✅ 已是最新',
     'status.stale': '⚠️ 已过期（重新运行 gitnexus analyze）',
@@ -30,6 +36,9 @@ export const zhCN = {
     'clean.deletedRepo': '已删除：{{name}}（{{storagePath}}）',
     'clean.notFoundHere': '当前目录未找到已索引仓库。',
     'clean.deleteCurrent': '将删除该仓库的 GitNexus 索引：{{repoName}}',
+    'clean.branchNotIndexed': '该仓库没有名为 “{{branch}}” 的已索引分支。',
+    'clean.deleteBranch': '将删除分支索引 “{{branch}}”，路径：{{path}}',
+    'clean.deletedBranch': '已删除分支索引：{{branch}}',
     'clean.lbugSidecars.state': 'LadybugDB sidecar 状态：{{state}}',
     'clean.lbugSidecars.none': '未找到已隔离的 LadybugDB missing-shadow WAL sidecar。',
     'clean.lbugSidecars.preview': '将删除 {{count}} 个已隔离的 LadybugDB missing-shadow WAL sidecar：',
@@ -156,6 +165,7 @@ export const zhCN = {
     'help.option.force.confirmation': '跳过确认提示',
     'help.option.uninstall.force': '应用更改（默认仅为预演预览）',
     'help.option.clean.all': '清理所有已索引仓库',
+    'help.option.clean.branch': '仅删除指定分支的索引（不影响主索引）',
     'help.option.clean.lbugSidecars': '清理已隔离的 LadybugDB missing-shadow WAL sidecar',
     'help.option.wiki.force': '即使已是最新也强制完整重新生成',
     'help.option.wiki.provider': 'LLM 提供商：openai、openrouter、azure、custom、cursor、claude、codex 或 opencode（默认：openai）',
@@ -178,6 +188,7 @@ export const zhCN = {
     'help.option.query.limit': '最多返回的流程数（默认：5）',
     'help.option.content': '包含完整符号源码',
     'help.option.repo.target': '目标仓库',
+    'help.option.branch': '将查询限定到指定分支的索引（多分支仓库）',
     'help.option.context.uid': '直接符号 UID（零歧义查找）',
     'help.option.context.file': '用于消除常见名称歧义的文件路径',
     'help.option.impact.kind': '用于消除常见名称歧义的类型过滤（如 Function、Class、Method）',