gitnexus 1.6.13-rc.23 → 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.
  *