gitnexus 1.6.13-rc.35 → 1.6.13-rc.37

package/README.md

@@ -367,7 +367,7 @@ projects:
       - git@gitee.com:owner/repo.git
 ```
 
-`sync_interval_minutes` must be an integer of at least `5`. `local_path` must be an absolute path without traversal; each remote is cloned below it as `host/namespace/repo`, preventing same-basename repositories from colliding. `remote_urls` must use SSH SCP form for github.com, gitlab.com, or gitee.com. `repo_git_timeout` applies to each repo clone/pull and defaults to `10s`; a bare number such as `10` is interpreted as seconds, while `10000ms`, `10s`, and `1m` keep their explicit units. It must not exceed one hour or `sync_interval_minutes`, whichever is smaller — so a bare `600000` is rejected, because it means 600000 seconds rather than milliseconds. `analyze_timeout` applies to each isolated analysis worker and defaults to half of `sync_interval_minutes`, but it is independent of polling and may be longer, up to Node's timer limit (`2147483647ms`). A `5` minute poll with `analyze_timeout: 30m` is valid. A tick that arrives while the previous loop is active never overlaps it: ticks coalesce into one immediate follow-up run, which pulls and analyzes the newest commit. If the parent times out and leaves that worker running, the follow-up is deferred to the next interval so a leftover lock holder is not counted as a hard analyze failure. Timeout and `auto-sync stop` request safe cancellation; a worker already in native work exits after it returns to a JS-visible safe point. While waiting, auto-sync reports `cancelling` or `stopping` and keeps its ownership files so another auto-sync cannot take over. The parent waits up to 5 seconds for the worker to exit; after that it stops waiting, releases its ownership files, and leaves the worker to finish and exit on its own rather than killing it mid-write. `auto-sync stop` uses this same control path on macOS and Windows.
+`sync_interval_minutes` must be an integer of at least `5`. `local_path` must be an absolute path without traversal; each remote is cloned below it as `host/namespace/repo`, preventing same-basename repositories from colliding. `remote_urls` may use SSH SCP form (`git@host:owner/repo.git`) or HTTPS (`https://host/owner/repo.git`) for github.com, gitlab.com, or gitee.com. The published CLI image includes `openssh-client` so SSH remotes can clone; mount keys and `known_hosts` yourself. An invalid `watch_config.yml` skips auto-sync immediately with the validation error. `repo_git_timeout` applies to each repo clone/pull and defaults to `10s`; a bare number such as `10` is interpreted as seconds, while `10000ms`, `10s`, and `1m` keep their explicit units. It must not exceed one hour or `sync_interval_minutes`, whichever is smaller — so a bare `600000` is rejected, because it means 600000 seconds rather than milliseconds. `analyze_timeout` applies to each isolated analysis worker and defaults to half of `sync_interval_minutes`, but it is independent of polling and may be longer, up to Node's timer limit (`2147483647ms`). A `5` minute poll with `analyze_timeout: 30m` is valid. Auto-sync analysis honors the cloned repo's `.gitnexusrc` embeddings settings; the CLI image still needs `GITNEXUS_EMBEDDING_URL` or a bind-mounted embedding stack because npm is stripped. A tick that arrives while the previous loop is active never overlaps it: ticks coalesce into one immediate follow-up run, which pulls and analyzes the newest commit. If the parent times out and leaves that worker running, the follow-up is deferred to the next interval so a leftover lock holder is not counted as a hard analyze failure. Timeout and `auto-sync stop` request safe cancellation; a worker already in native work exits after it returns to a JS-visible safe point. While waiting, auto-sync reports `cancelling` or `stopping` and keeps its ownership files so another auto-sync cannot take over. The parent waits up to 5 seconds for the worker to exit; after that it stops waiting, releases its ownership files, and leaves the worker to finish and exit on its own rather than killing it mid-write. `auto-sync stop` uses this same control path on macOS and Windows.
 
 `pdg` is configured per project. `pdg: true` builds and maintains the full CFG, control-dependence, reaching-definition, and taint layers on both initial and incremental analyses. Auto-sync requests staged atomic incremental publication where the analyzer supports it: the old graph remains available to readers until the replacement succeeds, and analysis errors are recorded while the old graph remains intact. Unsupported paths retain the analyzer's existing in-place behavior. Untouched configs that omit `pdg` preserve the existing index mode and cannot silently strip PDG data. Do not paste `pdg: false` from this example onto an existing watch file unless you intend to drop PDG. An explicit `pdg: false` disables PDG and emits a warning before a successful rebuild removes those layers. `overwrite_local_changes` defaults to `false`; a dirty local clone is skipped with an error log, while `true` allows branch fallback to replace local changes and additionally discards untracked files and directories in the clone after checkout — ignored paths, including GitNexus's own `.gitnexus/` storage, are preserved. `max_concurrency` defaults to `1` and is capped at runtime by `floor(availableMemoryGB / 2)` with a minimum of `1`; the effective value is printed at the start of each loop. Each analysis worker's heap cap is the machine-wide cap divided by the number of repositories analyzed in parallel, so concurrent workers share one memory budget instead of each claiming the whole machine. `analyze_failure_threshold` defaults to `3`, must be at least `2`, and pauses repeated failures only for the same repo branch, commit, and requested PDG mode; a new commit, a PDG mode change, or `gitnexus auto-sync reset` clears the block and allows analysis again. Repositories are registered and added to groups by their full remote identity (`host/namespace/repo`), so repositories with the same basename remain distinct. Use `branches` to try branches in order; legacy `branch` remains supported, but the two fields cannot be set together. If all branches are unavailable or time out, watch logs an error, records the repo status, and skips that repo for the loop. Leave `group_name` empty or omit it to skip group add/sync for that project; otherwise create the group first with `gitnexus group create <name>`. `$GITNEXUS_HOME/watch/project_commit_info.txt` is for inspection only; GitNexus stores machine state separately in `$GITNEXUS_HOME/watch/auto-sync-state.json`.
 

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/auto-sync.js

@@ -106,6 +106,8 @@ function defaultSyncConfig(localPath) {
         '    overwrite_local_changes: false',
         '    remote_urls:',
         '      - git@github.com:owner/repo.git',
+        '      # HTTPS remotes on github.com, gitlab.com, or gitee.com are also allowed',
+        '      # - https://github.com/owner/public-repo.git',
         '',
     ].join('\n');
 }

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.';
@@ -155,7 +170,7 @@ export declare const en: {
     readonly 'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex, Factory Droid';
     readonly 'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors';
     readonly 'help.command.autoSync.description': 'Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml';
-    readonly 'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.';
+    readonly 'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: SSH or HTTPS URLs on github.com, gitlab.com, and gitee.com are allowed. Invalid watch_config.yml skips auto-sync immediately.\nRuns once immediately, then repeats on sync_interval_minutes.';
     readonly 'help.command.watch.description': 'Ambiguous: use `analyze --watch` for local files, or `auto-sync` for scheduled remotes';
     readonly 'help.watch.details': '\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n';
     readonly 'error.watch.ambiguous': '`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n';
@@ -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.',
@@ -157,7 +172,7 @@ export const en = {
     'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex, Factory Droid',
     'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors',
     'help.command.autoSync.description': 'Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml',
-    'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.',
+    'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: SSH or HTTPS URLs on github.com, gitlab.com, and gitee.com are allowed. Invalid watch_config.yml skips auto-sync immediately.\nRuns once immediately, then repeats on sync_interval_minutes.',
     'help.command.watch.description': 'Ambiguous: use `analyze --watch` for local files, or `auto-sync` for scheduled remotes',
     'help.watch.details': '\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n',
     'error.watch.ambiguous': '`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n',
@@ -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.';
@@ -156,7 +171,7 @@ export declare const cliResources: {
         readonly 'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex, Factory Droid';
         readonly 'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors';
         readonly 'help.command.autoSync.description': 'Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml';
-        readonly 'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.';
+        readonly 'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: SSH or HTTPS URLs on github.com, gitlab.com, and gitee.com are allowed. Invalid watch_config.yml skips auto-sync immediately.\nRuns once immediately, then repeats on sync_interval_minutes.';
         readonly 'help.command.watch.description': 'Ambiguous: use `analyze --watch` for local files, or `auto-sync` for scheduled remotes';
         readonly 'help.watch.details': '\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n';
         readonly 'error.watch.ambiguous': '`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n';
@@ -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;