release: v1.6.4-rc.74

fix(server): use ipKeyGenerator for IPv6 subnet normalisation (#1360 ) (#1374 )
The custom keyGenerator in createRouteLimiter referenced req.ip without passing it through express-rate-limit's ipKeyGenerator helper. This caused ERR_ERL_KEY_GEN_IPV6 on startup when binding to 0.0.0.0, and meant each full IPv6 address got its own rate-limit counter — trivially bypassing the per-IP limit. Wrap the IP through ipKeyGenerator so IPv6 addresses are collapsed to their /56 subnet before keying the counter. The existing fallback chain (req.ip → socket.remoteAddress → 'unknown') is preserved to keep ERR_ERL_UNDEFINED_IP_ADDRESS from firing on abruptly closed connections. Tests: 3 new assertions (construction-time regression guard, source-grep for import and call site).
2026-05-06 13:25:04 +00:00 · 2026-05-06 14:07:37 +01:00 · 2026-05-06 09:19:10 +01:00 · 2026-05-06 07:52:58 +01:00 · 2026-05-06 07:41:46 +01:00 · 2026-05-06 07:09:42 +01:00
485 changed files with 299031 additions and 5879 deletions
@@ -17,12 +17,13 @@ npx gitnexus analyze

 Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.

-| Flag           | Effect                                                           |
-| -------------- | ---------------------------------------------------------------- |
-| `--force`      | Force full re-index even if up to date                           |
-| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| Flag                | Effect                                                                                                  |
+| ------------------- | ------------------------------------------------------------------------------------------------------- |
+| `--force`           | Force full re-index even if up to date                                                                  |
+| `--embeddings`      | Enable embedding generation for semantic search (off by default)                                        |
+| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them.    |

-**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.

 ### status — Check index freshness

@@ -1,4 +1,8 @@
-# Images (signed Cosign keyless on every push from main / vX.Y.Z tags)
+# Images (signed Cosign keyless on every push from main / vX.Y.Z tags).
+# Available from both GHCR (default below) and Docker Hub — pick one:
+#   GHCR:       ghcr.io/abhigyanpatwari/gitnexus{,-web}:latest
+#   Docker Hub: akonlabs/gitnexus{,-web}:latest
+# Both registries receive the same digest from a single signed build.
 SERVER_IMAGE=ghcr.io/abhigyanpatwari/gitnexus:latest
 WEB_IMAGE=ghcr.io/abhigyanpatwari/gitnexus-web:latest

@@ -0,0 +1,105 @@
+# Wraps docker/build-push-action with one automatic retry. Upstream explicitly
+# keeps retry out of the action (docker/build-push-action#1422); a local
+# composite keeps docker.yml readable and pins the same action SHA in one place.
+name: Docker build-push (with retry)
+description: >-
+  Runs docker/build-push-action twice on failure with a configurable backoff,
+  then exposes the digest from whichever attempt succeeded.
+
+inputs:
+  context:
+    description: Build context path
+    required: false
+    default: '.'
+  file:
+    description: Dockerfile path (relative to repo root)
+    required: true
+  platforms:
+    description: Comma-separated platforms list for buildx
+    required: true
+  push:
+    description: Whether to push (string 'true' or 'false')
+    required: true
+  tags:
+    description: Newline-separated image tags (from docker/metadata-action)
+    required: true
+  labels:
+    description: Labels string (from docker/metadata-action)
+    required: true
+  cache-from:
+    description: buildx cache-from value
+    required: true
+  cache-to:
+    description: buildx cache-to value (include ignore-error=true for GHA cache flakes)
+    required: true
+  retry-wait-seconds:
+    description: Seconds to sleep before the second attempt
+    required: false
+    default: '45'
+
+outputs:
+  digest:
+    description: Manifest digest from the successful build attempt
+    value: ${{ steps.resolve.outputs.digest }}
+
+runs:
+  using: composite
+  steps:
+    - name: Build and push (attempt 1)
+      id: try1
+      continue-on-error: true
+      uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+      with:
+        context: ${{ inputs.context }}
+        file: ${{ inputs.file }}
+        platforms: ${{ inputs.platforms }}
+        push: ${{ inputs.push == 'true' }}
+        tags: ${{ inputs.tags }}
+        labels: ${{ inputs.labels }}
+        cache-from: ${{ inputs.cache-from }}
+        cache-to: ${{ inputs.cache-to }}
+        provenance: mode=max
+        sbom: true
+
+    - name: Backoff before Docker build retry
+      if: steps.try1.outcome == 'failure'
+      shell: bash
+      env:
+        RETRY_WAIT_SECONDS: ${{ inputs.retry-wait-seconds }}
+      run: |
+        echo "::warning::Docker build-push attempt 1 failed; retrying in ${RETRY_WAIT_SECONDS}s…"
+        sleep "${RETRY_WAIT_SECONDS}"
+
+    - name: Build and push (attempt 2)
+      id: try2
+      if: steps.try1.outcome == 'failure'
+      uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+      with:
+        context: ${{ inputs.context }}
+        file: ${{ inputs.file }}
+        platforms: ${{ inputs.platforms }}
+        push: ${{ inputs.push == 'true' }}
+        tags: ${{ inputs.tags }}
+        labels: ${{ inputs.labels }}
+        cache-from: ${{ inputs.cache-from }}
+        cache-to: ${{ inputs.cache-to }}
+        provenance: mode=max
+        sbom: true
+
+    - name: Resolve image digest
+      id: resolve
+      if: always()
+      shell: bash
+      run: |
+        set -euo pipefail
+        if [ "${{ steps.try1.outcome }}" = "success" ]; then
+          echo "digest=${{ steps.try1.outputs.digest }}" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+        if [ "${{ steps.try2.outcome }}" = "success" ]; then
+          echo "::notice::docker-build-push retry succeeded (attempt 2); investigate if this recurs across runs."
+          echo "digest=${{ steps.try2.outputs.digest }}" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+        echo "::error::Docker build and push failed after two attempts (registry/cache flake or real build error)."
+        exit 1
@@ -1,12 +1,15 @@
 name: Setup GitNexus Web
-description: Setup Node.js 20, build gitnexus-shared, install web dependencies
+description: Setup Node.js 20.19+ (vite 7 floor), build gitnexus-shared, install web dependencies

 runs:
  using: composite
  steps:
    - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
      with:
-        node-version: 20
+        # Vite 7 requires Node ^20.19.0 || >=22.12.0 (require(esm) support).
+        # Pin explicitly so we don't depend on the floating "20" alias resolving
+        # to a high enough patch version on every runner image.
+        node-version: '20.19.0'
        cache: npm
        cache-dependency-path: gitnexus-web/package-lock.json

@@ -36,7 +36,6 @@ import urllib.request

 REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
 GITNEXUS_DIR = REPO_ROOT / "gitnexus"
-VENDOR_PROTO_DIR = GITNEXUS_DIR / "vendor" / "tree-sitter-proto"

 # ── Upgrade target ──────────────────────────────────────────────────────
 # The runtime version we want to upgrade TO. Update this when the goal
@@ -73,18 +72,37 @@ GRAMMARS: dict[str, tuple[str, str, str]] = {
    "tree-sitter-rust":       ("tree-sitter/tree-sitter-rust",       "master", "src/parser.c"),
    "tree-sitter-swift":      ("alex-pinkus/tree-sitter-swift",      "main",   "src/parser.c"),
    "tree-sitter-typescript": ("tree-sitter/tree-sitter-typescript", "master",  "typescript/src/parser.c"),
+    # Vendored parsers — kept here so the upstream coords for drift
+    # detection are co-located with every other grammar's coords.
+    "tree-sitter-proto":      ("coder3101/tree-sitter-proto",        "main",   "src/parser.c"),
 }

-UPSTREAM_PROTO_OWNER = "coder3101"
-UPSTREAM_PROTO_REPO = "tree-sitter-proto"
-UPSTREAM_PROTO_BRANCH = "main"
+# Grammars deliberately held below npm latest. The readiness report surfaces
+# these so reviewers can tell intentional pins apart from drift, and so the
+# context for each pin (which issue motivated it) is visible at a glance.
+# Add an entry whenever you pin a grammar below npm latest.
+INTENTIONAL_PINS: dict[str, str] = {
+    "tree-sitter-c": (
+        "#1242 — last release built against the tree-sitter@0.21 ABI; "
+        "tree-sitter-c@0.23.x prebuilds segfault on Windows under tree-sitter@0.21.1"
+    ),
+    "tree-sitter-cpp": (
+        "#1242 — last 0.23.x release before tree-sitter-cpp added a runtime "
+        "dep on the broken-ABI tree-sitter-c@^0.23.1; pinning here removes "
+        "the need for a transitive override"
+    ),
+}


 # ── Helpers ─────────────────────────────────────────────────────────────

+def _load_package_json() -> dict:
+    return json.loads((GITNEXUS_DIR / "package.json").read_text())
+
+
 def read_current_runtime() -> str:
    """Return the tree-sitter runtime version pinned in package.json (e.g. '0.21')."""
-    pkg = json.loads((GITNEXUS_DIR / "package.json").read_text())
+    pkg = _load_package_json()
    raw = pkg["dependencies"]["tree-sitter"]
    match = re.search(r"(\d+)\.(\d+)", raw)
    if not match:
@@ -92,6 +110,22 @@ def read_current_runtime() -> str:
    return f"{match.group(1)}.{match.group(2)}"


+def read_pinned_grammar_versions() -> dict[str, str]:
+    """Return the grammar version range pinned in gitnexus/package.json.
+
+    Looks at both runtime and optional dependencies. Returns the raw range
+    string (e.g. '0.21.4', '^0.23.0', 'file:./vendor/...') so the report can
+    expose how flexible each pin is.
+    """
+    pkg = _load_package_json()
+    pinned: dict[str, str] = {}
+    for section in ("dependencies", "optionalDependencies"):
+        for name, spec in (pkg.get(section) or {}).items():
+            if name.startswith("tree-sitter-"):
+                pinned[name] = spec
+    return pinned
+
+
 def npm_view_json(pkg: str) -> dict | None:
    """Fetch package metadata from the npm registry via HTTPS.

@@ -185,8 +219,178 @@ def md_h(text: str, level: int = 2) -> str:
    return f"{'#' * level} {text}\n"


+def _first_sentence(text: str) -> str:
+    """Return the leading sentence of a free-form rationale string.
+
+    Vendor package.json `_vendoredBy` fields often look like
+    "<reason>. <install-script breadcrumb>. Do NOT <warning>." — the
+    first sentence is what reviewers actually want to read; the rest is
+    noise in this context. Match a sentence-ending '.' followed by
+    whitespace; fall back to the whole string if nothing matches.
+    """
+    text = text.strip()
+    match = re.search(r"\.\s+[A-Z]", text)
+    return text[: match.start() + 1] if match else text
+
+
+def range_includes(spec: str | None, version: str) -> bool:
+    """Return True if pinned-range `spec` accepts the concrete `version`.
+
+    Handles the spec shapes we actually use in package.json:
+      - exact pins  ('0.21.4')
+      - caret / tilde ranges ('^0.23.0', '~0.23.5')
+      - non-registry pins ('file:./vendor/...', 'git+...') — always False,
+        because there's no meaningful "behind npm latest" comparison.
+    """
+    if not spec or spec == "—":
+        return False
+    if spec.startswith(("file:", "git", "http")):
+        return False
+    if spec.startswith(("^", "~")):
+        return satisfies_target(spec, version)
+    return spec.strip() == version.strip()
+
+
+def is_vendored_pin(spec: str | None) -> bool:
+    return bool(spec) and spec.startswith(("file:", "git", "http"))
+
+
+def vendored_drift_summary(
+    name: str, upstream_repo: str, upstream_branch: str, parser_path: str
+) -> dict:
+    """Inspect a vendored grammar under gitnexus/vendor/<name>.
+
+    Returns the vendored package.json's ``version`` and ``_vendoredBy``
+    fields (which carry the human rationale for vendoring), the vendored
+    parser's ABI, and a comparison against upstream main. We deliberately
+    rely on ``_vendoredBy`` rather than a parallel registry in this
+    script: the rationale belongs next to the vendored sources, not in
+    a daily-running CI script.
+    """
+    vendor_dir = GITNEXUS_DIR / "vendor" / name
+    pkg: dict = {}
+    pkg_path = vendor_dir / "package.json"
+    if pkg_path.is_file():
+        try:
+            pkg = json.loads(pkg_path.read_text(encoding="utf-8", errors="ignore"))
+        except json.JSONDecodeError:
+            pass
+
+    vendored_parser = vendor_dir / parser_path
+    if not vendored_parser.is_file():
+        vendored_parser = vendor_dir / "src" / "parser.c"
+    vendored_abi = extract_language_version(vendored_parser)
+
+    upstream_url = (
+        f"https://raw.githubusercontent.com/{upstream_repo}/"
+        f"{upstream_branch}/{parser_path}"
+    )
+    upstream_text = fetch_text(upstream_url)
+    upstream_abi = extract_abi_from_text(upstream_text) if upstream_text else None
+
+    sha_text = fetch_text(
+        f"https://api.github.com/repos/{upstream_repo}/commits/{upstream_branch}"
+    )
+    upstream_sha = "?"
+    if sha_text:
+        try:
+            upstream_sha = json.loads(sha_text).get("sha", "?")[:12]
+        except json.JSONDecodeError:
+            pass
+
+    local_text = (
+        vendored_parser.read_text(encoding="utf-8", errors="ignore")
+        if vendored_parser.is_file()
+        else ""
+    )
+    in_sync = bool(
+        upstream_text
+        and local_text.replace("\r\n", "\n") == upstream_text.replace("\r\n", "\n")
+    )
+
+    return {
+        "name": name,
+        "vendored_version": pkg.get("version", "?"),
+        "vendored_by": pkg.get("_vendoredBy"),
+        "vendored_abi": vendored_abi,
+        "upstream_repo": upstream_repo,
+        "upstream_branch": upstream_branch,
+        "upstream_sha": upstream_sha,
+        "upstream_abi": upstream_abi,
+        "in_sync": in_sync,
+    }
+
+
 # ── Main ────────────────────────────────────────────────────────────────

+
+def _classify_grammar(
+    *,
+    name: str,
+    pinned_spec: str | None,
+    npm_version: str,
+    peer_range: str | None,
+    fetch_failed: bool,
+    target_compat: bool,
+    current_compat: bool,
+    upstream_progress: str | None,
+) -> dict:
+    """Decide a single primary disposition + a separate bump-now hint.
+
+    Buckets are mutually exclusive and ordered by what a reviewer should
+    look at first:
+      - fetch_failed   : npm registry fetch failed (treat as blocker, but
+                          surface separately so reviewers don't confuse it
+                          with an upstream block)
+      - intentional    : pinned in INTENTIONAL_PINS — explicit choice
+      - ready          : npm-latest peer dep already accepts the target
+                          runtime; nothing to do
+      - waiting        : main has a fix (ABI 15 or relaxed peer) but no
+                          published npm release yet
+      - blocked        : peer dep too tight on both npm and main
+
+    Independently of bucket, `bump_now` reports whether reviewers can
+    move the pin forward today without touching the runtime — we only
+    suggest it when npm-latest's peer dep also accepts our *current*
+    runtime, otherwise the bump would break `npm install`.
+    """
+    is_vendored = is_vendored_pin(pinned_spec)
+    behind_latest = (
+        not is_vendored
+        and npm_version != "?"
+        and not range_includes(pinned_spec, npm_version)
+    )
+    # Intentional pins must never appear as actionable bumps — by definition
+    # we're holding them back on purpose. The pin can only be lifted by
+    # editing INTENTIONAL_PINS and package.json together.
+    bump_now = behind_latest and current_compat and name not in INTENTIONAL_PINS
+
+    if fetch_failed:
+        bucket = "fetch_failed"
+    elif name in INTENTIONAL_PINS:
+        bucket = "intentional"
+    elif target_compat:
+        bucket = "ready"
+    elif upstream_progress:
+        bucket = "waiting"
+    else:
+        bucket = "blocked"
+
+    return {
+        "name": name,
+        "pinned_spec": pinned_spec or "—",
+        "npm_version": npm_version,
+        "peer_range": peer_range,
+        "target_compat": target_compat,
+        "current_compat": current_compat,
+        "upstream_progress": upstream_progress,
+        "behind_latest": behind_latest,
+        "bump_now": bump_now,
+        "bucket": bucket,
+        "is_vendored": is_vendored,
+    }
+
+
 def main() -> int:
    blockers: dict[str, str] = {}
    lines: list[str] = []
@@ -196,20 +400,68 @@ def main() -> int:
    current_runtime = read_current_runtime()
    current_abi_range = RUNTIME_ABI_RANGES.get(current_runtime, (0, 0))
    target_abi_range = RUNTIME_ABI_RANGES.get(TARGET_RUNTIME_MAJOR_MINOR, (0, 0))
+    pinned_versions = read_pinned_grammar_versions()

-    lines.append(f"- Current runtime: `tree-sitter@{current_runtime}.x` (ABI {current_abi_range[0]}..{current_abi_range[1]})")
-    lines.append(f"- Target runtime: `tree-sitter@{TARGET_RUNTIME}` (ABI {target_abi_range[0]}..{target_abi_range[1]})")
+    lines.append(
+        f"`tree-sitter@{current_runtime}.x` (ABI {current_abi_range[0]}–{current_abi_range[1]}) "
+        f"→ target `tree-sitter@{TARGET_RUNTIME}` "
+        f"(ABI {target_abi_range[0]}–{target_abi_range[1]})."
+    )
    lines.append("")

-    # ── Grammar peer-dep compatibility ───────────────────────────────
-    lines.append(md_h("Grammar compatibility", 2))
-    lines.append("| Grammar | npm latest | Peer dep | Satisfies 0.25? | ABI | Upstream ABI | Status |")
-    lines.append("|---|---|---|---|---|---|---|")
+    # First pass: gather raw data + classification per grammar. We render
+    # the human-friendly buckets first, then the raw matrix in a <details>
+    # block at the end. Status text in the matrix is preserved verbatim
+    # so the workflow's row-diff change-detection keeps working.
+    grammar_rows: list[dict] = []
+    raw_matrix: list[str] = [
+        "| Grammar | Pinned | npm latest | Peer dep | Satisfies 0.25? | ABI | Upstream ABI | Status |",
+        "|---|---|---|---|---|---|---|---|",
+    ]

-    ready_count = 0
-    total_count = len(GRAMMARS)
+    vendored_grammars: list[dict] = []

    for name, (upstream_repo, upstream_branch, parser_path) in sorted(GRAMMARS.items()):
+        pinned_spec = pinned_versions.get(name, "—")
+
+        # Vendored grammars don't have an "npm latest" we install from —
+        # we ship our own copy under gitnexus/vendor/<name>. Treat them
+        # as a separate kind of artefact: their readiness for the runtime
+        # upgrade depends on the vendored ABI being in the target range,
+        # not on a peer-dep negotiation.
+        if is_vendored_pin(pinned_spec):
+            v = vendored_drift_summary(name, upstream_repo, upstream_branch, parser_path)
+            v["pinned_spec"] = pinned_spec
+            # Three-state classification: in-range, out-of-range, or
+            # not-introspectable (e.g. tree-sitter-swift ships only
+            # prebuilt .node binaries, no parser.c — assume compatible).
+            if v["vendored_abi"] is None:
+                v["target_compat"] = True
+                v["abi_state"] = "prebuilt"
+                status = "Vendored (prebuilt — ABI not introspectable)"
+            elif target_abi_range[0] <= v["vendored_abi"] <= target_abi_range[1]:
+                v["target_compat"] = True
+                v["abi_state"] = "in_range"
+                status = "Vendored (ABI in target range)"
+            else:
+                v["target_compat"] = False
+                v["abi_state"] = "out_of_range"
+                status = "Vendored (ABI out of range)"
+                blockers[name] = (
+                    f"vendored `{name}`: ABI {v['vendored_abi']} outside target range "
+                    f"{target_abi_range[0]}..{target_abi_range[1]}"
+                )
+            # Keep vendored grammars in the raw matrix so the workflow's
+            # row-diff change-detection picks up status transitions on
+            # them too. npm-only columns get sentinels.
+            raw_matrix.append(
+                f"| `{name}` | {pinned_spec} | (vendored) | (vendored) | "
+                f"{'Yes' if v['target_compat'] else '**No**'} | "
+                f"{v['vendored_abi'] or '?'} | {v['upstream_abi'] or '?'} | {status} |"
+            )
+            vendored_grammars.append(v)
+            continue
+
        # Fetch latest npm metadata.
        info = npm_view_json(name)
        fetch_failed = info is None
@@ -226,12 +478,14 @@ def main() -> int:

        if fetch_failed:
            peer_display = "? (fetch failed)"
-            compatible = False
+            target_compat = False
+            current_compat = False
        else:
            peer_display = peer_range or "none"
            if peer_range and not peer_optional:
                peer_display += " (required)"
-            compatible = satisfies_target(peer_range, TARGET_RUNTIME)
+            target_compat = satisfies_target(peer_range, TARGET_RUNTIME)
+            current_compat = satisfies_target(peer_range, f"{current_runtime}.0")

        # Check installed ABI using the same parser_path from GRAMMARS.
        installed_parser = GITNEXUS_DIR / "node_modules" / name / parser_path
@@ -250,22 +504,40 @@ def main() -> int:
        upstream_abi = extract_abi_from_text(upstream_text) if upstream_text else None
        upstream_abi_display = str(upstream_abi) if upstream_abi else "?"

-        # Determine status.
+        # Status text + upstream-progress detection. The Status column
+        # values are preserved as-is to keep the workflow's row-diff
+        # change-detection working on the raw matrix below.
+        upstream_progress: str | None = None
        if fetch_failed:
            status = "Unknown (fetch failed)"
            blockers[name] = f"`{name}`: npm registry fetch failed — could not verify peer dep"
-        elif compatible:
+        elif name in INTENTIONAL_PINS:
+            # An intentional pin is, by definition, a held-back grammar:
+            # whatever npm-latest's peer dep says, our shipped version is
+            # the one whose ABI/peer must accept the target runtime, and
+            # the pin entry exists precisely because it does not. Treat
+            # it as a blocker until the pin is lifted (entry removed from
+            # INTENTIONAL_PINS), at which point this grammar falls back
+            # to standard classification on the next run.
+            status = "Intentionally pinned"
+            blockers[name] = (
+                f"`{name}` intentionally pinned at `{pinned_spec}` "
+                f"({INTENTIONAL_PINS[name]}) — pin must be lifted "
+                f"before the {TARGET_RUNTIME} runtime upgrade"
+            )
+        elif target_compat:
            status = "Ready"
-            ready_count += 1
        elif upstream_abi and upstream_abi >= 15:
            status = "Unreleased (ABI 15 on main)"
+            upstream_progress = f"ABI 15 on `{upstream_repo}@{upstream_branch}` not yet published"
            blockers[name] = f"`{name}`: ABI 15 on `{upstream_repo}` main but not published to npm"
        else:
            status = "Blocking"
            blockers[name] = f"`{name}@{npm_version}`: peer `{peer_display}` incompatible with 0.25"

-        # Also check upstream package.json for relaxed peer dep.
-        if not compatible and not fetch_failed:
+        # Also check upstream package.json for relaxed peer dep — beats
+        # the ABI-15 hint when both are true.
+        if not target_compat and not fetch_failed:
            upstream_pkg_url = (
                f"https://raw.githubusercontent.com/{upstream_repo}/"
                f"{upstream_branch}/package.json"
@@ -277,82 +549,250 @@ def main() -> int:
                    upstream_peer = (upstream_pkg.get("peerDependencies") or {}).get("tree-sitter")
                    if upstream_peer and satisfies_target(upstream_peer, TARGET_RUNTIME):
                        status = "Unreleased (peer relaxed on main)"
+                        upstream_progress = (
+                            f"peer relaxed to `{upstream_peer}` on "
+                            f"`{upstream_repo}@{upstream_branch}` not yet published"
+                        )
                        blockers[name] = f"`{name}`: peer dep relaxed on `{upstream_repo}` main but not published to npm"
                except json.JSONDecodeError:
                    pass

-        compat_icon = "Yes" if compatible else "**No**"
-        lines.append(
-            f"| `{name}` | {npm_version} | {peer_display} | {compat_icon} | {abi_display} | {upstream_abi_display} | {status} |"
+        pinned_spec = pinned_versions.get(name, "—")
+        compat_icon = "Yes" if target_compat else "**No**"
+        raw_matrix.append(
+            f"| `{name}` | {pinned_spec} | {npm_version} | {peer_display} | "
+            f"{compat_icon} | {abi_display} | {upstream_abi_display} | {status} |"
        )

-    lines.append("")
-    lines.append(f"**{ready_count}/{total_count}** grammars ready for `tree-sitter@{TARGET_RUNTIME}`.")
-    lines.append("")
+        grammar_rows.append(_classify_grammar(
+            name=name,
+            pinned_spec=pinned_spec,
+            npm_version=npm_version,
+            peer_range=peer_range,
+            fetch_failed=fetch_failed,
+            target_compat=target_compat,
+            current_compat=current_compat,
+            upstream_progress=upstream_progress,
+        ))

-    # ── Vendored proto drift ─────────────────────────────────────────
-    lines.append(md_h("Vendored tree-sitter-proto", 2))
-    vendored_abi = extract_language_version(VENDOR_PROTO_DIR / "src" / "parser.c")
+    # ── Bucketize ────────────────────────────────────────────────────
+    by_bucket: dict[str, list[dict]] = {
+        k: [] for k in ("ready", "intentional", "waiting", "blocked", "fetch_failed")
+    }
+    for row in grammar_rows:
+        by_bucket[row["bucket"]].append(row)
+    bump_now = [r for r in grammar_rows if r["bump_now"]]
+    ready_count = len(by_bucket["ready"])

-    upstream_proto_url = (
-        f"https://raw.githubusercontent.com/{UPSTREAM_PROTO_OWNER}/"
-        f"{UPSTREAM_PROTO_REPO}/{UPSTREAM_PROTO_BRANCH}/src/parser.c"
-    )
-    upstream_proto_text = fetch_text(upstream_proto_url)
-    upstream_proto_abi = extract_abi_from_text(upstream_proto_text) if upstream_proto_text else None
+    # ── TL;DR ────────────────────────────────────────────────────────
+    npm_count = len(grammar_rows)
+    vendored_count = len(vendored_grammars)
+    vendored_ready = sum(1 for v in vendored_grammars if v["target_compat"])

-    sha_url = (
-        f"https://api.github.com/repos/{UPSTREAM_PROTO_OWNER}/"
-        f"{UPSTREAM_PROTO_REPO}/commits/{UPSTREAM_PROTO_BRANCH}"
-    )
-    sha_text = fetch_text(sha_url)
-    upstream_sha = "?"
-    if sha_text:
-        try:
-            upstream_sha = json.loads(sha_text).get("sha", "?")[:12]
-        except json.JSONDecodeError:
-            pass
-
-    local_proto_path = VENDOR_PROTO_DIR / "src" / "parser.c"
-    local_proto_text = local_proto_path.read_text(encoding="utf-8", errors="ignore") if local_proto_path.is_file() else ""
-    in_sync = bool(
-        upstream_proto_text
-        and local_proto_text.replace("\r\n", "\n")
-        == upstream_proto_text.replace("\r\n", "\n")
-    )
-
-    lines.append(f"- Upstream: `{UPSTREAM_PROTO_OWNER}/{UPSTREAM_PROTO_REPO}@{UPSTREAM_PROTO_BRANCH}` (HEAD `{upstream_sha}`)")
-    lines.append(f"- Upstream ABI: **{upstream_proto_abi}**")
-    lines.append(f"- Vendored ABI: **{vendored_abi}**")
-    lines.append(f"- In sync: {'yes' if in_sync else 'no — upstream has diverged'}")
-
-    if upstream_proto_abi and vendored_abi and upstream_proto_abi > vendored_abi:
-        can_upgrade = upstream_proto_abi <= target_abi_range[1]
-        lines.append(f"- Upstream ABI {upstream_proto_abi} {'is' if can_upgrade else 'is NOT'} within target runtime range ({target_abi_range[0]}..{target_abi_range[1]})")
-        if can_upgrade:
-            lines.append(f"- **Action:** after upgrading to tree-sitter@{TARGET_RUNTIME}, regenerate vendored parser.c from upstream `{upstream_sha}`")
-        else:
-            lines.append(f"- **Action:** wait for runtime upgrade beyond {TARGET_RUNTIME} that supports ABI {upstream_proto_abi}")
-            blockers["vendored-proto-abi"] = f"vendored tree-sitter-proto: upstream ABI {upstream_proto_abi} outside target range"
-    elif not in_sync:
-        lines.append("- **Action:** review upstream changes; vendored copy may need updating")
-        blockers["vendored-proto-sync"] = "vendored tree-sitter-proto: out of sync with upstream"
-
-    # ── Summary ──────────────────────────────────────────────────────
-    lines.append("")
-    lines.append(md_h("Summary", 2))
-    if blockers:
-        lines.append(f"**{len(blockers)} blocker(s) remaining:**\n")
-        for b in blockers.values():
-            lines.append(f"- {b}")
-        lines.append("")
-        lines.append("Upgrade to `tree-sitter@0.25` is **blocked**.")
+    if not blockers:
+        verdict = "**Ready** — all grammars are 0.25-compatible. The runtime upgrade can proceed."
    else:
-        lines.append("All grammars are compatible. Upgrade to `tree-sitter@0.25` is **ready**.")
+        moved = "no" if not by_bucket["waiting"] else f"yes — {len(by_bucket['waiting'])} grammars have unreleased fixes on main"
+        verdict = (
+            f"**Blocked** — {len(blockers)} grammars are not yet 0.25-compatible. "
+            f"Upstream movement: {moved}."
+        )
+
+    lines.append(md_h("TL;DR", 2))
+    lines.append(verdict)
+    lines.append("")
+    lines.append(f"- {ready_count}/{npm_count} npm-installed grammars already accept tree-sitter@{TARGET_RUNTIME}")
+    if vendored_count:
+        lines.append(
+            f"- {vendored_ready}/{vendored_count} vendored grammars at an ABI within the target runtime range"
+        )
+    lines.append(f"- {len(by_bucket['intentional'])} intentionally pinned (see below)")
+    lines.append(f"- {len(by_bucket['waiting'])} waiting on an upstream npm release")
+    lines.append(f"- {len(by_bucket['blocked'])} blocked on upstream (no fix even on main)")
+    if by_bucket['fetch_failed']:
+        lines.append(f"- {len(by_bucket['fetch_failed'])} could not be checked (npm registry unreachable)")
+    if bump_now:
+        lines.append(
+            f"- **{len(bump_now)} bump candidate(s) you can take TODAY** (npm-latest "
+            f"is newer than the pin AND its peer dep accepts our current runtime)"
+        )
+    lines.append("")
+
+    # ── What you can do today ───────────────────────────────────────
+    if bump_now:
+        lines.append(md_h("What you can do today", 2))
+        lines.append(
+            "These pins lag npm latest and the latest version's peer dep already "
+            "accepts our current `tree-sitter@" + current_runtime + ".x` runtime. "
+            "Bumping is independent of the 0.25 upgrade and should be a quick PR."
+        )
+        lines.append("")
+        for r in sorted(bump_now, key=lambda r: r["name"]):
+            lines.append(
+                f"- `{r['name']}`: `{r['pinned_spec']}` → `{r['npm_version']}` "
+                f"(peer `{r['peer_range'] or 'none'}`)"
+            )
+        lines.append("")
+
+    # ── Per-disposition sections ────────────────────────────────────
+    def _emit_bucket(title: str, body_intro: str, rows: list[dict], render) -> None:
+        if not rows:
+            return
+        lines.append(md_h(f"{title} ({len(rows)})", 3))
+        lines.append(body_intro)
+        lines.append("")
+        for r in sorted(rows, key=lambda r: r["name"]):
+            lines.append(render(r))
+        lines.append("")
+
+    lines.append(md_h("Disposition", 2))
+
+    _emit_bucket(
+        "Ready for 0.25",
+        "These grammars' npm-latest peer dep already accepts the target runtime. No action needed for the upgrade.",
+        by_bucket["ready"],
+        lambda r: (
+            f"- `{r['name']}` — pinned `{r['pinned_spec']}`, npm latest `{r['npm_version']}`"
+            + ("  _(also a bump candidate — see above)_" if r["bump_now"] else "")
+        ),
+    )
+
+    if by_bucket["intentional"]:
+        lines.append(md_h(f"Intentionally pinned ({len(by_bucket['intentional'])})", 3))
+        lines.append(
+            "Deliberately held below npm latest. These are **not** drift — each entry "
+            "lists the issue motivating the pin and the condition for unpinning."
+        )
+        lines.append("")
+        for r in sorted(by_bucket["intentional"], key=lambda r: r["name"]):
+            reason = INTENTIONAL_PINS.get(r["name"], "(no rationale recorded)")
+            lines.append(
+                f"- `{r['name']}` pinned at `{r['pinned_spec']}` "
+                f"(npm latest `{r['npm_version']}`)\n  {reason}"
+            )
+        lines.append("")
+
+    _emit_bucket(
+        "Waiting on upstream npm release",
+        "Fixes are merged on the upstream main branch but not yet published to npm. "
+        "We can move forward as soon as upstream cuts a release.",
+        by_bucket["waiting"],
+        lambda r: (
+            f"- `{r['name']}@{r['npm_version']}` — peer `{r['peer_range'] or 'none'}`. "
+            f"_{r['upstream_progress']}_"
+        ),
+    )
+
+    _emit_bucket(
+        "Blocked on upstream",
+        "Peer dep is too tight on both the latest npm release and on upstream main. "
+        "These need an upstream issue/PR before we can proceed.",
+        by_bucket["blocked"],
+        lambda r: (
+            f"- `{r['name']}@{r['npm_version']}` — peer `{r['peer_range'] or 'none'}`"
+            + (" _(vendored)_" if r["is_vendored"] else "")
+        ),
+    )
+
+    _emit_bucket(
+        "Could not check",
+        "npm registry fetch failed for these grammars. Re-run the workflow to retry.",
+        by_bucket["fetch_failed"],
+        lambda r: f"- `{r['name']}` (pinned `{r['pinned_spec']}`)",
+    )
+
+    # ── Vendored parsers ────────────────────────────────────────────
+    if vendored_grammars:
+        lines.append(md_h(f"Vendored parsers ({len(vendored_grammars)})", 2))
+        lines.append(
+            "These grammars ship from `gitnexus/vendor/` rather than the npm "
+            "registry. Their compatibility is governed by the **vendored "
+            "ABI** (must lie in the target runtime's range), not by a peer-"
+            "dep negotiation. The rationale for each vendored copy lives in "
+            "its own `package.json` `_vendoredBy` field."
+        )
+        lines.append("")
+        for v in sorted(vendored_grammars, key=lambda v: v["name"]):
+            sync_label = (
+                "in sync with upstream" if v["in_sync"] else "diverged from upstream"
+            )
+            if v["abi_state"] == "in_range":
+                abi_label = f"ABI `{v['vendored_abi']}` (in target range)"
+            elif v["abi_state"] == "prebuilt":
+                abi_label = "ABI `prebuilt` (binary-only vendor, source not introspectable)"
+            else:
+                abi_label = (
+                    f"ABI `{v['vendored_abi']}` (**outside** target range "
+                    f"{target_abi_range[0]}..{target_abi_range[1]})"
+                )
+            upstream_abi_str = (
+                f"ABI `{v['upstream_abi']}`" if v["upstream_abi"] else "ABI `?`"
+            )
+            lines.append(
+                f"- **`{v['name']}`** `{v['vendored_version']}` — {abi_label}, "
+                f"upstream `{v['upstream_repo']}@{v['upstream_sha']}` "
+                f"{upstream_abi_str} · {sync_label}"
+            )
+            if v["vendored_by"]:
+                # Show the first sentence — vendor package.json fields tend
+                # to start with the rationale and tail off into install-
+                # script breadcrumbs that aren't useful in this report.
+                rationale = _first_sentence(v["vendored_by"])
+                lines.append(f"  - **Why vendored:** {rationale}")
+            # Action computation: needs regen iff upstream ABI exceeds
+            # vendored AND is still within target range. If upstream ABI
+            # exceeds the target, that's a runtime-side blocker. For
+            # prebuilt-only vendors we can't drive this from source ABI;
+            # the action is a manual upstream-binary refresh, surfaced
+            # via the in-sync flag instead.
+            if v["abi_state"] == "prebuilt":
+                if not v["in_sync"]:
+                    lines.append(
+                        "  - **Action:** check whether upstream has shipped a new "
+                        "prebuilt release; this vendor ships binary-only artefacts."
+                    )
+            elif v["upstream_abi"] and v["vendored_abi"] and v["upstream_abi"] > v["vendored_abi"]:
+                if v["upstream_abi"] <= target_abi_range[1]:
+                    lines.append(
+                        f"  - **Action:** after upgrading to tree-sitter@{TARGET_RUNTIME}, "
+                        f"regenerate `parser.c` from upstream `{v['upstream_sha']}`."
+                    )
+                else:
+                    lines.append(
+                        f"  - **Action:** wait for a runtime supporting ABI "
+                        f"{v['upstream_abi']}; current target ({TARGET_RUNTIME}) only "
+                        f"goes up to ABI {target_abi_range[1]}."
+                    )
+                    blockers[f"vendored-{v['name']}-abi"] = (
+                        f"vendored {v['name']}: upstream ABI {v['upstream_abi']} outside target range"
+                    )
+            elif not v["in_sync"]:
+                lines.append(
+                    "  - **Action:** review upstream changes; vendored copy may "
+                    "need a refresh (no ABI bump required)."
+                )
+        lines.append("")
+
+    # ── Raw matrix (for completeness + workflow row-diff) ────────────
+    lines.append(md_h("Full grammar matrix", 2))
+    lines.append(
+        "<details><summary>Click to expand the raw per-grammar table "
+        "(used by the workflow's change-detection bot).</summary>\n"
+    )
+    lines.extend(raw_matrix)
+    lines.append("\n</details>")
+    lines.append("")

    print("\n".join(lines))
    return 1 if blockers else 0


 if __name__ == "__main__":
+    # Force UTF-8 output: the report contains em-dashes and arrows that
+    # Windows' default cp1252 codepage can't encode, while Linux runners
+    # default to UTF-8 anyway.
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
+    except Exception:
+        pass
    sys.exit(main())
@@ -28,6 +28,9 @@ jobs:
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

+      - name: Configure e2e GitNexus home
+        run: echo "GITNEXUS_HOME=${RUNNER_TEMP}/gitnexus-home" >> "$GITHUB_ENV"
+
      - uses: ./.github/actions/setup-gitnexus-web

      - name: Install Playwright browsers
@@ -44,9 +47,14 @@ jobs:

      - name: Analyze repository (index for backend)
        run: |
-          node gitnexus/dist/cli/index.js analyze || true
-          if [ ! -d ".gitnexus" ]; then
-            echo "::error::No .gitnexus index created"
+          E2E_REPO="${RUNNER_TEMP}/gitnexus-e2e-repo"
+          rm -rf "${E2E_REPO}"
+          mkdir -p "${E2E_REPO}"
+          cp -R gitnexus/test/fixtures/mini-repo/src "${E2E_REPO}/src"
+          printf '%s\n' '{"name":"e2e-mini-repo","version":"0.0.0","private":true}' > "${E2E_REPO}/package.json"
+          node gitnexus/dist/cli/index.js analyze "${E2E_REPO}" --skip-git --skip-agents-md --name e2e-mini-repo
+          if [ ! -d "${E2E_REPO}/.gitnexus" ]; then
+            echo "::error::No fixture .gitnexus index created"
            exit 1
          fi

@@ -9,7 +9,7 @@ jobs:
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: 20
          cache: npm
@@ -22,7 +22,7 @@ jobs:
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: 20
          cache: npm
@@ -11,7 +11,8 @@ name: Scope Resolution Parity
 # TWICE on every PR:
 #
 #   1. `REGISTRY_PRIMARY_<LANG>=0` — legacy DAG path (guarantees we haven't
-#      broken the old path while migrating).
+#      broken the old path while migrating). Known legacy gaps may be skipped
+#      through the resolver test helper's expected-failure list.
 #   2. `REGISTRY_PRIMARY_<LANG>=1` — registry-primary path (guarantees the
 #      new path carries the same behavior — the parity gate).
 #
@@ -1,9 +1,6 @@
 name: CI

 on:
-  push:
-    branches: [main]
-    paths-ignore: ['**.md', 'docs/**', 'LICENSE']
  pull_request:
    branches: [main]
    paths-ignore: ['**.md', 'docs/**', 'LICENSE']
@@ -15,13 +12,12 @@ on:
 # called-workflow context `github.workflow` evaluation is ambiguous across GitHub
 # Actions versions, and a prefix that could resolve to the caller's name would
 # share a concurrency group with the caller → deadlock. A literal prefix is
-# immune. Direct `push`/`pull_request` invocations use `CI-<ref>`; invocations
-# from a reusable-workflow caller fall into a per-run-unique group that never
-# serializes with the caller.
-# cancel-in-progress is event-aware: cancel superseded PR runs, queue every other
-# event (push to main, workflow_call from publish.yml, etc.).
+# immune. Direct `pull_request` invocations use `CI-<ref>`; invocations from a
+# reusable-workflow caller fall into a per-run-unique group that never serializes
+# with the caller. `push` to main is handled by release-candidate.yml, which
+# calls this workflow once before publishing.
 concurrency:
-  group: ${{ (github.event_name == 'pull_request' || github.event_name == 'push') && format('CI-{0}', github.ref) || format('CI-nested-{0}', github.run_id) }}
+  group: ${{ github.event_name == 'pull_request' && format('CI-{0}', github.ref) || format('CI-nested-{0}', github.run_id) }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

 # ── Reusable workflow orchestration ─────────────────────────────────
@@ -1,96 +0,0 @@
-name: Claude Code Review
-
-# Uses pull_request_target so the workflow runs as defined on the default branch,
-# which allows access to secrets for posting review comments on fork PRs.
-# SECURITY: The checkout pins the fork's HEAD SHA (not the branch name) to
-# prevent TOCTOU races (force-push between trigger and checkout). The
-# claude-code-action sandboxes execution — it does NOT run arbitrary code
-# from the checked-out source.
-
-on:
-  # Trigger only when explicitly requested:
-  #   - Add the "claude-review" label to a PR, OR
-  #   - Comment "@claude" or "/review" on a PR
-  pull_request_target:
-    types: [labeled]
-  issue_comment:
-    types: [created]
-
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-# Serialize per-PR to avoid racing review comments.
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.issue.number || github.event.pull_request.number }}
-  cancel-in-progress: false
-
-jobs:
-  claude-review:
-    # Run only when:
-    #   1. The "claude-review" label is added to a non-draft PR by a trusted contributor, OR
-    #   2. A trusted contributor comments "@claude" or "/review" on a PR
-    if: |
-      (
-        github.event_name == 'pull_request_target' &&
-        github.event.label.name == 'claude-review' &&
-        github.event.pull_request.draft == false &&
-        (github.event.pull_request.author_association == 'OWNER' ||
-         github.event.pull_request.author_association == 'MEMBER' ||
-         github.event.pull_request.author_association == 'COLLABORATOR')
-      ) ||
-      (
-        github.event_name == 'issue_comment' &&
-        github.event.issue.pull_request &&
-        (contains(github.event.comment.body, '@claude') ||
-         contains(github.event.comment.body, '/review')) &&
-        (github.event.comment.author_association == 'OWNER' ||
-         github.event.comment.author_association == 'MEMBER' ||
-         github.event.comment.author_association == 'COLLABORATOR')
-      )
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    permissions:
-      contents: read
-      pull-requests: write
-      issues: read
-      id-token: write
-
-    steps:
-      # For issue_comment triggers, resolve the PR number, head SHA, and fork repo
-      - name: Resolve PR context
-        id: pr
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
-        with:
-          script: |
-            let pr;
-            if (context.eventName === 'issue_comment') {
-              const resp = await github.rest.pulls.get({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                pull_number: context.payload.issue.number,
-              });
-              pr = resp.data;
-            } else {
-              pr = context.payload.pull_request;
-            }
-            core.setOutput('number', pr.number);
-            core.setOutput('sha', pr.head.sha);
-            core.setOutput('repo', pr.head.repo.full_name);
-            core.setOutput('branch', pr.head.ref);
-
-      - name: Checkout PR head
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          repository: ${{ steps.pr.outputs.repo }}
-          ref: ${{ steps.pr.outputs.sha }}
-          fetch-depth: 1
-
-      - name: Run Claude Code Review
-        id: claude-review
-        uses: anthropics/claude-code-action@9469d113c6afd29550c402740f22d1a97dd1209b # v1
-        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          allowed_non_write_users: '*'
-          show_full_output: true
-          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
-          plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ steps.pr.outputs.number }}'
@@ -1,8 +1,17 @@
 name: Claude Code

+# Label-triggered code-review requests use pull_request_target so the workflow
+# runs as defined on the default branch, which allows access to secrets for
+# posting review comments on fork PRs. SECURITY: PR checkouts pin the fork's
+# HEAD SHA (not the branch name) to prevent TOCTOU races.
+# The claude-code-action sandboxes execution; it does not run arbitrary code
+# from the checked-out source.
+
 on:
  issue_comment:
    types: [created]
+  pull_request_target:
+    types: [labeled]
  pull_request_review_comment:
    types: [created]
  issues:
@@ -21,7 +30,10 @@ jobs:
    if: |
      (
        github.event_name == 'issue_comment' &&
-        contains(github.event.comment.body, '@claude') &&
+        (
+          contains(github.event.comment.body, '@claude') ||
+          (github.event.issue.pull_request && contains(github.event.comment.body, '/review'))
+        ) &&
        (github.event.comment.author_association == 'OWNER' ||
         github.event.comment.author_association == 'MEMBER' ||
         github.event.comment.author_association == 'COLLABORATOR')
@@ -46,6 +58,14 @@ jobs:
        (github.event.issue.author_association == 'OWNER' ||
         github.event.issue.author_association == 'MEMBER' ||
         github.event.issue.author_association == 'COLLABORATOR')
+      ) ||
+      (
+        github.event_name == 'pull_request_target' &&
+        github.event.label.name == 'claude-review' &&
+        github.event.pull_request.draft == false &&
+        (github.event.pull_request.author_association == 'OWNER' ||
+         github.event.pull_request.author_association == 'MEMBER' ||
+         github.event.pull_request.author_association == 'COLLABORATOR')
      )
    runs-on: ubuntu-latest
    timeout-minutes: 30
@@ -63,33 +83,48 @@ jobs:
        with:
          script: |
            // Determine if this event is PR-related
-            let prNumber = null;
+            let pr = null;
            if (context.eventName === 'issue_comment' && context.payload.issue.pull_request) {
-              prNumber = context.payload.issue.number;
+              const resp = await github.rest.pulls.get({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: context.payload.issue.number,
+              });
+              pr = resp.data;
            } else if (context.eventName === 'pull_request_review_comment') {
-              prNumber = context.payload.pull_request.number;
+              pr = context.payload.pull_request;
            } else if (context.eventName === 'pull_request_review') {
-              prNumber = context.payload.pull_request.number;
+              pr = context.payload.pull_request;
+            } else if (context.eventName === 'pull_request_target') {
+              pr = context.payload.pull_request;
            }

-            if (!prNumber) {
+            if (!pr) {
              core.setOutput('is_pr', 'false');
              return;
            }

-            const resp = await github.rest.pulls.get({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: prNumber,
-            });
-            const pr = resp.data;
-
            core.setOutput('is_pr', 'true');
-            core.setOutput('number', String(prNumber));
+            core.setOutput('number', String(pr.number));
            core.setOutput('sha', pr.head.sha);
            core.setOutput('repo', pr.head.repo.full_name);
            core.setOutput('branch', pr.head.ref);

+      - name: Resolve Claude mode
+        id: mode
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
+        with:
+          script: |
+            const body = (context.payload.comment?.body ?? '').toLowerCase();
+            const isCodeReview =
+              (context.eventName === 'pull_request_target' &&
+                context.payload.label?.name === 'claude-review') ||
+              (context.eventName === 'issue_comment' &&
+                Boolean(context.payload.issue?.pull_request) &&
+                body.includes('/review'));
+
+            core.setOutput('code_review', isCodeReview ? 'true' : 'false');
+
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
@@ -98,6 +133,7 @@ jobs:
          fetch-depth: 1

      - name: Run Claude Code
+        if: steps.mode.outputs.code_review != 'true'
        id: claude
        uses: anthropics/claude-code-action@9469d113c6afd29550c402740f22d1a97dd1209b # v1
        with:
@@ -109,3 +145,16 @@ jobs:
          # This is an optional setting that allows Claude to read CI results on PRs
          additional_permissions: |
            actions: read
+
+      - name: Run Claude Code Review
+        if: steps.mode.outputs.code_review == 'true'
+        id: claude-review
+        uses: anthropics/claude-code-action@9469d113c6afd29550c402740f22d1a97dd1209b # v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          allowed_non_write_users: '*'
+          show_full_output: true
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ steps.pr.outputs.number }}'
@@ -0,0 +1,71 @@
+name: CodeQL
+
+# Static analysis (SAST) for TypeScript/JavaScript and Python sources.
+# Findings upload to the GitHub Security tab as SARIF.
+#
+# Advisory only on first introduction — see docs/plans/2026-05-03-001-feat-automated-security-scans-plan.md.
+# Promote to a required check after baseline triage (operator decision).
+
+on:
+  pull_request:
+    branches: [main]
+    paths-ignore: ['**.md', 'docs/**', 'LICENSE']
+  push:
+    branches: [main]
+  schedule:
+    # Weekly Monday 06:00 UTC — catches advisories newly published against
+    # already-merged code without waiting for the next PR.
+    - cron: '0 6 * * 1'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      actions: read
+      contents: read
+      # security-events:write is what enables SARIF upload to the Security tab.
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [javascript-typescript, python]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Don't leave GITHUB_TOKEN in .git/config for downstream steps to read.
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3.35.3
+        with:
+          languages: ${{ matrix.language }}
+          queries: security-and-quality
+          # Exclude generated/vendored code; tune after first-run signal.
+          # gitnexus/vendor/ holds tree-sitter-proto sources (regenerated, not authored).
+          # CodeQL path filters use .gitignore-style globs and do NOT support
+          # brace expansion — list each generated parser file separately.
+          config: |
+            paths-ignore:
+              - '**/dist/**'
+              - '**/node_modules/**'
+              - 'gitnexus/vendor/**'
+              - 'gitnexus/src/core/parsing/**/parser.c'
+              - 'gitnexus/src/core/parsing/**/parser.js'
+              # Test fixtures are intentionally synthetic inputs (broken/unused
+              # code, malformed samples) used to exercise the analyzer. CodeQL
+              # findings here are noise, not real bugs.
+              - '**/test/fixtures/**'
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3.35.3
+        with:
+          category: '/language:${{ matrix.language }}'
@@ -0,0 +1,36 @@
+name: Dependency Review
+
+# Blocks PRs that introduce dependencies with high/critical known vulnerabilities.
+# Reads the dependency graph diff between PR head and base.
+#
+# This is a required-check candidate after one week of clean runs
+# (operator decision — see docs/plans/2026-05-03-001-feat-automated-security-scans-plan.md).
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      # pull-requests:write enables the inline summary comment on failure.
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Dependency Review
+        uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0
+        with:
+          fail-on-severity: high
+          comment-summary-in-pr: on-failure
@@ -4,9 +4,18 @@ on:
  push:
    tags:
      - 'v*'
-  # No workflow_dispatch: publishing is exclusively tag-driven so that every
-  # signed image corresponds 1:1 to a published `gitnexus@X.Y.Z` on npm. A
-  # manual run from a branch ref would fail the version check below anyway.
+  pull_request:
+  # workflow_dispatch is allowed for dry-run testing only. Publishing is still
+  # exclusively tag-driven so that every signed image corresponds 1:1 to a
+  # published `gitnexus@X.Y.Z` on npm. dry_run:true (the default) skips all
+  # push, sign, and attestation steps — the build runs but nothing is published.
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Build only — skip push, signing, and attestations'
+        required: false
+        default: true
+        type: boolean
  workflow_call:
    inputs:
      tag:
@@ -60,6 +69,12 @@ jobs:
            slug: gitnexus

    steps:
+      # Only the workflow_call path requires a non-empty `inputs.tag` — callers
+      # (e.g. release-candidate.yml) must pass the RC tag explicitly. On direct
+      # tag pushes the tag comes from `github.ref`, so `inputs.tag` is always
+      # empty and validating it here would break every real release (#1064).
+      # The downstream "Verify tag matches gitnexus/package.json version" step
+      # handles both event types by falling back to GITHUB_REF.
      - name: Validate tag input
        if: github.event_name == 'workflow_call'
        shell: bash
@@ -85,6 +100,7 @@ jobs:
      # `gitnexus@X.Y.Z` published to npm — no drift, no surprises.
      - name: Verify tag matches gitnexus/package.json version
        id: version
+        if: github.event_name != 'workflow_dispatch' && github.event_name != 'pull_request'
        shell: bash
        env:
          # For workflow_call the tag comes from the caller input; for push events
@@ -119,12 +135,27 @@ jobs:
        uses: sigstore/cosign-installer@cad07c2e89fa2edd6e2d7bab4c1aa38e53f76003 # v4.1.1

      - name: Log in to GitHub Container Registry
+        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

+      # Docker Hub is a mirror of GHCR: same tags, same digests, same Cosign
+      # signatures. GHCR remains authoritative (it is the registry the
+      # ClusterImagePolicy globs against by default), but Docker Hub is the
+      # registry most users reach for first, so we publish there too.
+      # Requires repo secrets DOCKERHUB_USERNAME and DOCKERHUB_TOKEN (a scoped
+      # access token, NOT the account password) with write access to the
+      # `akonlabs/gitnexus` and `akonlabs/gitnexus-web` repos.
+      - name: Log in to Docker Hub
+        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
      # Computes image tags and labels from the verified semver tag:
      #   v1.2.3        → :1.2.3, :1.2, :1, :latest (auto, only for non-prerelease)
      #   v1.2.3-rc.1   → :1.2.3-rc.1 only (prereleases never become :latest)
@@ -142,7 +173,16 @@ jobs:
        id: meta
        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
        with:
-          images: ghcr.io/${{ github.repository_owner }}/${{ matrix.image.slug }}
+          # Dual-registry publish. metadata-action expands the same tag set
+          # against every image ref listed here, and build-push-action pushes
+          # one build to all of them, so the GHCR and Docker Hub images share
+          # a digest and are byte-identical. The Docker Hub namespace
+          # (`akonlabs`) is hardcoded because it differs from the GitHub org
+          # (`abhigyanpatwari`) — `github.repository_owner` would produce the
+          # wrong ref.
+          images: |
+            ghcr.io/${{ github.repository_owner }}/${{ matrix.image.slug }}
+            docker.io/akonlabs/${{ matrix.image.slug }}
          flavor: latest=auto
          tags: |
            type=semver,pattern={{version}}
@@ -150,20 +190,23 @@ jobs:
            type=semver,pattern={{major}}
            type=raw,value=${{ steps.version.outputs.version }},enable=${{ inputs.tag != '' }}

+      # Transient 502s from GHCR / Docker Hub / GHA cache during multi-platform
+      # exports are retried inside `.github/actions/docker-build-push-retry`
+      # (see docker/build-push-action#1422 — retry policy stays out of the
+      # upstream action). `ignore-error=true` on cache-to avoids cache export
+      # flakes failing an otherwise successful push.
      - name: Build and push
        id: build
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: ./.github/actions/docker-build-push-retry
        with:
          context: .
          file: ${{ matrix.image.dockerfile }}
          platforms: linux/amd64,linux/arm64
-          push: true
+          push: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha,scope=${{ matrix.image.slug }}
-          cache-to: type=gha,mode=max,scope=${{ matrix.image.slug }}
-          provenance: mode=max
-          sbom: true
+          cache-to: type=gha,mode=max,scope=${{ matrix.image.slug }},ignore-error=true

      # Cosign keyless signing. Each pushed tag is signed by the workflow's
      # OIDC identity, so consumers can verify the image with the strict,
@@ -178,6 +221,7 @@ jobs:
      # Do NOT relax to `@.*` — that accepts signatures from any ref, including
      # unprotected branches and PRs, and defeats the supply-chain guarantee.
      - name: Sign image with Cosign (keyless)
+        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
        env:
          # Cosign v2 (installed by sigstore/cosign-installer above) makes
          # keyless the default. COSIGN_EXPERIMENTAL is a v1-only opt-in flag
@@ -193,10 +237,23 @@ jobs:
            [[ -n "$tag" ]] && cosign sign --yes "${tag}@${DIGEST}"
          done <<< "$TAGS"

-      # Attach the SBOM produced by buildx as a verifiable attestation on the digest.
-      - name: Generate build provenance attestation
+      # Attach the SBOM produced by buildx as a verifiable attestation on the
+      # digest. Attestations are pushed as OCI referrers to the registry named
+      # in `subject-name`, so we call the action once per registry. The digest
+      # is identical across registries (same build, same push), so consumers
+      # pulling from either GHCR or Docker Hub see the same provenance.
+      - name: Generate build provenance attestation (GHCR)
+        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
        with:
          subject-name: ghcr.io/${{ github.repository_owner }}/${{ matrix.image.slug }}
          subject-digest: ${{ steps.build.outputs.digest }}
          push-to-registry: true
+
+      - name: Generate build provenance attestation (Docker Hub)
+        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
+        with:
+          subject-name: docker.io/akonlabs/${{ matrix.image.slug }}
+          subject-digest: ${{ steps.build.outputs.digest }}
+          push-to-registry: true
@@ -0,0 +1,45 @@
+name: Gitleaks
+
+# Deterministic in-CI secret scanning. Defense-in-depth on top of GitHub's
+# native secret-scanning push protection (which is a repo Settings toggle —
+# see SECURITY.md for the recommended admin action).
+#
+# PR runs scan the diff (fast); main pushes scan full history.
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Full history needed for the on-push full-history scan; on PRs the
+          # action diffs against the base ref so the cost is bounded by the PR.
+          fetch-depth: 0
+          # Don't bake the token into the cloned .git/config; downstream
+          # steps (and Gitleaks itself) don't need it for repo operations.
+          persist-credentials: false
+
+      # No GITLEAKS_LICENSE secret is required for OSS / public-repo usage.
+      # If this repo becomes private, the action will require a license key.
+      - name: Gitleaks
+        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2.3.9
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_ENABLE_UPLOAD_ARTIFACT: true
+          GITLEAKS_ENABLE_SUMMARY: true
@@ -105,7 +105,7 @@ jobs:
      # Pinned to v7.2.0. Verify SHA via:
      #   gh api repos/release-drafter/release-drafter/git/refs/tags/v7.2.0
      # v7 removed `disable-releaser`; use `dry-run: true` to only autolabel.
-      - uses: release-drafter/release-drafter@5de93583980a40bd78603b6dfdcda5b4df377b32 # v7.2.0
+      - uses: release-drafter/release-drafter@563bf132657a13ded0b01fcb723c5a58cdd824e2 # v7.2.1
        with:
          config-name: release-drafter.yml
          dry-run: true
@@ -33,12 +33,16 @@ jobs:
      id-token: write
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org
-          cache: npm
-          cache-dependency-path: gitnexus/package-lock.json
+          # Hermetic install for the published artifact — no cache carry-over
+          # from non-tag contexts. setup-node v5+ caches by default when a
+          # packageManager field is present in package.json, so the explicit
+          # opt-out is required to clear the zizmor cache-poisoning audit.
+          # ~30s slower per release; runs rarely.
+          package-manager-cache: false
      - name: Build gitnexus-shared
        run: npm install && npm run build
        working-directory: gitnexus-shared
@@ -133,12 +133,15 @@ jobs:
          fetch-depth: 0
          fetch-tags: true

-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org
-          cache: npm
-          cache-dependency-path: gitnexus/package-lock.json
+          # Hermetic install — release-candidate produces shipped artifacts.
+          # setup-node v5+ caches by default when a packageManager field is
+          # present in package.json; explicit opt-out is required to clear
+          # the zizmor cache-poisoning audit. See cache-poisoning audit.
+          package-manager-cache: false

      - name: Build gitnexus-shared
        run: npm install && npm run build
@@ -379,6 +382,10 @@ jobs:
    needs: [guard, publish]
    if: needs.guard.outputs.should_run == 'true' && needs.publish.outputs.vtag != ''
    uses: ./.github/workflows/docker.yml
+    # Reusable workflows do not receive caller secrets unless inherited; without
+    # this, DOCKERHUB_* / GITHUB_TOKEN are empty in docker.yml → "Username and
+    # password required" on Docker Hub login (see same pattern on `ci:` above).
+    secrets: inherit
    permissions:
      contents: read
      packages: write
@@ -0,0 +1,58 @@
+name: Scorecard
+
+# OpenSSF Scorecard supply-chain posture check. Runs weekly + on main push +
+# branch_protection_rule changes. SARIF uploads to the Security tab; the public
+# badge URL resolves once the first scheduled run lands (see README badge wiring).
+
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: '0 7 * * 1'
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      # Needed to upload SARIF results to the Security tab.
+      security-events: write
+      # Needed for the publish_results badge flow (OIDC).
+      id-token: write
+      contents: read
+      actions: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Run Scorecard
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # publish_results enables the public Scorecard badge.
+          publish_results: true
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      - name: Upload to Security tab
+        uses: github/codeql-action/upload-sarif@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3.35.3
+        with:
+          sarif_file: results.sarif
@@ -0,0 +1,73 @@
+name: Trivy Image Scan
+
+# Builds Dockerfile.cli and Dockerfile.web, then scans the resulting images
+# for OS-package and language-package CVEs at HIGH/CRITICAL severity.
+# Findings upload to the Security tab; record-only (does not block merges).
+#
+# NOT triggered on PRs — image builds are slow and base-image CVE churn
+# shouldn't gate feature delivery.
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: '0 8 * * 1'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  scan:
+    name: Trivy (${{ matrix.image.name }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        image:
+          - { dockerfile: Dockerfile.cli, name: gitnexus-cli }
+          - { dockerfile: Dockerfile.web, name: gitnexus-web }
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      - name: Build image (load locally for scan)
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
+        with:
+          context: .
+          file: ${{ matrix.image.dockerfile }}
+          load: true
+          push: false
+          tags: scan-target:${{ matrix.image.name }}
+
+      # aquasecurity/trivy-action versions < 0.35.0 are flagged by
+      # GHSA-69fq-xp46-6x23 (briefly compromised supply chain). Pinned to
+      # v0.36.0 (post-incident clean release) by commit SHA.
+      - name: Run Trivy
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+        with:
+          image-ref: scan-target:${{ matrix.image.name }}
+          format: sarif
+          output: trivy-${{ matrix.image.name }}.sarif
+          severity: HIGH,CRITICAL
+          # Hides CVEs with no available fix in the base image.
+          ignore-unfixed: true
+          exit-code: '0'
+
+      - name: Upload to Security tab
+        uses: github/codeql-action/upload-sarif@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3.35.3
+        with:
+          sarif_file: trivy-${{ matrix.image.name }}.sarif
+          category: trivy-${{ matrix.image.name }}
@@ -0,0 +1,58 @@
+name: Workflow Lint (zizmor)
+
+# Lints .github/workflows/** for known GitHub Actions security misconfigurations:
+# unpinned Actions, dangerous ${{ ... }} interpolation in run: blocks,
+# missing per-job permissions:, etc.
+#
+# Scoped to PRs that touch .github/** only — keeps off the typical PR critical path.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - '.github/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  zizmor:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      security-events: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Install zizmor
+        # Pinned — resolves to whatever's latest on PyPI otherwise.
+        # Bump via Dependabot pip ecosystem (see .github/dependabot.yml).
+        run: pipx install zizmor==1.24.1
+
+      # Initial threshold: medium. High+ findings fail the job; medium findings
+      # appear in the Security tab without blocking. Tune after first run.
+      # Per-rule exemptions for pre-existing intentional patterns live in
+      # .github/zizmor.yml (each carries a documented mitigation).
+      - name: Run zizmor
+        run: zizmor --config .github/zizmor.yml --format sarif --min-severity medium . > zizmor.sarif
+        continue-on-error: true
+
+      - name: Upload SARIF
+        uses: github/codeql-action/upload-sarif@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3.35.3
+        with:
+          sarif_file: zizmor.sarif
+          category: zizmor
+
+      - name: Fail on high+ findings
+        run: zizmor --config .github/zizmor.yml --min-severity high .
@@ -0,0 +1,34 @@
+# zizmor config — pre-existing intentional patterns flagged on initial introduction.
+# Each ignore below has a documented mitigation. Re-evaluate when the source workflow changes.
+#
+# To run zizmor locally with this config:
+#   zizmor --config .github/zizmor.yml .
+
+rules:
+  dangerous-triggers:
+    ignore:
+      # workflow_run is REQUIRED to post sticky comments on fork PRs — the
+      # default-branch privileged token isn't accessible from `pull_request`
+      # on a fork. Mitigated by: read-only `actions:read` + `contents:read`
+      # for artifact download; `pull-requests:write` is the only write scope;
+      # no checkout of fork code occurs. Header comment in the file documents.
+      - ci-report.yml
+
+      # pull_request_target needed by claude-code-action to access secrets
+      # and post review comments on fork PRs. Mitigated by: PR checkouts pin
+      # the fork's HEAD SHA (not the branch ref) to prevent TOCTOU races,
+      # and claude-code-action sandboxes execution. Header comment documents.
+      - claude.yml
+
+      # pull_request_target on the autolabel job needs `pull-requests:write`
+      # to apply labels. Mitigated by: release-drafter runs with `dry-run:
+      # true`, reads only `.github/release-drafter.yml` from the BASE ref,
+      # and the validate-title job (which runs untrusted `pull_request`
+      # context) holds no write permissions. Header comment documents.
+      - pr-labeler.yml
+
+  # Note: cache-poisoning is NOT exempted. The two prior findings in
+  # publish.yml and release-candidate.yml were fixed structurally by
+  # dropping `cache: npm` from those workflows (matches the pattern used
+  # by PyO3/maturin for the same audit). See the commit that added this
+  # file for the rationale.
@@ -106,3 +106,5 @@ local_docs/
 # Local agent scratch / review prompts (never commit)
 .tmp/
 .agents/
+.context/
+gitnexus/web/
@@ -2,6 +2,7 @@ dist/
 coverage/
 gitnexus/vendor/
 gitnexus/test/fixtures/
+gitnexus-web/test/fixtures/
 gitnexus-web/playwright-report/
 gitnexus-web/test-results/
 *.d.ts
@@ -1,7 +1,7 @@
-<!-- version: 1.6.0 -->
-<!-- Last updated: 2026-04-20 -->
+<!-- version: 1.7.0 -->
+<!-- Last updated: 2026-04-23 -->

-Last reviewed: 2026-04-20
+Last reviewed: 2026-04-23

 **Project:** GitNexus · **Environment:** dev · **Maintainer:** repository maintainers (see GitHub)

@@ -40,7 +40,7 @@ Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.

 - **[ARCHITECTURE.md](ARCHITECTURE.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**, **[GUARDRAILS.md](GUARDRAILS.md)**
 - **Call-resolution DAG (legacy path):** See ARCHITECTURE.md § Call-Resolution DAG. Typed 6-stage DAG inside the `parse` phase; language-specific behavior behind `inferImplicitReceiver` / `selectDispatch` hooks on `LanguageProvider`. Shared code in `gitnexus/src/core/ingestion/` must not name languages. Types: `gitnexus/src/core/ingestion/call-types.ts`.
- **Scope-resolution pipeline (RFC #909 Ring 3):** See ARCHITECTURE.md § Scope-Resolution Pipeline. Replaces the legacy DAG for languages in `MIGRATED_LANGUAGES` (currently Python). A language plugs in by implementing `ScopeResolver` (`scope-resolution/contract/scope-resolver.ts`) and registering it in `SCOPE_RESOLVERS`. CI parity gate runs BOTH paths per migrated language on every PR.
+- **Scope-resolution pipeline (RFC #909 Ring 3):** See ARCHITECTURE.md § Scope-Resolution Pipeline. Replaces the legacy DAG for languages in `MIGRATED_LANGUAGES` (see `registry-primary-flag.ts`). A language plugs in by implementing `ScopeResolver` (`scope-resolution/contract/scope-resolver.ts`) and registering it in `SCOPE_RESOLVERS`. CI parity gate runs BOTH paths per migrated language on every PR.
 - **Cursor:** `.cursor/index.mdc` (always-on); `.cursor/rules/*.mdc` (glob-scoped). Legacy `.cursorrules` deprecated.
 - **GitNexus:** skills in `.claude/skills/gitnexus/`; MCP rules in `gitnexus:start` block below.

@@ -48,6 +48,7 @@ Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.

 | Date | Version | Change |
 |------|---------|--------|
+| 2026-04-23 | 1.7.0 | TypeScript added to `MIGRATED_LANGUAGES` (registry-primary call resolution by default). |
 | 2026-04-20 | 1.6.0 | Added scope-resolution pipeline pointer (RFC #909 Ring 3); Python migrated to registry-primary. |
 | 2026-04-19 | 1.5.0 | Cross-repo impact (#794): `impact`/`query`/`context` accept `repo: "@<group>"` + `service`. Removed `group_query`/`group_contracts`/`group_status` MCP tools; added `gitnexus://group/{name}/contracts` and `gitnexus://group/{name}/status` resources. |
 | 2026-04-16 | 1.4.0 | Fixed: web UI description, pre-commit behavior, MCP tools (7->16), added gitnexus-shared, removed stale vite-plugin-wasm gotcha. |
@@ -148,13 +149,14 @@ Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows)
 ## Keeping the Index Fresh

 ```bash
-npx gitnexus analyze              # basic refresh
-npx gitnexus analyze --embeddings # preserve embeddings
+npx gitnexus analyze                 # basic refresh; preserves any existing embeddings
+npx gitnexus analyze --embeddings    # also generate embeddings for new/changed nodes
+npx gitnexus analyze --drop-embeddings  # explicit opt-in to wipe existing embeddings
 ```

-Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). Running without `--embeddings` deletes existing vectors.
+Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). A plain `analyze` no longer drops existing vectors — pass `--drop-embeddings` to wipe.

-> Claude Code: PostToolUse hook handles this after `git commit` and `git merge`.
+> Claude Code: PostToolUse hook detects a stale index after `git commit` and `git merge` and prompts the agent to run `analyze`. The hook does not invoke `analyze` itself.

 ## CLI Skills

@@ -215,10 +215,52 @@ Both hooks are optional on `LanguageProvider`. Ruby is the only current implemen
 The Call-Resolution DAG is the **legacy path**. RFC #909 Ring 3 introduces a parallel **scope-resolution pipeline** (next section) that replaces stages 1–6 with a scope-indexed registry lookup. Both paths ship side-by-side and are gated per-language via `MIGRATED_LANGUAGES` + the `REGISTRY_PRIMARY_<LANG>` env var.

 - **Unmigrated language** → Call-Resolution DAG runs; scope-resolution phase is a no-op.
- **Migrated language** (currently: Python) → scope-resolution owns CALLS/ACCESSES/USES emission; the legacy DAG gates off for that language via `isRegistryPrimary(lang)` checks in `call-processor.ts` and `import-processor.ts`.
+- **Migrated language** (currently: Python, C#) → scope-resolution owns CALLS/ACCESSES/USES emission; the legacy DAG gates off for that language via `isRegistryPrimary(lang)` checks in `call-processor.ts` and `import-processor.ts`.
 - `import-processor` still populates `importMap` for migrated languages — heritage's `ctx.resolve` reads it to disambiguate parent classes. Only edge emission is gated.
 - CI runs BOTH paths for every migrated language on every PR (`.github/workflows/ci-scope-parity.yml`); both must pass.

+#### Same-graph guarantee
+
+Edges emitted by the scope-resolution pipeline and edges emitted by the legacy DAG are indistinguishable to downstream consumers (MCP tools, HTTP API, embeddings, group bridge):
+
+- **Node identity** — both paths use `generateId(...)` from `lib/utils.ts`, the same qualified-name keyspace, and the same node labels (`File`, `Folder`, `Class`, `Method`, `Function`, …). Overload disambiguation suffixes `parameterTypes` into the id consistently — see `scope-resolution/graph-bridge/ids.ts` and the legacy emitter in `call-processor.ts`.
+- **Edge vocabulary** — both paths emit the same reasons: `'import-resolved' | 'global' | 'local-call' | 'same-file' | 'interface-dispatch' | 'read' | 'write'`. Migrating a language must not change which reasons consumers see for previously-resolved edges.
+- **Confidence tier** — both paths attach a numeric `confidence` to each edge using the same scale.
+
+The CI parity workflow (`.github/workflows/ci-scope-parity.yml`) runs both paths against every migrated language's fixture corpus and fails on any divergence.
+
+#### Semantic-model source of truth
+
+Two independent invariants.
+
+**ParsedFile = the AST-level truth.** `ParsedFile` (`gitnexus-shared/src/scope-resolution/parsed-file.ts`) is the single per-file artifact both resolution paths consume. Scope-resolution passes MUST NOT build a parallel parse representation. If a per-language hook needs AST-level facts that `ParsedFile` doesn't expose, it should reuse the orchestrator's `treeCache` (`RunScopeResolutionInput.treeCache`) rather than re-invoking `parser.parse(...)` on its own — the C# `populateNamespaceSiblings` hook is the reference implementation of this pattern.
+
+**SemanticModel = the symbol-level truth.** `SemanticModel` (`gitnexus/src/core/ingestion/model/semantic-model.ts`) is the authoritative store for every symbol-indexed lookup (by `nodeId`, `simpleName`, `qualifiedName`, or `filePath`). Both paths read from here:
+
+- Legacy Call-Resolution DAG → `call-processor` Tier 1/2/3 via `model.symbols.lookupExactAll`, `model.methods.lookupMethodByName`, `model.types.lookupClassByName`, `lookupMethodByOwnerWithMRO`.
+- Scope-resolution pipeline → `findOwnedMember`, `pickOverload`, `findExportedDefByName` all consult `model.methods` / `model.fields` / `model.symbols`.
+
+The scope-resolution pipeline additionally carries `WorkspaceResolutionIndex` for `Scope`-valued lookups (`classScopeByDefId`, `moduleScopeByFile`) that `SemanticModel` structurally cannot hold. No symbol-indexed duplicates exist outside `SemanticModel`.
+
+**Write / read phase contract.** The model is mutable during three ordered phases and read-only afterward:
+
+```
+ Phase 1: legacy parse     ──► symbolTable.add fans into types/methods/fields
+ Phase 2: scope-resolution ──► reconcileOwnership() registers corrected ownerIds
+ Phase 3: finalize         ──► model.attachScopeIndexes(bundle) — one-shot freeze
+ ─────────────────────────── phase boundary ───────────────────────────
+ Read phase: all resolution passes + MCP + HTTP + embeddings see
+             SemanticModel (read-only handle); writes are type-errors.
+```
+
+`runScopeResolution` narrows `MutableSemanticModel` → `SemanticModel` at the phase boundary so downstream passes physically cannot mutate the model even accidentally.
+
+**Transitional: reconciliation pass.** `reconcileOwnership` (`scope-resolution/pipeline/reconcile-ownership.ts`) is a shim for languages whose legacy extractor doesn't resolve `enclosingClassId` at parse time (Python class-body methods are the canonical case). It walks `parsed.localDefs[i].ownerId` after `populateOwners` and registers any missed methods/fields into the model. Idempotent — safe to re-run, safe alongside languages whose legacy extractor already carries `ownerId` (C#).
+
+The architectural end state is for every language's parse-time extractor to emit the correct `ownerId` directly, making reconciliation a no-op (tracked as a follow-up refactor). The dev-mode validator `validateOwnershipParity` surfaces any drift via `onWarn` under `NODE_ENV !== 'production' && VALIDATE_SEMANTIC_MODEL !== '0'`.
+
+References: `semantic-model.ts` file-head (full write/read contract); `contract/scope-resolver.ts` Contract Invariant I9 (scope-resolution-side rule).
+
 ---

 ## Scope-Resolution Pipeline (RFC #909 Ring 3)
@@ -260,6 +302,11 @@ Single interface a language implements to plug into the pipeline. Contract fully
 | `arityCompatibility` | Provider consumed by registry during `MethodRegistry.lookup` Step 2 |
 | `importEdgeReason` | Confidence-tier string for IMPORTS edge reason field |
 | `propagatesReturnTypesAcrossImports?` | Opt out of cross-file return-type propagation (default on) |
+| `fieldFallbackOnMethodLookup?` | Statically-typed languages turn this OFF — the heuristic over-connects (default on) |
+| `unwrapCollectionAccessor?` | Property-style collection views (`data.Values` on Dictionary-like receivers) — default off |
+| `collapseMemberCallsByCallerTarget?` | One CALLS edge per (caller, target) instead of per-site — default off |
+| `populateNamespaceSiblings?` | Cross-file implicit visibility (compiler-implicit namespace sharing) — default off; ctx carries `treeCache` |
+| `hoistTypeBindingsToModule?` | Walk up to Module scope when looking up a method's return-type typeBinding — default off; enable only when bindings are stored at module level |

 ### Per-language registration

@@ -284,12 +331,16 @@ CI auto-discovers the set via `tsx`. No workflow edit required.
 | `registry-primary-flag.ts` | `MIGRATED_LANGUAGES` set + `isRegistryPrimary(lang)` |
 | `languages/python/index.ts` | Python `ScopeResolver` hooks + known-limitation docs |
 | `languages/python/captures.ts` | `emitPythonScopeCaptures` (honors cross-phase Tree cache) |
+| `languages/csharp/index.ts` | C# `ScopeResolver` hooks + known-limitation docs |
+| `languages/csharp/captures.ts` | `emitCsharpScopeCaptures` (honors cross-phase Tree cache) |
+| `languages/csharp/namespace-siblings.ts` | Cross-file implicit-namespace visibility hook (reads `treeCache`) |

 ### Performance notes

 - **Cross-phase Tree cache**: parse phase writes Trees into `scopeTreeCache` (separate from the chunk-local `astCache`) ONLY for languages with `emitScopeCaptures`. Scope-resolution reads from it to skip the second parse. Cleared at end of the phase. Workers leave the cache empty — Trees can't cross MessageChannels; cache miss = fresh parse. `PROF_SCOPE_RESOLUTION=1` emits hit/miss counters and a worker-engaged warning.
 - **Typed relationship iteration**: heritage + MRO walk only the EXTENDS / IMPLEMENTS / HAS_METHOD edges via `iterRelationshipsByType`, not the full relationship map.
 - **Workspace-resolution-index**: O(1) `findOwnedMember` / `findExportedDef` / `classScopeByDefId` built once per run.
+- **SCC-ordered cross-file return-type propagation** (PR #1050): `propagateImportedReturnTypes` walks `indexes.sccs` in reverse-topological order (leaves first), so multi-hop alias chains like `models.User → service.user → app.user` collapse to the terminal class in a single linear pass. Within each importer, the source module's `typeBindings` is chain-followed BEFORE mirroring (so we mirror terminal types, not intermediate refs), and the importer's own `typeBindings` is chain-followed AFTER mirroring (so local `const x = importedFn()` resolves before downstream importers run). Cyclic SCCs reach a partial fixpoint within a single pass without iterating to convergence — see the `ts-circular` cross-file-binding fixture which only asserts pipeline-no-throw. PROF output (`PROF_SCOPE_RESOLUTION=1`) splits `finalize` from `propagate` so quadratic regressions in the chain-follow surface independently.

 ---

@@ -129,9 +129,10 @@ Two publish workflows ship `gitnexus` to npm:
    registry. First rc for a given base is `rc.1`.
  - After the npm publish succeeds, the workflow calls `docker.yml` as a
    reusable workflow to build and push the corresponding RC Docker images
-    (e.g. `ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1`). The images are
-    signed with Cosign; the OIDC identity is `docker.yml@refs/heads/main`
-    (the caller's ref — see README.md § Docker for the verify command).
+    (e.g. `ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1`, mirrored to
+    `docker.io/akonlabs/gitnexus:1.7.0-rc.1`). The images are signed
+    with Cosign; the OIDC identity is `docker.yml@refs/heads/main` (the
+    caller's ref — see README.md § Docker for the verify command).

  Idempotency: the workflow pushes an `rc/<HEAD_SHA>` marker tag and a
  `v<RC>` release tag **atomically, before** calling `npm publish`. The guard
@@ -0,0 +1,209 @@
+# Definition of Done — GitNexus
+
+Last reviewed: 2026-04-23 · Version: 2.0.0
+
+This document defines the repo-wide completion bar for production-ready changes in GitNexus. It is the stable baseline. Implementation prompts, agent behavior, and review workflows may add task-specific checks, but they must never weaken this bar.
+
+Use it together with:
+
+- `AGENTS.md` — agent-facing rules of engagement
+- `GUARDRAILS.md` — hard safety constraints
+- `CONTRIBUTING.md` — contributor workflow
+- `TESTING.md` — test strategy and coverage expectations
+- `ARCHITECTURE.md` — pipeline boundaries, Call-Resolution DAG, LanguageProvider contract
+
+## 1. Scope and Intent
+
+A change is **Done** when it is correct, safely integrated, appropriately tested, operationally sound, and a net improvement to the codebase — not merely "the code compiles and a test passes."
+
+This DoD applies to:
+
+- CLI, MCP, and HTTP-bridge behavior in `gitnexus/`
+- Browser UI in `gitnexus-web/`
+- Shared contracts in `gitnexus-shared/`
+- CI workflows, release pipelines, and repo-level docs
+
+Out of scope: full agent personas, step-by-step implementation prompts, verbose review formatting rules, repo walkthroughs already covered elsewhere, temporary task-specific acceptance criteria. Those belong in prompts, PR templates, or other repo docs.
+
+## 2. Core Definition of Done
+
+Every change must satisfy **every relevant item** below. If an item does not apply, say so explicitly in the PR description.
+
+### 2.1 Correctness and Completeness
+
+- [ ] The requested behavior is implemented end-to-end in the **real runtime path** for the affected surface — no dead code, partial wiring, test-only shims, or "works in isolation but not in production" seams.
+- [ ] Edge cases relevant to the changed surface are handled or explicitly documented as out of scope.
+- [ ] Error handling is proportionate: inputs at system boundaries (user input, external APIs, filesystem, process spawn) are validated; internal, framework-guaranteed paths are trusted.
+- [ ] The change produces the same result on re-run (idempotent where expected) and does not rely on accidental ordering.
+
+### 2.2 Architecture and Placement
+
+- [ ] The change is placed in the correct package and layer:
+  - `gitnexus/` for CLI, MCP, HTTP bridge, ingestion, graph, and runtime logic
+  - `gitnexus-web/` for browser UI (thin client — no WASM workers, all queries via HTTP API)
+  - `gitnexus-shared/` for shared contracts, types, and constants
+- [ ] Pipeline and architecture boundaries remain explicit. Shared ingestion code in `gitnexus/src/core/ingestion/` must not name languages — use `LanguageProvider` hooks (see `AGENTS.md` and `ARCHITECTURE.md` § Call-Resolution DAG).
+- [ ] No hidden cross-phase coupling; no leaking of language-specific logic into shared infrastructure without a documented architectural reason.
+- [ ] Runtime and graph behavior are consistent — the real source of truth is fixed at the source, not symptom-patched in a downstream layer.
+- [ ] Direct imports from `gitnexus-shared` are used. No barrel re-exports introduced to paper over drift between packages.
+
+### 2.3 Design and Readability
+
+- [ ] The implementation is the **smallest correct solution** for the requirement. No speculative abstraction, unnecessary indirection, clever but hard-to-follow control flow, or unrelated cleanup.
+- [ ] Naming, control flow, ownership, and extension points are clear enough that the next contributor can extend the code without archaeology.
+- [ ] Comments are minimal and useful — they explain intent, invariants, contracts, or non-obvious constraints. No stale comments, placeholder comments, narrated code, commented-out code, or "what" comments where a good name would do.
+- [ ] No copy-paste duplication created for convenience; no premature deduplication of three similar lines.
+
+### 2.4 Contracts and Compatibility
+
+- [ ] Existing contracts (types in `gitnexus-shared/`, CLI flags, MCP tools/resources, HTTP routes, graph node/edge shapes, persisted IDs) are preserved unless the task explicitly requires a contract change.
+- [ ] Any contract change is intentional, explicit, and reflected in **every direct consumer** in the same change, with types aligned end-to-end.
+- [ ] Persisted data changes (graph schema, IDs, embeddings) are backward-compatible or accompanied by a documented migration / reindex path.
+- [ ] If user-visible behavior, public usage, CLI help, or README examples change, the relevant docs, examples, help text, or migration notes are updated in the same change.
+
+### 2.5 Security
+
+- [ ] No new injection surfaces (command, path, SQL/Cypher-style, prompt) introduced on paths that consume untrusted input.
+- [ ] No secrets, tokens, or credentials committed to the repo, to logs, or to error messages.
+- [ ] Filesystem access honors the repo-scope and indexed-repo boundaries documented in `AGENTS.md` and `GUARDRAILS.md`.
+- [ ] Third-party dependencies added or bumped are justified, from reputable sources, and do not regress the supply-chain posture.
+
+### 2.6 Performance and Resource Use
+
+- [ ] No repeated avoidable work, unnecessary scans, unnecessary round-trips, unbounded caches, or obvious hot-path regressions.
+- [ ] Tree-sitter buffer sizing follows the adaptive 512KB–32MB convention (`getTreeSitterBufferSize`) — do not hard-code new buffer sizes.
+- [ ] Memory and handle lifecycles are explicit: database handles (LadybugDB) close cleanly, no dangling process watchers, no leaked tree-sitter parsers.
+- [ ] Long-running or large-graph paths remain bounded or are measurably streamed; degradation on large real repos is considered, not assumed benign.
+
+### 2.7 Tests
+
+- [ ] Tests cover the **real changed path** — they would fail if behavior, wiring, or contracts were broken, not only if a mock were misconfigured.
+- [ ] Integration tests hit a real database where the production path does; do not introduce mocks that hide migration or schema drift.
+- [ ] Assertions are meaningful. Use `toBe` / `toEqual` for exact expectations; avoid `toBeGreaterThanOrEqual` and other bounds-only assertions that mask regressions.
+- [ ] Fixtures are realistic enough for the risk of the change — a one-file fixture is not sufficient for a pipeline-wide behavior change.
+- [ ] New tests are deterministic and do not depend on network, clock, or host-specific paths without explicit isolation.
+
+### 2.8 Observability and Operability
+
+- [ ] Errors surfaced to users or callers are actionable: they name what failed, what input was involved (without leaking secrets), and how to recover where possible.
+- [ ] Logging is proportionate — no noisy debug logs left in hot paths, no silent catches that swallow diagnostics.
+- [ ] CLI exit codes and MCP tool responses are correct for each outcome (success, user error, internal error).
+- [ ] Progress reporting (`PipelineProgress` and similar shared contracts) remains accurate after the change.
+
+### 2.9 Reversibility and Risk
+
+- [ ] The change has a clear rollback story: revert is safe, or migration is accompanied by a documented rollback / reindex procedure.
+- [ ] Residual risks, compatibility impacts, and operational concerns are either resolved or **clearly stated** in the PR description.
+- [ ] Destructive or hard-to-reverse operations (graph rebuild, schema change, `git` state manipulation) are opt-in or guarded.
+
+## 3. Agent-Assisted Workflow Guardrails
+
+When the change is produced with or reviewed by an AI agent, the following additional gates apply:
+
+- [ ] **Scope match.** The final diff matches the intended symbols, files, and processes — no speculative refactors, unrelated formatting churn, or collateral edits outside the task scope.
+- [ ] **Evidence-based edits.** Claims about repo state are verified against the current code, not trusted from memory or stale documentation.
+- [ ] **Impact analysis.** Where GitNexus graph tooling is available and relevant, impact of non-trivial symbol, contract, or runtime-path changes is checked **before** editing.
+- [ ] **Embeddings preserved.** If an indexed repo already has embeddings and re-analysis is required, embeddings are preserved — not accidentally dropped by a destructive reindex.
+- [ ] **No false-done.** "Done" is claimed only after the Validation Baseline below has been run or any gap is explicitly named. Green tests on an unrelated path do not constitute validation.
+- [ ] **Five-axis self-review** before handing off: correctness, readability, architecture, security, performance.
+
+## 4. Validation Baseline
+
+Run the commands relevant to the touched area. If something cannot be run in the current environment, state it explicitly in the handoff.
+
+### 4.1 Build ordering
+
+- [ ] `gitnexus-shared/` dist is built before consuming packages are typechecked or tested (CI uses the `setup-gitnexus` action for this — local runs must match).
+
+### 4.2 If `gitnexus/` changed
+
+- [ ] `cd gitnexus && npx tsc --noEmit`
+- [ ] `cd gitnexus && npm test`
+- [ ] `cd gitnexus && npx prettier --check .` for files in the diff (pre-commit runs the affected-tests subset; do not expand scope)
+
+### 4.3 If `gitnexus-web/` changed
+
+- [ ] `cd gitnexus-web && npx tsc -b --noEmit`
+- [ ] `cd gitnexus-web && npm test`
+- [ ] `cd gitnexus-web && npm run test:e2e` when browser flows or user-facing UI behavior changed
+
+### 4.4 If `gitnexus-shared/` changed
+
+- [ ] Shared package builds cleanly (`npm run build` in `gitnexus-shared/`)
+- [ ] Dependent packages still typecheck and test after the shared change — verify both CLI and web consumers together
+
+### 4.5 If CI workflows or release pipelines changed
+
+- [ ] The workflow passes a dry-run or triggered run before merge; concurrency (`cancel-in-progress`) and the `setup-gitnexus` action remain wired correctly.
+- [ ] `CHANGELOG.md` is **not** edited here — it is owned by the release process.
+
+## 5. Review Gates
+
+A reviewer (human or agent) should be able to answer **yes** to each of the following before approving:
+
+1. **Correctness** — Does the change do what it claims on the real runtime path?
+2. **Readability** — Will the next contributor understand this in six months without asking?
+3. **Architecture** — Is it in the right package, layer, and phase? Are boundaries respected?
+4. **Security** — No new injection, leak, or trust-boundary violation?
+5. **Performance** — No obvious regression on realistic inputs?
+6. **Tests** — Would a regression in the changed behavior fail loudly?
+7. **Scope** — Does the diff match the intended change, with no unrelated churn?
+
+## 6. "Not Done" Signals
+
+A change is **not** Done if any of the following is true, even if CI is green:
+
+- The runtime path is not actually exercised by the tests.
+- A contract drifted between `gitnexus/`, `gitnexus-web/`, and `gitnexus-shared/` and only one side was updated.
+- A language-specific concern leaked into shared ingestion code.
+- The diff contains unrelated reformatting, refactors, or cleanup beyond the stated task.
+- Logs, comments, or TODOs were added as placeholders for work not done.
+- The change depends on a manual step that is not documented.
+- `CHANGELOG.md` was edited during PR work.
+- Pre-commit, prettier, or typecheck was bypassed without explicit justification.
+
+## 7. Task-Specific DoD Template
+
+Use this in implementation and review prompts. Keep it short and tailor it to the actual change:
+
+```md
+# Definition of Done for this implementation
+
+- [ ] Runtime wiring is complete for the affected path.
+- [ ] Requested behavior is correct and relevant contracts are preserved or explicitly updated.
+- [ ] The design stays scoped, readable, and proportionate to the task.
+- [ ] Tests prove the changed behavior and catch broken wiring.
+- [ ] Required validation for touched packages has been run, or any gap is explicitly noted.
+- [ ] Repo boundaries, security, performance, and operational safety are respected.
+- [ ] The diff contains only the intended change — no unrelated churn.
+```
+
+## 8. How to Use This File in Claude Review
+
+Reference this file as the repo-wide completion bar. Add a task-specific review instruction such as:
+
+```md
+Review this change against `DoD.md` and the repo docs (`AGENTS.md`, `GUARDRAILS.md`,
+`CONTRIBUTING.md`, `TESTING.md`, `ARCHITECTURE.md`). Treat `DoD.md` as the minimum
+bar for production readiness. Flag anything that is partially wired, contract-unsafe,
+under-tested, architecturally misplaced, scope-creeping, or harder to maintain than
+necessary. Apply the five-axis review gate: correctness, readability, architecture,
+security, performance.
+```
+
+## 9. Evolution
+
+This DoD is living. Revisit it when:
+
+- A class of incident slips past it (add a gate).
+- A gate becomes consistently ceremonial without catching issues (remove or merge it).
+- The architecture evolves in a way that changes what "done" means (update placement, validation, or contracts sections).
+
+Track material updates in the changelog below. Keep the file tight — if it grows past a single read-in-one-sitting, something has drifted into the wrong place.
+
+## Changelog
+
+| Date       | Version | Change                                                                                                                                                        |
+| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2026-04-23 | 2.0.0   | Restructured into numbered sections; added Security, Observability, Reversibility, Agent-Assisted Guardrails, Review Gates, Not-Done Signals; expanded validation baseline (shared-first build, prettier, CI workflow checks). |
+| 2026-04-13 | 1.0.0   | Initial repo-wide Definition of Done.                                                                                                                         |
@@ -19,7 +19,7 @@ Maintainer may widen scope per task.
 2. **Never rename with find-and-replace** in GitNexus-indexed projects — use `rename` MCP tool with `dry_run: true` first, review `graph` vs `text_search` edits. No separate `gitnexus rename` CLI exists.
 3. **Run impact analysis before editing shared symbols** — `impact` (upstream) for functions/classes/methods others call. Do not ignore HIGH/CRITICAL without maintainer sign-off.
 4. **Run `detect_changes` before commit** — confirm diffs map to expected symbols/processes when the graph is available.
-5. **Preserve embeddings** — if `.gitnexus/meta.json` shows embeddings, use `npx gitnexus analyze --embeddings`; plain `analyze` drops them.
+5. **Preserve embeddings** — plain `npx gitnexus analyze` now preserves any embeddings recorded in `.gitnexus/meta.json` (the previous behavior wiped them). Use `--embeddings` to also generate vectors for new/changed nodes; use `--drop-embeddings` only when an explicit wipe is intended (e.g., model swap).

 ---

@@ -36,8 +36,8 @@ Format: **Trigger → Instruction → Reason**. Append new Signs when the same m
 ### Embeddings vanished after analyze

 - **Trigger:** Semantic search quality drops; `stats.embeddings` in `meta.json` is 0 after refresh.
- **Do:** `npx gitnexus analyze --embeddings`, confirm `meta.json` reflects stored embeddings.
- **Why:** Embedding generation is opt-in; analyze without the flag does not preserve prior vectors.
+- **Do:** Re-run `npx gitnexus analyze --embeddings` to regenerate. Check the analyze log for a `Warning: could not load cached embeddings` line — if present, the cache restore failed (corrupt DB / schema mismatch) and the rebuild had nothing to preserve. If you intentionally passed `--drop-embeddings`, this is expected.
+- **Why:** Plain `analyze` preserves prior vectors by re-inserting them after the rebuild; the only ways to end up at zero are an explicit `--drop-embeddings`, a cache-load failure (now logged), or a model/dimension change that invalidates the cache.

 ### MCP lists no repos

@@ -1,5 +1,5 @@
 # GitNexus
-⚠️ Important Notice:** GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is **not affiliated with, endorsed by, or created by** this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus.
+**⚠️ Important Notice:** GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is **not affiliated with, endorsed by, or created by** this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus.

 <div align="center">

@@ -18,6 +18,9 @@
  <a href="https://polyformproject.org/licenses/noncommercial/1.0.0/">
    <img src="https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg" alt="License: PolyForm Noncommercial"/>
  </a>
+  <a href="https://securityscorecards.dev/viewer/?uri=github.com/abhigyanpatwari/GitNexus">
+    <img src="https://api.securityscorecards.dev/projects/github.com/abhigyanpatwari/GitNexus/badge" alt="OpenSSF Scorecard"/>
+  </a>

  <p><strong>Enterprise (SaaS & Self-hosted)</strong> - <a href="https://akonlabs.com">akonlabs.com</a></p>

@@ -36,7 +39,7 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72

 > *Like DeepWiki, but deeper.* DeepWiki helps you *understand* code. GitNexus lets you *analyze* it — because a knowledge graph tracks every relationship, not just descriptions.

-**TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with goliath models.
+**TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with Goliath models.

 ---

@@ -120,7 +123,7 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 | **Windsurf**    | Yes | —     | —                   | MCP            |
 | **OpenCode**    | Yes | Yes    | —                   | MCP + Skills   |

-> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that auto-reindex after commits.
+> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.

 ## Community Integrations

@@ -197,6 +200,7 @@ gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexu
 gitnexus analyze --skip-git        # Index folders that are not Git repositories
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
+gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI connection
 gitnexus list                    # List all indexed repositories
@@ -208,16 +212,18 @@ gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-m
 gitnexus wiki --base-url <url>   # Wiki with custom LLM API base URL

 # Repository groups (multi-repo / monorepo service tracking)
-gitnexus group create <name>     # Create a repository group
-gitnexus group add <name> <repo> # Add a repo to a group
-gitnexus group remove <name> <repo> # Remove a repo from a group
-gitnexus group list [name]       # List groups, or show one group's config
-gitnexus group sync <name>       # Extract contracts and match across repos/services
+gitnexus group create <name>                                   # Create a repository group
+gitnexus group add <group> <groupPath> <registryName>          # Add a repo to a group. <groupPath> is a hierarchy path (e.g. hr/hiring/backend); <registryName> is the repo's name from the registry (see `gitnexus list`)
+gitnexus group remove <group> <groupPath>                      # Remove a repo from a group by its hierarchy path
+gitnexus group list [name]                                     # List groups, or show one group's config
+gitnexus group sync <name>                                     # Extract contracts and match across repos/services
 gitnexus group contracts <name>  # Inspect extracted contracts and cross-links
 gitnexus group query <name> <q>  # Search execution flows across all repos in a group
 gitnexus group status <name>     # Check staleness of repos in a group
 ```

+If `analyze` reports a worker parse timeout on a large or unusual repository, it keeps running and falls back safely. To give slow worker jobs more time, use `gitnexus analyze --worker-timeout 60` or set `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000`. For very large files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget.
+
 ### What Your AI Agent Gets

 **16 tools** exposed via MCP (11 per-repo + 5 group):
@@ -321,29 +327,31 @@ flowchart TD

 ## Web UI (browser-based)

-A fully client-side graph explorer and AI chat. No server, no install — your code never leaves the browser.
+A client-side graph explorer and AI chat — your code never leaves your machine.

-**Try it now:** [gitnexus.vercel.app](https://gitnexus.vercel.app) — drag & drop a ZIP and start exploring.
+**Try it now:** [gitnexus.vercel.app](https://gitnexus.vercel.app) — run `npx gitnexus@latest serve` locally and the page auto-connects to your local backend.

 <img width="2550" height="1343" alt="gitnexus_img" src="https://github.com/user-attachments/assets/cc5d637d-e0e5-48e6-93ff-5bcfdb929285" />

-Or run locally:
+Or run the frontend locally:

 ```bash
 git clone https://github.com/abhigyanpatwari/gitnexus.git
 cd gitnexus/gitnexus-shared && npm install && npm run build
 cd ../gitnexus-web && npm install
 npm run dev
+# Then in another terminal, start the backend the frontend connects to:
+npx gitnexus@latest serve
 ```

 ## Docker

-The official Docker setup ships **two signed images** orchestrated by `docker-compose.yaml`:
+The official Docker setup ships **two signed images** orchestrated by `docker-compose.yaml`. Each image is published to both **GitHub Container Registry** (GHCR) and **Docker Hub** — same build, same digest, same Cosign signature — so pick whichever registry you prefer:

-| Image                                              | Purpose                                                                |
-| -------------------------------------------------- | ---------------------------------------------------------------------- |
-| `ghcr.io/abhigyanpatwari/gitnexus:latest`          | CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) |
-| `ghcr.io/abhigyanpatwari/gitnexus-web:latest`      | Static web UI (port `4173`)                                            |
+| Purpose                                                                | GHCR (default in `docker-compose.yaml`)       | Docker Hub mirror                           |
+| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- |
+| CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) | `ghcr.io/abhigyanpatwari/gitnexus:latest`     | `akonlabs/gitnexus:latest`                  |
+| Static web UI (port `4173`)                                            | `ghcr.io/abhigyanpatwari/gitnexus-web:latest` | `akonlabs/gitnexus-web:latest`              |

 > **Heads-up — image rename.** Earlier releases published the web UI under
 > `ghcr.io/abhigyanpatwari/gitnexus`. Starting with the introduction of the
@@ -404,8 +412,11 @@ The Docker images are version-locked to the npm package:
 - Stable images are **only published from `vX.Y.Z` git tags** (via `docker.yml`
  triggered directly by the tag push), and the workflow refuses to build unless
  the tag exactly matches `gitnexus/package.json`'s version. So
-  `ghcr.io/abhigyanpatwari/gitnexus:1.6.2` is byte-for-byte the same release
-  as `npm install gitnexus@1.6.2` — no drift, no floating builds from `main`.
+  `ghcr.io/abhigyanpatwari/gitnexus:1.6.2` (and its Docker Hub mirror
+  `akonlabs/gitnexus:1.6.2`) is byte-for-byte the same release as
+  `npm install gitnexus@1.6.2` — no drift, no floating builds from `main`.
+  Both registries receive the same digest from a single build step, so you can
+  pull from either and the signature verifies identically.
 - Release-candidate images (e.g. `:1.7.0-rc.1`) are published alongside each
  RC npm release. They are built by `release-candidate.yml` calling `docker.yml`
  as a reusable workflow after the RC tag is created and pushed.
@@ -426,11 +437,18 @@ sensitive environments:
 cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+
+# Same signature verifies the Docker Hub mirror (identical digest):
+cosign verify docker.io/akonlabs/gitnexus:1.6.2 \
+  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
 ```

 The regex pins the certificate identity to this repo's `docker.yml` workflow
 **run from a `v*` tag** — rejecting unsigned images, images signed by other
-workflows, and images signed from unprotected refs.
+workflows, and images signed from unprotected refs. It is identical for both
+registries because both sets of tags were signed at the same digest in one
+workflow run.

 **Release candidates** — signed from `refs/heads/main` (the caller's ref when
 `release-candidate.yml` invokes `docker.yml` as a reusable workflow):
@@ -0,0 +1,67 @@
+# Security Policy
+
+## Supported Versions
+
+GitNexus is developed on `main`. Security fixes are applied to the latest released minor on npm (`gitnexus`) and to the published Docker images (`Dockerfile.cli`, `Dockerfile.web`). Older minors are not back-patched.
+
+## Reporting a Vulnerability
+
+**Please do not open a public GitHub issue for security reports.**
+
+Use **GitHub Private Vulnerability Reporting** for this repository:
+
+→ https://github.com/abhigyanpatwari/GitNexus/security/advisories/new
+
+Please include:
+
+- A description of the issue and its potential impact
+- Steps to reproduce (a minimal repro repo or commit hash if possible)
+- The affected version(s) — `npm view gitnexus version`, image digest, or commit SHA
+- Any suggested mitigation
+
+### What to expect
+
+- **Acknowledgement:** best-effort within 5 business days, subject to maintainer capacity.
+- **Triage:** we will confirm whether the report is in scope, request clarifications if needed, and propose a fix timeline.
+- **Disclosure:** coordinated. We will agree on a disclosure date with you before publishing an advisory.
+
+### Scope
+
+In scope:
+
+- The `gitnexus` CLI and MCP server (`gitnexus/`)
+- The `gitnexus-web` thin client (`gitnexus-web/`)
+- The `gitnexus-shared` types package (`gitnexus-shared/`)
+- The published Docker images (`Dockerfile.cli`, `Dockerfile.web`)
+- GitHub Actions workflows in `.github/workflows/`
+
+Out of scope:
+
+- Vulnerabilities in third-party dependencies that we have no influence over (please report upstream; if a viable mitigation exists at the GitNexus layer, that's in scope).
+- Issues requiring physical access to a developer machine or a compromised local environment.
+- Theoretical attacks without a practical exploit against a default GitNexus deployment.
+
+## Recommended Hardening for Forks and Self-Hosted Deployments
+
+If you fork GitNexus or self-host it, we recommend enabling the following in your repository's **Settings → Code security and analysis**:
+
+- **Private vulnerability reporting** — the channel described above.
+- **Dependabot alerts** — alerts on advisories affecting your dependencies.
+- **Dependabot security updates** — automated PRs for security patches (this repo's `.github/dependabot.yml` already covers version updates).
+- **Secret scanning** and **Push protection** — blocks pushes that introduce known secret patterns. Defense-in-depth on top of the in-CI Gitleaks scan documented below.
+- **Code scanning** — surfaces SARIF results from CodeQL, Trivy, Scorecard, and zizmor in one place.
+
+## Automated Scans Running in CI
+
+This repository runs the following scans automatically. Findings appear under the repository's **Security → Code scanning** tab.
+
+| Scan | Tool | Trigger | Action on finding |
+|------|------|---------|-------------------|
+| Static analysis (JS/TS, Python) | [CodeQL](https://github.com/github/codeql-action) | PR, `main` push, weekly | Advisory (Security tab) |
+| Dependency vulnerabilities (PR diff) | [`dependency-review-action`](https://github.com/actions/dependency-review-action) | PR | **Blocks PR** at `high+` severity |
+| Secret scanning | [Gitleaks](https://github.com/gitleaks/gitleaks-action) | PR, `main` push | **Blocks PR** on default rules |
+| Supply-chain posture | [OpenSSF Scorecard](https://github.com/ossf/scorecard-action) | Weekly, `main` push | Advisory (Security tab + public badge) |
+| Workflow lint | [zizmor](https://github.com/woodruffw/zizmor) | PR (touching `.github/**`) | **Blocks PR** at `high+` severity |
+| Container image scan | [Trivy](https://github.com/aquasecurity/trivy-action) | Weekly, `main` push | Advisory (Security tab) |
+
+Dependency version updates are managed separately by Dependabot — see `.github/dependabot.yml`.
@@ -36,12 +36,24 @@ kind: ClusterImagePolicy
 metadata:
  name: gitnexus-signed-images
 spec:
-  # Apply to both published GitNexus images on GHCR. Image references always
-  # carry a tag or digest at admission time, so these two globs cover every
-  # `gitnexus:<tag>`, `gitnexus@sha256:...`, `gitnexus-web:<tag>`, and
-  # `gitnexus-web@sha256:...` reference.
+  # Apply to both published GitNexus images on both registries. Image
+  # references always carry a tag or digest at admission time, so these globs
+  # cover every `gitnexus:<tag>`, `gitnexus@sha256:...`, `gitnexus-web:<tag>`,
+  # and `gitnexus-web@sha256:...` reference on either GHCR or Docker Hub.
+  # The Docker Hub images are byte-for-byte mirrors of the GHCR images (same
+  # build, same digest, same Cosign signature), so the same keyless identity
+  # authority verifies both.
  images:
    - glob: 'ghcr.io/abhigyanpatwari/gitnexus*'
+    # Docker Hub references can appear in three forms at admission time
+    # (`docker.io/...`, `index.docker.io/...`, and bare `akonlabs/...` with
+    # the default registry implied). List all three so the policy cannot be
+    # sidestepped by the choice of registry prefix. The Docker Hub namespace
+    # is `akonlabs` rather than `abhigyanpatwari` because the Docker Hub org
+    # differs from the GitHub org.
+    - glob: 'docker.io/akonlabs/gitnexus*'
+    - glob: 'index.docker.io/akonlabs/gitnexus*'
+    - glob: 'akonlabs/gitnexus*'
  authorities:
    - name: gitnexus-cosign-keyless
      keyless:
@@ -19,7 +19,7 @@ services:
      - ${WORKSPACE_DIR:-./workspace}:/workspace:ro
    restart: unless-stopped
    healthcheck:
-      test: ['CMD', 'curl', '-fsS', 'http://localhost:4747/api/heartbeat']
+      test: ['CMD', 'curl', '-f', 'http://localhost:4747/api/health']
      interval: 30s
      timeout: 5s
      retries: 3
@@ -1,11 +1,11 @@
 import { createReadStream } from 'node:fs';
 import { stat } from 'node:fs/promises';
 import { createServer } from 'node:http';
-import { extname, join, normalize, sep } from 'node:path';
+import { extname, isAbsolute, normalize, relative, resolve } from 'node:path';

 const host = '0.0.0.0';
 const port = Number(process.env.PORT || '4173');
-const root = join(process.cwd(), 'dist');
+const root = resolve(process.cwd(), 'dist');

 const contentTypes = {
  '.css': 'text/css; charset=utf-8',
@@ -20,39 +20,78 @@ const contentTypes = {
  '.woff2': 'font/woff2',
 };

-function resolvePath(urlPath) {
+// Static asset server for the gitnexus-web Docker image.
+//
+// Path-injection containment: the request handler is intentionally a single
+// inline pipeline with no helper functions on the path-data flow. Each
+// filesystem sink (stat, createReadStream) is immediately preceded by the
+// canonical `path.relative` containment check that CodeQL's
+// `js/path-injection` query recognizes as a sanitizer barrier:
+//
+//     const rel = relative(root, candidate);
+//     if (rel.startsWith('..') || isAbsolute(rel)) reject;
+//     // candidate is now proven inside `root`
+//
+// Earlier iterations of this file used a helper (`resolveWithinRoot`) and a
+// `startsWith(root + sep)` check. Both were semantically correct but neither
+// was recognized by CodeQL: `startsWith(root + sep)` is not in the analyzer's
+// barrier-pattern set, and helper-based sanitization is not followed across
+// the request handler's reassignment paths in vanilla JS. The inline-at-sink
+// shape below is the documented analyzer-friendly idiom.
+const server = createServer(async (req, res) => {
+  const urlPath = req.url?.split('?')[0] || '/';
+
  let decoded;
  try {
    decoded = decodeURIComponent(urlPath);
  } catch {
-    return null;
+    res.writeHead(400);
+    res.end('Bad request');
+    return;
  }
-  if (decoded.includes('\0')) return null;
+  if (decoded.includes('\0')) {
+    res.writeHead(400);
+    res.end('Bad request');
+    return;
+  }
+
  const cleanPath = normalize(decoded.replace(/^\/+/, ''));
-  const candidate = join(root, cleanPath);
-  if (candidate !== root && !candidate.startsWith(root + sep)) return null;
-  return candidate;
-}
+  const initialPath = resolve(root, cleanPath);

-const server = createServer(async (req, res) => {
-  const requestPath = req.url?.split('?')[0] || '/';
-  let filePath = resolvePath(requestPath);
-
-  if (!filePath) {
+  // Sanitizer barrier #1 — guards the first stat() sink.
+  const initialRel = relative(root, initialPath);
+  if (initialRel.startsWith('..') || isAbsolute(initialRel)) {
    res.writeHead(400);
    res.end('Bad request');
    return;
  }

  try {
-    const fileStat = await stat(filePath).catch(() => null);
-    if (fileStat?.isDirectory()) {
-      filePath = join(filePath, 'index.html');
-    } else if (!fileStat?.isFile()) {
-      filePath = join(root, 'index.html');
+    const initialStat = await stat(initialPath).catch(() => null);
+
+    // Pick the path we actually serve. Note: any branch reassigns to a
+    // freshly-resolved path; the next sanitizer barrier re-validates.
+    let finalPath;
+    if (initialStat?.isDirectory()) {
+      finalPath = resolve(initialPath, 'index.html');
+    } else if (!initialStat?.isFile()) {
+      finalPath = resolve(root, 'index.html');
+    } else {
+      finalPath = initialPath;
    }

-    const finalStat = await stat(filePath).catch(() => null);
+    // Sanitizer barrier #2 — guards both the second stat() and the
+    // createReadStream() sinks. No reassignment of finalPath happens
+    // between this guard and either sink, so the analyzer can prove
+    // containment for both.
+    const finalRel = relative(root, finalPath);
+    if (finalRel.startsWith('..') || isAbsolute(finalRel)) {
+      res.writeHead(400);
+      res.end('Bad request');
+      return;
+    }
+
+    const finalStat = await stat(finalPath).catch(() => null);
    if (!finalStat?.isFile()) {
      res.writeHead(404);
      res.end('Not found');
@@ -60,14 +99,14 @@ const server = createServer(async (req, res) => {
    }

    res.writeHead(200, {
-      'Cache-Control': filePath.includes('/assets/')
+      'Cache-Control': finalPath.includes('/assets/')
        ? 'public, max-age=31536000, immutable'
        : 'no-cache',
-      'Content-Type': contentTypes[extname(filePath)] || 'application/octet-stream',
+      'Content-Type': contentTypes[extname(finalPath)] || 'application/octet-stream',
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
    });
-    const stream = createReadStream(filePath);
+    const stream = createReadStream(finalPath);
    stream.on('error', () => res.destroy());
    stream.pipe(res);
  } catch (error) {
@@ -100,6 +100,23 @@ it('rejects percent-encoded null bytes with 400', async () => {
  assert.equal(res.status, 400);
 });

+it('rejects percent-encoded path traversal with 400', async () => {
+  // %2e%2e%2f decodes to '../'. Without the path.relative inline barrier,
+  // a naive string check on the raw URL would let this through and only
+  // the lexical-decoded path.resolve would catch it. Confirm the barrier
+  // does its job after decodeURIComponent.
+  const res = await rawGet(serverPort, '/%2e%2e%2f%2e%2e%2fetc%2fpasswd');
+  assert.equal(res.status, 400);
+});
+
+it('rejects malformed percent-encoding with 400', async () => {
+  // %GG is not a valid percent-encoded sequence — decodeURIComponent throws.
+  // The handler's try/catch around decode must convert this to a 400 rather
+  // than an unhandled rejection.
+  const res = await rawGet(serverPort, '/foo%GGbar');
+  assert.equal(res.status, 400);
+});
+
 it('returns 404 when dist/index.html is missing', async () => {
  await unlink(join(tmpDir, 'dist', 'index.html'));
  const res = await rawGet(serverPort, '/nonexistent-page');
@@ -82,6 +82,9 @@ matching:
  bm25_threshold: 0.7
  embedding_threshold: 0.65
  max_candidates_per_step: 3
+  # Exclude noisy paths from cross-link matching (contracts are still extracted)
+  exclude_links_paths: [/ping, /health, /healthcheck]
+  exclude_links_param_only_paths: true
 ```

 Field notes (schema in [`types.ts`](../../gitnexus/src/core/group/types.ts)):
@@ -91,7 +94,9 @@ Field notes (schema in [`types.ts`](../../gitnexus/src/core/group/types.ts)):
 - `repos` — a mapping from **group path** (a logical name you choose; can be a hierarchy like `backend/orders`) to **registry name** (the name shown by `npx gitnexus list`). Both sides appear throughout the tooling: contract rows use the group path; `@<group>/<groupPath>` routes tools to a single member.
 - `links` — optional manifest escape hatch, one entry per explicit cross-repo contract. Validated by the parser: `from` and `to` must be known repo paths, `type` must be one of `http | grpc | topic | lib | custom`, and `role` must be `provider | consumer`.
 - `detect` — toggles per extractor family. Defaults (set in `config-parser.ts`) turn `http`, `grpc`, `topics`, and `shared_libs` on; disable the ones you don't use to speed up sync.
- `matching` — thresholds for the matching cascade. The exact match is always run; other strategies depend on indexer state.
+- `matching` — thresholds for the matching cascade. The exact match is always run; other strategies depend on indexer state. Two optional fields reduce false-positive cross-links in large groups:
+  - `exclude_links_paths` — list of HTTP paths to exclude from cross-link matching (default `[]`). Contracts at these paths are still extracted and visible in the registry, but they don't produce cross-repo links. Useful for health-check endpoints (`/ping`, `/health`) that every service exposes. Trailing slashes are normalized.
+  - `exclude_links_param_only_paths` — when `true`, exclude routes where every segment is `{param}` (e.g. `/{param}`, `/{param}/{param}`) from cross-link matching (default `false`). Mixed routes like `/users/{param}` are not affected.

 ### 3. Sync the group

@@ -0,0 +1,185 @@
+# Using GitNexus across Apache Thrift microservices
+
+## When to use this guide
+
+Use this guide when several repositories communicate through Apache Thrift and you want GitNexus to trace impact across provider and consumer boundaries. The walkthrough assumes each service is indexed on its own, then joined through a GitNexus group.
+
+This is not a framework integration guide. GitNexus reads portable Thrift IDL and common Java generated-code shapes. Framework-specific wiring, service discovery, deployment metadata, and private annotations belong outside the open-source core.
+
+## Mental model
+
+- `.thrift` files define the canonical service contract. A method in an IDL service becomes a stable contract id in the form `thrift::<namespace>.<Service>/<Method>`.
+- Service wildcard ids in the form `thrift::<namespace>.<Service>/*` are supported as manifest and matching fallback forms when a service-level link is needed.
+- Java generated-code usage points GitNexus toward implementation and call sites. Providers commonly implement generated `Service.Iface`; consumers commonly hold or construct generated service interfaces or clients.
+- Group sync matches provider and consumer contracts with the same id, then cross-repo impact can hop through those links.
+- Framework-specific wiring should be modeled by extractor plugins, manifest links, or downstream integrations rather than hard-coded into core Thrift support.
+
+## Fictional IDL
+
+```thrift
+namespace java billing.v1
+
+struct PlaceOrderRequest {
+  1: string orderId
+  2: double amount
+}
+
+struct PlaceOrderResponse {
+  1: bool accepted
+}
+
+struct GetOrderRequest {
+  1: string orderId
+}
+
+struct GetOrderResponse {
+  1: string orderId
+  2: string status
+}
+
+service OrderService {
+  PlaceOrderResponse PlaceOrder(1: PlaceOrderRequest request)
+  GetOrderResponse GetOrder(1: GetOrderRequest request)
+}
+```
+
+The service methods above produce canonical ids:
+
+- `thrift::billing.v1.OrderService/PlaceOrder`
+- `thrift::billing.v1.OrderService/GetOrder`
+- `thrift::billing.v1.OrderService/*` as a service-level manifest or matching fallback form
+
+## Java provider example
+
+Generated Java code usually exposes an `Iface` interface for the service. A provider implementation can be detected when it implements that generated interface.
+
+```java
+package example.billing;
+
+import billing.v1.GetOrderRequest;
+import billing.v1.GetOrderResponse;
+import billing.v1.OrderService;
+import billing.v1.PlaceOrderRequest;
+import billing.v1.PlaceOrderResponse;
+
+public final class OrderServiceHandler implements OrderService.Iface {
+  @Override
+  public PlaceOrderResponse PlaceOrder(PlaceOrderRequest request) {
+    return new PlaceOrderResponse(true);
+  }
+
+  @Override
+  public GetOrderResponse GetOrder(GetOrderRequest request) {
+    return new GetOrderResponse(request.getOrderId(), "CREATED");
+  }
+}
+```
+
+With the IDL available, GitNexus can connect the implementation to `thrift::billing.v1.OrderService/PlaceOrder` and `thrift::billing.v1.OrderService/GetOrder`.
+
+## Java consumer examples
+
+Consumers are strongest when Java usage can be tied back to the IDL namespace and service.
+
+```java
+package example.checkout;
+
+import billing.v1.OrderService;
+import billing.v1.PlaceOrderRequest;
+
+public final class CheckoutWorkflow {
+  private final OrderService.Iface orders;
+
+  public CheckoutWorkflow(OrderService.Iface orders) {
+    this.orders = orders;
+  }
+
+  public void submit(String orderId) throws Exception {
+    orders.PlaceOrder(new PlaceOrderRequest(orderId, 42.0));
+  }
+}
+```
+
+Some generated-code styles use the generated service type directly while keeping enough IDL context through imports and method calls.
+
+```java
+package example.reporting;
+
+import billing.v1.GetOrderRequest;
+import billing.v1.OrderService;
+
+public final class OrderLookup {
+  private final OrderService.Client client;
+
+  public OrderLookup(OrderService.Client client) {
+    this.client = client;
+  }
+
+  public String status(String orderId) throws Exception {
+    return client.GetOrder(new GetOrderRequest(orderId)).getStatus();
+  }
+}
+```
+
+When IDL context is missing, GitNexus may still emit a weaker consumer signal for generated `Iface` or `Client` shapes, but confidence is lower.
+
+## Group configuration
+
+New group configs enable Thrift contract detection by default. Keep `detect.thrift: true`
+when a group should scan for Thrift contracts, or set it to `false` to skip Thrift
+extraction for that group.
+
+```yaml
+version: 1
+name: billing-platform
+description: Fictional services connected by Apache Thrift
+
+repos:
+  checkout: checkout-service
+  billing: billing-service
+
+links: []
+
+detect:
+  http: true
+  grpc: false
+  thrift: true
+  topics: false
+  shared_libs: true
+```
+
+To disable Thrift extraction explicitly:
+
+```yaml
+detect:
+  thrift: false
+```
+
+After indexing each member repository, run group sync to extract contracts and write cross-repo links:
+
+```bash
+npx gitnexus group sync billing-platform
+```
+
+## Manifest escape hatch
+
+Use manifest links when automatic extraction cannot see a provider or consumer, or when generated code is wrapped behind an abstraction. Write the contract without the `thrift::` prefix; GitNexus canonicalizes it to the full Thrift contract id.
+
+```yaml
+links:
+  - from: checkout
+    to: billing
+    type: thrift
+    contract: billing.v1.OrderService/PlaceOrder
+    role: consumer
+```
+
+GitNexus canonicalizes that manifest entry to `thrift::billing.v1.OrderService/PlaceOrder` and uses it to connect the two repositories.
+
+## Known limitations
+
+- Java detection currently targets v1 generated-code patterns.
+- Maven and POM dependency coordinates are not used for inference.
+- Framework-specific annotations and service discovery metadata are ignored by open-source Thrift extraction.
+- Ambiguous same-name services are skipped instead of guessed.
+- Java consumers without IDL context are lower confidence and limited to generated `Iface` and `Client` shapes.
@@ -14,6 +14,7 @@ export default [
      'gitnexus/vendor/**',
      'gitnexus-web/src/vendor/**',
      'gitnexus/test/fixtures/**',
+      'gitnexus-web/test/fixtures/**',
      'gitnexus-web/playwright-report/**',
      'gitnexus-web/test-results/**',
      '**/*.d.ts',
@@ -53,13 +53,13 @@ class MCPBridge:

        try:
            # Find gitnexus binary
-            gitnexus_bin = self._find_gitnexus()
-            if not gitnexus_bin:
+            gitnexus_cmd = self._find_gitnexus_command()
+            if not gitnexus_cmd:
                logger.error("GitNexus not found. Install with: npm install -g gitnexus")
                return False

            self.process = subprocess.Popen(
-                [gitnexus_bin, "mcp"],
+                [*gitnexus_cmd, "mcp"],
                stdin=subprocess.PIPE,
                stdout=subprocess.PIPE,
                stderr=subprocess.PIPE,
@@ -152,33 +152,34 @@ class MCPBridge:
                return contents[0].get("text", "")
        return None

-    def _find_gitnexus(self) -> str | None:
-        """Find the gitnexus CLI binary."""
+    def _find_gitnexus_command(self) -> list[str] | None:
+        """Find the gitnexus CLI command prefix."""
        # Check if npx is available (preferred - uses local install)
-        for cmd in ["npx"]:
-            try:
-                result = subprocess.run(
-                    [cmd, "gitnexus", "--version"],
-                    capture_output=True,
-                    text=True,
-                    timeout=MCP_FIND_GITNEXUS_TIMEOUT_SECONDS,
-                    cwd=self.repo_path,
-                )
-                if result.returncode == 0:
-                    return cmd  # Will use "npx gitnexus mcp"
-            except Exception:
-                continue
+        try:
+            result = subprocess.run(
+                ["npx", "gitnexus", "--version"],
+                stdin=subprocess.DEVNULL,
+                capture_output=True,
+                text=True,
+                timeout=MCP_FIND_GITNEXUS_TIMEOUT_SECONDS,
+                cwd=self.repo_path,
+            )
+            if result.returncode == 0:
+                return ["npx", "gitnexus"]
+        except Exception:
+            pass

        # Check for global install
        try:
            result = subprocess.run(
                ["gitnexus", "--version"],
+                stdin=subprocess.DEVNULL,
                capture_output=True,
                text=True,
                timeout=MCP_FIND_GITNEXUS_FALLBACK_TIMEOUT_SECONDS,
            )
            if result.returncode == 0:
-                return "gitnexus"
+                return ["gitnexus"]
        except Exception:
            pass

@@ -6,19 +6,19 @@ readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
    "mini-swe-agent>=2.0.0",
-    "litellm>=1.50.0,!=1.82.7,!=1.82.8",
+    "litellm!=1.82.7,!=1.82.8,>=1.83.7",
    "datasets>=3.0.0",
    "typer>=0.12.0",
    "rich>=13.0.0",
    "pyyaml>=6.0",
    "pandas>=2.0.0",
    "tabulate>=0.9.0",
-    "python-dotenv>=1.0.0",
+    "python-dotenv>=1.2.2",
 ]

 [project.optional-dependencies]
 dev = [
-    "pytest>=8.0.0",
+    "pytest>=9.0.3",
    "ruff>=0.5.0",
    "hypothesis>=6.88.0",
    "coverage>=7.6.0",
@@ -0,0 +1,170 @@
+"""Tests for MCPBridge._find_gitnexus_command() and subprocess spawn."""
+import subprocess
+import unittest
+from unittest.mock import MagicMock, call, patch
+
+
+class TestFindGitnexusCommand(unittest.TestCase):
+    """Verify _find_gitnexus_command() returns the correct command prefix."""
+
+    def _make_bridge(self):
+        from bridge.mcp_bridge import MCPBridge
+        return MCPBridge(repo_path="/fake/repo")
+
+    def _success(self):
+        r = MagicMock()
+        r.returncode = 0
+        return r
+
+    def _failure(self):
+        r = MagicMock()
+        r.returncode = 1
+        return r
+
+    def test_npx_path_returns_npx_gitnexus(self):
+        """When npx probe succeeds, command prefix is ['npx', 'gitnexus']."""
+        with patch("subprocess.run", return_value=self._success()) as mock_run:
+            bridge = self._make_bridge()
+            result = bridge._find_gitnexus_command()
+
+        self.assertEqual(result, ["npx", "gitnexus"])
+        mock_run.assert_called_once()
+        args = mock_run.call_args[0][0]
+        self.assertEqual(args, ["npx", "gitnexus", "--version"])
+
+    def test_global_path_returns_gitnexus(self):
+        """When npx probe fails but global install exists, prefix is ['gitnexus']."""
+        with patch("subprocess.run", side_effect=[self._failure(), self._success()]) as mock_run:
+            bridge = self._make_bridge()
+            result = bridge._find_gitnexus_command()
+
+        self.assertEqual(result, ["gitnexus"])
+        self.assertEqual(mock_run.call_count, 2)
+
+    def test_both_fail_returns_none(self):
+        """When both probes fail, returns None."""
+        with patch("subprocess.run", return_value=self._failure()):
+            bridge = self._make_bridge()
+            result = bridge._find_gitnexus_command()
+
+        self.assertIsNone(result)
+
+    def test_npx_exception_falls_back_to_global(self):
+        """When npx raises (not installed), falls back to global probe."""
+        with patch("subprocess.run", side_effect=[FileNotFoundError, self._success()]):
+            bridge = self._make_bridge()
+            result = bridge._find_gitnexus_command()
+
+        self.assertEqual(result, ["gitnexus"])
+
+    def test_both_raise_returns_none(self):
+        """When both probes raise exceptions, returns None."""
+        with patch("subprocess.run", side_effect=FileNotFoundError):
+            bridge = self._make_bridge()
+            result = bridge._find_gitnexus_command()
+
+        self.assertIsNone(result)
+
+    def test_stdin_devnull_on_npx_probe(self):
+        """npx probe must pass stdin=DEVNULL to prevent interactive blocking."""
+        with patch("subprocess.run", return_value=self._success()) as mock_run:
+            bridge = self._make_bridge()
+            bridge._find_gitnexus_command()
+
+        kwargs = mock_run.call_args[1]
+        self.assertEqual(kwargs.get("stdin"), subprocess.DEVNULL)
+
+    def test_stdin_devnull_on_global_probe(self):
+        """global probe must pass stdin=DEVNULL to prevent interactive blocking."""
+        with patch("subprocess.run", side_effect=[self._failure(), self._success()]) as mock_run:
+            bridge = self._make_bridge()
+            bridge._find_gitnexus_command()
+
+        global_call_kwargs = mock_run.call_args_list[1][1]
+        self.assertEqual(global_call_kwargs.get("stdin"), subprocess.DEVNULL)
+
+
+class TestStartSpawnCommand(unittest.TestCase):
+    """Verify start() spawns Popen with the correct argv."""
+
+    def _make_bridge(self):
+        from bridge.mcp_bridge import MCPBridge
+        return MCPBridge(repo_path="/fake/repo")
+
+    def test_npx_path_spawns_npx_gitnexus_mcp(self):
+        """When npx path found, Popen must receive ['npx', 'gitnexus', 'mcp']."""
+        bridge = self._make_bridge()
+
+        with patch.object(bridge, "_find_gitnexus_command", return_value=["npx", "gitnexus"]), \
+             patch("subprocess.Popen") as mock_popen, \
+             patch.object(bridge, "_send_request", return_value={"protocolVersion": "2024-11-05"}), \
+             patch.object(bridge, "_send_notification"):
+
+            mock_proc = MagicMock()
+            mock_proc.stdin = MagicMock()
+            mock_proc.stdout = MagicMock()
+            mock_proc.stderr = MagicMock()
+            mock_popen.return_value = mock_proc
+
+            bridge.start()
+
+        mock_popen.assert_called_once()
+        argv = mock_popen.call_args[0][0]
+        self.assertEqual(argv, ["npx", "gitnexus", "mcp"])
+
+    def test_global_path_spawns_gitnexus_mcp(self):
+        """When global path found, Popen must receive ['gitnexus', 'mcp']."""
+        bridge = self._make_bridge()
+
+        with patch.object(bridge, "_find_gitnexus_command", return_value=["gitnexus"]), \
+             patch("subprocess.Popen") as mock_popen, \
+             patch.object(bridge, "_send_request", return_value={"protocolVersion": "2024-11-05"}), \
+             patch.object(bridge, "_send_notification"):
+
+            mock_proc = MagicMock()
+            mock_proc.stdin = MagicMock()
+            mock_proc.stdout = MagicMock()
+            mock_proc.stderr = MagicMock()
+            mock_popen.return_value = mock_proc
+
+            bridge.start()
+
+        mock_popen.assert_called_once()
+        argv = mock_popen.call_args[0][0]
+        self.assertEqual(argv, ["gitnexus", "mcp"])
+
+    def test_no_shell_true(self):
+        """Popen must never be called with shell=True."""
+        bridge = self._make_bridge()
+
+        with patch.object(bridge, "_find_gitnexus_command", return_value=["npx", "gitnexus"]), \
+             patch("subprocess.Popen") as mock_popen, \
+             patch.object(bridge, "_send_request", return_value={"protocolVersion": "2024-11-05"}), \
+             patch.object(bridge, "_send_notification"):
+
+            mock_proc = MagicMock()
+            mock_proc.stdin = MagicMock()
+            mock_proc.stdout = MagicMock()
+            mock_proc.stderr = MagicMock()
+            mock_popen.return_value = mock_proc
+
+            bridge.start()
+
+        kwargs = mock_popen.call_args[1]
+        self.assertNotEqual(kwargs.get("shell"), True)
+
+    def test_gitnexus_not_found_returns_false(self):
+        """start() returns False and does not call Popen when gitnexus not found."""
+        bridge = self._make_bridge()
+
+        with patch.object(bridge, "_find_gitnexus_command", return_value=None), \
+             patch("subprocess.Popen") as mock_popen:
+
+            result = bridge.start()
+
+        self.assertFalse(result)
+        mock_popen.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -21,7 +21,7 @@ wheels = [

 [[package]]
 name = "aiohttp"
-version = "3.13.3"
+version = "3.13.4"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "aiohappyeyeballs" },
@@ -32,93 +32,93 @@ dependencies = [
    { name = "propcache" },
    { name = "yarl" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/50/42/32cf8e7704ceb4481406eb87161349abb46a57fee3f008ba9cb610968646/aiohttp-3.13.3.tar.gz", hash = "sha256:a949eee43d3782f2daae4f4a2819b2cb9b0c5d3b7f7a927067cc84dafdbb9f88", size = 7844556, upload-time = "2026-01-03T17:33:05.204Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/45/4a/064321452809dae953c1ed6e017504e72551a26b6f5708a5a80e4bf556ff/aiohttp-3.13.4.tar.gz", hash = "sha256:d97a6d09c66087890c2ab5d49069e1e570583f7ac0314ecf98294c1b6aaebd38", size = 7859748, upload-time = "2026-03-28T17:19:40.6Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/f1/4c/a164164834f03924d9a29dc3acd9e7ee58f95857e0b467f6d04298594ebb/aiohttp-3.13.3-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:5b6073099fb654e0a068ae678b10feff95c5cae95bbfcbfa7af669d361a8aa6b", size = 746051, upload-time = "2026-01-03T17:29:43.287Z" },
-    { url = "https://files.pythonhosted.org/packages/82/71/d5c31390d18d4f58115037c432b7e0348c60f6f53b727cad33172144a112/aiohttp-3.13.3-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:1cb93e166e6c28716c8c6aeb5f99dfb6d5ccf482d29fe9bf9a794110e6d0ab64", size = 499234, upload-time = "2026-01-03T17:29:44.822Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/c9/741f8ac91e14b1d2e7100690425a5b2b919a87a5075406582991fb7de920/aiohttp-3.13.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:28e027cf2f6b641693a09f631759b4d9ce9165099d2b5d92af9bd4e197690eea", size = 494979, upload-time = "2026-01-03T17:29:46.405Z" },
-    { url = "https://files.pythonhosted.org/packages/75/b5/31d4d2e802dfd59f74ed47eba48869c1c21552c586d5e81a9d0d5c2ad640/aiohttp-3.13.3-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3b61b7169ababd7802f9568ed96142616a9118dd2be0d1866e920e77ec8fa92a", size = 1748297, upload-time = "2026-01-03T17:29:48.083Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/3e/eefad0ad42959f226bb79664826883f2687d602a9ae2941a18e0484a74d3/aiohttp-3.13.3-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:80dd4c21b0f6237676449c6baaa1039abae86b91636b6c91a7f8e61c87f89540", size = 1707172, upload-time = "2026-01-03T17:29:49.648Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/3a/54a64299fac2891c346cdcf2aa6803f994a2e4beeaf2e5a09dcc54acc842/aiohttp-3.13.3-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:65d2ccb7eabee90ce0503c17716fc77226be026dcc3e65cce859a30db715025b", size = 1805405, upload-time = "2026-01-03T17:29:51.244Z" },
-    { url = "https://files.pythonhosted.org/packages/6c/70/ddc1b7169cf64075e864f64595a14b147a895a868394a48f6a8031979038/aiohttp-3.13.3-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5b179331a481cb5529fca8b432d8d3c7001cb217513c94cd72d668d1248688a3", size = 1899449, upload-time = "2026-01-03T17:29:53.938Z" },
-    { url = "https://files.pythonhosted.org/packages/a1/7e/6815aab7d3a56610891c76ef79095677b8b5be6646aaf00f69b221765021/aiohttp-3.13.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9d4c940f02f49483b18b079d1c27ab948721852b281f8b015c058100e9421dd1", size = 1748444, upload-time = "2026-01-03T17:29:55.484Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/f2/073b145c4100da5511f457dc0f7558e99b2987cf72600d42b559db856fbc/aiohttp-3.13.3-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f9444f105664c4ce47a2a7171a2418bce5b7bae45fb610f4e2c36045d85911d3", size = 1606038, upload-time = "2026-01-03T17:29:57.179Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/c1/778d011920cae03ae01424ec202c513dc69243cf2db303965615b81deeea/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:694976222c711d1d00ba131904beb60534f93966562f64440d0c9d41b8cdb440", size = 1724156, upload-time = "2026-01-03T17:29:58.914Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/cb/3419eabf4ec1e9ec6f242c32b689248365a1cf621891f6f0386632525494/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:f33ed1a2bf1997a36661874b017f5c4b760f41266341af36febaf271d179f6d7", size = 1722340, upload-time = "2026-01-03T17:30:01.962Z" },
-    { url = "https://files.pythonhosted.org/packages/7a/e5/76cf77bdbc435bf233c1f114edad39ed4177ccbfab7c329482b179cff4f4/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:e636b3c5f61da31a92bf0d91da83e58fdfa96f178ba682f11d24f31944cdd28c", size = 1783041, upload-time = "2026-01-03T17:30:03.609Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/d4/dd1ca234c794fd29c057ce8c0566b8ef7fd6a51069de5f06fa84b9a1971c/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:5d2d94f1f5fcbe40838ac51a6ab5704a6f9ea42e72ceda48de5e6b898521da51", size = 1596024, upload-time = "2026-01-03T17:30:05.132Z" },
-    { url = "https://files.pythonhosted.org/packages/55/58/4345b5f26661a6180afa686c473620c30a66afdf120ed3dd545bbc809e85/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:2be0e9ccf23e8a94f6f0650ce06042cefc6ac703d0d7ab6c7a917289f2539ad4", size = 1804590, upload-time = "2026-01-03T17:30:07.135Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/06/05950619af6c2df7e0a431d889ba2813c9f0129cec76f663e547a5ad56f2/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:9af5e68ee47d6534d36791bbe9b646d2a7c7deb6fc24d7943628edfbb3581f29", size = 1740355, upload-time = "2026-01-03T17:30:09.083Z" },
-    { url = "https://files.pythonhosted.org/packages/3e/80/958f16de79ba0422d7c1e284b2abd0c84bc03394fbe631d0a39ffa10e1eb/aiohttp-3.13.3-cp311-cp311-win32.whl", hash = "sha256:a2212ad43c0833a873d0fb3c63fa1bacedd4cf6af2fee62bf4b739ceec3ab239", size = 433701, upload-time = "2026-01-03T17:30:10.869Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/f2/27cdf04c9851712d6c1b99df6821a6623c3c9e55956d4b1e318c337b5a48/aiohttp-3.13.3-cp311-cp311-win_amd64.whl", hash = "sha256:642f752c3eb117b105acbd87e2c143de710987e09860d674e068c4c2c441034f", size = 457678, upload-time = "2026-01-03T17:30:12.719Z" },
-    { url = "https://files.pythonhosted.org/packages/a0/be/4fc11f202955a69e0db803a12a062b8379c970c7c84f4882b6da17337cc1/aiohttp-3.13.3-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:b903a4dfee7d347e2d87697d0713be59e0b87925be030c9178c5faa58ea58d5c", size = 739732, upload-time = "2026-01-03T17:30:14.23Z" },
-    { url = "https://files.pythonhosted.org/packages/97/2c/621d5b851f94fa0bb7430d6089b3aa970a9d9b75196bc93bb624b0db237a/aiohttp-3.13.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:a45530014d7a1e09f4a55f4f43097ba0fd155089372e105e4bff4ca76cb1b168", size = 494293, upload-time = "2026-01-03T17:30:15.96Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/43/4be01406b78e1be8320bb8316dc9c42dbab553d281c40364e0f862d5661c/aiohttp-3.13.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:27234ef6d85c914f9efeb77ff616dbf4ad2380be0cda40b4db086ffc7ddd1b7d", size = 493533, upload-time = "2026-01-03T17:30:17.431Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/a8/5a35dc56a06a2c90d4742cbf35294396907027f80eea696637945a106f25/aiohttp-3.13.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d32764c6c9aafb7fb55366a224756387cd50bfa720f32b88e0e6fa45b27dcf29", size = 1737839, upload-time = "2026-01-03T17:30:19.422Z" },
-    { url = "https://files.pythonhosted.org/packages/bf/62/4b9eeb331da56530bf2e198a297e5303e1c1ebdceeb00fe9b568a65c5a0c/aiohttp-3.13.3-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:b1a6102b4d3ebc07dad44fbf07b45bb600300f15b552ddf1851b5390202ea2e3", size = 1703932, upload-time = "2026-01-03T17:30:21.756Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/f6/af16887b5d419e6a367095994c0b1332d154f647e7dc2bd50e61876e8e3d/aiohttp-3.13.3-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c014c7ea7fb775dd015b2d3137378b7be0249a448a1612268b5a90c2d81de04d", size = 1771906, upload-time = "2026-01-03T17:30:23.932Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/83/397c634b1bcc24292fa1e0c7822800f9f6569e32934bdeef09dae7992dfb/aiohttp-3.13.3-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2b8d8ddba8f95ba17582226f80e2de99c7a7948e66490ef8d947e272a93e9463", size = 1871020, upload-time = "2026-01-03T17:30:26Z" },
-    { url = "https://files.pythonhosted.org/packages/86/f6/a62cbbf13f0ac80a70f71b1672feba90fdb21fd7abd8dbf25c0105fb6fa3/aiohttp-3.13.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9ae8dd55c8e6c4257eae3a20fd2c8f41edaea5992ed67156642493b8daf3cecc", size = 1755181, upload-time = "2026-01-03T17:30:27.554Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/87/20a35ad487efdd3fba93d5843efdfaa62d2f1479eaafa7453398a44faf13/aiohttp-3.13.3-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:01ad2529d4b5035578f5081606a465f3b814c542882804e2e8cda61adf5c71bf", size = 1561794, upload-time = "2026-01-03T17:30:29.254Z" },
-    { url = "https://files.pythonhosted.org/packages/de/95/8fd69a66682012f6716e1bc09ef8a1a2a91922c5725cb904689f112309c4/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:bb4f7475e359992b580559e008c598091c45b5088f28614e855e42d39c2f1033", size = 1697900, upload-time = "2026-01-03T17:30:31.033Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/66/7b94b3b5ba70e955ff597672dad1691333080e37f50280178967aff68657/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:c19b90316ad3b24c69cd78d5c9b4f3aa4497643685901185b65166293d36a00f", size = 1728239, upload-time = "2026-01-03T17:30:32.703Z" },
-    { url = "https://files.pythonhosted.org/packages/47/71/6f72f77f9f7d74719692ab65a2a0252584bf8d5f301e2ecb4c0da734530a/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:96d604498a7c782cb15a51c406acaea70d8c027ee6b90c569baa6e7b93073679", size = 1740527, upload-time = "2026-01-03T17:30:34.695Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/b4/75ec16cbbd5c01bdaf4a05b19e103e78d7ce1ef7c80867eb0ace42ff4488/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:084911a532763e9d3dd95adf78a78f4096cd5f58cdc18e6fdbc1b58417a45423", size = 1554489, upload-time = "2026-01-03T17:30:36.864Z" },
-    { url = "https://files.pythonhosted.org/packages/52/8f/bc518c0eea29f8406dcf7ed1f96c9b48e3bc3995a96159b3fc11f9e08321/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:7a4a94eb787e606d0a09404b9c38c113d3b099d508021faa615d70a0131907ce", size = 1767852, upload-time = "2026-01-03T17:30:39.433Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/f2/a07a75173124f31f11ea6f863dc44e6f09afe2bca45dd4e64979490deab1/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:87797e645d9d8e222e04160ee32aa06bc5c163e8499f24db719e7852ec23093a", size = 1722379, upload-time = "2026-01-03T17:30:41.081Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/4a/1a3fee7c21350cac78e5c5cef711bac1b94feca07399f3d406972e2d8fcd/aiohttp-3.13.3-cp312-cp312-win32.whl", hash = "sha256:b04be762396457bef43f3597c991e192ee7da460a4953d7e647ee4b1c28e7046", size = 428253, upload-time = "2026-01-03T17:30:42.644Z" },
-    { url = "https://files.pythonhosted.org/packages/d9/b7/76175c7cb4eb73d91ad63c34e29fc4f77c9386bba4a65b53ba8e05ee3c39/aiohttp-3.13.3-cp312-cp312-win_amd64.whl", hash = "sha256:e3531d63d3bdfa7e3ac5e9b27b2dd7ec9df3206a98e0b3445fa906f233264c57", size = 455407, upload-time = "2026-01-03T17:30:44.195Z" },
-    { url = "https://files.pythonhosted.org/packages/97/8a/12ca489246ca1faaf5432844adbfce7ff2cc4997733e0af120869345643a/aiohttp-3.13.3-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:5dff64413671b0d3e7d5918ea490bdccb97a4ad29b3f311ed423200b2203e01c", size = 734190, upload-time = "2026-01-03T17:30:45.832Z" },
-    { url = "https://files.pythonhosted.org/packages/32/08/de43984c74ed1fca5c014808963cc83cb00d7bb06af228f132d33862ca76/aiohttp-3.13.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:87b9aab6d6ed88235aa2970294f496ff1a1f9adcd724d800e9b952395a80ffd9", size = 491783, upload-time = "2026-01-03T17:30:47.466Z" },
-    { url = "https://files.pythonhosted.org/packages/17/f8/8dd2cf6112a5a76f81f81a5130c57ca829d101ad583ce57f889179accdda/aiohttp-3.13.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:425c126c0dc43861e22cb1c14ba4c8e45d09516d0a3ae0a3f7494b79f5f233a3", size = 490704, upload-time = "2026-01-03T17:30:49.373Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/40/a46b03ca03936f832bc7eaa47cfbb1ad012ba1be4790122ee4f4f8cba074/aiohttp-3.13.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7f9120f7093c2a32d9647abcaf21e6ad275b4fbec5b55969f978b1a97c7c86bf", size = 1720652, upload-time = "2026-01-03T17:30:50.974Z" },
-    { url = "https://files.pythonhosted.org/packages/f7/7e/917fe18e3607af92657e4285498f500dca797ff8c918bd7d90b05abf6c2a/aiohttp-3.13.3-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:697753042d57f4bf7122cab985bf15d0cef23c770864580f5af4f52023a56bd6", size = 1692014, upload-time = "2026-01-03T17:30:52.729Z" },
-    { url = "https://files.pythonhosted.org/packages/71/b6/cefa4cbc00d315d68973b671cf105b21a609c12b82d52e5d0c9ae61d2a09/aiohttp-3.13.3-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6de499a1a44e7de70735d0b39f67c8f25eb3d91eb3103be99ca0fa882cdd987d", size = 1759777, upload-time = "2026-01-03T17:30:54.537Z" },
-    { url = "https://files.pythonhosted.org/packages/fb/e3/e06ee07b45e59e6d81498b591fc589629be1553abb2a82ce33efe2a7b068/aiohttp-3.13.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:37239e9f9a7ea9ac5bf6b92b0260b01f8a22281996da609206a84df860bc1261", size = 1861276, upload-time = "2026-01-03T17:30:56.512Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/24/75d274228acf35ceeb2850b8ce04de9dd7355ff7a0b49d607ee60c29c518/aiohttp-3.13.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f76c1e3fe7d7c8afad7ed193f89a292e1999608170dcc9751a7462a87dfd5bc0", size = 1743131, upload-time = "2026-01-03T17:30:58.256Z" },
-    { url = "https://files.pythonhosted.org/packages/04/98/3d21dde21889b17ca2eea54fdcff21b27b93f45b7bb94ca029c31ab59dc3/aiohttp-3.13.3-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:fc290605db2a917f6e81b0e1e0796469871f5af381ce15c604a3c5c7e51cb730", size = 1556863, upload-time = "2026-01-03T17:31:00.445Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/84/da0c3ab1192eaf64782b03971ab4055b475d0db07b17eff925e8c93b3aa5/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:4021b51936308aeea0367b8f006dc999ca02bc118a0cc78c303f50a2ff6afb91", size = 1682793, upload-time = "2026-01-03T17:31:03.024Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/0f/5802ada182f575afa02cbd0ec5180d7e13a402afb7c2c03a9aa5e5d49060/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:49a03727c1bba9a97d3e93c9f93ca03a57300f484b6e935463099841261195d3", size = 1716676, upload-time = "2026-01-03T17:31:04.842Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/8c/714d53bd8b5a4560667f7bbbb06b20c2382f9c7847d198370ec6526af39c/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:3d9908a48eb7416dc1f4524e69f1d32e5d90e3981e4e37eb0aa1cd18f9cfa2a4", size = 1733217, upload-time = "2026-01-03T17:31:06.868Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/79/e2176f46d2e963facea939f5be2d26368ce543622be6f00a12844d3c991f/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:2712039939ec963c237286113c68dbad80a82a4281543f3abf766d9d73228998", size = 1552303, upload-time = "2026-01-03T17:31:08.958Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/6a/28ed4dea1759916090587d1fe57087b03e6c784a642b85ef48217b0277ae/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:7bfdc049127717581866fa4708791220970ce291c23e28ccf3922c700740fdc0", size = 1763673, upload-time = "2026-01-03T17:31:10.676Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/35/4a3daeb8b9fab49240d21c04d50732313295e4bd813a465d840236dd0ce1/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:8057c98e0c8472d8846b9c79f56766bcc57e3e8ac7bfd510482332366c56c591", size = 1721120, upload-time = "2026-01-03T17:31:12.575Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/9f/d643bb3c5fb99547323e635e251c609fbbc660d983144cfebec529e09264/aiohttp-3.13.3-cp313-cp313-win32.whl", hash = "sha256:1449ceddcdbcf2e0446957863af03ebaaa03f94c090f945411b61269e2cb5daf", size = 427383, upload-time = "2026-01-03T17:31:14.382Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/f1/ab0395f8a79933577cdd996dd2f9aa6014af9535f65dddcf88204682fe62/aiohttp-3.13.3-cp313-cp313-win_amd64.whl", hash = "sha256:693781c45a4033d31d4187d2436f5ac701e7bbfe5df40d917736108c1cc7436e", size = 453899, upload-time = "2026-01-03T17:31:15.958Z" },
-    { url = "https://files.pythonhosted.org/packages/99/36/5b6514a9f5d66f4e2597e40dea2e3db271e023eb7a5d22defe96ba560996/aiohttp-3.13.3-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:ea37047c6b367fd4bd632bff8077449b8fa034b69e812a18e0132a00fae6e808", size = 737238, upload-time = "2026-01-03T17:31:17.909Z" },
-    { url = "https://files.pythonhosted.org/packages/f7/49/459327f0d5bcd8c6c9ca69e60fdeebc3622861e696490d8674a6d0cb90a6/aiohttp-3.13.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:6fc0e2337d1a4c3e6acafda6a78a39d4c14caea625124817420abceed36e2415", size = 492292, upload-time = "2026-01-03T17:31:19.919Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/0b/b97660c5fd05d3495b4eb27f2d0ef18dc1dc4eff7511a9bf371397ff0264/aiohttp-3.13.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c685f2d80bb67ca8c3837823ad76196b3694b0159d232206d1e461d3d434666f", size = 493021, upload-time = "2026-01-03T17:31:21.636Z" },
-    { url = "https://files.pythonhosted.org/packages/54/d4/438efabdf74e30aeceb890c3290bbaa449780583b1270b00661126b8aae4/aiohttp-3.13.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:48e377758516d262bde50c2584fc6c578af272559c409eecbdd2bae1601184d6", size = 1717263, upload-time = "2026-01-03T17:31:23.296Z" },
-    { url = "https://files.pythonhosted.org/packages/71/f2/7bddc7fd612367d1459c5bcf598a9e8f7092d6580d98de0e057eb42697ad/aiohttp-3.13.3-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:34749271508078b261c4abb1767d42b8d0c0cc9449c73a4df494777dc55f0687", size = 1669107, upload-time = "2026-01-03T17:31:25.334Z" },
-    { url = "https://files.pythonhosted.org/packages/00/5a/1aeaecca40e22560f97610a329e0e5efef5e0b5afdf9f857f0d93839ab2e/aiohttp-3.13.3-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:82611aeec80eb144416956ec85b6ca45a64d76429c1ed46ae1b5f86c6e0c9a26", size = 1760196, upload-time = "2026-01-03T17:31:27.394Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/f8/0ff6992bea7bd560fc510ea1c815f87eedd745fe035589c71ce05612a19a/aiohttp-3.13.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2fff83cfc93f18f215896e3a190e8e5cb413ce01553901aca925176e7568963a", size = 1843591, upload-time = "2026-01-03T17:31:29.238Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/d1/e30e537a15f53485b61f5be525f2157da719819e8377298502aebac45536/aiohttp-3.13.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bbe7d4cecacb439e2e2a8a1a7b935c25b812af7a5fd26503a66dadf428e79ec1", size = 1720277, upload-time = "2026-01-03T17:31:31.053Z" },
-    { url = "https://files.pythonhosted.org/packages/84/45/23f4c451d8192f553d38d838831ebbc156907ea6e05557f39563101b7717/aiohttp-3.13.3-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b928f30fe49574253644b1ca44b1b8adbd903aa0da4b9054a6c20fc7f4092a25", size = 1548575, upload-time = "2026-01-03T17:31:32.87Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/ed/0a42b127a43712eda7807e7892c083eadfaf8429ca8fb619662a530a3aab/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7b5e8fe4de30df199155baaf64f2fcd604f4c678ed20910db8e2c66dc4b11603", size = 1679455, upload-time = "2026-01-03T17:31:34.76Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/b5/c05f0c2b4b4fe2c9d55e73b6d3ed4fd6c9dc2684b1d81cbdf77e7fad9adb/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:8542f41a62bcc58fc7f11cf7c90e0ec324ce44950003feb70640fc2a9092c32a", size = 1687417, upload-time = "2026-01-03T17:31:36.699Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/6b/915bc5dad66aef602b9e459b5a973529304d4e89ca86999d9d75d80cbd0b/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:5e1d8c8b8f1d91cd08d8f4a3c2b067bfca6ec043d3ff36de0f3a715feeedf926", size = 1729968, upload-time = "2026-01-03T17:31:38.622Z" },
-    { url = "https://files.pythonhosted.org/packages/11/3b/e84581290a9520024a08640b63d07673057aec5ca548177a82026187ba73/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:90455115e5da1c3c51ab619ac57f877da8fd6d73c05aacd125c5ae9819582aba", size = 1545690, upload-time = "2026-01-03T17:31:40.57Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/04/0c3655a566c43fd647c81b895dfe361b9f9ad6d58c19309d45cff52d6c3b/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:042e9e0bcb5fba81886c8b4fbb9a09d6b8a00245fd8d88e4d989c1f96c74164c", size = 1746390, upload-time = "2026-01-03T17:31:42.857Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/53/71165b26978f719c3419381514c9690bd5980e764a09440a10bb816ea4ab/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:2eb752b102b12a76ca02dff751a801f028b4ffbbc478840b473597fc91a9ed43", size = 1702188, upload-time = "2026-01-03T17:31:44.984Z" },
-    { url = "https://files.pythonhosted.org/packages/29/a7/cbe6c9e8e136314fa1980da388a59d2f35f35395948a08b6747baebb6aa6/aiohttp-3.13.3-cp314-cp314-win32.whl", hash = "sha256:b556c85915d8efaed322bf1bdae9486aa0f3f764195a0fb6ee962e5c71ef5ce1", size = 433126, upload-time = "2026-01-03T17:31:47.463Z" },
-    { url = "https://files.pythonhosted.org/packages/de/56/982704adea7d3b16614fc5936014e9af85c0e34b58f9046655817f04306e/aiohttp-3.13.3-cp314-cp314-win_amd64.whl", hash = "sha256:9bf9f7a65e7aa20dd764151fb3d616c81088f91f8df39c3893a536e279b4b984", size = 459128, upload-time = "2026-01-03T17:31:49.2Z" },
-    { url = "https://files.pythonhosted.org/packages/6c/2a/3c79b638a9c3d4658d345339d22070241ea341ed4e07b5ac60fb0f418003/aiohttp-3.13.3-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:05861afbbec40650d8a07ea324367cb93e9e8cc7762e04dd4405df99fa65159c", size = 769512, upload-time = "2026-01-03T17:31:51.134Z" },
-    { url = "https://files.pythonhosted.org/packages/29/b9/3e5014d46c0ab0db8707e0ac2711ed28c4da0218c358a4e7c17bae0d8722/aiohttp-3.13.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:2fc82186fadc4a8316768d61f3722c230e2c1dcab4200d52d2ebdf2482e47592", size = 506444, upload-time = "2026-01-03T17:31:52.85Z" },
-    { url = "https://files.pythonhosted.org/packages/90/03/c1d4ef9a054e151cd7839cdc497f2638f00b93cbe8043983986630d7a80c/aiohttp-3.13.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:0add0900ff220d1d5c5ebbf99ed88b0c1bbf87aa7e4262300ed1376a6b13414f", size = 510798, upload-time = "2026-01-03T17:31:54.91Z" },
-    { url = "https://files.pythonhosted.org/packages/ea/76/8c1e5abbfe8e127c893fe7ead569148a4d5a799f7cf958d8c09f3eedf097/aiohttp-3.13.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:568f416a4072fbfae453dcf9a99194bbb8bdeab718e08ee13dfa2ba0e4bebf29", size = 1868835, upload-time = "2026-01-03T17:31:56.733Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/ac/984c5a6f74c363b01ff97adc96a3976d9c98940b8969a1881575b279ac5d/aiohttp-3.13.3-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:add1da70de90a2569c5e15249ff76a631ccacfe198375eead4aadf3b8dc849dc", size = 1720486, upload-time = "2026-01-03T17:31:58.65Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/9a/b7039c5f099c4eb632138728828b33428585031a1e658d693d41d07d89d1/aiohttp-3.13.3-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:10b47b7ba335d2e9b1239fa571131a87e2d8ec96b333e68b2a305e7a98b0bae2", size = 1847951, upload-time = "2026-01-03T17:32:00.989Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/02/3bec2b9a1ba3c19ff89a43a19324202b8eb187ca1e928d8bdac9bbdddebd/aiohttp-3.13.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:3dd4dce1c718e38081c8f35f323209d4c1df7d4db4bab1b5c88a6b4d12b74587", size = 1941001, upload-time = "2026-01-03T17:32:03.122Z" },
-    { url = "https://files.pythonhosted.org/packages/37/df/d879401cedeef27ac4717f6426c8c36c3091c6e9f08a9178cc87549c537f/aiohttp-3.13.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:34bac00a67a812570d4a460447e1e9e06fae622946955f939051e7cc895cfab8", size = 1797246, upload-time = "2026-01-03T17:32:05.255Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/15/be122de1f67e6953add23335c8ece6d314ab67c8bebb3f181063010795a7/aiohttp-3.13.3-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:a19884d2ee70b06d9204b2727a7b9f983d0c684c650254679e716b0b77920632", size = 1627131, upload-time = "2026-01-03T17:32:07.607Z" },
-    { url = "https://files.pythonhosted.org/packages/12/12/70eedcac9134cfa3219ab7af31ea56bc877395b1ac30d65b1bc4b27d0438/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:5f8ca7f2bb6ba8348a3614c7918cc4bb73268c5ac2a207576b7afea19d3d9f64", size = 1795196, upload-time = "2026-01-03T17:32:09.59Z" },
-    { url = "https://files.pythonhosted.org/packages/32/11/b30e1b1cd1f3054af86ebe60df96989c6a414dd87e27ad16950eee420bea/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:b0d95340658b9d2f11d9697f59b3814a9d3bb4b7a7c20b131df4bcef464037c0", size = 1782841, upload-time = "2026-01-03T17:32:11.445Z" },
-    { url = "https://files.pythonhosted.org/packages/88/0d/d98a9367b38912384a17e287850f5695c528cff0f14f791ce8ee2e4f7796/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:a1e53262fd202e4b40b70c3aff944a8155059beedc8a89bba9dc1f9ef06a1b56", size = 1795193, upload-time = "2026-01-03T17:32:13.705Z" },
-    { url = "https://files.pythonhosted.org/packages/43/a5/a2dfd1f5ff5581632c7f6a30e1744deda03808974f94f6534241ef60c751/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:d60ac9663f44168038586cab2157e122e46bdef09e9368b37f2d82d354c23f72", size = 1621979, upload-time = "2026-01-03T17:32:15.965Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/f0/12973c382ae7c1cccbc4417e129c5bf54c374dfb85af70893646e1f0e749/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:90751b8eed69435bac9ff4e3d2f6b3af1f57e37ecb0fbeee59c0174c9e2d41df", size = 1822193, upload-time = "2026-01-03T17:32:18.219Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/5f/24155e30ba7f8c96918af1350eb0663e2430aad9e001c0489d89cd708ab1/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:fc353029f176fd2b3ec6cfc71be166aba1936fe5d73dd1992ce289ca6647a9aa", size = 1769801, upload-time = "2026-01-03T17:32:20.25Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/f8/7314031ff5c10e6ece114da79b338ec17eeff3a079e53151f7e9f43c4723/aiohttp-3.13.3-cp314-cp314t-win32.whl", hash = "sha256:2e41b18a58da1e474a057b3d35248d8320029f61d70a37629535b16a0c8f3767", size = 466523, upload-time = "2026-01-03T17:32:22.215Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/63/278a98c715ae467624eafe375542d8ba9b4383a016df8fdefe0ae28382a7/aiohttp-3.13.3-cp314-cp314t-win_amd64.whl", hash = "sha256:44531a36aa2264a1860089ffd4dce7baf875ee5a6079d5fb42e261c704ef7344", size = 499694, upload-time = "2026-01-03T17:32:24.546Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/7e/cb94129302d78c46662b47f9897d642fd0b33bdfef4b73b20c6ced35aa4c/aiohttp-3.13.4-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:8ea0c64d1bcbf201b285c2246c51a0c035ba3bbd306640007bc5844a3b4658c1", size = 760027, upload-time = "2026-03-28T17:15:33.022Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/cd/2db3c9397c3bd24216b203dd739945b04f8b87bb036c640da7ddb63c75ef/aiohttp-3.13.4-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6f742e1fa45c0ed522b00ede565e18f97e4cf8d1883a712ac42d0339dfb0cce7", size = 508325, upload-time = "2026-03-28T17:15:34.714Z" },
+    { url = "https://files.pythonhosted.org/packages/36/a3/d28b2722ec13107f2e37a86b8a169897308bab6a3b9e071ecead9d67bd9b/aiohttp-3.13.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:6dcfb50ee25b3b7a1222a9123be1f9f89e56e67636b561441f0b304e25aaef8f", size = 502402, upload-time = "2026-03-28T17:15:36.409Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/d6/acd47b5f17c4430e555590990a4746efbcb2079909bb865516892bf85f37/aiohttp-3.13.4-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3262386c4ff370849863ea93b9ea60fd59c6cf56bf8f93beac625cf4d677c04d", size = 1771224, upload-time = "2026-03-28T17:15:38.223Z" },
+    { url = "https://files.pythonhosted.org/packages/98/af/af6e20113ba6a48fd1cd9e5832c4851e7613ef50c7619acdaee6ec5f1aff/aiohttp-3.13.4-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:473bb5aa4218dd254e9ae4834f20e31f5a0083064ac0136a01a62ddbae2eaa42", size = 1731530, upload-time = "2026-03-28T17:15:39.988Z" },
+    { url = "https://files.pythonhosted.org/packages/81/16/78a2f5d9c124ad05d5ce59a9af94214b6466c3491a25fb70760e98e9f762/aiohttp-3.13.4-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e56423766399b4c77b965f6aaab6c9546617b8994a956821cc507d00b91d978c", size = 1827925, upload-time = "2026-03-28T17:15:41.944Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/1f/79acf0974ced805e0e70027389fccbb7d728e6f30fcac725fb1071e63075/aiohttp-3.13.4-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8af249343fafd5ad90366a16d230fc265cf1149f26075dc9fe93cfd7c7173942", size = 1923579, upload-time = "2026-03-28T17:15:44.071Z" },
+    { url = "https://files.pythonhosted.org/packages/af/53/29f9e2054ea6900413f3b4c3eb9d8331f60678ec855f13ba8714c47fd48d/aiohttp-3.13.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0bc0a5cf4f10ef5a2c94fdde488734b582a3a7a000b131263e27c9295bd682d9", size = 1767655, upload-time = "2026-03-28T17:15:45.911Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/57/462fe1d3da08109ba4aa8590e7aed57c059af2a7e80ec21f4bac5cfe1094/aiohttp-3.13.4-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:5c7ff1028e3c9fc5123a865ce17df1cb6424d180c503b8517afbe89aa566e6be", size = 1630439, upload-time = "2026-03-28T17:15:48.11Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/4b/4813344aacdb8127263e3eec343d24e973421143826364fa9fc847f6283f/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:ba5cf98b5dcb9bddd857da6713a503fa6d341043258ca823f0f5ab7ab4a94ee8", size = 1745557, upload-time = "2026-03-28T17:15:50.13Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/01/1ef1adae1454341ec50a789f03cfafe4c4ac9c003f6a64515ecd32fe4210/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:d85965d3ba21ee4999e83e992fecb86c4614d6920e40705501c0a1f80a583c12", size = 1741796, upload-time = "2026-03-28T17:15:52.351Z" },
+    { url = "https://files.pythonhosted.org/packages/22/04/8cdd99af988d2aa6922714d957d21383c559835cbd43fbf5a47ddf2e0f05/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:49f0b18a9b05d79f6f37ddd567695943fcefb834ef480f17a4211987302b2dc7", size = 1805312, upload-time = "2026-03-28T17:15:54.407Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/7f/b48d5577338d4b25bbdbae35c75dbfd0493cb8886dc586fbfb2e90862239/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:7f78cb080c86fbf765920e5f1ef35af3f24ec4314d6675d0a21eaf41f6f2679c", size = 1621751, upload-time = "2026-03-28T17:15:56.564Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/89/4eecad8c1858e6d0893c05929e22343e0ebe3aec29a8a399c65c3cc38311/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:67a3ec705534a614b68bbf1c70efa777a21c3da3895d1c44510a41f5a7ae0453", size = 1826073, upload-time = "2026-03-28T17:15:58.489Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/5c/9dc8293ed31b46c39c9c513ac7ca152b3c3d38e0ea111a530ad12001b827/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:d6630ec917e85c5356b2295744c8a97d40f007f96a1c76bf1928dc2e27465393", size = 1760083, upload-time = "2026-03-28T17:16:00.677Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/19/8bbf6a4994205d96831f97b7d21a0feed120136e6267b5b22d229c6dc4dc/aiohttp-3.13.4-cp311-cp311-win32.whl", hash = "sha256:54049021bc626f53a5394c29e8c444f726ee5a14b6e89e0ad118315b1f90f5e3", size = 439690, upload-time = "2026-03-28T17:16:02.902Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/f5/ac409ecd1007528d15c3e8c3a57d34f334c70d76cfb7128a28cffdebd4c1/aiohttp-3.13.4-cp311-cp311-win_amd64.whl", hash = "sha256:c033f2bc964156030772d31cbf7e5defea181238ce1f87b9455b786de7d30145", size = 463824, upload-time = "2026-03-28T17:16:05.058Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/bd/ede278648914cabbabfdf95e436679b5d4156e417896a9b9f4587169e376/aiohttp-3.13.4-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ee62d4471ce86b108b19c3364db4b91180d13fe3510144872d6bad5401957360", size = 752158, upload-time = "2026-03-28T17:16:06.901Z" },
+    { url = "https://files.pythonhosted.org/packages/90/de/581c053253c07b480b03785196ca5335e3c606a37dc73e95f6527f1591fe/aiohttp-3.13.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c0fd8f41b54b58636402eb493afd512c23580456f022c1ba2db0f810c959ed0d", size = 501037, upload-time = "2026-03-28T17:16:08.82Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/f9/a5ede193c08f13cc42c0a5b50d1e246ecee9115e4cf6e900d8dbd8fd6acb/aiohttp-3.13.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:4baa48ce49efd82d6b1a0be12d6a36b35e5594d1dd42f8bfba96ea9f8678b88c", size = 501556, upload-time = "2026-03-28T17:16:10.63Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/10/88ff67cd48a6ec36335b63a640abe86135791544863e0cfe1f065d6cef7a/aiohttp-3.13.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d738ebab9f71ee652d9dbd0211057690022201b11197f9a7324fd4dba128aa97", size = 1757314, upload-time = "2026-03-28T17:16:12.498Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/15/fdb90a5cf5a1f52845c276e76298c75fbbcc0ac2b4a86551906d54529965/aiohttp-3.13.4-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:0ce692c3468fa831af7dceed52edf51ac348cebfc8d3feb935927b63bd3e8576", size = 1731819, upload-time = "2026-03-28T17:16:14.558Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/df/28146785a007f7820416be05d4f28cc207493efd1e8c6c1068e9bdc29198/aiohttp-3.13.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8e08abcfe752a454d2cb89ff0c08f2d1ecd057ae3e8cc6d84638de853530ebab", size = 1793279, upload-time = "2026-03-28T17:16:16.594Z" },
+    { url = "https://files.pythonhosted.org/packages/10/47/689c743abf62ea7a77774d5722f220e2c912a77d65d368b884d9779ef41b/aiohttp-3.13.4-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5977f701b3fff36367a11087f30ea73c212e686d41cd363c50c022d48b011d8d", size = 1891082, upload-time = "2026-03-28T17:16:18.71Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/b6/f7f4f318c7e58c23b761c9b13b9a3c9b394e0f9d5d76fbc6622fa98509f6/aiohttp-3.13.4-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:54203e10405c06f8b6020bd1e076ae0fe6c194adcee12a5a78af3ffa3c57025e", size = 1773938, upload-time = "2026-03-28T17:16:21.125Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/06/f207cb3121852c989586a6fc16ff854c4fcc8651b86c5d3bd1fc83057650/aiohttp-3.13.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:358a6af0145bc4dda037f13167bef3cce54b132087acc4c295c739d05d16b1c3", size = 1579548, upload-time = "2026-03-28T17:16:23.588Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/58/e1289661a32161e24c1fe479711d783067210d266842523752869cc1d9c2/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:898ea1850656d7d61832ef06aa9846ab3ddb1621b74f46de78fbc5e1a586ba83", size = 1714669, upload-time = "2026-03-28T17:16:25.713Z" },
+    { url = "https://files.pythonhosted.org/packages/96/0a/3e86d039438a74a86e6a948a9119b22540bae037d6ba317a042ae3c22711/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:7bc30cceb710cf6a44e9617e43eebb6e3e43ad855a34da7b4b6a73537d8a6763", size = 1754175, upload-time = "2026-03-28T17:16:28.18Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/30/e717fc5df83133ba467a560b6d8ef20197037b4bb5d7075b90037de1018e/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:4a31c0c587a8a038f19a4c7e60654a6c899c9de9174593a13e7cc6e15ff271f9", size = 1762049, upload-time = "2026-03-28T17:16:30.941Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/28/8f7a2d4492e336e40005151bdd94baf344880a4707573378579f833a64c1/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:2062f675f3fe6e06d6113eb74a157fb9df58953ffed0cdb4182554b116545758", size = 1570861, upload-time = "2026-03-28T17:16:32.953Z" },
+    { url = "https://files.pythonhosted.org/packages/78/45/12e1a3d0645968b1c38de4b23fdf270b8637735ea057d4f84482ff918ad9/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:3d1ba8afb847ff80626d5e408c1fdc99f942acc877d0702fe137015903a220a9", size = 1790003, upload-time = "2026-03-28T17:16:35.468Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/0f/60374e18d590de16dcb39d6ff62f39c096c1b958e6f37727b5870026ea30/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:b08149419994cdd4d5eecf7fd4bc5986b5a9380285bcd01ab4c0d6bfca47b79d", size = 1737289, upload-time = "2026-03-28T17:16:38.187Z" },
+    { url = "https://files.pythonhosted.org/packages/02/bf/535e58d886cfbc40a8b0013c974afad24ef7632d645bca0b678b70033a60/aiohttp-3.13.4-cp312-cp312-win32.whl", hash = "sha256:fc432f6a2c4f720180959bc19aa37259651c1a4ed8af8afc84dd41c60f15f791", size = 434185, upload-time = "2026-03-28T17:16:40.735Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/1a/d92e3325134ebfff6f4069f270d3aac770d63320bd1fcd0eca023e74d9a8/aiohttp-3.13.4-cp312-cp312-win_amd64.whl", hash = "sha256:6148c9ae97a3e8bff9a1fc9c757fa164116f86c100468339730e717590a3fb77", size = 461285, upload-time = "2026-03-28T17:16:42.713Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/ac/892f4162df9b115b4758d615f32ec63d00f3084c705ff5526630887b9b42/aiohttp-3.13.4-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:63dd5e5b1e43b8fb1e91b79b7ceba1feba588b317d1edff385084fcc7a0a4538", size = 745744, upload-time = "2026-03-28T17:16:44.67Z" },
+    { url = "https://files.pythonhosted.org/packages/97/a9/c5b87e4443a2f0ea88cb3000c93a8fdad1ee63bffc9ded8d8c8e0d66efc6/aiohttp-3.13.4-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:746ac3cc00b5baea424dacddea3ec2c2702f9590de27d837aa67004db1eebc6e", size = 498178, upload-time = "2026-03-28T17:16:46.766Z" },
+    { url = "https://files.pythonhosted.org/packages/94/42/07e1b543a61250783650df13da8ddcdc0d0a5538b2bd15cef6e042aefc61/aiohttp-3.13.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:bda8f16ea99d6a6705e5946732e48487a448be874e54a4f73d514660ff7c05d3", size = 498331, upload-time = "2026-03-28T17:16:48.9Z" },
+    { url = "https://files.pythonhosted.org/packages/20/d6/492f46bf0328534124772d0cf58570acae5b286ea25006900650f69dae0e/aiohttp-3.13.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4b061e7b5f840391e3f64d0ddf672973e45c4cfff7a0feea425ea24e51530fc2", size = 1744414, upload-time = "2026-03-28T17:16:50.968Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/4d/e02627b2683f68051246215d2d62b2d2f249ff7a285e7a858dc47d6b6a14/aiohttp-3.13.4-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:b252e8d5cd66184b570d0d010de742736e8a4fab22c58299772b0c5a466d4b21", size = 1719226, upload-time = "2026-03-28T17:16:53.173Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/6c/5d0a3394dd2b9f9aeba6e1b6065d0439e4b75d41f1fb09a3ec010b43552b/aiohttp-3.13.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:20af8aad61d1803ff11152a26146d8d81c266aa8c5aa9b4504432abb965c36a0", size = 1782110, upload-time = "2026-03-28T17:16:55.362Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/2d/c20791e3437700a7441a7edfb59731150322424f5aadf635602d1d326101/aiohttp-3.13.4-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:13a5cc924b59859ad2adb1478e31f410a7ed46e92a2a619d6d1dd1a63c1a855e", size = 1884809, upload-time = "2026-03-28T17:16:57.734Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/94/d99dbfbd1924a87ef643833932eb2a3d9e5eee87656efea7d78058539eff/aiohttp-3.13.4-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:534913dfb0a644d537aebb4123e7d466d94e3be5549205e6a31f72368980a81a", size = 1764938, upload-time = "2026-03-28T17:17:00.221Z" },
+    { url = "https://files.pythonhosted.org/packages/49/61/3ce326a1538781deb89f6cf5e094e2029cd308ed1e21b2ba2278b08426f6/aiohttp-3.13.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:320e40192a2dcc1cf4b5576936e9652981ab596bf81eb309535db7e2f5b5672f", size = 1570697, upload-time = "2026-03-28T17:17:02.985Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/77/4ab5a546857bb3028fbaf34d6eea180267bdab022ee8b1168b1fcde4bfdd/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:9e587fcfce2bcf06526a43cb705bdee21ac089096f2e271d75de9c339db3100c", size = 1702258, upload-time = "2026-03-28T17:17:05.28Z" },
+    { url = "https://files.pythonhosted.org/packages/79/63/d8f29021e39bc5af8e5d5e9da1b07976fb9846487a784e11e4f4eeda4666/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:9eb9c2eea7278206b5c6c1441fdd9dc420c278ead3f3b2cc87f9b693698cc500", size = 1740287, upload-time = "2026-03-28T17:17:07.712Z" },
+    { url = "https://files.pythonhosted.org/packages/55/3a/cbc6b3b124859a11bc8055d3682c26999b393531ef926754a3445b99dfef/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:29be00c51972b04bf9d5c8f2d7f7314f48f96070ca40a873a53056e652e805f7", size = 1753011, upload-time = "2026-03-28T17:17:10.053Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/30/836278675205d58c1368b21520eab9572457cf19afd23759216c04483048/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:90c06228a6c3a7c9f776fe4fc0b7ff647fffd3bed93779a6913c804ae00c1073", size = 1566359, upload-time = "2026-03-28T17:17:12.433Z" },
+    { url = "https://files.pythonhosted.org/packages/50/b4/8032cc9b82d17e4277704ba30509eaccb39329dc18d6a35f05e424439e32/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:a533ec132f05fd9a1d959e7f34184cd7d5e8511584848dab85faefbaac573069", size = 1785537, upload-time = "2026-03-28T17:17:14.721Z" },
+    { url = "https://files.pythonhosted.org/packages/17/7d/5873e98230bde59f493bf1f7c3e327486a4b5653fa401144704df5d00211/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:1c946f10f413836f82ea4cfb90200d2a59578c549f00857e03111cf45ad01ca5", size = 1740752, upload-time = "2026-03-28T17:17:17.387Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/f2/13e46e0df051494d7d3c68b7f72d071f48c384c12716fc294f75d5b1a064/aiohttp-3.13.4-cp313-cp313-win32.whl", hash = "sha256:48708e2706106da6967eff5908c78ca3943f005ed6bcb75da2a7e4da94ef8c70", size = 433187, upload-time = "2026-03-28T17:17:19.523Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/c0/649856ee655a843c8f8664592cfccb73ac80ede6a8c8db33a25d810c12db/aiohttp-3.13.4-cp313-cp313-win_amd64.whl", hash = "sha256:74a2eb058da44fa3a877a49e2095b591d4913308bb424c418b77beb160c55ce3", size = 459778, upload-time = "2026-03-28T17:17:21.964Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/29/6657cc37ae04cacc2dbf53fb730a06b6091cc4cbe745028e047c53e6d840/aiohttp-3.13.4-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:e0a2c961fc92abeff61d6444f2ce6ad35bb982db9fc8ff8a47455beacf454a57", size = 749363, upload-time = "2026-03-28T17:17:24.044Z" },
+    { url = "https://files.pythonhosted.org/packages/90/7f/30ccdf67ca3d24b610067dc63d64dcb91e5d88e27667811640644aa4a85d/aiohttp-3.13.4-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:153274535985a0ff2bff1fb6c104ed547cec898a09213d21b0f791a44b14d933", size = 499317, upload-time = "2026-03-28T17:17:26.199Z" },
+    { url = "https://files.pythonhosted.org/packages/93/13/e372dd4e68ad04ee25dafb050c7f98b0d91ea643f7352757e87231102555/aiohttp-3.13.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:351f3171e2458da3d731ce83f9e6b9619e325c45cbd534c7759750cabf453ad7", size = 500477, upload-time = "2026-03-28T17:17:28.279Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/fe/ee6298e8e586096fb6f5eddd31393d8544f33ae0792c71ecbb4c2bef98ac/aiohttp-3.13.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f989ac8bc5595ff761a5ccd32bdb0768a117f36dd1504b1c2c074ed5d3f4df9c", size = 1737227, upload-time = "2026-03-28T17:17:30.587Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/b9/a7a0463a09e1a3fe35100f74324f23644bfc3383ac5fd5effe0722a5f0b7/aiohttp-3.13.4-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:d36fc1709110ec1e87a229b201dd3ddc32aa01e98e7868083a794609b081c349", size = 1694036, upload-time = "2026-03-28T17:17:33.29Z" },
+    { url = "https://files.pythonhosted.org/packages/57/7c/8972ae3fb7be00a91aee6b644b2a6a909aedb2c425269a3bfd90115e6f8f/aiohttp-3.13.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:42adaeea83cbdf069ab94f5103ce0787c21fb1a0153270da76b59d5578302329", size = 1786814, upload-time = "2026-03-28T17:17:36.035Z" },
+    { url = "https://files.pythonhosted.org/packages/93/01/c81e97e85c774decbaf0d577de7d848934e8166a3a14ad9f8aa5be329d28/aiohttp-3.13.4-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:92deb95469928cc41fd4b42a95d8012fa6df93f6b1c0a83af0ffbc4a5e218cde", size = 1866676, upload-time = "2026-03-28T17:17:38.441Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/5f/5b46fe8694a639ddea2cd035bf5729e4677ea882cb251396637e2ef1590d/aiohttp-3.13.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0c0c7c07c4257ef3a1df355f840bc62d133bcdef5c1c5ba75add3c08553e2eed", size = 1740842, upload-time = "2026-03-28T17:17:40.783Z" },
+    { url = "https://files.pythonhosted.org/packages/20/a2/0d4b03d011cca6b6b0acba8433193c1e484efa8d705ea58295590fe24203/aiohttp-3.13.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f062c45de8a1098cb137a1898819796a2491aec4e637a06b03f149315dff4d8f", size = 1566508, upload-time = "2026-03-28T17:17:43.235Z" },
+    { url = "https://files.pythonhosted.org/packages/98/17/e689fd500da52488ec5f889effd6404dece6a59de301e380f3c64f167beb/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:76093107c531517001114f0ebdb4f46858ce818590363e3e99a4a2280334454a", size = 1700569, upload-time = "2026-03-28T17:17:46.165Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/0d/66402894dbcf470ef7db99449e436105ea862c24f7ea4c95c683e635af35/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:6f6ec32162d293b82f8b63a16edc80769662fbd5ae6fbd4936d3206a2c2cc63b", size = 1707407, upload-time = "2026-03-28T17:17:48.825Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/eb/af0ab1a3650092cbd8e14ef29e4ab0209e1460e1c299996c3f8288b3f1ff/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:5903e2db3d202a00ad9f0ec35a122c005e85d90c9836ab4cda628f01edf425e2", size = 1752214, upload-time = "2026-03-28T17:17:51.206Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/bf/72326f8a98e4c666f292f03c385545963cc65e358835d2a7375037a97b57/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:2d5bea57be7aca98dbbac8da046d99b5557c5cf4e28538c4c786313078aca09e", size = 1562162, upload-time = "2026-03-28T17:17:53.634Z" },
+    { url = "https://files.pythonhosted.org/packages/67/9f/13b72435f99151dd9a5469c96b3b5f86aa29b7e785ca7f35cf5e538f74c0/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:bcf0c9902085976edc0232b75006ef38f89686901249ce14226b6877f88464fb", size = 1768904, upload-time = "2026-03-28T17:17:55.991Z" },
+    { url = "https://files.pythonhosted.org/packages/18/bc/28d4970e7d5452ac7776cdb5431a1164a0d9cf8bd2fffd67b4fb463aa56d/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:c3295f98bfeed2e867cab588f2a146a9db37a85e3ae9062abf46ba062bd29165", size = 1723378, upload-time = "2026-03-28T17:17:58.348Z" },
+    { url = "https://files.pythonhosted.org/packages/53/74/b32458ca1a7f34d65bdee7aef2036adbe0438123d3d53e2b083c453c24dd/aiohttp-3.13.4-cp314-cp314-win32.whl", hash = "sha256:a598a5c5767e1369d8f5b08695cab1d8160040f796c4416af76fd773d229b3c9", size = 438711, upload-time = "2026-03-28T17:18:00.728Z" },
+    { url = "https://files.pythonhosted.org/packages/40/b2/54b487316c2df3e03a8f3435e9636f8a81a42a69d942164830d193beb56a/aiohttp-3.13.4-cp314-cp314-win_amd64.whl", hash = "sha256:c555db4bc7a264bead5a7d63d92d41a1122fcd39cc62a4db815f45ad46f9c2c8", size = 464977, upload-time = "2026-03-28T17:18:03.367Z" },
+    { url = "https://files.pythonhosted.org/packages/47/fb/e41b63c6ce71b07a59243bb8f3b457ee0c3402a619acb9d2c0d21ef0e647/aiohttp-3.13.4-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:45abbbf09a129825d13c18c7d3182fecd46d9da3cfc383756145394013604ac1", size = 781549, upload-time = "2026-03-28T17:18:05.779Z" },
+    { url = "https://files.pythonhosted.org/packages/97/53/532b8d28df1e17e44c4d9a9368b78dcb6bf0b51037522136eced13afa9e8/aiohttp-3.13.4-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:74c80b2bc2c2adb7b3d1941b2b60701ee2af8296fc8aad8b8bc48bc25767266c", size = 514383, upload-time = "2026-03-28T17:18:08.096Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/1f/62e5d400603e8468cd635812d99cb81cfdc08127a3dc474c647615f31339/aiohttp-3.13.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c97989ae40a9746650fa196894f317dafc12227c808c774929dda0ff873a5954", size = 518304, upload-time = "2026-03-28T17:18:10.642Z" },
+    { url = "https://files.pythonhosted.org/packages/90/57/2326b37b10896447e3c6e0cbef4fe2486d30913639a5cfd1332b5d870f82/aiohttp-3.13.4-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:dae86be9811493f9990ef44fff1685f5c1a3192e9061a71a109d527944eed551", size = 1893433, upload-time = "2026-03-28T17:18:13.121Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/b4/a24d82112c304afdb650167ef2fe190957d81cbddac7460bedd245f765aa/aiohttp-3.13.4-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:1db491abe852ca2fa6cc48a3341985b0174b3741838e1341b82ac82c8bd9e871", size = 1755901, upload-time = "2026-03-28T17:18:16.21Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/2d/0883ef9d878d7846287f036c162a951968f22aabeef3ac97b0bea6f76d5d/aiohttp-3.13.4-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:0e5d701c0aad02a7dce72eef6b93226cf3734330f1a31d69ebbf69f33b86666e", size = 1876093, upload-time = "2026-03-28T17:18:18.703Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/52/9204bb59c014869b71971addad6778f005daa72a96eed652c496789d7468/aiohttp-3.13.4-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8ac32a189081ae0a10ba18993f10f338ec94341f0d5df8fff348043962f3c6f8", size = 1970815, upload-time = "2026-03-28T17:18:21.858Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/b5/e4eb20275a866dde0f570f411b36c6b48f7b53edfe4f4071aa1b0728098a/aiohttp-3.13.4-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:98e968cdaba43e45c73c3f306fca418c8009a957733bac85937c9f9cf3f4de27", size = 1816223, upload-time = "2026-03-28T17:18:24.729Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/23/e98075c5bb146aa61a1239ee1ac7714c85e814838d6cebbe37d3fe19214a/aiohttp-3.13.4-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:ca114790c9144c335d538852612d3e43ea0f075288f4849cf4b05d6cd2238ce7", size = 1649145, upload-time = "2026-03-28T17:18:27.269Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/c1/7bad8be33bb06c2bb224b6468874346026092762cbec388c3bdb65a368ee/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:ea2e071661ba9cfe11eabbc81ac5376eaeb3061f6e72ec4cc86d7cdd1ffbdbbb", size = 1816562, upload-time = "2026-03-28T17:18:29.847Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/10/c00323348695e9a5e316825969c88463dcc24c7e9d443244b8a2c9cf2eae/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:34e89912b6c20e0fd80e07fa401fd218a410aa1ce9f1c2f1dad6db1bd0ce0927", size = 1800333, upload-time = "2026-03-28T17:18:32.269Z" },
+    { url = "https://files.pythonhosted.org/packages/84/43/9b2147a1df3559f49bd723e22905b46a46c068a53adb54abdca32c4de180/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:0e217cf9f6a42908c52b46e42c568bd57adc39c9286ced31aaace614b6087965", size = 1820617, upload-time = "2026-03-28T17:18:35.238Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/7f/b3481a81e7a586d02e99387b18c6dafff41285f6efd3daa2124c01f87eae/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:0c296f1221e21ba979f5ac1964c3b78cfde15c5c5f855ffd2caab337e9cd9182", size = 1643417, upload-time = "2026-03-28T17:18:37.949Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/72/07181226bc99ce1124e0f89280f5221a82d3ae6a6d9d1973ce429d48e52b/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:d99a9d168ebaffb74f36d011750e490085ac418f4db926cce3989c8fe6cb6b1b", size = 1849286, upload-time = "2026-03-28T17:18:40.534Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/e6/1b3566e103eca6da5be4ae6713e112a053725c584e96574caf117568ffef/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:cb19177205d93b881f3f89e6081593676043a6828f59c78c17a0fd6c1fbed2ba", size = 1782635, upload-time = "2026-03-28T17:18:43.073Z" },
+    { url = "https://files.pythonhosted.org/packages/37/58/1b11c71904b8d079eb0c39fe664180dd1e14bebe5608e235d8bfbadc8929/aiohttp-3.13.4-cp314-cp314t-win32.whl", hash = "sha256:c606aa5656dab6552e52ca368e43869c916338346bfaf6304e15c58fb113ea30", size = 472537, upload-time = "2026-03-28T17:18:46.286Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/8f/87c56a1a1977d7dddea5b31e12189665a140fdb48a71e9038ff90bb564ec/aiohttp-3.13.4-cp314-cp314t-win_amd64.whl", hash = "sha256:014dcc10ec8ab8db681f0d68e939d1e9286a5aa2b993cbbdb0db130853e02144", size = 506381, upload-time = "2026-03-28T17:18:48.74Z" },
 ]

 [[package]]
@@ -274,14 +274,14 @@ wheels = [

 [[package]]
 name = "click"
-version = "8.3.1"
+version = "8.1.8"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "colorama", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/3d/fa/656b739db8587d7b5dfa22e22ed02566950fbfbcdc20311993483657a5c0/click-8.3.1.tar.gz", hash = "sha256:12ff4785d337a1bb490bb7e9c2b1ee5da3112e94a8622f26a6c77f5d2fc6842a", size = 295065, upload-time = "2025-11-15T20:45:42.706Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/b9/2e/0090cbf739cee7d23781ad4b89a9894a41538e4fcf4c31dcdd705b78eb8b/click-8.1.8.tar.gz", hash = "sha256:ed53c9d8990d83c2a27deae68e4ee337473f6330c040a31d4225c9574d16096a", size = 226593, upload-time = "2024-12-21T18:38:44.339Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/98/78/01c019cdb5d6498122777c1a43056ebb3ebfeef2076d9d026bfe15583b2b/click-8.3.1-py3-none-any.whl", hash = "sha256:981153a64e25f12d547d3426c367a4857371575ee7ad18df2a6183ab0545b2a6", size = 108274, upload-time = "2025-11-15T20:45:41.139Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/d4/7ebdbd03970677812aac39c869717059dbb71a4cfc033ca6e5221787892c/click-8.1.8-py3-none-any.whl", hash = "sha256:63c132bbbed01578a06712a2d1f497bb62d9c1c0d329b7903a866228027263b2", size = 98188, upload-time = "2024-12-21T18:38:41.666Z" },
 ]

 [[package]]
@@ -644,11 +644,11 @@ requires-dist = [
    { name = "coverage", marker = "extra == 'dev'", specifier = ">=7.6.0" },
    { name = "datasets", specifier = ">=3.0.0" },
    { name = "hypothesis", marker = "extra == 'dev'", specifier = ">=6.88.0" },
-    { name = "litellm", specifier = ">=1.50.0" },
+    { name = "litellm", specifier = "!=1.82.7,!=1.82.8,>=1.83.7" },
    { name = "mini-swe-agent", specifier = ">=2.0.0" },
    { name = "pandas", specifier = ">=2.0.0" },
-    { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0.0" },
-    { name = "python-dotenv", specifier = ">=1.0.0" },
+    { name = "pytest", marker = "extra == 'dev'", specifier = ">=9.0.3" },
+    { name = "python-dotenv", specifier = ">=1.2.2" },
    { name = "pyyaml", specifier = ">=6.0" },
    { name = "rich", specifier = ">=13.0.0" },
    { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.5.0" },
@@ -769,14 +769,14 @@ wheels = [

 [[package]]
 name = "importlib-metadata"
-version = "9.0.0"
+version = "8.5.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "zipp" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/a9/01/15bb152d77b21318514a96f43af312635eb2500c96b55398d020c93d86ea/importlib_metadata-9.0.0.tar.gz", hash = "sha256:a4f57ab599e6a2e3016d7595cfd72eb4661a5106e787a95bcc90c7105b831efc", size = 56405, upload-time = "2026-03-20T06:42:56.999Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/cd/12/33e59336dca5be0c398a7482335911a33aa0e20776128f038019f1a95f1b/importlib_metadata-8.5.0.tar.gz", hash = "sha256:71522656f0abace1d072b9e5481a48f07c138e00f079c38c8f883823f9c26bd7", size = 55304, upload-time = "2024-09-11T14:56:08.937Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/38/3d/2d244233ac4f76e38533cfcb2991c9eb4c7bf688ae0a036d30725b8faafe/importlib_metadata-9.0.0-py3-none-any.whl", hash = "sha256:2d21d1cc5a017bd0559e36150c21c830ab1dc304dedd1b7ea85d20f45ef3edd7", size = 27789, upload-time = "2026-03-20T06:42:55.665Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/d9/a1e041c5e7caa9a05c925f4bdbdfb7f006d1f74996af53467bc394c97be7/importlib_metadata-8.5.0-py3-none-any.whl", hash = "sha256:45e54197d28b7a7f1559e60b95e7c567032b602131fbd588f1497f47880aa68b", size = 26514, upload-time = "2024-09-11T14:56:07.019Z" },
 ]

 [[package]]
@@ -887,7 +887,7 @@ wheels = [

 [[package]]
 name = "jsonschema"
-version = "4.26.0"
+version = "4.23.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "attrs" },
@@ -895,9 +895,9 @@ dependencies = [
    { name = "referencing" },
    { name = "rpds-py" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b3/fc/e067678238fa451312d4c62bf6e6cf5ec56375422aee02f9cb5f909b3047/jsonschema-4.26.0.tar.gz", hash = "sha256:0c26707e2efad8aa1bfc5b7ce170f3fccc2e4918ff85989ba9ffa9facb2be326", size = 366583, upload-time = "2026-01-07T13:41:07.246Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/38/2e/03362ee4034a4c917f697890ccd4aec0800ccf9ded7f511971c75451deec/jsonschema-4.23.0.tar.gz", hash = "sha256:d71497fef26351a33265337fa77ffeb82423f3ea21283cd9467bb03999266bc4", size = 325778, upload-time = "2024-07-08T18:40:05.546Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/69/90/f63fb5873511e014207a475e2bb4e8b2e570d655b00ac19a9a0ca0a385ee/jsonschema-4.26.0-py3-none-any.whl", hash = "sha256:d489f15263b8d200f8387e64b4c3a75f06629559fb73deb8fdfb525f2dab50ce", size = 90630, upload-time = "2026-01-07T13:41:05.306Z" },
+    { url = "https://files.pythonhosted.org/packages/69/4a/4f9dbeb84e8850557c02365a0eee0649abe5eb1d84af92a25731c6c0f922/jsonschema-4.23.0-py3-none-any.whl", hash = "sha256:fbadb6f8b144a8f8cf9f0b89ba94501d143e50411a1278633f56a7acf7fd5566", size = 88462, upload-time = "2024-07-08T18:40:00.165Z" },
 ]

 [[package]]
@@ -926,7 +926,7 @@ wheels = [

 [[package]]
 name = "litellm"
-version = "1.82.6"
+version = "1.83.14"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "aiohttp" },
@@ -942,9 +942,9 @@ dependencies = [
    { name = "tiktoken" },
    { name = "tokenizers" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/29/75/1c537aa458426a9127a92bc2273787b2f987f4e5044e21f01f2eed5244fd/litellm-1.82.6.tar.gz", hash = "sha256:2aa1c2da21fe940c33613aa447119674a3ad4d2ad5eb064e4d5ce5ee42420136", size = 17414147, upload-time = "2026-03-22T06:36:00.452Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/8d/7c/c095649380adc96c8630273c1768c2ad1e74aa2ee1dd8dd05d218a60569f/litellm-1.83.14.tar.gz", hash = "sha256:24aef9b47cdc424c833e32f3727f411741c690832cd1fe4405e0077144fe09c9", size = 14836599, upload-time = "2026-04-26T03:16:10.176Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/02/6c/5327667e6dbe9e98cbfbd4261c8e91386a52e38f41419575854248bbab6a/litellm-1.82.6-py3-none-any.whl", hash = "sha256:164a3ef3e19f309e3cabc199bef3d2045212712fefdfa25fc7f75884a5b5b205", size = 15591595, upload-time = "2026-03-22T06:35:56.795Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/5c/1b5691575420135e90578543b2bf219497caa33cfd0af64cb38f30288450/litellm-1.83.14-py3-none-any.whl", hash = "sha256:92b11ba2a32cf80707ddf388d18526696c7999a21b418c5e3b6eda1243d2cfdb", size = 16457054, upload-time = "2026-04-26T03:16:05.72Z" },
 ]

 [[package]]
@@ -1302,7 +1302,7 @@ wheels = [

 [[package]]
 name = "openai"
-version = "2.29.0"
+version = "2.24.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "anyio" },
@@ -1314,9 +1314,9 @@ dependencies = [
    { name = "tqdm" },
    { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b4/15/203d537e58986b5673e7f232453a2a2f110f22757b15921cbdeea392e520/openai-2.29.0.tar.gz", hash = "sha256:32d09eb2f661b38d3edd7d7e1a2943d1633f572596febe64c0cd370c86d52bec", size = 671128, upload-time = "2026-03-17T17:53:49.599Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/55/13/17e87641b89b74552ed408a92b231283786523edddc95f3545809fab673c/openai-2.24.0.tar.gz", hash = "sha256:1e5769f540dbd01cb33bc4716a23e67b9d695161a734aff9c5f925e2bf99a673", size = 658717, upload-time = "2026-02-24T20:02:07.958Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d0/b1/35b6f9c8cf9318e3dbb7146cc82dab4cf61182a8d5406fc9b50864362895/openai-2.29.0-py3-none-any.whl", hash = "sha256:b7c5de513c3286d17c5e29b92c4c98ceaf0d775244ac8159aeb1bddf840eb42a", size = 1141533, upload-time = "2026-03-17T17:53:47.348Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/30/844dc675ee6902579b8eef01ed23917cc9319a1c9c0c14ec6e39340c96d0/openai-2.24.0-py3-none-any.whl", hash = "sha256:fed30480d7d6c884303287bde864980a4b137b60553ffbcf9ab4a233b7a73d94", size = 1120122, upload-time = "2026-02-24T20:02:05.669Z" },
 ]

 [[package]]
@@ -1690,7 +1690,7 @@ wheels = [

 [[package]]
 name = "pytest"
-version = "9.0.2"
+version = "9.0.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "colorama", marker = "sys_platform == 'win32'" },
@@ -1699,9 +1699,9 @@ dependencies = [
    { name = "pluggy" },
    { name = "pygments" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/d1/db/7ef3487e0fb0049ddb5ce41d3a49c235bf9ad299b6a25d5780a89f19230f/pytest-9.0.2.tar.gz", hash = "sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11", size = 1568901, upload-time = "2025-12-06T21:30:51.014Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/549bd94f1a0a402dc8cf64563a117c0f3765662e2e668477624baeec44d5/pytest-9.0.3.tar.gz", hash = "sha256:b86ada508af81d19edeb213c681b1d48246c1a91d304c6c81a427674c17eb91c", size = 1572165, upload-time = "2026-04-07T17:16:18.027Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" },
 ]

 [[package]]
@@ -1900,7 +1900,7 @@ wheels = [

 [[package]]
 name = "requests"
-version = "2.32.5"
+version = "2.33.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "certifi" },
@@ -1908,9 +1908,9 @@ dependencies = [
    { name = "idna" },
    { name = "urllib3" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/c9/74/b3ff8e6c8446842c3f5c837e9c3dfcfe2018ea6ecef224c710c85ef728f4/requests-2.32.5.tar.gz", hash = "sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf", size = 134517, upload-time = "2025-08-18T20:46:02.573Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/34/64/8860370b167a9721e8956ae116825caff829224fbca0ca6e7bf8ddef8430/requests-2.33.0.tar.gz", hash = "sha256:c7ebc5e8b0f21837386ad0e1c8fe8b829fa5f544d8df3b2253bff14ef29d7652", size = 134232, upload-time = "2026-03-25T15:10:41.586Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", size = 64738, upload-time = "2025-08-18T20:46:00.542Z" },
+    { url = "https://files.pythonhosted.org/packages/56/5d/c814546c2333ceea4ba42262d8c4d55763003e767fa169adc693bd524478/requests-2.33.0-py3-none-any.whl", hash = "sha256:3324635456fa185245e24865e810cecec7b4caf933d7eb133dcde67d48cee69b", size = 65017, upload-time = "2026-03-25T15:10:40.382Z" },
 ]

 [[package]]
@@ -2224,7 +2224,7 @@ wheels = [

 [[package]]
 name = "typer"
-version = "0.24.1"
+version = "0.23.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "annotated-doc" },
@@ -2232,9 +2232,9 @@ dependencies = [
    { name = "rich" },
    { name = "shellingham" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/f5/24/cb09efec5cc954f7f9b930bf8279447d24618bb6758d4f6adf2574c41780/typer-0.24.1.tar.gz", hash = "sha256:e39b4732d65fbdcde189ae76cf7cd48aeae72919dea1fdfc16593be016256b45", size = 118613, upload-time = "2026-02-21T16:54:40.609Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/fd/07/b822e1b307d40e263e8253d2384cf98c51aa2368cc7ba9a07e523a1d964b/typer-0.23.1.tar.gz", hash = "sha256:2070374e4d31c83e7b61362fd859aa683576432fd5b026b060ad6b4cd3b86134", size = 120047, upload-time = "2026-02-13T10:04:30.984Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4a/91/48db081e7a63bb37284f9fbcefda7c44c277b18b0e13fbc36ea2335b71e6/typer-0.24.1-py3-none-any.whl", hash = "sha256:112c1f0ce578bfb4cab9ffdabc68f031416ebcc216536611ba21f04e9aa84c9e", size = 56085, upload-time = "2026-02-21T16:54:41.616Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/91/9b286ab899c008c2cb05e8be99814807e7fbbd33f0c0c960470826e5ac82/typer-0.23.1-py3-none-any.whl", hash = "sha256:3291ad0d3c701cbf522012faccfbb29352ff16ad262db2139e6b01f15781f14e", size = 56813, upload-time = "2026-02-13T10:04:32.008Z" },
 ]

 [[package]]
@@ -31,11 +31,25 @@ function readInput() {
 * Find the .gitnexus directory by walking up from startDir.
 * Returns the path to .gitnexus/ or null if not found.
 */
-function findGitNexusDir(startDir) {
-  let dir = startDir || process.cwd();
+function isGlobalRegistryDir(candidate) {
+  if (fs.existsSync(path.join(candidate, 'meta.json'))) return false;
+  return (
+    fs.existsSync(path.join(candidate, 'registry.json')) ||
+    fs.existsSync(path.join(candidate, 'repos'))
+  );
+}
+
+/**
+ * Walk up from `startDir` looking for a non-registry `.gitnexus/` folder.
+ * Returns the path to `.gitnexus/` or null if not found within 5 levels.
+ */
+function walkForGitNexusDir(startDir) {
+  let dir = startDir;
  for (let i = 0; i < 5; i++) {
    const candidate = path.join(dir, '.gitnexus');
-    if (fs.existsSync(candidate)) return candidate;
+    if (fs.existsSync(candidate)) {
+      if (!isGlobalRegistryDir(candidate)) return candidate;
+    }
    const parent = path.dirname(dir);
    if (parent === dir) break;
    dir = parent;
@@ -43,6 +57,51 @@ function findGitNexusDir(startDir) {
  return null;
 }

+/**
+ * Resolve the canonical (main) worktree root for `cwd`, when `cwd` is inside
+ * any git working tree — including a *linked* worktree created via
+ * `git worktree add`. Linked worktrees never contain `.gitnexus/`, so the
+ * upward walk from cwd alone misses the index. Returns null when `cwd` is
+ * not inside a git repo or `git` is not available.
+ *
+ * Implementation: `git rev-parse --git-common-dir` resolves to the canonical
+ * `.git/` directory (or `.git/worktrees/...` parent) that is shared across
+ * all linked worktrees. The canonical repo root is its parent directory.
+ */
+function findCanonicalRepoRoot(cwd) {
+  try {
+    const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      encoding: 'utf-8',
+      timeout: 2000,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.error || result.status !== 0) return null;
+    const commonDir = (result.stdout || '').trim();
+    if (!commonDir || !path.isAbsolute(commonDir)) return null;
+    return path.dirname(commonDir);
+  } catch {
+    return null;
+  }
+}
+
+function findGitNexusDir(startDir) {
+  const cwd = startDir || process.cwd();
+
+  // Fast path: the cwd is inside the canonical repo (most common case).
+  const fromCwd = walkForGitNexusDir(cwd);
+  if (fromCwd) return fromCwd;
+
+  // Fallback: cwd may be inside a linked git worktree whose `.gitnexus/`
+  // only lives in the canonical repo root. Resolve the shared git dir
+  // and retry from there.
+  const canonicalRoot = findCanonicalRepoRoot(cwd);
+  if (canonicalRoot && canonicalRoot !== cwd) {
+    return walkForGitNexusDir(canonicalRoot);
+  }
+  return null;
+}
+
 /**
 * Extract search pattern from tool input.
 */
@@ -21,6 +21,7 @@ Run from the project root. This parses all source files, builds the knowledge gr
 |------|--------|
 | `--force` | Force full re-index even if up to date |
 | `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |

 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.

@@ -8,13 +8,13 @@
      "name": "gitnexus-shared",
      "version": "1.0.0",
      "devDependencies": {
-        "typescript": "^6.0.2"
+        "typescript": "^6.0.3"
      }
    },
    "node_modules/typescript": {
-      "version": "6.0.2",
-      "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.2.tgz",
-      "integrity": "sha512-bGdAIrZ0wiGDo5l8c++HWtbaNCWTS4UTv7RaTH/ThVIgjkveJt83m74bBHMJkuCbslY8ixgLBVZJIOiQlQTjfQ==",
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
+      "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
      "dev": true,
      "license": "Apache-2.0",
      "bin": {
@@ -20,6 +20,6 @@
    "src"
  ],
  "devDependencies": {
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
  }
 }
@@ -134,7 +134,11 @@ export type {
 // Scope tree spine + position lookup (RFC §2.2 + §3.1; Ring 2 SHARED #912)
 export { makeScopeId, clearScopeIdInternPool } from './scope-resolution/scope-id.js';
 export type { ScopeIdInput } from './scope-resolution/scope-id.js';
-export { buildScopeTree, ScopeTreeInvariantError } from './scope-resolution/scope-tree.js';
+export {
+  buildScopeTree,
+  canParentScope,
+  ScopeTreeInvariantError,
+} from './scope-resolution/scope-tree.js';
 export type { ScopeTree } from './scope-resolution/scope-tree.js';
 export { buildPositionIndex } from './scope-resolution/position-index.js';
 export type { PositionIndex } from './scope-resolution/position-index.js';
@@ -26,9 +26,9 @@
 * (`resolveImportTarget`, `expandsWildcardTo`, `mergeBindings`) that
 * match the LanguageProvider surface from #911.
 *
- * **Dynamic imports rule.** `kind === 'dynamic-unresolved'` passes through
- * as an `ImportEdge { kind: 'dynamic-unresolved', targetFile: null }`
- * with no `BindingRef`. They are parse-time signals, not linkable targets.
+ * **Non-binding imports rule.** `dynamic-unresolved` passes through with
+ * `targetFile: null`; `dynamic-resolved` and `side-effect` resolve to
+ * file-level `ImportEdge`s. None of these materialize `BindingRef`s.
 */

 import type { SymbolDefinition } from './symbol-definition.js';
@@ -45,20 +45,28 @@ export interface FinalizeFile {
  /**
   * Defs exported from this file — the "what other files can import by name"
   * surface. Typically those with `isExported: true` (the module's own
-   * declarations) plus, for multi-hop re-export chains, the re-exported
-   * names the parser chose to surface here.
+   * declarations); parsers MAY also surface re-exported names here as a
+   * shortcut, but it is no longer required for correctness.
   *
   * **Multi-hop re-export contract.** `finalize` resolves an edge
-   * `A → B (importedName: 'X')` by looking up `X` in `B.localDefs`. If B
-   * only has `export { X } from './C'` and the parser *does not* include
-   * `X` in `B.localDefs`, A's edge hits the fixpoint cap and is marked
-   * `linkStatus: 'unresolved'`. The fixpoint does NOT mutate `localDefs`
-   * across iterations — it is static input.
+   * `A → B (importedName: 'X')` by first looking up `X` in `B.localDefs`.
+   * If `B` only has `export { X } from './C'` and does NOT surface `X` in
+   * its own `localDefs`, `finalize` falls back to the precomputed
+   * per-file re-export closure (`buildReexportClosures`), which encodes
+   * every name reachable through `B`'s named and wildcard re-exports —
+   * including transitively through cyclic SCCs. The lookup is O(1) and
+   * inherits the upstream `targetDefId`, populating `transitiveVia` with
+   * the file paths traversed to reach the leaf def.
   *
-   * Parsers that want multi-hop re-export chains to settle end-to-end must
-   * include re-exported names in the intermediate file's `localDefs` (with
-   * the original `DefId` of the source symbol). This keeps the algorithm
-   * O(1) per lookup and avoids graph-crawl during finalize.
+   * Surfacing re-exported names in `localDefs` is still a valid (and
+   * slightly cheaper) optimization: the direct lookup short-circuits the
+   * closure consult. Parsers SHOULD prefer surfacing names they can resolve
+   * statically (e.g., `export { X } from './c'` when `c.ts` is parsed in
+   * the same workspace), and rely on the closure for the long tail of
+   * barrel patterns.
+   *
+   * The fixpoint does NOT mutate `localDefs` across iterations — it is
+   * static input.
   */
  readonly localDefs: readonly SymbolDefinition[];
 }
@@ -85,7 +93,7 @@ export interface FinalizeHooks {
    targetRaw: string,
    fromFile: string,
    workspaceIndex: WorkspaceIndex,
-  ): string | null;
+  ): string | readonly string[] | null;

  /**
   * For a wildcard `import * from M`, return the names visible in the
@@ -119,20 +127,22 @@ export interface FinalizedScc {
 /**
 * Counters reported by `finalize`.
 *
- * **Counting granularity** — all edge counters are **per-`ParsedImport`**,
- * not per-materialized-`ImportEdge`. A single `wildcard` ParsedImport that
- * expands to N exports counts as one linked edge in these stats; the
- * materialized output (`FinalizeOutput.imports`) will have N edges for
- * that input. `dynamic-unresolved` ParsedImports count as linked (they
- * pass through with no `linkStatus`), so `linkedEdges` ≠ "has a
+ * **Counting granularity** — `totalEdges` is **per-generated-`ImportEdgeDraft`**,
+ * which may exceed the number of `ParsedImport` records when
+ * `resolveImportTarget` returns a multi-file array (e.g. Go package-scoped
+ * imports fan out to every `.go` file in the target directory). A single
+ * `wildcard` ParsedImport that expands to N exports also counts as one
+ * linked edge here; the materialized output (`FinalizeOutput.imports`) will
+ * have N edges for that input. `dynamic-unresolved` ParsedImports count as
+ * linked (they pass through with no `linkStatus`), so `linkedEdges` ≠ "has a
 * BindingRef" — use the `bindings` map for that.
 *
- * In other words: `totalEdges === input.parsedImports.length` summed
+ * In other words: `totalEdges >= input.parsedImports.length` summed
 * across files, and `linkedEdges + unresolvedEdges === totalEdges`.
 */
 export interface FinalizeStats {
  readonly totalFiles: number;
-  /** Total `ParsedImport` records seen across all files. */
+  /** Total `ImportEdgeDraft` records generated (≥ ParsedImport count). */
  readonly totalEdges: number;
  /**
   * `ParsedImport`s whose finalized edge does NOT carry
@@ -171,9 +181,9 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu
  for (const file of input.files) {
    const drafts: ImportEdgeDraft[] = [];
    for (const parsed of file.parsedImports) {
-      const draft = makeEdgeDraft(parsed, file, hooks, input.workspaceIndex);
-      drafts.push(draft);
-      totalEdges++;
+      const draftArray = makeEdgeDrafts(parsed, file, hooks, input.workspaceIndex);
+      drafts.push(...draftArray);
+      totalEdges += draftArray.length;
    }
    edgeIndex.set(file.filePath, drafts);
  }
@@ -186,7 +196,8 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu
    graph.set(file.filePath, new Set());
  }
  for (const [fromFile, drafts] of edgeIndex) {
-    const edges = graph.get(fromFile)!;
+    const edges = graph.get(fromFile);
+    if (edges === undefined) continue;
    for (const d of drafts) {
      if (d.targetFile !== null && byFilePath.has(d.targetFile)) {
        edges.add(d.targetFile);
@@ -197,6 +208,12 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu
  // ── Phase 2: Tarjan SCC → reverse-topological list of SCCs.
  const sccs = tarjanSccs(graph);

+  // ── Phase 2.5: precompute the per-file re-export closure (iterative,
+  // SCC-condensed). Eliminates the recursive crawl that the per-edge
+  // `tryFinalize` call site used to do; lookups are O(1) afterwards.
+  // See `buildReexportClosures` for the algorithm.
+  const reexportClosures = buildReexportClosures(input.files, byFilePath, edgeIndex);
+
  // ── Phase 3: process SCCs in reverse-topological order (leaves first).
  // Within each SCC, run a bounded fixpoint that resolves intra-SCC edges.
  // Edges leaving the SCC are already resolved (their target SCC is
@@ -217,10 +234,11 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu
      progressed = false;
      iterations++;
      for (const filePath of scc.files) {
-        const drafts = edgeIndex.get(filePath)!;
+        const drafts = edgeIndex.get(filePath);
+        if (drafts === undefined) continue;
        for (const draft of drafts) {
          if (draft.finalized !== null) continue;
-          const finalized = tryFinalize(draft, byFilePath);
+          const finalized = tryFinalize(draft, byFilePath, reexportClosures);
          if (finalized !== null) {
            draft.finalized = finalized;
            progressed = true;
@@ -231,7 +249,8 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu

    // Any drafts still not finalized within this SCC hit the cap → unresolved.
    for (const filePath of scc.files) {
-      const drafts = edgeIndex.get(filePath)!;
+      const drafts = edgeIndex.get(filePath);
+      if (drafts === undefined) continue;
      for (const draft of drafts) {
        if (draft.finalized !== null) continue;
        draft.finalized = {
@@ -245,10 +264,14 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu
  // ── Phase 4: collect finalized `ImportEdge[]` per module scope, preserving
  // input order within each file, and wildcard-expand where applicable.
  for (const file of input.files) {
-    const drafts = edgeIndex.get(file.filePath)!;
+    const drafts = edgeIndex.get(file.filePath);
+    if (drafts === undefined) continue;
    const finalized: ImportEdge[] = [];
    for (const d of drafts) {
-      const edge = d.finalized!;
+      const edge = d.finalized;
+      if (edge === null) {
+        throw new Error(`Invariant violated: import edge was not finalized for ${file.filePath}`);
+      }
      if (d.source.kind === 'wildcard' && edge.linkStatus !== 'unresolved') {
        // Produce one `wildcard-expanded` ImportEdge per exported name.
        const expanded = expandWildcard(edge, byFilePath, hooks, input.workspaceIndex);
@@ -299,12 +322,12 @@ interface ImportEdgeDraft {
  finalized: ImportEdge | null;
 }

-function makeEdgeDraft(
+function makeEdgeDrafts(
  parsed: ParsedImport,
  file: FinalizeFile,
  hooks: FinalizeHooks,
  workspace: WorkspaceIndex,
-): ImportEdgeDraft {
+): ImportEdgeDraft[] {
  // Dynamic-unresolved passes through — no `BindingRef`, no target file.
  if (parsed.kind === 'dynamic-unresolved') {
    const base: ImportEdge = {
@@ -313,59 +336,80 @@ function makeEdgeDraft(
      targetExportedName: '',
      kind: 'dynamic-unresolved',
    };
-    return {
-      source: parsed,
-      fromFile: file.filePath,
-      fromScope: file.moduleScope,
-      targetFile: null,
-      base,
-      finalized: base, // already fully finalized
-    };
+    return [
+      {
+        source: parsed,
+        fromFile: file.filePath,
+        fromScope: file.moduleScope,
+        targetFile: null,
+        base,
+        finalized: base, // already fully finalized
+      },
+    ];
  }

  const targetFile = hooks.resolveImportTarget(parsed.targetRaw ?? '', file.filePath, workspace);

  // Edge is unresolvable at the file level — mark unresolved now.
  if (targetFile === null) {
-    const edgeKind = parsed.kind === 'wildcard' ? 'wildcard-expanded' : parsed.kind;
-    const localName = parsed.kind === 'wildcard' ? '' : parsed.localName;
-    const targetExportedName = extractExportedName(parsed);
    const base: ImportEdge = {
-      localName,
+      localName: extractLocalName(parsed),
      targetFile: null,
-      targetExportedName,
-      kind: edgeKind,
+      targetExportedName: extractExportedName(parsed),
+      kind: edgeKindFor(parsed),
      linkStatus: 'unresolved',
    };
+    return [
+      {
+        source: parsed,
+        fromFile: file.filePath,
+        fromScope: file.moduleScope,
+        targetFile: null,
+        base,
+        finalized: base,
+      },
+    ];
+  }
+
+  // Resolvable at the file level; intra-SCC fixpoint may still fail to fill
+  // in `targetDefId` (e.g., symbol not exported from target). Side-effect
+  // and resolved-dynamic imports are terminal at the file level — no
+  // `targetDefId` needed since they materialize no `BindingRef`. Pre-
+  // finalize them here so the fixpoint loop skips them entirely.
+  const targetFiles = Array.isArray(targetFile) ? targetFile : [targetFile];
+  const isFileLevelTerminal = parsed.kind === 'side-effect' || parsed.kind === 'dynamic-resolved';
+  return targetFiles.map((tf) => {
+    const base: ImportEdge = {
+      localName: extractLocalName(parsed),
+      targetFile: tf,
+      targetExportedName: extractExportedName(parsed),
+      kind: edgeKindFor(parsed),
+    };
    return {
      source: parsed,
      fromFile: file.filePath,
      fromScope: file.moduleScope,
-      targetFile: null,
+      targetFile: tf,
      base,
-      finalized: base,
+      finalized: isFileLevelTerminal ? base : null,
    };
-  }
+  });
+}

-  // Resolvable at the file level; intra-SCC fixpoint may still fail to fill
-  // in `targetDefId` (e.g., symbol not exported from target).
-  const edgeKind = parsed.kind === 'wildcard' ? 'wildcard-expanded' : parsed.kind;
-  const localName = parsed.kind === 'wildcard' ? '' : parsed.localName;
-  const targetExportedName = extractExportedName(parsed);
-  const base: ImportEdge = {
-    localName,
-    targetFile,
-    targetExportedName,
-    kind: edgeKind,
-  };
-  return {
-    source: parsed,
-    fromFile: file.filePath,
-    fromScope: file.moduleScope,
-    targetFile,
-    base,
-    finalized: null,
-  };
+function edgeKindFor(parsed: ParsedImport): ImportEdge['kind'] {
+  if (parsed.kind === 'wildcard') return 'wildcard-expanded';
+  return parsed.kind;
+}
+
+function extractLocalName(parsed: ParsedImport): string {
+  switch (parsed.kind) {
+    case 'wildcard':
+    case 'side-effect':
+    case 'dynamic-resolved':
+      return '';
+    default:
+      return parsed.localName;
+  }
 }

 function extractExportedName(parsed: ParsedImport): string {
@@ -377,6 +421,8 @@ function extractExportedName(parsed: ParsedImport): string {
      return parsed.importedName;
    case 'wildcard':
    case 'dynamic-unresolved':
+    case 'dynamic-resolved':
+    case 'side-effect':
      return '';
  }
 }
@@ -386,6 +432,7 @@ function extractExportedName(parsed: ParsedImport): string {
 function tryFinalize(
  draft: ImportEdgeDraft,
  byFilePath: Map<string, FinalizeFile>,
+  reexportClosures: ReadonlyMap<string, FileReexportClosure>,
 ): ImportEdge | null {
  const targetFile = draft.targetFile;
  if (targetFile === null) return draft.base; // already terminal
@@ -423,22 +470,265 @@ function tryFinalize(
  const importedName = extractExportedName(draft.source);
  const exported = findExportByName(targetModule.localDefs, importedName);

-  if (exported === undefined) {
+  if (exported !== undefined) {
+    const transitiveVia =
+      draft.source.kind === 'reexport' ? Object.freeze([targetFile]) : undefined;
+    return {
+      ...draft.base,
+      targetModuleScope: targetModule.moduleScope,
+      targetDefId: exported.nodeId,
+      ...(transitiveVia !== undefined ? { transitiveVia } : {}),
+    };
+  }
+
+  // Multi-hop re-export follow. Barrel modules like
+  //   // models.ts
+  //   export { User } from './base';
+  // emit no local def for `User`; the name surfaces only via their own
+  // `reexport` edge. The per-file re-export closure built in phase 2.5
+  // already encodes every name reachable through that file's named and
+  // wildcard re-exports — including transitively through cyclic SCCs —
+  // so the lookup is O(1) and never recurses.
+  const followed = lookupReexportedName(reexportClosures, targetFile, importedName);
+  if (followed === null) {
    // Target resolvable but the name isn't exported — keep trying in case a
    // re-export inside the target's SCC surfaces it in a later iteration.
    return null;
  }

-  const transitiveVia = draft.source.kind === 'reexport' ? Object.freeze([targetFile]) : undefined;
+  const viaFiles = [targetFile, ...followed.via];
+  const transitiveVia =
+    draft.source.kind === 'reexport' || viaFiles.length > 1 ? Object.freeze(viaFiles) : undefined;

  return {
    ...draft.base,
    targetModuleScope: targetModule.moduleScope,
-    targetDefId: exported.nodeId,
+    targetDefId: followed.def.nodeId,
    ...(transitiveVia !== undefined ? { transitiveVia } : {}),
  };
 }

+// ─── Internal: re-export closure (phase 2.5) ───────────────────────────────
+
+/**
+ * Per-file map of `name → terminal def + via path` — i.e. every name
+ * importable from this file via its named/wildcard re-export chain
+ * (excluding the file's own `localDefs`, which the caller checks first
+ * via `findExportByName`). `via` is the ordered list of intermediate
+ * files traversed to reach the def.
+ *
+ * Built once per finalize pass. Lookups are O(1).
+ */
+type ReexportClosureEntry = { readonly def: SymbolDefinition; readonly via: readonly string[] };
+type FileReexportClosure = ReadonlyMap<string, ReexportClosureEntry>;
+
+/**
+ * Build per-file re-export closures.
+ *
+ * **Algorithm.** Iterative SCC-condensed reverse-topological propagation,
+ * structurally identical to how `finalize` itself processes the file-
+ * level import graph. Replaces the legacy recursive
+ * `followReexportChain` crawl with a bounded, stack-safe pass:
+ *
+ *   1. **Sub-graph.** Build a directed graph whose edges are
+ *      `reexport` and `wildcard` drafts only (regular imports do not
+ *      contribute to the export surface, and `namespace`/
+ *      `reexport-namespace` are terminal — their target def lives in
+ *      `localDefs`).
+ *   2. **SCC condensation.** Run the same iterative `tarjanSccs` over
+ *      the sub-graph. Output is in reverse-topological order (leaves
+ *      first), so when we process an SCC every out-of-SCC neighbor
+ *      already has its closure populated.
+ *   3. **Per-SCC propagation.**
+ *        * Acyclic singleton: one pass — read neighbors' (already
+ *          fully populated) closures.
+ *        * Cyclic SCC (cycle ≥ 2 files, or self-loop): bounded
+ *          fixpoint inside the SCC, capped at `|SCC| + 1` iterations
+ *          (each iteration propagates names one hop further around
+ *          the cycle; first-wins precedence keeps the map monotone
+ *          so the fixpoint converges in at most |SCC| hops).
+ *
+ * **Precedence semantics — preserved from the recursive crawl.**
+ *   * Named re-exports take precedence over wildcards.
+ *   * Within each kind, declaration order wins (first match for a
+ *     given exported name is kept; later drafts skip).
+ *
+ * **Complexity.**
+ *   * Pre-pass: O(V + E_re) for SCC, plus O(|SCC| × Σ drafts) per cyclic
+ *     SCC. For tree-shaped barrel graphs (the common case) it
+ *     collapses to O(E_re) total.
+ *   * Per-edge lookup at finalize time: O(1).
+ *   * `transitiveVia` preserves the exact file path chain for diagnostics
+ *     and graph provenance. Building those arrays copies the inherited path,
+ *     which is O(depth²) in a pathological single-name barrel chain; practical
+ *     TypeScript barrel chains are shallow enough that we keep exact paths
+ *     instead of capping or summarizing them.
+ *   * Pathological deep chains that previously needed
+ *     `MAX_REEXPORT_DEPTH=100` to bound stack growth now resolve
+ *     in full and are bounded only by available memory — the
+ *     iterative formulation has no call-stack ceiling.
+ */
+function buildReexportClosures(
+  files: readonly FinalizeFile[],
+  byFilePath: ReadonlyMap<string, FinalizeFile>,
+  edgeIndex: ReadonlyMap<string, ImportEdgeDraft[]>,
+): ReadonlyMap<string, FileReexportClosure> {
+  const closures = new Map<string, Map<string, ReexportClosureEntry>>();
+  for (const file of files) closures.set(file.filePath, new Map());
+
+  // ── Step 1: build the re-export sub-graph (only resolvable
+  // reexport/wildcard targets contribute edges).
+  const subGraph = new Map<string, Set<string>>();
+  for (const file of files) {
+    const targets = new Set<string>();
+    const drafts = edgeIndex.get(file.filePath);
+    if (drafts !== undefined) {
+      for (const d of drafts) {
+        if (d.source.kind !== 'reexport' && d.source.kind !== 'wildcard') continue;
+        if (d.targetFile === null) continue;
+        if (!byFilePath.has(d.targetFile)) continue;
+        targets.add(d.targetFile);
+      }
+    }
+    subGraph.set(file.filePath, targets);
+  }
+
+  // ── Step 2: SCC over the sub-graph. Reuses the same iterative Tarjan
+  // implementation that drives the file-level finalize loop, so any
+  // call-stack-safety guarantees there transfer here unchanged.
+  const subSccs = tarjanSccs(subGraph);
+
+  // ── Step 3: process SCCs in reverse-topological order. Acyclic
+  // singletons settle in one pass; cyclic SCCs run a bounded fixpoint.
+  for (const scc of subSccs) {
+    if (!scc.isCycle) {
+      const filePath = scc.files[0];
+      if (filePath !== undefined) {
+        populateFileClosure(filePath, byFilePath, edgeIndex, closures);
+      }
+      continue;
+    }
+    // Cap = |SCC| + 1. With first-wins precedence each name needs at
+    // most |SCC| iterations to propagate fully around the cycle; the
+    // extra iteration confirms no progress and breaks the loop.
+    const cap = scc.files.length + 1;
+    let progressed = true;
+    let iter = 0;
+    while (progressed && iter < cap) {
+      progressed = false;
+      iter++;
+      for (const filePath of scc.files) {
+        if (populateFileClosure(filePath, byFilePath, edgeIndex, closures)) {
+          progressed = true;
+        }
+      }
+    }
+  }
+
+  return closures;
+}
+
+/**
+ * Populate one file's re-export closure for one pass. Returns `true`
+ * iff the closure grew (signalling fixpoint progress to the caller).
+ *
+ * Walks the file's drafts in declaration order, named re-exports first
+ * (precedence), then wildcards. For each draft, attempts:
+ *   1. **Direct hit** — name exists in the target file's `localDefs`.
+ *   2. **Inherited** — name exists in the target file's already-populated
+ *      closure (which encodes the target's own re-export chain).
+ *
+ * `closures.get(targetFile)` may itself still be empty for in-SCC
+ * targets on the first iteration; the outer fixpoint loop handles
+ * that by re-invoking this function.
+ */
+function populateFileClosure(
+  filePath: string,
+  byFilePath: ReadonlyMap<string, FinalizeFile>,
+  edgeIndex: ReadonlyMap<string, ImportEdgeDraft[]>,
+  closures: Map<string, Map<string, ReexportClosureEntry>>,
+): boolean {
+  const myClosure = closures.get(filePath);
+  if (myClosure === undefined) return false;
+  const before = myClosure.size;
+  const drafts = edgeIndex.get(filePath);
+  if (drafts === undefined) return false;
+
+  // Named re-exports — precedence over wildcards, declaration order
+  // first-wins for duplicates of the same exported name.
+  for (const draft of drafts) {
+    if (draft.source.kind !== 'reexport') continue;
+    const targetFile = draft.targetFile;
+    if (targetFile === null) continue;
+    const targetModule = byFilePath.get(targetFile);
+    if (targetModule === undefined) continue;
+
+    const localName = draft.source.localName;
+    if (myClosure.has(localName)) continue;
+
+    const importedName = draft.source.importedName;
+    const direct = findExportByName(targetModule.localDefs, importedName);
+    if (direct !== undefined) {
+      myClosure.set(localName, { def: direct, via: Object.freeze([targetFile]) });
+      continue;
+    }
+    const inherited = closures.get(targetFile)?.get(importedName);
+    if (inherited !== undefined) {
+      myClosure.set(localName, {
+        def: inherited.def,
+        via: Object.freeze([targetFile, ...inherited.via]),
+      });
+    }
+    // Else: target's closure is still empty (in-SCC, awaiting next
+    // iteration). Outer loop will revisit.
+  }
+
+  // Wildcard re-exports — fan out the target's own surface (localDefs
+  // + transitive closure). `myClosure.has(name)` checks below preserve
+  // the named-precedence and first-wins semantics from above.
+  for (const draft of drafts) {
+    if (draft.source.kind !== 'wildcard') continue;
+    const targetFile = draft.targetFile;
+    if (targetFile === null) continue;
+    const targetModule = byFilePath.get(targetFile);
+    if (targetModule === undefined) continue;
+
+    for (const def of targetModule.localDefs) {
+      const name = deriveSimpleName(def);
+      if (name === null || myClosure.has(name)) continue;
+      myClosure.set(name, { def, via: Object.freeze([targetFile]) });
+    }
+    const targetClosure = closures.get(targetFile);
+    if (targetClosure !== undefined) {
+      for (const [name, entry] of targetClosure) {
+        if (myClosure.has(name)) continue;
+        myClosure.set(name, {
+          def: entry.def,
+          via: Object.freeze([targetFile, ...entry.via]),
+        });
+      }
+    }
+  }
+
+  return myClosure.size > before;
+}
+
+/**
+ * O(1) lookup into a precomputed re-export closure. Replaces the legacy
+ * recursive `followReexportChain` traversal with a single map indexing.
+ */
+function lookupReexportedName(
+  closures: ReadonlyMap<string, FileReexportClosure>,
+  filePath: string,
+  name: string,
+): { def: SymbolDefinition; via: readonly string[] } | null {
+  const closure = closures.get(filePath);
+  if (closure === undefined) return null;
+  const entry = closure.get(name);
+  if (entry === undefined) return null;
+  return { def: entry.def, via: entry.via };
+}
+
 /**
 * The "simple" (unqualified) name of a def, for import-name matching.
 *
@@ -459,10 +749,58 @@ function findExportByName(
  defs: readonly SymbolDefinition[],
  name: string,
 ): SymbolDefinition | undefined {
+  // GENERIC RULE (applies to every language using this finalize
+  // algorithm): when MULTIPLE `SymbolDefinition`s share the same simple
+  // name in `localDefs`, prefer callable / type-like defs over plain
+  // value defs (`Variable`, `Property`, …). The CALLER side of an
+  // import almost always wants the callable, not a value shadow that
+  // happens to share the name — and without a deterministic
+  // preference, capture order silently decides which def the import
+  // binds to.
+  //
+  // The single-def case is unchanged: when only one def has the name,
+  // it's returned regardless of its type (the `fallback` path below).
+  //
+  // TypeScript is the first known language where this matters in
+  // practice: `const fn = () => {}` emits BOTH a `Function` def (from
+  // `@declaration.function` on the inner arrow) AND a `Variable` def
+  // (from the generic `@declaration.variable` pattern matching the
+  // wrapping `lexical_declaration`), and consumers of `import { fn }`
+  // need to bind to the callable. Other migrated languages don't
+  // currently produce dual emits of this shape, so the rule is a no-op
+  // for them today; future languages get the same correctness
+  // guarantee for free if they ever do.
+  //
+  // See `gitnexus/test/integration/resolvers/typescript-hof-callbacks.test.ts`
+  // for the cross-file regression this rule prevents.
+  let fallback: SymbolDefinition | undefined;
  for (const d of defs) {
-    if (deriveSimpleName(d) === name) return d;
+    if (deriveSimpleName(d) !== name) continue;
+    if (isCallableOrTypeLike(d.type)) return d;
+    if (fallback === undefined) fallback = d;
  }
-  return undefined;
+  return fallback;
+}
+
+const CALLABLE_OR_TYPE_LIKE: ReadonlySet<string> = new Set([
+  'Function',
+  'Method',
+  'Constructor',
+  'Class',
+  'Interface',
+  'Enum',
+  'Struct',
+  'Record',
+  'Trait',
+  'Namespace',
+  'Module',
+  'TypeAlias',
+  'Type',
+  'Typedef',
+]);
+
+function isCallableOrTypeLike(type: string): boolean {
+  return CALLABLE_OR_TYPE_LIKE.has(type);
 }

 function countEdgesWithin(edgeIndex: Map<string, ImportEdgeDraft[]>, files: Set<string>): number {
@@ -522,6 +860,17 @@ function materializeBindings(
 ): ReadonlyMap<ScopeId, ReadonlyMap<string, readonly BindingRef[]>> {
  const out = new Map<ScopeId, ReadonlyMap<string, readonly BindingRef[]>>();

+  // Build a `nodeId → SymbolDefinition` index once across all files
+  // (O(N_files × D_defs)) so the per-edge lookup below is O(1) instead
+  // of a full linear scan. At realistic TypeScript monorepo scale
+  // (~5k files × ~50 defs × ~100k linked import edges) this is the
+  // difference between ~25 s and a few ms inside finalize. The map
+  // is local to this pass — no cross-pass state leaks.
+  const defById = new Map<string, SymbolDefinition>();
+  for (const f of files) {
+    for (const d of f.localDefs) defById.set(d.nodeId, d);
+  }
+
  for (const file of files) {
    const scopeBindings = new Map<string, readonly BindingRef[]>();

@@ -538,10 +887,7 @@ function materializeBindings(
    const imports = linkedByScope.get(file.moduleScope) ?? [];
    for (const edge of imports) {
      if (edge.targetDefId === undefined || edge.linkStatus === 'unresolved') continue;
-      // Every def the importing file needs to reach is in some other file's
-      // `localDefs`; walk all files to find it. In practice we could index
-      // this, but at finalize-time N(files) is small per workspace pass.
-      const def = findDefById(files, edge.targetDefId);
+      const def = defById.get(edge.targetDefId);
      if (def === undefined) continue;

      const origin: BindingRef['origin'] =
@@ -571,15 +917,6 @@ function materializeBindings(
  return out;
 }

-function findDefById(files: readonly FinalizeFile[], defId: string): SymbolDefinition | undefined {
-  for (const f of files) {
-    for (const d of f.localDefs) {
-      if (d.nodeId === defId) return d;
-    }
-  }
-  return undefined;
-}
-
 // ─── Internal: Tarjan SCC ──────────────────────────────────────────────────

 /**
@@ -607,7 +944,8 @@ function tarjanSccs(graph: ReadonlyMap<string, ReadonlySet<string>>): FinalizedS
      entered: false,
    });
    while (iterStack.length > 0) {
-      const frame = iterStack[iterStack.length - 1]!;
+      const frame = iterStack[iterStack.length - 1];
+      if (frame === undefined) break;

      if (!frame.entered) {
        frame.entered = true;
@@ -625,7 +963,10 @@ function tarjanSccs(graph: ReadonlyMap<string, ReadonlySet<string>>): FinalizedS
          const scc: string[] = [];
          let selfInCycle = false;
          while (true) {
-            const w = stack.pop()!;
+            const w = stack.pop();
+            if (w === undefined) {
+              throw new Error(`Invariant violated: Tarjan stack exhausted at ${frame.node}`);
+            }
            onStack.delete(w);
            scc.push(w);
            // A single-file self-loop counts as a cycle.
@@ -640,8 +981,16 @@ function tarjanSccs(graph: ReadonlyMap<string, ReadonlySet<string>>): FinalizedS
        iterStack.pop();
        // Propagate lowlink to parent.
        if (iterStack.length > 0) {
-          const parent = iterStack[iterStack.length - 1]!;
-          lowlink.set(parent.node, Math.min(lowlink.get(parent.node)!, lowlink.get(frame.node)!));
+          const parent = iterStack[iterStack.length - 1];
+          if (parent !== undefined) {
+            lowlink.set(
+              parent.node,
+              Math.min(
+                requiredNumber(lowlink, parent.node, 'lowlink'),
+                requiredNumber(lowlink, frame.node, 'lowlink'),
+              ),
+            );
+          }
        }
        continue;
      }
@@ -654,10 +1003,24 @@ function tarjanSccs(graph: ReadonlyMap<string, ReadonlySet<string>>): FinalizedS
          entered: false,
        });
      } else if (onStack.has(child)) {
-        lowlink.set(frame.node, Math.min(lowlink.get(frame.node)!, index.get(child)!));
+        lowlink.set(
+          frame.node,
+          Math.min(
+            requiredNumber(lowlink, frame.node, 'lowlink'),
+            requiredNumber(index, child, 'index'),
+          ),
+        );
      }
    }
  }

  return sccs;
 }
+
+function requiredNumber(map: ReadonlyMap<string, number>, key: string, label: string): number {
+  const value = map.get(key);
+  if (value === undefined) {
+    throw new Error(`Invariant violated: missing Tarjan ${label} for ${key}`);
+  }
+  return value;
+}
@@ -37,6 +37,18 @@
 * `localDefs`. A `ParsedFile` is trivially convertible to a `FinalizeFile`
 * by picking those four fields, so the finalize orchestrator threads
 * ParsedFile through to the shared algorithm without shape-shifting.
+ *
+ * ## Source-of-truth invariant
+ *
+ * `ParsedFile` is the single semantic model consumed by both the legacy
+ * DAG (`gitnexus/src/core/ingestion/` outside `scope-resolution/`) and
+ * the scope-resolution pipeline (`gitnexus/src/core/ingestion/scope-resolution/`).
+ * Downstream passes MUST NOT build a parallel parse representation; if
+ * a pass needs AST-level facts that `ParsedFile` doesn't expose, it
+ * should reuse the orchestrator's `treeCache` rather than re-invoke
+ * `parser.parse(...)` on its own. See the
+ * `ScopeResolver` contract (`gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts`)
+ * for the full list of invariants downstream consumers rely on.
 */

 import type { Scope, ScopeId } from './types.js';
@@ -71,4 +71,12 @@ export interface ReferenceSite {
  readonly explicitReceiver?: { readonly name: string };
  /** Argument count at the call site; used by `provider.arityCompatibility`. */
  readonly arity?: number;
+  /**
+   * Inferred argument types at the call site, one per argument. An
+   * empty-string entry means "unknown" — consumers narrowing overload
+   * candidates treat unknown as any-match. Populated by languages
+   * that can derive types from literals / constructor expressions
+   * (C#: `42` → `'int'`, `"alice"` → `'string'`).
+   */
+  readonly argumentTypes?: readonly string[];
 }
@@ -119,10 +119,10 @@ export function buildScopeTree(scopes: readonly Scope[]): ScopeTree {
        `Scope '${scope.id}' (${scope.filePath}) has parent '${parent.id}' in a different file (${parent.filePath}). Parent/child scopes must share filePath.`,
      );
    }
-    if (!rangeStrictlyContains(parent.range, scope.range)) {
+    if (!canParentScope(parent.range, scope.range, parent.kind, scope.kind)) {
      throw new ScopeTreeInvariantError(
        'parent-must-contain-child',
-        `Parent scope '${parent.id}' at ${formatRange(parent.range)} does not strictly contain child '${scope.id}' at ${formatRange(scope.range)}.`,
+        `Parent scope '${parent.id}' at ${formatRange(parent.range)} does not contain child '${scope.id}' at ${formatRange(scope.range)} (allowed: strict containment, or equal-range Module-as-parent).`,
      );
    }

@@ -230,6 +230,47 @@ function rangeStrictlyContains(outer: Range, inner: Range): boolean {
  return outerStartsAtOrBefore && outerEndsAtOrAfter;
 }

+function rangesEqual(a: Range, b: Range): boolean {
+  return (
+    a.startLine === b.startLine &&
+    a.startCol === b.startCol &&
+    a.endLine === b.endLine &&
+    a.endCol === b.endCol
+  );
+}
+
+/**
+ * Whether `outer` (kind `outerKind`) is a valid parent for `inner` (kind
+ * `innerKind`).
+ *
+ * Strict containment is the general rule. The single carve-out is the
+ * `Module`/non-`Module` pair whose ranges are exactly equal — this happens
+ * naturally when tree-sitter reports identical byte spans for the
+ * `compilation_unit` (or equivalent file-root construct) and the file's
+ * single top-level scope. Common shape: a C# file consisting of nothing
+ * but `namespace X { ... }` with no leading or trailing trivia outside the
+ * namespace's `{}` body — `compilation_unit` and `namespace_declaration`
+ * both span exactly the same byte range. The `Module` is the universal
+ * outer of any file-level scope by language semantics, so coincident
+ * ranges should not break the parent chain.
+ *
+ * The carve-out is direction-asymmetric: only `Module`-as-outer parents a
+ * same-range non-`Module`, never the reverse. This preserves the
+ * acyclicity buildScopeTree relies on, and matches the corresponding
+ * helper in `scope-extractor.ts` so `pass1BuildScopes` and the validator
+ * agree on what a well-formed parent edge looks like.
+ */
+export function canParentScope(
+  outer: Range,
+  inner: Range,
+  outerKind: Scope['kind'],
+  innerKind: Scope['kind'],
+): boolean {
+  if (rangeStrictlyContains(outer, inner)) return true;
+  if (outerKind === 'Module' && innerKind !== 'Module' && rangesEqual(outer, inner)) return true;
+  return false;
+}
+
 /**
 * Two ranges overlap when neither finishes before the other begins. Ranges
 * that merely touch at a single boundary point (`a.end === b.start`) do
@@ -10,8 +10,16 @@
 * Lifecycle contract (RFC §2.8): scopes are **constructed during extraction,
 * linked during finalize, immutable after finalize**. All fields are
 * `readonly` at the type level; `Object.freeze` is applied at runtime in dev
- * builds. `ReferenceIndex` is the sole structure populated after freeze — by
- * resolution, before emission.
+ * builds.
+ *
+ * Two structures are populated after freeze:
+ *   1. `ReferenceIndex` — by resolution, before emission.
+ *   2. `ScopeResolutionIndexes.bindingAugmentations` — the dedicated
+ *      append-only post-finalize binding channel (e.g. C# same-namespace
+ *      cross-file fanout). The companion `indexes.bindings` is the
+ *      finalize-output channel and is deep-frozen by `materializeBindings`;
+ *      walkers consult both via `lookupBindingsAt`. See `ScopeResolver`
+ *      Invariant I8 for the full lifecycle contract.
 */

 import type { NodeLabel } from '../graph/types.js';
@@ -182,6 +190,42 @@ export type ParsedImport =
      readonly localName: string;
      /** Source text of the unresolved expression when available; `null` otherwise. */
      readonly targetRaw: string | null;
+    }
+  /**
+   * Lazy / dynamic import whose target IS a static string literal at parse
+   * time, so it can be linked to a concrete `targetFile`. No local name
+   * binding is materialized — `import('./m')` returns `Promise<Module>` and
+   * any consumer-visible names appear via subsequent `.then(({ X }) => …)`
+   * destructuring, which is outside the static-import surface. The edge
+   * exists for module-reachability and impact analysis (so editing `./m`
+   * still flags the dynamic importer as affected).
+   *
+   * Providers MUST only emit this kind when `targetRaw` is a literal
+   * string they can hand to `resolveImportTarget`; expression arguments
+   * stay `dynamic-unresolved`.
+   *
+   * Examples:
+   *   - JS `import('./feature')`                  → `{ kind: 'dynamic-resolved', targetRaw: './feature' }`
+   *   - JS `await import('@scope/pkg/sub')`       → `{ kind: 'dynamic-resolved', targetRaw: '@scope/pkg/sub' }`
+   */
+  | {
+      readonly kind: 'dynamic-resolved';
+      readonly targetRaw: string;
+    }
+  /**
+   * Bare-source / side-effect import that introduces no local name binding
+   * but still establishes a file-level dependency. Resolves to a concrete
+   * `targetFile` via `resolveImportTarget` and produces a file→file
+   * `ImportEdge` for module-reachability and impact analysis, with no
+   * `BindingRef` materialized.
+   *
+   * Examples:
+   *   - JS / TS `import './polyfill'`        → `{ kind: 'side-effect', targetRaw: './polyfill' }`
+   *   - Rust    `use foo::bar as _`          → side-effect (binding hidden under `_`)
+   */
+  | {
+      readonly kind: 'side-effect';
+      readonly targetRaw: string;
    };

 /**
@@ -253,7 +297,9 @@ export interface ImportEdge {
    | 'namespace'
    | 'wildcard-expanded'
    | 'reexport'
-    | 'dynamic-unresolved';
+    | 'dynamic-unresolved'
+    | 'dynamic-resolved'
+    | 'side-effect';
  /** Re-export chain, for provenance (e.g., `['./y']` when re-exported via `./y`). */
  readonly transitiveVia?: readonly string[];
  /** Set to `'unresolved'` when the SCC fixpoint could not link this edge. */
@@ -3,7 +3,7 @@
  "private": true,
  "version": "0.0.0",
  "engines": {
-    "node": ">=20.0.0"
+    "node": "^20.19.0 || >=22.12.0"
  },
  "type": "module",
  "scripts": {
@@ -19,59 +19,59 @@
  },
  "dependencies": {
    "gitnexus-shared": "file:../gitnexus-shared",
-    "@langchain/anthropic": "^1.3.10",
-    "@langchain/core": "^1.1.15",
-    "@langchain/google-genai": "^2.1.10",
-    "@langchain/langgraph": "^1.1.0",
-    "@langchain/ollama": "^1.2.0",
-    "@langchain/openai": "^1.2.2",
+    "@langchain/anthropic": "^1.3.27",
+    "@langchain/core": "^1.1.41",
+    "@langchain/google-genai": "^2.1.28",
+    "@langchain/langgraph": "^1.2.9",
+    "@langchain/ollama": "^1.2.6",
+    "@langchain/openai": "^1.4.5",
    "@sigma/edge-curve": "^3.1.0",
-    "@tailwindcss/vite": "^4.1.18",
-    "axios": "^1.13.2",
+    "@tailwindcss/vite": "^4.2.4",
+    "axios": "^1.16.0",
    "d3": "^7.9.0",
-    "dompurify": "^3.3.3",
+    "dompurify": "^3.4.2",
    "graphology": "^0.26.0",
    "graphology-indices": "^0.17.0",
    "graphology-layout-force": "^0.2.4",
    "graphology-layout-forceatlas2": "^0.10.1",
    "graphology-layout-noverlap": "^0.4.2",
    "graphology-utils": "^2.3.0",
-    "langchain": "^1.2.10",
+    "langchain": "^1.3.4",
    "lru-cache": "^11.2.4",
-    "lucide-react": "^0.562.0",
+    "lucide-react": "^1.11.0",
    "mermaid": "^11.14.0",
    "mnemonist": "^0.39.0",
    "pandemonium": "^2.4.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
    "react-markdown": "^10.1.0",
    "react-syntax-highlighter": "^16.1.0",
-    "react-zoom-pan-pinch": "^3.7.0",
+    "react-zoom-pan-pinch": "^4.0.3",
    "remark-gfm": "^4.0.1",
    "sigma": "^3.0.2",
-    "tailwindcss": "^4.2.2",
-    "uuid": "^13.0.0",
+    "tailwindcss": "^4.2.4",
+    "uuid": "^14.0.0",
    "zod": "^3.25.76"
  },
  "devDependencies": {
-    "@babel/types": "^7.28.5",
+    "@babel/types": "^7.29.0",
    "@playwright/test": "^1.58.2",
    "@testing-library/jest-dom": "^6.9.1",
    "@testing-library/react": "^16.3.2",
    "@testing-library/user-event": "^14.6.1",
    "@types/dompurify": "^3.0.5",
-    "@types/node": "^24.10.1",
-    "@types/react": "^18.3.5",
-    "@types/react-dom": "^18.3.0",
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
    "@types/react-syntax-highlighter": "^15.5.13",
    "@vercel/node": "^5.5.16",
-    "@vitejs/plugin-react": "^5.1.0",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitejs/plugin-react": "^5.1.4",
+    "@vitest/coverage-v8": "^4.1.5",
    "jsdom": "^29.0.2",
    "tree-sitter-wasms": "^0.1.13",
    "typescript": "^5.4.5",
-    "vite": "^5.2.0",
-    "vitest": "^3.2.4",
+    "vite": "^8.0.10",
+    "vitest": "^4.1.5",
    "wait-on": "^9.0.5"
  }
 }
@@ -4,8 +4,8 @@ const DEFAULT_BOTTOM_THRESHOLD = 100;
 const USER_SCROLL_EPSILON = 5;

 export interface UseAutoScrollResult {
-  scrollContainerRef: React.RefObject<HTMLDivElement>;
-  messagesContainerRef: React.RefObject<HTMLDivElement>;
+  scrollContainerRef: React.RefObject<HTMLDivElement | null>;
+  messagesContainerRef: React.RefObject<HTMLDivElement | null>;
  isAtBottom: boolean;
  scrollToBottom: (behavior?: ScrollBehavior) => void;
 }
@@ -65,7 +65,7 @@ interface UseSigmaOptions {
 }

 interface UseSigmaReturn {
-  containerRef: React.RefObject<HTMLDivElement>;
+  containerRef: React.RefObject<HTMLDivElement | null>;
  sigmaRef: React.RefObject<Sigma | null>;
  setGraph: (graph: Graph<SigmaNodeAttributes, SigmaEdgeAttributes>) => void;
  zoomIn: () => void;
@@ -5,7 +5,42 @@
 * than directly from lucide-react. This provides a single place to manage
 * which icons are used and allows future optimization (e.g., tree-shaking
 * configuration, icon subset bundling) without touching every component.
+ *
+ * --- Why a local `Github` icon? ---
+ *
+ * Lucide removed all brand icons in v1
+ * (https://lucide.dev/guide/react/migration,
+ *  https://github.com/lucide-icons/lucide/blob/main/BRAND_LOGOS_STATEMENT.md),
+ * so `import { Github } from 'lucide-react'` no longer compiles.
+ *
+ * We replace it with the official mark from Primer Octicons — the icon set
+ * GitHub itself uses on github.com — copied verbatim. This was preferred over
+ * the alternatives because it:
+ *
+ *   1. Is the canonical GitHub-maintained source for the mark, kept in sync
+ *      with what users see on github.com.
+ *   2. Is MIT-licensed (Copyright (c) GitHub Inc.,
+ *      https://github.com/primer/octicons/blob/main/LICENSE), so embedding the
+ *      path data is permitted.
+ *   3. Adds zero new npm dependencies (vs. `@primer/octicons-react`,
+ *      `react-icons`, or `simple-icons`), keeping the web bundle lean.
+ *   4. Ships per-size hand-tuned glyphs (16 + 24) — the same approach Primer
+ *      uses — so the mark stays crisp at the small `h-4 w-4` sites in the
+ *      header and onboarding screens as well as at full size.
+ *
+ * Trademark note: the GitHub mark is a registered trademark of GitHub, Inc.
+ * (https://brand.github.com/foundations/logo). The MIT license covers our
+ * right to copy the SVG; trademark rules still govern *use*. We use the mark
+ * here only to link to GitHub and to indicate GitHub source-repo integration,
+ * which are explicitly permitted by GitHub's brand toolkit.
+ *
+ * SVG sources (copied verbatim, MIT, Copyright (c) GitHub Inc.):
+ *   - https://github.com/primer/octicons/blob/main/icons/mark-github-16.svg
+ *   - https://github.com/primer/octicons/blob/main/icons/mark-github-24.svg
 */
+import { forwardRef } from 'react';
+import type { LucideProps } from 'lucide-react';
+
 export {
  AlertCircle,
  AlertTriangle,
@@ -31,7 +66,6 @@ export {
  Folder,
  FolderOpen,
  GitBranch,
-  Github,
  Globe,
  Hash,
  Heart,
@@ -75,3 +109,63 @@ export {
  ZoomIn,
  ZoomOut,
 } from 'lucide-react';
+
+/**
+ * GitHub mark — local copy of Primer Octicons `mark-github-{16,24}`.
+ *
+ * Why this exists, why Primer Octicons, and the trademark caveat are documented
+ * at the top of this file. Please read that header before changing the SVG
+ * paths or swapping the source.
+ *
+ * API-compatible with `lucide-react` icons (`LucideProps`). The Octicons mark
+ * is a *filled* glyph, so the lucide-only stroke props (`strokeWidth`,
+ * `absoluteStrokeWidth`) are accepted for type parity but ignored. Color
+ * defaults to `currentColor`, so Tailwind `text-*` utilities work the same as
+ * with any other icon in this module.
+ */
+export const Github = forwardRef<SVGSVGElement, LucideProps>(function Github(
+  {
+    size = 24,
+    color = 'currentColor',
+    className,
+    strokeWidth: _strokeWidth,
+    absoluteStrokeWidth: _absoluteStrokeWidth,
+    ...rest
+  },
+  ref,
+) {
+  const numericSize = typeof size === 'string' ? Number.parseFloat(size) : size;
+  const useSmallVariant = Number.isFinite(numericSize) && (numericSize as number) <= 16;
+
+  if (useSmallVariant) {
+    return (
+      <svg
+        ref={ref}
+        xmlns="http://www.w3.org/2000/svg"
+        width={size}
+        height={size}
+        viewBox="0 0 16 16"
+        fill={color}
+        className={className}
+        {...rest}
+      >
+        <path d="M6.766 11.328c-2.063-.25-3.516-1.734-3.516-3.656 0-.781.281-1.625.75-2.188-.203-.515-.172-1.609.063-2.062.625-.078 1.468.25 1.968.703.594-.187 1.219-.281 1.985-.281.765 0 1.39.094 1.953.265.484-.437 1.344-.765 1.969-.687.218.422.25 1.515.046 2.047.5.593.766 1.39.766 2.203 0 1.922-1.453 3.375-3.547 3.64.531.344.89 1.094.89 1.954v1.625c0 .468.391.734.86.547C13.781 14.359 16 11.53 16 8.03 16 3.61 12.406 0 7.984 0 3.563 0 0 3.61 0 8.031a7.88 7.88 0 0 0 5.172 7.422c.422.156.828-.125.828-.547v-1.25c-.219.094-.5.156-.75.156-1.031 0-1.64-.562-2.078-1.609-.172-.422-.36-.672-.719-.719-.187-.015-.25-.093-.25-.187 0-.188.313-.328.625-.328.453 0 .844.281 1.25.86.313.452.64.655 1.031.655s.641-.14 1-.5c.266-.265.47-.5.657-.656" />
+      </svg>
+    );
+  }
+
+  return (
+    <svg
+      ref={ref}
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill={color}
+      className={className}
+      {...rest}
+    >
+      <path d="M10.226 17.284c-2.965-.36-5.054-2.493-5.054-5.256 0-1.123.404-2.336 1.078-3.144-.292-.741-.247-2.314.09-2.965.898-.112 2.111.36 2.83 1.01.853-.269 1.752-.404 2.853-.404 1.1 0 1.999.135 2.807.382.696-.629 1.932-1.1 2.83-.988.315.606.36 2.179.067 2.942.72.854 1.101 2 1.101 3.167 0 2.763-2.089 4.852-5.098 5.234.763.494 1.28 1.572 1.28 2.807v2.336c0 .674.561 1.056 1.235.786 4.066-1.55 7.255-5.615 7.255-10.646C23.5 6.188 18.334 1 11.978 1 5.62 1 .5 6.188.5 12.545c0 4.986 3.167 9.12 7.435 10.669.606.225 1.19-.18 1.19-.786V20.63a2.9 2.9 0 0 1-1.078.224c-1.483 0-2.359-.808-2.987-2.313-.247-.607-.517-.966-1.034-1.033-.27-.023-.359-.135-.359-.27 0-.27.45-.471.898-.471.652 0 1.213.404 1.797 1.235.45.651.921.943 1.483.943.561 0 .92-.202 1.437-.719.382-.381.674-.718.944-.943" />
+    </svg>
+  );
+});
@@ -72,7 +72,19 @@ export class BackendError extends Error {
  constructor(
    message: string,
    public readonly status: number,
-    public readonly code: 'network' | 'server' | 'client' | 'not_found' | 'timeout',
+    public readonly code:
+      | 'network'
+      | 'server'
+      | 'client'
+      | 'not_found'
+      | 'timeout'
+      | 'rate_limited',
+    /**
+     * Milliseconds until the caller should retry. Populated for rate-limited
+     * responses (HTTP 429) from the server's `Retry-After` header. `undefined`
+     * for every other code, including `client` errors that aren't 429.
+     */
+    public readonly retryAfterMs?: number,
  ) {
    super(message);
    this.name = 'BackendError';
@@ -279,10 +291,32 @@ const assertOk = async (response: Response): Promise<void> => {
  const code =
    response.status === 404
      ? 'not_found'
-      : response.status >= 400 && response.status < 500
-        ? 'client'
-        : 'server';
-  throw new BackendError(message, response.status, code);
+      : response.status === 429
+        ? 'rate_limited'
+        : response.status >= 400 && response.status < 500
+          ? 'client'
+          : 'server';
+
+  // Retry-After is the standard HTTP signal for when the client may try again.
+  // express-rate-limit emits it on 429 with seconds (integer) or HTTP-date.
+  // We accept both shapes; an unparseable header yields undefined retryAfterMs.
+  let retryAfterMs: number | undefined;
+  if (response.status === 429) {
+    const header = response.headers.get('retry-after');
+    if (header) {
+      const seconds = Number(header);
+      if (Number.isFinite(seconds) && seconds >= 0) {
+        retryAfterMs = seconds * 1000;
+      } else {
+        const dateMs = Date.parse(header);
+        if (Number.isFinite(dateMs)) {
+          retryAfterMs = Math.max(0, dateMs - Date.now());
+        }
+      }
+    }
+  }
+
+  throw new BackendError(message, response.status, code, retryAfterMs);
 };

 const repoParam = (repo?: string): string => (repo ? `repo=${encodeURIComponent(repo)}` : '');
@@ -16,9 +16,12 @@ let lastEventSource: MockEventSource | null = null;

 beforeEach(() => {
  lastEventSource = null;
+  // vitest 4 enforces that mock implementations used with `new` must have a
+  // [[Construct]] slot. Arrow functions don't, so we use a regular function
+  // declaration here. The production code calls `new EventSource(...)`.
  vi.stubGlobal(
    'EventSource',
-    vi.fn().mockImplementation(() => {
+    vi.fn().mockImplementation(function () {
      lastEventSource = new MockEventSource();
      return lastEventSource;
    }),
@@ -38,11 +38,15 @@ export default defineConfig({
        'src/main.tsx', // Entry point
        'src/vite-env.d.ts', // Type declarations
      ],
+      // Thresholds set to the post-vitest-4 baseline (AST-aware remapping
+      // measures coverage more accurately than the old istanbul-style mapping,
+      // so the same 220 tests now report slightly lower percentages). These
+      // are soft floors for regression detection, not coverage targets.
      thresholds: {
-        statements: 10,
-        branches: 10,
-        functions: 10,
-        lines: 10,
+        statements: 9,
+        branches: 4,
+        functions: 7,
+        lines: 9,
      },
    },
  },
@@ -4,9 +4,73 @@ All notable changes to GitNexus will be documented in this file.

 ## [Unreleased]

-### Performance
+## [1.6.3] - 2026-04-24

- **`analyze` ~33% faster** — moved FTS index creation from the analyze pipeline to first-use lazy initialisation. The 5 `CREATE_FTS_INDEX` calls cost ~440 ms each in LadybugDB regardless of table size (≈2 s fixed overhead) and dominated runtime on small repos and slow CI runners. The cost now amortises across the first `query`/`context` call in a session via a new `ensureFTSIndex` helper. Mini-repo `analyze` measured locally on Windows: 6.4 s → 4.0 s warm; on CI Windows runners (≈3× slower) restores comfortable headroom against the 30 s e2e test budget.
+### Added
+
+- **Cross-repo impact analysis** — `@repo` MCP routing plus group resources let impact queries span multiple indexed repositories in a group (#794, #984)
+- **Python scope-based call resolution** — registry-primary flip, performance, and generalization work from RFC #909 Ring 3 (#980)
+- **C# scope-resolution migration** — C# now runs on the registry-primary path alongside Python (#934, #1019)
+- **RFC #909 Ring 1 & Ring 2 scope-resolution infrastructure** — the shared foundation for language-agnostic scope resolution:
+  - Scope-resolution types and constants, `LanguageProvider` hook extension (#910, #911, #949, #950)
+  - `ScopeTree` + `PositionIndex` + `makeScopeId` (#912, #961)
+  - `DefIndex` / `ModuleScopeIndex` / `QualifiedNameIndex` (#913, #958)
+  - `MethodDispatchIndex` materialized view over `HeritageMap` (#914, #960)
+  - `resolveTypeRef` strict single-return type resolver (#916, #959)
+  - SCC-aware finalize with bounded fixpoint (#915, #962)
+  - `ClassRegistry` / `MethodRegistry` / `FieldRegistry` + 7-step lookup (#917, #963)
+  - Shadow-mode diff + aggregate, parity harness + static dashboard (#918, #923, #951, #972)
+  - `ScopeExtractor` driver with 5-pass CaptureMatch → ParsedFile (#919, #965)
+  - `ScopeExtractor` wired into parse-worker + processor (#920, #969)
+  - `finalize-orchestrator` materializes `ScopeResolutionIndexes` (#921, #970)
+  - Per-language `resolveImportTarget` adapter (#922, #971)
+  - `REGISTRY_PRIMARY_<LANG>` per-language flag reader (#924, #968)
+  - `emit-references` drains `ReferenceIndex` to graph edges (#925, #973)
+- **`gitnexus analyze --name <alias>`** with duplicate-name guard in the repo registry (#955)
+- **`gitnexus remove <target>`** unindexes a registered repo by name or path (#664, #1003)
+- **Auto-infer registry name** from `git remote.origin.url` when `--name` is omitted (#981)
+- **Sibling-clone drift detection** — indexed repos are fingerprinted by remote URL so duplicate registrations are caught before graph divergence (#982)
+- **Configurable large-file skip threshold** — the walker's 512 KB default is now overridable via `GITNEXUS_MAX_FILE_SIZE` (KB) or `gitnexus analyze --max-file-size <kb>`. Values are clamped to the 32 MB tree-sitter ceiling, invalid inputs fall back to the default with a one-time warning, and the CLI banner reports the effective post-clamp threshold when an override is active (#991, #1044, #1045)
+- **`GITNEXUS_INDEX_TEST_DIRS` opt-in** for `__tests__` / `__mocks__` traversal (#771, #1046)
+- **`analyze` embedding preservation** — existing embeddings are preserved by default, `--force` regenerates them, `--drop-embeddings` opts out entirely (CLI + HTTP API) (#1055)
+- **Structural embedding chunking** with data-driven `CHUNKING_RULES` dispatch, replacing the flat line-based split (#987)
+- **PHP HTTP consumer detection** for the extractor catalogue (#993)
+- **Per-phase search timing** instrumentation across the query pipeline (#953)
+- **MCP disambiguation ranking** — `context` / `impact` candidates are ranked and expose `kind` / `file_path` hints (#888)
+- **Docker images for UI + CLI/server** shipped via `docker-compose` with cosign signing (#967), RC image builds (#978), and GHCR → Docker Hub mirroring (#1029)
+
+### Fixed
+
+- **Go CALLS edges for receiver methods** — worker source IDs now align with the main pipeline, restoring receiver-method call edges (#1043)
+- **Node 22 DEP0151 warning** from `tree-sitter-c-sharp` import silenced (#1013, #1049)
+- **FTS index bootstrap** tries a local `LOAD` before `INSTALL` so offline/air-gapped runs no longer fail on network errors (#726)
+- **FTS ensure failures** are no longer cached and are invalidated on pool teardown (#1006)
+- **`groupImpact` local-impact errors** now bubble to the caller instead of being swallowed (#1004, #1007)
+- **Friendly error** when a group name is not found, with regression test for #903 (#989)
+- **`bm25` results** return FTS-matched symbols instead of an arbitrary `LIMIT 3` slice (#806)
+- **Embedding AST traversal** switched from recursion to iterative DFS, fixing stack overflow on deeply nested files (#990)
+- **React component path detection** runs before lowercasing, so mixed-case `.jsx`/`.tsx` files are recognised (#260)
+- **`detect-changes` ENOBUFS** by setting `maxBuffer` on `git` / `rg` `execFileSync` invocations (#957)
+- **`detect-changes` in direct CLI** — command was wired to MCP only; now exposed on the CLI as well (#892)
+- **CLI gitnexus markers** — `<!-- gitnexus:* -->` is only matched at section position, no longer inside code/prose (#1041, #1042)
+- **`opencode.json` setup** preserves existing comments and config during install (#998)
+- **Sequential parser logging** — skipped languages are now logged instead of silently dropped (#1021)
+- **`cli-e2e` fixture isolation** from the shared mini-repo, plus stabilised `rel-csv-split` stream teardown on Windows via `expect.poll` (#954, #1052)
+- **Docker** — RC build guarded against empty `vtag`, `inputs.tag` used to detect `workflow_call` context, web builder stage now copies `gitnexus/package.json`, base image switched from alpine to debian (#983, #996, #997, #1014)
+- **CI** — reusable `docker.yml` now inherits secrets from `release-candidate.yml` (#1054)
+
+### Changed
+
+- **`setup` config I/O unified** on `mergeJsoncFile` across all writers (#1031)
+- **Docker CI** gains a retry wrapper for `build-push` with visibility and hardened shell
+
+### Chore / Dependencies
+
+- Dependency bumps: `graphology` 0.25.4 → 0.26.0 (#1001), `uuid` 13 → 14 (#1000), `@huggingface/transformers` (#1035), `@types/node` (#1002), `@types/uuid` (#1016), `vitest` 4.1.4 → 4.1.5 (#1017), `@vitest/coverage-v8` (#1018)
+- gitnexus-web dependency bumps: `vite` 5.4.21 → 6.4.2 → 7.3.2 → 8.0.10 + `vitest` 4 (#1061, #1062, #1063), `lucide-react` 0.562.0 → 1.11.0 with local GitHub SVG fallback (#1038), `@langchain/anthropic` 1.3.10 → 1.3.27 (#1039), `@babel/types` (#1037)
+- gitnexus-shared dependency bumps: `typescript` (#1034)
+- GitHub Actions bumps: `actions/setup-node` 6.3.0 → 6.4.0 (#1033)
+- Documentation: repo-wide `DoD.md` Definition of Done (#1032), gRPC microservices group guide (#906, #994), `group add` / `group remove` README fixes (#1020), CLI docs include `--skip-git` (#750), README Discord link updated

 ## [1.6.2] - 2026-04-18

@@ -3,7 +3,8 @@ WORKDIR /app
 RUN apt-get -o Acquire::Check-Valid-Until=false -o Acquire::Check-Date=false update && apt-get install -y python3 make g++ && rm -rf /var/lib/apt/lists/*
 COPY . .
 RUN npm ci --ignore-scripts \
-    && node scripts/patch-tree-sitter-swift.cjs \
+    && npm rebuild tree-sitter-swift 2>&1 \
+    && node -e "require('tree-sitter-swift')" \
    && (npm rebuild 2>&1 || true) \
    && cd node_modules/tree-sitter-kotlin && npx --yes node-gyp rebuild 2>&1
 CMD ["npx", "vitest", "run", "test/integration", "--reporter=verbose"]
@@ -155,6 +155,8 @@ gitnexus analyze --force         # Force full re-index
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
+gitnexus analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
+gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
 gitnexus index                   # Register an existing .gitnexus/ folder into the global registry
@@ -166,11 +168,11 @@ gitnexus wiki [path]             # Generate LLM-powered docs from knowledge grap
 gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)

 # Repository groups (multi-repo / monorepo service tracking)
-gitnexus group create <name>     # Create a repository group
-gitnexus group add <name> <repo> # Add a repo to a group
-gitnexus group remove <name> <repo> # Remove a repo from a group
-gitnexus group list [name]       # List groups, or show one group's config
-gitnexus group sync <name>       # Extract contracts and match across repos/services
+gitnexus group create <name>                                   # Create a repository group
+gitnexus group add <group> <groupPath> <registryName>          # Add a repo to a group. <groupPath> is a hierarchy path (e.g. hr/hiring/backend); <registryName> is the repo's name from the registry (see `gitnexus list`)
+gitnexus group remove <group> <groupPath>                      # Remove a repo from a group by its hierarchy path
+gitnexus group list [name]                                     # List groups, or show one group's config
+gitnexus group sync <name>                                     # Extract contracts and match across repos/services
 gitnexus group contracts <name>  # Inspect extracted contracts and cross-links
 gitnexus group query <name> <q>  # Search execution flows across all repos in a group
 gitnexus group status <name>     # Check staleness of repos in a group
@@ -294,6 +296,25 @@ If `npm install -g gitnexus` fails on native modules:
 npm install -g gitnexus
 ```

+### Analyze warns about unavailable FTS or VECTOR extensions
+
+GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process `INSTALL` if `LOAD` fails and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
+
+Configure the behavior with two environment variables:
+
+| Variable | Values | Default | Effect |
+|----------|--------|---------|--------|
+| `GITNEXUS_LBUG_EXTENSION_INSTALL` | `auto`, `load-only`, `never` | `auto` | `auto` runs one bounded INSTALL if LOAD fails. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely. |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer | `15000` | Wall-clock budget for the out-of-process `INSTALL` child before it is killed. |
+
+```bash
+# Offline/airgapped: never reach the network for extensions
+GITNEXUS_LBUG_EXTENSION_INSTALL=load-only npx gitnexus analyze
+
+# Slow network: give extension downloads more time
+GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS=30000 npx gitnexus analyze
+```
+
 ### Analysis runs out of memory

 For very large repositories:
@@ -307,6 +328,36 @@ echo "vendor/" >> .gitnexusignore
 echo "dist/" >> .gitnexusignore
 ```

+### Large files are being skipped
+
+By default the walker skips files larger than **512 KB** (see log line `Skipped N large files (>512KB)`). Raise the threshold via either the CLI flag or the environment variable — both accept a value in **KB**:
+
+```bash
+# CLI flag (takes precedence over the env var)
+npx gitnexus analyze --max-file-size 2048     # skip only files > 2 MB
+
+# Environment variable (persists across commands)
+export GITNEXUS_MAX_FILE_SIZE=2048
+npx gitnexus analyze
+```
+
+Values above **32768 KB (32 MB)** are clamped to the tree-sitter parser ceiling; invalid values fall back to the 512 KB default with a one-time warning. When an override is active, `analyze` prints the effective threshold in its startup banner (e.g. `GITNEXUS_MAX_FILE_SIZE: effective threshold 2048KB (default 512KB)`).
+
+### Analyze reports a worker timeout
+
+Worker parse timeouts are recoverable. GitNexus retries stalled worker jobs with backoff, splits large jobs to isolate slow files, and falls back to the sequential parser when needed. If a large repository needs more time per worker job, use either:
+
+```bash
+# CLI flag, in seconds
+npx gitnexus analyze --worker-timeout 60
+
+# Environment variable, in milliseconds
+export GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000
+npx gitnexus analyze
+```
+
+For repositories with very large source files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget. The default is **8388608 bytes (8 MB)**.
+
 ## Privacy

 - All processing happens locally on your machine
@@ -31,11 +31,25 @@ function readInput() {
 * Find the .gitnexus directory by walking up from startDir.
 * Returns the path to .gitnexus/ or null if not found.
 */
-function findGitNexusDir(startDir) {
-  let dir = startDir || process.cwd();
+function isGlobalRegistryDir(candidate) {
+  if (fs.existsSync(path.join(candidate, 'meta.json'))) return false;
+  return (
+    fs.existsSync(path.join(candidate, 'registry.json')) ||
+    fs.existsSync(path.join(candidate, 'repos'))
+  );
+}
+
+/**
+ * Walk up from `startDir` looking for a non-registry `.gitnexus/` folder.
+ * Returns the path to `.gitnexus/` or null if not found within 5 levels.
+ */
+function walkForGitNexusDir(startDir) {
+  let dir = startDir;
  for (let i = 0; i < 5; i++) {
    const candidate = path.join(dir, '.gitnexus');
-    if (fs.existsSync(candidate)) return candidate;
+    if (fs.existsSync(candidate)) {
+      if (!isGlobalRegistryDir(candidate)) return candidate;
+    }
    const parent = path.dirname(dir);
    if (parent === dir) break;
    dir = parent;
@@ -43,6 +57,51 @@ function findGitNexusDir(startDir) {
  return null;
 }

+/**
+ * Resolve the canonical (main) worktree root for `cwd`, when `cwd` is inside
+ * any git working tree — including a *linked* worktree created via
+ * `git worktree add`. Linked worktrees never contain `.gitnexus/`, so the
+ * upward walk from cwd alone misses the index. Returns null when `cwd` is
+ * not inside a git repo or `git` is not available.
+ *
+ * Implementation: `git rev-parse --git-common-dir` resolves to the canonical
+ * `.git/` directory (or `.git/worktrees/...` parent) that is shared across
+ * all linked worktrees. The canonical repo root is its parent directory.
+ */
+function findCanonicalRepoRoot(cwd) {
+  try {
+    const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      encoding: 'utf-8',
+      timeout: 2000,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.error || result.status !== 0) return null;
+    const commonDir = (result.stdout || '').trim();
+    if (!commonDir || !path.isAbsolute(commonDir)) return null;
+    return path.dirname(commonDir);
+  } catch {
+    return null;
+  }
+}
+
+function findGitNexusDir(startDir) {
+  const cwd = startDir || process.cwd();
+
+  // Fast path: the cwd is inside the canonical repo (most common case).
+  const fromCwd = walkForGitNexusDir(cwd);
+  if (fromCwd) return fromCwd;
+
+  // Fallback: cwd may be inside a linked git worktree whose `.gitnexus/`
+  // only lives in the canonical repo root. Resolve the shared git dir
+  // and retry from there.
+  const canonicalRoot = findCanonicalRepoRoot(cwd);
+  if (canonicalRoot && canonicalRoot !== cwd) {
+    return walkForGitNexusDir(canonicalRoot);
+  }
+  return null;
+}
+
 /**
 * Extract search pattern from tool input.
 */
@@ -1,37 +1,39 @@
 {
  "name": "gitnexus",
-  "version": "1.6.2",
+  "version": "1.6.4-rc.74",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "gitnexus",
-      "version": "1.6.2",
+      "version": "1.6.4-rc.74",
      "hasInstallScript": true,
      "license": "PolyForm-Noncommercial-1.0.0",
      "dependencies": {
        "@huggingface/transformers": "^4.1.0",
-        "@ladybugdb/core": "^0.15.2",
+        "@ladybugdb/core": "^0.16.1",
        "@modelcontextprotocol/sdk": "^1.0.0",
        "@scarf/scarf": "^1.4.0",
        "cli-progress": "^3.12.0",
        "commander": "^14.0.3",
        "cors": "^2.8.5",
        "express": "^4.19.2",
+        "express-rate-limit": "^8.4.1",
        "glob": "^13.0.6",
        "graphology": "^0.26.0",
        "graphology-indices": "^0.17.0",
        "graphology-utils": "^2.3.0",
        "ignore": "^7.0.5",
        "js-yaml": "^4.1.1",
+        "jsonc-parser": "^3.3.1",
        "lru-cache": "^11.0.0",
        "mnemonist": "^0.40.3",
        "onnxruntime-node": "^1.24.0",
        "pandemonium": "^2.4.0",
        "tree-sitter": "^0.21.1",
-        "tree-sitter-c": "0.23.2",
+        "tree-sitter-c": "0.21.4",
        "tree-sitter-c-sharp": "0.23.1",
-        "tree-sitter-cpp": "^0.23.4",
+        "tree-sitter-cpp": "0.23.2",
        "tree-sitter-go": "^0.23.0",
        "tree-sitter-java": "^0.23.5",
        "tree-sitter-javascript": "^0.23.0",
@@ -64,17 +66,17 @@
      "optionalDependencies": {
        "node-addon-api": "^8.0.0",
        "node-gyp-build": "^4.8.0",
-        "tree-sitter-dart": "git+https://github.com/UserNobody14/tree-sitter-dart.git#80e23c07b64494f7e21090bb3450223ef0b192f4",
+        "tree-sitter-dart": "file:./vendor/tree-sitter-dart",
        "tree-sitter-kotlin": "^0.3.8",
        "tree-sitter-proto": "file:./vendor/tree-sitter-proto",
-        "tree-sitter-swift": "^0.6.0"
+        "tree-sitter-swift": "file:./vendor/tree-sitter-swift"
      }
    },
    "../gitnexus-shared": {
      "version": "1.0.0",
      "dev": true,
      "devDependencies": {
-        "typescript": "^6.0.2"
+        "typescript": "^6.0.3"
      }
    },
    "node_modules/@babel/helper-string-parser": {
@@ -613,9 +615,9 @@
      }
    },
    "node_modules/@hono/node-server": {
-      "version": "1.19.11",
-      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.11.tgz",
-      "integrity": "sha512-dr8/3zEaB+p0D2n/IUrlPF1HZm586qgJNXK1a9fhg/PzdtkK7Ksd5l312tJX2yBuALqDYBlG20QEbayqPyxn+g==",
+      "version": "1.19.14",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.14.tgz",
+      "integrity": "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==",
      "license": "MIT",
      "engines": {
        "node": ">=18.14.1"
@@ -640,15 +642,15 @@
      "license": "Apache-2.0"
    },
    "node_modules/@huggingface/transformers": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/@huggingface/transformers/-/transformers-4.1.0.tgz",
-      "integrity": "sha512-WiMf9eyvF6V2pj4gs12A7GQV3svyFIBtB/W+Hn5lT5E5DyqWUno1ZrWoAfJv69X1RNv/0GoOo6DFmL6NOYd+rg==",
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/@huggingface/transformers/-/transformers-4.2.0.tgz",
+      "integrity": "sha512-8BRCoBMH0XsWaEIamuR0LrJGAfftgHAfb2Vrffy0VKlSAE/MnUJ5/h/zTfEP3fDIft+nk7TqB8xXEyABGitBjQ==",
      "license": "Apache-2.0",
      "dependencies": {
        "@huggingface/jinja": "^0.5.6",
        "@huggingface/tokenizers": "^0.1.3",
        "onnxruntime-node": "1.24.3",
-        "onnxruntime-web": "1.26.0-dev.20260410-5e55544225",
+        "onnxruntime-web": "1.26.0-dev.20260416-b7804b056c",
        "sharp": "^0.34.5"
      }
    },
@@ -1158,9 +1160,9 @@
      }
    },
    "node_modules/@ladybugdb/core": {
-      "version": "0.15.3",
-      "resolved": "https://registry.npmjs.org/@ladybugdb/core/-/core-0.15.3.tgz",
-      "integrity": "sha512-Xa8VmWhMTvTCWmApnqm9FJtyxxV+CiMCokl1p9vEfXNuBz3SWXWGDmHlzKikswtQbUe9tTV3J9MxPdVFVE6/yg==",
+      "version": "0.16.1",
+      "resolved": "https://registry.npmjs.org/@ladybugdb/core/-/core-0.16.1.tgz",
+      "integrity": "sha512-qwuEcR8CVMKb6tNDaHtq7Ux8hT/XbPC0db+vwutX6JxNAejyx7YomHKPSy9XAKURhYK8mezZe3UN8rf+xpHOjQ==",
      "hasInstallScript": true,
      "license": "MIT",
      "dependencies": {
@@ -1168,16 +1170,17 @@
        "node-addon-api": "^6.0.0"
      },
      "optionalDependencies": {
-        "@ladybugdb/core-darwin-arm64": "0.15.3",
-        "@ladybugdb/core-linux-arm64": "0.15.3",
-        "@ladybugdb/core-linux-x64": "0.15.3",
-        "@ladybugdb/core-win32-x64": "0.15.3"
+        "@ladybugdb/core-darwin-arm64": "0.16.1",
+        "@ladybugdb/core-darwin-x64": "0.16.1",
+        "@ladybugdb/core-linux-arm64": "0.16.1",
+        "@ladybugdb/core-linux-x64": "0.16.1",
+        "@ladybugdb/core-win32-x64": "0.16.1"
      }
    },
    "node_modules/@ladybugdb/core-darwin-arm64": {
-      "version": "0.15.3",
-      "resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-arm64/-/core-darwin-arm64-0.15.3.tgz",
-      "integrity": "sha512-+bqAb3wbbmxPSeNQjbVd6Ek5K8GbHr1KlDr09YkNqZ7XWhKqWxbs097xAG9bynLcZh9oxok2PGCoK4w5YHs11w==",
+      "version": "0.16.1",
+      "resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-arm64/-/core-darwin-arm64-0.16.1.tgz",
+      "integrity": "sha512-Nl+Cf70rD+HaC9IBHv+oeUwqX9plghXD7PN9tyMzMohRVPvcGEbqWPB6YcdJa8rR7qRqCCbmaNMDen5wg4rY2w==",
      "cpu": [
        "arm64"
      ],
@@ -1187,10 +1190,23 @@
        "darwin"
      ]
    },
+    "node_modules/@ladybugdb/core-darwin-x64": {
+      "version": "0.16.1",
+      "resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-x64/-/core-darwin-x64-0.16.1.tgz",
+      "integrity": "sha512-4eAjfimAAQRSmDfUUkGrl9OhefxcW1ziA9tl0eljBlGoUseE7dL02+RSqjGohYMcQ+lzuHAq1QWb0XRlMA8YTQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
    "node_modules/@ladybugdb/core-linux-arm64": {
-      "version": "0.15.3",
-      "resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-arm64/-/core-linux-arm64-0.15.3.tgz",
-      "integrity": "sha512-Z8Ur6YbC5y6pgtKh/7b1/xdeRHy69sGhsoVJm1tc9xp9Zrar6G2A71bEdjOdDJ/mDRt6RtY0zdhUgIgQXYQtbQ==",
+      "version": "0.16.1",
+      "resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-arm64/-/core-linux-arm64-0.16.1.tgz",
+      "integrity": "sha512-zkctksev+hsPFrNxHHdq4lYK5OWdLhWfRdQzjzkgDyaHayHU6yCL2fgD6uPGQ8TRQ6/2DxMErb4p3FzGW85Ubw==",
      "cpu": [
        "arm64"
      ],
@@ -1201,9 +1217,9 @@
      ]
    },
    "node_modules/@ladybugdb/core-linux-x64": {
-      "version": "0.15.3",
-      "resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-x64/-/core-linux-x64-0.15.3.tgz",
-      "integrity": "sha512-DT9xBc91tuxzjRu1dJ3xGt/K/uR1Q8bX5+8tCtj66UbVIVvp1RWAAE9phq7eahcF/3zBuFRonkxW/tTyQdQIlQ==",
+      "version": "0.16.1",
+      "resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-x64/-/core-linux-x64-0.16.1.tgz",
+      "integrity": "sha512-5rAb9T5vif8WKhHwhobosu2/aiOwJkWb/ViybvUc5GFKunKl8VI6RmZQVeufT9zUzRktUwrxBrxblCxsnamXJw==",
      "cpu": [
        "x64"
      ],
@@ -1214,9 +1230,9 @@
      ]
    },
    "node_modules/@ladybugdb/core-win32-x64": {
-      "version": "0.15.3",
-      "resolved": "https://registry.npmjs.org/@ladybugdb/core-win32-x64/-/core-win32-x64-0.15.3.tgz",
-      "integrity": "sha512-ymHC8nHGIT7M9aditBQFIystxW+WoqvI3xklz22BHaFpU9CrTNtdU20K6cuRZvqEA2//Edu7kMoP9OwLkIleCg==",
+      "version": "0.16.1",
+      "resolved": "https://registry.npmjs.org/@ladybugdb/core-win32-x64/-/core-win32-x64-0.16.1.tgz",
+      "integrity": "sha512-ShOUTrIuZKQ63J95tcRJxKf1cvg8yi2FSYx9kMTSercc1FdQZPV+zxUN0myMq3MTWOl7xDxsVMmdp/t80O29UQ==",
      "cpu": [
        "x64"
      ],
@@ -2427,13 +2443,6 @@
        "node": ">= 0.8"
      }
    },
-    "node_modules/boolean": {
-      "version": "3.2.0",
-      "resolved": "https://registry.npmjs.org/boolean/-/boolean-3.2.0.tgz",
-      "integrity": "sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw==",
-      "deprecated": "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.",
-      "license": "MIT"
-    },
    "node_modules/brace-expansion": {
      "version": "5.0.5",
      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz",
@@ -2762,12 +2771,6 @@
        "node": ">=8"
      }
    },
-    "node_modules/detect-node": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/detect-node/-/detect-node-2.1.0.tgz",
-      "integrity": "sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g==",
-      "license": "MIT"
-    },
    "node_modules/dunder-proto": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
@@ -2840,12 +2843,6 @@
        "node": ">= 0.4"
      }
    },
-    "node_modules/es6-error": {
-      "version": "4.1.1",
-      "resolved": "https://registry.npmjs.org/es6-error/-/es6-error-4.1.1.tgz",
-      "integrity": "sha512-Um/+FxMr9CISWh0bi5Zv0iOD+4cFh5qLeks1qhAopKVAJw3drgKbKySikp7wGhDL0HPeaja0P5ULZrxLkniUVg==",
-      "license": "MIT"
-    },
    "node_modules/esbuild": {
      "version": "0.27.4",
      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.4.tgz",
@@ -3021,9 +3018,9 @@
      }
    },
    "node_modules/express-rate-limit": {
-      "version": "8.3.1",
-      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.3.1.tgz",
-      "integrity": "sha512-D1dKN+cmyPWuvB+G2SREQDzPY1agpBIcTa9sJxOPMCNeH3gwzhqJRDWCXW3gg0y//+LQ/8j52JbMROWyrKdMdw==",
+      "version": "8.5.0",
+      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.5.0.tgz",
+      "integrity": "sha512-XKhFohWaSBdVJNTi5TaHziqnPkv04I9UQV6q1Wy7Ui6GGQZVW12ojDFwqer14EvCXxjvPG0CyWXx7cAXpALB4Q==",
      "license": "MIT",
      "dependencies": {
        "ip-address": "10.1.0"
@@ -3269,17 +3266,15 @@
      }
    },
    "node_modules/global-agent": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/global-agent/-/global-agent-3.0.0.tgz",
-      "integrity": "sha512-PT6XReJ+D07JvGoxQMkT6qji/jVNfX/h364XHZOWeRzy64sSFr+xJ5OX7LI3b4MPQzdL4H8Y8M0xzPpsVMwA8Q==",
+      "version": "4.1.3",
+      "resolved": "https://registry.npmjs.org/global-agent/-/global-agent-4.1.3.tgz",
+      "integrity": "sha512-KUJEViiuFT3I97t+GYMikLPJS2Lfo/S2F+DQuBWzuzaMPnvt5yyZePzArx36fBzpGTxZjIpDbXLeySLgh+k76g==",
      "license": "BSD-3-Clause",
      "dependencies": {
-        "boolean": "^3.0.1",
-        "es6-error": "^4.1.1",
-        "matcher": "^3.0.0",
-        "roarr": "^2.15.3",
-        "semver": "^7.3.2",
-        "serialize-error": "^7.0.1"
+        "globalthis": "^1.0.2",
+        "matcher": "^4.0.0",
+        "semver": "^7.3.5",
+        "serialize-error": "^8.1.0"
      },
      "engines": {
        "node": ">=10.0"
@@ -3422,9 +3417,9 @@
      }
    },
    "node_modules/hono": {
-      "version": "4.12.9",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.9.tgz",
-      "integrity": "sha512-wy3T8Zm2bsEvxKZM5w21VdHDDcwVS1yUFFY6i8UobSsKfFceT7TOwhbhfKsDyx7tYQlmRM5FLpIuYvNFyjctiA==",
+      "version": "4.12.16",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.16.tgz",
+      "integrity": "sha512-jN0ZewiNAWSe5khM3EyCmBb250+b40wWbwNILNfEvq84VREWwOIkuUsFONk/3i3nqkz7Oe1PcpM2mwQEK2L9Kg==",
      "license": "MIT",
      "engines": {
        "node": ">=16.9.0"
@@ -3611,11 +3606,11 @@
      "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
      "license": "BSD-2-Clause"
    },
-    "node_modules/json-stringify-safe": {
-      "version": "5.0.1",
-      "resolved": "https://registry.npmjs.org/json-stringify-safe/-/json-stringify-safe-5.0.1.tgz",
-      "integrity": "sha512-ZClg6AaYvamvYEE82d3Iyd3vSSIjQ+odgjaTzRuO3s7toCdFKczob2i0zCh7JE8kWn17yvAWhUVxvqGwUalsRA==",
-      "license": "ISC"
+    "node_modules/jsonc-parser": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz",
+      "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
+      "license": "MIT"
    },
    "node_modules/jsonfile": {
      "version": "6.2.0",
@@ -3897,9 +3892,9 @@
      "license": "Apache-2.0"
    },
    "node_modules/lru-cache": {
-      "version": "11.3.5",
-      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.3.5.tgz",
-      "integrity": "sha512-NxVFwLAnrd9i7KUBxC4DrUhmgjzOs+1Qm50D3oF1/oL+r1NpZ4gA7xvG0/zJ8evR7zIKn4vLf7qTNduWFtCrRw==",
+      "version": "11.3.6",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.3.6.tgz",
+      "integrity": "sha512-Gf/KoL3C/MlI7Bt0PGI9I+TeTC/I6r/csU58N4BSNc4lppLBeKsOdFYkK+dX0ABDUMJNfCHTyPpzwwO21Awd3A==",
      "license": "BlueOak-1.0.0",
      "engines": {
        "node": "20 || >=22"
@@ -3944,15 +3939,18 @@
      }
    },
    "node_modules/matcher": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/matcher/-/matcher-3.0.0.tgz",
-      "integrity": "sha512-OkeDaAZ/bQCxeFAozM55PKcKU0yJMPGifLwV4Qgjitu+5MoAfSQN4lsLJeXZ1b8w0x+/Emda6MZgXS1jvsapng==",
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/matcher/-/matcher-4.0.0.tgz",
+      "integrity": "sha512-S6x5wmcDmsDRRU/c2dkccDwQPXoFczc5+HpQ2lON8pnvHlnvHAHj5WlLVvw6n6vNyHuVugYrFohYxbS+pvFpKQ==",
      "license": "MIT",
      "dependencies": {
        "escape-string-regexp": "^4.0.0"
      },
      "engines": {
        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
    "node_modules/math-intrinsics": {
@@ -4070,9 +4068,9 @@
      }
    },
    "node_modules/mnemonist": {
-      "version": "0.40.3",
-      "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.40.3.tgz",
-      "integrity": "sha512-Vjyr90sJ23CKKH/qPAgUKicw/v6pRoamxIEDFOF8uSgFME7DqPRpHgRTejWVjkdGg5dXj0/NyxZHZ9bcjH+2uQ==",
+      "version": "0.40.4",
+      "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.40.4.tgz",
+      "integrity": "sha512-ZAv+KNavneRVzu4tUeOgzkScI3W5BGwZ3rkxIpKtzzVgfTtWQFN1CgX0U72cyvyh3iTuHL3SiSmrQxTlryEIcw==",
      "license": "MIT",
      "dependencies": {
        "obliterator": "^2.0.4"
@@ -4207,15 +4205,15 @@
      }
    },
    "node_modules/onnxruntime-common": {
-      "version": "1.24.3",
-      "resolved": "https://registry.npmjs.org/onnxruntime-common/-/onnxruntime-common-1.24.3.tgz",
-      "integrity": "sha512-GeuPZO6U/LBJXvwdaqHbuUmoXiEdeCjWi/EG7Y1HNnDwJYuk6WUbNXpF6luSUY8yASul3cmUlLGrCCL1ZgVXqA==",
+      "version": "1.25.1",
+      "resolved": "https://registry.npmjs.org/onnxruntime-common/-/onnxruntime-common-1.25.1.tgz",
+      "integrity": "sha512-kKvYQFdos4LWJqhZ+nmKu3NT8NXzw8I5x9fNUKe1rNKcPfNKnYXUtW7JBpcKFsvLtrJashRgVYSbFap4cHxvNg==",
      "license": "MIT"
    },
    "node_modules/onnxruntime-node": {
-      "version": "1.24.3",
-      "resolved": "https://registry.npmjs.org/onnxruntime-node/-/onnxruntime-node-1.24.3.tgz",
-      "integrity": "sha512-JH7+czbc8ALA819vlTgcV+Q214/+VjGeBHDjX81+ZCD0PCVCIFGFNtT0V4sXG/1JXypKPgScQcB3ij/hk3YnTg==",
+      "version": "1.25.1",
+      "resolved": "https://registry.npmjs.org/onnxruntime-node/-/onnxruntime-node-1.25.1.tgz",
+      "integrity": "sha512-N0M58CGTiTsLkPpx9bxmRFi24GT6r67Qei/GrBEIiDyntcYdXU5vQZp112ypydG9vEKRFgbgUYQJnEi+jll8dg==",
      "hasInstallScript": true,
      "license": "MIT",
      "os": [
@@ -4225,14 +4223,14 @@
      ],
      "dependencies": {
        "adm-zip": "^0.5.16",
-        "global-agent": "^3.0.0",
-        "onnxruntime-common": "1.24.3"
+        "global-agent": "^4.1.3",
+        "onnxruntime-common": "1.25.1"
      }
    },
    "node_modules/onnxruntime-web": {
-      "version": "1.26.0-dev.20260410-5e55544225",
-      "resolved": "https://registry.npmjs.org/onnxruntime-web/-/onnxruntime-web-1.26.0-dev.20260410-5e55544225.tgz",
-      "integrity": "sha512-hHd9n8DzIfGSAjM4Dvslesc8i6h9HEEcl8qt7X3LfhUxMgls6FBJ32j2xrDtJjKJFEehFeJmyB/pvad1I8KS8w==",
+      "version": "1.26.0-dev.20260416-b7804b056c",
+      "resolved": "https://registry.npmjs.org/onnxruntime-web/-/onnxruntime-web-1.26.0-dev.20260416-b7804b056c.tgz",
+      "integrity": "sha512-MD6Ss4GSpQBo6zqoJzyT9LRbKYs7x/JVN23FT24EcEvlqF4VuzPOeH6X38orZPKHQDbprn7K+SBpu0/mj2CQiw==",
      "license": "MIT",
      "dependencies": {
        "flatbuffers": "^25.1.24",
@@ -4513,23 +4511,6 @@
        "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
      }
    },
-    "node_modules/roarr": {
-      "version": "2.15.4",
-      "resolved": "https://registry.npmjs.org/roarr/-/roarr-2.15.4.tgz",
-      "integrity": "sha512-CHhPh+UNHD2GTXNYhPWLnU8ONHdI+5DI+4EYIAOaiD63rHeYlZvyh8P+in5999TTSFgUYuKUAjzRI4mdh/p+2A==",
-      "license": "BSD-3-Clause",
-      "dependencies": {
-        "boolean": "^3.0.1",
-        "detect-node": "^2.0.4",
-        "globalthis": "^1.0.1",
-        "json-stringify-safe": "^5.0.1",
-        "semver-compare": "^1.0.0",
-        "sprintf-js": "^1.1.2"
-      },
-      "engines": {
-        "node": ">=8.0"
-      }
-    },
    "node_modules/rolldown": {
      "version": "1.0.0-rc.16",
      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.16.tgz",
@@ -4628,12 +4609,6 @@
        "node": ">=10"
      }
    },
-    "node_modules/semver-compare": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/semver-compare/-/semver-compare-1.0.0.tgz",
-      "integrity": "sha512-YM3/ITh2MJ5MtzaM429anh+x2jiLVjqILF4m4oyQB18W7Ggea7BfqdH/wGMK7dDiMghv/6WG7znWMwUDzJiXow==",
-      "license": "MIT"
-    },
    "node_modules/send": {
      "version": "0.19.2",
      "resolved": "https://registry.npmjs.org/send/-/send-0.19.2.tgz",
@@ -4674,12 +4649,12 @@
      "license": "MIT"
    },
    "node_modules/serialize-error": {
-      "version": "7.0.1",
-      "resolved": "https://registry.npmjs.org/serialize-error/-/serialize-error-7.0.1.tgz",
-      "integrity": "sha512-8I8TjW5KMOKsZQTvoxjuSIa7foAwPWGOts+6o7sgjz41/qMD9VQHEDxi6PBvK2l0MXUmqZyNpUK+T2tQaaElvw==",
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/serialize-error/-/serialize-error-8.1.0.tgz",
+      "integrity": "sha512-3NnuWfM6vBYoy5gZFvHiYsVbafvI9vZv/+jlIigFn4oP4zjNPK3LhcY0xSCgeb1a5L8jO71Mit9LlNoi2UfDDQ==",
      "license": "MIT",
      "dependencies": {
-        "type-fest": "^0.13.1"
+        "type-fest": "^0.20.2"
      },
      "engines": {
        "node": ">=10"
@@ -4863,12 +4838,6 @@
        "node": ">=0.10.0"
      }
    },
-    "node_modules/sprintf-js": {
-      "version": "1.1.3",
-      "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.1.3.tgz",
-      "integrity": "sha512-Oo+0REFV59/rz3gfJNKQiBlwfHaSESl1pcGyABQsnnIfWOFt6JNj5gCog2U6MLZ//IGYD+nA8nI+mTShREReaA==",
-      "license": "BSD-3-Clause"
-    },
    "node_modules/stackback": {
      "version": "0.0.2",
      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
@@ -5021,20 +4990,20 @@
      }
    },
    "node_modules/tree-sitter-c": {
-      "version": "0.23.2",
-      "resolved": "https://registry.npmjs.org/tree-sitter-c/-/tree-sitter-c-0.23.2.tgz",
-      "integrity": "sha512-9kADOx31AF94DHcrsMGW0zM/2LS6v7wFkPHPVm7RQU+vYVVZMKZ2FJ9e99pm5feqsAcjUzB9CarqDLgRT1Fe/w==",
+      "version": "0.21.4",
+      "resolved": "https://registry.npmjs.org/tree-sitter-c/-/tree-sitter-c-0.21.4.tgz",
+      "integrity": "sha512-IahxFIhXiY15SUlrt2upBiKSBGdOaE1fjKLK1Ik5zxqGHf6T1rvr3IJrovbsE5sXhypx7Hnmf50gshsppaIihA==",
      "hasInstallScript": true,
      "license": "MIT",
      "dependencies": {
-        "node-addon-api": "^8.2.2",
-        "node-gyp-build": "^4.8.2"
+        "node-addon-api": "^8.0.0",
+        "node-gyp-build": "^4.8.1"
      },
      "peerDependencies": {
-        "tree-sitter": "^0.21.1"
+        "tree-sitter": "^0.21.0"
      },
      "peerDependenciesMeta": {
-        "tree-sitter": {
+        "tree_sitter": {
          "optional": true
        }
      }
@@ -5058,30 +5027,15 @@
        }
      }
    },
-    "node_modules/tree-sitter-cli": {
-      "version": "0.23.2",
-      "resolved": "https://registry.npmjs.org/tree-sitter-cli/-/tree-sitter-cli-0.23.2.tgz",
-      "integrity": "sha512-kPPXprOqREX+C/FgUp2Qpt9jd0vSwn+hOgjzVv/7hapdoWpa+VeWId53rf4oNNd29ikheF12BYtGD/W90feMbA==",
-      "hasInstallScript": true,
-      "license": "MIT",
-      "optional": true,
-      "bin": {
-        "tree-sitter": "cli.js"
-      },
-      "engines": {
-        "node": ">=12.0.0"
-      }
-    },
    "node_modules/tree-sitter-cpp": {
-      "version": "0.23.4",
-      "resolved": "https://registry.npmjs.org/tree-sitter-cpp/-/tree-sitter-cpp-0.23.4.tgz",
-      "integrity": "sha512-qR5qUDyhZ5jJ6V8/umiBxokRbe89bCGmcq/dk94wI4kN86qfdV8k0GHIUEKaqWgcu42wKal5E97LKpLeVW8sKw==",
+      "version": "0.23.2",
+      "resolved": "https://registry.npmjs.org/tree-sitter-cpp/-/tree-sitter-cpp-0.23.2.tgz",
+      "integrity": "sha512-GTa5Dx1O9ihzW70LvaUviTclh+wlBDRz6opR9Ij4NQIFmq/joeZ/k65UbLV4nLidR7xZ9eNNGT/SonCqAmjGVg==",
      "hasInstallScript": true,
      "license": "MIT",
      "dependencies": {
        "node-addon-api": "^8.2.1",
-        "node-gyp-build": "^4.8.2",
-        "tree-sitter-c": "^0.23.1"
+        "node-gyp-build": "^4.8.2"
      },
      "peerDependencies": {
        "tree-sitter": "^0.21.1"
@@ -5093,31 +5047,8 @@
      }
    },
    "node_modules/tree-sitter-dart": {
-      "version": "1.0.0",
-      "resolved": "git+ssh://git@github.com/UserNobody14/tree-sitter-dart.git#80e23c07b64494f7e21090bb3450223ef0b192f4",
-      "integrity": "sha512-Bs/1wAOIJ2akPEXlE/XVpuES19Oo3NqoSJRJ/0N2r38qAd9nTXdqmaGHQ44/JXnA6QHcbgD2YzCCc4wUc98cyQ==",
-      "hasInstallScript": true,
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "node-addon-api": "^7.1.0",
-        "node-gyp-build": "^4.8.0"
-      },
-      "peerDependencies": {
-        "tree-sitter": "^0.21.0"
-      },
-      "peerDependenciesMeta": {
-        "tree_sitter": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/tree-sitter-dart/node_modules/node-addon-api": {
-      "version": "7.1.1",
-      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
-      "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
-      "license": "MIT",
-      "optional": true
+      "resolved": "vendor/tree-sitter-dart",
+      "link": true
    },
    "node_modules/tree-sitter-go": {
      "version": "0.23.4",
@@ -5284,49 +5215,8 @@
      }
    },
    "node_modules/tree-sitter-swift": {
-      "version": "0.6.0",
-      "resolved": "https://registry.npmjs.org/tree-sitter-swift/-/tree-sitter-swift-0.6.0.tgz",
-      "integrity": "sha512-9vOJZes4/UFjBr4COHtp6ZHVuZYwfChSQbpneXQog04dAstfx5px3ybVX2cN+ylvLqsvVpmXLpidxxgF2rDQ7A==",
-      "hasInstallScript": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "node-addon-api": "^8.0.0",
-        "node-gyp-build": "^4.8.0",
-        "tree-sitter-cli": "^0.23",
-        "which": "2.0.2"
-      },
-      "peerDependencies": {
-        "tree-sitter": "^0.21.1"
-      },
-      "peerDependenciesMeta": {
-        "tree_sitter": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/tree-sitter-swift/node_modules/isexe": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
-      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
-      "license": "ISC",
-      "optional": true
-    },
-    "node_modules/tree-sitter-swift/node_modules/which": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
-      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "isexe": "^2.0.0"
-      },
-      "bin": {
-        "node-which": "bin/node-which"
-      },
-      "engines": {
-        "node": ">= 8"
-      }
+      "resolved": "vendor/tree-sitter-swift",
+      "link": true
    },
    "node_modules/tree-sitter-typescript": {
      "version": "0.23.2",
@@ -5376,9 +5266,9 @@
      }
    },
    "node_modules/type-fest": {
-      "version": "0.13.1",
-      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.13.1.tgz",
-      "integrity": "sha512-34R7HTnG0XIJcBSn5XhDd7nNFPRcXYRZrBB2O2jdKqYODldSzBAqzsWoZYYvduky73toYS/ESqxPvkDf/F0XMg==",
+      "version": "0.20.2",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.20.2.tgz",
+      "integrity": "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==",
      "license": "(MIT OR CC0-1.0)",
      "engines": {
        "node": ">=10"
@@ -5761,6 +5651,19 @@
        "zod": "^3.25.28 || ^4"
      }
    },
+    "vendor/tree-sitter-dart": {
+      "version": "1.0.0",
+      "license": "ISC",
+      "optional": true,
+      "peerDependencies": {
+        "tree-sitter": "^0.21.0"
+      },
+      "peerDependenciesMeta": {
+        "tree_sitter": {
+          "optional": true
+        }
+      }
+    },
    "vendor/tree-sitter-proto": {
      "version": "0.4.1",
      "license": "MIT",
@@ -5768,6 +5671,24 @@
      "peerDependencies": {
        "tree-sitter": ">=0.21.0"
      }
+    },
+    "vendor/tree-sitter-swift": {
+      "version": "0.7.1",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "node-addon-api": "^8.0.0",
+        "node-gyp-build": "^4.8.0"
+      },
+      "peerDependencies": {
+        "tree-sitter": "^0.21.1 || ^0.22.1"
+      },
+      "peerDependenciesMeta": {
+        "tree-sitter": {
+          "optional": true
+        }
+      }
    }
  }
 }
@@ -1,6 +1,6 @@
 {
  "name": "gitnexus",
-  "version": "1.6.2",
+  "version": "1.6.4-rc.74",
  "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",
@@ -35,7 +35,8 @@
    "hooks",
    "scripts",
    "skills",
-    "vendor"
+    "vendor",
+    "web"
  ],
  "scripts": {
    "build": "node scripts/build.js",
@@ -46,33 +47,35 @@
    "test:integration": "vitest run test/integration",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage",
-    "postinstall": "node scripts/patch-tree-sitter-swift.cjs && node scripts/build-tree-sitter-proto.cjs",
+    "postinstall": "node scripts/build-tree-sitter-dart.cjs && node scripts/build-tree-sitter-proto.cjs",
    "prepare": "node scripts/build.js",
    "prepack": "node scripts/build.js"
  },
  "dependencies": {
    "@huggingface/transformers": "^4.1.0",
-    "@ladybugdb/core": "^0.15.2",
+    "@ladybugdb/core": "^0.16.1",
    "@modelcontextprotocol/sdk": "^1.0.0",
    "@scarf/scarf": "^1.4.0",
    "cli-progress": "^3.12.0",
    "commander": "^14.0.3",
    "cors": "^2.8.5",
    "express": "^4.19.2",
+    "express-rate-limit": "^8.4.1",
    "glob": "^13.0.6",
    "graphology": "^0.26.0",
    "graphology-indices": "^0.17.0",
    "graphology-utils": "^2.3.0",
    "ignore": "^7.0.5",
    "js-yaml": "^4.1.1",
+    "jsonc-parser": "^3.3.1",
    "lru-cache": "^11.0.0",
    "mnemonist": "^0.40.3",
    "onnxruntime-node": "^1.24.0",
    "pandemonium": "^2.4.0",
    "tree-sitter": "^0.21.1",
-    "tree-sitter-c": "0.23.2",
+    "tree-sitter-c": "0.21.4",
    "tree-sitter-c-sharp": "0.23.1",
-    "tree-sitter-cpp": "^0.23.4",
+    "tree-sitter-cpp": "0.23.2",
    "tree-sitter-go": "^0.23.0",
    "tree-sitter-java": "^0.23.5",
    "tree-sitter-javascript": "^0.23.0",
@@ -86,10 +89,10 @@
  "optionalDependencies": {
    "node-addon-api": "^8.0.0",
    "node-gyp-build": "^4.8.0",
-    "tree-sitter-dart": "git+https://github.com/UserNobody14/tree-sitter-dart.git#80e23c07b64494f7e21090bb3450223ef0b192f4",
+    "tree-sitter-dart": "file:./vendor/tree-sitter-dart",
    "tree-sitter-kotlin": "^0.3.8",
    "tree-sitter-proto": "file:./vendor/tree-sitter-proto",
-    "tree-sitter-swift": "^0.6.0"
+    "tree-sitter-swift": "file:./vendor/tree-sitter-swift"
  },
  "devDependencies": {
    "@types/cli-progress": "^3.11.6",
@@ -107,8 +110,7 @@
  "overrides": {
    "@huggingface/transformers": {
      "onnxruntime-node": "$onnxruntime-node"
-    },
-    "tree-sitter-c": "0.23.2"
+    }
  },
  "engines": {
    "node": ">=20.0.0"
@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const dartDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-dart');
+const bindingGyp = path.join(dartDir, 'binding.gyp');
+const bindingNode = path.join(dartDir, 'build', 'Release', 'tree_sitter_dart_binding.node');
+
+try {
+  if (!fs.existsSync(bindingGyp) || fs.existsSync(bindingNode)) {
+    process.exit(0);
+  }
+
+  try {
+    require.resolve('node-addon-api');
+    require.resolve('node-gyp-build');
+  } catch (resolveErr) {
+    console.warn(
+      '[tree-sitter-dart] Skipping build: hoisted build deps not resolvable (%s).',
+      resolveErr.message,
+    );
+    console.warn(
+      '[tree-sitter-dart] Dart parsing will be unavailable. Install without --no-optional and with scripts enabled to build.',
+    );
+    process.exit(0);
+  }
+
+  console.log('[tree-sitter-dart] Building native binding...');
+  execSync('npx node-gyp rebuild', {
+    cwd: dartDir,
+    stdio: 'pipe',
+    timeout: 180000,
+  });
+  console.log('[tree-sitter-dart] Native binding built successfully');
+} catch (err) {
+  console.warn('[tree-sitter-dart] Could not build native binding:', err.message);
+  console.warn(
+    '[tree-sitter-dart] Dart parsing will be unavailable. Non-Dart functionality is unaffected.',
+  );
+  process.exit(0);
+}
@@ -26,7 +26,7 @@
 *   `node_modules/tree-sitter-proto/build/Release/tree_sitter_proto_binding.node`
 *   — under npm-managed territory, safe on upgrade.
 *
- *   Mirrors scripts/patch-tree-sitter-swift.cjs. Best-effort: if any
+ *   Mirrors the tree-sitter-dart build helper. Best-effort: if any
 *   precondition fails (optional dep absent, no toolchain, --ignore-scripts),
 *   warn and exit 0 so gitnexus install still succeeds.
 */
@@ -21,11 +21,11 @@ const SHARED_DEST = path.join(DIST, '_shared');

 // ── 1. Build gitnexus-shared ───────────────────────────────────────
 console.log('[build] compiling gitnexus-shared…');
-execSync('npx tsc', { cwd: SHARED_ROOT, stdio: 'inherit' });
+execSync('npx tsc', { cwd: SHARED_ROOT, stdio: 'inherit', timeout: 120_000 });

 // ── 2. Build gitnexus ──────────────────────────────────────────────
 console.log('[build] compiling gitnexus…');
-execSync('npx tsc', { cwd: ROOT, stdio: 'inherit' });
+execSync('npx tsc', { cwd: ROOT, stdio: 'inherit', timeout: 120_000 });

 // ── 3. Copy shared dist ────────────────────────────────────────────
 console.log('[build] copying shared module into dist/_shared…');
@@ -70,4 +70,24 @@ walk(DIST, ['.js', '.d.ts'], rewriteFile);
 const cliEntry = path.join(DIST, 'cli', 'index.js');
 if (fs.existsSync(cliEntry)) fs.chmodSync(cliEntry, 0o755);

+// ── 6. Build & copy web UI ──────────────────────────────────────────
+const WEB_ROOT = path.resolve(ROOT, '..', 'gitnexus-web');
+const WEB_DEST = path.join(DIST, '..', 'web');
+
+if (fs.existsSync(path.join(WEB_ROOT, 'package.json'))) {
+  console.log('[build] building gitnexus-web…');
+  if (!fs.existsSync(path.join(WEB_ROOT, 'node_modules'))) {
+    console.log('[build] installing gitnexus-web dependencies…');
+    execSync('npm ci', { cwd: WEB_ROOT, stdio: 'inherit', timeout: 120_000 });
+  }
+  execSync('npm run build', { cwd: WEB_ROOT, stdio: 'inherit', timeout: 120_000 });
+
+  // Copy dist → gitnexus/web/ (shipped in the npm package)
+  fs.rmSync(WEB_DEST, { recursive: true, force: true });
+  fs.cpSync(path.join(WEB_ROOT, 'dist'), WEB_DEST, { recursive: true });
+  console.log('[build] copied web UI → gitnexus/web/');
+} else {
+  console.log('[build] skipping web UI (gitnexus-web not found)');
+}
+
 console.log(`[build] done — rewrote ${rewritten} files.`);
@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+function parseLbugMaxDbSize(raw) {
+  const parsed = raw ? Number(raw) : NaN;
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Invalid LadybugDB max DB size for extension installer: ${raw ?? '<missing>'}`);
+  }
+  return Math.floor(parsed);
+}
+
+async function installDuckDbExtension(extensionName) {
+  if (!extensionName || !EXTENSION_NAME_PATTERN.test(extensionName)) {
+    throw new Error(`Invalid DuckDB extension name: ${extensionName ?? '<missing>'}`);
+  }
+
+  const require = createRequire(import.meta.url);
+  const lbugModule = require('@ladybugdb/core');
+  const lbug = lbugModule.default ?? lbugModule;
+  const lbugMaxDbSize = parseLbugMaxDbSize(
+    process.argv[3] ?? process.env.GITNEXUS_LBUG_MAX_DB_SIZE,
+  );
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ext-install-'));
+  const dbPath = path.join(tmpDir, 'install.lbug');
+  let db;
+  let conn;
+
+  try {
+    db = new lbug.Database(dbPath, 0, false, false, lbugMaxDbSize);
+    conn = new lbug.Connection(db);
+    await conn.query(`INSTALL ${extensionName}`);
+  } finally {
+    if (conn) await conn.close().catch(() => {});
+    if (db) await db.close().catch(() => {});
+    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+installDuckDbExtension(process.argv[2] ?? process.env.GITNEXUS_LBUG_EXTENSION_NAME).catch((err) => {
+  console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+  process.exitCode = 1;
+});
@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-/**
- * WORKAROUND: tree-sitter-swift@0.6.0 binding.gyp build failure
- *
- * Background:
- *   tree-sitter-swift@0.6.0's binding.gyp contains an "actions" array that
- *   invokes `tree-sitter generate` to regenerate parser.c from grammar.js.
- *   This is intended for grammar developers, but the published npm package
- *   already ships pre-generated parser files (parser.c, scanner.c), so the
- *   actions are unnecessary for consumers. Since consumers don't have
- *   tree-sitter-cli installed, the actions always fail during `npm install`.
- *
- * Why we can't just upgrade:
- *   tree-sitter-swift@0.7.1 fixes this (removes postinstall, ships prebuilds),
- *   but it requires tree-sitter@^0.22.1. The upstream project pins tree-sitter
- *   to ^0.21.0 and all other grammar packages depend on that version.
- *   Upgrading tree-sitter would be a separate breaking change.
- *
- * How this workaround works:
- *   1. tree-sitter-swift's own postinstall fails (npm warns but continues)
- *   2. This script runs as gitnexus's postinstall
- *   3. It removes the "actions" array from binding.gyp
- *   4. It rebuilds the native binding with the cleaned binding.gyp
- *
- * TODO: Remove this script when tree-sitter is upgraded to ^0.22.x,
- *       which allows using tree-sitter-swift@0.7.1+ directly.
- */
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-
-const swiftDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-swift');
-const bindingPath = path.join(swiftDir, 'binding.gyp');
-
-try {
-  if (!fs.existsSync(bindingPath)) {
-    process.exit(0);
-  }
-
-  const content = fs.readFileSync(bindingPath, 'utf8');
-  let needsRebuild = false;
-
-  if (content.includes('"actions"')) {
-    // Strip Python-style comments (#) and trailing commas before JSON parsing
-    const cleaned = content
-      .replace(/#[^\n]*/g, '') // Remove # comments
-      .replace(/,(\s*[\]}])/g, '$1'); // Remove trailing commas before ] or }
-    const gyp = JSON.parse(cleaned);
-
-    if (gyp.targets && gyp.targets[0] && gyp.targets[0].actions) {
-      delete gyp.targets[0].actions;
-      fs.writeFileSync(bindingPath, JSON.stringify(gyp, null, 2) + '\n');
-      console.log('[tree-sitter-swift] Patched binding.gyp (removed actions array)');
-      needsRebuild = true;
-    }
-  }
-
-  // Check if native binding exists
-  const bindingNode = path.join(swiftDir, 'build', 'Release', 'tree_sitter_swift_binding.node');
-  if (!fs.existsSync(bindingNode)) {
-    needsRebuild = true;
-  }
-
-  if (needsRebuild) {
-    console.log('[tree-sitter-swift] Rebuilding native binding...');
-    execSync('npx node-gyp rebuild', {
-      cwd: swiftDir,
-      stdio: 'pipe',
-      timeout: 120000,
-    });
-    console.log('[tree-sitter-swift] Native binding built successfully');
-  }
-} catch (err) {
-  console.warn('[tree-sitter-swift] Could not build native binding:', err.message);
-  console.warn(
-    '[tree-sitter-swift] You may need to manually run: cd node_modules/tree-sitter-swift && npx node-gyp rebuild',
-  );
-}
@@ -21,8 +21,9 @@ Run from the project root. This parses all source files, builds the knowledge gr
 | -------------- | ---------------------------------------------------------------- |
 | `--force`      | Force full re-index even if up to date                           |
 | `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |

-**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.

 ### status — Check index freshness

@@ -32,6 +32,33 @@ export interface AIContextOptions {
 const GITNEXUS_START_MARKER = '<!-- gitnexus:start -->';
 const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';

+/**
+ * Find the index of a section marker that occupies its own line.
+ * Unlike `indexOf`, this rejects inline prose references like
+ * `` See the `<!-- gitnexus:start -->` block `` that appear
+ * mid-sentence (#1041). A marker counts as section-position only when:
+ *   - preceded by newline or start-of-file, AND
+ *   - followed by newline, `\r` (CRLF files), or end-of-file.
+ * The generator always emits each marker alone on its line, so this
+ * matches every legitimate section and none of the inline mentions.
+ *
+ * `startFrom` lets the end-marker lookup start after the already-found
+ * start marker, avoiding a scan from 0 and guaranteeing we never pick
+ * up an end marker that appears earlier in the file than the start.
+ */
+function findSectionMarkerIndex(content: string, marker: string, startFrom = 0): number {
+  let idx = content.indexOf(marker, startFrom);
+  while (idx !== -1) {
+    const atLineStart = idx === 0 || content[idx - 1] === '\n';
+    const endPos = idx + marker.length;
+    const atLineEnd =
+      endPos === content.length || content[endPos] === '\n' || content[endPos] === '\r';
+    if (atLineStart && atLineEnd) return idx;
+    idx = content.indexOf(marker, idx + 1);
+  }
+  return -1;
+}
+
 /**
 * Generate the full GitNexus context content.
 *
@@ -163,9 +190,18 @@ async function upsertGitNexusSection(

  const existingContent = await fs.readFile(filePath, 'utf-8');

-  // Check if GitNexus section already exists
-  const startIdx = existingContent.indexOf(GITNEXUS_START_MARKER);
-  const endIdx = existingContent.indexOf(GITNEXUS_END_MARKER);
+  // Check if GitNexus section already exists. Matching is restricted
+  // to markers that occupy their own line so that inline prose
+  // references (e.g. `` See the `<!-- gitnexus:start -->` block `` in
+  // the shipped CLAUDE.md) are NOT treated as section delimiters
+  // (#1041). The end-marker scan starts after the start-marker so it
+  // can never pick up an earlier end in the file.
+  const startIdx = findSectionMarkerIndex(existingContent, GITNEXUS_START_MARKER);
+  const endIdx = findSectionMarkerIndex(
+    existingContent,
+    GITNEXUS_END_MARKER,
+    startIdx === -1 ? 0 : startIdx,
+  );

  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
    // Replace existing section
@@ -17,11 +17,52 @@ import {
  getStoragePaths,
  getGlobalRegistryPath,
  RegistryNameCollisionError,
+  AnalysisNotFinalizedError,
+  assertAnalysisFinalized,
 } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir } from '../storage/git.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
+import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
 import fs from 'fs/promises';

+// Capture stderr.write at module load BEFORE anything (LadybugDB native
+// init, progress bar, console redirection) can monkey-patch it. The
+// fatal handlers below MUST reach the user even when the analyze path
+// has redirected console.* through the progress bar's bar.log() — the
+// previous behaviour silently swallowed stack traces and made #1169
+// indistinguishable from a no-op success on Windows.
+const realStderrWrite = process.stderr.write.bind(process.stderr);
+
+const writeFatalToStderr = (label: string, err: unknown): void => {
+  const isErr = err instanceof Error;
+  const message = isErr ? err.message : String(err);
+  realStderrWrite(`\n  ${label}: ${message}\n`);
+  if (isErr && err.stack) realStderrWrite(`${err.stack}\n`);
+};
+
+let fatalHandlersInstalled = false;
+
+/**
+ * Install one-shot `unhandledRejection` / `uncaughtException` handlers
+ * that surface the failure to the real stderr (bypassing any console
+ * redirection installed by the progress bar) and force a non-zero exit
+ * code. Without these, an async error escaping {@link analyzeCommand}'s
+ * try/catch was reported as exit 0 with no diagnostic — the silent
+ * failure mode tracked in #1169.
+ */
+const installFatalHandlers = (): void => {
+  if (fatalHandlersInstalled) return;
+  fatalHandlersInstalled = true;
+  process.on('unhandledRejection', (err) => {
+    writeFatalToStderr('Analysis failed (unhandled rejection)', err);
+    process.exit(1);
+  });
+  process.on('uncaughtException', (err) => {
+    writeFatalToStderr('Analysis failed (uncaught exception)', err);
+    process.exit(1);
+  });
+};
+
 const HEAP_MB = 8192;
 const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
 /** Increase default stack size (KB) to prevent stack overflow on deep class hierarchies. */
@@ -55,6 +96,12 @@ function ensureHeap(): boolean {
 export interface AnalyzeOptions {
  force?: boolean;
  embeddings?: boolean;
+  /**
+   * Explicitly drop existing embeddings on rebuild instead of preserving
+   * them. Without this flag, a routine `analyze` keeps any embeddings
+   * already present in the index even when `--embeddings` is omitted.
+   */
+  dropEmbeddings?: boolean;
  skills?: boolean;
  verbose?: boolean;
  /** Skip AGENTS.md and CLAUDE.md gitnexus block updates. */
@@ -78,35 +125,112 @@ export interface AnalyzeOptions {
   * `allowDuplicateName` option end-to-end.
   */
  allowDuplicateName?: boolean;
+  /**
+   * Override the walker's large-file skip threshold (#991). Value in KB;
+   * clamped downstream to the tree-sitter 32 MB ceiling. Sets
+   * `GITNEXUS_MAX_FILE_SIZE` for the rest of the pipeline.
+   */
+  maxFileSize?: string;
+  /** Override worker sub-batch idle timeout in seconds. */
+  workerTimeout?: string;
+  embeddingThreads?: string;
+  embeddingBatchSize?: string;
+  embeddingSubBatchSize?: string;
+  embeddingDevice?: string;
 }

 export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOptions) => {
  if (ensureHeap()) return;

+  // Install fatal handlers immediately after re-exec resolution so any
+  // async error that escapes the try/catch below (#1169) surfaces with
+  // a stack trace and a non-zero exit code instead of a silent exit 0.
+  installFatalHandlers();
+
  if (options?.verbose) {
    process.env.GITNEXUS_VERBOSE = '1';
  }

+  if (options?.maxFileSize) {
+    process.env.GITNEXUS_MAX_FILE_SIZE = options.maxFileSize;
+  }
+
+  if (options?.workerTimeout) {
+    const workerTimeoutSeconds = Number(options.workerTimeout);
+    if (!Number.isFinite(workerTimeoutSeconds) || workerTimeoutSeconds < 1) {
+      console.error('  --worker-timeout must be at least 1 second.\n');
+      process.exitCode = 1;
+      return;
+    }
+    process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(
+      Math.round(workerTimeoutSeconds * 1000),
+    );
+  }
+
+  const setPositiveEnv = (
+    optionName: string,
+    envName: string,
+    value: string | undefined,
+  ): boolean => {
+    if (value === undefined) return true;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+      console.error(`  ${optionName} must be a positive integer.\n`);
+      process.exitCode = 1;
+      return false;
+    }
+    process.env[envName] = String(parsed);
+    return true;
+  };
+
+  if (
+    !setPositiveEnv(
+      '--embedding-threads',
+      'GITNEXUS_EMBEDDING_THREADS',
+      options?.embeddingThreads,
+    ) ||
+    !setPositiveEnv(
+      '--embedding-batch-size',
+      'GITNEXUS_EMBEDDING_BATCH_SIZE',
+      options?.embeddingBatchSize,
+    ) ||
+    !setPositiveEnv(
+      '--embedding-sub-batch-size',
+      'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
+      options?.embeddingSubBatchSize,
+    )
+  ) {
+    return;
+  }
+
+  if (options?.embeddingDevice) {
+    const allowed = new Set(['auto', 'cpu', 'dml', 'cuda', 'wasm']);
+    if (!allowed.has(options.embeddingDevice)) {
+      console.error('  --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
+      process.exitCode = 1;
+      return;
+    }
+    process.env.GITNEXUS_EMBEDDING_DEVICE = options.embeddingDevice;
+  }
+
  console.log('\n  GitNexus Analyzer\n');

  let repoPath: string;
  if (inputPath) {
    repoPath = path.resolve(inputPath);
+  } else if (options?.skipGit) {
+    // --skip-git: treat cwd as the index root, do not walk up to a parent git repo.
+    repoPath = path.resolve(process.cwd());
  } else {
    const gitRoot = getGitRoot(process.cwd());
    if (!gitRoot) {
-      if (!options?.skipGit) {
-        console.log(
-          '  Not inside a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n',
-        );
-        process.exitCode = 1;
-        return;
-      }
-      // --skip-git: fall back to cwd as the root
-      repoPath = path.resolve(process.cwd());
-    } else {
-      repoPath = gitRoot;
+      console.log(
+        '  Not inside a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n',
+      );
+      process.exitCode = 1;
+      return;
    }
+    repoPath = gitRoot;
  }

  const repoHasGit = hasGitDir(repoPath);
@@ -132,6 +256,11 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
    );
  }

+  const maxFileSizeBanner = getMaxFileSizeBannerMessage();
+  if (maxFileSizeBanner) {
+    console.log(`${maxFileSizeBanner}\n`);
+  }
+
  // ── CLI progress bar setup ─────────────────────────────────────────
  const bar = new cliProgress.SingleBar(
    {
@@ -210,6 +339,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
        // collision guard (see allowDuplicateName below).
        force: options?.force || options?.skills,
        embeddings: options?.embeddings,
+        dropEmbeddings: options?.dropEmbeddings,
        skipGit: options?.skipGit,
        skipAgentsMd: options?.skipAgentsMd,
        noStats: options?.noStats,
@@ -229,6 +359,11 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
    );

    if (result.alreadyUpToDate) {
+      // Even the fast path must prove the repo is discoverable. A prior
+      // run can write meta.json and then fail before registerRepo(); in
+      // that half-finalized state, runFullAnalysis returns alreadyUpToDate
+      // on the next invocation unless we check the registry here too.
+      await assertAnalysisFinalized(repoPath);
      clearInterval(elapsedTimer);
      process.removeListener('SIGINT', sigintHandler);
      console.log = origLog;
@@ -241,6 +376,15 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
      return;
    }

+    // Post-finalize invariant (#1169): runFullAnalysis nominally writes
+    // meta.json and registers the repo, but on Windows it has been
+    // observed to return successfully with neither artifact present
+    // (banner-only output, exit 0). Verify both before declaring
+    // success so the silent-finalize state surfaces with a non-zero
+    // exit code and an actionable error instead of being mistaken for
+    // a healthy index.
+    await assertAnalysisFinalized(repoPath);
+
    // Skill generation (CLI-only, uses pipeline result from analysis)
    if (options?.skills && result.pipelineResult) {
      updateBar(99, 'Generating skill files...');
@@ -342,7 +486,29 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
      return;
    }

-    console.error(`\n  Analysis failed: ${msg}\n`);
+    // Finalize invariant failure (#1169) — keep the rich actionable
+    // message intact and write through realStderrWrite so it can't be
+    // erased by a leftover bar refresh on slow terminals.
+    if (err instanceof AnalysisNotFinalizedError) {
+      writeFatalToStderr('Analysis did not finalize', err);
+      realStderrWrite(
+        `\n  Diagnostic checklist:\n` +
+          `    1. Re-run "gitnexus analyze" - transient native errors often clear on retry.\n` +
+          `    2. Inspect ${err.storagePath} - a leftover lbug.wal indicates an aborted write.\n` +
+          `    3. If the failure persists, run with NODE_OPTIONS="--max-old-space-size=8192 --trace-exit"\n` +
+          `       and attach the trace to the GitNexus issue tracker.\n\n`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    // Bypass the redirected console.error and write the full stack to
+    // the real stderr captured at module load. The redirected
+    // console.error wraps every line with `\\x1b[2K\\r` (ANSI clear-line)
+    // and forces a bar.update() afterwards, which on some Windows
+    // terminals visually erases the failure message — the canonical
+    // shape of the silent-exit symptom in #1169.
+    writeFatalToStderr('Analysis failed', err);

    // Provide helpful guidance for known failure modes
    if (
@@ -0,0 +1,32 @@
+import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/capabilities.js';
+import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
+import { isHttpMode } from '../core/embeddings/http-client.js';
+
+export const doctorCommand = async () => {
+  const fingerprint = getRuntimeFingerprint();
+  const capabilities = getRuntimeCapabilities();
+  const embeddingConfig = resolveEmbeddingConfig();
+
+  console.log('GitNexus Doctor\n');
+  console.log('Runtime');
+  console.log(`  OS:        ${fingerprint.platform}/${fingerprint.arch}`);
+  console.log(`  Node:      ${fingerprint.node}`);
+  console.log(`  GitNexus:  ${fingerprint.gitnexus}`);
+  console.log(`  LadybugDB: ${fingerprint.ladybugdb ?? 'unknown'}`);
+  console.log(`  ONNX:      ${fingerprint.onnxruntime ?? 'unknown'}`);
+  console.log('');
+  console.log('Capabilities');
+  console.log(`  Graph store:     ${capabilities.graph}`);
+  console.log(`  Full-text search:${capabilities.fts.padStart(10)}`);
+  console.log(`  VECTOR index:    ${capabilities.vector}`);
+  console.log(`  Semantic mode:   ${capabilities.semanticMode}`);
+  console.log(`  Exact scan limit:${String(capabilities.exactScanLimit).padStart(9)} chunks`);
+  if (capabilities.reason) console.log(`  Note:            ${capabilities.reason}`);
+  console.log('');
+  console.log('Embeddings');
+  console.log(`  Backend:   ${isHttpMode() ? 'http' : 'local'}`);
+  console.log(`  Device:    ${embeddingConfig.device}`);
+  console.log(`  Threads:   ${embeddingConfig.threads}`);
+  console.log(`  Batch:     ${embeddingConfig.batchSize} nodes`);
+  console.log(`  Sub-batch: ${embeddingConfig.subBatchSize} chunks`);
+};
@@ -14,7 +14,7 @@ import fs from 'fs/promises';
 import {
  getStoragePaths,
  loadMeta,
-  addToGitignore,
+  ensureGitNexusIgnored,
  registerRepo,
 } from '../storage/repo-manager.js';
 import { getGitRoot, getRemoteUrl, isGitRepo } from '../storage/git.js';
@@ -115,7 +115,7 @@ export const indexCommand = async (inputPathParts?: string[], options?: IndexOpt
    meta.remoteUrl = getRemoteUrl(repoPath);
  }
  await registerRepo(repoPath, meta);
-  await addToGitignore(repoPath);
+  await ensureGitNexusIgnored(repoPath);

  const projectName = path.basename(repoPath);
  const { stats } = meta;
@@ -24,10 +24,18 @@ program
  .description('Index a repository (full analysis)')
  .option('-f, --force', 'Force full re-index even if up to date')
  .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
+  .option(
+    '--drop-embeddings',
+    'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` ' +
+      'preserves any embeddings already present in the index.',
+  )
  .option('--skills', 'Generate repo-specific skill files from detected communities')
  .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
  .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
-  .option('--skip-git', 'Index a folder without requiring a .git directory')
+  .option(
+    '--skip-git',
+    'Treat the provided path/cwd as the index root and skip parent git-root discovery',
+  )
  .option(
    '--name <alias>',
    'Register this repo under a custom name in ~/.gitnexus/registry.json ' +
@@ -39,9 +47,29 @@ program
      'Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.',
  )
  .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
+  .option(
+    '--max-file-size <kb>',
+    'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).',
+  )
+  .option(
+    '--worker-timeout <seconds>',
+    'Worker sub-batch idle timeout before retry/fallback. Default: 30.',
+  )
+  .option('--embedding-threads <n>', 'Limit local ONNX embedding CPU threads')
+  .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
+  .option('--embedding-sub-batch-size <n>', 'Number of chunks per embedding model call')
+  .option('--embedding-device <device>', 'Embedding device: auto, cpu, dml, cuda, or wasm')
  .addHelpText(
    'after',
-    '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1  Skip .gitignore parsing (still reads .gitnexusignore)',
+    '\nEnvironment variables:\n' +
+      '  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n' +
+      '  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n' +
+      '  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n' +
+      '  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n' +
+      '  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n' +
+      '  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n' +
+      '\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n' +
+      '     `!__tests__/` to index a directory that is auto-filtered by default (#771).',
  )
  .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));

@@ -76,6 +104,11 @@ program
  .description('Show index status for current repo')
  .action(createLazyAction(() => import('./status.js'), 'statusCommand'));

+program
+  .command('doctor')
+  .description('Show runtime platform capabilities and embedding configuration')
+  .action(createLazyAction(() => import('./doctor.js'), 'doctorCommand'));
+
 program
  .command('clean')
  .description('Delete GitNexus index for current repo')
@@ -13,6 +13,7 @@ import { execFile, execFileSync } from 'child_process';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import { glob } from 'glob';
+import { parseTree, modify, applyEdits, ParseError, parse as parseJsonc } from 'jsonc-parser';
 import { getGlobalDir } from '../storage/repo-manager.js';

 const __filename = fileURLToPath(import.meta.url);
@@ -31,15 +32,27 @@ interface SetupResult {
 */
 function resolveGitnexusBin(): string | null {
  try {
-    const cmd = process.platform === 'win32' ? 'where' : 'which';
-    const resolved = execFileSync(cmd, ['gitnexus'], {
+    const isWin = process.platform === 'win32';
+    const cmd = isWin ? 'where' : 'which';
+    const output = execFileSync(cmd, ['gitnexus'], {
      encoding: 'utf-8',
      timeout: 5000,
      stdio: ['ignore', 'pipe', 'ignore'],
-    })
-      .split('\n')[0]
-      .trim();
-    return resolved || null;
+    });
+    const lines = output
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean);
+
+    if (isWin) {
+      // On Windows, `where` returns multiple entries (e.g. the POSIX shell
+      // script AND the .cmd/.bat wrapper). Prefer the wrapper because
+      // child_process.spawn() cannot execute a shell script directly.
+      const cmdLine = lines.find((l) => /\.(cmd|bat)$/i.test(l));
+      return cmdLine || lines[0] || null;
+    }
+
+    return lines[0] || null;
  } catch {
    return null;
  }
@@ -76,38 +89,70 @@ function getMcpEntry() {
 }

 /**
- * Merge gitnexus entry into an existing MCP config JSON object.
- * Returns the updated config.
+ * OpenCode uses a different MCP format: { type: "local", command: [...] }
+ * where command is a flat array (command + args combined).
 */
-function mergeMcpConfig(existing: any): any {
-  if (!existing || typeof existing !== 'object') {
-    existing = {};
+function getOpenCodeMcpEntry() {
+  const bin = resolveGitnexusBin();
+
+  if (bin) {
+    return { type: 'local', command: [bin, 'mcp'] };
  }
-  if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
-    existing.mcpServers = {};
+
+  if (process.platform === 'win32') {
+    return { type: 'local', command: ['cmd', '/c', 'npx', '-y', 'gitnexus@latest', 'mcp'] };
  }
-  existing.mcpServers.gitnexus = getMcpEntry();
-  return existing;
+  return { type: 'local', command: ['npx', '-y', 'gitnexus@latest', 'mcp'] };
 }

 /**
- * Try to read a JSON file, returning null if it doesn't exist or is invalid.
+ * Detect indentation style from file content.
+ * Returns formatting options matching the file's existing style.
 */
-async function readJsonFile(filePath: string): Promise<any | null> {
+function detectIndentation(raw: string): { tabSize: number; insertSpaces: boolean } {
+  const firstIndented = raw.match(/^( +|\t)/m);
+  if (!firstIndented) return { tabSize: 2, insertSpaces: true };
+  if (firstIndented[1] === '\t') return { tabSize: 1, insertSpaces: false };
+  return { tabSize: firstIndented[1].length, insertSpaces: true };
+}
+
+/**
+ * Merge a key/value pair into a JSONC config file, preserving comments and formatting.
+ * If the file is genuinely corrupt (not valid JSONC), leaves it untouched.
+ */
+async function mergeJsoncFile(
+  filePath: string,
+  keyPath: string[],
+  value: unknown,
+): Promise<boolean> {
+  let raw: string;
  try {
-    const raw = await fs.readFile(filePath, 'utf-8');
-    return JSON.parse(raw);
+    raw = await fs.readFile(filePath, 'utf-8');
  } catch {
-    return null;
+    raw = '';
  }
-}

-/**
- * Write JSON to a file, creating parent directories if needed.
- */
-async function writeJsonFile(filePath: string, data: any): Promise<void> {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  if (raw.trim().length === 0) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const formattingOptions = { tabSize: 2, insertSpaces: true };
+    const edits = modify('{}', keyPath, value, { formattingOptions });
+    const result = applyEdits('{}', edits);
+    await fs.writeFile(filePath, result, 'utf-8');
+    return true;
+  }
+
+  const parseErrors: ParseError[] = [];
+  const tree = parseTree(raw, parseErrors);
+
+  if (tree && tree.type === 'object' && parseErrors.length === 0) {
+    const formattingOptions = detectIndentation(raw);
+    const edits = modify(raw, keyPath, value, { formattingOptions });
+    const result = applyEdits(raw, edits);
+    await fs.writeFile(filePath, result, 'utf-8');
+    return true;
+  }
+
+  return false;
 }

 /**
@@ -133,10 +178,12 @@ async function setupCursor(result: SetupResult): Promise<void> {

  const mcpPath = path.join(cursorDir, 'mcp.json');
  try {
-    const existing = await readJsonFile(mcpPath);
-    const updated = mergeMcpConfig(existing);
-    await writeJsonFile(mcpPath, updated);
-    result.configured.push('Cursor');
+    const ok = await mergeJsoncFile(mcpPath, ['mcpServers', 'gitnexus'], getMcpEntry());
+    if (ok) {
+      result.configured.push('Cursor');
+    } else {
+      result.errors.push('Cursor: mcp.json is corrupt — skipping to preserve existing content');
+    }
  } catch (err: any) {
    result.errors.push(`Cursor: ${err.message}`);
  }
@@ -152,10 +199,14 @@ async function setupClaudeCode(result: SetupResult): Promise<void> {
  // Claude Code stores MCP config in ~/.claude.json
  const mcpPath = path.join(os.homedir(), '.claude.json');
  try {
-    const existing = await readJsonFile(mcpPath);
-    const updated = mergeMcpConfig(existing);
-    await writeJsonFile(mcpPath, updated);
-    result.configured.push('Claude Code');
+    const ok = await mergeJsoncFile(mcpPath, ['mcpServers', 'gitnexus'], getMcpEntry());
+    if (ok) {
+      result.configured.push('Claude Code');
+    } else {
+      result.errors.push(
+        'Claude Code: .claude.json is corrupt — skipping to preserve existing content',
+      );
+    }
  } catch (err: any) {
    result.errors.push(`Claude Code: ${err.message}`);
  }
@@ -179,9 +230,90 @@ async function installClaudeCodeSkills(result: SetupResult): Promise<void> {
  }
 }

+/**
+ * Check whether an event array already contains a gitnexus-hook entry.
+ */
+function hasGitnexusHook(hooksObj: any, eventName: string): boolean {
+  const entries = hooksObj?.[eventName];
+  if (!Array.isArray(entries)) return false;
+  return entries.some(
+    (h: any) =>
+      Array.isArray(h.hooks) &&
+      h.hooks.some(
+        (hh: any) => typeof hh.command === 'string' && hh.command.includes('gitnexus-hook'),
+      ),
+  );
+}
+
+/**
+ * Merge hook entries into a JSONC settings file, preserving comments and formatting.
+ * Uses chained modify()+applyEdits() calls to append to arrays without a full
+ * JSON.stringify roundtrip that would strip comments.
+ */
+async function mergeHooksJsonc(
+  filePath: string,
+  entries: Array<{ eventName: string; value: unknown }>,
+): Promise<boolean> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(filePath, 'utf-8');
+  } catch {
+    raw = '';
+  }
+
+  if (raw.trim().length === 0) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const hooks: any = {};
+    for (const { eventName, value } of entries) {
+      hooks[eventName] = [value];
+    }
+    const formattingOptions = { tabSize: 2, insertSpaces: true };
+    const edits = modify('{}', ['hooks'], hooks, { formattingOptions });
+    await fs.writeFile(filePath, applyEdits('{}', edits), 'utf-8');
+    return true;
+  }
+
+  const parseErrors: ParseError[] = [];
+  const tree = parseTree(raw, parseErrors);
+
+  if (!tree || tree.type !== 'object' || parseErrors.length > 0) {
+    return false;
+  }
+
+  const formattingOptions = detectIndentation(raw);
+  let current = raw;
+
+  for (const { eventName, value } of entries) {
+    // Re-parse after each edit to get a fresh insertion index.
+    const currentTree = parseTree(current, []);
+    const hooksNode = currentTree?.children?.find(
+      (c) => c.type === 'property' && c.children?.[0]?.value === 'hooks',
+    );
+    const eventNode = hooksNode?.children?.[1]?.children?.find(
+      (c: any) => c.type === 'property' && c.children?.[0]?.value === eventName,
+    );
+
+    let insertIndex: number;
+    if (eventNode?.children?.[1] && Array.isArray(eventNode.children[1].children)) {
+      insertIndex = eventNode.children[1].children.length;
+    } else {
+      insertIndex = 0;
+    }
+
+    const edits = modify(current, ['hooks', eventName, insertIndex], value, {
+      formattingOptions,
+    });
+    current = applyEdits(current, edits);
+  }
+
+  await fs.writeFile(filePath, current, 'utf-8');
+  return true;
+}
+
 /**
 * Install GitNexus hooks to ~/.claude/settings.json for Claude Code.
- * Merges hook config without overwriting existing hooks.
+ * Merges hook config without overwriting existing hooks, preserving
+ * comments and formatting in the JSONC file.
 */
 async function installClaudeCodeHooks(result: SetupResult): Promise<void> {
  const claudeDir = path.join(os.homedir(), '.claude');
@@ -202,8 +334,6 @@ async function installClaudeCodeHooks(result: SetupResult): Promise<void> {
    const dest = path.join(destHooksDir, 'gitnexus-hook.cjs');
    try {
      let content = await fs.readFile(src, 'utf-8');
-      // Inject resolved CLI path so the copied hook can find the CLI
-      // even when it's no longer inside the npm package tree
      const resolvedCli = path.join(__dirname, '..', 'cli', 'index.js');
      const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
      const jsonCli = JSON.stringify(normalizedCli);
@@ -219,40 +349,67 @@ async function installClaudeCodeHooks(result: SetupResult): Promise<void> {
    const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
    const hookCmd = `node "${hookPath.replace(/"/g, '\\"')}"`;

-    // Merge hook config into ~/.claude/settings.json
-    const existing = (await readJsonFile(settingsPath)) || {};
-    if (!existing.hooks) existing.hooks = {};
+    // Check which hook events need entries (idempotent: skip if already registered)
+    const parsed = await (async () => {
+      try {
+        const r = await fs.readFile(settingsPath, 'utf-8');
+        return parseJsonc(r);
+      } catch {
+        return null;
+      }
+    })();
+
+    const hookEntries: Array<{ eventName: string; value: unknown }> = [];

    // NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576).
    // Session context is delivered via CLAUDE.md / skills instead.

-    // Helper: add a hook entry if one with 'gitnexus-hook' isn't already registered
-    interface HookEntry {
-      hooks?: Array<{ command?: string }>;
+    if (!hasGitnexusHook(parsed?.hooks, 'PreToolUse')) {
+      hookEntries.push({
+        eventName: 'PreToolUse',
+        value: {
+          matcher: 'Grep|Glob|Bash',
+          hooks: [
+            {
+              type: 'command',
+              command: hookCmd,
+              timeout: 10,
+              statusMessage: 'Enriching with GitNexus graph context...',
+            },
+          ],
+        },
+      });
    }
-    function ensureHookEntry(
-      eventName: string,
-      matcher: string,
-      timeout: number,
-      statusMessage: string,
-    ) {
-      if (!existing.hooks[eventName]) existing.hooks[eventName] = [];
-      const hasHook = existing.hooks[eventName].some((h: HookEntry) =>
-        h.hooks?.some((hh) => hh.command?.includes('gitnexus-hook')),
+    if (!hasGitnexusHook(parsed?.hooks, 'PostToolUse')) {
+      hookEntries.push({
+        eventName: 'PostToolUse',
+        value: {
+          matcher: 'Bash',
+          hooks: [
+            {
+              type: 'command',
+              command: hookCmd,
+              timeout: 10,
+              statusMessage: 'Checking GitNexus index freshness...',
+            },
+          ],
+        },
+      });
+    }
+
+    if (hookEntries.length === 0) {
+      result.configured.push('Claude Code hooks (already configured)');
+      return;
+    }
+
+    const ok = await mergeHooksJsonc(settingsPath, hookEntries);
+    if (ok) {
+      result.configured.push('Claude Code hooks (PreToolUse, PostToolUse)');
+    } else {
+      result.errors.push(
+        'Claude Code hooks: settings.json is corrupt — skipping to preserve existing content',
      );
-      if (!hasHook) {
-        existing.hooks[eventName].push({
-          matcher,
-          hooks: [{ type: 'command', command: hookCmd, timeout, statusMessage }],
-        });
-      }
    }
-
-    ensureHookEntry('PreToolUse', 'Grep|Glob|Bash', 10, 'Enriching with GitNexus graph context...');
-    ensureHookEntry('PostToolUse', 'Bash', 10, 'Checking GitNexus index freshness...');
-
-    await writeJsonFile(settingsPath, existing);
-    result.configured.push('Claude Code hooks (PreToolUse, PostToolUse)');
  } catch (err: any) {
    result.errors.push(`Claude Code hooks: ${err.message}`);
  }
@@ -267,12 +424,14 @@ async function setupOpenCode(result: SetupResult): Promise<void> {

  const configPath = path.join(opencodeDir, 'opencode.json');
  try {
-    const existing = await readJsonFile(configPath);
-    const config = existing || {};
-    if (!config.mcp) config.mcp = {};
-    config.mcp.gitnexus = getMcpEntry();
-    await writeJsonFile(configPath, config);
-    result.configured.push('OpenCode');
+    const ok = await mergeJsoncFile(configPath, ['mcp', 'gitnexus'], getOpenCodeMcpEntry());
+    if (ok) {
+      result.configured.push('OpenCode');
+    } else {
+      result.errors.push(
+        'OpenCode: opencode.json is corrupt — skipping to preserve existing content',
+      );
+    }
  } catch (err: any) {
    result.errors.push(`OpenCode: ${err.message}`);
  }
@@ -434,13 +593,13 @@ async function installCursorSkills(result: SetupResult): Promise<void> {
 }

 /**
- * Install global OpenCode skills to ~/.config/opencode/skill/gitnexus/
+ * Install global OpenCode skills to ~/.config/opencode/skills/gitnexus/
 */
 async function installOpenCodeSkills(result: SetupResult): Promise<void> {
  const opencodeDir = path.join(os.homedir(), '.config', 'opencode');
  if (!(await dirExists(opencodeDir))) return;

-  const skillsDir = path.join(opencodeDir, 'skill');
+  const skillsDir = path.join(opencodeDir, 'skills');
  try {
    const installed = await installSkillsTo(skillsDir);
    if (installed.length > 0) {
@@ -270,17 +270,21 @@ const IGNORED_FILES = new Set([
  '.env.example',
 ]);

-// NOTE: Negation patterns in .gitnexusignore (e.g. `!vendor/`) cannot override
-// entries in DEFAULT_IGNORE_LIST — this is intentional. The hardcoded list protects
-// against indexing directories that are almost never source code (node_modules, .git, etc.).
-// Users who need to include such directories should remove them from the hardcoded list.
+// The hardcoded DEFAULT_IGNORE_LIST is the "safety net" default: directories
+// that are almost never source code (node_modules, .git, dist, __tests__,
+// etc.). Users who legitimately need to index one of these can negate the
+// hardcoded rule via a `!pattern` line in `.gitnexusignore` (#771) — same
+// semantics as `.gitignore` negation. That override is applied in
+// `createIgnoreFilter` below; `shouldIgnorePath` itself stays a pure
+// hardcoded-list check so its callers (wiki generator, tests) get
+// deterministic results independent of per-repo config.
 export const shouldIgnorePath = (filePath: string): boolean => {
  const normalizedPath = filePath.replace(/\\/g, '/');
  const parts = normalizedPath.split('/');
  const fileName = parts[parts.length - 1];
  const fileNameLower = fileName.toLowerCase();

-  // Check if any path segment is in ignore list
+  // Check if any path segment is in the hardcoded ignore list.
  for (const part of parts) {
    if (DEFAULT_IGNORE_LIST.has(part)) {
      return true;
@@ -369,6 +373,42 @@ export const loadIgnoreRules = async (
  return hasRules ? ig : null;
 };

+/**
+ * Walk ancestor segments of `rel` and check whether `.gitnexusignore`
+ * (or `.gitignore`) contains an explicit `!pattern` negation that
+ * applies. Returns true as soon as any segment — or the path itself —
+ * is matched by a negation rule.
+ *
+ * Why this exists (#771): the hardcoded DEFAULT_IGNORE_LIST would
+ * otherwise block indexing of directories like `__tests__/` even when
+ * the user has an explicit `!__tests__/` line in `.gitnexusignore`.
+ * Mirroring `.gitignore` negation semantics: a user's explicit
+ * unignore of a parent directory implicitly unignores everything
+ * underneath, so we walk the ancestor chain rather than only testing
+ * the leaf.
+ *
+ * The `ignore` package's `test(path)` returns `{ignored, unignored}`;
+ * `unignored: true` is the "a negation rule matched this path"
+ * signal. Children of a negated directory return
+ * `{ignored: false, unignored: false}` on a direct test, which is why
+ * we also walk the ancestors here.
+ */
+const hasExplicitUnignore = (ig: Ignore, rel: string): boolean => {
+  // Direct match on the path (as a file).
+  if (ig.test(rel).unignored) return true;
+  // Direct match on the path treated as a directory — `!dir/` matches
+  // here when rel is the directory itself.
+  if (ig.test(rel + '/').unignored) return true;
+  // Walk ancestor segments. `!parent/` should propagate to every
+  // descendant the same way `.gitignore` negation propagates.
+  const parts = rel.split('/');
+  for (let i = parts.length - 1; i > 0; i--) {
+    const ancestor = parts.slice(0, i).join('/') + '/';
+    if (ig.test(ancestor).unignored) return true;
+  }
+  return false;
+};
+
 /**
 * Create a glob-compatible ignore filter combining:
 * - .gitignore / .gitnexusignore patterns (via `ignore` package)
@@ -376,6 +416,15 @@ export const loadIgnoreRules = async (
 *
 * Returns an IgnoreLike object for glob's `ignore` option,
 * enabling directory-level pruning during traversal.
+ *
+ * Precedence (#771): user's `.gitnexusignore` negation patterns take
+ * priority over the hardcoded list, matching `.gitignore` semantics.
+ * An explicit `!pattern` rule unignores descendants even when they
+ * would otherwise be blocked by DEFAULT_IGNORE_LIST — UNLESS a more
+ * specific rule in the same file re-ignores a subset (e.g.
+ * `!__tests__/` paired with `__tests__/generated/` blocks the child
+ * while leaving the parent negated). Last-match-wins is enforced by
+ * consulting `ig.ignores(rel)` after `hasExplicitUnignore`.
 */
 export const createIgnoreFilter = async (repoPath: string, options?: IgnoreOptions) => {
  const ig = await loadIgnoreRules(repoPath, options);
@@ -386,16 +435,33 @@ export const createIgnoreFilter = async (repoPath: string, options?: IgnoreOptio
      // which is what the `ignore` package expects. No explicit normalization needed.
      const rel = p.relative();
      if (!rel) return false;
+      // User's .gitnexusignore negation takes precedence over hardcoded
+      // rules (#771). If any ancestor or the path itself was explicitly
+      // unignored AND no more-specific rule re-ignores this exact path,
+      // allow it through. The `!ig.ignores(rel)` guard matches
+      // .gitignore's last-match-wins semantics: `!__tests__/` followed
+      // by `__tests__/generated/` negates the parent but still blocks
+      // the re-ignored child.
+      if (ig && hasExplicitUnignore(ig, rel) && !ig.ignores(rel)) return false;
      // Check .gitignore / .gitnexusignore patterns
      if (ig && ig.ignores(rel)) return true;
      // Fall back to hardcoded rules
      return shouldIgnorePath(rel);
    },
    childrenIgnored(p: Path): boolean {
-      // Fast path: check directory name against hardcoded list.
      // Note: dot-directories (.git, .vscode, etc.) are primarily excluded by
-      // glob's `dot: false` option in filesystem-walker.ts. This check is
-      // defense-in-depth — do not remove `dot: false` assuming this covers it.
+      // glob's `dot: false` option in filesystem-walker.ts. The hardcoded
+      // list check below is defense-in-depth — do not remove `dot: false`
+      // assuming this covers it.
+      const rel = p.relative();
+      // User's .gitnexusignore negation takes precedence (#771) — if the
+      // user explicitly unignored this directory or any ancestor via a
+      // !pattern rule, allow descent even if the directory name is in
+      // DEFAULT_IGNORE_LIST. The `!ig.ignores(rel + '/')` guard keeps
+      // last-match-wins: `!__tests__/` + `__tests__/generated/` still
+      // blocks descent into `__tests__/generated/`.
+      if (ig && rel && hasExplicitUnignore(ig, rel) && !ig.ignores(rel + '/')) return false;
+      // Hardcoded list: block descent into well-known noise directories.
      if (DEFAULT_IGNORE_LIST.has(p.name)) return true;
      // Check against .gitignore / .gitnexusignore patterns.
      // Since childrenIgnored is only called for directories, always test with
@@ -405,10 +471,7 @@ export const createIgnoreFilter = async (repoPath: string, options?: IgnoreOptio
      // Bare-name patterns (e.g. `local`) still match `local/` per gitignore spec:
      // the `ignore` package normalizes `dir` and `dir/` to match directories.
      // See: https://github.com/kaelzhang/node-ignore#2-filenames-and-dirnames
-      if (ig) {
-        const rel = p.relative();
-        if (rel && ig.ignores(rel + '/')) return true;
-      }
+      if (ig && rel && ig.ignores(rel + '/')) return true;
      return false;
    },
  };
@@ -0,0 +1,54 @@
+/**
+ * Pure derivation of the embedding-mode flags for `runFullAnalysis`.
+ *
+ * Lives in its own module (no native imports) so the branching contract can
+ * be unit-tested without spinning up LadybugDB, tree-sitter, or any of the
+ * other side-effecting dependencies pulled in by `run-analyze.ts`.
+ *
+ * Semantics:
+ *   --drop-embeddings         -> wipe (skip cache load entirely)
+ *   --embeddings              -> load cache, restore, then generate
+ *   --force + existing>0      -> load cache, restore, then generate (regenerate top-up)
+ *   (default) + existing>0    -> preserve only (load + restore, no generation)
+ *   any path with existing=0  -> no cache work, no preservation
+ */
+
+export interface EmbeddingModeInput {
+  force?: boolean;
+  embeddings?: boolean;
+  dropEmbeddings?: boolean;
+}
+
+export interface EmbeddingMode {
+  /** True when phase 4 should run the embedding generation pipeline. */
+  shouldGenerateEmbeddings: boolean;
+  /** True when we should load the cache to re-insert vectors after rebuild without generating new ones. */
+  preserveExistingEmbeddings: boolean;
+  /** True when `--force` upgraded a default analyze into a regeneration because the repo was already embedded. */
+  forceRegenerateEmbeddings: boolean;
+  /** True when we need to load cached embeddings from the existing DB before the rebuild. */
+  shouldLoadCache: boolean;
+}
+
+export function deriveEmbeddingMode(
+  options: EmbeddingModeInput,
+  existingEmbeddingCount: number,
+): EmbeddingMode {
+  const hasExisting = existingEmbeddingCount > 0;
+  const drop = !!options.dropEmbeddings;
+  const explicit = !!options.embeddings;
+  const force = !!options.force;
+
+  const forceRegenerateEmbeddings = force && !explicit && !drop && hasExisting;
+  const preserveExistingEmbeddings =
+    !explicit && !drop && !forceRegenerateEmbeddings && hasExisting;
+  const shouldGenerateEmbeddings = explicit || forceRegenerateEmbeddings;
+  const shouldLoadCache = !drop && (shouldGenerateEmbeddings || preserveExistingEmbeddings);
+
+  return {
+    shouldGenerateEmbeddings,
+    preserveExistingEmbeddings,
+    forceRegenerateEmbeddings,
+    shouldLoadCache,
+  };
+}
@@ -0,0 +1,54 @@
+import { defaultEmbeddingThreads } from '../platform/capabilities.js';
+import { DEFAULT_EMBEDDING_CONFIG, type EmbeddingConfig } from './types.js';
+
+const parsePositiveInt = (name: string, value: string | undefined, fallback: number): number => {
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer, got "${value}"`);
+  }
+  return parsed;
+};
+
+const parseDevice = (value: string | undefined): EmbeddingConfig['device'] | undefined => {
+  if (value === undefined) return undefined;
+  if (
+    value === 'auto' ||
+    value === 'dml' ||
+    value === 'cuda' ||
+    value === 'cpu' ||
+    value === 'wasm'
+  ) {
+    return value;
+  }
+  throw new Error(`embedding device must be one of auto, dml, cuda, cpu, wasm; got "${value}"`);
+};
+
+export const resolveEmbeddingConfig = (
+  overrides: Partial<EmbeddingConfig> = {},
+): EmbeddingConfig => {
+  const env = process.env;
+  return {
+    ...DEFAULT_EMBEDDING_CONFIG,
+    ...overrides,
+    batchSize: parsePositiveInt(
+      'GITNEXUS_EMBEDDING_BATCH_SIZE',
+      env.GITNEXUS_EMBEDDING_BATCH_SIZE,
+      overrides.batchSize ?? DEFAULT_EMBEDDING_CONFIG.batchSize,
+    ),
+    subBatchSize: parsePositiveInt(
+      'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
+      env.GITNEXUS_EMBEDDING_SUB_BATCH_SIZE,
+      overrides.subBatchSize ?? DEFAULT_EMBEDDING_CONFIG.subBatchSize,
+    ),
+    threads: parsePositiveInt(
+      'GITNEXUS_EMBEDDING_THREADS',
+      env.GITNEXUS_EMBEDDING_THREADS,
+      overrides.threads ?? defaultEmbeddingThreads(),
+    ),
+    device:
+      parseDevice(env.GITNEXUS_EMBEDDING_DEVICE) ??
+      overrides.device ??
+      DEFAULT_EMBEDDING_CONFIG.device,
+  };
+};
@@ -21,6 +21,8 @@ import { join, dirname } from 'path';
 import { createRequire } from 'module';
 import { DEFAULT_EMBEDDING_CONFIG, type EmbeddingConfig, type ModelProgress } from './types.js';
 import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.js';
+import { resolveEmbeddingConfig } from './config.js';
+import { applyHfEnvOverrides } from './hf-env.js';

 /**
 * Check whether the onnxruntime-node package that @huggingface/transformers
@@ -143,13 +145,12 @@ export const initEmbedder = async (

  isInitializing = true;

-  const finalConfig = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
-  // On Windows, use DirectML for GPU acceleration (via DirectX12)
-  // CUDA is only available on Linux x64 with onnxruntime-node
+  const finalConfig = resolveEmbeddingConfig(config);
+  // CUDA is probe-gated because ONNX Runtime can crash in native code when
+  // provider libraries are missing. DirectML stays opt-in for the same reason.
  // Probe for CUDA first — ONNX Runtime crashes (uncatchable native error)
  // if we attempt CUDA without the required shared libraries
-  const isWindows = process.platform === 'win32';
-  const gpuDevice = isWindows ? 'dml' : isCudaAvailable() ? 'cuda' : 'cpu';
+  const gpuDevice = isCudaAvailable() ? 'cuda' : 'cpu';
  const requestedDevice =
    forceDevice || (finalConfig.device === 'auto' ? gpuDevice : finalConfig.device);

@@ -157,11 +158,11 @@ export const initEmbedder = async (
    try {
      // Configure transformers.js environment
      env.allowLocalModels = false;
-      // Default cache to user-writable location. transformers.js defaults to
-      // ./node_modules/.cache inside its own install dir, which is unwritable
-      // when gitnexus is installed globally (e.g. /usr/lib/node_modules/).
-      // Respect HF_HOME if set, otherwise fall back to ~/.cache/huggingface.
-      env.cacheDir = process.env.HF_HOME ?? `${process.env.HOME}/.cache/huggingface`;
+      // Bridge user-controlled env vars to transformers.js: HF_HOME →
+      // env.cacheDir, HF_ENDPOINT → env.remoteHost (#1205). Centralised in
+      // applyHfEnvOverrides so the MCP embedder entry point behaves
+      // identically.
+      applyHfEnvOverrides(env);

      const isDev = process.env.NODE_ENV === 'development';
      if (isDev) {
@@ -204,7 +205,12 @@ export const initEmbedder = async (
            device: device,
            dtype: 'fp32',
            progress_callback: progressCallback,
-            session_options: { logSeverityLevel: 3 },
+            session_options: {
+              logSeverityLevel: 3,
+              intraOpNumThreads: finalConfig.threads,
+              interOpNumThreads: 1,
+              executionMode: 'sequential',
+            },
          });
          currentDevice = device;

@@ -27,7 +27,6 @@ import {
  type SemanticSearchResult,
  type ModelProgress,
  type EmbeddingContext,
-  DEFAULT_EMBEDDING_CONFIG,
  EMBEDDABLE_LABELS,
  isShortLabel,
  LABEL_METHOD,
@@ -35,6 +34,8 @@ import {
  STRUCTURAL_LABELS,
  collectBestChunks,
 } from './types.js';
+import { resolveEmbeddingConfig } from './config.js';
+import { rankExactEmbeddingRows, type ExactEmbeddingRow } from './exact-search.js';
 import {
  EMBEDDING_TABLE_NAME,
  EMBEDDING_INDEX_NAME,
@@ -42,8 +43,20 @@ import {
  STALE_HASH_SENTINEL,
 } from '../lbug/schema.js';
 import { loadVectorExtension } from '../lbug/lbug-adapter.js';
+import { getExactScanLimit } from '../platform/capabilities.js';

 const isDev = process.env.NODE_ENV === 'development';
+
+const vectorUnavailableMessage =
+  'VECTOR extension is unavailable for this LadybugDB runtime; semantic search will use exact scan when embeddings exist.';
+
+const ensureVectorExtensionAvailable = async (): Promise<boolean> => {
+  const vectorReady = await loadVectorExtension();
+  if (!vectorReady) {
+    return false;
+  }
+  return true;
+};
 /**
 * Bump this when the embedding text template changes in a way that should
 * invalidate existing vectors, such as metadata/header shape changes,
@@ -192,19 +205,26 @@ export const batchInsertEmbeddings = async (
 */
 const createVectorIndex = async (
  executeQuery: (cypher: string) => Promise<any[]>,
-): Promise<void> => {
-  // Delegate to the adapter which tracks loaded state and handles DB reconnect resets
-  await loadVectorExtension();
-
+): Promise<boolean> => {
+  if (!(await ensureVectorExtensionAvailable())) return false;
  try {
    await executeQuery(CREATE_VECTOR_INDEX_QUERY);
+    return true;
  } catch (error) {
    if (isDev) {
      console.warn('Vector index creation warning:', error);
    }
+    return false;
  }
 };

+export interface EmbeddingPipelineResult {
+  nodesProcessed: number;
+  chunksProcessed: number;
+  vectorIndexReady: boolean;
+  semanticMode: 'vector-index' | 'exact-scan';
+}
+
 /**
 * Run the embedding pipeline
 *
@@ -230,10 +250,14 @@ export const runEmbeddingPipeline = async (
  skipNodeIds?: Set<string>,
  context?: EmbeddingContext,
  existingEmbeddings?: Map<string, string>,
-): Promise<void> => {
-  const finalConfig = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
+): Promise<EmbeddingPipelineResult> => {
+  const finalConfig = resolveEmbeddingConfig(config);
+  let totalChunks = 0;

  try {
+    const vectorAvailable = await ensureVectorExtensionAvailable();
+    if (!vectorAvailable && isDev) console.warn(vectorUnavailableMessage);
+
    // Phase 1: Load embedding model
    onProgress({
      phase: 'loading-model',
@@ -338,7 +362,7 @@ export const runEmbeddingPipeline = async (
      // Ensure the vector index exists even when no new nodes need embedding.
      // A prior crash or first-time incremental run may have left CodeEmbedding
      // rows without ever reaching index creation.
-      await createVectorIndex(executeQuery);
+      const vectorIndexReady = await createVectorIndex(executeQuery);

      onProgress({
        phase: 'ready',
@@ -346,7 +370,12 @@ export const runEmbeddingPipeline = async (
        nodesProcessed: 0,
        totalNodes: 0,
      });
-      return;
+      return {
+        nodesProcessed: 0,
+        chunksProcessed: 0,
+        vectorIndexReady,
+        semanticMode: vectorIndexReady ? 'vector-index' : 'exact-scan',
+      };
    }

    // Phase 3: Chunk + embed nodes
@@ -354,7 +383,6 @@ export const runEmbeddingPipeline = async (
    const chunkSize = finalConfig.chunkSize;
    const overlap = finalConfig.overlap;
    let processedNodes = 0;
-    let totalChunks = 0;

    onProgress({
      phase: 'embedding',
@@ -445,7 +473,7 @@ export const runEmbeddingPipeline = async (
      }

      // Embed chunk texts in sub-batches to control memory
-      const EMBED_SUB_BATCH = 8;
+      const EMBED_SUB_BATCH = finalConfig.subBatchSize;
      for (let si = 0; si < allTexts.length; si += EMBED_SUB_BATCH) {
        const subTexts = allTexts.slice(si, si + EMBED_SUB_BATCH);
        const subUpdates = allUpdates.slice(si, si + EMBED_SUB_BATCH);
@@ -495,7 +523,7 @@ export const runEmbeddingPipeline = async (
      console.log('📇 Creating vector index...');
    }

-    await createVectorIndex(executeQuery);
+    const vectorIndexReady = await createVectorIndex(executeQuery);

    onProgress({
      phase: 'ready',
@@ -509,6 +537,12 @@ export const runEmbeddingPipeline = async (
        `✅ Embedding pipeline complete! (${totalChunks} chunks from ${totalNodes} nodes)`,
      );
    }
+    return {
+      nodesProcessed: totalNodes,
+      chunksProcessed: totalChunks,
+      vectorIndexReady,
+      semanticMode: vectorIndexReady ? 'vector-index' : 'exact-scan',
+    };
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';

@@ -543,27 +577,71 @@ export const semanticSearch = async (
  const queryVec = embeddingToArray(queryEmbedding);
  const queryVecStr = `[${queryVec.join(',')}]`;

-  const bestChunks = await collectBestChunks(k, async (fetchLimit) => {
-    const vectorQuery = `
-      CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
-        CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${fetchLimit})
-      YIELD node AS emb, distance
-      WITH emb, distance
-      WHERE distance < ${maxDistance}
-      RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
-             emb.startLine AS startLine, emb.endLine AS endLine, distance
-      ORDER BY distance
-    `;
+  let bestChunks = new Map<
+    string,
+    { distance: number; chunkIndex: number; startLine: number; endLine: number }
+  >();
+  if (await loadVectorExtension()) {
+    try {
+      bestChunks = await collectBestChunks(k, async (fetchLimit) => {
+        const vectorQuery = `
+          CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
+            CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${fetchLimit})
+          YIELD node AS emb, distance
+          WITH emb, distance
+          WHERE distance < ${maxDistance}
+          RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
+                 emb.startLine AS startLine, emb.endLine AS endLine, distance
+          ORDER BY distance
+        `;

-    const embResults = await executeQuery(vectorQuery);
-    return embResults.map((row) => ({
-      nodeId: row.nodeId ?? row[0],
-      chunkIndex: row.chunkIndex ?? row[1] ?? 0,
-      startLine: row.startLine ?? row[2] ?? 0,
-      endLine: row.endLine ?? row[3] ?? 0,
-      distance: row.distance ?? row[4],
-    }));
-  });
+        const embResults = await executeQuery(vectorQuery);
+        return embResults.map((row) => ({
+          nodeId: row.nodeId ?? row[0],
+          chunkIndex: row.chunkIndex ?? row[1] ?? 0,
+          startLine: row.startLine ?? row[2] ?? 0,
+          endLine: row.endLine ?? row[3] ?? 0,
+          distance: row.distance ?? row[4],
+        }));
+      });
+    } catch {
+      bestChunks = new Map();
+    }
+  }
+
+  if (bestChunks.size === 0) {
+    const countRows = await executeQuery(
+      `MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN count(e) AS cnt`,
+    );
+    const countRow = countRows[0];
+    const embeddingCount = Number(countRow?.cnt ?? countRow?.[0] ?? 0);
+    const exactLimit = getExactScanLimit();
+    if (embeddingCount > 0 && embeddingCount <= exactLimit) {
+      const rows = await executeQuery(`
+        MATCH (e:${EMBEDDING_TABLE_NAME})
+        RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex,
+               e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding
+      `);
+      const exactRows: ExactEmbeddingRow[] = rows.map((row) => ({
+        nodeId: row.nodeId ?? row[0],
+        chunkIndex: row.chunkIndex ?? row[1] ?? 0,
+        startLine: row.startLine ?? row[2] ?? 0,
+        endLine: row.endLine ?? row[3] ?? 0,
+        embedding: row.embedding ?? row[4] ?? [],
+      }));
+      bestChunks = new Map(
+        rankExactEmbeddingRows(exactRows, queryVec, k, maxDistance).map((row) => [
+          row.nodeId,
+          {
+            distance: row.distance,
+            chunkIndex: row.chunkIndex,
+            startLine: row.startLine,
+            endLine: row.endLine,
+          },
+        ]),
+      );
+    }
+  }

  if (bestChunks.size === 0) {
    return [];
@@ -0,0 +1,49 @@
+export interface ExactEmbeddingRow {
+  nodeId: string;
+  chunkIndex: number;
+  startLine: number;
+  endLine: number;
+  embedding: readonly number[];
+}
+
+export interface ExactSearchChunk {
+  nodeId: string;
+  chunkIndex: number;
+  startLine: number;
+  endLine: number;
+  distance: number;
+}
+
+const cosineDistance = (a: readonly number[], b: readonly number[]): number => {
+  let dot = 0;
+  let aNorm = 0;
+  let bNorm = 0;
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    dot += av * bv;
+    aNorm += av * av;
+    bNorm += bv * bv;
+  }
+  if (aNorm === 0 || bNorm === 0) return 1;
+  return 1 - dot / (Math.sqrt(aNorm) * Math.sqrt(bNorm));
+};
+
+export const rankExactEmbeddingRows = (
+  rows: readonly ExactEmbeddingRow[],
+  queryEmbedding: readonly number[],
+  limit: number,
+  maxDistance: number,
+): ExactSearchChunk[] =>
+  rows
+    .map((row) => ({
+      nodeId: row.nodeId,
+      chunkIndex: row.chunkIndex,
+      startLine: row.startLine,
+      endLine: row.endLine,
+      distance: cosineDistance(row.embedding, queryEmbedding),
+    }))
+    .filter((row) => row.distance < maxDistance)
+    .sort((a, b) => a.distance - b.distance)
+    .slice(0, limit);
@@ -0,0 +1,62 @@
+import os from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * @internal Exported only for unit tests and the two embedder entry points
+ * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Not part of the
+ * public package API.
+ *
+ * Minimal subset of `@huggingface/transformers`' `env` object that gitnexus
+ * mutates. Defining a local structural type keeps this helper free of a
+ * transitive dependency on transformers' generated `.d.ts` while still
+ * giving full type-checking on the two fields we actually touch.
+ */
+export interface HfEnvSubset {
+  cacheDir: string;
+  remoteHost: string;
+}
+
+/**
+ * @internal Exported only for unit tests and the two embedder entry points
+ * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Not part of the
+ * public package API.
+ *
+ * Apply user-controlled HuggingFace environment overrides to the
+ * `@huggingface/transformers` `env` object. Centralises the two env-var
+ * bridges so every gitnexus embedder entry point (the analyze pipeline
+ * and the MCP server) behaves identically.
+ *
+ * - **`HF_HOME`** → `env.cacheDir` (default: `~/.cache/huggingface`).
+ *   transformers.js otherwise defaults to `./node_modules/.cache` inside
+ *   its own install dir, which is unwritable when gitnexus is installed
+ *   globally (e.g. `/usr/lib/node_modules/`).
+ *
+ * - **`HF_ENDPOINT`** → `env.remoteHost` (#1205). transformers.js does
+ *   not read `HF_ENDPOINT` on its own — it reads `env.remoteHost` —
+ *   even though `HF_ENDPOINT` is the standard env var the upstream
+ *   `huggingface_hub` Python client and the official HF mirror docs
+ *   tell users to set. Bridging the two unblocks `--embeddings` for
+ *   users behind networks where `huggingface.co` is unreachable
+ *   (corporate proxies, the GFW, air-gapped mirrors). The trailing
+ *   slash is normalised because transformers.js builds URLs by string
+ *   concatenation and a missing slash silently falls through to its
+ *   default `huggingface.co/...` host.
+ *
+ * Mutation rather than return-and-apply because callers already hold a
+ * reference to the live `env` object imported from
+ * `@huggingface/transformers` — passing the same reference in keeps the
+ * call site a single line at each entry point.
+ */
+export function applyHfEnvOverrides(env: HfEnvSubset): void {
+  env.cacheDir = process.env.HF_HOME ?? join(os.homedir(), '.cache', 'huggingface');
+  // `.trim()` guards against the common copy-paste failure mode of
+  // `HF_ENDPOINT="  https://hf-mirror.com  "` (leading/trailing whitespace
+  // from shell scripts or docs) — without it, a whitespace-only value
+  // would be truthy and produce an invalid `env.remoteHost = '   /'` that
+  // silently misroutes downloads. Empty string remains falsy in JS so the
+  // truthy guard already handles the unset/empty cases.
+  const endpoint = process.env.HF_ENDPOINT?.trim();
+  if (endpoint) {
+    env.remoteHost = endpoint.endsWith('/') ? endpoint : endpoint + '/';
+  }
+}
@@ -207,6 +207,10 @@ export interface EmbeddingConfig {
  modelId: string;
  /** Number of nodes to embed in each batch */
  batchSize: number;
+  /** Number of chunks passed to one local/HTTP embedding call */
+  subBatchSize: number;
+  /** Maximum ONNX Runtime CPU threads for local inference */
+  threads: number;
  /** Embedding vector dimensions */
  dimensions: number;
  /** Device to use for inference: 'auto' tries GPU first (DirectML on Windows, CUDA on Linux), falls back to CPU */
@@ -229,6 +233,8 @@ export interface EmbeddingConfig {
 export const DEFAULT_EMBEDDING_CONFIG: EmbeddingConfig = {
  modelId: 'Snowflake/snowflake-arctic-embed-xs',
  batchSize: 16,
+  subBatchSize: 8,
+  threads: 2,
  dimensions: 384,
  device: 'auto',
  maxSnippetLength: 500,
@@ -6,7 +6,7 @@
 import { execFileSync } from 'node:child_process';
 import path from 'path';
 import { readRegistry, type RegistryEntry, type CwdMatch } from '../storage/repo-manager.js';
-import { getGitRoot, getCurrentCommit, getRemoteUrl } from '../storage/git.js';
+import { findGitRootByDotGit, getCurrentCommit, getRemoteUrl } from '../storage/git.js';

 export interface StalenessInfo {
  isStale: boolean;
@@ -101,9 +101,10 @@ export async function checkCwdMatch(cwd: string): Promise<CwdMatch> {
  }
  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);
+  // 2) Sibling-by-remote: locate the cwd's git root using only ancestor
+  //    `.git` checks before shelling out. This keeps MCP startup from
+  //    running git in an unrelated launch cwd such as $HOME (#1138).
+  const cwdGitRoot = findGitRootByDotGit(cwdResolved);
  if (!cwdGitRoot) return { match: 'none' };

  const cwdRemote = getRemoteUrl(cwdGitRoot);
@@ -5,8 +5,42 @@ import lbug from '@ladybugdb/core';
 import type { LbugValue } from '@ladybugdb/core';
 import type { BridgeHandle, BridgeMeta, StoredContract, CrossLink, RepoSnapshot } from './types.js';
 import { BRIDGE_SCHEMA_QUERIES, BRIDGE_SCHEMA_VERSION } from './bridge-schema.js';
+import {
+  closeLbugConnection,
+  openLbugConnection,
+  type LbugConnectionHandle,
+} from '../lbug/lbug-config.js';
 import { dedupeContracts, dedupeCrossLinks } from './normalization.js';

+/**
+ * Sidecar files that LadybugDB creates next to a `bridge.lbug` file.
+ *
+ * - `.wal` — write-ahead log; persists across opens but must be associated
+ *   with the same database instance (LadybugDB 0.16.0 enforces this via a
+ *   database-id check and rejects opens with the diagnostic
+ *   `"Database ID for temporary file 'X.wal' does not match the current
+ *   database. This file may have been left behind from a previous database
+ *   with the same name"`).
+ * - `.shadow` — non-blocking concurrent checkpoint sidecar (added in
+ *   LadybugDB 0.15.4); same pairing constraint as `.wal`.
+ *
+ * `bridge-db` writes to a `bridge.lbug.tmp` file and then atomically renames
+ * it into place. The rename only moves the main file; sidecars must be
+ * cleaned up explicitly or the next writer trips the database-id check.
+ */
+const LBUG_SIDECAR_SUFFIXES = ['.wal', '.shadow'] as const;
+
+async function removeLbugFile(basePath: string): Promise<void> {
+  const candidates = [basePath, ...LBUG_SIDECAR_SUFFIXES.map((s) => `${basePath}${s}`)];
+  for (const f of candidates) {
+    try {
+      await fsp.rm(f, { recursive: true, force: true });
+    } catch {
+      /* best-effort: caller will surface real errors via the open path */
+    }
+  }
+}
+
 export function contractNodeId(
  repo: string,
  contractId: string,
@@ -127,8 +161,7 @@ export function findContractNode(
 export async function openBridgeDb(dbPath: string): Promise<BridgeHandle> {
  const parentDir = path.dirname(dbPath);
  await fsp.mkdir(parentDir, { recursive: true });
-  const db = new lbug.Database(dbPath, 0, false, false); // writable
-  const conn = new lbug.Connection(db);
+  const { db, conn } = await openLbugConnection(lbug, dbPath);
  return { _db: db, _conn: conn, groupDir: parentDir } as BridgeHandle;
 }

@@ -195,6 +228,17 @@ function unwrapQueryResult(queryResult: lbug.QueryResult | lbug.QueryResult[]):
 }

 export async function closeBridgeDb(handle: BridgeHandle): Promise<void> {
+  // CHECKPOINT before close so the WAL/.shadow contents are flushed into
+  // the main database file. Without this, LadybugDB 0.16.0's non-blocking
+  // checkpoint thread can outlive the close call and leave sidecar pages
+  // pending on disk, which makes a subsequent read-side open either race
+  // with the WAL replay or trip the database-id check on the sidecars.
+  // CHECKPOINT is a no-op when there's nothing pending, so it's cheap.
+  try {
+    await (handle._conn as lbug.Connection).query('CHECKPOINT');
+  } catch {
+    /* ignore — older LadybugDB or schemaless DB may not accept it */
+  }
  try {
    await (handle._conn as lbug.Connection).close();
  } catch {
@@ -322,12 +366,11 @@ export async function writeBridge(
    }
  };

-  // Clean up any leftover tmp
-  try {
-    await fsp.rm(tmpPath, { recursive: true, force: true });
-  } catch {
-    /* ignore */
-  }
+  // Clean up any leftover tmp main file AND its `.wal` / `.shadow` sidecars.
+  // LadybugDB 0.16.0 rejects opening a database whose sidecars belong to a
+  // different database instance (database-id check), so any stale sidecar
+  // from a crashed previous run will fail the next writeBridge.
+  await removeLbugFile(tmpPath);

  // 1. Create temp DB, insert all data.
  //
@@ -497,18 +540,43 @@ export async function writeBridge(
  }

  // 3. Atomic swap: old→.bak, tmp→final, rm .bak
+  //
+  // The current database file (with its `.wal` / `.shadow` sidecars) is
+  // moved aside, then the freshly built tmp database takes its place.
+  // We move the sidecars together with the main file so the open below
+  // and any external readers see a consistent set; orphan sidecars from
+  // the tmp namespace are then removed because LadybugDB looks for them
+  // under the renamed-to base name and would reject mismatching IDs.
  try {
    await fsp.access(finalPath);
    await retryRename(finalPath, bakPath);
+    for (const suffix of LBUG_SIDECAR_SUFFIXES) {
+      try {
+        await fsp.access(`${finalPath}${suffix}`);
+        await retryRename(`${finalPath}${suffix}`, `${bakPath}${suffix}`);
+      } catch {
+        /* sidecar absent — nothing to move */
+      }
+    }
  } catch {
    /* no existing db */
  }
  await retryRename(tmpPath, finalPath);
-  try {
-    await fsp.rm(bakPath, { recursive: true, force: true });
-  } catch {
-    /* ignore */
+  for (const suffix of LBUG_SIDECAR_SUFFIXES) {
+    // Rename — not delete — so the WAL (which may carry uncommitted-at-
+    // close-time pages on a graceful close, depending on
+    // `autoCheckpoint` / `checkpointThreshold`) and the `.shadow`
+    // checkpoint snapshot stay paired with the database file under its
+    // final name. LadybugDB 0.16.0's database-id check rejects an open
+    // when the sidecars belong to a different base name.
+    try {
+      await fsp.access(`${tmpPath}${suffix}`);
+      await retryRename(`${tmpPath}${suffix}`, `${finalPath}${suffix}`);
+    } catch {
+      /* sidecar absent — nothing to move */
+    }
  }
+  await removeLbugFile(bakPath);

  // 4. Write meta.json
  await writeBridgeMeta(groupDir, {
@@ -524,10 +592,38 @@ export async function writeBridge(
 /*  openBridgeDbReadOnly                                               */
 /* ------------------------------------------------------------------ */

-export async function openBridgeDbReadOnly(groupDir: string): Promise<BridgeHandle | null> {
+/**
+ * Substrings observed in the message of an `Error` raised by the LadybugDB
+ * native open path when Windows still holds an exclusive lock on the file
+ * after a writer's `Database.close()` returned. LadybugDB 0.16.0's
+ * non-blocking checkpoint thread can briefly outlive the close call, so a
+ * read-side opener that races in immediately afterwards sees Win32 error
+ * 33 ("The process cannot access the file because another process has
+ * locked a portion of the file"). Retrying with a small back-off lets the
+ * background thread settle and the OS release the handle.
+ */
+const LBUG_OPEN_RETRY_PATTERNS = [
+  'process cannot access the file',
+  'another process has locked',
+  'could not set lock',
+  'lock held by another process',
+];
+
+const LBUG_OPEN_RETRY_ATTEMPTS = 10;
+const LBUG_OPEN_RETRY_BASE_MS = 100;
+/** Cap individual back-off delays so the total wait is bounded (~3s). */
+const LBUG_OPEN_RETRY_MAX_MS = 500;
+
+function isTransientLockError(err: unknown): boolean {
+  const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+  return LBUG_OPEN_RETRY_PATTERNS.some((p) => msg.includes(p));
+}
+
+async function ensureBridgeDbFileAvailable(groupDir: string): Promise<boolean> {
  const dbPath = path.join(groupDir, 'bridge.lbug');
  try {
    await fsp.access(dbPath);
+    return true;
  } catch {
    // Check for .bak recovery. Use `retryRename` (not `fsp.rename`) for the
    // exact same reason the rest of this file does: the scenario that
@@ -538,42 +634,62 @@ export async function openBridgeDbReadOnly(groupDir: string): Promise<BridgeHand
    try {
      await fsp.access(bakPath);
      await retryRename(bakPath, dbPath);
+      for (const suffix of LBUG_SIDECAR_SUFFIXES) {
+        try {
+          await fsp.access(`${bakPath}${suffix}`);
+          await retryRename(`${bakPath}${suffix}`, `${dbPath}${suffix}`);
+        } catch {
+          /* sidecar absent */
+        }
+      }
+      return true;
    } catch {
-      return null;
+      return false;
    }
  }
+}
+
+export async function openBridgeDbReadOnly(groupDir: string): Promise<BridgeHandle | null> {
+  const dbPath = path.join(groupDir, 'bridge.lbug');
+  if (!(await ensureBridgeDbFileAvailable(groupDir))) return null;
+
  // Version gate: check meta.json version compatibility
  const meta = await readBridgeMeta(groupDir);
  if (meta.version > 0 && meta.version !== BRIDGE_SCHEMA_VERSION) {
    return null; // incompatible schema version — fallback to JSON or re-sync
  }

-  // Open the native handle. If Connection construction throws AFTER
-  // Database was successfully allocated, we'd leak the native Database
-  // object. Wrap each step separately and tear down the partial handle.
-  let db: lbug.Database | undefined;
-  let conn: lbug.Connection | undefined;
-  try {
-    db = new lbug.Database(dbPath, 0, false, true); // readOnly
-    conn = new lbug.Connection(db);
-    return { _db: db, _conn: conn, groupDir } as BridgeHandle;
-  } catch {
-    if (conn) {
-      try {
-        await conn.close();
-      } catch {
-        /* ignore */
-      }
+  // Open the native handle with a bounded retry on transient OS-level file
+  // locks (see LBUG_OPEN_RETRY_PATTERNS). If Connection construction throws
+  // AFTER Database was successfully allocated, we'd leak the native Database
+  // object — wrap each step separately and tear down the partial handle.
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= LBUG_OPEN_RETRY_ATTEMPTS; attempt++) {
+    let handle: LbugConnectionHandle | undefined;
+    try {
+      handle = await openLbugConnection(lbug, dbPath, { readOnly: true });
+      // Force the lazy native init now so a transient lock surfaces here
+      // (where we can retry) instead of on the first user query.
+      await handle.db.init();
+      await handle.conn.init();
+      return { _db: handle.db, _conn: handle.conn, groupDir } as BridgeHandle;
+    } catch (err) {
+      lastErr = err;
+      if (handle) await closeLbugConnection(handle);
+      if (!isTransientLockError(err) || attempt === LBUG_OPEN_RETRY_ATTEMPTS) break;
+      const delay = Math.min(LBUG_OPEN_RETRY_BASE_MS * attempt, LBUG_OPEN_RETRY_MAX_MS);
+      await new Promise((r) => setTimeout(r, delay));
    }
-    if (db) {
-      try {
-        await db.close();
-      } catch {
-        /* ignore */
-      }
-    }
-    return null;
  }
+  if (process.env.GITNEXUS_DEBUG_BRIDGE) {
+    console.warn(
+      `[bridge-db] openBridgeDbReadOnly(${groupDir}) gave up after ` +
+        `${LBUG_OPEN_RETRY_ATTEMPTS} attempts: ${
+          lastErr instanceof Error ? lastErr.message : String(lastErr)
+        }`,
+    );
+  }
+  return null;
 }

 /* ------------------------------------------------------------------ */
@@ -581,8 +697,7 @@ export async function openBridgeDbReadOnly(groupDir: string): Promise<BridgeHand
 /* ------------------------------------------------------------------ */

 export async function bridgeExists(groupDir: string): Promise<boolean> {
-  const handle = await openBridgeDbReadOnly(groupDir);
-  if (!handle) return false;
-  await closeBridgeDb(handle);
-  return true;
+  if (!(await ensureBridgeDbFileAvailable(groupDir))) return false;
+  const meta = await readBridgeMeta(groupDir);
+  return meta.version === 0 || meta.version === BRIDGE_SCHEMA_VERSION;
 }
@@ -4,21 +4,25 @@ import type { GroupConfig, GroupManifestLink, ContractType, ContractRole } from
 const _require = createRequire(import.meta.url);
 const yaml = _require('js-yaml') as typeof import('js-yaml');

-const VALID_CONTRACT_TYPES: ContractType[] = ['http', 'grpc', 'topic', 'lib', 'custom'];
+const VALID_CONTRACT_TYPES: ContractType[] = ['http', 'grpc', 'thrift', 'topic', 'lib', 'custom'];
 const VALID_ROLES: ContractRole[] = ['provider', 'consumer'];

 const DEFAULT_DETECT = {
  http: true,
  grpc: true,
+  thrift: true,
  topics: true,
  shared_libs: true,
  embedding_fallback: true,
+  workspace_deps: false,
 };

 const DEFAULT_MATCHING = {
  bm25_threshold: 0.7,
  embedding_threshold: 0.65,
  max_candidates_per_step: 3,
+  exclude_links_paths: [] as string[],
+  exclude_links_param_only_paths: false,
 };

 export function parseGroupConfig(yamlContent: string): GroupConfig {
@@ -0,0 +1,253 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { CypherExecutor } from '../contract-extractor.js';
+import type { GroupManifestLink, ContractRole } from '../types.js';
+import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
+
+interface ElixirAppMeta {
+  appName: string;
+  modulePrefix: string;
+  groupPath: string;
+  repoPath: string;
+  deps: string[];
+}
+
+interface ImportedModule {
+  appName: string;
+  moduleName: string;
+  filePath: string;
+}
+
+async function parseMixExs(
+  repoPath: string,
+): Promise<{ appName: string; modulePrefix: string; deps: string[] } | null> {
+  const mixPath = path.join(repoPath, 'mix.exs');
+  let content: string;
+  try {
+    content = await fs.readFile(mixPath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  // app: :my_app
+  const appMatch = content.match(/app:\s*:(\w+)/);
+  if (!appMatch) return null;
+  const appName = appMatch[1];
+
+  // Derive module prefix: my_app -> MyApp
+  const modulePrefix = appName
+    .split('_')
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join('');
+
+  const deps: string[] = [];
+
+  // {:dep_name, "~> 1.0"} or {:dep_name, in_umbrella: true}
+  // {:dep_name, git: "..."} or {:dep_name, path: "..."}
+  const depMatches = content.matchAll(
+    /\{:(\w+)\s*,\s*(?:"[^"]*"|~[^}]*|[^}]*(?:in_umbrella|path|git)\s*:[^}]*)\}/g,
+  );
+  for (const m of depMatches) {
+    deps.push(m[1]);
+  }
+
+  return { appName, modulePrefix, deps: [...new Set(deps)] };
+}
+
+async function scanElixirImports(
+  repoPath: string,
+  knownApps: Map<string, string>,
+): Promise<ImportedModule[]> {
+  const results: ImportedModule[] = [];
+  const sourceFiles = await findElixirFiles(repoPath);
+
+  for (const relFile of sourceFiles) {
+    const absPath = path.join(repoPath, relFile);
+    let content: string;
+    try {
+      content = await fs.readFile(absPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    // alias MyApp.SomeModule
+    // alias MyApp.SomeModule, as: Short
+    // alias MyApp.{ModA, ModB}
+    const aliasRegex = /^\s*alias\s+([A-Z]\w+(?:\.[A-Z]\w+)*(?:\.\{[^}]+\})?)/gm;
+    let match;
+    while ((match = aliasRegex.exec(content)) !== null) {
+      const aliasExpr = match[1];
+      const modules = expandAlias(aliasExpr);
+      for (const mod of modules) {
+        const appName = matchModuleToApp(mod, knownApps);
+        if (appName) {
+          results.push({ appName, moduleName: mod, filePath: relFile });
+        }
+      }
+    }
+
+    // Direct module reference: MyApp.Module.func() or MyApp.Module
+    // Strip comment lines and string literals to avoid false positives
+    const codeOnly = content
+      .split('\n')
+      .filter((line) => !line.trimStart().startsWith('#'))
+      .join('\n');
+    for (const [prefix, appName] of knownApps) {
+      const refRegex = new RegExp(
+        `\\b(${escapeRegex(prefix)}\\.[A-Z][A-Za-z0-9]*(?:\\.[A-Z][A-Za-z0-9]*)*)`,
+        'g',
+      );
+      while ((match = refRegex.exec(codeOnly)) !== null) {
+        const mod = match[1];
+        if (!results.some((r) => r.moduleName === mod && r.filePath === relFile)) {
+          results.push({ appName, moduleName: mod, filePath: relFile });
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+function expandAlias(expr: string): string[] {
+  const braceMatch = expr.match(/^([A-Z][\w.]*)\.\{([^}]+)\}$/);
+  if (braceMatch) {
+    const prefix = braceMatch[1];
+    return braceMatch[2]
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .map((s) => `${prefix}.${s}`);
+  }
+  return [expr];
+}
+
+function matchModuleToApp(moduleName: string, knownApps: Map<string, string>): string | null {
+  for (const [prefix, appName] of knownApps) {
+    if (moduleName === prefix || moduleName.startsWith(prefix + '.')) {
+      return appName;
+    }
+  }
+  return null;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function extractTopModule(moduleName: string, prefix: string): string {
+  const rest = moduleName.slice(prefix.length);
+  if (!rest || rest === '.') return moduleName;
+  const afterDot = rest.startsWith('.') ? rest.slice(1) : rest;
+  const parts = afterDot.split('.');
+  return `${prefix}.${parts[0]}`;
+}
+
+async function findElixirFiles(repoPath: string): Promise<string[]> {
+  const results: string[] = [];
+  const ig = await loadIgnoreRules(repoPath);
+
+  async function walk(dir: string, rel: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (shouldIgnorePath(childRel)) continue;
+        if (ig && ig.ignores(childRel + '/')) continue;
+        await walk(path.join(dir, entry.name), childRel);
+      } else if (entry.name.endsWith('.ex') || entry.name.endsWith('.exs')) {
+        if (entry.name === 'mix.exs' || entry.name === 'mix.lock') continue;
+        if (shouldIgnorePath(childRel)) continue;
+        if (ig && ig.ignores(childRel)) continue;
+        results.push(childRel);
+      }
+    }
+  }
+
+  await walk(repoPath, '');
+  return results;
+}
+
+export interface ElixirWorkspaceResult {
+  links: GroupManifestLink[];
+  discoveredApps: Map<string, ElixirAppMeta>;
+}
+
+export async function extractElixirWorkspaceLinks(
+  repos: Record<string, string>,
+  repoPaths: Map<string, string>,
+  _dbExecutors?: Map<string, CypherExecutor>,
+): Promise<ElixirWorkspaceResult> {
+  const appsByName = new Map<string, ElixirAppMeta>();
+  const appsByGroupPath = new Map<string, ElixirAppMeta>();
+
+  for (const [groupPath] of Object.entries(repos)) {
+    const repoPath = repoPaths.get(groupPath);
+    if (!repoPath) continue;
+
+    const manifest = await parseMixExs(repoPath);
+    if (!manifest) continue;
+
+    const meta: ElixirAppMeta = {
+      appName: manifest.appName,
+      modulePrefix: manifest.modulePrefix,
+      groupPath,
+      repoPath,
+      deps: manifest.deps,
+    };
+    const existing = appsByName.get(manifest.appName);
+    if (existing) {
+      console.warn(
+        `[elixir-workspace-extractor] duplicate app "${manifest.appName}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
+      );
+      continue;
+    }
+    appsByName.set(manifest.appName, meta);
+    appsByGroupPath.set(groupPath, meta);
+  }
+
+  const links: GroupManifestLink[] = [];
+  const seen = new Set<string>();
+
+  for (const [, app] of appsByGroupPath) {
+    const groupDeps = app.deps.filter((d) => appsByName.has(d));
+    if (groupDeps.length === 0) continue;
+
+    const knownApps = new Map<string, string>();
+    for (const dep of groupDeps) {
+      const depMeta = appsByName.get(dep);
+      if (depMeta) knownApps.set(depMeta.modulePrefix, dep);
+    }
+
+    const imports = await scanElixirImports(app.repoPath, knownApps);
+
+    for (const imp of imports) {
+      const providerApp = appsByName.get(imp.appName);
+      if (!providerApp) continue;
+
+      const topModule = extractTopModule(imp.moduleName, providerApp.modulePrefix);
+      const key = `${app.groupPath}→${providerApp.groupPath}::${topModule}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      // V1: Elixir contracts use the full module name (e.g. "Core.Schema") without
+      // an "appName::" prefix. resolveSymbol will query the graph with this full
+      // string — resolution depends on Elixir indexer storing fully-qualified names.
+      const link: GroupManifestLink = {
+        from: providerApp.groupPath,
+        to: app.groupPath,
+        type: 'custom',
+        contract: topModule,
+        role: 'provider' as ContractRole,
+      };
+      links.push(link);
+    }
+  }
+
+  return { links, discoveredApps: appsByGroupPath };
+}
@@ -0,0 +1,258 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { CypherExecutor } from '../contract-extractor.js';
+import type { GroupManifestLink, ContractRole } from '../types.js';
+import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
+
+interface GoModuleMeta {
+  modulePath: string;
+  groupPath: string;
+  repoPath: string;
+  requires: string[];
+}
+
+interface ImportedSymbol {
+  modulePath: string;
+  symbolName: string;
+  filePath: string;
+}
+
+async function parseGoMod(
+  repoPath: string,
+): Promise<{ modulePath: string; requires: string[] } | null> {
+  const goModPath = path.join(repoPath, 'go.mod');
+  let content: string;
+  try {
+    content = await fs.readFile(goModPath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  const moduleMatch = content.match(/^module\s+(\S+)/m);
+  if (!moduleMatch) return null;
+  const modulePath = moduleMatch[1];
+
+  const requires: string[] = [];
+
+  // Single-line: require github.com/org/repo v1.2.3
+  const singleReqs = content.matchAll(/^require\s+(\S+)\s+/gm);
+  for (const m of singleReqs) requires.push(m[1]);
+
+  // Block: require ( ... )
+  const blockReqs = content.matchAll(/^require\s*\(\s*\n([\s\S]*?)\)/gm);
+  for (const block of blockReqs) {
+    const lines = block[1].split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('//')) continue;
+      const parts = trimmed.split(/\s+/);
+      if (parts[0]) requires.push(parts[0]);
+    }
+  }
+
+  // replace directives (local path deps)
+  const replaceLines = content.matchAll(/^replace\s+(\S+)\s+=>\s+\.\//gm);
+  for (const m of replaceLines) {
+    if (!requires.includes(m[1])) requires.push(m[1]);
+  }
+
+  const replaceBlocks = content.matchAll(/^replace\s*\(\s*\n([\s\S]*?)\)/gm);
+  for (const block of replaceBlocks) {
+    const lines = block[1].split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('//')) continue;
+      const match = trimmed.match(/^(\S+)\s+=>\s+\.\//);
+      if (match && !requires.includes(match[1])) requires.push(match[1]);
+    }
+  }
+
+  return { modulePath, requires: [...new Set(requires)] };
+}
+
+async function scanGoImports(
+  repoPath: string,
+  knownModules: Map<string, string>,
+): Promise<ImportedSymbol[]> {
+  const results: ImportedSymbol[] = [];
+  const sourceFiles = await findGoFiles(repoPath);
+
+  for (const relFile of sourceFiles) {
+    const absPath = path.join(repoPath, relFile);
+    let content: string;
+    try {
+      content = await fs.readFile(absPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const importPaths = extractImportPaths(content);
+    for (const importPath of importPaths) {
+      const matchedModule = findMatchingModule(importPath, knownModules);
+      if (!matchedModule) continue;
+
+      const symbols = extractUsedTypes(content, importPath);
+      for (const sym of symbols) {
+        results.push({ modulePath: matchedModule, symbolName: sym, filePath: relFile });
+      }
+    }
+  }
+
+  return results;
+}
+
+function extractImportPaths(content: string): string[] {
+  const paths: string[] = [];
+
+  // Single: import "path"
+  const singleImports = content.matchAll(/^import\s+"([^"]+)"/gm);
+  for (const m of singleImports) paths.push(m[1]);
+
+  // Single aliased: import alias "path"
+  const aliasedImports = content.matchAll(/^import\s+\w+\s+"([^"]+)"/gm);
+  for (const m of aliasedImports) paths.push(m[1]);
+
+  // Block: import ( ... )
+  const blockImports = content.matchAll(/^import\s*\(\s*\n([\s\S]*?)\)/gm);
+  for (const block of blockImports) {
+    const lines = block[1].split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('//')) continue;
+      const pathMatch = trimmed.match(/"([^"]+)"/);
+      if (pathMatch) paths.push(pathMatch[1]);
+    }
+  }
+
+  return [...new Set(paths)];
+}
+
+function findMatchingModule(importPath: string, knownModules: Map<string, string>): string | null {
+  for (const [modPath] of knownModules) {
+    if (importPath === modPath || importPath.startsWith(modPath + '/')) {
+      return modPath;
+    }
+  }
+  return null;
+}
+
+function extractUsedTypes(content: string, importPath: string): string[] {
+  const pkgName = importPath.split('/').pop() || '';
+  if (!pkgName) return [];
+
+  // Match pkg.TypeName where TypeName is PascalCase (exported)
+  const typeRegex = new RegExp(`\\b${escapeRegex(pkgName)}\\.([A-Z][A-Za-z0-9]*)`, 'g');
+  const types = new Set<string>();
+  let match;
+  while ((match = typeRegex.exec(content)) !== null) {
+    types.add(match[1]);
+  }
+  return [...types];
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+async function findGoFiles(repoPath: string): Promise<string[]> {
+  const results: string[] = [];
+  const ig = await loadIgnoreRules(repoPath);
+
+  async function walk(dir: string, rel: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (shouldIgnorePath(childRel)) continue;
+        if (ig && ig.ignores(childRel + '/')) continue;
+        await walk(path.join(dir, entry.name), childRel);
+      } else if (entry.name.endsWith('.go') && !entry.name.endsWith('_test.go')) {
+        if (shouldIgnorePath(childRel)) continue;
+        if (ig && ig.ignores(childRel)) continue;
+        results.push(childRel);
+      }
+    }
+  }
+
+  await walk(repoPath, '');
+  return results;
+}
+
+export interface GoWorkspaceResult {
+  links: GroupManifestLink[];
+  discoveredModules: Map<string, GoModuleMeta>;
+}
+
+export async function extractGoWorkspaceLinks(
+  repos: Record<string, string>,
+  repoPaths: Map<string, string>,
+  _dbExecutors?: Map<string, CypherExecutor>,
+): Promise<GoWorkspaceResult> {
+  const modulesByPath = new Map<string, GoModuleMeta>();
+  const modulesByGroupPath = new Map<string, GoModuleMeta>();
+
+  for (const [groupPath] of Object.entries(repos)) {
+    const repoPath = repoPaths.get(groupPath);
+    if (!repoPath) continue;
+
+    const manifest = await parseGoMod(repoPath);
+    if (!manifest) continue;
+
+    const meta: GoModuleMeta = {
+      modulePath: manifest.modulePath,
+      groupPath,
+      repoPath,
+      requires: manifest.requires,
+    };
+    const existing = modulesByPath.get(manifest.modulePath);
+    if (existing) {
+      console.warn(
+        `[go-workspace-extractor] duplicate module "${manifest.modulePath}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
+      );
+      continue;
+    }
+    modulesByPath.set(manifest.modulePath, meta);
+    modulesByGroupPath.set(groupPath, meta);
+  }
+
+  const links: GroupManifestLink[] = [];
+  const seen = new Set<string>();
+
+  for (const [, mod] of modulesByGroupPath) {
+    const groupModDeps = mod.requires.filter((r) => modulesByPath.has(r));
+    if (groupModDeps.length === 0) continue;
+
+    const knownModules = new Map<string, string>();
+    for (const dep of groupModDeps) {
+      knownModules.set(dep, dep);
+    }
+
+    const imports = await scanGoImports(mod.repoPath, knownModules);
+
+    for (const imp of imports) {
+      const providerMod = modulesByPath.get(imp.modulePath);
+      if (!providerMod) continue;
+
+      const qualifiedContract = `${imp.modulePath}::${imp.symbolName}`;
+      const key = `${mod.groupPath}→${providerMod.groupPath}::${qualifiedContract}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const link: GroupManifestLink = {
+        from: providerMod.groupPath,
+        to: mod.groupPath,
+        type: 'custom',
+        contract: qualifiedContract,
+        role: 'provider' as ContractRole,
+      };
+      links.push(link);
+    }
+  }
+
+  return { links, discoveredModules: modulesByGroupPath };
+}
@@ -1,6 +1,7 @@
 import * as path from 'node:path';
 import { glob } from 'glob';
 import Parser from 'tree-sitter';
+import { createIgnoreFilter } from '../../../config/ignore-service.js';
 import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
 import type { ExtractedContract, RepoHandle } from '../types.js';
 import { readSafe } from './fs-utils.js';
@@ -227,11 +228,16 @@ async function buildProtoContext(repoPath: string): Promise<{
  servicesByName: Map<string, ProtoServiceInfo[]>;
 }> {
  const servicesByName = new Map<string, ProtoServiceInfo[]>();
+  // `.gitnexusignore` / `.gitignore` honoured via the shared IgnoreService —
+  // see `filesystem-walker.ts` for the canonical pattern. Replaces a
+  // hardcoded `[node_modules, .git, vendor]` array; those names plus the
+  // rest of `DEFAULT_IGNORE_LIST` are still excluded by default (#1185).
+  const protoIgnoreFilter = await createIgnoreFilter(repoPath);
  const protoFiles = await glob('**/*.proto', {
    cwd: repoPath,
    absolute: false,
    nodir: true,
-    ignore: ['**/node_modules/**', '**/.git/**', '**/vendor/**'],
+    ignore: protoIgnoreFilter,
  });
  const contents = new Map<string, string>();

@@ -401,9 +407,14 @@ export class GrpcExtractor implements ContractExtractor {
    }

    // ─── Source files (+ .proto when plugin available) ────────────
+    // Honour `.gitnexusignore` / `.gitignore` via the shared IgnoreService —
+    // mirrors `filesystem-walker.ts`. Replaces a hardcoded
+    // `[node_modules, .git, vendor, dist, build]` array; those names are all
+    // in `DEFAULT_IGNORE_LIST`, so default behaviour is preserved (#1185).
+    const sourceIgnoreFilter = await createIgnoreFilter(repoPath);
    const sourceFiles = await glob(GRPC_SCAN_GLOB, {
      cwd: repoPath,
-      ignore: ['**/node_modules/**', '**/.git/**', '**/vendor/**', '**/dist/**', '**/build/**'],
+      ignore: sourceIgnoreFilter,
      nodir: true,
    });

@@ -1,6 +1,7 @@
 import * as path from 'node:path';
 import { glob } from 'glob';
 import Parser from 'tree-sitter';
+import { createIgnoreFilter } from '../../../config/ignore-service.js';
 import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
 import type { ExtractedContract, RepoHandle } from '../types.js';
 import { readSafe } from './fs-utils.js';
@@ -208,9 +209,16 @@ export class HttpRouteExtractor implements ContractExtractor {
  }

  private async scanFiles(repoPath: string): Promise<string[]> {
+    // Honour `.gitnexusignore` and `.gitignore` via the shared IgnoreService
+    // so contract extraction respects the same exclusion rules as the rest of
+    // the ingestion pipeline. Mirrors `filesystem-walker.ts` which uses the
+    // same shape. Replaces a hardcoded `[node_modules, .git, dist, build,
+    // vendor]` array — those names are still in `DEFAULT_IGNORE_LIST`, so
+    // default behaviour is preserved (#1185).
+    const ignoreFilter = await createIgnoreFilter(repoPath);
    return glob(HTTP_SCAN_GLOB, {
      cwd: repoPath,
-      ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**', '**/vendor/**'],
+      ignore: ignoreFilter,
      nodir: true,
    });
  }
@@ -0,0 +1,261 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { CypherExecutor } from '../contract-extractor.js';
+import type { GroupManifestLink, ContractRole } from '../types.js';
+import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
+
+interface JavaProjectMeta {
+  groupId: string;
+  artifactId: string;
+  basePackage: string;
+  groupPath: string;
+  repoPath: string;
+  deps: string[];
+}
+
+interface ImportedSymbol {
+  artifactKey: string;
+  symbolName: string;
+  filePath: string;
+}
+
+async function parseJavaManifest(
+  repoPath: string,
+): Promise<{ groupId: string; artifactId: string; deps: string[] } | null> {
+  const pomPath = path.join(repoPath, 'pom.xml');
+  try {
+    const content = await fs.readFile(pomPath, 'utf-8');
+    return parsePom(content);
+  } catch {
+    // fall through to Gradle
+  }
+
+  for (const name of ['build.gradle.kts', 'build.gradle']) {
+    const gradlePath = path.join(repoPath, name);
+    try {
+      const content = await fs.readFile(gradlePath, 'utf-8');
+      return parseGradle(content, repoPath);
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+function parsePom(content: string): { groupId: string; artifactId: string; deps: string[] } | null {
+  const projectGroupMatch = content.match(/<project[^>]*>[\s\S]*?<groupId>([^<]+)<\/groupId>/);
+  const projectArtifactMatch = content.match(
+    /<project[^>]*>[\s\S]*?<artifactId>([^<]+)<\/artifactId>/,
+  );
+  if (!projectGroupMatch || !projectArtifactMatch) return null;
+
+  const groupId = projectGroupMatch[1].trim();
+  const artifactId = projectArtifactMatch[1].trim();
+
+  const deps: string[] = [];
+  const depBlocks = content.matchAll(/<dependency>\s*([\s\S]*?)<\/dependency>/g);
+  for (const block of depBlocks) {
+    const gMatch = block[1].match(/<groupId>([^<]+)<\/groupId>/);
+    const aMatch = block[1].match(/<artifactId>([^<]+)<\/artifactId>/);
+    if (gMatch && aMatch) {
+      deps.push(`${gMatch[1].trim()}:${aMatch[1].trim()}`);
+    }
+  }
+
+  return { groupId, artifactId, deps: [...new Set(deps)] };
+}
+
+function parseGradle(
+  content: string,
+  repoPath: string,
+): { groupId: string; artifactId: string; deps: string[] } | null {
+  const groupMatch = content.match(/group\s*=\s*['"]([^'"]+)['"]/);
+  const dirName = path.basename(repoPath);
+  const groupId = groupMatch ? groupMatch[1] : '';
+  if (!groupId) return null;
+
+  const artifactId = dirName;
+
+  const deps: string[] = [];
+  // implementation("group:artifact:version") or api("group:artifact:version")
+  const depMatches = content.matchAll(
+    /(?:implementation|api|compileOnly|runtimeOnly)\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  );
+  for (const m of depMatches) {
+    const parts = m[1].split(':');
+    if (parts.length >= 2) {
+      deps.push(`${parts[0]}:${parts[1]}`);
+    }
+  }
+
+  // implementation(project(":subproject"))
+  const projDeps = content.matchAll(
+    /(?:implementation|api)\s*\(\s*project\s*\(\s*['"]([^'"]+)['"]\s*\)\s*\)/g,
+  );
+  for (const m of projDeps) {
+    const subName = m[1].replace(/^:/, '');
+    deps.push(`${groupId}:${subName}`);
+  }
+
+  return { groupId, artifactId, deps: [...new Set(deps)] };
+}
+
+function deriveBasePackage(groupId: string, artifactId: string): string {
+  const sanitized = artifactId.replace(/-/g, '.');
+  if (groupId.endsWith(`.${sanitized}`) || groupId === sanitized) {
+    return groupId;
+  }
+  return `${groupId}.${sanitized}`;
+}
+
+async function scanJavaImports(
+  repoPath: string,
+  knownPackages: Map<string, string>,
+): Promise<ImportedSymbol[]> {
+  const results: ImportedSymbol[] = [];
+  const sourceFiles = await findJavaFiles(repoPath);
+
+  for (const relFile of sourceFiles) {
+    const absPath = path.join(repoPath, relFile);
+    let content: string;
+    try {
+      content = await fs.readFile(absPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const importRegex = /^import\s+(?:static\s+)?([a-zA-Z][\w.]*\.[A-Z]\w*)/gm;
+    let match;
+    while ((match = importRegex.exec(content)) !== null) {
+      const fullImport = match[1];
+      for (const [basePkg, artifactKey] of knownPackages) {
+        if (fullImport.startsWith(basePkg + '.') || fullImport === basePkg) {
+          const parts = fullImport.split('.');
+          const className = parts[parts.length - 1];
+          if (isPascalCase(className)) {
+            results.push({
+              artifactKey,
+              symbolName: className,
+              filePath: relFile,
+            });
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+function isPascalCase(name: string): boolean {
+  return /^[A-Z][A-Za-z0-9]*$/.test(name);
+}
+
+async function findJavaFiles(repoPath: string): Promise<string[]> {
+  const results: string[] = [];
+  const ig = await loadIgnoreRules(repoPath);
+
+  async function walk(dir: string, rel: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (shouldIgnorePath(childRel)) continue;
+        if (ig && ig.ignores(childRel + '/')) continue;
+        await walk(path.join(dir, entry.name), childRel);
+      } else if (entry.name.endsWith('.java') || entry.name.endsWith('.kt')) {
+        if (shouldIgnorePath(childRel)) continue;
+        if (ig && ig.ignores(childRel)) continue;
+        results.push(childRel);
+      }
+    }
+  }
+
+  await walk(repoPath, '');
+  return results;
+}
+
+export interface JavaWorkspaceResult {
+  links: GroupManifestLink[];
+  discoveredProjects: Map<string, JavaProjectMeta>;
+}
+
+export async function extractJavaWorkspaceLinks(
+  repos: Record<string, string>,
+  repoPaths: Map<string, string>,
+  _dbExecutors?: Map<string, CypherExecutor>,
+): Promise<JavaWorkspaceResult> {
+  const projectsByKey = new Map<string, JavaProjectMeta>();
+  const projectsByGroupPath = new Map<string, JavaProjectMeta>();
+
+  for (const [groupPath] of Object.entries(repos)) {
+    const repoPath = repoPaths.get(groupPath);
+    if (!repoPath) continue;
+
+    const manifest = await parseJavaManifest(repoPath);
+    if (!manifest) continue;
+
+    const key = `${manifest.groupId}:${manifest.artifactId}`;
+    const meta: JavaProjectMeta = {
+      groupId: manifest.groupId,
+      artifactId: manifest.artifactId,
+      basePackage: deriveBasePackage(manifest.groupId, manifest.artifactId),
+      groupPath,
+      repoPath,
+      deps: manifest.deps,
+    };
+    const existing = projectsByKey.get(key);
+    if (existing) {
+      console.warn(
+        `[java-workspace-extractor] duplicate artifact "${key}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
+      );
+      continue;
+    }
+    projectsByKey.set(key, meta);
+    projectsByGroupPath.set(groupPath, meta);
+  }
+
+  const links: GroupManifestLink[] = [];
+  const seen = new Set<string>();
+
+  for (const [, proj] of projectsByGroupPath) {
+    const groupDeps = proj.deps.filter((d) => projectsByKey.has(d));
+    if (groupDeps.length === 0) continue;
+
+    const knownPackages = new Map<string, string>();
+    for (const dep of groupDeps) {
+      const depMeta = projectsByKey.get(dep);
+      if (depMeta) knownPackages.set(depMeta.basePackage, dep);
+    }
+
+    const imports = await scanJavaImports(proj.repoPath, knownPackages);
+
+    for (const imp of imports) {
+      const providerProj = projectsByKey.get(imp.artifactKey);
+      if (!providerProj) continue;
+
+      const qualifiedContract = `${providerProj.artifactId}::${imp.symbolName}`;
+      const dedupKey = `${proj.groupPath}→${providerProj.groupPath}::${qualifiedContract}`;
+      if (seen.has(dedupKey)) continue;
+      seen.add(dedupKey);
+
+      const link: GroupManifestLink = {
+        from: providerProj.groupPath,
+        to: proj.groupPath,
+        type: 'custom',
+        contract: qualifiedContract,
+        role: 'provider' as ContractRole,
+      };
+      links.push(link);
+    }
+  }
+
+  return { links, discoveredProjects: projectsByGroupPath };
+}
@@ -177,7 +177,7 @@ export class ManifestExtractor {

    // NOTE: All lookups use EXACT equality on the relevant name field and
    // deterministic ORDER BY before LIMIT 1. Previous versions used CONTAINS
-    // for fuzzy matching (plus an unconditional ".proto" fallback for gRPC)
+    // for fuzzy matching (plus an unconditional IDL file fallback for gRPC)
    // which produced silent false positives: e.g. manifest "/orders" would
    // match "/suborders", and a gRPC manifest entry in a repo with any
    // .proto file would attach to a random proto symbol.
@@ -225,16 +225,21 @@ export class ManifestExtractor {
           LIMIT 1`,
          { contract: link.contract },
        );
-      } else if (link.type === 'grpc') {
+      } else if (link.type === 'grpc' || link.type === 'thrift') {
        // Contract is "Service/Method" or just "Service" (or package.Service
        // variants). Prefer matching by method name when present, otherwise
-        // by service name. NO .proto path fallback — that's guaranteed to
-        // return a wrong symbol in any repo with more than one proto file.
+        // by service name. Thrift generated Java classes often use
+        // package.Service in manifests while graph Class/Interface names are
+        // stored as bare Service, so strip the package prefix for thrift
+        // service-name lookups. NO IDL path fallback — that's guaranteed to
+        // return a wrong symbol in any repo with more than one IDL file.
        // Label filters scope lookups: methods → Function|Method, services
        // → Class|Interface (no label match = no silent wrong hits on
        // File/Variable nodes that happen to share the name).
        const parts = link.contract.split('/');
-        const serviceName = parts[0]?.trim() ?? '';
+        const rawServiceName = parts[0]?.trim() ?? '';
+        const serviceName =
+          link.type === 'thrift' ? (rawServiceName.split('.').pop() ?? '') : rawServiceName;
        const methodName = parts[1]?.trim() ?? '';
        if (methodName) {
          rows = await executor(
@@ -268,6 +273,21 @@ export class ManifestExtractor {
           LIMIT 1`,
          { contract: link.contract },
        );
+      } else if (link.type === 'custom') {
+        // Workspace extractors produce qualified contracts like "mathlex::Expression".
+        // Graph nodes store the unqualified symbol name ("Expression"), so strip
+        // the "provider::" prefix before querying.
+        const symbolName = link.contract.includes('::')
+          ? link.contract.split('::').pop()!
+          : link.contract;
+        rows = await executor(
+          `MATCH (n:Function|Method|Class|Interface|Struct|Enum|Trait|Constructor|TypeAlias|Impl|Macro|Union|Typedef|Property|Record|Delegate|Annotation|Template|Const|Static|CodeElement)
+           WHERE n.name = $symbolName
+           RETURN n.id AS uid, n.name AS name, n.filePath AS filePath
+           ORDER BY n.filePath ASC
+           LIMIT 1`,
+          { symbolName },
+        );
      } else {
        return null;
      }
@@ -329,6 +349,8 @@ export class ManifestExtractor {
      }
      case 'grpc':
        return `grpc::${contract}`;
+      case 'thrift':
+        return `thrift::${contract}`;
      case 'topic':
        return `topic::${contract}`;
      case 'lib':
@@ -0,0 +1,248 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { CypherExecutor } from '../contract-extractor.js';
+import type { GroupManifestLink, ContractRole } from '../types.js';
+import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
+
+interface PackageMeta {
+  name: string;
+  groupPath: string;
+  repoPath: string;
+  workspaceDeps: string[];
+}
+
+interface ImportedSymbol {
+  packageName: string;
+  symbolName: string;
+  filePath: string;
+}
+
+async function parsePackageManifest(
+  repoPath: string,
+): Promise<{ name: string; workspaceDeps: string[] } | null> {
+  const pkgPath = path.join(repoPath, 'package.json');
+  let content: string;
+  try {
+    content = await fs.readFile(pkgPath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(content);
+  } catch {
+    return null;
+  }
+
+  const name = typeof pkg.name === 'string' ? pkg.name : '';
+  if (!name) return null;
+
+  const deps: string[] = [];
+  for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
+    const section = pkg[field];
+    if (section && typeof section === 'object') {
+      deps.push(...Object.keys(section as Record<string, unknown>));
+    }
+  }
+
+  return { name, workspaceDeps: [...new Set(deps)] };
+}
+
+async function scanImports(
+  repoPath: string,
+  knownPackages: Set<string>,
+): Promise<ImportedSymbol[]> {
+  const results: ImportedSymbol[] = [];
+  const sourceFiles = await findSourceFiles(repoPath);
+
+  for (const relFile of sourceFiles) {
+    const absPath = path.join(repoPath, relFile);
+    let content: string;
+    try {
+      content = await fs.readFile(absPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    // ES import: import { Foo, Bar } from '<pkg>'
+    // Also: import { Foo as Baz } from '<pkg>'
+    const esImportRegex = /^import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/gm;
+    let match;
+    while ((match = esImportRegex.exec(content)) !== null) {
+      const importClause = match[1];
+      const modulePath = match[2];
+      const pkgName = resolvePackageName(modulePath);
+      if (!pkgName || !knownPackages.has(pkgName)) continue;
+
+      const symbols = parseImportClause(importClause);
+      for (const sym of symbols) {
+        if (isExportedName(sym)) {
+          results.push({ packageName: pkgName, symbolName: sym, filePath: relFile });
+        }
+      }
+    }
+
+    // ES import default: import Foo from '<pkg>'
+    const defaultImportRegex = /^import\s+([A-Z][A-Za-z0-9]*)\s+from\s+['"]([^'"]+)['"]/gm;
+    while ((match = defaultImportRegex.exec(content)) !== null) {
+      const symbolName = match[1];
+      const modulePath = match[2];
+      const pkgName = resolvePackageName(modulePath);
+      if (!pkgName || !knownPackages.has(pkgName)) continue;
+
+      if (isExportedName(symbolName)) {
+        results.push({ packageName: pkgName, symbolName, filePath: relFile });
+      }
+    }
+
+    // CommonJS: const { Foo, Bar } = require('<pkg>')
+    const cjsRegex = /(?:const|let|var)\s+\{([^}]+)\}\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)/gm;
+    while ((match = cjsRegex.exec(content)) !== null) {
+      const importClause = match[1];
+      const modulePath = match[2];
+      const pkgName = resolvePackageName(modulePath);
+      if (!pkgName || !knownPackages.has(pkgName)) continue;
+
+      const symbols = parseImportClause(importClause);
+      for (const sym of symbols) {
+        if (isExportedName(sym)) {
+          results.push({ packageName: pkgName, symbolName: sym, filePath: relFile });
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+function resolvePackageName(modulePath: string): string | null {
+  if (modulePath.startsWith('.') || modulePath.startsWith('/')) return null;
+  // Scoped: @scope/pkg or @scope/pkg/sub
+  if (modulePath.startsWith('@')) {
+    const parts = modulePath.split('/');
+    if (parts.length >= 2) return `${parts[0]}/${parts[1]}`;
+    return null;
+  }
+  // Unscoped: pkg or pkg/sub
+  return modulePath.split('/')[0];
+}
+
+function parseImportClause(clause: string): string[] {
+  return clause
+    .split(',')
+    .map((s) => {
+      const trimmed = s.trim();
+      // Handle `Foo as Bar` — use the original export name
+      const asMatch = trimmed.match(/^(\S+)\s+as\s+/);
+      return asMatch ? asMatch[1] : trimmed;
+    })
+    .filter(Boolean);
+}
+
+function isExportedName(name: string): boolean {
+  return /^[A-Z][A-Za-z0-9]*$/.test(name);
+}
+
+async function findSourceFiles(repoPath: string): Promise<string[]> {
+  const results: string[] = [];
+  const EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts']);
+  const ig = await loadIgnoreRules(repoPath);
+
+  async function walk(dir: string, rel: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (shouldIgnorePath(childRel)) continue;
+        if (ig && ig.ignores(childRel + '/')) continue;
+        await walk(path.join(dir, entry.name), childRel);
+      } else {
+        const ext = path.extname(entry.name);
+        if (EXTENSIONS.has(ext)) {
+          if (shouldIgnorePath(childRel)) continue;
+          if (ig && ig.ignores(childRel)) continue;
+          results.push(childRel);
+        }
+      }
+    }
+  }
+
+  await walk(repoPath, '');
+  return results;
+}
+
+export interface NodeWorkspaceResult {
+  links: GroupManifestLink[];
+  discoveredPackages: Map<string, PackageMeta>;
+}
+
+export async function extractNodeWorkspaceLinks(
+  repos: Record<string, string>,
+  repoPaths: Map<string, string>,
+  _dbExecutors?: Map<string, CypherExecutor>,
+): Promise<NodeWorkspaceResult> {
+  const packagesByName = new Map<string, PackageMeta>();
+  const packagesByGroupPath = new Map<string, PackageMeta>();
+
+  for (const [groupPath] of Object.entries(repos)) {
+    const repoPath = repoPaths.get(groupPath);
+    if (!repoPath) continue;
+
+    const manifest = await parsePackageManifest(repoPath);
+    if (!manifest) continue;
+
+    const meta: PackageMeta = {
+      name: manifest.name,
+      groupPath,
+      repoPath,
+      workspaceDeps: manifest.workspaceDeps,
+    };
+    const existing = packagesByName.get(manifest.name);
+    if (existing) {
+      console.warn(
+        `[node-workspace-extractor] duplicate package name "${manifest.name}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
+      );
+      continue;
+    }
+    packagesByName.set(manifest.name, meta);
+    packagesByGroupPath.set(groupPath, meta);
+  }
+
+  const links: GroupManifestLink[] = [];
+  const seen = new Set<string>();
+
+  for (const [, pkg] of packagesByGroupPath) {
+    const groupPkgDeps = pkg.workspaceDeps.filter((d) => packagesByName.has(d));
+    if (groupPkgDeps.length === 0) continue;
+
+    const knownPackages = new Set(groupPkgDeps);
+    const imports = await scanImports(pkg.repoPath, knownPackages);
+
+    for (const imp of imports) {
+      const providerPkg = packagesByName.get(imp.packageName);
+      if (!providerPkg) continue;
+
+      const qualifiedContract = `${imp.packageName}::${imp.symbolName}`;
+      const key = `${pkg.groupPath}→${providerPkg.groupPath}::${qualifiedContract}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const link: GroupManifestLink = {
+        from: providerPkg.groupPath,
+        to: pkg.groupPath,
+        type: 'custom',
+        contract: qualifiedContract,
+        role: 'provider' as ContractRole,
+      };
+      links.push(link);
+    }
+  }
+
+  return { links, discoveredPackages: packagesByGroupPath };
+}
@@ -0,0 +1,254 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { CypherExecutor } from '../contract-extractor.js';
+import type { GroupManifestLink, ContractRole } from '../types.js';
+import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
+
+interface PythonPackageMeta {
+  name: string;
+  importName: string;
+  groupPath: string;
+  repoPath: string;
+  workspaceDeps: string[];
+}
+
+interface ImportedSymbol {
+  packageName: string;
+  symbolName: string;
+  filePath: string;
+}
+
+async function parsePythonManifest(
+  repoPath: string,
+): Promise<{ name: string; importName: string; deps: string[] } | null> {
+  const pyprojectPath = path.join(repoPath, 'pyproject.toml');
+  let content: string | null = null;
+  try {
+    content = await fs.readFile(pyprojectPath, 'utf-8');
+  } catch {
+    // fall through to setup.py
+  }
+
+  if (content) return parsePyproject(content);
+
+  const setupPyPath = path.join(repoPath, 'setup.py');
+  try {
+    content = await fs.readFile(setupPyPath, 'utf-8');
+  } catch {
+    return null;
+  }
+  return parseSetupPy(content);
+}
+
+function parsePyproject(
+  content: string,
+): { name: string; importName: string; deps: string[] } | null {
+  const nameMatch = content.match(/^\[project\]\s*\n(?:[^\n\[]*\n)*?name\s*=\s*"([^"]+)"/m);
+  if (!nameMatch) return null;
+  const name = nameMatch[1];
+  const importName = name.replace(/-/g, '_');
+
+  const deps: string[] = [];
+  const depsMatch = content.match(/^\[project\]\s*\n[\s\S]*?dependencies\s*=\s*\[([\s\S]*?)\]/m);
+  if (depsMatch) {
+    const depLines = depsMatch[1].matchAll(/"([^"]+)"/g);
+    for (const m of depLines) {
+      deps.push(extractPepName(m[1]));
+    }
+  }
+
+  const optMatch = content.match(/\[project\.optional-dependencies\]\s*\n([\s\S]*?)(?=\n\[|$)/);
+  if (optMatch) {
+    const optDeps = optMatch[1].matchAll(/"([^"]+)"/g);
+    for (const m of optDeps) {
+      deps.push(extractPepName(m[1]));
+    }
+  }
+
+  return { name, importName, deps: [...new Set(deps)] };
+}
+
+function parseSetupPy(
+  content: string,
+): { name: string; importName: string; deps: string[] } | null {
+  const nameMatch = content.match(/name\s*=\s*['"]([^'"]+)['"]/);
+  if (!nameMatch) return null;
+  const name = nameMatch[1];
+  const importName = name.replace(/-/g, '_');
+
+  const deps: string[] = [];
+  const installMatch = content.match(/install_requires\s*=\s*\[([\s\S]*?)\]/);
+  if (installMatch) {
+    const depLines = installMatch[1].matchAll(/['"]([^'"]+)['"]/g);
+    for (const m of depLines) {
+      deps.push(extractPepName(m[1]));
+    }
+  }
+
+  return { name, importName, deps: [...new Set(deps)] };
+}
+
+function extractPepName(spec: string): string {
+  return spec.split(/[><=!~;\[]/)[0].trim();
+}
+
+async function scanPythonImports(
+  repoPath: string,
+  knownPackages: Map<string, string>,
+): Promise<ImportedSymbol[]> {
+  const results: ImportedSymbol[] = [];
+  const sourceFiles = await findPythonFiles(repoPath);
+
+  for (const relFile of sourceFiles) {
+    const absPath = path.join(repoPath, relFile);
+    let content: string;
+    try {
+      content = await fs.readFile(absPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    // from <pkg> import Foo, Bar
+    // from <pkg>.module import Foo
+    const fromImportRegex = /^from\s+(\w[\w.]*)\s+import\s+(.+)/gm;
+    let match;
+    while ((match = fromImportRegex.exec(content)) !== null) {
+      const modulePath = match[1];
+      const importClause = match[2];
+      const rootModule = modulePath.split('.')[0];
+      const originalName = knownPackages.get(rootModule);
+      if (!originalName) continue;
+
+      if (importClause.trim() === '(') continue;
+
+      const symbols = importClause
+        .replace(/\(|\)/g, '')
+        .split(',')
+        .map((s) => {
+          const trimmed = s.trim();
+          const asMatch = trimmed.match(/^(\S+)\s+as\s+/);
+          return asMatch ? asMatch[1] : trimmed;
+        })
+        .filter(Boolean);
+
+      for (const sym of symbols) {
+        if (isPascalCase(sym)) {
+          results.push({ packageName: originalName, symbolName: sym, filePath: relFile });
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+function isPascalCase(name: string): boolean {
+  return /^[A-Z][A-Za-z0-9]*$/.test(name);
+}
+
+async function findPythonFiles(repoPath: string): Promise<string[]> {
+  const results: string[] = [];
+  const ig = await loadIgnoreRules(repoPath);
+
+  async function walk(dir: string, rel: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (shouldIgnorePath(childRel)) continue;
+        if (ig && ig.ignores(childRel + '/')) continue;
+        await walk(path.join(dir, entry.name), childRel);
+      } else if (entry.name.endsWith('.py')) {
+        if (shouldIgnorePath(childRel)) continue;
+        if (ig && ig.ignores(childRel)) continue;
+        results.push(childRel);
+      }
+    }
+  }
+
+  await walk(repoPath, '');
+  return results;
+}
+
+export interface PythonWorkspaceResult {
+  links: GroupManifestLink[];
+  discoveredPackages: Map<string, PythonPackageMeta>;
+}
+
+export async function extractPythonWorkspaceLinks(
+  repos: Record<string, string>,
+  repoPaths: Map<string, string>,
+  _dbExecutors?: Map<string, CypherExecutor>,
+): Promise<PythonWorkspaceResult> {
+  const packagesByImportName = new Map<string, PythonPackageMeta>();
+  const packagesByGroupPath = new Map<string, PythonPackageMeta>();
+
+  for (const [groupPath] of Object.entries(repos)) {
+    const repoPath = repoPaths.get(groupPath);
+    if (!repoPath) continue;
+
+    const manifest = await parsePythonManifest(repoPath);
+    if (!manifest) continue;
+
+    const meta: PythonPackageMeta = {
+      name: manifest.name,
+      importName: manifest.importName,
+      groupPath,
+      repoPath,
+      workspaceDeps: manifest.deps,
+    };
+    const existing = packagesByImportName.get(manifest.importName);
+    if (existing) {
+      console.warn(
+        `[python-workspace-extractor] duplicate package "${manifest.name}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
+      );
+      continue;
+    }
+    packagesByImportName.set(manifest.importName, meta);
+    packagesByGroupPath.set(groupPath, meta);
+  }
+
+  const links: GroupManifestLink[] = [];
+  const seen = new Set<string>();
+
+  for (const [, pkg] of packagesByGroupPath) {
+    const normalizedDeps = pkg.workspaceDeps.map((d) => d.replace(/-/g, '_'));
+    const groupPkgDeps = normalizedDeps.filter((d) => packagesByImportName.has(d));
+    if (groupPkgDeps.length === 0) continue;
+
+    const knownPackages = new Map<string, string>();
+    for (const dep of groupPkgDeps) {
+      const meta = packagesByImportName.get(dep);
+      if (meta) knownPackages.set(dep, meta.name);
+    }
+
+    const imports = await scanPythonImports(pkg.repoPath, knownPackages);
+
+    for (const imp of imports) {
+      const providerImportName = imp.packageName.replace(/-/g, '_');
+      const providerPkg = packagesByImportName.get(providerImportName);
+      if (!providerPkg) continue;
+
+      const qualifiedContract = `${providerPkg.name}::${imp.symbolName}`;
+      const key = `${pkg.groupPath}→${providerPkg.groupPath}::${qualifiedContract}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const link: GroupManifestLink = {
+        from: providerPkg.groupPath,
+        to: pkg.groupPath,
+        type: 'custom',
+        contract: qualifiedContract,
+        role: 'provider' as ContractRole,
+      };
+      links.push(link);
+    }
+  }
+
+  return { links, discoveredPackages: packagesByGroupPath };
+}
@@ -0,0 +1,270 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { CypherExecutor } from '../contract-extractor.js';
+import type { GroupManifestLink, ContractRole } from '../types.js';
+import { shouldIgnorePath } from '../../../config/ignore-service.js';
+import { loadIgnoreRules } from '../../../config/ignore-service.js';
+
+/**
+ * Discover cross-crate contracts in a Rust workspace by reading each
+ * member's `Cargo.toml` dependencies and scanning source files for
+ * `use <workspace_dep>::<Type>` imports.
+ *
+ * Emits `GroupManifestLink[]` with `type: 'custom'` that feed into the
+ * existing ManifestExtractor pipeline — no new matching logic needed.
+ *
+ * Designed for the group-level sync pipeline: it receives all repos in
+ * a group and produces cross-repo links between them.
+ */
+
+interface CrateMeta {
+  name: string;
+  groupPath: string;
+  repoPath: string;
+  workspaceDeps: string[];
+}
+
+interface ImportedSymbol {
+  crateName: string;
+  symbolName: string;
+  filePath: string;
+}
+
+/**
+ * Parse a Cargo.toml to extract the crate name and workspace dependency
+ * names. Uses simple line-based parsing — no TOML library needed for
+ * the subset we care about.
+ */
+async function parseCrateManifest(
+  repoPath: string,
+): Promise<{ name: string; workspaceDeps: string[] } | null> {
+  const cargoPath = path.join(repoPath, 'Cargo.toml');
+  let content: string;
+  try {
+    content = await fs.readFile(cargoPath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  let name = '';
+  const workspaceDeps: string[] = [];
+
+  const nameMatch = content.match(/^\[package\]\s*\n(?:[^\[]*?\n)*?name\s*=\s*"([^"]+)"/m);
+  if (nameMatch) name = nameMatch[1];
+
+  // Match dependencies that use workspace = true, which indicates they
+  // are workspace-internal deps:
+  //   dep_name = { workspace = true }
+  //   dep_name.workspace = true
+  //
+  // Also match plain path dependencies:
+  //   dep_name = { path = "../other" }
+  const depSections = content.matchAll(
+    /\[(dependencies|dev-dependencies|build-dependencies)\]\s*\n([\s\S]*?)(?=\n\[|$)/g,
+  );
+
+  for (const section of depSections) {
+    const sectionBody = section[2];
+    // workspace = true style
+    const wsMatches = sectionBody.matchAll(
+      /^(\w[\w-]*)\s*=\s*\{[^}]*workspace\s*=\s*true[^}]*\}/gm,
+    );
+    for (const m of wsMatches) workspaceDeps.push(m[1]);
+
+    // dotted workspace style: dep_name.workspace = true
+    const dottedMatches = sectionBody.matchAll(/^(\w[\w-]*)\.workspace\s*=\s*true/gm);
+    for (const m of dottedMatches) workspaceDeps.push(m[1]);
+
+    // path = "../other" style (local path deps within workspace)
+    const pathMatches = sectionBody.matchAll(
+      /^(\w[\w-]*)\s*=\s*\{[^}]*path\s*=\s*"[^"]*"[^}]*\}/gm,
+    );
+    for (const m of pathMatches) workspaceDeps.push(m[1]);
+  }
+
+  if (!name) return null;
+  return { name, workspaceDeps: [...new Set(workspaceDeps)] };
+}
+
+/**
+ * Scan Rust source files for `use <crate>::<path>::<Symbol>` patterns
+ * where <crate> is a known workspace dependency.
+ */
+async function scanImports(repoPath: string, knownCrates: Set<string>): Promise<ImportedSymbol[]> {
+  const results: ImportedSymbol[] = [];
+
+  const normalizedCrates = new Map<string, string>();
+  for (const c of knownCrates) {
+    normalizedCrates.set(c.replace(/-/g, '_'), c);
+  }
+
+  const sourceFiles = await findRustFiles(repoPath);
+  for (const relFile of sourceFiles) {
+    const absPath = path.join(repoPath, relFile);
+    let content: string;
+    try {
+      content = await fs.readFile(absPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    // Match patterns:
+    //   use crate_name::Type;
+    //   use crate_name::module::Type;
+    //   use crate_name::{Type1, Type2};
+    //   use crate_name::module::{Type1, Type2};
+    const useRegex = /^use\s+(\w+)::(.+);/gm;
+    let match;
+    while ((match = useRegex.exec(content)) !== null) {
+      const crateName = match[1];
+      const originalCrateName = normalizedCrates.get(crateName);
+      if (!originalCrateName) continue;
+
+      const importPath = match[2].trim();
+
+      // Handle grouped imports: {Type1, Type2, module::Type3}
+      const braceMatch = importPath.match(/\{([^}]+)\}/);
+      if (braceMatch) {
+        const items = braceMatch[1].split(',').map((s) => s.trim());
+        for (const item of items) {
+          const symbolName = extractSymbolName(item);
+          if (symbolName && isTypeName(symbolName)) {
+            results.push({ crateName: originalCrateName, symbolName, filePath: relFile });
+          }
+        }
+      } else {
+        const symbolName = extractSymbolName(importPath);
+        if (symbolName && isTypeName(symbolName)) {
+          results.push({ crateName: originalCrateName, symbolName, filePath: relFile });
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+/** Extract the final symbol name from a path like `module::submod::TypeName`. */
+function extractSymbolName(importPath: string): string | null {
+  const trimmed = importPath.trim();
+  if (!trimmed || trimmed === '*' || trimmed === 'self') return null;
+  const parts = trimmed.split('::');
+  return parts[parts.length - 1].trim() || null;
+}
+
+/**
+ * Heuristic: in Rust, types (structs, enums, traits) are PascalCase.
+ * Functions and modules are snake_case. We only want types as cross-crate
+ * contracts — functions are too granular and modules too broad.
+ */
+function isTypeName(name: string): boolean {
+  return /^[A-Z][A-Za-z0-9]*$/.test(name);
+}
+
+async function findRustFiles(repoPath: string): Promise<string[]> {
+  const results: string[] = [];
+  const ig = await loadIgnoreRules(repoPath);
+
+  async function walk(dir: string, rel: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (shouldIgnorePath(childRel)) continue;
+        if (ig && ig.ignores(childRel + '/')) continue;
+        await walk(path.join(dir, entry.name), childRel);
+      } else if (entry.name.endsWith('.rs')) {
+        if (shouldIgnorePath(childRel)) continue;
+        if (ig && ig.ignores(childRel)) continue;
+        results.push(childRel);
+      }
+    }
+  }
+
+  await walk(repoPath, '');
+  return results;
+}
+
+export interface RustWorkspaceResult {
+  links: GroupManifestLink[];
+  discoveredCrates: Map<string, CrateMeta>;
+}
+
+/**
+ * Discover cross-crate contracts across all Rust repos in a group.
+ *
+ * Returns `GroupManifestLink[]` ready to feed into `ManifestExtractor`.
+ */
+export async function extractRustWorkspaceLinks(
+  repos: Record<string, string>,
+  repoPaths: Map<string, string>,
+  _dbExecutors?: Map<string, CypherExecutor>,
+): Promise<RustWorkspaceResult> {
+  // Phase 1: Parse all Cargo.toml files to build crate registry
+  const cratesByName = new Map<string, CrateMeta>();
+  const cratesByGroupPath = new Map<string, CrateMeta>();
+
+  for (const [groupPath] of Object.entries(repos)) {
+    const repoPath = repoPaths.get(groupPath);
+    if (!repoPath) continue;
+
+    const manifest = await parseCrateManifest(repoPath);
+    if (!manifest) continue;
+
+    const meta: CrateMeta = {
+      name: manifest.name,
+      groupPath,
+      repoPath,
+      workspaceDeps: manifest.workspaceDeps,
+    };
+    const existing = cratesByName.get(manifest.name);
+    if (existing) {
+      console.warn(
+        `[rust-workspace-extractor] duplicate crate name "${manifest.name}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
+      );
+      continue;
+    }
+    cratesByName.set(manifest.name, meta);
+    cratesByGroupPath.set(groupPath, meta);
+  }
+
+  // Phase 2: For each crate, identify which of its workspace deps are
+  // also in this group (i.e., repos we can link to)
+  const links: GroupManifestLink[] = [];
+  const seen = new Set<string>();
+
+  for (const [, crate] of cratesByGroupPath) {
+    const groupCrateDeps = crate.workspaceDeps.filter((d) => cratesByName.has(d));
+    if (groupCrateDeps.length === 0) continue;
+
+    // Phase 3: Scan source files for imports from workspace deps
+    const knownCrates = new Set(groupCrateDeps);
+    const imports = await scanImports(crate.repoPath, knownCrates);
+
+    for (const imp of imports) {
+      const providerCrate = cratesByName.get(imp.crateName);
+      if (!providerCrate) continue;
+
+      const qualifiedContract = `${imp.crateName}::${imp.symbolName}`;
+      const key = `${crate.groupPath}→${providerCrate.groupPath}::${qualifiedContract}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const link: GroupManifestLink = {
+        from: providerCrate.groupPath,
+        to: crate.groupPath,
+        type: 'custom',
+        contract: qualifiedContract,
+        role: 'provider' as ContractRole,
+      };
+      links.push(link);
+    }
+  }
+
+  return { links, discoveredCrates: cratesByGroupPath };
+}
@@ -0,0 +1,379 @@
+import { glob } from 'glob';
+import Parser from 'tree-sitter';
+import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
+import type { ExtractedContract, RepoHandle } from '../types.js';
+import { readSafe } from './fs-utils.js';
+import {
+  getPluginForFile,
+  THRIFT_SCAN_GLOB,
+  type ThriftDetection,
+} from './thrift-patterns/index.js';
+
+export interface ThriftServiceInfo {
+  namespace: string;
+  serviceName: string;
+  methods: string[];
+  thriftPath: string;
+}
+
+export interface ThriftContext {
+  namespacesByThrift: Map<string, string>;
+  servicesByName: Map<string, ThriftServiceInfo[]>;
+}
+
+function normalizeThriftPath(rel: string): string {
+  return rel.replace(/\\/g, '/');
+}
+
+export function thriftMethodContractId(
+  namespace: string,
+  serviceName: string,
+  methodName: string,
+): string {
+  const prefix = namespace ? `${namespace}.${serviceName}` : serviceName;
+  return `thrift::${prefix}/${methodName}`;
+}
+
+export function thriftServiceContractId(namespace: string, serviceName: string): string {
+  const prefix = namespace ? `${namespace}.${serviceName}` : serviceName;
+  return `thrift::${prefix}/*`;
+}
+
+/**
+ * Replace Thrift comments and string literals with spaces while preserving
+ * newlines and character offsets. Service block scanning can then count braces
+ * without being confused by examples or comments inside the IDL.
+ */
+function stripThriftCommentsAndStrings(content: string): string {
+  const out = new Array<string>(content.length);
+  let i = 0;
+
+  while (i < content.length) {
+    const ch = content[i];
+    const next = content[i + 1];
+
+    if (ch === '/' && next === '/') {
+      out[i] = ' ';
+      out[i + 1] = ' ';
+      i += 2;
+      while (i < content.length && content[i] !== '\n') {
+        out[i] = content[i] === '\r' ? '\r' : ' ';
+        i++;
+      }
+      continue;
+    }
+
+    if (ch === '#') {
+      out[i] = ' ';
+      i++;
+      while (i < content.length && content[i] !== '\n') {
+        out[i] = content[i] === '\r' ? '\r' : ' ';
+        i++;
+      }
+      continue;
+    }
+
+    if (ch === '/' && next === '*') {
+      out[i] = ' ';
+      out[i + 1] = ' ';
+      i += 2;
+      while (i < content.length) {
+        if (content[i] === '*' && content[i + 1] === '/') {
+          out[i] = ' ';
+          out[i + 1] = ' ';
+          i += 2;
+          break;
+        }
+        out[i] = content[i] === '\n' || content[i] === '\r' ? content[i] : ' ';
+        i++;
+      }
+      continue;
+    }
+
+    if (ch === '"' || ch === "'") {
+      const quote = ch;
+      out[i] = ' ';
+      i++;
+      while (i < content.length) {
+        const c = content[i];
+        if (c === '\\' && i + 1 < content.length) {
+          out[i] = ' ';
+          out[i + 1] = ' ';
+          i += 2;
+          continue;
+        }
+        if (c === quote) {
+          out[i] = ' ';
+          i++;
+          break;
+        }
+        out[i] = c === '\n' || c === '\r' ? c : ' ';
+        i++;
+      }
+      continue;
+    }
+
+    out[i] = ch;
+    i++;
+  }
+
+  return out.join('');
+}
+
+function extractNamespace(sanitizedContent: string): string {
+  const namespaces: Array<{ language: string; namespace: string }> = [];
+  const namespaceRe = /^\s*namespace\s+([A-Za-z_*][\w.*-]*)\s+([A-Za-z_][\w.]*)\s*$/gm;
+  let match: RegExpExecArray | null;
+
+  while ((match = namespaceRe.exec(sanitizedContent)) !== null) {
+    namespaces.push({ language: match[1], namespace: match[2] });
+  }
+
+  return (
+    namespaces.find((entry) => entry.language === 'java')?.namespace ??
+    namespaces[0]?.namespace ??
+    ''
+  );
+}
+
+function extractServiceBlocks(sanitizedContent: string): Array<{ name: string; body: string }> {
+  const results: Array<{ name: string; body: string }> = [];
+  const headerRe = /service\s+([A-Za-z_]\w*)\s*(?:extends\s+[A-Za-z_][\w.]*)?\s*\{/g;
+  let headerMatch: RegExpExecArray | null;
+
+  while ((headerMatch = headerRe.exec(sanitizedContent)) !== null) {
+    const serviceName = headerMatch[1];
+    const bodyStart = headerMatch.index + headerMatch[0].length;
+    let depth = 1;
+    let pos = bodyStart;
+
+    while (pos < sanitizedContent.length && depth > 0) {
+      const ch = sanitizedContent[pos];
+      if (ch === '{') depth++;
+      else if (ch === '}') depth--;
+      pos++;
+    }
+
+    if (depth !== 0) continue;
+
+    results.push({
+      name: serviceName,
+      body: sanitizedContent.slice(bodyStart, pos - 1),
+    });
+  }
+
+  return results;
+}
+
+function extractMethods(sanitizedServiceBody: string): string[] {
+  const methods: string[] = [];
+  const methodRe =
+    /(?:^|[;,\n\r])\s*(?:oneway\s+)?[A-Za-z_][\w.]*(?:\s*<[^(){};]*>)?\s+([A-Za-z_]\w*)\s*\(/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = methodRe.exec(sanitizedServiceBody)) !== null) {
+    methods.push(match[1]);
+  }
+
+  return methods;
+}
+
+function thriftSourceScanSymbolUid(
+  contractId: string,
+  role: 'provider' | 'consumer',
+  filePath: string,
+  symbolName: string,
+): string {
+  const contractKey = contractId.startsWith('thrift::')
+    ? contractId.slice('thrift::'.length)
+    : contractId;
+  return ['source-scan::thrift', role, contractKey, normalizeThriftPath(filePath), symbolName].join(
+    '::',
+  );
+}
+
+function makeContract(
+  cid: string,
+  role: 'provider' | 'consumer',
+  filePath: string,
+  symbolName: string,
+  confidence: number,
+  meta: Record<string, unknown>,
+): ExtractedContract {
+  return {
+    contractId: cid,
+    type: 'thrift',
+    role,
+    symbolUid: thriftSourceScanSymbolUid(cid, role, filePath, symbolName),
+    symbolRef: { filePath: normalizeThriftPath(filePath), name: symbolName },
+    symbolName,
+    confidence,
+    meta: { ...meta, extractionStrategy: 'source_scan' },
+  };
+}
+
+export async function buildThriftContext(repoPath: string): Promise<ThriftContext> {
+  const thriftFiles = await glob('**/*.thrift', {
+    cwd: repoPath,
+    absolute: false,
+    nodir: true,
+    ignore: ['**/node_modules/**', '**/.git/**', '**/vendor/**', '**/dist/**', '**/build/**'],
+  });
+  const namespacesByThrift = new Map<string, string>();
+  const servicesByName = new Map<string, ThriftServiceInfo[]>();
+
+  for (const rel of thriftFiles) {
+    const thriftPath = normalizeThriftPath(rel);
+    const content = readSafe(repoPath, rel);
+    if (!content) continue;
+
+    const sanitized = stripThriftCommentsAndStrings(content);
+    const namespace = extractNamespace(sanitized);
+    namespacesByThrift.set(thriftPath, namespace);
+
+    for (const block of extractServiceBlocks(sanitized)) {
+      const methods = extractMethods(block.body);
+      const info: ThriftServiceInfo = {
+        namespace,
+        serviceName: block.name,
+        methods,
+        thriftPath,
+      };
+      const existing = servicesByName.get(block.name) ?? [];
+      existing.push(info);
+      servicesByName.set(block.name, existing);
+    }
+  }
+
+  return { namespacesByThrift, servicesByName };
+}
+
+export class ThriftExtractor implements ContractExtractor {
+  type = 'thrift' as const;
+
+  async canExtract(_repo: RepoHandle): Promise<boolean> {
+    return true;
+  }
+
+  async extract(
+    _dbExecutor: CypherExecutor | null,
+    repoPath: string,
+    _repo: RepoHandle,
+  ): Promise<ExtractedContract[]> {
+    const out: ExtractedContract[] = [];
+    const context = await buildThriftContext(repoPath);
+
+    for (const infos of context.servicesByName.values()) {
+      for (const info of infos) {
+        for (const methodName of info.methods) {
+          const symbolName = `${info.serviceName}.${methodName}`;
+          out.push(
+            makeContract(
+              thriftMethodContractId(info.namespace, info.serviceName, methodName),
+              'provider',
+              info.thriftPath,
+              symbolName,
+              0.85,
+              {
+                namespace: info.namespace,
+                service: info.serviceName,
+                method: methodName,
+                source: 'thrift_idl',
+              },
+            ),
+          );
+        }
+      }
+    }
+
+    const sourceFiles = await glob(THRIFT_SCAN_GLOB, {
+      cwd: repoPath,
+      absolute: false,
+      nodir: true,
+      ignore: ['**/node_modules/**', '**/.git/**', '**/vendor/**', '**/dist/**', '**/build/**'],
+    });
+
+    const parser = new Parser();
+    for (const rel of sourceFiles) {
+      const plugin = getPluginForFile(rel);
+      if (!plugin) continue;
+      const content = readSafe(repoPath, rel);
+      if (!content) continue;
+
+      let detections: ThriftDetection[] = [];
+      try {
+        parser.setLanguage(plugin.language);
+        const tree = parser.parse(content);
+        detections = plugin.scan(tree);
+      } catch {
+        continue;
+      }
+
+      for (const detection of detections) {
+        const contract = this.detectionToContract(detection, rel, context);
+        if (contract) out.push(contract);
+      }
+    }
+
+    return this.dedupe(out);
+  }
+
+  private detectionToContract(
+    detection: ThriftDetection,
+    filePath: string,
+    context: ThriftContext,
+  ): ExtractedContract | null {
+    const candidates = context.servicesByName.get(detection.serviceName) ?? [];
+    if (candidates.length > 1) return null;
+
+    const info = candidates[0];
+    if (info) {
+      if (!info.methods.includes(detection.methodName)) return null;
+      return makeContract(
+        thriftMethodContractId(info.namespace, info.serviceName, detection.methodName),
+        detection.role,
+        filePath,
+        detection.symbolName,
+        detection.confidenceWithIdl,
+        {
+          namespace: info.namespace,
+          service: info.serviceName,
+          method: detection.methodName,
+          source: detection.source,
+        },
+      );
+    }
+
+    if (
+      detection.role !== 'consumer' ||
+      !detection.methodName ||
+      !detection.usesGeneratedServiceMember
+    ) {
+      return null;
+    }
+    return makeContract(
+      thriftMethodContractId('', detection.serviceName, detection.methodName),
+      detection.role,
+      filePath,
+      detection.symbolName,
+      detection.confidenceWithoutIdl,
+      {
+        service: detection.serviceName,
+        method: detection.methodName,
+        source: 'java_thrift_consumer_weak',
+      },
+    );
+  }
+
+  private dedupe(items: ExtractedContract[]): ExtractedContract[] {
+    const byKey = new Map<string, ExtractedContract>();
+    for (const c of items) {
+      const key = `${c.contractId}|${c.role}|${c.symbolRef.filePath}|${c.symbolName}`;
+      const existing = byKey.get(key);
+      if (!existing || c.confidence > existing.confidence) {
+        byKey.set(key, c);
+      }
+    }
+    return Array.from(byKey.values());
+  }
+}
@@ -0,0 +1,16 @@
+import * as path from 'node:path';
+import type { ThriftLanguagePlugin } from './types.js';
+import { JAVA_THRIFT_PLUGIN } from './java.js';
+
+export type { ThriftDetection, ThriftLanguagePlugin, ThriftRole } from './types.js';
+
+const REGISTRY: Record<string, ThriftLanguagePlugin> = {
+  '.java': JAVA_THRIFT_PLUGIN,
+};
+
+export const THRIFT_SCAN_GLOB = '**/*.java';
+
+export function getPluginForFile(rel: string): ThriftLanguagePlugin | undefined {
+  const ext = path.extname(rel).toLowerCase();
+  return REGISTRY[ext];
+}
--- a/Show More
+++ b/Show More