cgraphx 2.0.2 → 2.0.6

package/dist/core/code/engine/storage/repo-manager.js

@@ -0,0 +1,1061 @@
+"use strict";
+/**
+ * Repository Manager
+ *
+ * Manages GitNexus index storage:
+ * - Per-repo metadata file (cgraph.json) under .cgraphx/code/, dual-written to a
+ *   legacy meta.json mirror for backward compatibility (see MIGRATION.md)
+ * - .cgraphx/code/ directory for local metadata and caches (parse-cache, parsedfile-store)
+ *
+ * cgraph.json is simply a filename distinct from the generic meta.json — it
+ * has no bearing on git worktree behavior. .cgraphx/code/ remains fully git-ignored
+ * in every case; each worktree already has its own independent .cgraphx/code/ by
+ * construction (getStoragePath is per-checkout), regardless of which filename
+ * the metadata inside it uses.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findSiblingClones = exports.saveCLIConfig = exports.loadCLIConfig = exports.getGlobalConfigPath = exports.listRegisteredRepos = exports.resolveRegistryEntry = exports.assertSafeStoragePath = exports.UnsafeStoragePathError = exports.assertAnalysisFinalized = exports.isRepoRegistered = exports.AnalysisNotFinalizedError = exports.RegistryAmbiguousTargetError = exports.RegistryNotFoundError = exports.adoptFlatBranchLabel = exports.removeBranchIndex = exports.unregisterRepo = exports.registerRepo = exports.RegistryNameCollisionError = exports.readRegistry = exports.resolveProjectRoot = exports.getGlobalDir = exports.ensureGitNexusIgnored = exports.findRepo = exports.reconcileMetadataFiles = exports.loadRepo = exports.hasIndex = exports.saveMeta = exports.loadMeta = exports.cleanupOldKuzuFiles = exports.hasKuzuIndex = exports.getStoragePaths = exports.getStoragePath = exports.INDEX_METADATA_FILE = exports.cloneDirBelongsToEntry = exports.registryPathEquals = exports.canonicalizePath = exports.resolveBranchPlacement = exports.branchSlug = void 0;
+exports.isReadOnlyFilesystemError = isReadOnlyFilesystemError;
+exports.isMissingFilesystemError = isMissingFilesystemError;
+const promises_1 = __importDefault(require("fs/promises"));
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const crypto_1 = require("crypto");
+const git_js_1 = require("./git.js");
+const utils_js_1 = require("../lib/utils.js");
+const fs_atomic_js_1 = require("./fs-atomic.js");
+const logger_js_1 = require("../core/logger.js");
+const branch_index_js_1 = require("./branch-index.js");
+Object.defineProperty(exports, "branchSlug", { enumerable: true, get: function () { return branch_index_js_1.branchSlug; } });
+Object.defineProperty(exports, "resolveBranchPlacement", { enumerable: true, get: function () { return branch_index_js_1.resolveBranchPlacement; } });
+/**
+ * Normalise a repo path for registry comparison across platforms
+ * (#664 review feedback from @evander-wang).
+ *
+ * Why this exists: `path.resolve` alone is NOT enough for
+ * cross-platform registry stability.
+ *   - **macOS**: tmpdirs and `/var` are symlinks to `/private/var`.
+ *     A child process that stored `/private/var/folders/.../repo` in
+ *     the registry cannot later be matched by an outer caller that
+ *     supplies the symlink form `/var/folders/.../repo`. `path.resolve`
+ *     does not follow symlinks; `realpathSync.native` does.
+ *   - **Windows**: GitHub runners surface tmpdirs in 8.3 short-name
+ *     form (`RUNNERA~1\...`), but `process.cwd()` often returns the
+ *     long form (`runneradmin\...`). `realpathSync.native` normalises
+ *     both sides to the long-name canonical path.
+ *   - **Windows, extended-length paths** (#2667): a caller can supply a
+ *     `\\?\`-prefixed path — the usual MAX_PATH workaround — and
+ *     `path.resolve` preserves the prefix, so the string compare below
+ *     never matches the un-prefixed entry the registry stores. The
+ *     realpath branch already dropped it (libuv strips the prefix inside
+ *     `fs__realpath`), but the fallback branch did not, which is exactly
+ *     the branch a missing path takes. `stripWindowsLongPathPrefix` is
+ *     applied to both so the two branches agree.
+ *
+ * This normalisation is safe here precisely because the result is only ever
+ * compared, never opened: Node does NOT re-add `\\?\` for over-MAX_PATH
+ * paths, so an fs-facing path must keep whatever form the caller gave it.
+ * See the `registerRepo` comment on applying canonicalisation at COMPARE
+ * points only.
+ *
+ * Fallback behaviour: if the path does not exist on disk (e.g. a user
+ * passed `gitnexus remove some-alias` and the alias misses every
+ * registry entry, or the caller is resolving a path that was deleted
+ * after registration), we return `path.resolve(p)` rather than
+ * throwing. This preserves the idempotent-on-missing semantics of
+ * `resolveRegistryEntry` / `remove`.
+ *
+ * Backwards compatibility: this function is applied to BOTH the
+ * caller-supplied input AND each stored `entry.path` at compare time
+ * inside `resolveRegistryEntry`, so registries written by older
+ * versions still match correctly. Entries are NOT canonicalised at
+ * write time — `registerRepo` stores `path.resolve(repoPath)` — which
+ * is what makes the compare-only rule above hold.
+ */
+const canonicalizePath = (p) => {
+    const resolved = path_1.default.resolve(p);
+    try {
+        return (0, utils_js_1.stripWindowsLongPathPrefix)(fs_1.realpathSync.native(resolved));
+    }
+    catch {
+        return (0, utils_js_1.stripWindowsLongPathPrefix)(resolved);
+    }
+};
+exports.canonicalizePath = canonicalizePath;
+/**
+ * Compare two already-canonicalised registry paths. Case-insensitive on Windows
+ * (its filesystem is), case-sensitive elsewhere. Both arguments must already be
+ * run through {@link canonicalizePath}; this is the single comparison the registry
+ * lookups/dedup/finalize checks all share so they answer identically.
+ */
+const registryPathEquals = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+exports.registryPathEquals = registryPathEquals;
+/**
+ * Does the clone dir derived from an entry's *name* actually belong to that
+ * entry? Registry names are not unique across storage locations: a cloned
+ * repo under `~/.cgraphx/code/repos/<name>` and a local repo registered under the
+ * same name share a `getCloneDir(entry.name)` result. The server's delete
+ * handler must therefore never remove the clone dir based on the name alone —
+ * only when the entry's own `path` resolves to that dir (mirroring its step-2b
+ * rule that cleanup is driven off `entry.path`, so a same-named sibling's
+ * clone is never removed). Both sides are canonicalised so symlinked or
+ * differently-spelled forms of the same dir still match.
+ */
+const cloneDirBelongsToEntry = (cloneDir, entryPath) => (0, exports.registryPathEquals)((0, exports.canonicalizePath)(cloneDir), (0, exports.canonicalizePath)(entryPath));
+exports.cloneDirBelongsToEntry = cloneDirBelongsToEntry;
+// Index directory: `<projectRoot>/.cgraphx/code` (cgraphx code 子系统,spec §4.4).
+// Kept as two segments so path joins and the string-based git-exclude checks
+// below share one source of truth.
+const CGRAPHX_DIR = '.cgraphx';
+const CGRAPHX_CODE_DIR_PARTS = [CGRAPHX_DIR, 'code'];
+// git exclude entry covers the whole `.cgraphx/` tree (index + any sibling
+// cgraphx state), not just the `code/` subdirectory.
+const CGRAPHX_EXCLUDE_ENTRY = `${CGRAPHX_DIR}/`;
+exports.INDEX_METADATA_FILE = 'cgraph.json';
+// Dual-written mirror of INDEX_METADATA_FILE, kept for backward compatibility
+// with consumers that only know the pre-rename filename (see MIGRATION.md).
+const LEGACY_METADATA_FILE = 'meta.json';
+// ─── Local Storage Helpers ─────────────────────────────────────────────
+/**
+ * Get the .cgraphx/code storage path for a repository.
+ * Used for local metadata and caches that are not committed.
+ */
+const getStoragePath = (repoPath) => {
+    return path_1.default.join(path_1.default.resolve(repoPath), ...CGRAPHX_CODE_DIR_PARTS);
+};
+exports.getStoragePath = getStoragePath;
+/**
+ * Get paths to key storage files.
+ *
+ * `storagePath` is ALWAYS the flat `<repo>/.cgraphx/code` — content-addressed
+ * caches (`parse-cache/`, `parsedfile-store/`) live there and are shared
+ * across branches (#2106 KTD7). When `branch` is provided, both `lbugPath`
+ * and `metaPath` are scoped under `branches/<slug>/`. For the flat call
+ * (no `branch`), `storagePath` and `lbugPath` remain byte-identical to the
+ * pre-multi-branch behavior (#2106); `metaPath`'s FILENAME changed from
+ * `meta.json` to `cgraph.json` (PR #2363) — `saveMeta` keeps a `meta.json`
+ * mirror in sync for consumers that still read the legacy name.
+ *
+ * Each branch slot has its own metadata file:
+ * - Primary/flat: <repo>/.cgraphx/code/cgraph.json
+ * - Feature branches: <repo>/.cgraphx/code/branches/<slug>/cgraph.json
+ *
+ * Callers should use `loadMeta(metaDir)` and `saveMeta(metaDir, meta)` where
+ * metaDir is the directory containing the metadata file — both handle the
+ * legacy mirror automatically.
+ */
+const getStoragePaths = (repoPath, branch) => {
+    const storagePath = (0, exports.getStoragePath)(repoPath);
+    const baseDir = branch ? path_1.default.join(storagePath, branch_index_js_1.BRANCHES_DIR, (0, branch_index_js_1.branchSlug)(branch)) : storagePath;
+    return {
+        storagePath,
+        lbugPath: path_1.default.join(baseDir, 'lbug'),
+        metaPath: path_1.default.join(baseDir, exports.INDEX_METADATA_FILE), // Branch-specific metadata file
+    };
+};
+exports.getStoragePaths = getStoragePaths;
+/**
+ * Check whether a KuzuDB index exists in the given storage path.
+ * Non-destructive — safe to call from status commands.
+ */
+const hasKuzuIndex = async (storagePath) => {
+    try {
+        await promises_1.default.stat(path_1.default.join(storagePath, 'kuzu'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.hasKuzuIndex = hasKuzuIndex;
+/**
+ * Clean up stale KuzuDB files after migration to LadybugDB.
+ *
+ * Returns:
+ *   found        — true if .cgraphx/code/kuzu existed and was deleted
+ *   needsReindex — true if kuzu existed but lbug does not (re-analyze required)
+ *
+ * Callers own the user-facing messaging; this function only deletes files.
+ */
+const cleanupOldKuzuFiles = async (storagePath) => {
+    const oldPath = path_1.default.join(storagePath, 'kuzu');
+    const newPath = path_1.default.join(storagePath, 'lbug');
+    try {
+        await promises_1.default.stat(oldPath);
+        // Old kuzu file/dir exists — determine if lbug is already present
+        let needsReindex = false;
+        try {
+            await promises_1.default.stat(newPath);
+        }
+        catch {
+            needsReindex = true;
+        }
+        // Delete kuzu database file and its sidecars (.wal, .lock)
+        for (const suffix of ['', '.wal', '.lock']) {
+            try {
+                await promises_1.default.unlink(oldPath + suffix);
+            }
+            catch { }
+        }
+        // Also handle the case where kuzu was stored as a directory
+        try {
+            await promises_1.default.rm(oldPath, { recursive: true, force: true });
+        }
+        catch { }
+        return { found: true, needsReindex };
+    }
+    catch {
+        // Old path doesn't exist — nothing to do
+        return { found: false, needsReindex: false };
+    }
+};
+exports.cleanupOldKuzuFiles = cleanupOldKuzuFiles;
+/**
+ * Load metadata from the legacy `meta.json` mirror in the given directory.
+ * Returns null when the file is absent, unreadable, or unparseable — a
+ * corrupt legacy file is treated the same as a missing one (safe rebuild).
+ */
+const loadMetaLegacy = async (metaDir) => tryReadMetaFile(metaDir, LEGACY_METADATA_FILE);
+/**
+ * Load metadata from a directory containing the metadata file (cgraph.json).
+ * For primary/flat: metaDir = <repo>/.cgraphx/code
+ * For feature branches: metaDir = <repo>/.cgraphx/code/branches/<slug>
+ *
+ * Falls back to the legacy `meta.json` mirror ONLY when `cgraph.json` is
+ * provably absent (ENOENT/ENOTDIR). Any other failure — a parse error, EACCES,
+ * EIO — returns null instead of silently resurrecting possibly-stale legacy
+ * content: a corrupt primary file must trigger the same safe full-rebuild path
+ * a missing index would (the fail-safe `saveMeta`'s docstring relies on), not
+ * an incremental run over a stale legacy baseline.
+ */
+const loadMeta = async (metaDir) => {
+    let raw;
+    try {
+        raw = await promises_1.default.readFile(path_1.default.join(metaDir, exports.INDEX_METADATA_FILE), 'utf-8');
+    }
+    catch (err) {
+        // Provably absent → the legacy mirror is the source of truth (pre-rename
+        // repo, or a mirror-only state). Anything else → fail safe with null.
+        return isMissingFilesystemError(err) ? loadMetaLegacy(metaDir) : null;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // Corrupt primary file — do NOT mask it with legacy content.
+        return null;
+    }
+};
+exports.loadMeta = loadMeta;
+/**
+ * Atomically write `meta` to `<dir>/<filename>`. Tmp name includes a random
+ * suffix (not a fixed `.tmp`) so two concurrent writers targeting the same
+ * directory never collide on the same tmp path — mirrors the pattern in
+ * core/group/bridge-db.ts's `writeBridgeMeta` (`'wx'` + `0o600` closes the
+ * symlink-race/permissions holes CodeQL flags as `js/insecure-temporary-file`;
+ * `retryRename` absorbs a transient EBUSY/EPERM/EACCES on the rename itself).
+ */
+async function writeMetaFile(dir, filename, meta) {
+    const targetPath = path_1.default.join(dir, filename);
+    const tmpPath = `${targetPath}.tmp.${(0, crypto_1.randomBytes)(8).toString('hex')}`;
+    const handle = await promises_1.default.open(tmpPath, 'wx', 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(meta, null, 2), 'utf-8');
+    }
+    finally {
+        await handle.close();
+    }
+    await (0, fs_atomic_js_1.retryRename)(tmpPath, targetPath);
+}
+/**
+ * Save metadata to the metadata file (cgraph.json) in the given directory,
+ * dual-writing the legacy `meta.json` mirror for backward compatibility.
+ *
+ * Atomic via tmp-file + rename (matches `saveParseCache`'s pattern). The
+ * `incrementalInProgress` dirty flag travels through this file — a crash
+ * mid-write would leave a corrupt `cgraph.json` that the next run's
+ * `loadMeta` would silently treat as "no prior index", losing the dirty
+ * flag and skipping the recovery full-rebuild. Write-and-rename rules
+ * that out: the rename is atomic on POSIX and on Windows (`fs.rename`
+ * on `node:fs/promises` uses `MoveFileEx(REPLACE_EXISTING)`), so either
+ * the old or the new file is observed at every moment.
+ *
+ * `cgraph.json` is the primary write and must succeed. `meta.json` is a
+ * best-effort mirror kept for consumers that only know the legacy filename
+ * (see MIGRATION.md) — its write failure is logged, not thrown, so a
+ * mirror-write hiccup never fails the caller's analyze run.
+ */
+const saveMeta = async (metaDir, meta) => {
+    await promises_1.default.mkdir(metaDir, { recursive: true });
+    await writeMetaFile(metaDir, exports.INDEX_METADATA_FILE, meta);
+    try {
+        await writeMetaFile(metaDir, LEGACY_METADATA_FILE, meta);
+    }
+    catch (err) {
+        logger_js_1.logger.warn({ err, metaDir }, 'Failed to write legacy meta.json mirror (non-critical)');
+    }
+};
+exports.saveMeta = saveMeta;
+/**
+ * Check if a path has a GitNexus index (metadata file or legacy location)
+ */
+const hasIndex = async (repoPath) => {
+    const paths = (0, exports.getStoragePaths)(repoPath);
+    // Check new metadata file first
+    try {
+        await promises_1.default.access(paths.metaPath);
+        return true;
+    }
+    catch {
+        // Fall back to legacy location
+        try {
+            await promises_1.default.access(path_1.default.join(paths.storagePath, LEGACY_METADATA_FILE));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+};
+exports.hasIndex = hasIndex;
+/**
+ * Load an indexed repo from a path (checks metadata file first, then legacy)
+ */
+const loadRepo = async (repoPath) => {
+    const paths = (0, exports.getStoragePaths)(repoPath);
+    const meta = await (0, exports.loadMeta)(paths.storagePath);
+    if (!meta)
+        return null;
+    return {
+        repoPath: path_1.default.resolve(repoPath),
+        ...paths,
+        meta,
+    };
+};
+exports.loadRepo = loadRepo;
+/**
+ * Best-effort read of one specific metadata filename — no fallback, null on
+ * any failure (absent, unreadable, or unparseable).
+ */
+const tryReadMetaFile = async (dir, filename) => {
+    try {
+        const raw = await promises_1.default.readFile(path_1.default.join(dir, filename), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/** `indexedAt` as epoch millis; 0 when absent/unparseable (i.e. oldest). */
+const metaTimestamp = (meta) => {
+    const t = Date.parse(meta.indexedAt ?? '');
+    return Number.isFinite(t) ? t : 0;
+};
+/**
+ * Reconcile `cgraph.json` and the legacy `meta.json` mirror in one
+ * directory: whichever parses and is fresher (by `indexedAt`) wins and is
+ * re-written to BOTH files via `saveMeta`. Never deletes anything.
+ * Returns true when a write occurred.
+ */
+const reconcileMetaDir = async (dir) => {
+    const primary = await tryReadMetaFile(dir, exports.INDEX_METADATA_FILE);
+    const legacy = await tryReadMetaFile(dir, LEGACY_METADATA_FILE);
+    if (!primary && !legacy) {
+        // Fresh directory (neither file) is a silent no-op; a file that exists
+        // but doesn't parse deserves a warning — loadMeta will treat it as "no
+        // prior index" and the next successful saveMeta self-heals it.
+        for (const filename of [exports.INDEX_METADATA_FILE, LEGACY_METADATA_FILE]) {
+            try {
+                await promises_1.default.access(path_1.default.join(dir, filename));
+                logger_js_1.logger.warn({ dir, filename }, 'Metadata file exists but is unreadable/corrupt; leaving as-is (next successful analyze rewrites it)');
+            }
+            catch {
+                // absent — expected for a fresh directory
+            }
+        }
+        return false;
+    }
+    if (primary && legacy) {
+        if (JSON.stringify(primary) === JSON.stringify(legacy))
+            return false; // converged
+        // Both parse but differ — the fresher one wins (an older binary may have
+        // re-analyzed and written only meta.json AFTER cgraph.json was created;
+        // blind-preferring the primary would permanently shadow that fresher
+        // state, silently certifying a stale index as up to date).
+        const winner = metaTimestamp(legacy) > metaTimestamp(primary) ? legacy : primary;
+        await (0, exports.saveMeta)(dir, winner);
+        logger_js_1.logger.info({ dir, winner: winner === legacy ? LEGACY_METADATA_FILE : exports.INDEX_METADATA_FILE }, 'Reconciled diverged metadata files (fresher indexedAt wins, written to both)');
+        return true;
+    }
+    // Exactly one parses — establish/repair the other so both stay in sync.
+    const survivor = (primary ?? legacy);
+    await (0, exports.saveMeta)(dir, survivor);
+    return true;
+};
+/**
+ * Reconcile the metadata files for a repo's flat slot and every
+ * `branches/<slug>/` slot. Runs once per `analyze` (see run-analyze.ts).
+ *
+ * This is a best-effort compatibility sync, NOT a one-way migration: the
+ * legacy `meta.json` mirror is kept in sync indefinitely (removal happens at
+ * a future major version — see MIGRATION.md), so older binaries, still-running
+ * MCP servers, and the shipped editor hooks keep working, and a rollback to a
+ * pre-rename version sees current metadata instead of "no prior index".
+ * Returns true when any file was written.
+ */
+const reconcileMetadataFiles = async (repoPath) => {
+    const storagePath = (0, exports.getStoragePath)(repoPath);
+    let changed = await reconcileMetaDir(storagePath);
+    const branchesDir = path_1.default.join(storagePath, branch_index_js_1.BRANCHES_DIR);
+    let branchDirs;
+    try {
+        branchDirs = await promises_1.default.readdir(branchesDir);
+    }
+    catch {
+        // branchesDir may not exist (not a multi-branch repo) — expected, silent.
+        return changed;
+    }
+    for (const branchDir of branchDirs) {
+        const branchPath = path_1.default.join(branchesDir, branchDir);
+        // Per-branch isolation: one bad branch dir (dangling symlink, EACCES)
+        // must not silently abort reconciliation for every branch after it —
+        // readdir order is stable, so an unguarded throw here would permanently
+        // starve the same trailing branches on every run.
+        try {
+            const stat = await promises_1.default.stat(branchPath);
+            if (!stat.isDirectory())
+                continue;
+            if (await reconcileMetaDir(branchPath))
+                changed = true;
+        }
+        catch (err) {
+            logger_js_1.logger.warn({ branchDir, err }, 'Skipping branch directory during metadata reconciliation (non-critical)');
+        }
+    }
+    return changed;
+};
+exports.reconcileMetadataFiles = reconcileMetadataFiles;
+/**
+ * Find the .cgraphx/code index by walking up from a starting path
+ */
+const findRepo = async (startPath) => {
+    let current = path_1.default.resolve(startPath);
+    const root = path_1.default.parse(current).root;
+    while (current !== root) {
+        const repo = await (0, exports.loadRepo)(current);
+        if (repo)
+            return repo;
+        current = path_1.default.dirname(current);
+    }
+    return null;
+};
+exports.findRepo = findRepo;
+function isReadOnlyFilesystemError(err) {
+    const code = err?.code;
+    return code === 'EROFS' || code === 'EACCES' || code === 'EPERM';
+}
+/**
+ * True for errors that prove a path is absent (ENOENT/ENOTDIR) — as opposed
+ * to transient/permission failures (EIO/EACCES/EBUSY…) where the file may
+ * well still exist. Exported for consumers that need the same "provably
+ * missing vs not provably absent" distinction (e.g. collectBranchCacheKeys).
+ */
+function isMissingFilesystemError(err) {
+    const code = err?.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+/**
+ * Keep .cgraphx/code/ ignored. It contains local index state and caches.
+ */
+const ensureGitNexusIgnored = async (repoPath) => {
+    const gitignorePath = path_1.default.join((0, exports.getStoragePath)(repoPath), '.gitignore');
+    const desired = '*\n';
+    // Idempotent fast path: skip the write entirely when the file already has
+    // the expected content. Lets this run cleanly on read-only mounts (e.g.
+    // the documented Docker workflow with WORKSPACE_DIR bound :ro) when an
+    // earlier `analyze` already created the file. See issue #1549.
+    try {
+        if ((await promises_1.default.readFile(gitignorePath, 'utf-8')) === desired) {
+            await ensureGitInfoExclude(repoPath);
+            return;
+        }
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            throw err;
+    }
+    try {
+        await promises_1.default.mkdir(path_1.default.dirname(gitignorePath), { recursive: true });
+        await promises_1.default.writeFile(gitignorePath, desired, 'utf-8');
+    }
+    catch (err) {
+        if (isReadOnlyFilesystemError(err)) {
+            logger_js_1.logger.warn({ path: gitignorePath, code: err.code }, 'GitNexus storage filesystem is not writable; skipping .cgraphx/code/.gitignore. Cache files may appear as untracked in this repo locally.');
+        }
+        else {
+            throw err;
+        }
+    }
+    await ensureGitInfoExclude(repoPath);
+};
+exports.ensureGitNexusIgnored = ensureGitNexusIgnored;
+const ensureGitInfoExclude = async (repoPath) => {
+    const gitDirPath = path_1.default.join(path_1.default.resolve(repoPath), '.git');
+    const excludePath = path_1.default.join(gitDirPath, 'info', 'exclude');
+    try {
+        const gitDir = await promises_1.default.stat(gitDirPath);
+        if (!gitDir.isDirectory())
+            return;
+    }
+    catch {
+        return;
+    }
+    let content = '';
+    try {
+        content = await promises_1.default.readFile(excludePath, 'utf-8');
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            throw err;
+    }
+    const excludes = content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith('#'));
+    if (excludes.includes(CGRAPHX_DIR) || excludes.includes(CGRAPHX_EXCLUDE_ENTRY))
+        return;
+    const separator = content.length === 0 || content.endsWith('\n') ? '' : '\n';
+    try {
+        await promises_1.default.mkdir(path_1.default.dirname(excludePath), { recursive: true });
+        await promises_1.default.writeFile(excludePath, `${content}${separator}${CGRAPHX_EXCLUDE_ENTRY}\n`, 'utf-8');
+    }
+    catch (err) {
+        if (isReadOnlyFilesystemError(err)) {
+            logger_js_1.logger.warn({ path: excludePath, code: err.code }, 'GitNexus storage filesystem is not writable; skipping .git/info/exclude update. .cgraphx/ cache directory may appear as untracked in `git status` locally.');
+        }
+        else {
+            throw err;
+        }
+    }
+};
+// ─── Global Directory (~/.cgraphx/code/) ───────────────────────────────
+/**
+ * Get the path to the global GitNexus directory (used for CLI config only).
+ */
+const getGlobalDir = () => {
+    return process.env.CGRAPH_HOME || path_1.default.join(os_1.default.homedir(), '.cgraphx', 'code');
+};
+exports.getGlobalDir = getGlobalDir;
+// ─── Project-root discovery (cwd-based; global registry removed) ────────
+//
+// The global registry was removed per spec §8 ("无全局状态"): index data lives
+// ONLY in `<projectRoot>/.cgraphx/code/`, and the CLI operates on "当前目录或显式
+// 路径的项目根索引". These functions replace the old registry I/O with cwd-
+// based discovery so every former registry consumer (LocalBackend.refreshRepos,
+// git-staleness.checkCwdMatch, findSiblingClones) resolves the same single
+// project-root index without any `~/.cgraphx/code/registry.json`.
+/**
+ * Best-effort `process.cwd()` that never throws — some sandboxed runtimes
+ * (deleted cwd, container teardown) make `process.cwd()` throw EBADF/ENOENT.
+ * Falling back to the current module directory keeps discovery alive instead
+ * of crashing the CLI entrypoint.
+ */
+const safeCwd = () => {
+    try {
+        return process.cwd();
+    }
+    catch {
+        return __dirname;
+    }
+};
+/**
+ * Resolve the project root whose `.cgraphx/code/` index the CLI should operate on
+ * (spec §8). Discovery precedence:
+ *
+ *   1. `opts.explicitPath` — a caller-provided `--path` project root.
+ *   2. `CGRAPH_REPO` env var — an ambient override for scripted/CI contexts.
+ *   3. upward walk from `opts.startCwd` (default `process.cwd()`) for the
+ *      nearest ancestor (or self) directory containing a readable `.cgraphx/code/`
+ *      index metadata file.
+ *
+ * Returns the discovered {@link IndexedRepo} (meta + paths), or `null` when no
+ * index is found — callers surface a "run `cgraph analyze`" error in that case.
+ *
+ * Reuses {@link findRepo} / {@link loadRepo} so the walk, the cgraph.json↔
+ * meta.json fallback, and the storage-path derivation stay identical to the
+ * `status` / `analyze` commands.
+ */
+const resolveProjectRoot = async (opts) => {
+    const explicit = opts?.explicitPath ?? process.env.CGRAPH_REPO;
+    const start = opts?.startCwd ?? (explicit ? path_1.default.resolve(explicit) : safeCwd());
+    return (0, exports.findRepo)(start);
+};
+exports.resolveProjectRoot = resolveProjectRoot;
+/**
+ * Scan the `branches/<slug>/` sub-indexes of a project root and return their
+ * summaries (#2106). Non-primary branch indexes live under
+ * `<storagePath>/branches/<slug>/cgraph.json`; each readable meta becomes one
+ * {@link BranchSummary}. Absent dir, unreadable entries, or a fresh repo yield
+ * `[]`. Used by discovery so `--branch` scoping in LocalBackend still resolves
+ * pinned sub-indexes without a global registry.
+ */
+const readBranchSummaries = async (repoPath) => {
+    const { storagePath } = (0, exports.getStoragePaths)(repoPath);
+    const branchesDir = path_1.default.join(storagePath, branch_index_js_1.BRANCHES_DIR);
+    let entries;
+    try {
+        entries = await promises_1.default.readdir(branchesDir);
+    }
+    catch {
+        return []; // no branches dir → single-branch/legacy repo, expected.
+    }
+    const summaries = [];
+    for (const slug of entries) {
+        const slugDir = path_1.default.join(branchesDir, slug);
+        try {
+            const stat = await promises_1.default.stat(slugDir);
+            if (!stat.isDirectory())
+                continue;
+        }
+        catch {
+            continue; // dangling symlink / EACCES — skip one branch, not the whole scan.
+        }
+        const meta = await (0, exports.loadMeta)(slugDir);
+        if (meta?.branch) {
+            summaries.push({
+                branch: meta.branch,
+                indexedAt: meta.indexedAt ?? '',
+                lastCommit: meta.lastCommit ?? '',
+                stats: meta.stats,
+            });
+        }
+    }
+    return summaries;
+};
+/**
+ * Convert a discovered {@link IndexedRepo} into the {@link RegistryEntry} shape
+ * that former registry consumers (LocalBackend, git-staleness) expect. The
+ * `name` is derived the same way {@link registerRepo} derives it (explicit
+ * alias → inferred git remote name → basename), so the displayed label matches
+ * what `cgraph analyze` would report.
+ */
+const indexedRepoToRegistryEntry = async (repo) => ({
+    name: (0, git_js_1.getInferredRepoName)(repo.repoPath) ?? path_1.default.basename(repo.repoPath),
+    path: repo.repoPath,
+    storagePath: repo.storagePath,
+    indexedAt: repo.meta.indexedAt ?? '',
+    lastCommit: repo.meta.lastCommit ?? '',
+    remoteUrl: repo.meta.remoteUrl,
+    stats: repo.meta.stats,
+    branch: repo.meta.branch,
+    branches: await readBranchSummaries(repo.repoPath),
+});
+/**
+ * Read the set of indexed repos discoverable from the given context. With the
+ * global registry removed (spec §8), this is cwd-based discovery that returns
+ * at most ONE entry — the project root whose `.cgraphx/code/` index is nearest the
+ * starting directory (or the explicit `--path` / `CGRAPH_REPO` override).
+ *
+ * Formerly read `~/.cgraphx/code/registry.json`; now delegates to
+ * {@link resolveProjectRoot}. Accepts optional discovery context so callers
+ * like `checkCwdMatch(cwd)` can pin the start directory instead of implicitly
+ * using `process.cwd()`.
+ */
+const readRegistry = async (opts) => {
+    const repo = await (0, exports.resolveProjectRoot)(opts);
+    return repo ? [await indexedRepoToRegistryEntry(repo)] : [];
+};
+exports.readRegistry = readRegistry;
+/**
+ * Thrown by {@link registerRepo} when a requested name is already in
+ * use by a DIFFERENT path. The CLI layer surfaces this as an actionable
+ * error instead of relying on `.message` string-matching.
+ *
+ * The colliding alias is exposed as `err.registryName` (not `err.name`).
+ * `err.name` keeps its inherited `Error.prototype.name` semantics (the
+ * class name) so downstream code can do the usual `err.name ===
+ * 'RegistryNameCollisionError'` checks; use the `kind` discriminant or
+ * `instanceof RegistryNameCollisionError` for type-safe narrowing.
+ */
+class RegistryNameCollisionError extends Error {
+    registryName;
+    existingPath;
+    requestedPath;
+    kind = 'RegistryNameCollisionError';
+    constructor(registryName, existingPath, requestedPath) {
+        super(`Registry name "${registryName}" is already used by "${existingPath}".\n` +
+            `Pass --name <alias> to register "${requestedPath}" under a different name, ` +
+            `or --allow-duplicate-name to allow both paths under the same name (leaves -r <name> ambiguous for these two).`);
+        this.registryName = registryName;
+        this.existingPath = existingPath;
+        this.requestedPath = requestedPath;
+        this.name = 'RegistryNameCollisionError';
+    }
+}
+exports.RegistryNameCollisionError = RegistryNameCollisionError;
+/**
+ * Register a repo. With the global registry removed (spec §8), this is a
+ * minimal stub: it derives and returns a project name from the repo path
+ * or the provided `opts.name`, performing no disk I/O. Called after
+ * `cgraph analyze` completes.
+ *
+ * Name resolution precedence:
+ *   1. explicit `opts.name` (from `analyze --name <alias>`)
+ *   2. `git config --get remote.origin.url` repo name
+ *   3. `path.basename(repoPath)` (the original default)
+ */
+const registerRepo = async (repoPath, _meta, opts) => {
+    if (opts?.name)
+        return opts.name;
+    const resolved = path_1.default.resolve(repoPath);
+    return (0, git_js_1.getInferredRepoName)(resolved) ?? path_1.default.basename((0, git_js_1.resolveRepoIdentityRoot)(resolved));
+};
+exports.registerRepo = registerRepo;
+/**
+ * No-op unregister — the global registry no longer exists.
+ */
+const unregisterRepo = async (_repoPath) => { };
+exports.unregisterRepo = unregisterRepo;
+/**
+ * No-op branch-index removal — the global registry no longer exists.
+ * Returns `false` (no matching entry found) unconditionally.
+ */
+const removeBranchIndex = async (_repoPath, _branch) => false;
+exports.removeBranchIndex = removeBranchIndex;
+/**
+ * Remove a shadowed `branches/<slug>/` sub-index directory when the flat slot
+ * adopts this run's branch label (#2354).
+ *
+ * The flat index follows the checked-out working tree, so when a plain analyze
+ * lands on a branch that also has a pinned `branches/<slug>/` sub-index, that
+ * sub-index becomes permanently shadowed — explicit `--branch` runs re-resolve
+ * to the flat slot and query-side branch scoping serves the flat handle first.
+ * This deletes the shadowed directory to avoid stranding un-cleanable disk
+ * bloat. The registry-summary bookkeeping half was removed along with the
+ * global registry (spec §8).
+ */
+const adoptFlatBranchLabel = async (repoPath, branch) => {
+    const resolved = path_1.default.resolve(repoPath);
+    const { storagePath } = (0, exports.getStoragePaths)(resolved);
+    // Remove a shadowed sub-index directory, mirroring `clean --branch`'s
+    // containment guard: the target MUST live under .cgraphx/code/branches/.
+    const branchDir = path_1.default.join(storagePath, branch_index_js_1.BRANCHES_DIR, (0, branch_index_js_1.branchSlug)(branch));
+    const branchesRoot = path_1.default.join(storagePath, branch_index_js_1.BRANCHES_DIR) + path_1.default.sep;
+    if (!branchDir.startsWith(branchesRoot))
+        return;
+    let rmError;
+    await promises_1.default.rm(branchDir, { recursive: true, force: true }).catch((err) => {
+        rmError = err;
+    });
+    let dirGone = false;
+    if (!rmError) {
+        dirGone = true;
+    }
+    else {
+        // On failure, probe the disk and treat only provably-absent errno as gone
+        // — EACCES/EIO are "not provably absent" (same polarity as the old
+        // listRegisteredRepos validate path).
+        const probeCode = await promises_1.default.access(branchDir).then(() => null, (e) => e?.code ?? 'UNKNOWN');
+        dirGone = probeCode === 'ENOENT' || probeCode === 'ENOTDIR';
+    }
+    if (dirGone) {
+        // Non-recursive by design: only removes the parent when no other pinned
+        // sub-index remains, so an empty branches/ dir doesn't read as "pinned".
+        await promises_1.default.rmdir(path_1.default.join(storagePath, branch_index_js_1.BRANCHES_DIR)).catch(() => { });
+    }
+    else {
+        logger_js_1.logger.warn({ path: branchDir, code: rmError?.code }, 'Could not remove the shadowed branch sub-index.');
+    }
+};
+exports.adoptFlatBranchLabel = adoptFlatBranchLabel;
+/**
+ * Thrown by {@link resolveRegistryEntry} when no registered repo matches
+ * the caller's target string (by alias, basename, remote-inferred name,
+ * or resolved path). CLI callers that want idempotent "remove" semantics
+ * should catch this and exit 0 with a warning; non-idempotent callers
+ * (e.g. MCP tools) can surface the error directly.
+ */
+class RegistryNotFoundError extends Error {
+    target;
+    availableNames;
+    kind = 'RegistryNotFoundError';
+    constructor(target, availableNames) {
+        const hint = availableNames.length > 0
+            ? ` Available: ${availableNames.join(', ')}.`
+            : ' No repositories are currently registered.';
+        super(`No registered repo matches "${target}".${hint}`);
+        this.target = target;
+        this.availableNames = availableNames;
+        this.name = 'RegistryNotFoundError';
+    }
+}
+exports.RegistryNotFoundError = RegistryNotFoundError;
+/**
+ * Thrown by {@link resolveRegistryEntry} when the target string matches
+ * the `name` of two or more entries — only possible when the user
+ * previously registered duplicates via `analyze --name X
+ * --allow-duplicate-name` (#829). The error carries enough information
+ * for the caller to render an actionable disambiguation hint without
+ * string-matching on `.message`.
+ *
+ * `kind` is a string literal discriminant (same pattern as
+ * {@link RegistryNameCollisionError}) so callers can narrow via
+ * `err.kind === 'RegistryAmbiguousTargetError'` without importing the
+ * class.
+ */
+class RegistryAmbiguousTargetError extends Error {
+    target;
+    matches;
+    kind = 'RegistryAmbiguousTargetError';
+    constructor(target, matches) {
+        const listing = matches.map((m) => `  - ${m.name}  (${m.path})`).join('\n');
+        super(`Multiple registered repos match "${target}":\n${listing}\n` +
+            `Pass the absolute path instead to disambiguate.`);
+        this.target = target;
+        this.matches = matches;
+        this.name = 'RegistryAmbiguousTargetError';
+    }
+}
+exports.RegistryAmbiguousTargetError = RegistryAmbiguousTargetError;
+/**
+ * Thrown by {@link assertAnalysisFinalized} when a successful `analyze` run
+ * did not actually persist the index metadata file (#1169).
+ *
+ * Why this exists: on Windows, `cgraph analyze` has been observed to exit
+ * cleanly (code 0) with `lbug.wal` written but no metadata file, leaving the
+ * repo invisible to `cgraph list`/`status`. This invariant fails loudly so
+ * the silent-finalize bug surfaces with a non-zero exit code regardless of
+ * the upstream root cause.
+ */
+class AnalysisNotFinalizedError extends Error {
+    repoPath;
+    storagePath;
+    kind = 'AnalysisNotFinalizedError';
+    constructor(repoPath, storagePath) {
+        super(`Analysis did not finalize for ${repoPath}: ` +
+            `${exports.INDEX_METADATA_FILE} was not written to ${path_1.default.join(storagePath, exports.INDEX_METADATA_FILE)}. ` +
+            `The on-disk index is incomplete. ` +
+            `Re-run "cgraph analyze" — if the problem persists, inspect ` +
+            `${storagePath} for a stale lbug.wal that signals an aborted write.`);
+        this.repoPath = repoPath;
+        this.storagePath = storagePath;
+        this.name = 'AnalysisNotFinalizedError';
+    }
+}
+exports.AnalysisNotFinalizedError = AnalysisNotFinalizedError;
+/**
+ * Always returns false — the global registry no longer exists, so no repo is
+ * ever "registered" in that sense.
+ */
+const isRepoRegistered = async (_repoPath) => false;
+exports.isRepoRegistered = isRepoRegistered;
+/**
+ * Verify that a successful `analyze` call actually produced the index
+ * metadata file on disk:
+ *   - `cgraph.json` must exist at `<repoPath>/.cgraphx/code/cgraph.json`.
+ *
+ * Throws {@link AnalysisNotFinalizedError} on failure. Pure read — does not
+ * mutate disk state.
+ *
+ * Callers must skip this assertion on the `alreadyUpToDate` early-return
+ * path, where the rebuild was deliberately not run.
+ */
+const assertAnalysisFinalized = async (repoPath) => {
+    const resolved = path_1.default.resolve(repoPath);
+    const { storagePath, metaPath } = (0, exports.getStoragePaths)(resolved);
+    try {
+        await promises_1.default.access(metaPath);
+    }
+    catch {
+        throw new AnalysisNotFinalizedError(resolved, storagePath);
+    }
+};
+exports.assertAnalysisFinalized = assertAnalysisFinalized;
+/**
+ * Thrown by {@link assertSafeStoragePath} when an entry's `storagePath` does
+ * NOT point at the expected `<entry.path>/.cgraphx/code` subfolder. CLI destructive
+ * commands (`remove`, `clean --all`) should catch this and exit non-zero
+ * without deleting anything — proceeding would mean `fs.rm(recursive: true)`
+ * on whatever odd path the entry is pointing at.
+ */
+class UnsafeStoragePathError extends Error {
+    entry;
+    expectedStoragePath;
+    actualStoragePath;
+    kind = 'UnsafeStoragePathError';
+    constructor(entry, expectedStoragePath, actualStoragePath) {
+        super(`Refusing to remove storage path for safety: expected ` +
+            `"${expectedStoragePath}" under the repo's .cgraphx/code subfolder, ` +
+            `but the entry has "${actualStoragePath}".`);
+        this.entry = entry;
+        this.expectedStoragePath = expectedStoragePath;
+        this.actualStoragePath = actualStoragePath;
+        this.name = 'UnsafeStoragePathError';
+    }
+}
+exports.UnsafeStoragePathError = UnsafeStoragePathError;
+/**
+ * Guard rail for destructive CLI paths: verify that an entry's `storagePath`
+ * is the canonical `<repo>/.cgraphx/code` subfolder of its `path`. If not, throw
+ * {@link UnsafeStoragePathError} so the caller exits without touching disk.
+ *
+ * Pure string check — does NOT require the paths to exist on disk.
+ * Windows: case-insensitive; POSIX: case-sensitive.
+ */
+const assertSafeStoragePath = (entry) => {
+    const expected = path_1.default.join(path_1.default.resolve(entry.path), ...CGRAPHX_CODE_DIR_PARTS);
+    const actual = path_1.default.resolve(entry.storagePath);
+    const matches = process.platform === 'win32'
+        ? expected.toLowerCase() === actual.toLowerCase()
+        : expected === actual;
+    if (!matches) {
+        throw new UnsafeStoragePathError(entry, expected, actual);
+    }
+};
+exports.assertSafeStoragePath = assertSafeStoragePath;
+/**
+ * Resolve a user-supplied target string (from `gitnexus remove <target>`
+ * or equivalent MCP tool argument) to a single registry entry.
+ *
+ * Match precedence (first hit wins, subsequent tiers are only tried if
+ * the prior tier produces zero matches):
+ *   1. Exact resolved-path match (Windows: case-insensitive).
+ *      Paths are unique by registry construction, so a path match can
+ *      never be ambiguous.
+ *   2. Exact `name` match (case-insensitive). If ≥ 2 entries share the
+ *      name — only possible via `--allow-duplicate-name` (#829) —
+ *      throws {@link RegistryAmbiguousTargetError}.
+ *
+ * No fuzzy / partial matching — unambiguous, scriptable behaviour is
+ * more important than convenience for destructive commands.
+ *
+ * Throws {@link RegistryNotFoundError} if no entry matches.
+ *
+ * `entries` is passed in (rather than re-read) so callers that already
+ * hold the registry snapshot (e.g. to print a "before" state) can avoid
+ * a second disk read, and so tests can inject fixtures without touching
+ * `CGRAPH_HOME`.
+ */
+const resolveRegistryEntry = (entries, target) => {
+    // Tier 1: path match. Canonicalise BOTH sides so symlink and
+    // Windows-8.3 quirks don't cause a false miss — e.g. the caller
+    // passes `/var/folders/.../repo` while the registry has
+    // `/private/var/folders/.../repo` (both resolve to the same
+    // `realpath.native`). See `canonicalizePath` for the rationale.
+    //
+    // Canonicalising the STORED entry (not just the input) is what gives
+    // us backward-compat for registries written by versions that only
+    // ran `path.resolve` — both get canonicalised here at compare time.
+    const canonicalTarget = (0, exports.canonicalizePath)(target);
+    const pathMatch = entries.find((e) => {
+        const a = (0, exports.canonicalizePath)(e.path);
+        const b = canonicalTarget;
+        return (0, exports.registryPathEquals)(a, b);
+    });
+    if (pathMatch)
+        return pathMatch;
+    // Tier 2: name match. Case-insensitive on all platforms — registry
+    // name collisions are already filtered case-insensitively in
+    // `registerRepo`, so "APP" vs "app" are considered the same key.
+    const targetLower = target.toLowerCase();
+    const nameMatches = entries.filter((e) => e.name.toLowerCase() === targetLower);
+    if (nameMatches.length === 1)
+        return nameMatches[0];
+    if (nameMatches.length > 1) {
+        throw new RegistryAmbiguousTargetError(target, nameMatches);
+    }
+    // Tier 3: miss. Build the available-names hint ONCE; resolveRepo-style
+    // disambiguated labels (`app (/path)`) are applied when the same name
+    // appears in multiple entries so the user sees the same hint shape as
+    // `-r <name>` errors.
+    const nameCounts = new Map();
+    for (const e of entries) {
+        const key = e.name.toLowerCase();
+        nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+    }
+    const availableNames = entries.map((e) => (nameCounts.get(e.name.toLowerCase()) ?? 0) > 1 ? `${e.name} (${e.path})` : e.name);
+    throw new RegistryNotFoundError(target, availableNames);
+};
+exports.resolveRegistryEntry = resolveRegistryEntry;
+/**
+ * List the indexed repos available to CLI tool operations. With the global
+ * registry removed (spec §8), this is cwd-based discovery ({@link readRegistry})
+ * returning at most ONE entry — the project root whose `.cgraphx/code/` index is
+ * nearest `startCwd` (or the `explicitPath` / `CGRAPH_REPO` override).
+ *
+ * The legacy `validate` flag is now implicit: discovery reads the index meta,
+ * so an absent or unreadable `.cgraphx/code/` naturally yields `[]` (the "no index"
+ * path) — there is no separate on-disk validation step to skip.
+ */
+const listRegisteredRepos = async (opts) => (0, exports.readRegistry)(opts);
+exports.listRegisteredRepos = listRegisteredRepos;
+/**
+ * Get the path to the global CLI config file
+ */
+const getGlobalConfigPath = () => {
+    return path_1.default.join((0, exports.getGlobalDir)(), 'config.json');
+};
+exports.getGlobalConfigPath = getGlobalConfigPath;
+/**
+ * Load CLI config from ~/.cgraphx/code/config.json
+ */
+const loadCLIConfig = async () => {
+    try {
+        const raw = await promises_1.default.readFile((0, exports.getGlobalConfigPath)(), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+};
+exports.loadCLIConfig = loadCLIConfig;
+/**
+ * Save CLI config to ~/.cgraphx/code/config.json
+ */
+const saveCLIConfig = async (config) => {
+    const dir = (0, exports.getGlobalDir)();
+    await promises_1.default.mkdir(dir, { recursive: true });
+    const configPath = (0, exports.getGlobalConfigPath)();
+    await promises_1.default.writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    // Restrict file permissions on Unix (config may contain API keys)
+    if (process.platform !== 'win32') {
+        try {
+            await promises_1.default.chmod(configPath, 0o600);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+};
+exports.saveCLIConfig = saveCLIConfig;
+// ─── Sibling-clone detection ─────────────────────────────────────────────
+//
+// A "sibling clone" is a different on-disk path that points at the same
+// logical repository (same `origin` remote URL) as an indexed project root.
+// With the global registry removed (spec §8), detection is limited to the
+// one project root discoverable from the caller's context ({@link readRegistry}
+// → cwd / `--path` / `CGRAPH_REPO`): it can surface a sibling only when the
+// discovered index's `remoteUrl` matches and its path differs from the
+// caller's `selfPath`. Cross-clone discovery that walks every registered path
+// is gone with the registry; the realistic shape this still catches is a
+// query whose cwd resolves to one clone while the indexed root lives at
+// another path sharing the same origin.
+/**
+ * Find a discovered project root whose `remoteUrl` matches the given one,
+ * excluding `selfPath` (case-insensitive on Windows). Entries without a
+ * `remoteUrl` are ignored — we cannot prove sibling-ness without a fingerprint.
+ */
+const findSiblingClones = async (remoteUrl, selfPath) => {
+    if (!remoteUrl)
+        return [];
+    const entries = await (0, exports.readRegistry)();
+    const isWin = process.platform === 'win32';
+    const norm = (p) => (isWin ? path_1.default.resolve(p).toLowerCase() : path_1.default.resolve(p));
+    const self = norm(selfPath);
+    return entries.filter((e) => e.remoteUrl === remoteUrl && norm(e.path) !== self);
+};
+exports.findSiblingClones = findSiblingClones;