gitnexus 1.6.13-rc.24 → 1.6.13-rc.25

package/dist/cli/clean.d.ts

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

package/dist/cli/clean.js

@@ -7,11 +7,112 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { logger } from '../core/logger.js';
-import { findRepo, unregisterRepo, listRegisteredRepos, getStoragePaths, removeBranchIndex, } from '../storage/repo-manager.js';
+import { findRegistryEntryByRepoPath, findRepo, unregisterRepo, listRegisteredRepos, getStoragePaths, } from '../storage/repo-manager.js';
 import { requireDeletableStoragePath, StorageDeletionError } from '../storage/storage-resolver.js';
+import { formatStaleSlotLine } from './stale-branch-format.js';
+import { listLocalHeads } from '../storage/git.js';
+import { isContainedBranchDir, isDeleteCandidate, listStaleBranchSlots, removeBranchSlot, staleListingBlock, } from '../storage/stale-branch-slots.js';
 import { cleanParkedLbugSidecars, inspectLbugSidecars, listParkedLbugSidecars, } from '../core/lbug/sidecar-recovery.js';
 import { t } from './i18n/index.js';
 export const cleanCommand = async (options) => {
+    // --stale: reclaim leftover per-branch slots whose recorded branch is not
+    // a live local head (#3331). Exclusive arm before --branch.
+    if (options?.stale) {
+        const cwd = process.cwd();
+        const repo = await findRepo(cwd);
+        if (!repo) {
+            console.log(t('clean.notFoundHere'));
+            return;
+        }
+        const entries = await listRegisteredRepos();
+        const entry = findRegistryEntryByRepoPath(entries, repo.repoPath);
+        let storagePath;
+        try {
+            storagePath = await requireDeletableStoragePath({
+                path: repo.repoPath,
+                storagePath: repo.storagePath,
+            });
+        }
+        catch (err) {
+            if (err instanceof StorageDeletionError) {
+                logger.error(`Refusing to clean leftover branch indexes: ${err.message}`);
+                return;
+            }
+            throw err;
+        }
+        const slots = await listStaleBranchSlots({
+            repoPath: repo.repoPath,
+            storagePath,
+            branches: entry?.branches,
+            includeSize: !options.force,
+        });
+        const listingBlock = staleListingBlock(slots);
+        if (listingBlock === 'heads-unavailable') {
+            console.log(t('clean.stale.headsUnavailable'));
+            for (const slot of slots.filter((row) => row.reason === 'heads-unavailable')) {
+                console.log(`  - ${formatStaleSlotLine(slot)}`);
+            }
+            return;
+        }
+        if (listingBlock === 'listing-failed') {
+            console.log(t('clean.stale.listingFailed'));
+            return;
+        }
+        const candidates = slots.filter(isDeleteCandidate);
+        const probeFailed = slots.filter((slot) => slot.reason === 'probe-failed');
+        const printProbeFailed = () => {
+            console.log(t('clean.stale.probeFailed'));
+            for (const slot of probeFailed) {
+                console.log(`  - ${formatStaleSlotLine(slot)}`);
+            }
+        };
+        if (candidates.length === 0) {
+            if (probeFailed.length > 0) {
+                printProbeFailed();
+                return;
+            }
+            console.log(t('clean.stale.none'));
+            return;
+        }
+        if (!options.force) {
+            console.log(t('clean.stale.preview', { count: candidates.length }));
+            for (const slot of candidates) {
+                console.log(`  - ${formatStaleSlotLine(slot)}`);
+            }
+            if (probeFailed.length > 0) {
+                printProbeFailed();
+            }
+            console.log(`\n${t('common.runForceConfirm')}`);
+            return;
+        }
+        for (const slot of candidates) {
+            const heads = listLocalHeads(repo.repoPath);
+            if (heads === null) {
+                console.log(t('clean.stale.headsUnavailable'));
+                return;
+            }
+            if (heads.includes(slot.branch)) {
+                console.log(t('clean.stale.skippedLive', { branch: slot.branch }));
+                continue;
+            }
+            const result = await removeBranchSlot({
+                repoPath: repo.repoPath,
+                storagePath,
+                branch: slot.branch,
+                dir: slot.dir,
+            });
+            if (!result.ok) {
+                console.log(t('clean.stale.failed', { branch: slot.branch }));
+                logger.error({ err: result.error }, 'Failed to delete leftover branch index:');
+                continue;
+            }
+            console.log(t('clean.stale.deleted', { branch: slot.branch }));
+        }
+        if (probeFailed.length > 0) {
+            printProbeFailed();
+        }
+        return;
+    }
     // --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).
@@ -23,7 +124,7 @@ export const cleanCommand = async (options) => {
             return;
         }
         const entries = await listRegisteredRepos();
-        const entry = entries.find((e) => path.resolve(e.path) === path.resolve(repo.repoPath));
+        const entry = findRegistryEntryByRepoPath(entries, repo.repoPath);
         const summary = entry?.branches?.find((b) => b.branch === options.branch);
         if (!summary) {
             console.log(t('clean.branchNotIndexed', { branch: options.branch }));
@@ -45,10 +146,7 @@ export const cleanCommand = async (options) => {
         }
         const { lbugPath } = getStoragePaths(repo.repoPath, summary.branch, storagePath);
         const branchDir = path.dirname(lbugPath);
-        // Safety guard: the target MUST live under the validated
-        // storage slot's `branches/` directory before any destructive fs.rm.
-        const branchesRoot = path.join(storagePath, 'branches') + path.sep;
-        if (!branchDir.startsWith(branchesRoot)) {
+        if (!isContainedBranchDir(storagePath, branchDir)) {
             logger.error(`Refusing to clean branch index outside the validated storage slot: ${branchDir}`);
             return;
         }
@@ -57,14 +155,17 @@ export const cleanCommand = async (options) => {
             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:');
+        const result = await removeBranchSlot({
+            repoPath: repo.repoPath,
+            storagePath,
+            branch: summary.branch,
+            dir: branchDir,
+        });
+        if (!result.ok) {
+            logger.error({ err: result.error }, 'Failed to delete branch index:');
+            return;
         }
+        console.log(t('clean.deletedBranch', { branch: summary.branch }));
         return;
     }
     if (options?.lbugSidecars) {

package/dist/cli/doctor.d.ts

@@ -1,6 +1,7 @@
 import { type EmbeddingRuntimeResolution } from '../core/embeddings/runtime-install.js';
 import { type NativeCheckResult } from '../core/lbug/native-check.js';
 import { type ValidatedUpdateCache } from '../core/update-cache.js';
+import { type StaleBranchSlot } from '../storage/stale-branch-slots.js';
 export declare function displayWidth(value: string): number;
 export declare function padDisplayEnd(value: string, columns: number): string;
 /**
@@ -60,6 +61,12 @@ export declare function poolSizeDoctorLine(pool: number, envRaw: string | undefi
  * stderr right below said the opposite. Render what the check actually found.
  */
 export declare function nativeStatusLine(check: NativeCheckResult): string;
+/**
+ * Cwd leftover-slot lines (#3331). Pure: no deletes and no registry scan.
+ * When heads cannot be listed, do not title rows as orphaned or name
+ * `clean --stale` (#3337): that command refuses to delete in the same state.
+ */
+export declare function orphanedBranchSlotDoctorLines(slots: StaleBranchSlot[]): string[];
 export declare function cachedUpdateDoctorLine(options: {
     installedVersion: string;
     eligible: boolean;

package/dist/cli/doctor.js

@@ -13,6 +13,9 @@ import { updateEligibleInstallSync } from '../core/install-context.js';
 import { readValidatedUpdateCacheSync } from '../core/update-cache.js';
 import { t } from './i18n/index.js';
 import { cachedUpdateNoticeLine } from './update-notice.js';
+import { formatSlotSize, staleReasonLabel } from './stale-branch-format.js';
+import { findRegistryEntryByRepoPath, findRepo, listRegisteredRepos, } from '../storage/repo-manager.js';
+import { isDeleteCandidate, listStaleBranchSlots, staleListingBlock, } from '../storage/stale-branch-slots.js';
 function isCombiningMark(codePoint) {
     return ((codePoint >= 0x0300 && codePoint <= 0x036f) ||
         (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
@@ -145,6 +148,33 @@ export function poolSizeDoctorLine(pool, envRaw) {
 export function nativeStatusLine(check) {
     return `  ${padDisplayEnd('native', 10)}${nativeStatusText(check)}`;
 }
+/**
+ * Cwd leftover-slot lines (#3331). Pure: no deletes and no registry scan.
+ * When heads cannot be listed, do not title rows as orphaned or name
+ * `clean --stale` (#3337): that command refuses to delete in the same state.
+ */
+export function orphanedBranchSlotDoctorLines(slots) {
+    if (slots.length === 0)
+        return [];
+    const listingBlock = staleListingBlock(slots);
+    if (listingBlock === 'heads-unavailable') {
+        return [t('clean.stale.headsUnavailable')];
+    }
+    if (listingBlock === 'listing-failed') {
+        return [t('clean.stale.listingFailed')];
+    }
+    const lines = [t('doctor.orphanedBranches')];
+    let total = 0;
+    for (const slot of slots) {
+        total += slot.sizeBytes;
+        lines.push(`  ${slot.branch}  ${staleReasonLabel(slot.reason)}  ${formatSlotSize(slot.sizeBytes)}`);
+    }
+    lines.push(`  ${t('doctor.orphanedBranches.total', { size: formatSlotSize(total) })}`);
+    if (slots.some(isDeleteCandidate)) {
+        lines.push(`  ${t('doctor.orphanedBranches.reclaim')}`);
+    }
+    return lines;
+}
 function nativeStatusText(check) {
     if (check.ok)
         return '✓ lbugjs.node loaded';
@@ -285,4 +315,24 @@ export const doctorCommand = async () => {
             console.log(`  ${padDisplayEnd('', 12)}${cudaRedirect.detail}`);
         }
     }
+    // Doctor stays runtime-global. Add only a cwd leftover-slot section when
+    // this process is inside an indexed repo. Look up that repo's registry row
+    // for recorded branch slugs; do not report leftovers for every registered
+    // repo, and never delete.
+    const [cwdRepo, entries] = await Promise.all([findRepo(process.cwd()), listRegisteredRepos()]);
+    if (!cwdRepo)
+        return;
+    const entry = findRegistryEntryByRepoPath(entries, cwdRepo.repoPath);
+    const slots = await listStaleBranchSlots({
+        repoPath: cwdRepo.repoPath,
+        storagePath: cwdRepo.storagePath,
+        branches: entry?.branches,
+    });
+    const orphanLines = orphanedBranchSlotDoctorLines(slots);
+    if (orphanLines.length === 0)
+        return;
+    console.log('');
+    for (const line of orphanLines) {
+        console.log(line);
+    }
 };

package/dist/cli/help-i18n.js

@@ -92,6 +92,7 @@ const OPTION_DESCRIPTION_KEYS = {
     'clean|--all': 'help.option.clean.all',
     'clean|--branch <name>': 'help.option.clean.branch',
     'clean|--lbug-sidecars': 'help.option.clean.lbugSidecars',
+    'clean|--stale': 'help.option.clean.stale',
     'remove|-f, --force': 'help.option.force.confirmation',
     'wiki|-f, --force': 'help.option.wiki.force',
     'wiki|--provider <provider>': 'help.option.wiki.provider',

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

@@ -53,7 +53,23 @@ 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.branchNotIndexed': 'No indexed branch named "{{branch}}" for this repository. Use `gitnexus clean --stale` to reclaim leftover branch indexes, or `gitnexus list` to see recorded names.';
+    readonly 'clean.stale.none': 'No leftover branch indexes to reclaim.';
+    readonly 'clean.stale.preview': 'This will delete {{count}} leftover branch index(es):';
+    readonly 'clean.stale.item': '{{branch}}  {{reason}}  {{path}}  {{size}}';
+    readonly 'clean.stale.registryOnlyPath': '(registry only)';
+    readonly 'clean.stale.headsUnavailable': 'Could not list local heads; leftover branch indexes were not deleted. Re-run `gitnexus clean --stale` when git is available.';
+    readonly 'clean.stale.listingFailed': 'Could not read leftover branch index directories; leftover indexes were not deleted. Check permissions on the branches/ directory and re-run `gitnexus clean --stale`.';
+    readonly 'clean.stale.probeFailed': 'Could not inspect leftover branch index path(s); those slots were not deleted.';
+    readonly 'clean.stale.deleted': 'Deleted leftover branch index: {{branch}}';
+    readonly 'clean.stale.failed': 'Could not delete leftover branch index "{{branch}}".';
+    readonly 'clean.stale.skippedLive': 'Skipped leftover branch index "{{branch}}" — it is a local head again.';
+    readonly 'clean.stale.reason.refMissing': 'not a local head';
+    readonly 'clean.stale.reason.diskOnly': 'leftover directory (no registry row)';
+    readonly 'clean.stale.reason.registryOnly': 'registry row (directory gone)';
+    readonly 'clean.stale.reason.headsUnavailable': 'could not list local heads';
+    readonly 'clean.stale.reason.probeFailed': 'could not inspect slot path';
+    readonly 'clean.stale.reason.listingFailed': 'could not list leftover directories';
     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}}';
@@ -95,6 +111,9 @@ export declare const en: {
     readonly 'doctor.runtime': 'Runtime';
     readonly 'doctor.capabilities': 'Capabilities';
     readonly 'doctor.embeddings': 'Embeddings';
+    readonly 'doctor.orphanedBranches': 'Orphaned branch indexes';
+    readonly 'doctor.orphanedBranches.total': 'Total: {{size}}';
+    readonly 'doctor.orphanedBranches.reclaim': 'Reclaim with: gitnexus clean --stale';
     readonly 'doctor.labels.os': 'OS:';
     readonly 'doctor.labels.node': 'Node:';
     readonly 'doctor.labels.gitnexus': 'GitNexus:';
@@ -215,6 +234,7 @@ export declare const en: {
     readonly 'help.option.clean.all': 'Clean all indexed repos';
     readonly 'help.option.clean.branch': 'Delete only the named branch index (not the workspace index)';
     readonly 'help.option.clean.lbugSidecars': 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)';
+    readonly 'help.option.clean.stale': 'Reclaim leftover branch indexes that are not a live local head';
     readonly 'help.option.wiki.force': 'Force full regeneration even if up to date';
     readonly 'help.option.wiki.provider': 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)';
     readonly 'help.option.wiki.model': 'LLM model or deployment name (default: MiniMax-M3)';

package/dist/cli/i18n/en.js

@@ -53,7 +53,23 @@ 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.branchNotIndexed': 'No indexed branch named "{{branch}}" for this repository. Use `gitnexus clean --stale` to reclaim leftover branch indexes, or `gitnexus list` to see recorded names.',
+    'clean.stale.none': 'No leftover branch indexes to reclaim.',
+    'clean.stale.preview': 'This will delete {{count}} leftover branch index(es):',
+    'clean.stale.item': '{{branch}}  {{reason}}  {{path}}  {{size}}',
+    'clean.stale.registryOnlyPath': '(registry only)',
+    'clean.stale.headsUnavailable': 'Could not list local heads; leftover branch indexes were not deleted. Re-run `gitnexus clean --stale` when git is available.',
+    'clean.stale.listingFailed': 'Could not read leftover branch index directories; leftover indexes were not deleted. Check permissions on the branches/ directory and re-run `gitnexus clean --stale`.',
+    'clean.stale.probeFailed': 'Could not inspect leftover branch index path(s); those slots were not deleted.',
+    'clean.stale.deleted': 'Deleted leftover branch index: {{branch}}',
+    'clean.stale.failed': 'Could not delete leftover branch index "{{branch}}".',
+    'clean.stale.skippedLive': 'Skipped leftover branch index "{{branch}}" — it is a local head again.',
+    'clean.stale.reason.refMissing': 'not a local head',
+    'clean.stale.reason.diskOnly': 'leftover directory (no registry row)',
+    'clean.stale.reason.registryOnly': 'registry row (directory gone)',
+    'clean.stale.reason.headsUnavailable': 'could not list local heads',
+    'clean.stale.reason.probeFailed': 'could not inspect slot path',
+    'clean.stale.reason.listingFailed': 'could not list leftover directories',
     'clean.deleteBranch': 'This will delete the branch index "{{branch}}" at: {{path}}',
     'clean.deletedBranch': 'Deleted branch index: {{branch}}',
     'clean.lbugSidecars.state': 'LadybugDB sidecar state: {{state}}',
@@ -97,6 +113,9 @@ export const en = {
     'doctor.runtime': 'Runtime',
     'doctor.capabilities': 'Capabilities',
     'doctor.embeddings': 'Embeddings',
+    'doctor.orphanedBranches': 'Orphaned branch indexes',
+    'doctor.orphanedBranches.total': 'Total: {{size}}',
+    'doctor.orphanedBranches.reclaim': 'Reclaim with: gitnexus clean --stale',
     'doctor.labels.os': 'OS:',
     'doctor.labels.node': 'Node:',
     'doctor.labels.gitnexus': 'GitNexus:',
@@ -217,6 +236,7 @@ export const en = {
     'help.option.clean.all': 'Clean all indexed repos',
     'help.option.clean.branch': 'Delete only the named branch index (not the workspace index)',
     'help.option.clean.lbugSidecars': 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)',
+    'help.option.clean.stale': 'Reclaim leftover branch indexes that are not a live local head',
     'help.option.wiki.force': 'Force full regeneration even if up to date',
     'help.option.wiki.provider': 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)',
     'help.option.wiki.model': 'LLM model or deployment name (default: MiniMax-M3)',

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

@@ -54,7 +54,23 @@ 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.branchNotIndexed': 'No indexed branch named "{{branch}}" for this repository. Use `gitnexus clean --stale` to reclaim leftover branch indexes, or `gitnexus list` to see recorded names.';
+        readonly 'clean.stale.none': 'No leftover branch indexes to reclaim.';
+        readonly 'clean.stale.preview': 'This will delete {{count}} leftover branch index(es):';
+        readonly 'clean.stale.item': '{{branch}}  {{reason}}  {{path}}  {{size}}';
+        readonly 'clean.stale.registryOnlyPath': '(registry only)';
+        readonly 'clean.stale.headsUnavailable': 'Could not list local heads; leftover branch indexes were not deleted. Re-run `gitnexus clean --stale` when git is available.';
+        readonly 'clean.stale.listingFailed': 'Could not read leftover branch index directories; leftover indexes were not deleted. Check permissions on the branches/ directory and re-run `gitnexus clean --stale`.';
+        readonly 'clean.stale.probeFailed': 'Could not inspect leftover branch index path(s); those slots were not deleted.';
+        readonly 'clean.stale.deleted': 'Deleted leftover branch index: {{branch}}';
+        readonly 'clean.stale.failed': 'Could not delete leftover branch index "{{branch}}".';
+        readonly 'clean.stale.skippedLive': 'Skipped leftover branch index "{{branch}}" — it is a local head again.';
+        readonly 'clean.stale.reason.refMissing': 'not a local head';
+        readonly 'clean.stale.reason.diskOnly': 'leftover directory (no registry row)';
+        readonly 'clean.stale.reason.registryOnly': 'registry row (directory gone)';
+        readonly 'clean.stale.reason.headsUnavailable': 'could not list local heads';
+        readonly 'clean.stale.reason.probeFailed': 'could not inspect slot path';
+        readonly 'clean.stale.reason.listingFailed': 'could not list leftover directories';
         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}}';
@@ -96,6 +112,9 @@ export declare const cliResources: {
         readonly 'doctor.runtime': 'Runtime';
         readonly 'doctor.capabilities': 'Capabilities';
         readonly 'doctor.embeddings': 'Embeddings';
+        readonly 'doctor.orphanedBranches': 'Orphaned branch indexes';
+        readonly 'doctor.orphanedBranches.total': 'Total: {{size}}';
+        readonly 'doctor.orphanedBranches.reclaim': 'Reclaim with: gitnexus clean --stale';
         readonly 'doctor.labels.os': 'OS:';
         readonly 'doctor.labels.node': 'Node:';
         readonly 'doctor.labels.gitnexus': 'GitNexus:';
@@ -216,6 +235,7 @@ export declare const cliResources: {
         readonly 'help.option.clean.all': 'Clean all indexed repos';
         readonly 'help.option.clean.branch': 'Delete only the named branch index (not the workspace index)';
         readonly 'help.option.clean.lbugSidecars': 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)';
+        readonly 'help.option.clean.stale': 'Reclaim leftover branch indexes that are not a live local head';
         readonly 'help.option.wiki.force': 'Force full regeneration even if up to date';
         readonly 'help.option.wiki.provider': 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)';
         readonly 'help.option.wiki.model': 'LLM model or deployment name (default: MiniMax-M3)';
@@ -341,6 +361,22 @@ export declare const cliResources: {
         'clean.notFoundHere': string;
         'clean.deleteCurrent': string;
         'clean.branchNotIndexed': string;
+        'clean.stale.none': string;
+        'clean.stale.preview': string;
+        'clean.stale.item': string;
+        'clean.stale.registryOnlyPath': string;
+        'clean.stale.headsUnavailable': string;
+        'clean.stale.listingFailed': string;
+        'clean.stale.probeFailed': string;
+        'clean.stale.deleted': string;
+        'clean.stale.failed': string;
+        'clean.stale.skippedLive': string;
+        'clean.stale.reason.refMissing': string;
+        'clean.stale.reason.diskOnly': string;
+        'clean.stale.reason.registryOnly': string;
+        'clean.stale.reason.headsUnavailable': string;
+        'clean.stale.reason.probeFailed': string;
+        'clean.stale.reason.listingFailed': string;
         'clean.deleteBranch': string;
         'clean.deletedBranch': string;
         'clean.lbugSidecars.state': string;
@@ -382,6 +418,9 @@ export declare const cliResources: {
         'doctor.runtime': string;
         'doctor.capabilities': string;
         'doctor.embeddings': string;
+        'doctor.orphanedBranches': string;
+        'doctor.orphanedBranches.total': string;
+        'doctor.orphanedBranches.reclaim': string;
         'doctor.labels.os': string;
         'doctor.labels.node': string;
         'doctor.labels.gitnexus': string;
@@ -502,6 +541,7 @@ export declare const cliResources: {
         'help.option.clean.all': string;
         'help.option.clean.branch': string;
         'help.option.clean.lbugSidecars': string;
+        'help.option.clean.stale': string;
         'help.option.wiki.force': string;
         'help.option.wiki.provider': string;
         'help.option.wiki.model': string;

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

@@ -54,6 +54,22 @@ export declare const zhCN: {
     'clean.notFoundHere': string;
     'clean.deleteCurrent': string;
     'clean.branchNotIndexed': string;
+    'clean.stale.none': string;
+    'clean.stale.preview': string;
+    'clean.stale.item': string;
+    'clean.stale.registryOnlyPath': string;
+    'clean.stale.headsUnavailable': string;
+    'clean.stale.listingFailed': string;
+    'clean.stale.probeFailed': string;
+    'clean.stale.deleted': string;
+    'clean.stale.failed': string;
+    'clean.stale.skippedLive': string;
+    'clean.stale.reason.refMissing': string;
+    'clean.stale.reason.diskOnly': string;
+    'clean.stale.reason.registryOnly': string;
+    'clean.stale.reason.headsUnavailable': string;
+    'clean.stale.reason.probeFailed': string;
+    'clean.stale.reason.listingFailed': string;
     'clean.deleteBranch': string;
     'clean.deletedBranch': string;
     'clean.lbugSidecars.state': string;
@@ -95,6 +111,9 @@ export declare const zhCN: {
     'doctor.runtime': string;
     'doctor.capabilities': string;
     'doctor.embeddings': string;
+    'doctor.orphanedBranches': string;
+    'doctor.orphanedBranches.total': string;
+    'doctor.orphanedBranches.reclaim': string;
     'doctor.labels.os': string;
     'doctor.labels.node': string;
     'doctor.labels.gitnexus': string;
@@ -215,6 +234,7 @@ export declare const zhCN: {
     'help.option.clean.all': string;
     'help.option.clean.branch': string;
     'help.option.clean.lbugSidecars': string;
+    'help.option.clean.stale': string;
     'help.option.wiki.force': string;
     'help.option.wiki.provider': string;
     'help.option.wiki.model': string;

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

@@ -53,7 +53,23 @@ export const zhCN = {
     'clean.deletedRepo': '已删除：{{name}}（{{storagePath}}）',
     'clean.notFoundHere': '当前目录未找到已索引仓库。',
     'clean.deleteCurrent': '将删除该仓库的 GitNexus 索引：{{repoName}}',
-    'clean.branchNotIndexed': '该仓库没有名为 “{{branch}}” 的已索引分支。',
+    'clean.branchNotIndexed': '该仓库没有名为 “{{branch}}” 的已索引分支。使用 `gitnexus clean --stale` 回收残留分支索引，或使用 `gitnexus list` 查看已记录名称。',
+    'clean.stale.none': '没有可回收的残留分支索引。',
+    'clean.stale.preview': '将删除 {{count}} 个残留分支索引：',
+    'clean.stale.item': '{{branch}}  {{reason}}  {{path}}  {{size}}',
+    'clean.stale.registryOnlyPath': '（仅注册表）',
+    'clean.stale.headsUnavailable': '无法列出本地分支，因此未删除残留分支索引。请在 git 可用后重新运行 `gitnexus clean --stale`。',
+    'clean.stale.listingFailed': '无法读取残留分支索引目录，因此未删除残留索引。请检查 branches/ 目录权限后重新运行 `gitnexus clean --stale`。',
+    'clean.stale.probeFailed': '无法检查残留分支索引路径，因此未删除这些槽位。',
+    'clean.stale.deleted': '已删除残留分支索引：{{branch}}',
+    'clean.stale.failed': '无法删除残留分支索引 “{{branch}}”。',
+    'clean.stale.skippedLive': '已跳过残留分支索引 “{{branch}}” — 它再次成为本地分支。',
+    'clean.stale.reason.refMissing': '不是本地分支',
+    'clean.stale.reason.diskOnly': '残留目录（无注册表记录）',
+    'clean.stale.reason.registryOnly': '注册表记录（目录已不存在）',
+    'clean.stale.reason.headsUnavailable': '无法列出本地分支',
+    'clean.stale.reason.probeFailed': '无法检查槽位路径',
+    'clean.stale.reason.listingFailed': '无法列出残留目录',
     'clean.deleteBranch': '将删除分支索引 “{{branch}}”，路径：{{path}}',
     'clean.deletedBranch': '已删除分支索引：{{branch}}',
     'clean.lbugSidecars.state': 'LadybugDB sidecar 状态：{{state}}',
@@ -95,6 +111,9 @@ export const zhCN = {
     'doctor.runtime': '运行时',
     'doctor.capabilities': '能力',
     'doctor.embeddings': '嵌入',
+    'doctor.orphanedBranches': '残留分支索引',
+    'doctor.orphanedBranches.total': '合计：{{size}}',
+    'doctor.orphanedBranches.reclaim': '回收命令：gitnexus clean --stale',
     'doctor.labels.os': '系统：',
     'doctor.labels.node': 'Node：',
     'doctor.labels.gitnexus': 'GitNexus：',
@@ -215,6 +234,7 @@ export const zhCN = {
     'help.option.clean.all': '清理所有已索引仓库',
     'help.option.clean.branch': '仅删除指定分支的索引（不影响工作区索引）',
     'help.option.clean.lbugSidecars': '清理已暂存的 LadybugDB 恢复 sidecar（missing-shadow WAL 隔离文件与 dirty-recovery 暂存文件）',
+    'help.option.clean.stale': '回收已不是本地 head 的残留分支索引',
     'help.option.wiki.force': '即使已是最新也强制完整重新生成',
     'help.option.wiki.provider': 'LLM 提供商：minimax、openai、openrouter、azure、custom、cursor、claude、codex、opencode 或 grok（默认：minimax）',
     'help.option.wiki.model': 'LLM 模型或 deployment 名称（默认：MiniMax-M3）',

package/dist/cli/index.js

@@ -211,6 +211,7 @@ program
     .option('-f, --force', 'Skip confirmation prompt')
     .option('--all', 'Clean all indexed repos')
     .option('--branch <name>', 'Delete only the named branch index (not the workspace index)')
+    .option('--stale', 'Reclaim leftover branch indexes that are not a live local head')
     .option('--lbug-sidecars', 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)')
     .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
 program

package/dist/cli/stale-branch-format.d.ts

@@ -0,0 +1,4 @@
+import { type StaleBranchReason, type StaleBranchSlot } from '../storage/stale-branch-slots.js';
+export declare const formatSlotSize: (bytes: number) => string;
+export declare const staleReasonLabel: (reason: StaleBranchReason) => string;
+export declare const formatStaleSlotLine: (slot: StaleBranchSlot) => string;

package/dist/cli/stale-branch-format.js

@@ -0,0 +1,34 @@
+import { t } from './i18n/index.js';
+export const formatSlotSize = (bytes) => {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+};
+export const staleReasonLabel = (reason) => {
+    switch (reason) {
+        case 'ref-missing':
+            return t('clean.stale.reason.refMissing');
+        case 'disk-only':
+            return t('clean.stale.reason.diskOnly');
+        case 'registry-only':
+            return t('clean.stale.reason.registryOnly');
+        case 'heads-unavailable':
+            return t('clean.stale.reason.headsUnavailable');
+        case 'probe-failed':
+            return t('clean.stale.reason.probeFailed');
+        case 'listing-failed':
+            return t('clean.stale.reason.listingFailed');
+        default: {
+            const _exhaustive = reason;
+            return _exhaustive;
+        }
+    }
+};
+export const formatStaleSlotLine = (slot) => t('clean.stale.item', {
+    branch: slot.branch,
+    reason: staleReasonLabel(slot.reason),
+    path: slot.dir ?? t('clean.stale.registryOnlyPath'),
+    size: formatSlotSize(slot.sizeBytes),
+});

package/dist/storage/git.d.ts

@@ -227,6 +227,12 @@ export declare const getDefaultBranch: (repoPath: string) => string | null;
  * "HEAD" (#2106).
  */
 export declare const getCurrentBranch: (repoPath: string) => string | null;
+/**
+ * Local `refs/heads` names, or `null` when the directory is not a git
+ * worktree or git cannot run. An empty array means the listing succeeded
+ * and there are no local heads — that is not a listing failure (#3331).
+ */
+export declare const listLocalHeads: (repoPath: string) => string[] | null;
 /**
  * Sanitize a repository name to prevent argument injection and ensure
  * cross-platform filesystem compatibility.

package/dist/storage/git.js

@@ -1,4 +1,4 @@
-import { execFileSync, execSync } from 'child_process';
+import { execFileSync, execSync, spawnSync } from 'child_process';
 import { statSync, existsSync } from 'fs';
 import path from 'path';
 import os from 'os';
@@ -633,6 +633,36 @@ export const getCurrentBranch = (repoPath) => {
         return null;
     }
 };
+/**
+ * Local `refs/heads` names, or `null` when the directory is not a git
+ * worktree or git cannot run. An empty array means the listing succeeded
+ * and there are no local heads — that is not a listing failure (#3331).
+ */
+export const listLocalHeads = (repoPath) => {
+    try {
+        const result = spawnSync('git', ['for-each-ref', '--format=%(refname)', 'refs/heads'], {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+            maxBuffer: GIT_PATH_LIST_MAX_BUFFER,
+        });
+        if (result.error || result.status !== 0)
+            return null;
+        const output = (result.stdout ?? '').toString().trim();
+        if (!output)
+            return [];
+        return output
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.startsWith('refs/heads/'))
+            .map((line) => line.slice('refs/heads/'.length))
+            .filter((line) => line.length > 0);
+    }
+    catch {
+        return null;
+    }
+};
 /**
  * Sanitize a repository name to prevent argument injection and ensure
  * cross-platform filesystem compatibility.

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

@@ -120,6 +120,8 @@ export interface RegistryEntry {
      */
     branches?: BranchSummary[];
 }
+/** Path-only registry lookup. Canonicalizes `repoPath` once. Does not throw. */
+export declare const findRegistryEntryByRepoPath: (entries: readonly RegistryEntry[], repoPath: string) => RegistryEntry | undefined;
 /**
  * Get paths to key storage files.
  *

package/dist/storage/repo-manager.js

@@ -110,6 +110,11 @@ export const registryPathEquals = (a, b) => process.platform === 'win32' ? a.toL
  * differently-spelled forms of the same dir still match.
  */
 export const cloneDirBelongsToEntry = (cloneDir, entryPath) => registryPathEquals(canonicalizePath(cloneDir), canonicalizePath(entryPath));
+/** Path-only registry lookup. Canonicalizes `repoPath` once. Does not throw. */
+export const findRegistryEntryByRepoPath = (entries, repoPath) => {
+    const repoKey = canonicalizePath(repoPath);
+    return entries.find((entry) => registryPathEquals(canonicalizePath(entry.path), repoKey));
+};
 const GITNEXUS_EXCLUDE_ENTRY = `${GITNEXUS_DIR}/`;
 // ─── Local Storage Helpers ─────────────────────────────────────────────
 /**

package/dist/storage/stale-branch-slots.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Classify and reclaim leftover per-branch index slots (#3331).
+ *
+ * Live means a name in local `refs/heads`. Classification never reverses
+ * `branchSlug`; registry rows join through the same forward slug path
+ * `clean --branch` already computes. Directory delete happens before the
+ * registry drop; a failed rm keeps the summary so a later clean can retry.
+ */
+export type StaleBranchReason = 'ref-missing' | 'registry-only' | 'disk-only' | 'heads-unavailable' | 'probe-failed' | 'listing-failed';
+export interface StaleBranchSlot {
+    branch: string;
+    dir: string | null;
+    sizeBytes: number;
+    reason: StaleBranchReason;
+}
+export interface ListStaleBranchSlotsInput {
+    repoPath: string;
+    storagePath: string;
+    branches?: readonly {
+        branch: string;
+    }[];
+    /** Injected in tests. When omitted, listed from `repoPath`. */
+    heads?: string[] | null;
+    /** Default true. `--stale --force` skips the size walk; it never prints sizes. */
+    includeSize?: boolean;
+}
+export declare const listStaleBranchSlots: (input: ListStaleBranchSlotsInput) => Promise<StaleBranchSlot[]>;
+export declare const isContainedBranchDir: (storagePath: string, dir: string) => boolean;
+export declare const isDeleteCandidate: (slot: StaleBranchSlot) => boolean;
+export type StaleListingBlock = 'heads-unavailable' | 'listing-failed';
+/** Git-list or branches/ listing failed; clean and doctor must not reclaim. */
+export declare const staleListingBlock: (slots: readonly StaleBranchSlot[]) => StaleListingBlock | null;
+export interface RemoveBranchSlotInput {
+    repoPath: string;
+    storagePath: string;
+    branch: string;
+    /** Slot directory to remove, or `null` for a registry-only row. */
+    dir: string | null;
+}
+export interface RemoveBranchSlotResult {
+    ok: boolean;
+    emptiedBranchesDir: boolean;
+    keptRegistry: boolean;
+    error?: Error;
+}
+export declare const removeBranchSlot: (input: RemoveBranchSlotInput) => Promise<RemoveBranchSlotResult>;

package/dist/storage/stale-branch-slots.js

@@ -0,0 +1,300 @@
+/**
+ * Classify and reclaim leftover per-branch index slots (#3331).
+ *
+ * Live means a name in local `refs/heads`. Classification never reverses
+ * `branchSlug`; registry rows join through the same forward slug path
+ * `clean --branch` already computes. Directory delete happens before the
+ * registry drop; a failed rm keeps the summary so a later clean can retry.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { BRANCHES_DIR } from './branch-index.js';
+import { listLocalHeads } from './git.js';
+import { isMissingFilesystemError, loadMeta } from './repo-meta.js';
+import { getStoragePaths, removeBranchIndex } from './repo-manager.js';
+const slotDirForBranch = (repoPath, storagePath, branch) => path.dirname(getStoragePaths(repoPath, branch, storagePath).metaPath);
+/** Same bound as `mapPool` in repo-manager: cap concurrent slot I/O. */
+const STALE_SLOT_IO_CONCURRENCY = 8;
+const mapPool = async (items, mapper) => {
+    if (items.length === 0)
+        return [];
+    const results = new Array(items.length);
+    let next = 0;
+    const workerCount = Math.max(1, Math.min(STALE_SLOT_IO_CONCURRENCY, items.length));
+    await Promise.all(Array.from({ length: workerCount }, async () => {
+        while (true) {
+            const index = next;
+            next += 1;
+            if (index >= items.length)
+                return;
+            results[index] = await mapper(items[index]);
+        }
+    }));
+    return results;
+};
+const probeDirectory = async (dir) => {
+    try {
+        return (await fs.stat(dir)).isDirectory() ? 'dir' : 'unreadable';
+    }
+    catch (err) {
+        return isMissingFilesystemError(err) ? 'missing' : 'unreadable';
+    }
+};
+const directorySizeBytes = async (root) => {
+    let total = 0;
+    const stack = [root];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current === undefined)
+            break;
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        const files = entries
+            .filter((entry) => entry.isFile())
+            .map((entry) => path.join(current, entry.name));
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                stack.push(path.join(current, entry.name));
+        }
+        for (const file of files) {
+            try {
+                total += (await fs.stat(file)).size;
+            }
+            catch {
+                // Skip files that disappear or become unreadable mid-walk.
+            }
+        }
+    }
+    return total;
+};
+const metadataBranch = async (dir) => {
+    const meta = await loadMeta(dir);
+    return typeof meta?.branch === 'string' && meta.branch.length > 0 ? meta.branch : null;
+};
+export const listStaleBranchSlots = async (input) => {
+    const recorded = input.branches ?? [];
+    const branchesRoot = path.join(input.storagePath, BRANCHES_DIR);
+    const registryByDir = new Map();
+    for (const row of recorded) {
+        registryByDir.set(path.resolve(slotDirForBranch(input.repoPath, input.storagePath, row.branch)), row.branch);
+    }
+    let diskDirs = [];
+    try {
+        const entries = await fs.readdir(branchesRoot, { withFileTypes: true });
+        diskDirs = entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => path.join(branchesRoot, entry.name));
+    }
+    catch (err) {
+        if (!isMissingFilesystemError(err)) {
+            return [{ branch: '', dir: null, sizeBytes: 0, reason: 'listing-failed' }];
+        }
+        diskDirs = [];
+    }
+    if (recorded.length === 0 && diskDirs.length === 0)
+        return [];
+    const heads = input.heads !== undefined ? input.heads : listLocalHeads(input.repoPath);
+    const live = heads === null ? null : new Set(heads);
+    const pending = [];
+    const registryProbes = await mapPool([...registryByDir], async ([resolvedDir, branch]) => ({
+        resolvedDir,
+        branch,
+        probe: await probeDirectory(resolvedDir),
+    }));
+    for (const { resolvedDir, branch, probe } of registryProbes) {
+        if (probe === 'unreadable') {
+            pending.push({ branch, dir: resolvedDir, reason: 'probe-failed' });
+            continue;
+        }
+        const exists = probe === 'dir';
+        const dir = exists ? resolvedDir : null;
+        if (live === null) {
+            pending.push({ branch, dir, reason: 'heads-unavailable' });
+            continue;
+        }
+        if (!exists) {
+            pending.push({ branch, dir: null, reason: 'registry-only' });
+            continue;
+        }
+        if (!live.has(branch)) {
+            pending.push({ branch, dir, reason: 'ref-missing' });
+        }
+    }
+    const leftoverDirs = diskDirs.filter((dir) => !registryByDir.has(path.resolve(dir)));
+    const leftoverMeta = await mapPool(leftoverDirs, async (dir) => ({
+        dir,
+        branch: await metadataBranch(dir),
+    }));
+    for (const { dir, branch } of leftoverMeta) {
+        if (branch === null)
+            continue;
+        const resolved = path.resolve(dir);
+        if (live === null) {
+            pending.push({ branch, dir: resolved, reason: 'heads-unavailable' });
+            continue;
+        }
+        if (!live.has(branch)) {
+            pending.push({ branch, dir: resolved, reason: 'disk-only' });
+        }
+    }
+    const includeSize = input.includeSize !== false;
+    return mapPool(pending, async (row) => ({
+        ...row,
+        sizeBytes: includeSize && row.dir ? await directorySizeBytes(row.dir) : 0,
+    }));
+};
+/** Lexical / realpath containment: `child` is a proper descendant of `parent`. */
+const isProperChildPath = (parent, child) => {
+    const root = path.resolve(parent);
+    const resolved = path.resolve(child);
+    const relative = path.relative(root, resolved);
+    return (relative !== '' &&
+        relative !== '..' &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+};
+const isSameNormalizedPath = (left, right) => path.relative(path.resolve(path.normalize(left)), path.resolve(path.normalize(right))) === '';
+export const isContainedBranchDir = (storagePath, dir) => isProperChildPath(path.resolve(storagePath, BRANCHES_DIR), dir);
+const toError = (err) => (err instanceof Error ? err : new Error(String(err)));
+const keepRegistryFailure = (error) => ({
+    ok: false,
+    emptiedBranchesDir: false,
+    keptRegistry: true,
+    error,
+});
+const refuseOutsideSlot = (dir) => keepRegistryFailure(new Error(`Refusing to clean branch index outside the validated storage slot: ${dir}`));
+const slotPathExists = async (slotDir) => {
+    try {
+        await fs.lstat(slotDir);
+        return true;
+    }
+    catch (err) {
+        return !isMissingFilesystemError(err);
+    }
+};
+/**
+ * Delete a lexically contained slot. Returns a failure result, or `null` when
+ * the slot path is gone and the registry row may drop.
+ */
+const removeValidatedSlotDir = async (storagePath, dir) => {
+    if (!isContainedBranchDir(storagePath, dir)) {
+        return refuseOutsideSlot(dir);
+    }
+    const branchesRoot = path.resolve(storagePath, BRANCHES_DIR);
+    let branchesStat;
+    try {
+        branchesStat = await fs.lstat(branchesRoot);
+    }
+    catch (err) {
+        if (isMissingFilesystemError(err))
+            return null;
+        return keepRegistryFailure(toError(err));
+    }
+    // Never walk a branches/ symlink (rm of a child would delete the target).
+    if (branchesStat.isSymbolicLink()) {
+        return refuseOutsideSlot(dir);
+    }
+    let realStorage;
+    let realBranches;
+    try {
+        realStorage = await fs.realpath(storagePath);
+        realBranches = await fs.realpath(branchesRoot);
+    }
+    catch (err) {
+        if (isMissingFilesystemError(err))
+            return null;
+        return keepRegistryFailure(toError(err));
+    }
+    // Junctions may not report as symlinks from lstat; realpath must still land
+    // on storagePath/branches, not an outside tree.
+    const expectedBranches = path.normalize(path.join(realStorage, BRANCHES_DIR));
+    if (!isSameNormalizedPath(realBranches, expectedBranches)) {
+        return refuseOutsideSlot(dir);
+    }
+    let slotStat;
+    try {
+        slotStat = await fs.lstat(dir);
+    }
+    catch (err) {
+        if (isMissingFilesystemError(err))
+            return null;
+        return keepRegistryFailure(toError(err));
+    }
+    let deleteError;
+    try {
+        // A symlink, or a Windows junction that lstat reports as a directory,
+        // must be unlinked at the lexical path. Never fs.rm through a target
+        // that realpath places outside branches/.
+        const realDir = slotStat.isSymbolicLink() ? null : await fs.realpath(dir);
+        const unlinkOnly = slotStat.isSymbolicLink() || (realDir !== null && !isProperChildPath(realBranches, realDir));
+        // Revalidate immediately before the destructive op. Another process can
+        // replace branches/ or the slot after the earlier lstat/realpath awaits.
+        const lastBranches = await fs.lstat(branchesRoot);
+        if (lastBranches.isSymbolicLink()) {
+            return refuseOutsideSlot(dir);
+        }
+        const lastSlot = await fs.lstat(dir);
+        const lastUnlinkOnly = lastSlot.isSymbolicLink() || unlinkOnly;
+        if (lastUnlinkOnly) {
+            await fs.unlink(dir);
+        }
+        else {
+            const lastReal = await fs.realpath(dir);
+            if (!isProperChildPath(realBranches, lastReal)) {
+                await fs.unlink(dir);
+            }
+            else {
+                await fs.rm(dir, { recursive: true, force: true });
+            }
+        }
+    }
+    catch (err) {
+        deleteError = toError(err);
+    }
+    if (await slotPathExists(dir)) {
+        return keepRegistryFailure(deleteError ?? new Error(`Could not remove branch index: ${dir}`));
+    }
+    return null;
+};
+export const isDeleteCandidate = (slot) => slot.reason === 'ref-missing' || slot.reason === 'registry-only' || slot.reason === 'disk-only';
+/** Git-list or branches/ listing failed; clean and doctor must not reclaim. */
+export const staleListingBlock = (slots) => {
+    if (slots.some((slot) => slot.reason === 'heads-unavailable'))
+        return 'heads-unavailable';
+    if (slots.some((slot) => slot.reason === 'listing-failed'))
+        return 'listing-failed';
+    return null;
+};
+const rmdirEmptyBranches = async (storagePath) => {
+    try {
+        await fs.rmdir(path.join(storagePath, BRANCHES_DIR));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const removeBranchSlot = async (input) => {
+    const { repoPath, storagePath, branch, dir } = input;
+    if (dir !== null) {
+        const slotDirError = await removeValidatedSlotDir(storagePath, dir);
+        if (slotDirError)
+            return slotDirError;
+    }
+    const dropRegistry = dir === null || isSameNormalizedPath(dir, slotDirForBranch(repoPath, storagePath, branch));
+    if (dropRegistry) {
+        try {
+            await removeBranchIndex(repoPath, branch);
+        }
+        catch (err) {
+            return keepRegistryFailure(toError(err));
+        }
+    }
+    const emptiedBranchesDir = await rmdirEmptyBranches(storagePath);
+    return { ok: true, emptiedBranchesDir, keptRegistry: !dropRegistry };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.13-rc.24",
+  "version": "1.6.13-rc.25",
   "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",