gitnexus 1.6.13-rc.35 → 1.6.13-rc.36

package/dist/cli/ai-context.js

@@ -5,6 +5,8 @@
  * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, CodeBuddy, Qoder, etc.
  * CLAUDE.md is for Claude Code which only reads that file.
  */
+import { GITNEXUS_DIR } from '../storage/storage-constants.js';
+import { storeRootOfCheckoutSlot } from '../storage/shared-store.js';
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -470,11 +472,17 @@ export async function generateAIContextFiles(repoPath, storagePath, projectName,
     // CLI and hooks already share; failure to copy is non-fatal (docs carry a
     // bootstrap fallback). `runnerPath` is project-relative with POSIX separators
     // so the emitted command is identical across platforms.
-    const runnerPath = path.relative(repoPath, path.join(storagePath, 'run.cjs')).replace(/\\/g, '/');
+    // A shared-store slot (#3352) lives under the GitNexus home, so its path
+    // would be machine- and worktree-specific in committed docs; the runner goes
+    // next to the checkout's store pointer instead.
+    const runnerDir = storeRootOfCheckoutSlot(storagePath)
+        ? path.join(repoPath, GITNEXUS_DIR)
+        : storagePath;
+    const runnerPath = path.relative(repoPath, path.join(runnerDir, 'run.cjs')).replace(/\\/g, '/');
     try {
         const runnerSrc = path.join(__dirname, '..', '..', 'hooks', 'claude', 'resolve-analyze-cmd.cjs');
-        await fs.mkdir(storagePath, { recursive: true });
-        await fs.copyFile(runnerSrc, path.join(storagePath, 'run.cjs'));
+        await fs.mkdir(runnerDir, { recursive: true });
+        await fs.copyFile(runnerSrc, path.join(runnerDir, 'run.cjs'));
     }
     catch (err) {
         logger.warn(`Could not write GitNexus runner to ${runnerPath}: ${String(err)}`);

package/dist/cli/analyze-options.d.ts

@@ -103,6 +103,10 @@ export interface AnalyzeOptions {
      * `allowDuplicateName` option end-to-end.
      */
     allowDuplicateName?: boolean;
+    /** `--share-with <repo>`: join that checkout's shared store (#3352). */
+    shareWith?: string;
+    /** `--no-share` sets this to false: leave the shared store (#3352). */
+    share?: boolean;
     /**
      * Override the walker's large-file skip threshold (#991). Value in KB;
      * clamped downstream to the tree-sitter 32 MB ceiling. Sets

package/dist/cli/analyze.js

@@ -1128,6 +1128,8 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             // be able to accept the duplicate name without also paying the
             // cost of a full pipeline re-index. See #829 review round 2.
             allowDuplicateName: options.allowDuplicateName,
+            shareWith: options.shareWith,
+            noShare: options.share === false,
             // Worker pool size threaded from --workers, replacing the previous
             // GITNEXUS_WORKER_POOL_SIZE env mutation. `undefined` defers to the
             // env / auto-formula fallback inside the pipeline.

package/dist/cli/clean.d.ts

@@ -10,4 +10,6 @@ export declare const cleanCommand: (options?: {
     lbugSidecars?: boolean;
     stale?: boolean;
     branch?: string;
+    gc?: boolean;
+    localIndex?: boolean;
 }) => Promise<void>;

package/dist/cli/clean.js

@@ -9,11 +9,14 @@ import path from 'path';
 import { logger } from '../core/logger.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 { formatSlotSize, 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';
+import { getGlobalDir } from '../storage/global-dir.js';
+import { STORES_DIR } from '../storage/shared-store.js';
+import { findLegacyLocalIndex, reclaimAfterSlotRemoval, reclaimSharedStore, removeLegacyLocalIndex, removeCheckoutStorage, } from '../storage/shared-store-lifecycle.js';
 const resolveOwnedCwdStorage = async (refusePrefix) => {
     const repo = await findRepo(process.cwd());
     if (!repo) {
@@ -115,7 +118,91 @@ const cleanStaleBranchSlots = async (force) => {
         printStaleSlotLines(t('clean.stale.probeFailed'), probeFailed);
     }
 };
+const reportReclaim = (result) => {
+    if (!result)
+        return;
+    if (result.removed.length > 0) {
+        console.log(t('clean.shared.reclaimed', { count: result.removed.length }));
+    }
+    if (result.kept.length > 0)
+        console.log(t('clean.shared.kept', { count: result.kept.length }));
+};
+/** `clean --gc`: collect every shared store under GITNEXUS_HOME (#3352). */
+const collectSharedStores = async (force) => {
+    const storesDir = path.join(getGlobalDir(), STORES_DIR);
+    // Only a missing stores root means "nothing to collect"; an unreadable one
+    // must fail loudly rather than report success.
+    const names = await fs.readdir(storesDir).catch((err) => {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    });
+    // Stray files (`.DS_Store`) are not stores, and a symlink is not followed:
+    // reclaim deletes under the root it is given. A store another collector
+    // removed meanwhile is simply gone. The lstat skips a stray link; it is not
+    // a race guard, since stores/ belongs to the user running clean and anyone
+    // able to swap an entry there can already delete the store itself.
+    const roots = [];
+    for (const name of names) {
+        const root = path.join(storesDir, name);
+        const stat = await fs.lstat(root).catch((err) => {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        });
+        if (stat?.isDirectory())
+            roots.push(root);
+    }
+    if (roots.length === 0) {
+        console.log(t('clean.gc.none'));
+        return;
+    }
+    for (const root of roots) {
+        // Without --force this is a preview: same selection, nothing deleted.
+        const result = await reclaimSharedStore(root, { gc: true, dryRun: !force });
+        console.log(t(force ? 'clean.gc.store' : 'clean.gc.preview', {
+            path: root,
+            members: result.droppedMembers.length,
+            graphs: result.removed.length,
+        }));
+        if (result.keptMembers.length > 0) {
+            console.log(t('clean.gc.keptMembers', { count: result.keptMembers.length }));
+        }
+        if (result.kept.length > 0)
+            console.log(t('clean.shared.kept', { count: result.kept.length }));
+        if (result.storeRemoved)
+            console.log(t('clean.shared.storeRemoved', { path: root }));
+    }
+    if (!force)
+        console.log(`\n${t('common.runForceConfirm')}`);
+};
 export const cleanCommand = async (options) => {
+    if (options?.gc) {
+        await collectSharedStores(options.force === true);
+        return;
+    }
+    // --local-index: delete a pre-adoption index left in <checkout>/.gitnexus
+    // after the checkout moved into a shared store (#3352). Keeps the pointer.
+    if (options?.localIndex) {
+        const repo = await findRepo(process.cwd());
+        if (!repo) {
+            console.log(t('clean.notFoundHere'));
+            return;
+        }
+        const legacy = await findLegacyLocalIndex(repo.repoPath, repo.storagePath);
+        if (!legacy) {
+            console.log(t('clean.localIndex.none'));
+            return;
+        }
+        if (!options.force) {
+            console.log(t('clean.localIndex.preview', { path: legacy.dir, size: formatSlotSize(legacy.bytes) }));
+            console.log(`\n${t('common.runForceConfirm')}`);
+            return;
+        }
+        await removeLegacyLocalIndex(repo.repoPath, repo.storagePath);
+        console.log(t('clean.localIndex.deleted', { path: legacy.dir, size: formatSlotSize(legacy.bytes) }));
+        return;
+    }
     // --stale: reclaim leftover per-branch slots whose recorded branch is not
     // a live local head (#3331). Exclusive arm before --branch.
     if (options?.stale) {
@@ -246,9 +333,12 @@ export const cleanCommand = async (options) => {
         for (const entry of entries) {
             try {
                 const storagePath = await requireDeletableStoragePath(entry);
-                await fs.rm(storagePath, { recursive: true, force: true });
-                await unregisterRepo(entry.path);
+                // A shared slot is unregistered before it is deleted: its lock file
+                // lives inside it, so it must go last. A failed delete throws with the
+                // `clean --gc --force` recovery (shared-store-clean.test.ts).
+                await removeCheckoutStorage(storagePath, () => unregisterRepo(entry.path), entry.path);
                 console.log(t('clean.deletedRepo', { name: entry.name, storagePath }));
+                reportReclaim(await reclaimAfterSlotRemoval(storagePath));
             }
             catch (err) {
                 if (err instanceof StorageDeletionError) {
@@ -289,9 +379,9 @@ export const cleanCommand = async (options) => {
         return;
     }
     try {
-        await fs.rm(storagePath, { recursive: true, force: true });
-        await unregisterRepo(repo.repoPath);
+        await removeCheckoutStorage(storagePath, () => unregisterRepo(repo.repoPath), repo.repoPath);
         console.log(t('common.deleted', { target: storagePath }));
+        reportReclaim(await reclaimAfterSlotRemoval(storagePath));
     }
     catch (err) {
         logger.error({ err }, 'Failed to delete:');

package/dist/cli/doctor.js

@@ -1,4 +1,5 @@
 import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/capabilities.js';
+import { findLegacyLocalIndex } from '../storage/shared-store-lifecycle.js';
 import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
 import { isHttpMode } from '../core/embeddings/http-client.js';
 import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
@@ -327,6 +328,12 @@ export const doctorCommand = async () => {
         branches: entry?.branches,
     });
     const leftoverLines = leftoverBranchSlotDoctorLines(slots);
+    // A pre-adoption index left in <repo>/.gitnexus after this checkout moved
+    // into a shared store (#3352).
+    const legacy = await findLegacyLocalIndex(cwdRepo.repoPath, cwdRepo.storagePath);
+    if (legacy) {
+        leftoverLines.push(t('status.legacyLocalIndex', { path: legacy.dir, size: formatSlotSize(legacy.bytes) }));
+    }
     if (leftoverLines.length === 0)
         return;
     console.log('');

package/dist/cli/embeddings-sync.js

@@ -1,4 +1,6 @@
 import { lstat } from 'node:fs/promises';
+import { ensurePrivateSharedGraph } from '../core/shared-store-analyze.js';
+import { LBUG_DIRECTORY } from '../storage/storage-constants.js';
 import path from 'node:path';
 import { cliInfo } from './cli-message.js';
 import { getGitRoot } from '../storage/git.js';
@@ -17,11 +19,17 @@ export const embeddingsSyncCommand = async (inputPath) => {
     const repoPath = inputPath ? path.resolve(inputPath) : getGitRoot(process.cwd());
     if (!repoPath)
         throw new Error('Not inside a git repository. Pass a repository path.');
-    const { lbugPath, metaPath } = getStoragePaths(repoPath);
+    const { metaPath } = getStoragePaths(repoPath);
     const metaDir = path.dirname(metaPath);
+    // Writes go to the slot's own graph. A shared-store checkout that reads an
+    // immutable commit graph (#3352) takes a private copy first.
+    const lbugPath = path.join(metaDir, LBUG_DIRECTORY);
     const lock = await acquireIndexLock(metaDir);
     try {
         requireExclusiveIndexLock(lock, `Cannot acquire the index lock at ${metaDir}; refusing an unlocked embeddings sync.`);
+        if (!(await ensurePrivateSharedGraph(metaDir, (m) => console.log(`  ${m}`)))) {
+            throw new Error('The shared graph this checkout reads is gone. Run gitnexus analyze first.');
+        }
         const meta = await loadMeta(metaDir);
         if (!meta)
             throw new Error(`No GitNexus index found for ${repoPath}. Run gitnexus analyze first.`);

package/dist/cli/help-i18n.js

@@ -63,6 +63,8 @@ const OPTION_DESCRIPTION_KEYS = {
     'analyze|--skip-git': 'help.option.skipGit',
     'analyze|--name <alias>': 'help.option.analyze.name',
     'analyze|--allow-duplicate-name': 'help.option.analyze.allowDuplicateName',
+    'analyze|--share-with <repo>': 'help.option.analyze.shareWith',
+    'analyze|--no-share': 'help.option.analyze.noShare',
     'analyze|-v, --verbose': 'help.option.verbose',
     'analyze|--max-file-size <kb>': 'help.option.analyze.maxFileSize',
     'analyze|--worker-timeout <seconds>': 'help.option.analyze.workerTimeout',
@@ -93,6 +95,8 @@ const OPTION_DESCRIPTION_KEYS = {
     'clean|--branch <name>': 'help.option.clean.branch',
     'clean|--lbug-sidecars': 'help.option.clean.lbugSidecars',
     'clean|--stale': 'help.option.clean.stale',
+    'clean|--gc': 'help.option.clean.gc',
+    'clean|--local-index': 'help.option.clean.localIndex',
     '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

@@ -25,6 +25,11 @@ export declare const en: {
     readonly 'list.clusters': 'Clusters';
     readonly 'list.processes': 'Processes';
     readonly 'list.unknown': 'unknown';
+    readonly 'status.sharedStoreShared': 'Shared index: store {{key}}, shared graph for commit {{commit}}';
+    readonly 'status.sharedStorePrivate': 'Shared index: store {{key}}, private graph (local changes or a pinned branch index)';
+    readonly 'status.sharedStoreCloneCow': '  Copied copy-on-write: unchanged pages are shared with the commit graph on disk';
+    readonly 'status.sharedStoreCloneCopy': '  Full copy: this filesystem cannot clone copy-on-write (APFS, btrfs and XFS can)';
+    readonly 'status.legacyLocalIndex': 'Leftover local index: {{path}} ({{size}}); remove it with `gitnexus clean --local-index --force`';
     readonly 'status.notGitRepo': 'Not a git repository.';
     readonly 'status.staleKuzu': 'Repository has a stale KuzuDB index from a previous version.';
     readonly 'status.rebuildLadybug': 'Run: gitnexus analyze   (rebuilds the index with LadybugDB)';
@@ -52,6 +57,16 @@ export declare const en: {
     readonly 'clean.deleteAll': 'This will delete GitNexus indexes for {{count}} repo(s):';
     readonly 'clean.deletedRepo': 'Deleted: {{name}} ({{storagePath}})';
     readonly 'clean.notFoundHere': 'No indexed repository found in this directory.';
+    readonly 'clean.shared.reclaimed': 'Shared store: removed {{count}} commit graph(s) no checkout references.';
+    readonly 'clean.shared.kept': 'Shared store: kept {{count}} unreferenced commit graph(s) that could not be removed (in use or not writable); run `gitnexus clean --gc` later.';
+    readonly 'clean.shared.storeRemoved': 'Shared store: removed {{path}} (no checkouts remain).';
+    readonly 'clean.gc.none': 'No shared stores to collect.';
+    readonly 'clean.gc.keptMembers': 'Shared store: kept {{count}} checkout(s) it could not delete; run `gitnexus clean --gc --force` later.';
+    readonly 'clean.gc.store': 'Shared store {{path}}: dropped {{members}} checkout(s), removed {{graphs}} commit graph(s).';
+    readonly 'clean.gc.preview': 'Shared store {{path}}: would drop {{members}} checkout(s) and remove {{graphs}} commit graph(s).';
+    readonly 'clean.localIndex.none': 'No leftover local index in this checkout.';
+    readonly 'clean.localIndex.preview': 'This will delete the leftover local index at {{path}} ({{size}}). The shared index is not affected.';
+    readonly 'clean.localIndex.deleted': 'Deleted the leftover local index at {{path}} ({{size}}).';
     readonly 'clean.deleteCurrent': 'This will delete the GitNexus index for: {{repoName}}';
     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.';
@@ -208,6 +223,8 @@ export declare const en: {
     readonly 'help.option.skipGit': 'Treat the provided path/cwd as the index root and skip parent git-root discovery';
     readonly 'help.option.analyze.name': 'Register this repo under a custom name in ~/.gitnexus/registry.json (disambiguates repos whose paths share a basename, e.g. two different .../app folders)';
     readonly 'help.option.analyze.allowDuplicateName': 'Register this repo even if another path already uses the same --name alias. Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.';
+    readonly 'help.option.analyze.shareWith': 'Join the shared index store of a registered checkout of the same repository (name or path); the remote URL must match. Clones join a sibling clone’s store automatically; this names one explicitly and clears a --no-share opt-out.';
+    readonly 'help.option.analyze.noShare': 'Clones only: leave the shared index store, index into <repo>/.gitnexus again, and stop joining sibling clones automatically until --share-with (linked worktrees always share; set GITNEXUS_SHARED_STORE=off instead)';
     readonly 'help.option.verbose': 'Enable verbose output';
     readonly 'help.option.analyze.maxFileSize': 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).';
     readonly 'help.option.analyze.workerTimeout': 'Worker sub-batch idle timeout before retry/fallback. Default: 30.';
@@ -236,6 +253,8 @@ export declare const en: {
     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.clean.gc': 'Drop shared-store checkouts no registry entry uses and delete commit graphs nothing references';
+    readonly 'help.option.clean.localIndex': 'Delete the index left in <repo>/.gitnexus after this checkout moved into a shared store';
     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

@@ -25,6 +25,11 @@ export const en = {
     'list.clusters': 'Clusters',
     'list.processes': 'Processes',
     'list.unknown': 'unknown',
+    'status.sharedStoreShared': 'Shared index: store {{key}}, shared graph for commit {{commit}}',
+    'status.sharedStorePrivate': 'Shared index: store {{key}}, private graph (local changes or a pinned branch index)',
+    'status.sharedStoreCloneCow': '  Copied copy-on-write: unchanged pages are shared with the commit graph on disk',
+    'status.sharedStoreCloneCopy': '  Full copy: this filesystem cannot clone copy-on-write (APFS, btrfs and XFS can)',
+    'status.legacyLocalIndex': 'Leftover local index: {{path}} ({{size}}); remove it with `gitnexus clean --local-index --force`',
     'status.notGitRepo': 'Not a git repository.',
     'status.staleKuzu': 'Repository has a stale KuzuDB index from a previous version.',
     'status.rebuildLadybug': 'Run: gitnexus analyze   (rebuilds the index with LadybugDB)',
@@ -52,6 +57,16 @@ export const en = {
     'clean.deleteAll': 'This will delete GitNexus indexes for {{count}} repo(s):',
     'clean.deletedRepo': 'Deleted: {{name}} ({{storagePath}})',
     'clean.notFoundHere': 'No indexed repository found in this directory.',
+    'clean.shared.reclaimed': 'Shared store: removed {{count}} commit graph(s) no checkout references.',
+    'clean.shared.kept': 'Shared store: kept {{count}} unreferenced commit graph(s) that could not be removed (in use or not writable); run `gitnexus clean --gc` later.',
+    'clean.shared.storeRemoved': 'Shared store: removed {{path}} (no checkouts remain).',
+    'clean.gc.none': 'No shared stores to collect.',
+    'clean.gc.keptMembers': 'Shared store: kept {{count}} checkout(s) it could not delete; run `gitnexus clean --gc --force` later.',
+    'clean.gc.store': 'Shared store {{path}}: dropped {{members}} checkout(s), removed {{graphs}} commit graph(s).',
+    'clean.gc.preview': 'Shared store {{path}}: would drop {{members}} checkout(s) and remove {{graphs}} commit graph(s).',
+    'clean.localIndex.none': 'No leftover local index in this checkout.',
+    'clean.localIndex.preview': 'This will delete the leftover local index at {{path}} ({{size}}). The shared index is not affected.',
+    'clean.localIndex.deleted': 'Deleted the leftover local index at {{path}} ({{size}}).',
     'clean.deleteCurrent': 'This will delete the GitNexus index for: {{repoName}}',
     '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.',
@@ -210,6 +225,8 @@ export const en = {
     'help.option.skipGit': 'Treat the provided path/cwd as the index root and skip parent git-root discovery',
     'help.option.analyze.name': 'Register this repo under a custom name in ~/.gitnexus/registry.json (disambiguates repos whose paths share a basename, e.g. two different .../app folders)',
     'help.option.analyze.allowDuplicateName': 'Register this repo even if another path already uses the same --name alias. Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.',
+    'help.option.analyze.shareWith': 'Join the shared index store of a registered checkout of the same repository (name or path); the remote URL must match. Clones join a sibling clone’s store automatically; this names one explicitly and clears a --no-share opt-out.',
+    'help.option.analyze.noShare': 'Clones only: leave the shared index store, index into <repo>/.gitnexus again, and stop joining sibling clones automatically until --share-with (linked worktrees always share; set GITNEXUS_SHARED_STORE=off instead)',
     'help.option.verbose': 'Enable verbose output',
     'help.option.analyze.maxFileSize': 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).',
     'help.option.analyze.workerTimeout': 'Worker sub-batch idle timeout before retry/fallback. Default: 30.',
@@ -238,6 +255,8 @@ export const en = {
     '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.clean.gc': 'Drop shared-store checkouts no registry entry uses and delete commit graphs nothing references',
+    'help.option.clean.localIndex': 'Delete the index left in <repo>/.gitnexus after this checkout moved into a shared store',
     '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

@@ -26,6 +26,11 @@ export declare const cliResources: {
         readonly 'list.clusters': 'Clusters';
         readonly 'list.processes': 'Processes';
         readonly 'list.unknown': 'unknown';
+        readonly 'status.sharedStoreShared': 'Shared index: store {{key}}, shared graph for commit {{commit}}';
+        readonly 'status.sharedStorePrivate': 'Shared index: store {{key}}, private graph (local changes or a pinned branch index)';
+        readonly 'status.sharedStoreCloneCow': '  Copied copy-on-write: unchanged pages are shared with the commit graph on disk';
+        readonly 'status.sharedStoreCloneCopy': '  Full copy: this filesystem cannot clone copy-on-write (APFS, btrfs and XFS can)';
+        readonly 'status.legacyLocalIndex': 'Leftover local index: {{path}} ({{size}}); remove it with `gitnexus clean --local-index --force`';
         readonly 'status.notGitRepo': 'Not a git repository.';
         readonly 'status.staleKuzu': 'Repository has a stale KuzuDB index from a previous version.';
         readonly 'status.rebuildLadybug': 'Run: gitnexus analyze   (rebuilds the index with LadybugDB)';
@@ -53,6 +58,16 @@ export declare const cliResources: {
         readonly 'clean.deleteAll': 'This will delete GitNexus indexes for {{count}} repo(s):';
         readonly 'clean.deletedRepo': 'Deleted: {{name}} ({{storagePath}})';
         readonly 'clean.notFoundHere': 'No indexed repository found in this directory.';
+        readonly 'clean.shared.reclaimed': 'Shared store: removed {{count}} commit graph(s) no checkout references.';
+        readonly 'clean.shared.kept': 'Shared store: kept {{count}} unreferenced commit graph(s) that could not be removed (in use or not writable); run `gitnexus clean --gc` later.';
+        readonly 'clean.shared.storeRemoved': 'Shared store: removed {{path}} (no checkouts remain).';
+        readonly 'clean.gc.none': 'No shared stores to collect.';
+        readonly 'clean.gc.keptMembers': 'Shared store: kept {{count}} checkout(s) it could not delete; run `gitnexus clean --gc --force` later.';
+        readonly 'clean.gc.store': 'Shared store {{path}}: dropped {{members}} checkout(s), removed {{graphs}} commit graph(s).';
+        readonly 'clean.gc.preview': 'Shared store {{path}}: would drop {{members}} checkout(s) and remove {{graphs}} commit graph(s).';
+        readonly 'clean.localIndex.none': 'No leftover local index in this checkout.';
+        readonly 'clean.localIndex.preview': 'This will delete the leftover local index at {{path}} ({{size}}). The shared index is not affected.';
+        readonly 'clean.localIndex.deleted': 'Deleted the leftover local index at {{path}} ({{size}}).';
         readonly 'clean.deleteCurrent': 'This will delete the GitNexus index for: {{repoName}}';
         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.';
@@ -209,6 +224,8 @@ export declare const cliResources: {
         readonly 'help.option.skipGit': 'Treat the provided path/cwd as the index root and skip parent git-root discovery';
         readonly 'help.option.analyze.name': 'Register this repo under a custom name in ~/.gitnexus/registry.json (disambiguates repos whose paths share a basename, e.g. two different .../app folders)';
         readonly 'help.option.analyze.allowDuplicateName': 'Register this repo even if another path already uses the same --name alias. Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.';
+        readonly 'help.option.analyze.shareWith': 'Join the shared index store of a registered checkout of the same repository (name or path); the remote URL must match. Clones join a sibling clone’s store automatically; this names one explicitly and clears a --no-share opt-out.';
+        readonly 'help.option.analyze.noShare': 'Clones only: leave the shared index store, index into <repo>/.gitnexus again, and stop joining sibling clones automatically until --share-with (linked worktrees always share; set GITNEXUS_SHARED_STORE=off instead)';
         readonly 'help.option.verbose': 'Enable verbose output';
         readonly 'help.option.analyze.maxFileSize': 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).';
         readonly 'help.option.analyze.workerTimeout': 'Worker sub-batch idle timeout before retry/fallback. Default: 30.';
@@ -237,6 +254,8 @@ export declare const cliResources: {
         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.clean.gc': 'Drop shared-store checkouts no registry entry uses and delete commit graphs nothing references';
+        readonly 'help.option.clean.localIndex': 'Delete the index left in <repo>/.gitnexus after this checkout moved into a shared store';
         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)';
@@ -333,6 +352,11 @@ export declare const cliResources: {
         'list.clusters': string;
         'list.processes': string;
         'list.unknown': string;
+        'status.sharedStoreShared': string;
+        'status.sharedStorePrivate': string;
+        'status.sharedStoreCloneCow': string;
+        'status.sharedStoreCloneCopy': string;
+        'status.legacyLocalIndex': string;
         'status.notGitRepo': string;
         'status.staleKuzu': string;
         'status.rebuildLadybug': string;
@@ -360,6 +384,16 @@ export declare const cliResources: {
         'clean.deleteAll': string;
         'clean.deletedRepo': string;
         'clean.notFoundHere': string;
+        'clean.shared.reclaimed': string;
+        'clean.shared.kept': string;
+        'clean.shared.storeRemoved': string;
+        'clean.gc.none': string;
+        'clean.gc.keptMembers': string;
+        'clean.gc.store': string;
+        'clean.gc.preview': string;
+        'clean.localIndex.none': string;
+        'clean.localIndex.preview': string;
+        'clean.localIndex.deleted': string;
         'clean.deleteCurrent': string;
         'clean.branchNotIndexed': string;
         'clean.stale.none': string;
@@ -516,6 +550,8 @@ export declare const cliResources: {
         'help.option.skipGit': string;
         'help.option.analyze.name': string;
         'help.option.analyze.allowDuplicateName': string;
+        'help.option.analyze.shareWith': string;
+        'help.option.analyze.noShare': string;
         'help.option.verbose': string;
         'help.option.analyze.maxFileSize': string;
         'help.option.analyze.workerTimeout': string;
@@ -544,6 +580,8 @@ export declare const cliResources: {
         'help.option.clean.branch': string;
         'help.option.clean.lbugSidecars': string;
         'help.option.clean.stale': string;
+        'help.option.clean.gc': string;
+        'help.option.clean.localIndex': string;
         'help.option.wiki.force': string;
         'help.option.wiki.provider': string;
         'help.option.wiki.model': string;

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

@@ -25,6 +25,11 @@ export declare const zhCN: {
     'list.clusters': string;
     'list.processes': string;
     'list.unknown': string;
+    'status.sharedStoreShared': string;
+    'status.sharedStorePrivate': string;
+    'status.sharedStoreCloneCow': string;
+    'status.sharedStoreCloneCopy': string;
+    'status.legacyLocalIndex': string;
     'status.notGitRepo': string;
     'status.staleKuzu': string;
     'status.rebuildLadybug': string;
@@ -52,6 +57,16 @@ export declare const zhCN: {
     'clean.deleteAll': string;
     'clean.deletedRepo': string;
     'clean.notFoundHere': string;
+    'clean.shared.reclaimed': string;
+    'clean.shared.kept': string;
+    'clean.shared.storeRemoved': string;
+    'clean.gc.none': string;
+    'clean.gc.keptMembers': string;
+    'clean.gc.store': string;
+    'clean.gc.preview': string;
+    'clean.localIndex.none': string;
+    'clean.localIndex.preview': string;
+    'clean.localIndex.deleted': string;
     'clean.deleteCurrent': string;
     'clean.branchNotIndexed': string;
     'clean.stale.none': string;
@@ -208,6 +223,8 @@ export declare const zhCN: {
     'help.option.skipGit': string;
     'help.option.analyze.name': string;
     'help.option.analyze.allowDuplicateName': string;
+    'help.option.analyze.shareWith': string;
+    'help.option.analyze.noShare': string;
     'help.option.verbose': string;
     'help.option.analyze.maxFileSize': string;
     'help.option.analyze.workerTimeout': string;
@@ -236,6 +253,8 @@ export declare const zhCN: {
     'help.option.clean.branch': string;
     'help.option.clean.lbugSidecars': string;
     'help.option.clean.stale': string;
+    'help.option.clean.gc': string;
+    'help.option.clean.localIndex': string;
     'help.option.wiki.force': string;
     'help.option.wiki.provider': string;
     'help.option.wiki.model': string;

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

@@ -25,6 +25,11 @@ export const zhCN = {
     'list.clusters': '聚类',
     'list.processes': '流程',
     'list.unknown': 'unknown',
+    'status.sharedStoreShared': '共享索引：存储 {{key}}，提交 {{commit}} 的共享图',
+    'status.sharedStorePrivate': '共享索引：存储 {{key}}，私有图（有本地更改或固定分支索引）',
+    'status.sharedStoreCloneCow': '  写时复制副本：未更改的页面在磁盘上与提交图共享',
+    'status.sharedStoreCloneCopy': '  完整副本：此文件系统不支持写时复制克隆（APFS、btrfs 和 XFS 支持）',
+    'status.legacyLocalIndex': '残留的本地索引：{{path}}（{{size}}）；使用 `gitnexus clean --local-index --force` 删除',
     'status.notGitRepo': '当前目录不是 git 仓库。',
     'status.staleKuzu': '仓库包含旧版本遗留的 KuzuDB 索引。',
     'status.rebuildLadybug': '运行：gitnexus analyze   （使用 LadybugDB 重建索引）',
@@ -52,6 +57,16 @@ export const zhCN = {
     'clean.deleteAll': '将删除 {{count}} 个仓库的 GitNexus 索引：',
     'clean.deletedRepo': '已删除：{{name}}（{{storagePath}}）',
     'clean.notFoundHere': '当前目录未找到已索引仓库。',
+    'clean.shared.reclaimed': '共享存储：已删除 {{count}} 个不再被任何检出引用的提交图。',
+    'clean.shared.kept': '共享存储：保留了 {{count}} 个无法删除的未引用提交图（正在使用或不可写）；请稍后运行 `gitnexus clean --gc`。',
+    'clean.shared.storeRemoved': '共享存储：已删除 {{path}}（没有剩余检出）。',
+    'clean.gc.none': '没有可回收的共享存储。',
+    'clean.gc.keptMembers': '共享存储：保留了 {{count}} 个无法删除的检出；请稍后运行 `gitnexus clean --gc --force`。',
+    'clean.gc.store': '共享存储 {{path}}：移除了 {{members}} 个检出，删除了 {{graphs}} 个提交图。',
+    'clean.gc.preview': '共享存储 {{path}}：将移除 {{members}} 个检出并删除 {{graphs}} 个提交图。',
+    'clean.localIndex.none': '此检出中没有残留的本地索引。',
+    'clean.localIndex.preview': '将删除 {{path}} 处残留的本地索引（{{size}}）。共享索引不受影响。',
+    'clean.localIndex.deleted': '已删除 {{path}} 处残留的本地索引（{{size}}）。',
     'clean.deleteCurrent': '将删除该仓库的 GitNexus 索引：{{repoName}}',
     'clean.branchNotIndexed': '该仓库没有名为 “{{branch}}” 的已索引分支。使用 `gitnexus clean --stale` 回收残留分支索引，或使用 `gitnexus list` 查看已记录名称。',
     'clean.stale.none': '没有可回收的残留分支索引。',
@@ -208,6 +223,8 @@ export const zhCN = {
     'help.option.skipGit': '将提供的路径/cwd 视为索引根目录，并跳过向上查找 git 根目录',
     'help.option.analyze.name': '在 ~/.gitnexus/registry.json 中使用自定义名称注册该仓库（用于区分路径 basename 相同的仓库，例如两个不同的 .../app 目录）',
     'help.option.analyze.allowDuplicateName': '即使已有其他路径使用相同 --name 别名，也注册该仓库。会使两个路径的 `-r <name>` 产生歧义；请用 -r <path> 消除歧义。',
+    'help.option.analyze.shareWith': '加入同一仓库已注册检出的共享索引存储（名称或路径）；远程 URL 必须一致。克隆会自动加入同源克隆的存储；此选项显式指定存储，并清除 --no-share 的退出设置。',
+    'help.option.analyze.noShare': '仅限克隆：离开共享索引存储，重新索引到 <repo>/.gitnexus，并在使用 --share-with 之前不再自动加入同源克隆（链接工作树始终共享；请改用 GITNEXUS_SHARED_STORE=off）',
     'help.option.verbose': '启用详细输出',
     'help.option.analyze.maxFileSize': '跳过大于该值的文件（KB）。默认：512。硬上限：32768（tree-sitter 限制）。',
     'help.option.analyze.workerTimeout': 'Worker 子批次空闲超时，超时后重试/回退。默认：30。',
@@ -236,6 +253,8 @@ export const zhCN = {
     'help.option.clean.branch': '仅删除指定分支的索引（不影响工作区索引）',
     'help.option.clean.lbugSidecars': '清理已暂存的 LadybugDB 恢复 sidecar（missing-shadow WAL 隔离文件与 dirty-recovery 暂存文件）',
     'help.option.clean.stale': '回收已不是本地 head 的残留分支索引',
+    'help.option.clean.gc': '移除注册表不再使用的共享存储检出，并删除无人引用的提交图',
+    'help.option.clean.localIndex': '删除此检出迁入共享存储后遗留在 <repo>/.gitnexus 中的索引',
     '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

@@ -79,6 +79,12 @@ program
     '(disambiguates repos whose paths share a basename, e.g. two different .../app folders)')
     .option('--allow-duplicate-name', 'Register this repo even if another path already uses the same --name alias. ' +
     'Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.')
+    .option('--share-with <repo>', 'Join the shared index store of a registered checkout of the same repository ' +
+    '(name or path); the remote URL must match. Clones join a sibling clone’s store ' +
+    'automatically; this names one explicitly and clears a --no-share opt-out.')
+    .option('--no-share', 'Clones only: leave the shared index store, index into <repo>/.gitnexus again, and stop ' +
+    'joining sibling clones automatically until --share-with (linked worktrees always share; ' +
+    'set GITNEXUS_SHARED_STORE=off instead)')
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .option('--max-file-size <kb>', 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).')
     .option('--worker-timeout <seconds>', 'Worker sub-batch idle timeout before retry/fallback. Default: 30.')
@@ -212,6 +218,8 @@ program
     .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('--gc', 'Drop shared-store checkouts no registry entry uses and delete commit graphs nothing references')
+    .option('--local-index', 'Delete the index left in <repo>/.gitnexus after this checkout moved into a shared store')
     .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/remove.js

@@ -28,7 +28,7 @@
  *     `clean -f`. (Distinct from `analyze --force`, which re-indexes;
  *     here there is no pipeline, so no conflation.)
  */
-import fs from 'fs/promises';
+import { reclaimAfterSlotRemoval, removeCheckoutStorage, } from '../storage/shared-store-lifecycle.js';
 import { logger } from '../core/logger.js';
 import { cliError } from './cli-message.js';
 import { t } from './i18n/index.js';
@@ -88,8 +88,8 @@ export const removeCommand = async (target, options) => {
     // orphaned — `listRegisteredRepos({ validate: true })` prunes those on
     // next read, so the failure is self-healing.
     try {
-        await fs.rm(storagePath, { recursive: true, force: true });
-        await unregisterRepo(entry.path);
+        await removeCheckoutStorage(storagePath, () => unregisterRepo(entry.path), entry.path);
+        await reclaimAfterSlotRemoval(storagePath);
         console.log(t('remove.removed', { name: entry.name }));
         console.log(`   ${t('common.path')}:    ${entry.path}`);
         console.log(`   ${t('common.storage')}: ${entry.storagePath}`);