gitnexus 1.6.3-rc.33 → 1.6.3-rc.34

package/dist/cli/index-repo.js

@@ -11,7 +11,7 @@
 import path from 'path';
 import fs from 'fs/promises';
 import { getStoragePaths, loadMeta, addToGitignore, registerRepo, } from '../storage/repo-manager.js';
-import { getGitRoot, isGitRepo } from '../storage/git.js';
+import { getGitRoot, getRemoteUrl, isGitRepo } from '../storage/git.js';
 export const indexCommand = async (inputPathParts, options) => {
     console.log('\n  GitNexus Index\n');
     const inputPath = inputPathParts?.length ? inputPathParts.join(' ') : undefined;
@@ -88,6 +88,13 @@ export const indexCommand = async (inputPathParts, options) => {
         };
     }
     // ── Register in global registry ───────────────────────────────────
+    // Refresh the on-disk meta with a freshly captured `remoteUrl` if
+    // it's missing, so an `index` of an older `.gitnexus/` still gets
+    // sibling-clone fingerprinting on subsequent use without forcing a
+    // full re-analyze.
+    if (!meta.remoteUrl && isGitRepo(repoPath)) {
+        meta.remoteUrl = getRemoteUrl(repoPath);
+    }
     await registerRepo(repoPath, meta);
     await addToGitignore(repoPath);
     const projectName = path.basename(repoPath);

package/dist/core/git-staleness.d.ts

@@ -2,6 +2,7 @@
  * Git working tree vs index commit staleness (used by MCP resources, group status, etc.).
  * Lives in core/ so application code does not depend on the MCP package layer.
  */
+import { type CwdMatch } from '../storage/repo-manager.js';
 export interface StalenessInfo {
     isStale: boolean;
     commitsBehind: number;
@@ -11,3 +12,20 @@ export interface StalenessInfo {
  * Check how many commits the index is behind HEAD (synchronous; uses git CLI).
  */
 export declare function checkStaleness(repoPath: string, lastCommit: string): StalenessInfo;
+/**
+ * Resolve a working directory against the global registry. Returns:
+ *   - `match: 'path'`              when `cwd` is inside a registered entry's path
+ *   - `match: 'sibling-by-remote'` when `cwd` lives in a different on-disk clone
+ *                                   of the same repo (same `remoteUrl`)
+ *   - `match: 'none'`              when neither match applies
+ *
+ * For sibling-by-remote matches, the caller's HEAD and the drift vs the
+ * indexed `lastCommit` are also returned so the MCP layer can warn
+ * before serving silently-stale answers (issue: silent graph drift
+ * across sibling clones).
+ *
+ * `path` matches deliberately use the longest-prefix rule so a cwd
+ * inside a sub-path of a registered repo still matches that repo, not
+ * a coincidentally-aliased shorter entry.
+ */
+export declare function checkCwdMatch(cwd: string): Promise<CwdMatch>;

package/dist/core/git-staleness.js

@@ -3,6 +3,9 @@
  * Lives in core/ so application code does not depend on the MCP package layer.
  */
 import { execFileSync } from 'node:child_process';
+import path from 'path';
+import { readRegistry } from '../storage/repo-manager.js';
+import { getGitRoot, getCurrentCommit, getRemoteUrl } from '../storage/git.js';
 /**
  * Check how many commits the index is behind HEAD (synchronous; uses git CLI).
  */
@@ -27,3 +30,108 @@ export function checkStaleness(repoPath, lastCommit) {
         return { isStale: false, commitsBehind: 0 };
     }
 }
+/**
+ * Compare a sibling-clone HEAD against an indexed `lastCommit`. Returns
+ * `undefined` when the indexed commit is not reachable from the sibling
+ * (e.g. divergent branches, shallow clone, missing ref). The caller
+ * should treat `undefined` as "drift unknown" rather than "no drift".
+ */
+function commitsAheadOfIndexed(siblingPath, indexedCommit) {
+    if (!indexedCommit)
+        return undefined;
+    try {
+        const result = execFileSync('git', ['rev-list', '--count', `${indexedCommit}..HEAD`], {
+            cwd: siblingPath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return parseInt(result, 10) || 0;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve a working directory against the global registry. Returns:
+ *   - `match: 'path'`              when `cwd` is inside a registered entry's path
+ *   - `match: 'sibling-by-remote'` when `cwd` lives in a different on-disk clone
+ *                                   of the same repo (same `remoteUrl`)
+ *   - `match: 'none'`              when neither match applies
+ *
+ * For sibling-by-remote matches, the caller's HEAD and the drift vs the
+ * indexed `lastCommit` are also returned so the MCP layer can warn
+ * before serving silently-stale answers (issue: silent graph drift
+ * across sibling clones).
+ *
+ * `path` matches deliberately use the longest-prefix rule so a cwd
+ * inside a sub-path of a registered repo still matches that repo, not
+ * a coincidentally-aliased shorter entry.
+ */
+export async function checkCwdMatch(cwd) {
+    const entries = await readRegistry();
+    if (entries.length === 0)
+        return { match: 'none' };
+    const isWin = process.platform === 'win32';
+    const norm = (p) => (isWin ? path.resolve(p).toLowerCase() : path.resolve(p));
+    const sep = path.sep;
+    const cwdResolved = path.resolve(cwd);
+    const cwdNorm = norm(cwdResolved);
+    // 1) Path-based match (longest prefix wins, boundary-safe).
+    let bestPath;
+    let bestLen = -1;
+    for (const e of entries) {
+        const p = norm(e.path);
+        if (cwdNorm === p || cwdNorm.startsWith(p + sep)) {
+            if (p.length > bestLen) {
+                bestPath = e;
+                bestLen = p.length;
+            }
+        }
+    }
+    if (bestPath)
+        return { match: 'path', entry: bestPath };
+    // 2) Sibling-by-remote: locate the cwd's git root, get its remote
+    //    URL, and look for any registered entry with the same fingerprint.
+    const cwdGitRoot = getGitRoot(cwdResolved);
+    if (!cwdGitRoot)
+        return { match: 'none' };
+    const cwdRemote = getRemoteUrl(cwdGitRoot);
+    if (!cwdRemote)
+        return { match: 'none' };
+    const sibling = entries.find((e) => e.remoteUrl === cwdRemote && norm(e.path) !== norm(cwdGitRoot));
+    if (!sibling)
+        return { match: 'none' };
+    const cwdHead = getCurrentCommit(cwdGitRoot) || undefined;
+    const drift = commitsAheadOfIndexed(cwdGitRoot, sibling.lastCommit);
+    // Same commit on both clones → still report match=sibling-by-remote
+    // (the relationship is real and useful to callers like list_repos /
+    // future tooling) but leave `hint` unset: there's nothing to warn
+    // about, and `maybeWarnSiblingDrift` already short-circuits this
+    // case independently. Surfacing a no-op hint would force callers
+    // to second-guess whether they need to display it.
+    let hint;
+    if (cwdHead && cwdHead === sibling.lastCommit) {
+        hint = undefined;
+    }
+    else if (drift && drift > 0) {
+        hint =
+            `⚠️ Index for "${sibling.name}" was built at ${sibling.path}; ` +
+                `your cwd (${cwdGitRoot}) is a sibling clone that is ${drift} commit${drift > 1 ? 's' : ''} ` +
+                `ahead of the indexed commit. Results may be stale or incorrect — re-run \`gitnexus analyze\` ` +
+                `to refresh the index.`;
+    }
+    else {
+        hint =
+            `⚠️ Index for "${sibling.name}" was built at ${sibling.path}; ` +
+                `your cwd (${cwdGitRoot}) is a sibling clone whose HEAD differs from the indexed commit. ` +
+                `Results may be stale or incorrect — re-run \`gitnexus analyze\` to refresh the index.`;
+    }
+    return {
+        match: 'sibling-by-remote',
+        entry: sibling,
+        cwdGitRoot,
+        cwdHead,
+        drift,
+        hint,
+    };
+}

package/dist/core/run-analyze.js

@@ -13,7 +13,7 @@ import fs from 'fs/promises';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, } from './lbug/lbug-adapter.js';
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, } from '../storage/repo-manager.js';
-import { getCurrentCommit, hasGitDir, getInferredRepoName } from '../storage/git.js';
+import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName } from '../storage/git.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
 import { STALE_HASH_SENTINEL } from './lbug/schema.js';
@@ -203,6 +203,13 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             repoPath,
             lastCommit: currentCommit,
             indexedAt: new Date().toISOString(),
+            // Captured here (not at registration) so it travels with the
+            // on-disk meta.json — sibling-clone fingerprinting works for
+            // out-of-tree consumers (group-status, future tooling) without
+            // a second git shellout. `undefined` when the repo has no
+            // origin remote, which is fine: paths-only repos behave as
+            // before.
+            remoteUrl: hasGitDir(repoPath) ? getRemoteUrl(repoPath) : undefined,
             stats: {
                 files: pipelineResult.totalFileCount,
                 nodes: stats.nodes,

package/dist/mcp/local/local-backend.d.ts

@@ -56,6 +56,7 @@ interface RepoHandle {
     lbugPath: string;
     indexedAt: string;
     lastCommit: string;
+    remoteUrl?: string;
     stats?: RegistryEntry['stats'];
 }
 export declare class LocalBackend {
@@ -65,6 +66,13 @@ export declare class LocalBackend {
     private reinitPromises;
     private lastStalenessCheck;
     private groupToolSvc;
+    /**
+     * One-shot stderr warnings for sibling-clone drift, keyed by
+     * `${repoId}|${cwdGitRoot}`. Without this guard every tool call
+     * from inside a sibling clone would print the same warning,
+     * making MCP stderr unreadable.
+     */
+    private warnedSiblingDrift;
     /**
      * Cross-repo group tools (CLI). Shares logic with MCP `group_*` handlers.
      */
@@ -110,14 +118,55 @@ export declare class LocalBackend {
      * List all registered repos with their metadata.
      * Re-reads the global registry so newly indexed repos are discovered
      * without restarting the MCP server.
+     *
+     * Each entry includes:
+     *   - `staleness`: if the indexed clone's own HEAD has moved past
+     *     the recorded `lastCommit` (option D in the issue's fix list).
+     *   - `siblings`: other registered entries sharing the same
+     *     `remoteUrl` (option B's payoff: callers can see at a glance
+     *     that another clone of the same logical repo is registered).
+     *   - `remoteUrl`: the canonical origin URL recorded at index time.
      */
     listRepos(): Promise<Array<{
         name: string;
         path: string;
         indexedAt: string;
         lastCommit: string;
+        remoteUrl?: string;
         stats?: any;
+        staleness?: {
+            commitsBehind: number;
+            hint?: string;
+        };
+        siblings?: Array<{
+            name: string;
+            path: string;
+            lastCommit: string;
+        }>;
     }>>;
+    /**
+     * Best-effort sibling-clone drift warning.
+     *
+     * When the resolved index has a `remoteUrl` recorded and the caller's
+     * `process.cwd()` is inside a *different* clone of the same repo, emit
+     * one stderr line per (repo, cwd) pair so the operator knows the
+     * graph may be stale relative to what's actually on disk under their
+     * cwd. Silent on path matches and on repos without a remote URL.
+     *
+     * Limitation: in MCP stdio server mode `process.cwd()` is the
+     * server's CWD at start time, *not* the agent client's CWD. The
+     * warning therefore only fires when the MCP server itself was
+     * launched from inside a sibling clone (typical for `npx gitnexus
+     * serve` from a polecat workspace). Surfacing the client's CWD
+     * would require a per-tool-call `cwd` parameter — out of scope for
+     * the current MCP contract.
+     *
+     * Pure side-effect (stderr); never affects the returned handle.
+     * After the first computation for a given (repo, cwd) pair the
+     * result is cached so subsequent `resolveRepo()` calls don't
+     * re-shell-out to git.
+     */
+    private maybeWarnSiblingDrift;
     callTool(method: string, params: any): Promise<any>;
     /**
      * Query tool — process-grouped search.

package/dist/mcp/local/local-backend.js

@@ -20,6 +20,7 @@ import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member
 import { collectBestChunks } from '../../core/embeddings/types.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
+import { checkStaleness, checkCwdMatch } from '../../core/git-staleness.js';
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -162,6 +163,13 @@ export class LocalBackend {
     reinitPromises = new Map();
     lastStalenessCheck = new Map();
     groupToolSvc = null;
+    /**
+     * One-shot stderr warnings for sibling-clone drift, keyed by
+     * `${repoId}|${cwdGitRoot}`. Without this guard every tool call
+     * from inside a sibling clone would print the same warning,
+     * making MCP stderr unreadable.
+     */
+    warnedSiblingDrift = new Set();
     /**
      * Cross-repo group tools (CLI). Shares logic with MCP `group_*` handlers.
      */
@@ -218,6 +226,7 @@ export class LocalBackend {
                 lbugPath,
                 indexedAt: entry.indexedAt,
                 lastCommit: entry.lastCommit,
+                remoteUrl: entry.remoteUrl,
                 stats: entry.stats,
             };
             this.repos.set(id, handle);
@@ -270,13 +279,25 @@ export class LocalBackend {
      */
     async resolveRepo(repoParam) {
         const result = this.resolveRepoFromCache(repoParam);
-        if (result)
+        if (result) {
+            // Issue: silent graph drift across sibling clones.
+            // If the caller's cwd lives in a *different* on-disk clone of
+            // the same repo (matched by `remoteUrl`), warn once per
+            // (repo, cwd) pair on stderr. We do not fail or refuse to
+            // serve — the index is still the best answer we have — but
+            // the operator/agent has to know the answer may be stale.
+            this.maybeWarnSiblingDrift(result).catch(() => {
+                /* best-effort; never throw from resolveRepo */
+            });
             return result;
+        }
         // Miss — refresh registry and try once more
         await this.refreshRepos();
         const retried = this.resolveRepoFromCache(repoParam);
-        if (retried)
+        if (retried) {
+            this.maybeWarnSiblingDrift(retried).catch(() => { });
             return retried;
+        }
         // Still no match — throw with helpful message
         if (this.repos.size === 0) {
             throw new Error('No indexed repositories. Run: gitnexus analyze');
@@ -406,16 +427,113 @@ export class LocalBackend {
      * List all registered repos with their metadata.
      * Re-reads the global registry so newly indexed repos are discovered
      * without restarting the MCP server.
+     *
+     * Each entry includes:
+     *   - `staleness`: if the indexed clone's own HEAD has moved past
+     *     the recorded `lastCommit` (option D in the issue's fix list).
+     *   - `siblings`: other registered entries sharing the same
+     *     `remoteUrl` (option B's payoff: callers can see at a glance
+     *     that another clone of the same logical repo is registered).
+     *   - `remoteUrl`: the canonical origin URL recorded at index time.
      */
     async listRepos() {
         await this.refreshRepos();
-        return [...this.repos.values()].map((h) => ({
-            name: h.name,
-            path: h.repoPath,
-            indexedAt: h.indexedAt,
-            lastCommit: h.lastCommit,
-            stats: h.stats,
-        }));
+        const handles = [...this.repos.values()];
+        // Pre-group registered handles by `remoteUrl` so the sibling
+        // lookup is O(1) per handle. We reuse the in-memory `this.repos`
+        // (already populated by `refreshRepos`) instead of doing a fresh
+        // `readRegistry()` per entry — that would be N file reads for N
+        // registered repos.
+        const isWin = process.platform === 'win32';
+        const norm = (p) => (isWin ? path.resolve(p).toLowerCase() : path.resolve(p));
+        const byRemote = new Map();
+        for (const h of handles) {
+            if (!h.remoteUrl)
+                continue;
+            const list = byRemote.get(h.remoteUrl) ?? [];
+            list.push(h);
+            byRemote.set(h.remoteUrl, list);
+        }
+        return handles.map((h) => {
+            const stale = checkStaleness(h.repoPath, h.lastCommit);
+            const selfNorm = norm(h.repoPath);
+            const siblings = h.remoteUrl
+                ? (byRemote.get(h.remoteUrl) ?? []).filter((e) => norm(e.repoPath) !== selfNorm)
+                : [];
+            return {
+                name: h.name,
+                path: h.repoPath,
+                indexedAt: h.indexedAt,
+                lastCommit: h.lastCommit,
+                remoteUrl: h.remoteUrl,
+                stats: h.stats,
+                staleness: stale.isStale
+                    ? { commitsBehind: stale.commitsBehind, hint: stale.hint }
+                    : undefined,
+                siblings: siblings.length > 0
+                    ? siblings.map((s) => ({
+                        name: s.name,
+                        path: s.repoPath,
+                        lastCommit: s.lastCommit,
+                    }))
+                    : undefined,
+            };
+        });
+    }
+    /**
+     * Best-effort sibling-clone drift warning.
+     *
+     * When the resolved index has a `remoteUrl` recorded and the caller's
+     * `process.cwd()` is inside a *different* clone of the same repo, emit
+     * one stderr line per (repo, cwd) pair so the operator knows the
+     * graph may be stale relative to what's actually on disk under their
+     * cwd. Silent on path matches and on repos without a remote URL.
+     *
+     * Limitation: in MCP stdio server mode `process.cwd()` is the
+     * server's CWD at start time, *not* the agent client's CWD. The
+     * warning therefore only fires when the MCP server itself was
+     * launched from inside a sibling clone (typical for `npx gitnexus
+     * serve` from a polecat workspace). Surfacing the client's CWD
+     * would require a per-tool-call `cwd` parameter — out of scope for
+     * the current MCP contract.
+     *
+     * Pure side-effect (stderr); never affects the returned handle.
+     * After the first computation for a given (repo, cwd) pair the
+     * result is cached so subsequent `resolveRepo()` calls don't
+     * re-shell-out to git.
+     */
+    async maybeWarnSiblingDrift(handle) {
+        if (!handle.remoteUrl)
+            return;
+        let cwd;
+        try {
+            cwd = process.cwd();
+        }
+        catch {
+            return;
+        }
+        // Early-exit cache: keyed on (repo, cwd) BEFORE any git shellout.
+        // After the first call for a given cwd, this short-circuits the
+        // up-to-four `execSync`/`execFileSync` calls inside `checkCwdMatch`
+        // — important for MCP-server mode where `process.cwd()` is constant
+        // and `resolveRepo` runs on every tool call.
+        const cacheKey = `${handle.id}|${cwd}`;
+        if (this.warnedSiblingDrift.has(cacheKey))
+            return;
+        const match = await checkCwdMatch(cwd);
+        if (match.match !== 'sibling-by-remote' ||
+            !match.entry ||
+            !match.cwdGitRoot ||
+            match.entry.path !== handle.repoPath ||
+            !match.hint) {
+            // Cache "nothing to warn about" outcomes too — `checkCwdMatch`
+            // is deterministic for a fixed (registry, cwd) pair, so re-running
+            // it yields nothing new.
+            this.warnedSiblingDrift.add(cacheKey);
+            return;
+        }
+        this.warnedSiblingDrift.add(cacheKey);
+        console.error(`GitNexus: ${match.hint}`);
     }
     // ─── Tool Dispatch ───────────────────────────────────────────────
     async callTool(method, params) {

package/dist/storage/git.d.ts

@@ -1,5 +1,29 @@
 export declare const isGitRepo: (repoPath: string) => boolean;
 export declare const getCurrentCommit: (repoPath: string) => string;
+/**
+ * Get a stable canonical identifier for the repo's `origin` remote, if any.
+ *
+ * Used to fingerprint two on-disk clones as the same logical repository
+ * (issue #XXX — silent graph drift across sibling clones). `path` alone
+ * is unreliable: worktrees, "clean clone for indexing" hygiene, and
+ * multi-agent workspaces routinely have the same repo at multiple
+ * absolute paths. The remote URL is the only on-disk signal that
+ * survives those conventions.
+ *
+ * Normalisation strategy:
+ *   - Strip a trailing `.git` so `https://x/y` and `https://x/y.git` collapse.
+ *   - Strip a trailing `/` for the same reason.
+ *   - `git@github.com:foo/bar` and `https://github.com/foo/bar` are
+ *     intentionally NOT collapsed — they are different remotes from
+ *     git's perspective and we don't want to assert equivalence.
+ *   - Lower-case the host portion so `GitHub.com` and `github.com`
+ *     don't desync; preserves case in path because some hosts
+ *     (Bitbucket Server) treat repo paths case-sensitively.
+ *
+ * Returns `undefined` when there is no origin remote, the directory
+ * isn't a git repo, or git itself isn't available.
+ */
+export declare const getRemoteUrl: (repoPath: string) => string | undefined;
 /**
  * Find the git repository root from any path inside the repo
  */

package/dist/storage/git.js

@@ -19,6 +19,65 @@ export const getCurrentCommit = (repoPath) => {
         return '';
     }
 };
+/**
+ * Get a stable canonical identifier for the repo's `origin` remote, if any.
+ *
+ * Used to fingerprint two on-disk clones as the same logical repository
+ * (issue #XXX — silent graph drift across sibling clones). `path` alone
+ * is unreliable: worktrees, "clean clone for indexing" hygiene, and
+ * multi-agent workspaces routinely have the same repo at multiple
+ * absolute paths. The remote URL is the only on-disk signal that
+ * survives those conventions.
+ *
+ * Normalisation strategy:
+ *   - Strip a trailing `.git` so `https://x/y` and `https://x/y.git` collapse.
+ *   - Strip a trailing `/` for the same reason.
+ *   - `git@github.com:foo/bar` and `https://github.com/foo/bar` are
+ *     intentionally NOT collapsed — they are different remotes from
+ *     git's perspective and we don't want to assert equivalence.
+ *   - Lower-case the host portion so `GitHub.com` and `github.com`
+ *     don't desync; preserves case in path because some hosts
+ *     (Bitbucket Server) treat repo paths case-sensitively.
+ *
+ * Returns `undefined` when there is no origin remote, the directory
+ * isn't a git repo, or git itself isn't available.
+ */
+export const getRemoteUrl = (repoPath) => {
+    let raw;
+    try {
+        raw = execSync('git config --get remote.origin.url', {
+            cwd: repoPath,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return undefined;
+    }
+    if (!raw)
+        return undefined;
+    let normalised = raw.replace(/\/$/, '').replace(/\.git$/, '');
+    // Lower-case the host segment of `scheme://[user@]host[:port]/...`
+    // and the host segment of `git@host:owner/repo` SCP form.
+    // SSH user-segment regex deliberately accepts the common
+    // `git@`/`<alnum>-_@` cases. Less common usernames (e.g. with
+    // dots) fall through to the URL-form branch — they will simply
+    // not get host-case normalisation, which is acceptable: the raw
+    // `git config` output is still a valid fingerprint, just slightly
+    // less collapsible across host casings.
+    const sshMatch = normalised.match(/^(git@|[a-zA-Z0-9_-]+@)([^:/]+)(:.+)$/);
+    if (sshMatch) {
+        normalised = `${sshMatch[1]}${sshMatch[2].toLowerCase()}${sshMatch[3]}`;
+    }
+    else {
+        const urlMatch = normalised.match(/^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^/]+)(\/.*)?$/);
+        if (urlMatch) {
+            normalised = `${urlMatch[1]}${urlMatch[2].toLowerCase()}${urlMatch[3] ?? ''}`;
+        }
+    }
+    return normalised;
+};
 /**
  * Find the git repository root from any path inside the repo
  */

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

@@ -40,6 +40,14 @@ export interface RepoMeta {
     repoPath: string;
     lastCommit: string;
     indexedAt: string;
+    /**
+     * Canonical `origin` remote URL captured at index time. Used to
+     * fingerprint the same logical repo across multiple on-disk clones
+     * (worktrees, agent workspaces, "clean clone for indexing"). When
+     * absent (no remote configured, git unavailable, etc.) the repo is
+     * treated as path-only and sibling-clone detection is skipped.
+     */
+    remoteUrl?: string;
     stats?: {
         files?: number;
         nodes?: number;
@@ -65,6 +73,8 @@ export interface RegistryEntry {
     storagePath: string;
     indexedAt: string;
     lastCommit: string;
+    /** See {@link RepoMeta.remoteUrl}. Mirrored from meta at register time. */
+    remoteUrl?: string;
     stats?: RepoMeta['stats'];
 }
 /**
@@ -344,3 +354,36 @@ export declare const loadCLIConfig: () => Promise<CLIConfig>;
  * Save CLI config to ~/.gitnexus/config.json
  */
 export declare const saveCLIConfig: (config: CLIConfig) => Promise<void>;
+/**
+ * Find other registered entries 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.
+ */
+export declare const findSiblingClones: (remoteUrl: string | undefined, selfPath: string) => Promise<RegistryEntry[]>;
+/**
+ * Description of how a working directory relates to a registered index.
+ *
+ * `match` semantics:
+ *   - `path`              — `cwd` is inside the registered entry's path.
+ *   - `sibling-by-remote` — `cwd` is in a different on-disk clone of the
+ *                           same repo (same `remoteUrl`).
+ *   - `none`              — no relationship found.
+ */
+export interface CwdMatch {
+    match: 'path' | 'sibling-by-remote' | 'none';
+    entry?: RegistryEntry;
+    /** The git toplevel of `cwd`, when `cwd` is inside a git work tree. */
+    cwdGitRoot?: string;
+    /** HEAD of the cwd's clone, when resolvable. */
+    cwdHead?: string;
+    /**
+     * Number of commits the registered `lastCommit` is behind the
+     * sibling-clone HEAD, when both refs are known to the cwd's clone.
+     * `undefined` when the comparison cannot be performed (e.g. the
+     * indexed commit isn't reachable from cwd).
+     */
+    drift?: number;
+    /** Human-readable hint, set whenever the situation warrants warning. */
+    hint?: string;
+}

package/dist/storage/repo-manager.js

@@ -379,6 +379,7 @@ export const registerRepo = async (repoPath, meta, opts) => {
         storagePath,
         indexedAt: meta.indexedAt,
         lastCommit: meta.lastCommit,
+        remoteUrl: meta.remoteUrl,
         stats: meta.stats,
     };
     if (existingIdx >= 0) {
@@ -643,3 +644,38 @@ export const saveCLIConfig = async (config) => {
         }
     }
 };
+// ─── Sibling-clone detection ─────────────────────────────────────────────
+//
+// A "sibling clone" is a different on-disk path that points at the same
+// logical repository (same `origin` remote URL) as a registered index.
+// This shows up in three operationally important shapes (see issue):
+//
+//   1. The same repo is checked out under multiple paths (worktrees,
+//      multi-agent workspaces). Only one is indexed; the others silently
+//      diverge from the graph.
+//   2. The indexed clone is itself behind its own HEAD (the existing
+//      `checkStaleness` already handles this case).
+//   3. A query is issued from a `cwd` that lives inside a sibling clone
+//      whose HEAD has drifted from the indexed `lastCommit`.
+//
+// Detection is intentionally remote-URL-based and does NOT walk the
+// filesystem hunting for unregistered clones — only registered entries
+// are considered. The `cwd`-driven branch ({@link checkSiblingDrift})
+// also accepts an unregistered cwd, because the live caller's working
+// directory is the one place we can cheaply learn about an
+// unregistered clone.
+/**
+ * Find other registered entries 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.
+ */
+export const findSiblingClones = async (remoteUrl, selfPath) => {
+    if (!remoteUrl)
+        return [];
+    const entries = await readRegistry();
+    const isWin = process.platform === 'win32';
+    const norm = (p) => (isWin ? path.resolve(p).toLowerCase() : path.resolve(p));
+    const self = norm(selfPath);
+    return entries.filter((e) => e.remoteUrl === remoteUrl && norm(e.path) !== self);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.3-rc.33",
+  "version": "1.6.3-rc.34",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",