gitnexus 1.6.9-rc.45 → 1.6.9-rc.46

package/README.md

@@ -144,7 +144,7 @@ Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically:
 | `group_list`     | List configured repository groups                                       |
 | `group_sync`     | Rebuild a group's Contract Registry and cross-repo links                |
 
-> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for multi-branch indexes. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for indexes pinned with `gitnexus analyze --branch`; omitting it queries the workspace index, which follows your checked-out working tree. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
 
 ## MCP Resources
 

package/dist/cli/analyze.js

@@ -1005,10 +1005,11 @@ 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.
+            // Only refresh the repo-root AGENTS.md/CLAUDE.md base_ref for the flat
+            // WORKSPACE index (#2106 R2, #2354). A pinned --branch sub-index'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 = [];
             if (result.isPrimaryBranch !== false) {
                 try {

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

@@ -28,7 +28,7 @@ export declare const en: {
     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.workspaceIndexLabel': "Workspace index: last analyzed on '{{primary}}' (re-run gitnexus analyze to follow the current branch)";
     readonly 'status.status': "Status";
     readonly 'status.upToDate': "✅ up-to-date";
     readonly 'status.stale': "⚠️ stale (re-run gitnexus analyze)";
@@ -172,7 +172,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.branch': "Delete only the named branch index (not the workspace index)";
     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)";

package/dist/cli/i18n/en.js

@@ -28,7 +28,7 @@ export const en = {
     '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.workspaceIndexLabel': "Workspace index: last analyzed on '{{primary}}' (re-run gitnexus analyze to follow the current branch)",
     'status.status': 'Status',
     'status.upToDate': '✅ up-to-date',
     'status.stale': '⚠️ stale (re-run gitnexus analyze)',
@@ -172,7 +172,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.branch': 'Delete only the named branch index (not the workspace index)',
     '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)',

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

@@ -29,7 +29,7 @@ export declare const cliResources: {
         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.workspaceIndexLabel': "Workspace index: last analyzed on '{{primary}}' (re-run gitnexus analyze to follow the current branch)";
         readonly 'status.status': "Status";
         readonly 'status.upToDate': "✅ up-to-date";
         readonly 'status.stale': "⚠️ stale (re-run gitnexus analyze)";
@@ -173,7 +173,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.branch': "Delete only the named branch index (not the workspace index)";
         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)";
@@ -271,7 +271,7 @@ export declare const cliResources: {
         'status.currentCommit': string;
         'status.branch': string;
         'status.detached': string;
-        'status.branchNotIndexed': string;
+        'status.workspaceIndexLabel': string;
         'status.status': string;
         'status.upToDate': string;
         'status.stale': string;

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

@@ -28,7 +28,7 @@ export declare const zhCN: {
     'status.currentCommit': string;
     'status.branch': string;
     'status.detached': string;
-    'status.branchNotIndexed': string;
+    'status.workspaceIndexLabel': string;
     'status.status': string;
     'status.upToDate': string;
     'status.stale': string;

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

@@ -28,7 +28,7 @@ export const zhCN = {
     'status.currentCommit': '当前提交',
     'status.branch': '分支',
     'status.detached': '（分离 HEAD）',
-    'status.branchNotIndexed': "⚠️ 当前分支未索引（主索引对应 '{{primary}}'；请运行 gitnexus analyze）",
+    'status.workspaceIndexLabel': "工作区索引：最近在 '{{primary}}' 分支上分析（重新运行 gitnexus analyze 以跟随当前分支）",
     'status.status': '状态',
     'status.upToDate': '✅ 已是最新',
     'status.stale': '⚠️ 已过期（重新运行 gitnexus analyze）',
@@ -172,7 +172,7 @@ export const zhCN = {
     'help.option.force.confirmation': '跳过确认提示',
     'help.option.uninstall.force': '应用更改（默认仅为预演预览）',
     'help.option.clean.all': '清理所有已索引仓库',
-    'help.option.clean.branch': '仅删除指定分支的索引（不影响主索引）',
+    '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）',

package/dist/cli/index.js

@@ -49,9 +49,9 @@ program
     'for supported languages. Opt-in; off by default. (#2081 M1)')
     .option('--default-branch <branch>', 'Default branch used in the generated regression-compare example (base_ref). ' +
     'Falls back to .gitnexusrc, then auto-detected origin/HEAD, then "main".')
-    .option('--branch <name>', 'Index the working tree under a specific branch slot (multi-branch indexing). ' +
-    'Defaults to the checked-out branch; the primary/first-indexed branch keeps the ' +
-    'flat index and others get their own. Distinct from --default-branch (cosmetic base_ref).')
+    .option('--branch <name>', 'Pin the working tree into a dedicated per-branch index slot (multi-branch indexing). ' +
+    'Without this flag, analyze always updates the workspace index, which follows the ' +
+    'checked-out working tree. Distinct from --default-branch (cosmetic base_ref).')
     .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
     .option('--skip-skills', 'Skip installing standard GitNexus skill files under .claude/skills/gitnexus/. ' +
     'Does not suppress community skills from --skills (those use .claude/skills/generated/). ' +
@@ -158,7 +158,7 @@ program
     .description('Delete GitNexus index for current repo')
     .option('-f, --force', 'Skip confirmation prompt')
     .option('--all', 'Clean all indexed repos')
-    .option('--branch <name>', 'Delete only the named branch index (not the primary)')
+    .option('--branch <name>', 'Delete only the named branch index (not the workspace index)')
     .option('--lbug-sidecars', 'Clean quarantined LadybugDB missing-shadow WAL sidecars')
     .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
 program

package/dist/cli/status.js

@@ -30,25 +30,25 @@ export const statusCommand = async () => {
     }
     const currentCommit = getCurrentCommit(repo.repoPath);
     const currentBranch = getCurrentBranch(repo.repoPath);
-    // Pick the index matching the checked-out branch (#2106). The flat index
-    // belongs to the primary branch (repo.meta.branch); when the current branch
-    // differs and has its own index, report that one. Legacy/no-branch metas and
-    // detached HEAD fall through to the flat index (unchanged behavior).
+    // Pick the index matching the checked-out branch (#2106/#2354). A pinned
+    // `--branch` sub-index for the current branch wins; otherwise report the
+    // flat workspace index, which follows the checked-out working tree — the
+    // commit comparison below then says whether it needs a re-analyze. Legacy/
+    // no-branch metas and detached HEAD also fall through to the flat index.
     let activeMeta = repo.meta;
-    let currentBranchIndexed = true;
+    let workspaceLagsBranch = false;
     if (currentBranch && repo.meta.branch && currentBranch !== repo.meta.branch) {
         const { metaPath } = getStoragePaths(repo.repoPath, currentBranch);
         const branchMeta = await loadMeta(path.dirname(metaPath));
         if (branchMeta)
             activeMeta = branchMeta;
         else
-            currentBranchIndexed = false;
+            workspaceLagsBranch = true;
     }
     console.log(`${t('status.repository')}: ${repo.repoPath}`);
     console.log(`${t('status.branch')}: ${currentBranch ?? t('status.detached')}`);
-    if (!currentBranchIndexed) {
-        console.log(`${t('status.status')}: ${t('status.branchNotIndexed', { primary: repo.meta.branch ?? '' })}`);
-        return;
+    if (workspaceLagsBranch) {
+        console.log(t('status.workspaceIndexLabel', { primary: repo.meta.branch ?? '' }));
     }
     const isUpToDate = currentCommit === activeMeta.lastCommit;
     console.log(`${t('status.indexed')}: ${new Date(activeMeta.indexedAt).toLocaleString()}`);

package/dist/core/run-analyze.d.ts

@@ -103,13 +103,13 @@ export interface AnalyzeOptions {
      */
     defaultBranch?: string;
     /**
-     * Index-branch selector (#2106). Distinct from `defaultBranch` (which only
-     * affects generated AGENTS.md/CLAUDE.md base_ref text). When set, this run is
-     * labelled as that branch and routed to a per-branch index slot unless it is
-     * the primary branch. When `undefined`, the branch is auto-detected from the
-     * checked-out HEAD (the flat/primary slot for the first-indexed branch, a
-     * `branches/<slug>/` sub-directory otherwise). Detached HEAD / non-git always
-     * maps to the flat slot.
+     * Index-branch selector (#2106, #2354). Distinct from `defaultBranch` (which
+     * only affects generated AGENTS.md/CLAUDE.md base_ref text). When set, this
+     * run is pinned to a per-branch index slot (`branches/<slug>/`) unless the
+     * label matches the flat slot's recorded branch. When `undefined`, the run
+     * always targets the flat workspace slot, which follows the checked-out
+     * working tree; the auto-detected branch is only recorded as the slot's
+     * informational label. Detached HEAD / non-git also map to the flat slot.
      */
     branch?: string;
     /**
@@ -176,10 +176,12 @@ export interface AnalyzeResult {
      */
     ftsSkipped?: boolean;
     /**
-     * True when the index this run produced/validated is the primary/flat slot
-     * (#2106 R2). `false` for a non-primary branch index. Lets the CLI skip
-     * repo-root AGENTS.md/CLAUDE.md refreshes (e.g. the base_ref fast-path) for a
+     * True when the index this run produced/validated is the flat workspace
+     * slot (#2106 R2, inverted by #2354 to follow the checked-out branch).
+     * `false` for a pinned `--branch` sub-index. Lets the CLI skip repo-root
+     * AGENTS.md/CLAUDE.md refreshes (e.g. the base_ref fast-path) for a pinned
      * branch analyze, mirroring the in-pipeline `if (!placement.branch)` gate.
+     * (The historical "primary" name is kept — it is public API surface.)
      */
     isPrimaryBranch?: boolean;
 }
@@ -197,14 +199,6 @@ export declare const PHASE_LABELS: Record<string, string>;
  * the {@link AnalyzeCallbacks} interface — it never writes to stdout/stderr
  * directly and never calls `process.exit()`.
  */
-/**
- * Build the primary-inversion warning (#2106 R8), or `undefined` when there is
- * nothing to warn about. Pure + exported for testing. Both inputs are trimmed
- * (a diagnostic — a missed warning is low-harm; a false warning is the thing to
- * avoid). `defaultBranch` is the repo's `origin/HEAD` branch (null when unset,
- * e.g. fresh clones / CI), `flatOwner` is the branch that owns the flat slot.
- */
-export declare const primaryInversionWarning: (defaultBranch: string | null | undefined, flatOwner: string | null | undefined) => string | undefined;
 /**
  * Collect the recorded parse-cache chunk keys across the flat + every branch
  * metadata directory under a flat `.gitnexus` storage, EXCLUDING `excludeDir`

package/dist/core/run-analyze.js

@@ -18,7 +18,7 @@ import { createSearchFTSIndexes, initialiseSearchFTSStemmer, verifySearchFTSInde
 import { cjkSegmentationModeMismatch, getSearchFTSCjkSegmentation, initialiseSearchFTSCjkSegmentation, } from './search/cjk-segmentation.js';
 import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
 import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
-import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, isRepoRegistered, cleanupOldKuzuFiles, reconcileMetadataFiles, isMissingFilesystemError, INDEX_METADATA_FILE, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
+import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, adoptFlatBranchLabel, isReadOnlyFilesystemError, isRepoRegistered, cleanupOldKuzuFiles, reconcileMetadataFiles, isMissingFilesystemError, INDEX_METADATA_FILE, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { DEFAULT_PDG_MAX_FUNCTION_LINES } from './ingestion/cfg/collect.js';
 import { DEFAULT_MAX_CFG_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_CDG_EDGES_PER_FUNCTION, } from './ingestion/cfg/emit.js';
 import { DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from './ingestion/taint/propagate.js';
@@ -31,7 +31,7 @@ import { extractChangedSubgraph, computeEffectiveWriteSet, } from './incremental
 import { shadowCandidatesFor } from './incremental/shadow-candidates.js';
 import { loadParseCache, saveParseCache, pruneCache, PARSE_CACHE_VERSION, } from '../storage/parse-cache.js';
 import { getDurableParsedFileDir, pruneAndSaveDurableParsedFileStore, } from '../storage/parsedfile-store.js';
-import { getCurrentCommit, getCurrentBranch, getDefaultBranch, getRemoteUrl, hasGitDir, getInferredRepoName, resolveRepoIdentityRoot, } from '../storage/git.js';
+import { getCurrentCommit, getCurrentBranch, getRemoteUrl, hasGitDir, getInferredRepoName, resolveRepoIdentityRoot, } from '../storage/git.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { sanitizeDetectedBranch } from '../cli/analyze-config.js';
 import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
@@ -79,22 +79,6 @@ export const PHASE_LABELS = {
  * the {@link AnalyzeCallbacks} interface — it never writes to stdout/stderr
  * directly and never calls `process.exit()`.
  */
-/**
- * Build the primary-inversion warning (#2106 R8), or `undefined` when there is
- * nothing to warn about. Pure + exported for testing. Both inputs are trimmed
- * (a diagnostic — a missed warning is low-harm; a false warning is the thing to
- * avoid). `defaultBranch` is the repo's `origin/HEAD` branch (null when unset,
- * e.g. fresh clones / CI), `flatOwner` is the branch that owns the flat slot.
- */
-export const primaryInversionWarning = (defaultBranch, flatOwner) => {
-    const norm = (s) => s?.trim() || undefined;
-    const d = norm(defaultBranch);
-    const o = norm(flatOwner);
-    if (!d || !o || d === o)
-        return undefined;
-    return (`Warning: the default branch "${d}" is not the primary index — "${o}" owns the flat slot. ` +
-        `Run \`gitnexus clean --branch ${o}\` then re-index on "${d}", or query it explicitly with \`--branch ${d}\`.`);
-};
 /**
  * Collect the recorded parse-cache chunk keys across the flat + every branch
  * metadata directory under a flat `.gitnexus` storage, EXCLUDING `excludeDir`
@@ -293,13 +277,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     }
     const repoHasGit = hasGitDir(repoPath);
     const currentCommit = repoHasGit ? getCurrentCommit(repoPath) : '';
-    // ── #2106: resolve which branch slot this run writes to ───────────────
+    // ── #2106/#2354: resolve which branch slot this run writes to ─────────
     // `branchLabel` is the branch identity recorded in meta.json (incl. the
-    // primary). `placement.branch` is undefined for the flat/primary slot (the
-    // lbug/meta paths stay byte-identical to single-branch behavior) and set for
-    // a `branches/<slug>/` sub-directory. Explicit `--branch` is always honored;
-    // otherwise auto-detect the checked-out branch (null for detached HEAD /
-    // non-git → flat slot).
+    // flat workspace slot). `placement.branch` is undefined for the flat slot
+    // (the lbug/meta paths stay byte-identical to single-branch behavior) and
+    // set for a `branches/<slug>/` sub-directory. Only an explicit `--branch`
+    // can route to a sub-directory; a plain analyze ALWAYS targets the flat
+    // slot, which follows the checked-out working tree (#2354) — the
+    // auto-detected branch (null for detached HEAD / non-git) is recorded as
+    // the slot's informational label only.
     // Normalize the auto-detected branch the same way an explicit `--branch` is
     // validated (#2106 R1): a git ref the branch-name rules forbid (backtick,
     // `~ ^ : ? *`, leading `-`, `..`) becomes `null` → the flat slot, matching
@@ -318,7 +304,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             `Check out "${options.branch}" before indexing it, or omit --branch to index the current branch.`);
     }
     const branchLabel = options.branch ?? checkedOutBranch;
-    const placement = await resolveBranchPlacement(repoPath, branchLabel);
+    const placement = options.branch ? await resolveBranchPlacement(repoPath, branchLabel) : {};
     const { lbugPath, metaPath } = getStoragePaths(repoPath, placement.branch);
     // metaPath now points to the metadata file (gitnexus.json) in a branch-specific directory.
     // metaDir is the directory containing the metadata file (and branch-specific DBs).
@@ -336,21 +322,6 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         log(`Metadata reconciliation failed (non-critical${code ? `, ${code}` : ''}); continuing.`);
     }
     const existingMeta = await loadMeta(metaDir);
-    // ── #2106 (R8): warn when the repo's default branch is not the primary ──
-    // A non-default branch can own the flat slot (it was indexed first). That
-    // index is still fully queryable via `--branch`, so this is an ergonomics
-    // wart, not data loss — we only warn (no risky relocation of a live DB).
-    if (repoHasGit) {
-        // Who owns the flat slot after this run? For a flat/primary run it is this
-        // run's resolved label (carrying an existing stamp forward); for a branch
-        // run the flat owner is unchanged, so read the flat meta.
-        const flatOwner = placement.branch
-            ? (await loadMeta(storagePath))?.branch
-            : (branchLabel ?? existingMeta?.branch);
-        const warning = primaryInversionWarning(getDefaultBranch(repoPath), flatOwner);
-        if (warning)
-            log(warning);
-    }
     // ── FTS-only repair path ────────────────────────────────────────────
     if (options.repairFts) {
         if (!existingMeta) {
@@ -550,6 +521,38 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             // opt-in branch so the common fast path keeps its single-stat cost.
             const healUnregistered = options.allowDuplicateName === true && !(await isRepoRegistered(repoPath));
             if (!dirty && !healUnregistered) {
+                // ── #2354: restamp the workspace label on a same-commit branch flip ──
+                // The flat slot follows the checked-out working tree; a branch switch
+                // at the SAME commit with a clean tree changes nothing the pipeline
+                // must rebuild, but the slot's informational `branch` label (and the
+                // registry copy that query-side branch scoping reads) would go stale.
+                // Detached HEAD / non-git (branchLabel === null) keeps the existing
+                // stamp, mirroring the end-of-run meta write.
+                if (!placement.branch && branchLabel && existingMeta.branch !== branchLabel) {
+                    // Adopt first, stamp last (#2364 review F3): this block's retry
+                    // guard is `existingMeta.branch !== branchLabel`, so stamping the
+                    // meta before the registry/shadow cleanup would flip the guard and
+                    // lock in any partial failure — with saveMeta last, a failed adopt
+                    // leaves the guard true and the next same-commit run self-heals
+                    // (adopt is idempotent). The whole sync is best-effort: the label
+                    // is informational and the flat DB content is byte-valid for both
+                    // labels here (same commit, clean tree), so an "Already up to
+                    // date" run must not fail over it; read-only storage — the
+                    // documented Docker :ro workflow (#1549) — degrades to a warning.
+                    try {
+                        await adoptFlatBranchLabel(repoPath, branchLabel);
+                        await saveMeta(metaDir, { ...existingMeta, branch: branchLabel });
+                    }
+                    catch (err) {
+                        // EACCES/EPERM also arise from ownership problems and transient
+                        // Windows locks, so keep the real error visible alongside the
+                        // #1549 read-only hint instead of replacing it.
+                        const reason = isReadOnlyFilesystemError(err)
+                            ? `${err.message} — storage may be read-only (#1549)`
+                            : err.message;
+                        log(`Warning: could not restamp the workspace branch label (${reason}); will retry on the next run.`);
+                    }
+                }
                 await ensureGitNexusIgnored(repoPath);
                 return {
                     // `resolveRepoIdentityRoot` collapses worktree roots to the
@@ -1201,6 +1204,24 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             // top-level fields (#2106).
             branch: placement.branch,
         });
+        // ── #2354: the flat workspace slot has adopted this run's branch ──────
+        // Drop a now-shadowed `branches/<slug>/` sub-index for the same label
+        // (unreachable once the flat slot serves it) and align the registry's
+        // top-level branch label. Best-effort like the parse-cache save above
+        // (#2364 review F5): the index is complete and registered, and a failure
+        // here leaves only a stale registry label / undeleted shadowed dir —
+        // never wrong routing, because the flat meta this run already stamped is
+        // what applyBranchScope trusts. Retried by the next content-changing run
+        // (same-commit fast-path runs skip it: their guard compares the
+        // already-stamped meta label).
+        if (!placement.branch && branchLabel) {
+            try {
+                await adoptFlatBranchLabel(repoPath, branchLabel);
+            }
+            catch (e) {
+                log(`Warning: could not sync the workspace branch label (${e.message}); continuing.`);
+            }
+        }
         // Keep generated .gitnexus contents ignored without editing the user's root .gitignore.
         await ensureGitNexusIgnored(repoPath);
         // ── Generate AI context files (best-effort) ───────────────────────

package/dist/mcp/local/local-backend.d.ts

@@ -67,7 +67,7 @@ interface RepoHandle {
     stats?: RegistryEntry['stats'];
     /** Primary/flat branch name, when known (#2106). */
     branch?: string;
-    /** Non-primary branch indexes available for this repo (#2106). */
+    /** Pinned `--branch` sub-indexes available for this repo, distinct from the flat workspace slot (#2106/#2354). */
     branches?: BranchSummary[];
 }
 /**
@@ -122,7 +122,7 @@ export interface RepoListing {
     }>;
     /** Primary/flat branch name, when known (#2106). */
     branch?: string;
-    /** Non-primary branch indexes available for this repo (#2106). */
+    /** Pinned `--branch` sub-indexes available for this repo, distinct from the flat workspace slot (#2106/#2354). */
     branches?: Array<Omit<BranchSummary, 'stats'>>;
 }
 /** Continuation metadata for the paginated `list_repos` MCP tool (#2119). */
@@ -236,14 +236,28 @@ export declare class LocalBackend {
     /**
      * Re-point a resolved repo handle at a specific branch index (#2106).
      *
-     * - No `branch` (default) → the primary/flat handle, unchanged (backward
+     * - No `branch` (default) → the flat workspace handle, unchanged (backward
      *   compatible: every existing caller passes no branch).
-     * - `branch` equal to the known primary → the flat handle.
-     * - `branch` matching an indexed non-primary branch → a handle whose
+     * - `branch` equal to the flat slot's **on-disk** recorded branch → the
+     *   flat handle. The disk meta is read before any cached state is trusted
+     *   (#2364 review F1): the flat slot follows the checked-out working tree
+     *   (#2354), so a plain analyze after a branch switch restamps the meta
+     *   without any repo-resolution miss that would refresh a long-lived
+     *   server's cached handle — the cached label can otherwise serve another
+     *   branch's content under the old name (the pool staleness reinit
+     *   hot-swaps content without updating `handle.branch`).
+     * - `branch` matching an indexed pinned branch → a handle whose
      *   `lbugPath` points at `branches/<slug>/lbug`; the connection pool keys by
-     *   `lbugPath`, so this is the only change needed to scope every tool.
-     * - `branch` that was never indexed → a clear error (never a silently-empty
-     *   result against the wrong DB).
+     *   `lbugPath`, so this is the only change needed to scope every tool. The
+     *   sub-index lbug must actually exist on disk — `adoptFlatBranchLabel`
+     *   deletes the whole dir when the flat slot takes ownership, and a stale
+     *   cached summary must not route to the deleted path.
+     * - Cached `handle.branch` is trusted only when there is no readable flat
+     *   meta to contradict it (legacy shapes, #2106 R4).
+     * - Any miss → a clear error (never a silently-empty result against the
+     *   wrong DB), after exactly one `refreshRepos()` so newly-pinned branches
+     *   and restamped labels the cached handle predates resolve on the next
+     *   call.
      */
     private applyBranchScope;
     /**

package/dist/mcp/local/local-backend.js

@@ -809,45 +809,110 @@ export class LocalBackend {
     /**
      * Re-point a resolved repo handle at a specific branch index (#2106).
      *
-     * - No `branch` (default) → the primary/flat handle, unchanged (backward
+     * - No `branch` (default) → the flat workspace handle, unchanged (backward
      *   compatible: every existing caller passes no branch).
-     * - `branch` equal to the known primary → the flat handle.
-     * - `branch` matching an indexed non-primary branch → a handle whose
+     * - `branch` equal to the flat slot's **on-disk** recorded branch → the
+     *   flat handle. The disk meta is read before any cached state is trusted
+     *   (#2364 review F1): the flat slot follows the checked-out working tree
+     *   (#2354), so a plain analyze after a branch switch restamps the meta
+     *   without any repo-resolution miss that would refresh a long-lived
+     *   server's cached handle — the cached label can otherwise serve another
+     *   branch's content under the old name (the pool staleness reinit
+     *   hot-swaps content without updating `handle.branch`).
+     * - `branch` matching an indexed pinned branch → a handle whose
      *   `lbugPath` points at `branches/<slug>/lbug`; the connection pool keys by
-     *   `lbugPath`, so this is the only change needed to scope every tool.
-     * - `branch` that was never indexed → a clear error (never a silently-empty
-     *   result against the wrong DB).
+     *   `lbugPath`, so this is the only change needed to scope every tool. The
+     *   sub-index lbug must actually exist on disk — `adoptFlatBranchLabel`
+     *   deletes the whole dir when the flat slot takes ownership, and a stale
+     *   cached summary must not route to the deleted path.
+     * - Cached `handle.branch` is trusted only when there is no readable flat
+     *   meta to contradict it (legacy shapes, #2106 R4).
+     * - Any miss → a clear error (never a silently-empty result against the
+     *   wrong DB), after exactly one `refreshRepos()` so newly-pinned branches
+     *   and restamped labels the cached handle predates resolve on the next
+     *   call.
      */
     async applyBranchScope(handle, branch) {
         if (!branch)
             return handle;
-        if (handle.branch && handle.branch === branch)
-            return handle;
-        const summary = handle.branches?.find((b) => b.branch === branch);
-        if (summary) {
-            const { lbugPath } = getStoragePaths(handle.repoPath, branch);
+        // At most one cache refresh per resolution: enough for the NEXT call to
+        // see fresh handles, without paying two registry re-scans when several
+        // stale arms fire in one degraded resolution.
+        let refreshed = false;
+        const refreshOnce = async () => {
+            if (refreshed)
+                return;
+            refreshed = true;
+            await this.refreshRepos().catch(() => { });
+        };
+        // One small JSON read per scoped call; mid-run meta writes preserve the
+        // old label until the end-of-run atomic stamp (run-analyze dirty stamps
+        // spread the existing meta), so this read never runs ahead of the DB.
+        const flatMeta = await loadMeta(path.dirname(handle.lbugPath));
+        if (flatMeta?.branch && flatMeta.branch === branch) {
+            // The disk meta decides routing, so it also supplies the metadata —
+            // the cached handle's label/commit/stats can predate the restamp.
             return {
                 ...handle,
-                lbugPath,
-                indexedAt: summary.indexedAt,
-                lastCommit: summary.lastCommit,
-                stats: summary.stats,
+                branch: flatMeta.branch,
+                indexedAt: flatMeta.indexedAt ?? handle.indexedAt,
+                lastCommit: flatMeta.lastCommit ?? handle.lastCommit,
+                stats: flatMeta.stats ?? handle.stats,
             };
         }
-        // Legacy entry (pre-#2106): the registry has no recorded primary `branch`,
-        // so a `--branch <primary>` request misses the checks above. Read the flat
-        // meta.json (next to the flat handle's lbug) to learn the primary and serve
-        // the flat handle only when it actually matches — never serve flat for an
-        // arbitrary unindexed branch (#2106 R4).
-        if (!handle.branch) {
-            const flatMeta = await loadMeta(path.dirname(handle.lbugPath));
-            if (flatMeta?.branch && flatMeta.branch === branch)
+        // A registry entry claiming `branch` both as the flat label AND as a
+        // pinned summary is an adopt-degraded state (rm kept the summary while
+        // the label restamped) — never serve the possibly stale-vintage pin for
+        // a label the flat slot claims; fall through to the honest error.
+        const summary = handle.branch !== branch ? handle.branches?.find((b) => b.branch === branch) : undefined;
+        if (summary) {
+            const { lbugPath } = getStoragePaths(handle.repoPath, branch);
+            // The lbug is the artifact the pool opens, so its presence is the
+            // serviceability truth — a half-deleted dir can outlive its meta.json
+            // while the lbug is gone, and vice versa (#2364 review F1 arm ii).
+            // Only provably-absent errno counts as missing: a transient EACCES/EIO
+            // on a healthy pinned sub-index must serve the handle (the pool open
+            // surfaces the real error) rather than a false "not indexed".
+            const probeCode = await fs.access(lbugPath).then(() => null, (e) => e?.code ?? 'UNKNOWN');
+            const subIndexMissing = probeCode === 'ENOENT' || probeCode === 'ENOTDIR';
+            if (!subIndexMissing) {
+                return {
+                    ...handle,
+                    lbugPath,
+                    indexedAt: summary.indexedAt,
+                    lastCommit: summary.lastCommit,
+                    stats: summary.stats,
+                };
+            }
+            // Stale summary (sub-index adopted/deleted): refresh so later calls see
+            // fresh handles, then fall through — the flat meta above is the truth.
+            await refreshOnce();
+        }
+        if (handle.branch && handle.branch === branch) {
+            // No readable flat meta (missing/corrupt — loadMeta → null): keep the
+            // pre-#2354 trust in the cached label (#2106 R4 legacy shapes). A
+            // readable meta that names another branch means the label is stale.
+            if (!flatMeta?.branch)
                 return handle;
         }
-        const indexed = [handle.branch, ...(handle.branches?.map((b) => b.branch) ?? [])].filter(Boolean);
-        const available = indexed.length > 0 ? indexed.join(', ') : '(primary only)';
+        // Every miss refreshes once before erroring: newly-pinned branches and
+        // restamped labels the cached handle predates become resolvable on the
+        // caller's next attempt (the cache otherwise only refreshes on repo-
+        // resolution misses and list_repos).
+        await refreshOnce();
+        // The flat slot's label comes from the authoritative meta when readable —
+        // never echo a cached label the meta just contradicted (a "not indexed:
+        // main / indexed: main" self-contradiction). Cached summaries may still
+        // lag; they are a hint, not a promise.
+        const flatLabel = flatMeta?.branch ?? handle.branch;
+        const indexed = [flatLabel, ...(handle.branches?.map((b) => b.branch) ?? [])].filter((b) => Boolean(b) && b !== branch);
+        const available = indexed.length > 0 ? indexed.join(', ') : '(workspace only)';
+        // Post-#2354 a bare `analyze --branch <X>` refuses to run unless X is
+        // checked out, so the guidance must lead with the checkout (#2364 F6).
         throw new Error(`Branch "${branch}" is not indexed for "${handle.name}". ` +
-            `Indexed branches: ${available}. Run: gitnexus analyze --branch ${branch}`);
+            `Indexed branches: ${available}. The workspace index follows the ` +
+            `checked-out branch — check out "${branch}" and re-run: gitnexus analyze ` +
+            `(add --branch ${branch} while it is checked out to pin a separate sub-index).`);
     }
     /**
      * Try to resolve a repo from the in-memory cache. Returns null on miss.

package/dist/mcp/tools.js

@@ -834,10 +834,11 @@ for (const tool of GITNEXUS_TOOLS) {
     if (tool.inputSchema.properties.branch)
         continue;
     // Optional — `required` is left unchanged so omitting `branch` keeps today's
-    // default/primary-branch behavior. Ignored in group mode (repo starts "@").
+    // workspace-index behavior. Ignored in group mode (repo starts "@").
     tool.inputSchema.properties.branch = {
         type: 'string',
-        description: 'Optional: scope to a specific branch index (multi-branch repos, #2106). ' +
-            'Omit for the default/primary branch. Ignored in group mode.',
+        description: 'Optional: scope to a pinned branch index (multi-branch repos, #2106). ' +
+            'Omit for the workspace index, which follows the checked-out working tree. ' +
+            'Ignored in group mode.',
     };
 }

package/dist/storage/branch-index.d.ts

@@ -34,18 +34,20 @@ export declare const BRANCHES_DIR = "branches";
  */
 export declare const branchSlug: (rawRef: string) => string;
 /**
- * Decide where a freshly-analyzed branch's index lives: the flat (primary) slot
- * or a per-branch sub-directory (#2106 KTD2).
+ * Decide where an EXPLICIT `--branch` run's index lives: the flat workspace
+ * slot or a per-branch sub-directory (#2106 KTD2, #2354).
  *
- * Returns `{}` for the flat/primary placement (byte-identical layout) or
- * `{ branch }` for a `branches/<slug>/` sub-directory. The flat slot is owned by
- * the FIRST branch indexed, recorded as `branch` in the flat `meta.json`; a
- * different checked-out branch then auto-routes to its own sub-directory so it
- * never overwrites the primary index.
+ * Only explicit `--branch` runs consult this — a plain analyze always targets
+ * the flat slot, which follows the checked-out working tree (#2354; gated at
+ * the `runFullAnalysis` call site). Returns `{}` for the flat placement
+ * (byte-identical layout) or `{ branch }` for a `branches/<slug>/`
+ * sub-directory: when the requested label matches the flat slot's recorded
+ * `branch` label the run updates the flat slot in place (identical content —
+ * `--branch` requires the label to be checked out); any other label gets its
+ * own pinned sub-directory that plain analyzes won't touch.
  *
- * `label` is the resolved index-branch (explicit `--branch`, else the
- * checked-out branch, else `null`). A `null` label — detached HEAD, non-git
- * folder, or CI checkout — always maps to the flat slot.
+ * A `null` label — detached HEAD, non-git folder, or CI checkout — always
+ * maps to the flat slot.
  */
 export declare const resolveBranchPlacement: (repoPath: string, label: string | null) => Promise<{
     branch?: string;

package/dist/storage/branch-index.js

@@ -28,18 +28,20 @@ export const branchSlug = (rawRef) => {
     return `${safe}-${hash}`;
 };
 /**
- * Decide where a freshly-analyzed branch's index lives: the flat (primary) slot
- * or a per-branch sub-directory (#2106 KTD2).
+ * Decide where an EXPLICIT `--branch` run's index lives: the flat workspace
+ * slot or a per-branch sub-directory (#2106 KTD2, #2354).
  *
- * Returns `{}` for the flat/primary placement (byte-identical layout) or
- * `{ branch }` for a `branches/<slug>/` sub-directory. The flat slot is owned by
- * the FIRST branch indexed, recorded as `branch` in the flat `meta.json`; a
- * different checked-out branch then auto-routes to its own sub-directory so it
- * never overwrites the primary index.
+ * Only explicit `--branch` runs consult this — a plain analyze always targets
+ * the flat slot, which follows the checked-out working tree (#2354; gated at
+ * the `runFullAnalysis` call site). Returns `{}` for the flat placement
+ * (byte-identical layout) or `{ branch }` for a `branches/<slug>/`
+ * sub-directory: when the requested label matches the flat slot's recorded
+ * `branch` label the run updates the flat slot in place (identical content —
+ * `--branch` requires the label to be checked out); any other label gets its
+ * own pinned sub-directory that plain analyzes won't touch.
  *
- * `label` is the resolved index-branch (explicit `--branch`, else the
- * checked-out branch, else `null`). A `null` label — detached HEAD, non-git
- * folder, or CI checkout — always maps to the flat slot.
+ * A `null` label — detached HEAD, non-git folder, or CI checkout — always
+ * maps to the flat slot.
  */
 export const resolveBranchPlacement = async (repoPath, label) => {
     // Detached HEAD / non-git / no label → flat (CI-safe, byte-identical).

package/dist/storage/repo-manager.d.ts

@@ -381,6 +381,7 @@ export declare const reconcileMetadataFiles: (repoPath: string) => Promise<boole
  * Find .gitnexus by walking up from a starting path
  */
 export declare const findRepo: (startPath: string) => Promise<IndexedRepo | null>;
+export declare function isReadOnlyFilesystemError(err: unknown): boolean;
 /**
  * True for errors that prove a path is absent (ENOENT/ENOTDIR) — as opposed
  * to transient/permission failures (EIO/EACCES/EBUSY…) where the file may
@@ -500,6 +501,24 @@ export declare const unregisterRepo: (repoPath: string) => Promise<void>;
  * registry shape legacy-clean.
  */
 export declare const removeBranchIndex: (repoPath: string, branch: string) => Promise<boolean>;
+/**
+ * Record that the flat workspace slot now serves `branch` (#2354).
+ *
+ * The flat index follows the checked-out working tree, so when a plain
+ * analyze lands on a branch that also has a pinned `branches/<slug>/`
+ * sub-index, that sub-index becomes permanently shadowed — explicit
+ * `--branch` runs re-resolve to the flat slot and query-side branch scoping
+ * serves the flat handle first. Delete the shadowed directory and drop its
+ * registry summary in the same pass (leaving either half behind would strand
+ * un-cleanable disk bloat), and refresh the entry's top-level `branch` label
+ * so `list`/`list_repos`/branch-scoped queries stay coherent.
+ *
+ * Deliberately narrow for the analyze fast path: a missing registry entry is
+ * a no-op — including the sub-index deletion, which only runs for registered
+ * repos (never self-heals an unregistered repo, per #2264/#1169; the registry
+ * check precedes the rm per #2364 review F2) — and no subprocess is spawned.
+ */
+export declare const adoptFlatBranchLabel: (repoPath: string, branch: string) => Promise<void>;
 /**
  * Thrown by {@link resolveRegistryEntry} when no registered repo matches
  * the caller's target string (by alias, basename, remote-inferred name,

package/dist/storage/repo-manager.js

@@ -423,7 +423,7 @@ export const findRepo = async (startPath) => {
     }
     return null;
 };
-function isReadOnlyFilesystemError(err) {
+export function isReadOnlyFilesystemError(err) {
     const code = err?.code;
     return code === 'EROFS' || code === 'EACCES' || code === 'EPERM';
 }
@@ -831,6 +831,87 @@ export const removeBranchIndex = async (repoPath, branch) => {
     await writeRegistry(entries);
     return true;
 };
+/**
+ * Record that the flat workspace slot now serves `branch` (#2354).
+ *
+ * The flat index follows the checked-out working tree, so when a plain
+ * analyze lands on a branch that also has a pinned `branches/<slug>/`
+ * sub-index, that sub-index becomes permanently shadowed — explicit
+ * `--branch` runs re-resolve to the flat slot and query-side branch scoping
+ * serves the flat handle first. Delete the shadowed directory and drop its
+ * registry summary in the same pass (leaving either half behind would strand
+ * un-cleanable disk bloat), and refresh the entry's top-level `branch` label
+ * so `list`/`list_repos`/branch-scoped queries stay coherent.
+ *
+ * Deliberately narrow for the analyze fast path: a missing registry entry is
+ * a no-op — including the sub-index deletion, which only runs for registered
+ * repos (never self-heals an unregistered repo, per #2264/#1169; the registry
+ * check precedes the rm per #2364 review F2) — and no subprocess is spawned.
+ */
+export const adoptFlatBranchLabel = async (repoPath, branch) => {
+    const canonicalInput = canonicalizePath(repoPath);
+    const isRegistered = (list) => list.findIndex((e) => registryPathEquals(canonicalizePath(e.path), canonicalInput));
+    // Cheap membership gate only (#2364 review F2): never touch the disk for an
+    // unregistered repo. The mutate below re-reads its own fresh snapshot.
+    if (isRegistered(await readRegistry()) < 0)
+        return; // no-op, disk included (no self-heal)
+    const resolved = path.resolve(repoPath);
+    const { storagePath } = getStoragePaths(resolved);
+    // Remove a shadowed sub-index directory, mirroring `clean --branch`'s
+    // containment guard: the target MUST live under .gitnexus/branches/.
+    const branchDir = path.join(storagePath, BRANCHES_DIR, branchSlug(branch));
+    const branchesRoot = path.join(storagePath, BRANCHES_DIR) + path.sep;
+    let dirGone = false;
+    if (branchDir.startsWith(branchesRoot)) {
+        let rmError;
+        await fs.rm(branchDir, { recursive: true, force: true }).catch((err) => {
+            rmError = err;
+        });
+        // The registry summary may be dropped only for a verifiably-gone
+        // directory: `clean --branch` resolves its target solely via the
+        // recorded summary, so dropping it while the dir survives (e.g. Windows
+        // EBUSY on an lbug held open by a live MCP server) would strand
+        // un-cleanable disk bloat (#2364 review F4). A resolved force:true rm
+        // proves absence; on failure, probe the disk and treat only
+        // provably-absent errno as gone — EACCES/EIO are "not provably absent",
+        // the same polarity as listRegisteredRepos({ validate: true }).
+        if (!rmError) {
+            dirGone = true;
+        }
+        else {
+            const probeCode = await fs.access(branchDir).then(() => null, (e) => e?.code ?? 'UNKNOWN');
+            dirGone = probeCode === 'ENOENT' || probeCode === 'ENOTDIR';
+        }
+        if (dirGone) {
+            // Non-recursive by design: only removes the parent when no other pinned
+            // sub-index remains, so an empty branches/ dir doesn't read as "pinned".
+            await fs.rmdir(path.join(storagePath, BRANCHES_DIR)).catch(() => { });
+        }
+        else {
+            logger.warn({ path: branchDir, code: rmError?.code }, 'Could not remove the shadowed branch sub-index; keeping its registry summary so `gitnexus clean --branch` can still target it.');
+        }
+    }
+    // Re-read AFTER the potentially slow recursive rm: the registry is a
+    // multi-writer whole-file overwrite, and writing a pre-rm snapshot would
+    // silently clobber concurrent registerRepo/removeBranchIndex writers —
+    // the #2106 R9 re-read-before-write discipline registerRepo follows.
+    const entries = await readRegistry();
+    const idx = isRegistered(entries);
+    if (idx < 0)
+        return; // unregistered concurrently → still a no-op
+    const entry = entries[idx];
+    const remaining = dirGone ? entry.branches?.filter((b) => b.branch !== branch) : entry.branches;
+    const droppedSummary = (entry.branches?.length ?? 0) !== (remaining?.length ?? 0);
+    if (entry.branch === branch && !droppedSummary)
+        return; // already coherent
+    entry.branch = branch;
+    if (remaining && remaining.length > 0)
+        entry.branches = remaining;
+    else
+        delete entry.branches;
+    entries[idx] = entry;
+    await writeRegistry(entries);
+};
 /**
  * Thrown by {@link resolveRegistryEntry} when no registered repo matches
  * the caller's target string (by alias, basename, remote-inferred name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.9-rc.45",
+  "version": "1.6.9-rc.46",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",