chore: release v1.6.8 (#2260 )

Bump gitnexus, plugin.json, and marketplace.json to 1.6.8 and add the CHANGELOG section. Headline: opt-in PDG-backed impact analysis plus the full PDG/taint substrate (CFG → reaching-defs → intra/inter-procedural taint → control dependence) across the language matrix, multi-branch indexing, private GitHub PAT + Azure DevOps support, and MCP trace/HTTP. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ci: fail tree-sitter summary parse drift (#2246 )
2026-06-20 21:09:54 +01:00 · 2026-06-20 20:45:09 +01:00 · 2026-06-20 20:40:28 +01:00 · 2026-06-20 12:04:32 +01:00 · 2026-06-20 06:30:16 +01:00 · 2026-06-19 07:21:50 +01:00
603 changed files with 103378 additions and 3391 deletions
@@ -11,7 +11,7 @@
  "plugins": [
    {
      "name": "gitnexus",
-      "version": "1.6.7",
+      "version": "1.6.8",
      "source": "./gitnexus-claude-plugin",
      "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase."
    }
@@ -16,10 +16,10 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 ## Workflow

 ```
-1. query({query: "<error or symptom>"})            → Find related execution flows
+1. query({search_query: "<error or symptom>"})            → Find related execution flows
 2. context({name: "<suspect>"})                    → See callers/callees/processes
 3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
-4. cypher({query: "MATCH path..."})                 → Custom traces if needed
+4. cypher({statement: "MATCH path..."})                 → Custom traces if needed
 ```

 > If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
@@ -45,13 +45,14 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 | Intermittent failure | `context` → look for external calls, async deps            |
 | Performance issue    | `context` → find symbols with many callers (hot paths)     |
 | Recent regression    | `detect_changes` to see what your changes affect           |
+| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |

 ## Tools

 **query** — find code related to error:

 ```
-query({query: "payment validation error"})
+query({search_query: "payment validation error"})
 → Processes: CheckoutFlow, ErrorHandling
 → Symbols: validatePayment, handlePaymentError, PaymentException
 ```
@@ -72,10 +73,21 @@ MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "valid
 RETURN [n IN nodes(path) | n.name] AS chain
 ```

+**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
+
+```
+trace({ from: "processCheckout", to: "fetchRates" })
+→ status: ok, hopCount: 3
+→ hops: processCheckout → validatePayment → verifyCard → fetchRates
+→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
+```
+
+When no path exists, `trace` reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).
+
 ## Example: "Payment endpoint returns 500 intermittently"

 ```
-1. query({query: "payment error handling"})
+1. query({search_query: "payment error handling"})
   → Processes: CheckoutFlow, ErrorHandling
   → Symbols: validatePayment, handlePaymentError

@@ -18,7 +18,7 @@ description: "Use when the user asks how code works, wants to understand archite
 ```
 1. READ gitnexus://repos                          → Discover indexed repos
 2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. query({query: "<what you want to understand>"})  → Find related execution flows
+3. query({search_query: "<what you want to understand>"})  → Find related execution flows
 4. context({name: "<symbol>"})            → Deep dive on specific symbol
 5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
 ```
@@ -50,7 +50,7 @@ description: "Use when the user asks how code works, wants to understand archite
 **query** — find execution flows related to a concept:

 ```
-query({query: "payment processing"})
+query({search_query: "payment processing"})
 → Processes: CheckoutFlow, RefundFlow, WebhookHandler
 → Symbols grouped by flow with file locations
 ```
@@ -68,7 +68,7 @@ context({name: "validateUser"})

 ```
 1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
-2. query({query: "payment processing"})
+2. query({search_query: "payment processing"})
   → CheckoutFlow: processPayment → validateCard → chargeStripe
   → RefundFlow: initiateRefund → calculateRefund → processRefund
 3. context({name: "processPayment"})
@@ -35,10 +35,14 @@ For any task involving code understanding, debugging, impact analysis, or refact
 | `query`          | Process-grouped code intelligence — execution flows related to a concept |
 | `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
 | `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `trace`          | Shortest path between two symbols — "how does A reach B?" in one call     |
 | `detect_changes` | Git-diff impact — what do your current changes affect                    |
 | `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
 | `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
-| `list_repos`     | Discover indexed repos (paginated — `limit`/`offset`)                   |
+| `explain`        | Persisted taint findings — source→sink data flows (needs `analyze --pdg`) |
+| `pdg_query`      | Control/data dependence — what gates X (CDG) / where Y flows (REACHING_DEF); needs `analyze --pdg` |
+| `check`          | Check graph invariants such as circular imports                          |
+| `list_repos`     | Discover indexed repos (paginated — `limit`/`offset`)                    |

 ### Paginating `list_repos`

@@ -71,6 +75,35 @@ list_repos { offset: 400 }  → repos 401–437,                 hasMore false

 Notes: `offset` ≥ `total` returns an empty page (with `total` still reported). Out-of-range or malformed `limit`/`offset` (non-integer, `limit` outside `[1, 200]`, `offset < 0`) are rejected with a clear error — `limit` above the max is rejected, not silently capped. The order is deterministic (lower-cased name, then path), so paging never skips or duplicates an entry while the registry is unchanged.

+### Taint findings (`explain`)
+
+`explain` returns intra-procedural taint findings (`TAINTED` edges) recorded by `gitnexus analyze --pdg` — each with a sink category (command-injection, code-injection, path-traversal, sql-injection, xss), source/sink lines, and the ordered hop path with the variable carried on each hop.
+
+- `explain {}` — enumerate all findings for the repo (bounded by `limit`, deterministic order)
+- `explain { target: "src/vuln.ts" }` — findings in a file (suffix path match accepted)
+- `explain { target: "runUserCommand" }` — findings in a function (resolved like `context`; ambiguous names return ranked candidates)
+
+A repo indexed without `--pdg` returns a clear "no taint layer" note. Caveats: findings are intra-procedural only — cross-function, closure/callback, property/field, and implicit flows are not modeled, so the absence of a finding is **not** proof of safety. `SANITIZES` (sanitizer-kill) edges are queryable via `cypher`.
+
+### Control & data dependence (`pdg_query`)
+
+`pdg_query` reads the control/data-dependence layers `gitnexus analyze --pdg` records (CDG + REACHING_DEF, basic-block granular) — the control/data analog of `explain`. It is **always anchored** (a `target` file path or symbol, resolved like `context`) and has two modes:
+
+- `pdg_query { mode: "controls", target: "..." }` — CDG: "under what condition does X run?". Each edge is a controlling predicate block → dependent block with the branch sense (`'T'`/`'F'`) in `reason`; an edge into an early `return`/`throw` is flagged `guard: true` (guard-clause discovery — the sense depends on the predicate, so don't filter guards by a fixed label).
+- `pdg_query { mode: "flows", target: "...", variable?: "..." }` — REACHING_DEF def→use edges within the function; pass `variable` to trace one binding.
+
+A repo indexed without `--pdg` returns a "no PDG layer" note (or "status unknown" when the layer can't be confirmed). Intra-procedural only — cross-function flow is taint's domain (`explain`). The raw CDG/REACHING_DEF edges are also queryable via `cypher`. See the `gitnexus-pdg-query` skill for the full query surface.
+
+### Shortest path between two symbols (`trace`)
+
+`trace` answers "how does A reach B?" in one call — the shortest directed path over `CALLS` (plus `HAS_METHOD`, so a class-rooted trace descends into its methods) instead of chaining 3–8 `context`/`impact` hops by hand.
+
+- `trace { from: "validateUser", to: "executeQuery" }` — shortest path between two symbols.
+- Disambiguate common names with `from_uid`/`to_uid` (zero-ambiguity) or `from_file`/`to_file`; an ambiguous name returns ranked candidates.
+- `maxDepth` (default 10, max 30) bounds the search; `includeTests` (default false) lets the traversal pass through test-file symbols.
+
+Returns ordered `hops` (each `{ name, filePath, startLine }`) and an aligned `edges[]` of `{ relType, confidence }`, so call hops and containment (`HAS_METHOD`) hops stay distinguishable. When no path exists it reports the **furthest** reachable node (where the chain breaks) and sets `truncated: true` if a traversal cap was hit first. Every result carries a `status`: `ok` / `no_path` / `ambiguous` / `not_found` / `error`.
+
 ## Resources Reference

 Lightweight reads (~100-500 tokens) for navigation:
@@ -0,0 +1,89 @@
+---
+name: gitnexus-pdg-query
+description: "Use when querying or extending GitNexus's PDG control/data-dependence surface (the `pdg_query` MCP tool, CDG/REACHING_DEF edges), or reasoning about \"what controls X\" / \"where does Y flow\" / guard clauses. Examples: \"what guards this statement?\", \"trace this variable within the function\", \"why is the pdg_query result empty?\", \"add a CDG query\"."
+---
+
+# PDG query surface with GitNexus
+
+Expert knowledge for the `pdg_query` MCP tool and the control/data-dependence
+edges it reads — the opt-in `--pdg` program-dependence layers. Read this before
+touching `gitnexus/src/mcp/local/local-backend.ts` (`_pdgQueryImpl`) or the
+`pdg_query` tool def, or when explaining a `pdg_query` result.
+
+## When to Use
+
+- "Under what condition does this statement run?" (guarding predicates).
+- "Where does this variable flow inside the function?" (def→use).
+- Guard-clause discovery (early-return guards — subsumes the #559 heuristic).
+- Extending or reviewing `pdg_query` / the CDG / REACHING_DEF read path.
+- Debugging an empty or surprising `pdg_query` result.
+
+## The layered substrate (build order)
+
+`pdg_query` runs **on** the same graph taint runs on. Each layer is opt-in
+behind `--pdg`; a default `analyze` run records none of them (byte-identical).
+
+```
+L1  CFG            per-function basic blocks + control-flow edges   (M1 #2081)
+L2  REACHING_DEF   GEN/KILL def→use data dependence (pure solver)   (M2 #2082)
+L5  CDG            Ferrante control dependence (post-dominators)    (M5 #2085)
+```
+
+All three are `BasicBlock → BasicBlock` edges in the single `CodeRelation` table
+(keyed by the `type` property). There is **no** `Function → BasicBlock` edge.
+
+## The two modes
+
+- `pdg_query({ mode: 'controls', target })` — CDG. For the anchored function,
+  each edge: controlling predicate block → dependent block + branch sense in
+  `label` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An
+  edge into an early-return/throw block is flagged `guard: true`.
+- `pdg_query({ mode: 'flows', target, variable? })` — REACHING_DEF def→use
+  edges; `variable` filters to one binding.
+
+`target` is **required** — a file path or a symbol/function name (resolved like
+`context()`). There is no anchorless mode (see below).
+
+## The corrected guard-clause Cypher
+
+The RFC #567 §2 form (`[:CDG {label:'F'}]`) does **not** run as written. Edges
+are values of the single `CodeRelation` table's `type` property, and the branch
+sense is in `reason`, NOT a `label` column:
+
+```cypher
+MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock)
+WHERE dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw'
+RETURN pred.startLine, r.reason AS branch, dep.startLine, dep.text
+```
+
+`r.reason` is the sense the predicate took to reach the early exit. For
+`if (!ok) return;` the return rides the predicate's **true** arm (`'T'`) and the
+protected body rides the **false** arm (`'F'`) — polarity depends on the guard,
+so don't hard-code one sense.
+
+## Gotchas (the load-bearing ones)
+
+- **Always anchored + LIMIT-bounded.** LadybugDB has no rel-property index, so
+  an unanchored `[:CDG*]`/`[:REACHING_DEF*]` path scan is unbounded. `pdg_query`
+  requires `target` and bounds the page; raw `cypher` callers must anchor on a
+  file id-prefix or symbol span themselves.
+- **BasicBlock↔symbol join is reconstructed.** No `Function→BasicBlock` edge:
+  the block is matched by its id-prefix (`BasicBlock:<file>:<fnStartLine>:…`)
+  plus `startLine` within the symbol's span. BasicBlock `startLine` is **1-based**
+  while the symbol node's `startLine`/`endLine` are **0-based**, so **both** bounds
+  are shifted `+1` (`[symStart+1, symEnd+1]`): the upper `+1` keeps a guard/def/use
+  on the function's **final line**, the lower `+1` excludes an adjacent function's
+  block on the line directly **above**. Same-line / nested functions anchor coarsely.
+- **No PDG layer ⇒ a note, not an error.** If the repo wasn't indexed with
+  `--pdg` the tool returns `{ results: [], note: "no PDG layer …" }` (cheap meta
+  probe on `RepoMeta.pdg.maxCdgEdgesPerFunction` / `maxReachingDefEdgesPerFunction`).
+- **CDG labels are binary in M5/M6.** Every `switch`-case arm is `'T'`; per-case
+  conditions are not yet distinguished.
+- **Intra-procedural only.** Cross-function flow is taint's domain (`explain`).
+
+## Mirror, don't fork
+
+`_pdgQueryImpl` is the front half of `_explainImpl` (WAL wrapper, meta no-layer
+probe, limit validation, `resolveSymbolCandidates` anchoring) with CDG/
+REACHING_DEF instead of TAINTED — and none of taint's path-codec / interproc
+`TAINT_PATH` machinery. Reuse those shared helpers; do not re-implement them.
@@ -17,7 +17,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru

 ```
 1. impact({target: "X", direction: "upstream"})  → Map all dependents
-2. query({query: "X"})                            → Find execution flows involving X
+2. query({search_query: "X"})                            → Find execution flows involving X
 3. context({name: "X"})                           → See all incoming/outgoing refs
 4. Plan update order: interfaces → implementations → callers → tests
 ```
@@ -0,0 +1,178 @@
+---
+name: gitnexus-taint-analysis
+description: "Use when working on, reviewing, or extending GitNexus's CFG/taint/PDG subsystem (the `--pdg` layers), or when reasoning about source→sink data-flow findings. Examples: \"How does taint analysis work here?\", \"Why didn't explain find this flow?\", \"Add a new sink/source\", \"Review the interprocedural taint code\"."
+---
+
+# CFG & Taint Analysis with GitNexus
+
+Expert knowledge for the opt-in `--pdg` program-analysis subsystem: control-flow
+graphs, reaching definitions, and intra- + inter-procedural taint. Read this
+before touching `gitnexus/src/core/ingestion/cfg/**` or
+`gitnexus/src/core/ingestion/taint/**`, or when explaining a finding.
+
+## When to Use
+
+- "How does the taint engine work / why is this flow (not) reported?"
+- Adding a source, sink, or sanitizer to the model.
+- Extending or reviewing the CFG / reaching-defs / taint / summary code.
+- Understanding the `explain` MCP tool's findings (intra- vs inter-procedural).
+- Debugging a false positive or false negative in `--pdg` output.
+
+## The layered substrate (build order)
+
+Taint runs **on** the graph, not beside it. Each layer is opt-in behind `--pdg`
+and a default `analyze` run is **byte-identical** (the golden parity gate is the
+hard floor for every change here).
+
+```
+L1  CFG            per-function basic blocks + control-flow edges   (M1 #2081)
+L2  REACHING_DEF   GEN/KILL def→use data dependence (pure solver)   (M2 #2082)
+L3  Taint (intra)  source→sink over RD facts, minus sanitizers      (M3 #2083)
+L4  Taint (inter)  per-function summaries composed over CALLS       (M4 #2084)
+```
+
+- **Worker-built, main-thread-solved.** The parse worker builds each function's
+  CFG + harvests def/use + call-site facts onto `ParsedFile.cfgSideChannel`
+  (plain, structured-clone-safe data — never AST nodes). The main thread runs
+  the pure solvers. NEVER re-parse on the main thread (re-introduces the #1983
+  OOM).
+- **In-phase emit (KTD1).** L1–L4-harvest all run INSIDE the scope-resolution
+  pdg window (`scope-resolution/pipeline/run.ts`, gated `input.pdg === true`),
+  because the disk-backed ParsedFile store is cleared when that phase ends — a
+  standalone post-`mro` phase would read empty data. The cross-function fixpoint
+  (L4) is the exception: it runs in its OWN registered phase (`taintSummaries`)
+  AFTER scope-resolution, because it needs the COMPLETE call graph, and consumes
+  small plain summary data threaded out via `ScopeResolutionOutput`.
+- **Pure-solver contract.** `computeReachingDefs`, `computeTaintFlows`,
+  `harvestFunctionSummary`, and `solveInterprocTaint` are pure and deterministic
+  (no graph, no I/O, no logger; sorted outputs). Snapshot tests and
+  content-derived edge ids depend on it.
+
+## Intra-procedural taint (L3)
+
+Forward reachability over RD facts from matched **sources** to matched **sinks**,
+killed by **sanitizers**. Key design points worth internalizing:
+
+- **Occurrence-tagged sites.** A flat per-arg binding set cannot tell
+  `exec(escape(x))` (safe) from `exec(x)` (finding); the harvest records nested
+  call structure (`SiteRecord.parent`/via-tags) so sanitizer interposition is
+  precise.
+- **Kind-set sanitizer model.** A taint carries a set of *neutralized*
+  `SinkKind`s; a sink fires unless its kind is in the set. So `escape(req.body)`
+  suppresses `res.send` (xss) but STILL fires `db.query` (sql) — a kind-blind
+  kill would be a suppressed live injection (the forbidden FN direction).
+  `path.basename(t)` neutralizes path-traversal only, not command-injection.
+- **Statement-level finding identity.** NOT block-pair (block conflation drops
+  distinct findings; `exec(req.body, req.query)` is two findings).
+- Persisted as `TAINTED` edges (BasicBlock→BasicBlock); the path rides the
+  `reason` column via the shared versioned codec (`taint/path-codec.ts`).
+
+## Interprocedural taint (L4) — the functional/summary method
+
+The production approach (Sharir-Pnueli 1981; the same shape as Meta's Pysa and
+Mariana Trench, and FB Infer) — NOT full IFDS tabulation. Each function is
+reduced to a compact **summary**, and summaries are composed over the already-
+resolved `CALLS` graph.
+
+**Summary shape** (`taint/summary-model.ts`, whole-parameter granularity):
+
+| Edge | Meaning | Analogue |
+|------|---------|----------|
+| `param→return` | a param flows to the return value | TITO — **reserved** (the floor already covers its recall; precision pass deferred) |
+| `param→callee-arg` | a param flows into arg *j* of a call (carries the path's neutralized sink kinds) | TITO into callee |
+| `param→sink` | a param reaches a modelled sink | partial/triggered sink |
+| `source→return` | the function generates+returns a source | generative — **composed** via the caller's `callResults` |
+| `source→callee-arg` | a generated source flows into a call | fixpoint SEED |
+| `callResults` | a user-function call's result flows to a sink/return/callee-arg in the caller | composes with callee `source→return` |
+
+**The fixpoint** (`taint/interproc-solver.ts`): the unit is `(function,
+parameter, source)`. Seed from `source→callee-arg`, propagate via
+`param→callee-arg`, fire a finding when a tainted param meets `param→sink`.
+
+- **Cycle-safe by monotonicity.** The tainted-set is monotone over a finite
+  lattice (`fn × param × source`), so the worklist converges — a recursive call
+  just re-proposes an already-visited entry. SCC condensation would only refine
+  processing order; correctness/termination don't require it.
+- **Source-discriminated state (load-bearing).** Key the state by the SOURCE
+  too. Keying only by `(fn, param)` collapses multi-source flows: a sink param
+  tainted by source A is marked visited and a later flow from source B is dropped
+  before firing — the recurring multi-source bug class. (Bit M3; bit M4 U9.)
+- **Name-based call join.** Match a summary's call-arg edge to a `CALLS` edge by
+  CALLEE NAME, not call-site line — line-base parity (CFG 1-based vs reference
+  site) is fragile; the callee identity is exact and context-insensitivity
+  taints the callee's param identically at every call site.
+- Persisted as `TAINT_PATH` edges (Function→Function), function-level hop chain
+  in `reason` via the same codec; confidence < the intra-procedural 1.0.
+
+**Context-insensitivity** is the accepted trade-off at this tier: one summary
+per function, return/call-site merging accepted (security-conservative). Expect
+some FP from merging; the bigger FN sources are unmodeled features (below).
+
+## Known false-negative classes (documented, deferred)
+
+The largest is **closures/callbacks** (`arr.forEach(() => sink(y))`) — taint
+into a callback is dropped without per-library models (true of CodeQL's JS libs
+too). Also deferred: field/property flows (`obj.x = taint; sink(obj.y)`),
+field-sensitive access paths, guard-style sanitizers, implicit/control-dependence
+flows, promise/async-await threading, and **destructured/rest params before a
+tainted simple param** (the summary port index is the binding ordinal, not the
+formal arg position — needs a formal-param index threaded from the worker
+`BindingEntry`). The interprocedural join is also context-insensitive: when one
+caller invokes two distinct **same-named callees**, a flow into one
+over-attributes to both (sound — over-report, never a missed flow). Absence of a
+finding is NOT proof of safety.
+
+## GitNexus-specific gotchas
+
+- **Function↔CFG join.** `FunctionCfg.functionStartLine` is 1-based; `Function`/
+  `Method` node `startLine` is 0-based — join at `startLine - 1`. Function nodes
+  have no column, so same-line functions (`{a:()=>x(), b:()=>y()}`) are
+  ambiguous → drop (the summary driver counts `unresolved`) rather than
+  cross-wire.
+- **No rel-property index (S1).** Kuzu has no secondary index on relationship
+  properties, and unanchored `[:TAINTED*]`/`[:TAINT_PATH*]` queries explode.
+  TAINT_PATH is therefore MATERIALIZED + anchored at analyze time, never
+  traversed live; `explain` reads it source-anchored + LIMIT-guarded.
+- **`explain` is the only discovery surface.** `TAINTED`/`TAINT_PATH` are
+  deliberately OUT of `VALID_RELATION_TYPES` (impact's allow-list) and the web
+  schema (pinned in `security.test.ts`). `explain` enumerates both layers
+  (cross-function findings carry `interprocedural: true`).
+- **One shared codec.** Both the emit path and `explain` import
+  `taint/path-codec.ts`. Two hand-rolled copies of a wire format drift — never
+  fork it. New metadata extends the format WITHIN the version when writer +
+  reader ship together.
+- **Cache versioning.** A worker-harvest shape change bumps the parse-cache pdg
+  NAMESPACE (`pdg:N`), NOT `SCHEMA_BUMP` (which cold-invalidates every user).
+  Persisted-graph/config changes ride `RepoMeta.pdg`'s key-union mismatch →
+  full writeback. Model content rides `taintModelVersion`.
+
+## Adding a source / sink / sanitizer
+
+Edit the language model in `taint/typescript-model.ts` (registered via the
+explicit `registerBuiltinTaintModels` seam, keyed by `SupportedLanguages`). The
+spec is hashable data (no functions). A sanitizer's `neutralizes` lists the
+EXACT sink kinds it defends — never a blanket kill. Add a fixture + assert the
+finding (or its absence) in `test/unit/taint/` (real-source harness:
+`test/helpers/ts-cfg-harness.ts`); the end-to-end proof is
+`test/integration/cfg/`.
+
+## Validation checklist for any `--pdg` change
+
+```
+1. tsc clean (schema additions are exhaustiveness-checked; watch the
+   api.ts getNodeQuery runtime read-path if a node label is added).
+2. Targeted vitest by directory (test/unit/taint, test/unit/cfg,
+   test/integration/cfg) — verify by ISOLATION, not full-suite exit
+   (known load-flakes). `node scripts/build.js` before worker/integration runs.
+3. Flag-off golden byte-identical (pipeline-graph-golden.test.ts).
+4. bench/cfg/measure.mjs --check (no fingerprint drift / budget regression).
+5. detect_changes() before commit; impact({direction:'upstream'}) before
+   editing shared symbols (KnowledgeGraph, RepoMeta, RelationshipType, codec).
+```
+
+## Prior art (for deeper design questions)
+
+Sharir & Pnueli 1981 (functional approach); Reps-Horwitz-Sagiv IFDS (POPL 1995);
+FlowDroid/StubDroid (access-path summaries); Pysa & Mariana Trench (TITO /
+propagations, parallel SCC fixpoint); CodeQL Models-as-Data (the richest port
+notation, incl. callback ports); Infer (content-keyed incremental summaries).
@@ -22,26 +22,10 @@
 #     --format '{{json .Manifest.Digest}}'
 FROM mcr.microsoft.com/devcontainers/typescript-node@sha256:7c2e711a4f7b02f32d2da16192d5e05aa7c95279be4ce889cff5df316f251c1d

-# Build args. We deliberately set no version defaults here. devcontainer.json
-# `build.args` is the single source of truth for versions. A standalone
-# `docker build .devcontainer/` (for example, a CI smoke test) must pass each
-# version with --build-arg. Without a default, the build fails loudly instead of
-# silently drifting from the version pinned in devcontainer.json.
-ARG CLAUDE_CODE_VERSION
-ARG CODEX_VERSION
-# Cursor is pinned by version plus a per-arch tarball sha256 hash. The install
-# step below verifies that hash. All three values live in devcontainer.json
-# build.args. They follow the same rule as the others: one source of truth, and
-# no default so the build fails loudly if a value is missing.
-ARG CURSOR_VERSION
-ARG CURSOR_SHA256_X64
-ARG CURSOR_SHA256_ARM64
 # Bun is installed via the official remote script (bun.sh/install), pinned by
-# version. UNLIKE Cursor and the npm packages, this install path runs an
-# UNVERIFIED remote script — there is no tarball-hash check. Chosen explicitly
-# at request time over the pin-by-sha256 alternative for install-script
-# simplicity. To harden later, switch to a pinned tarball + per-arch sha256 in
-# the Cursor style (release artifacts at github.com/oven-sh/bun/releases).
+# version. Claude Code and Cursor also use official install scripts (no version
+# to pin). To harden Bun: switch to a pinned tarball + per-arch sha256
+# (release artifacts at github.com/oven-sh/bun/releases).
 ARG BUN_VERSION
 ARG TZ=UTC
 ARG USERNAME=node
@@ -50,10 +34,7 @@ ARG USERNAME=node
 # read them. We deliberately do not set CLAUDE_CONFIG_DIR here. Its one true
 # value lives in devcontainer.json `containerEnv`, and the runtime value wins
 # anyway.
-ENV CLAUDE_CODE_VERSION=${CLAUDE_CODE_VERSION} \
-    CODEX_VERSION=${CODEX_VERSION} \
-    CURSOR_VERSION=${CURSOR_VERSION} \
-    BUN_VERSION=${BUN_VERSION} \
+ENV BUN_VERSION=${BUN_VERSION} \
    BUN_INSTALL=/home/${USERNAME}/.bun \
    TZ=${TZ} \
    DEVCONTAINER=true \
@@ -86,51 +67,19 @@ RUN mkdir -p \

 USER ${USERNAME}

-# Install Claude Code and the Codex CLI globally, as the `node` user. The base
-# image sets /usr/local/share/npm-global as the npm-global prefix and makes the
-# `npm` group writable by `node`. So `npm install -g` works without sudo. Both
-# versions come from build args. To upgrade, bump them in devcontainer.json and
-# rebuild.
-RUN npm install -g \
-        @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION} \
-        @openai/codex@${CODEX_VERSION}
+# Install Claude Code via the official native installer. Downloads the latest
+# self-contained binary for the running platform and places it at
+# ~/.local/bin/claude — no Node.js runtime dependency, no version to pin.
+RUN curl -fsSL https://claude.ai/install.sh | bash

-# Install the Cursor CLI. It is pinned and hash-verified, and we run no remote
-# script. The cursor.com/install script just detects os/arch, downloads a
-# versioned tarball from
-# downloads.cursor.com/lab/<version>/<os>/<arch>/agent-cli-package.tar.gz,
-# extracts it, and symlinks `agent`/`cursor-agent` into ~/.local/bin. We do that
-# ourselves against a PINNED version plus a per-arch sha256 hash. So the build
-# runs no unverified remote code. This matches how we pin the base image and npm
-# packages by digest (issue #1451). The download is fail-closed: if the hash
-# does not match, the build aborts.
-#
-# To bump: set CURSOR_VERSION and both CURSOR_SHA256_* in devcontainer.json
-# build.args. Get each arch's hash with:
-#   curl -fSL https://downloads.cursor.com/lab/<ver>/linux/<x64|arm64>/agent-cli-package.tar.gz | sha256sum
-#
-# TARGETARCH is the per-platform build arg that BuildKit sets automatically. It
-# must be (re)declared in this stage to be visible. When the build is a
-# non-BuildKit `docker build`, TARGETARCH is unset, so we fall back to `dpkg
-# --print-architecture`.
-ARG TARGETARCH
-RUN set -eux; \
-    arch="${TARGETARCH:-$(dpkg --print-architecture)}"; \
-    case "$arch" in \
-        amd64) cursor_arch=x64;   cursor_sha="${CURSOR_SHA256_X64}";; \
-        arm64) cursor_arch=arm64; cursor_sha="${CURSOR_SHA256_ARM64}";; \
-        *) echo "unsupported architecture for Cursor: $arch" >&2; exit 1;; \
-    esac; \
-    url="https://downloads.cursor.com/lab/${CURSOR_VERSION}/linux/${cursor_arch}/agent-cli-package.tar.gz"; \
-    curl -fSL --retry 3 --max-time 120 -o /tmp/cursor.tgz "$url"; \
-    echo "${cursor_sha}  /tmp/cursor.tgz" | sha256sum -c -; \
-    dir="/home/${USERNAME}/.local/share/cursor-agent/versions/${CURSOR_VERSION}"; \
-    install -d "$dir" "/home/${USERNAME}/.local/bin"; \
-    tar --strip-components=1 -xzf /tmp/cursor.tgz -C "$dir"; \
-    test -x "$dir/cursor-agent"; \
-    ln -sf "$dir/cursor-agent" "/home/${USERNAME}/.local/bin/agent"; \
-    ln -sf "$dir/cursor-agent" "/home/${USERNAME}/.local/bin/cursor-agent"; \
-    rm -f /tmp/cursor.tgz
+# Install the Codex CLI globally via npm. No version pinned — @latest at build
+# time. (Codex has no native binary installer; npm is the canonical method.)
+RUN npm install -g @openai/codex
+
+# Install the Cursor agent CLI via the official install script. Downloads the
+# latest agent-cli-package for the running platform and places `cursor-agent`
+# and `agent` into ~/.local/bin — no version or hash to pin.
+RUN curl -fsSL https://cursor.com/install | bash

 # Install Bun via the official remote installer, pinned by version. The first
 # positional arg to `bash` is the release tag (`bun-vX.Y.Z`), so a specific
@@ -14,16 +14,6 @@
    "dockerfile": "Dockerfile",
    "context": ".",
    "args": {
-      "CLAUDE_CODE_VERSION": "2.1.156",
-      "CODEX_VERSION": "0.134.0",
-      // Cursor: a pinned version plus one sha256 hash per CPU arch. The
-      // Dockerfile checks the tarball against the hash at build time, so it
-      // never runs a remote install script. Bump all three values together.
-      // Re-hash each arch with:
-      //   curl -fSL https://downloads.cursor.com/lab/<ver>/linux/<x64|arm64>/agent-cli-package.tar.gz | sha256sum
-      "CURSOR_VERSION": "2026.05.28-a70ca7c",
-      "CURSOR_SHA256_X64": "7f8b6a09393e0b84b288cc6952b292fc98d15775f644cc01b0b9aa4f04b268df",
-      "CURSOR_SHA256_ARM64": "05a0ab361e038729aba25fe7f407531b3e8432912e499d0bffdf1dda0e7833e9",
      // Bun: pinned by version. Installed by the official bun.sh/install
      // script, which accepts the release tag as its first positional arg
      // (`bash -s bun-vX.Y.Z`). UNLIKE Cursor, the install path runs an
@@ -324,17 +314,6 @@
  // dependency explicit instead of silently following the default.
  "containerEnv": {
    "CODEX_HOME": "/home/node/.codex",
-    "DISABLE_AUTOUPDATER": "1",
-    // post-create.sh removes `installMethod` from the seeded ~/.claude.json so
-    // the npm-global binary detects its own install method. This is a backup
-    // safeguard for Claude Code issue #17289. The install-checks routine probes
-    // ~/.local/bin/claude just because that directory EXISTS. It does exist
-    // here, because Cursor drops agent and cursor-agent symlinks there. So even
-    // when installMethod is non-native, the routine reports a false "claude
-    // command not found at ~/.local/bin/claude". DISABLE_AUTOUPDATER does NOT
-    // turn that routine off. DISABLE_INSTALLATION_CHECKS is its dedicated kill
-    // switch.
-    "DISABLE_INSTALLATION_CHECKS": "1",
    "HISTFILE": "/commandhistory/.zsh_history"
  },

@@ -141,15 +141,12 @@ sync_from_host /host/.codex/config.toml   /home/node/.codex/config.toml   644
 # Seed $HOME/.claude.json from the host, but NOT as a straight copy. That file
 # mixes two kinds of state. Some is portable account and onboarding state we
 # want to keep: hasCompletedOnboarding, oauthAccount, userID, projects,
-# tipsHistory. The rest describes how Claude is installed on the host, and that
-# part is never valid here. This image installs Claude with `npm install -g`,
-# but the host's `installMethod` (for example "native") makes Claude look for
-# ~/.local/bin/claude and fail with
-# "claude command not found at /home/node/.local/bin/claude". The fix strips the
-# machine-specific fields and forces hasCompletedOnboarding, while handling a
-# host file that isn't a JSON object. That logic lives in seed-claude-config.cjs
-# so it can be unit-tested and prettier-checked
-# (translate-plugin-registries.test.cjs).
+# tipsHistory. The rest describes how Claude is installed on the HOST, and that
+# part is never valid here — for example the host's `installMethod` value only
+# makes sense for the host's binary. The fix strips the machine-specific fields
+# and forces hasCompletedOnboarding, while handling a host file that isn't a
+# JSON object. That logic lives in seed-claude-config.cjs so it can be
+# unit-tested and prettier-checked (translate-plugin-registries.test.cjs).
 node "$SCRIPT_DIR/seed-claude-config.cjs"

 # Codex auth. Some hosts store credentials in the OS keyring instead of on disk
@@ -17,3 +17,9 @@ WEB_HOST_PORT=4173
 # Optional read-only mount, exposed to the server as /workspace.
 # Override with the directory that contains the repos you want to index.
 WORKSPACE_DIR=./
+
+# Azure DevOps Server Integration (passed to the server container)
+# Prefer https:// — the PAT rides in an Authorization header, so cleartext
+# http:// exposes it on the wire (still supported for internal-only instances).
+# AZURE_DEVOPS_URL=https://azuredevops.example.com
+# AZURE_DEVOPS_PAT=your-pat-here
@@ -1,31 +1,19 @@
 #!/usr/bin/env python3
-"""Monitor tree-sitter 0.25 upgrade readiness.
+"""Monitor tree-sitter 0.25 upgrade readiness — two things Dependabot can't see:

-Tracks two things Dependabot cannot see:
+  1. Peer-dep compatibility: when every grammar's *latest npm release* accepts
+     tree-sitter@0.25.0 (so we can upgrade without --legacy-peer-deps).
+  2. Vendored upstream drift: whether a vendored grammar's upstream parser.c moved.

-  1. Peer-dep compatibility. Each tree-sitter-* grammar declares a peer
-     dependency on the tree-sitter runtime. We want to know when every
-     grammar's *latest npm release* satisfies tree-sitter@0.25.0 so we
-     can upgrade without --legacy-peer-deps.
-
-  2. Vendored upstream drift. vendor/tree-sitter-proto/ is a snapshot of
-     coder3101/tree-sitter-proto's parser.c. When upstream moves, we want
-     to know whether we can pick it up.
-
-Invoked from .github/workflows/tree-sitter-upgrade-readiness.yml daily.
-Runs locally too:
-
-    python3 .github/scripts/check-tree-sitter-upgrade-readiness.py
-
-Outputs Markdown to stdout. Exit 0 when every grammar is upgrade-ready
-and the vendored proto is in sync. Exit 1 when blockers remain (the
-workflow uses this to open or update a tracking issue).
-
-No external deps -- stdlib only, so it runs on any vanilla runner.
+Invoked daily from tree-sitter-upgrade-readiness.yml; runs locally too. Outputs
+Markdown to stdout; exit 1 when blockers remain (the workflow upserts a tracking
+issue). stdlib-only — runs on any vanilla runner.
+    python3 .github/scripts/check-tree-sitter-upgrade-readiness.py [--offline | --assert-current]
 """

 from __future__ import annotations

+import http.client
 import json
 import os
 import pathlib
@@ -38,6 +26,11 @@ import urllib.request
 REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
 GITNEXUS_DIR = REPO_ROOT / "gitnexus"

+# Offline mode (--offline flag or GITNEXUS_TS_READINESS_OFFLINE=1): skip ALL network
+# so the script + tests run hermetically. npm columns render "n/a (offline)";
+# vendored ABIs are still read from the repo. The read-path mirror of --assert-current.
+OFFLINE = os.environ.get("GITNEXUS_TS_READINESS_OFFLINE", "") not in ("", "0", "false")
+
 # ── Upgrade target ──────────────────────────────────────────────────────
 # The runtime version we want to upgrade TO. Update this when the goal
 # changes (e.g. once 0.25 lands and we target 0.26).
@@ -78,15 +71,11 @@ GRAMMARS: dict[str, tuple[str, str, str]] = {
    "tree-sitter-proto":      ("coder3101/tree-sitter-proto",        "main",   "src/parser.c"),
 }

-# 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.
+# npm-installed grammars deliberately held below npm latest (surfaced so reviewers
+# can tell intentional pins from drift). Add an entry when you pin an npm grammar.
+# VENDORED grammars carry their hold in .github/vendored-grammars.json instead, so a
+# vendored grammar's hold lives in one place — tree-sitter-c's is there, not here.
 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 "
@@ -95,6 +84,56 @@ INTENTIONAL_PINS: dict[str, str] = {
 }


+def load_vendored_manifest() -> dict[str, dict]:
+    """Load the shared vendored-grammar manifest (.github/vendored-grammars.json).
+
+    The single source of truth — shared with update-vendored-grammars.mjs — for
+    which grammars are *vendored* (shipped from gitnexus/vendor/<name>, not npm)
+    and any policy ``hold`` (e.g. tree-sitter-c, #1242/#858). Membership routes a
+    grammar to the vendored branch, which reads its ABI from the repo instead of
+    node_modules (the #858 source of the old bare ``?``). Returns
+    ``{ name: {"hold": str | None} }``; upstream-drift coords stay in ``GRAMMARS``.
+    """
+    manifest_path = REPO_ROOT / ".github" / "vendored-grammars.json"
+    # Fail loud with a pointer, not a bare traceback: this runs at module import,
+    # so a missing/corrupt manifest would otherwise crash both the script and any
+    # test that imports it with an opaque FileNotFoundError/JSONDecodeError.
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise SystemExit(
+            f"vendored-grammars manifest not found at {manifest_path}. "
+            f"It is the shared source of truth for vendored grammars "
+            f"(see CONTRIBUTING.md → CI automation contracts)."
+        ) from exc
+    except json.JSONDecodeError as exc:
+        raise SystemExit(
+            f"vendored-grammars manifest at {manifest_path} is not valid JSON: {exc}."
+        ) from exc
+    out: dict[str, dict] = {}
+    for key, g in (data.get("grammars") or {}).items():
+        name = g.get("name")
+        if not name:
+            raise SystemExit(
+                f"vendored-grammars manifest entry {key!r} is missing a 'name' field "
+                f"({manifest_path})."
+            )
+        # Defense-in-depth (#2187): `name` is joined into gitnexus/vendor/<name>, so
+        # reject anything not a plain grammar name before it can traverse ("../etc").
+        if not re.fullmatch(r"tree-sitter-[a-z0-9-]+", name):
+            raise SystemExit(
+                f"vendored-grammars manifest entry {key!r} has an invalid grammar "
+                f"name {name!r} (must match tree-sitter-[a-z0-9-]+)."
+            )
+        out[name] = {"hold": g.get("hold")}
+    return out
+
+
+# Vendored set + holds, keyed by full grammar name (e.g. "tree-sitter-c").
+VENDORED: dict[str, dict] = load_vendored_manifest()
+VENDORED_NAMES: frozenset[str] = frozenset(VENDORED)
+
+
 # ── Helpers ─────────────────────────────────────────────────────────────

 def _load_package_json() -> dict:
@@ -134,12 +173,27 @@ def npm_view_json(pkg: str) -> dict | None:
    being available (it's a batch file on Windows which complicates
    subprocess calls).
    """
+    if OFFLINE:
+        return None
    url = f"https://registry.npmjs.org/{pkg}/latest"
    try:
        req = urllib.request.Request(url, headers={"Accept": "application/json"})
        with urllib.request.urlopen(req, timeout=8) as resp:
            return json.loads(resp.read().decode("utf-8"))
-    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError):
+    # OSError covers read-phase transport failures (ConnectionResetError,
+    # ssl.SSLError, socket.timeout) that escape resp.read() AFTER urlopen
+    # returns — urllib only wraps connect-phase OSErrors into URLError, so these
+    # are not URLError subclasses. http.client.IncompleteRead is an HTTPException,
+    # not an OSError, so it must be named explicitly. Returning None routes the
+    # grammar to the fetch_failed blocker bucket (a complete report) instead of
+    # crashing main() to empty stdout.
+    except (
+        urllib.error.URLError,
+        urllib.error.HTTPError,
+        OSError,
+        http.client.IncompleteRead,
+        json.JSONDecodeError,
+    ):
        return None


@@ -190,6 +244,8 @@ def fetch_text(url: str, timeout: int = 8) -> str | None:
    Adds an Authorization header for github.com URLs when GITHUB_TOKEN is
    set (raises the rate limit from 60 to 5 000 requests/hour).
    """
+    if OFFLINE:
+        return None
    headers: dict[str, str] = {}
    # Parse the URL and check the hostname rather than substring-matching
    # on the full URL string (CodeQL py/incomplete-url-substring-sanitization).
@@ -207,7 +263,16 @@ def fetch_text(url: str, timeout: int = 8) -> str | None:
        req = urllib.request.Request(url, headers=headers)
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            return resp.read().decode("utf-8", errors="ignore")
-    except (urllib.error.URLError, urllib.error.HTTPError):
+    # See npm_view_json: OSError + http.client.IncompleteRead catch read-phase
+    # transport failures that escape resp.read() and are not URLError subclasses,
+    # so a transient network blip yields None (→ fetch_failed) rather than
+    # crashing the report to empty stdout.
+    except (
+        urllib.error.URLError,
+        urllib.error.HTTPError,
+        OSError,
+        http.client.IncompleteRead,
+    ):
        return None


@@ -231,14 +296,8 @@ def md_h(text: str, level: int = 2) -> str:


 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.
-    """
+    """Return the leading sentence of a `_vendoredBy` rationale (the rest tails off
+    into install-script breadcrumbs); fall back to the whole string."""
    text = text.strip()
    match = re.search(r"\.\s+[A-Z]", text)
    return text[: match.start() + 1] if match else text
@@ -262,21 +321,26 @@ def range_includes(spec: str | None, version: str) -> bool:
    return spec.strip() == version.strip()


-def is_vendored_pin(spec: str | None) -> bool:
-    return bool(spec) and spec.startswith(("file:", "git", "http"))
+def vendored_abi_from_repo(name: str, parser_path: str) -> int | None:
+    """Read a vendored grammar's ABI directly from gitnexus/vendor/<name>.
+
+    Local-only (no network) — the offline half of ``vendored_drift_summary``,
+    factored out so the hermetic ``--assert-current`` gate can introspect vendored
+    ABIs without triggering the upstream-drift fetches it never uses (#858 review).
+    """
+    vendor_dir = GITNEXUS_DIR / "vendor" / name
+    vendored_parser = vendor_dir / parser_path
+    if not vendored_parser.is_file():
+        vendored_parser = vendor_dir / "src" / "parser.c"
+    return extract_language_version(vendored_parser)


 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.
+    """Inspect a vendored grammar under gitnexus/vendor/<name>: returns its
+    package.json ``version`` + ``_vendoredBy`` (the rationale, kept next to the
+    sources), the vendored ABI, and a comparison against upstream main.
    """
    vendor_dir = GITNEXUS_DIR / "vendor" / name
    pkg: dict = {}
@@ -290,7 +354,7 @@ def vendored_drift_summary(
    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)
+    vendored_abi = vendored_abi_from_repo(name, parser_path)

    upstream_url = (
        f"https://raw.githubusercontent.com/{upstream_repo}/"
@@ -302,10 +366,13 @@ def vendored_drift_summary(
    sha_text = fetch_text(
        f"https://api.github.com/repos/{upstream_repo}/commits/{upstream_branch}"
    )
-    upstream_sha = "?"
+    # Labeled fallback rather than a bare "?": in CI this fetch succeeds, but
+    # offline (or on a transient API miss) the report should say *why* it's
+    # blank instead of leaving a placeholder (#858).
+    upstream_sha = "unknown"
    if sha_text:
        try:
-            upstream_sha = json.loads(sha_text).get("sha", "?")[:12]
+            upstream_sha = json.loads(sha_text).get("sha", "unknown")[:12]
        except json.JSONDecodeError:
            pass

@@ -321,7 +388,9 @@ def vendored_drift_summary(

    return {
        "name": name,
-        "vendored_version": pkg.get("version", "?"),
+        # Labeled fallback, never a bare "?": a vendor package.json should always
+        # carry a version, but if one is missing the report says so plainly (#858).
+        "vendored_version": pkg.get("version") or "unknown",
        "vendored_by": pkg.get("_vendoredBy"),
        "vendored_abi": vendored_abi,
        "upstream_repo": upstream_repo,
@@ -336,27 +405,14 @@ def vendored_drift_summary(


 def assert_current() -> int:
-    """Assert every grammar's ABI is loadable by the CURRENT runtime.
-
-    Unlike the readiness report (which probes the npm registry + upstream
-    main for the *target* runtime), this mode is hermetic and offline: it
-    reads only what's checked out / installed locally and asserts each
-    grammar's compiled ABI lies within the current runtime's
-    ``RUNTIME_ABI_RANGES`` window. It is the static half of the #1922 ABI
-    gate; the runtime load-smoke (`parser-loader-abi.test.ts`) is the
-    dynamic half.
-
-    Coverage, reusing the existing helpers:
-      - npm-installed grammars: ABI from node_modules/<name>/<parser.c>.
-      - vendored grammars (dart/proto/swift): ABI via ``vendored_drift_summary``.
-      - Swift is prebuilt-only (no parser.c) → not introspectable here;
-        treated as "covered by the runtime load-smoke", not asserted.
-      - INTENTIONAL_PINS are honored: a pinned grammar is expected to sit at
-        an ABI the current runtime loads (that's *why* it's pinned), so it is
-        asserted like any other rather than skipped.
+    """Assert every grammar's compiled ABI loads on the CURRENT runtime.

+    The hermetic/offline static half of the #1922 ABI gate (the runtime
+    load-smoke is the dynamic half): reads only local files — npm ABIs from
+    node_modules/<name>, vendored ABIs from gitnexus/vendor/<name> via
+    ``vendored_abi_from_repo`` (no network). A prebuilt-only vendor (no
+    parser.c) is skipped; INTENTIONAL_PINS are asserted like any other grammar.
    Returns 0 when every introspectable grammar is in range, 1 otherwise.
-    Prints a plain-text (non-Markdown) report so CI logs stay readable.
    """
    current_runtime = read_current_runtime()
    abi_range = RUNTIME_ABI_RANGES.get(current_runtime)
@@ -380,13 +436,20 @@ def assert_current() -> int:

    for name, (upstream_repo, upstream_branch, parser_path) in sorted(GRAMMARS.items()):
        pinned_spec = pinned_versions.get(name, "—")
-        pin_note = f" [intentional pin: {pinned_spec}]" if name in INTENTIONAL_PINS else ""
+        if name in VENDORED_NAMES and VENDORED[name].get("hold"):
+            pin_note = " [vendored, held]"
+        elif name in INTENTIONAL_PINS:
+            pin_note = f" [intentional pin: {pinned_spec}]"
+        else:
+            pin_note = ""

-        if is_vendored_pin(pinned_spec):
-            v = vendored_drift_summary(name, upstream_repo, upstream_branch, parser_path)
-            abi = v["vendored_abi"]
+        # Vendored grammars: ABI read locally from the repo via vendored_abi_from_repo
+        # (NOT vendored_drift_summary, which fetches upstream — this gate is hermetic),
+        # so the offline #1922 gate covers them instead of skipping them (#858/#2187).
+        if name in VENDORED_NAMES:
+            abi = vendored_abi_from_repo(name, parser_path)
            if abi is None:
-                # Prebuilt-only vendor (e.g. tree-sitter-swift): no parser.c to
+                # Prebuilt-only vendor (e.g. a binary-only grammar): no parser.c to
                # introspect. The runtime load-smoke covers it instead.
                skipped.append(f"{name} (vendored, prebuilt — covered by load-smoke)")
                continue
@@ -453,32 +516,18 @@ def _classify_grammar(
 ) -> 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`.
+    Mutually-exclusive buckets, ordered by reviewer priority: ``fetch_failed``
+    (npm fetch failed — surfaced apart from upstream blocks), ``intentional``
+    (in INTENTIONAL_PINS), ``ready`` (npm-latest peer accepts the target),
+    ``waiting`` (a fix on main, unpublished), ``blocked`` (peer too tight on
+    both). ``bump_now`` is independent: True only when npm-latest's peer also
+    accepts our *current* runtime (else 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.
+    # Only npm-path grammars reach this function — vendored grammars are routed
+    # to the vendored branch in main() and `continue` before classification.
+    behind_latest = npm_version != "?" and not range_includes(pinned_spec, npm_version)
+    # Intentional pins are never actionable bumps (held on purpose; lifted only by
+    # editing INTENTIONAL_PINS + package.json together).
    bump_now = behind_latest and current_compat and name not in INTENTIONAL_PINS

    if fetch_failed:
@@ -496,6 +545,9 @@ def _classify_grammar(
        "name": name,
        "pinned_spec": pinned_spec or "—",
        "npm_version": npm_version,
+        # Display form for the disposition prose, laundering a "?" (a malformed 200
+        # npm response lacking `version`) so it never shows bare, like the matrix cell.
+        "npm_version_label": "unknown" if npm_version == "?" else npm_version,
        "peer_range": peer_range,
        "target_compat": target_compat,
        "current_compat": current_compat,
@@ -503,15 +555,105 @@ def _classify_grammar(
        "behind_latest": behind_latest,
        "bump_now": bump_now,
        "bucket": bucket,
-        "is_vendored": is_vendored,
    }


+def _render_vendored_section(
+    vendored_grammars: list[dict],
+    target_abi_range: tuple[int, int],
+    blockers: dict[str, str],
+) -> list[str]:
+    """Render the 'Vendored parsers' prose block. Appends any runtime-side blocker
+    (upstream ABI beyond the target range) to ``blockers`` in place; returns the
+    markdown lines (empty when nothing is vendored). Extracted from main() so that
+    function coordinates named render phases rather than inlining them (#2187)."""
+    if not vendored_grammars:
+        return []
+    # Hoisted out of the list literal below: an implicit string concatenation
+    # inside a list display trips CodeQL py/implicit-string-concatenation-in-list
+    # (it reads as a possibly-missing comma between elements).
+    intro = (
+        "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 = [md_h(f"Vendored parsers ({len(vendored_grammars)})", 2), intro, ""]
+    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]})"
+            )
+        # Never a bare "?": when upstream parser.c can't be read (generated at build,
+        # or a transient fetch miss), use the neutral `n/a` token (#858).
+        upstream_abi_str = (
+            f"ABI `{v['upstream_abi']}`" if v["upstream_abi"] is not None else "ABI `n/a`"
+        )
+        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.get("hold"):
+            lines.append(f"  - **Held:** {v['hold']}")
+        if v["vendored_by"]:
+            # First sentence only — vendor _vendoredBy fields tail off into noise.
+            lines.append(f"  - **Why vendored:** {_first_sentence(v['vendored_by'])}")
+        # Action: regen iff upstream ABI exceeds vendored AND stays within target;
+        # beyond target is a runtime-side blocker. Prebuilt-only vendors get a
+        # manual-refresh action driven by 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("")
+    return lines
+
+
 def main() -> int:
    blockers: dict[str, str] = {}
    lines: list[str] = []
+    # Label for npm/upstream values we couldn't determine: in --offline mode the
+    # fetch was deliberately skipped (not "failed"), so say so honestly.
+    miss_label = "offline" if OFFLINE else "fetch failed"
    lines.append(md_h("Tree-sitter 0.25 upgrade readiness", 1))
    lines.append("")
+    if OFFLINE:
+        lines.append(
+            "> **Offline mode** — npm registry + upstream GitHub checks were skipped. "
+            "npm-installed grammars show as unverified; vendored-grammar ABIs are read "
+            "from `gitnexus/vendor/`."
+        )
+        lines.append("")

    current_runtime = read_current_runtime()
    current_abi_range = RUNTIME_ABI_RANGES.get(current_runtime, (0, 0))
@@ -525,10 +667,9 @@ def main() -> int:
    )
    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.
+    # First pass: gather + classify per grammar. Human buckets render first, then
+    # the raw matrix in a <details> block (Status text 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 |",
@@ -540,17 +681,17 @@ def main() -> int:
    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):
+        # Vendored grammars are classified by manifest membership (NOT a file: pin
+        # heuristic — they aren't in package.json at all, the #858 misrouting bug).
+        # Their readiness is governed by the vendored ABI, read from the repo, not a
+        # peer-dep negotiation. npm-latest columns get sentinels.
+        if name in VENDORED_NAMES:
            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).
+            hold = VENDORED[name].get("hold")
+            v["hold"] = hold
+            # Three-state ABI classification: in-range, out-of-range, or
+            # not-introspectable (e.g. a prebuilt-only vendor with no parser.c).
            if v["vendored_abi"] is None:
                v["target_compat"] = True
                v["abi_state"] = "prebuilt"
@@ -567,13 +708,37 @@ def main() -> int:
                    f"vendored `{name}`: ABI {v['vendored_abi']} outside target range "
                    f"{target_abi_range[0]}..{target_abi_range[1]}"
                )
+            # A held vendored grammar (e.g. tree-sitter-c, #1242/#858) is frozen below
+            # a runtime upgrade: in-range ABI or not, keep it a blocker until the hold
+            # (from the manifest) is lifted — same treatment as npm INTENTIONAL_PINS.
+            if hold:
+                v["target_compat"] = False
+                status = "Vendored — held"
+                # Compose with any out-of-range reason rather than overwriting it:
+                # both share the blockers[name] key, and the ABI-out-of-range
+                # detail would otherwise be lost from the blockers summary.
+                hold_reason = f"vendored `{name}` held: {hold}"
+                prior = blockers.get(name)
+                blockers[name] = f"{prior}; {hold_reason}" if prior else hold_reason
+            # Cell sentinels: never emit a bare "?". A vendored grammar's ABI is
+            # the real LANGUAGE_VERSION when introspectable, else a labeled token.
+            vendored_abi_cell = (
+                str(v["vendored_abi"]) if v["vendored_abi"] is not None else "prebuilt"
+            )
+            # A None upstream ABI means the upstream parser.c couldn't be read —
+            # either it is generated at build time (e.g. swift) or the fetch
+            # missed. We can't tell which here, so use a neutral label rather
+            # than asserting "generated at build". Never a bare "?".
+            upstream_abi_cell = (
+                str(v["upstream_abi"]) if v["upstream_abi"] is not None else "n/a"
+            )
            # 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.
+            # 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} |"
+                f"{vendored_abi_cell} | {upstream_abi_cell} | {status} |"
            )
            vendored_grammars.append(v)
            continue
@@ -593,7 +758,7 @@ def main() -> int:
            peer_optional = ts_meta.get("optional", False) if peer_range else True

        if fetch_failed:
-            peer_display = "? (fetch failed)"
+            peer_display = f"n/a ({miss_label})"
            target_compat = False
            current_compat = False
        else:
@@ -609,7 +774,9 @@ def main() -> int:
            # Fallback to default location.
            installed_parser = GITNEXUS_DIR / "node_modules" / name / "src" / "parser.c"
        installed_abi = extract_language_version(installed_parser)
-        abi_display = str(installed_abi) if installed_abi else "?"
+        # Labeled sentinel, never a bare "?": CI's `npm ci` populates node_modules,
+        # but if it's absent say so plainly rather than leaving a placeholder (#858).
+        abi_display = str(installed_abi) if installed_abi else "n/a (not installed)"

        # Check upstream (main/master branch) ABI for unreleased work.
        upstream_url = (
@@ -618,23 +785,19 @@ def main() -> int:
        )
        upstream_text = fetch_text(upstream_url)
        upstream_abi = extract_abi_from_text(upstream_text) if upstream_text else None
-        upstream_abi_display = str(upstream_abi) if upstream_abi else "?"
+        upstream_abi_display = str(upstream_abi) if upstream_abi else "n/a"

        # 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"
+            status = f"Unknown ({miss_label})"
+            reason = "checks skipped (offline)" if OFFLINE else "npm registry fetch failed"
+            blockers[name] = f"`{name}`: {reason} — could not verify peer dep"
        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.
+            # A held-back grammar: treated as a blocker until the pin is lifted
+            # (entry removed from INTENTIONAL_PINS), then reclassified next run.
            status = "Intentionally pinned"
            blockers[name] = (
                f"`{name}` intentionally pinned at `{pinned_spec}` "
@@ -675,8 +838,11 @@ def main() -> int:

        pinned_spec = pinned_versions.get(name, "—")
        compat_icon = "Yes" if target_compat else "**No**"
+        # "?" stays the internal fetch-failed sentinel (compared above); render a
+        # labeled token in the matrix so the report never shows a bare "?" (#858).
+        npm_version_cell = f"n/a ({miss_label})" if npm_version == "?" else npm_version
        raw_matrix.append(
-            f"| `{name}` | {pinned_spec} | {npm_version} | {peer_display} | "
+            f"| `{name}` | {pinned_spec} | {npm_version_cell} | {peer_display} | "
            f"{compat_icon} | {abi_display} | {upstream_abi_display} | {status} |"
        )

@@ -726,7 +892,8 @@ def main() -> int:
    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)")
+        why = "checks skipped in offline mode" if OFFLINE else "npm registry unreachable"
+        lines.append(f"- {len(by_bucket['fetch_failed'])} could not be checked ({why})")
    if bump_now:
        lines.append(
            f"- **{len(bump_now)} bump candidate(s) you can take TODAY** (npm-latest "
@@ -745,7 +912,7 @@ def main() -> int:
        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"- `{r['name']}`: `{r['pinned_spec']}` → `{r['npm_version_label']}` "
                f"(peer `{r['peer_range'] or 'none'}`)"
            )
        lines.append("")
@@ -768,7 +935,7 @@ def main() -> int:
        "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']}`"
+            f"- `{r['name']}` — pinned `{r['pinned_spec']}`, npm latest `{r['npm_version_label']}`"
            + ("  _(also a bump candidate — see above)_" if r["bump_now"] else "")
        ),
    )
@@ -784,7 +951,7 @@ def main() -> int:
            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}"
+                f"(npm latest `{r['npm_version_label']}`)\n  {reason}"
            )
        lines.append("")

@@ -794,7 +961,7 @@ def main() -> int:
        "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['name']}@{r['npm_version_label']}` — peer `{r['peer_range'] or 'none'}`. "
            f"_{r['upstream_progress']}_"
        ),
    )
@@ -804,90 +971,23 @@ def main() -> int:
        "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 "")
-        ),
+        lambda r: f"- `{r['name']}@{r['npm_version_label']}` — peer `{r['peer_range'] or 'none'}`",
    )

    _emit_bucket(
        "Could not check",
-        "npm registry fetch failed for these grammars. Re-run the workflow to retry.",
+        (
+            "Checks were skipped because the report ran in `--offline` mode. "
+            "Re-run online to verify these grammars."
+            if OFFLINE
+            else "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("")
+    lines.extend(_render_vendored_section(vendored_grammars, target_abi_range, blockers))

    # ── Raw matrix (for completeness + workflow row-diff) ────────────
    lines.append(md_h("Full grammar matrix", 2))
@@ -911,6 +1011,11 @@ if __name__ == "__main__":
        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
    except Exception:
        pass
+    # `--offline` skips all network so the readiness report renders hermetically
+    # (vendored ABIs from the repo; npm columns marked unverified). Useful for
+    # air-gapped runs and deterministic tests.
+    if "--offline" in sys.argv[1:]:
+        OFFLINE = True
    # `--assert-current` is the offline CI gate (#1922): assert every grammar's
    # ABI loads on the CURRENT runtime. Bare invocation keeps the original
    # target-runtime readiness report behaviour.
@@ -0,0 +1,474 @@
+#!/usr/bin/env python3
+"""Tests for check-tree-sitter-upgrade-readiness.py.
+
+Stdlib-only (``unittest`` + ``unittest.mock``) to match the script under test,
+which is deliberately dependency-free so it runs on any vanilla runner. Run with:
+
+    python3 -m unittest .github/scripts/test_check_tree_sitter_upgrade_readiness.py
+
+(pytest also discovers ``unittest.TestCase`` classes, so a future pytest CI job
+picks these up unchanged.)
+
+These tests lock in the #858 fix: the 5 vendored grammars
+(c/swift/kotlin/dart/proto) are classified from the shared manifest
+(.github/vendored-grammars.json), their ABI is read from gitnexus/vendor/<name>,
+and the report never renders a bare ``?`` placeholder. All network is mocked.
+"""
+from __future__ import annotations
+
+import contextlib
+import http.client
+import importlib.util
+import io
+import json
+import pathlib
+import re
+from unittest import TestCase, main, mock
+
+# ── Load the hyphenated script as a module ───────────────────────────────
+_SCRIPTS_DIR = pathlib.Path(__file__).resolve().parent
+_SCRIPT = _SCRIPTS_DIR / "check-tree-sitter-upgrade-readiness.py"
+_REPO_ROOT = _SCRIPTS_DIR.parents[1]
+_MANIFEST = _REPO_ROOT / ".github" / "vendored-grammars.json"
+
+_spec = importlib.util.spec_from_file_location("readiness_under_test", _SCRIPT)
+readiness = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(readiness)  # type: ignore[union-attr]
+
+# The exact row-diff regex the workflow's change-detection bot uses
+# (.github/workflows/tree-sitter-upgrade-readiness.yml) — byte-identical so a matrix
+# format change that would silently break change-detection fails here. Group 2 is
+# ONLY the Status cell ([^|]+? before the final `|$`).
+_ROW_DIFF_RE = re.compile(r"\| `(tree-sitter-[^`]+)` \|.*\| ([^|]+?) \|$", re.M)
+# Mirrors the scheduled issue-update summary extraction in
+# tree-sitter-upgrade-readiness.yml. If the report prose changes again, the issue
+# comment should not silently degrade to "?/? ready. ? blocker(s)".
+_ISSUE_READY_RE = re.compile(
+    r"- (\d+)/(\d+) npm-installed grammars already accept tree-sitter@"
+)
+_ISSUE_BLOCKER_RE = re.compile(r"\*\*Blocked\*\* — (\d+) grammars? ")
+
+
+def _physical_vendor_grammars() -> set[str]:
+    vendor = _REPO_ROOT / "gitnexus" / "vendor"
+    return {
+        p.name
+        for p in vendor.iterdir()
+        if p.is_dir() and p.name.startswith("tree-sitter-")
+    }
+
+
+def _render_report() -> tuple[str, int]:
+    """Run main() with network mocked to mirror PRODUCTION; return (md, exit_code).
+
+    - npm grammars resolve to a permissive "Ready" peer dep, so the ONLY blocker
+      left is the held vendored tree-sitter-c — letting us assert the hold is
+      load-bearing (exit code stays non-zero because of it).
+    - npm_view_json records its calls so we can prove vendored grammars are never
+      npm-queried.
+    - fetch_text mirrors the real workflow: upstream parser.c resolves to a real
+      ABI (committed upstream), commit endpoints return a sha — EXCEPT swift's
+      upstream, whose parser.c is generated at build time and so is unreachable
+      (None). That single miss exercises the labeled-sentinel path; every other
+      cell must be a real value, never a bare '?'.
+    """
+    npm_calls: list[str] = []
+
+    def fake_npm_view_json(pkg: str):
+        npm_calls.append(pkg)
+        return {"version": "9.9.9", "peerDependencies": {"tree-sitter": "^0.25.0"}}
+
+    def fake_fetch_text(url: str, timeout: int = 8):
+        if "parser.c" in url:
+            # swift's upstream parser.c is generated at build time → unreachable;
+            # the others ship a committed parser.c.
+            if "alex-pinkus" in url:
+                return None
+            return "#define LANGUAGE_VERSION 14\n#define STATE_COUNT 1\n"
+        if "/commits/" in url:
+            return json.dumps({"sha": "0123456789abcdef"})
+        # package.json (relaxed-peer probe) etc. — not needed for these assertions.
+        return None
+
+    buf = io.StringIO()
+    with mock.patch.object(readiness, "npm_view_json", side_effect=fake_npm_view_json), \
+         mock.patch.object(readiness, "fetch_text", side_effect=fake_fetch_text), \
+         contextlib.redirect_stdout(buf):
+        code = readiness.main()
+    report = buf.getvalue()
+    _render_report.last_npm_calls = npm_calls  # type: ignore[attr-defined]
+    return report, code
+
+
+class ManifestClassification(TestCase):
+    def test_manifest_matches_physical_vendor_dirs(self):
+        """Consistency guard: the manifest set == the gitnexus/vendor/tree-sitter-*
+        dirs. Vendoring a grammar without a manifest entry (or vice-versa) fails —
+        this is what keeps the two tree-sitter workflows aligned (#858)."""
+        manifest_names = {
+            g["name"]
+            for g in json.loads(_MANIFEST.read_text())["grammars"].values()
+        }
+        self.assertEqual(manifest_names, _physical_vendor_grammars())
+
+    def test_vendored_names_loaded_from_manifest(self):
+        self.assertEqual(set(readiness.VENDORED_NAMES), _physical_vendor_grammars())
+        # npm-installed grammars must NOT be classified vendored.
+        self.assertNotIn("tree-sitter-cpp", readiness.VENDORED_NAMES)
+        self.assertNotIn("tree-sitter-go", readiness.VENDORED_NAMES)
+
+    def test_c_carries_a_hold_cpp_does_not(self):
+        self.assertTrue(readiness.VENDORED["tree-sitter-c"]["hold"])
+        self.assertNotIn("tree-sitter-c", readiness.INTENTIONAL_PINS)
+        # cpp stays an npm intentional pin.
+        self.assertIn("tree-sitter-cpp", readiness.INTENTIONAL_PINS)
+
+    def test_vendored_names_are_a_subset_of_GRAMMARS(self):
+        # The report + --assert-current iterate the hardcoded GRAMMARS dict for
+        # upstream-drift coords. A vendored grammar present in the manifest but
+        # missing from GRAMMARS would be silently dropped from both — re-creating
+        # the cross-workflow divergence the manifest exists to kill (#858). Guard it.
+        missing = set(readiness.VENDORED_NAMES) - set(readiness.GRAMMARS)
+        self.assertEqual(missing, set(), f"manifest grammars missing from GRAMMARS: {missing}")
+
+    def test_missing_manifest_raises_a_clear_error(self):
+        import pathlib
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as d:
+            with mock.patch.object(readiness, "REPO_ROOT", pathlib.Path(d)):
+                with self.assertRaises(SystemExit) as ctx:
+                    readiness.load_vendored_manifest()
+        self.assertIn("vendored-grammars manifest", str(ctx.exception))
+
+    def test_malformed_manifest_raises_a_clear_error(self):
+        import pathlib
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as d:
+            gh = pathlib.Path(d) / ".github"
+            gh.mkdir()
+            (gh / "vendored-grammars.json").write_text("{ not valid json", encoding="utf-8")
+            with mock.patch.object(readiness, "REPO_ROOT", pathlib.Path(d)):
+                with self.assertRaises(SystemExit) as ctx:
+                    readiness.load_vendored_manifest()
+        self.assertIn("not valid JSON", str(ctx.exception))
+
+    def test_path_traversal_grammar_name_is_rejected(self):
+        import pathlib
+        import tempfile
+
+        bad = '{"grammars": {"evil": {"name": "../etc"}}}'
+        with tempfile.TemporaryDirectory() as d:
+            gh = pathlib.Path(d) / ".github"
+            gh.mkdir()
+            (gh / "vendored-grammars.json").write_text(bad, encoding="utf-8")
+            with mock.patch.object(readiness, "REPO_ROOT", pathlib.Path(d)):
+                with self.assertRaises(SystemExit) as ctx:
+                    readiness.load_vendored_manifest()
+        self.assertIn("invalid grammar name", str(ctx.exception))
+
+
+class AssertCurrent(TestCase):
+    """The offline #1922 ABI gate (--assert-current) must stay hermetic — it reads
+    vendored ABIs from the repo, never the network. (Regression guard: a prior
+    revision routed vendored grammars through vendored_drift_summary, which fetches
+    upstream parser.c + commit sha, silently breaking the 'hermetic and offline'
+    contract — #858 review.)"""
+
+    def _run_assert_current(self):
+        import urllib.request
+
+        def explode(*a, **k):
+            raise AssertionError("--assert-current attempted a network call")
+
+        buf = io.StringIO()
+        with mock.patch.object(urllib.request, "urlopen", side_effect=explode), \
+             contextlib.redirect_stdout(buf):
+            code = readiness.assert_current()
+        return buf.getvalue(), code
+
+    def test_assert_current_is_network_free_and_passes(self):
+        report, code = self._run_assert_current()  # raises if any urlopen fires
+        self.assertEqual(code, 0)
+        # All 5 vendored grammars are introspected from the repo (ABI 14), not skipped.
+        for name in readiness.VENDORED_NAMES:
+            self.assertIn(f"{name}: vendored ABI", report)
+
+    def test_assert_current_fails_an_out_of_range_vendored_abi(self):
+        # vendored_abi_from_repo is the local-read injection point: force one
+        # grammar out of the current runtime's ABI window and assert the gate trips.
+        real = readiness.vendored_abi_from_repo
+
+        def fake(name, parser_path):
+            return 99 if name == "tree-sitter-dart" else real(name, parser_path)
+
+        import urllib.request
+        buf = io.StringIO()
+        with mock.patch.object(readiness, "vendored_abi_from_repo", side_effect=fake), \
+             mock.patch.object(urllib.request, "urlopen", side_effect=AssertionError("network")), \
+             contextlib.redirect_stdout(buf):
+            code = readiness.assert_current()
+        self.assertEqual(code, 1)
+        self.assertIn("tree-sitter-dart", buf.getvalue())
+        self.assertIn("outside current runtime range", buf.getvalue())
+
+
+class FetchHelperReadPhaseErrors(TestCase):
+    """Read-phase transport failures — raised by resp.read() AFTER urlopen has
+    returned (ConnectionResetError, ssl.SSLError, socket.timeout,
+    http.client.IncompleteRead) — are NOT urllib.error.URLError subclasses
+    (urllib only wraps connect-phase OSErrors). A prior revision's narrow except
+    tuple let them escape npm_view_json / fetch_text, crash main(), and empty
+    stdout — which makes the workflow's requireMatch throw on a non-drift
+    scheduled run. The helpers must swallow them to None so the grammar routes to
+    the fetch_failed blocker bucket and the report still renders completely."""
+
+    @staticmethod
+    def _patch_urlopen(*, read_returns=None, read_raises=None):
+        class _Resp:
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *exc):
+                return False
+
+            def read(self, *a, **k):
+                if read_raises is not None:
+                    raise read_raises
+                return read_returns
+
+        def _fake_urlopen(*a, **k):
+            return _Resp()
+
+        import urllib.request
+
+        return mock.patch.object(urllib.request, "urlopen", side_effect=_fake_urlopen)
+
+    def test_npm_view_json_swallows_read_phase_connection_reset(self):
+        # ConnectionResetError is an OSError but NOT a URLError — the broadened
+        # OSError clause must catch it so the helper returns None, not raises.
+        with mock.patch.object(readiness, "OFFLINE", False), self._patch_urlopen(
+            read_raises=ConnectionResetError("peer reset mid-body")
+        ):
+            self.assertIsNone(readiness.npm_view_json("tree-sitter-anything"))
+
+    def test_fetch_text_swallows_read_phase_incomplete_read(self):
+        # http.client.IncompleteRead is an HTTPException (not OSError), so it must
+        # be named explicitly in the except tuple.
+        with mock.patch.object(readiness, "OFFLINE", False), self._patch_urlopen(
+            read_raises=http.client.IncompleteRead(partial=b"half")
+        ):
+            self.assertIsNone(readiness.fetch_text("https://example.com/parser.c"))
+
+    def test_npm_view_json_still_swallows_bad_json(self):
+        # JSONDecodeError is a ValueError, not an OSError — broadening the tuple
+        # must not drop it. Non-JSON body still yields None.
+        with mock.patch.object(readiness, "OFFLINE", False), self._patch_urlopen(
+            read_returns=b"<<not json>>"
+        ):
+            self.assertIsNone(readiness.npm_view_json("tree-sitter-anything"))
+
+
+class ReportRendering(TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.report, cls.code = _render_report()
+        cls.rows = dict(_ROW_DIFF_RE.findall(cls.report))
+
+    def test_no_bare_question_mark_anywhere(self):
+        # The only legitimate '?' is the "Satisfies 0.25?" column header.
+        sanitized = self.report.replace("Satisfies 0.25?", "Satisfies 0.25")
+        self.assertNotIn("?", sanitized, "report still contains a bare '?' placeholder")
+
+    def test_malformed_npm_version_renders_unknown_in_prose_not_bare_question(self):
+        # A successful (200) npm /latest response that omits `version` leaves
+        # npm_version == "?"; the grammar is still bucketed (fetch did not fail), so
+        # its disposition PROSE line must show the labeled sentinel, never a bare '?'.
+        def fake_npm(pkg: str):
+            if pkg == "tree-sitter-go":
+                return {"peerDependencies": {"tree-sitter": "^0.25.0"}}  # no 'version'
+            return {"version": "9.9.9", "peerDependencies": {"tree-sitter": "^0.25.0"}}
+
+        def fake_fetch(url: str, timeout: int = 8):
+            if "parser.c" in url and "alex-pinkus" not in url:
+                return "#define LANGUAGE_VERSION 14\n"
+            if "/commits/" in url:
+                return json.dumps({"sha": "0123456789abcdef"})
+            return None
+
+        buf = io.StringIO()
+        with mock.patch.object(readiness, "npm_view_json", side_effect=fake_npm), \
+             mock.patch.object(readiness, "fetch_text", side_effect=fake_fetch), \
+             contextlib.redirect_stdout(buf):
+            readiness.main()
+        report = buf.getvalue()
+        sanitized = report.replace("Satisfies 0.25?", "Satisfies 0.25")
+        self.assertNotIn("?", sanitized)
+        # The Ready bucket prose line for go shows the labeled 'unknown', not '?'.
+        self.assertRegex(report, r"`tree-sitter-go`.*npm latest `unknown`")
+
+    def test_every_vendored_grammar_shows_numeric_abi_not_question_mark(self):
+        for name in readiness.VENDORED_NAMES:
+            row = self._matrix_row(name)
+            cells = [c.strip() for c in row.strip().strip("|").split("|")]
+            abi_cell = cells[5]  # Grammar|Pinned|npm|Peer|Satisfies|ABI|UpstreamABI|Status
+            self.assertRegex(
+                abi_cell, r"^\d+$",
+                f"{name} ABI cell is '{abi_cell}', expected a number (read from vendor/)",
+            )
+
+    def test_proto_is_never_npm_queried(self):
+        # github-only vendored grammars must skip the npm peer-dep path entirely,
+        # which is what removes the old "? (fetch failed)" for tree-sitter-proto.
+        self.assertNotIn("tree-sitter-proto", _render_report.last_npm_calls)
+        self.assertNotIn("tree-sitter-dart", _render_report.last_npm_calls)
+        self.assertNotIn("Could not check", self.report)
+        self.assertNotIn("fetch failed", self.report)
+
+    def test_held_c_renders_held_and_keeps_exit_nonzero(self):
+        # Status is the last matrix cell (the row-diff regex captures the whole
+        # tail, not just status, so read the cell directly).
+        cells = [c.strip() for c in self._matrix_row("tree-sitter-c").strip().strip("|").split("|")]
+        self.assertEqual(cells[-1], "Vendored — held")
+        self.assertIn("**Held:**", self.report)
+        # With every npm grammar mocked to "Ready", the ONLY remaining blocker is
+        # the held c — so a non-zero exit proves the hold is treated as a blocker.
+        self.assertEqual(self.code, 1)
+
+    def test_upstream_abi_miss_uses_labeled_sentinel(self):
+        # swift's upstream parser.c is unreachable (mocked None), so its
+        # upstream-ABI cell is the labeled 'n/a' token, never a bare '?'.
+        cells = [c.strip() for c in self._matrix_row("tree-sitter-swift").strip().strip("|").split("|")]
+        self.assertEqual(cells[6], "n/a")  # Upstream ABI column
+
+    def test_row_diff_regex_captures_all_fifteen_grammar_statuses(self):
+        # The change-detection bot keys on this regex: group 1 = grammar name,
+        # group 2 = the Status cell ONLY (not the whole tail). It must match every
+        # row after the format change so status transitions keep being detected.
+        self.assertEqual(len(self.rows), 15)
+        for name in readiness.VENDORED_NAMES:
+            self.assertIn(name, self.rows)
+        # group 2 is the Status cell — held c renders exactly "Vendored — held",
+        # and no captured status contains a pipe (proves cell-scoped capture).
+        self.assertEqual(self.rows["tree-sitter-c"], "Vendored — held")
+        for status in self.rows.values():
+            self.assertNotIn("|", status)
+
+    def test_issue_update_summary_regex_matches_current_report(self):
+        ready = _ISSUE_READY_RE.search(self.report)
+        blockers = _ISSUE_BLOCKER_RE.search(self.report)
+        self.assertIsNotNone(ready)
+        self.assertIsNotNone(blockers)
+        # Counts are derived from _render_report()'s mock corpus (all npm peer
+        # deps mocked permissive): of the 10 npm-installed grammars, 9 render
+        # Ready and 1 — tree-sitter-cpp — is the intentional pin (#1242), so it is
+        # not counted ready. The 2 blockers are that same pinned tree-sitter-cpp
+        # plus the vendored, ABI-held tree-sitter-c (the only out-of-range
+        # vendored grammar). If a grammar is added/removed or a pin/hold changes,
+        # update _render_report()'s mock AND these expected counts together; a
+        # mismatch here means the report prose drifted, not the regex.
+        self.assertEqual(ready.groups(), ("9", "10"))
+        self.assertEqual(blockers.group(1), "2")
+
+    def _matrix_row(self, name: str) -> str:
+        for line in self.report.splitlines():
+            if line.startswith(f"| `{name}` |"):
+                return line
+        # Explicit terminating raise (not self.fail, which CodeQL doesn't model as
+        # NoReturn) so the function has no implicit fall-through return (CodeQL 754).
+        raise AssertionError(f"no matrix row for {name}")
+
+
+class OfflineMode(TestCase):
+    """--offline must render the report touching ZERO network — vendored ABIs come
+    from the repo, npm columns are marked unverified. This is what makes the
+    network-dependent report deterministically testable in air-gapped CI."""
+
+    def _render_offline(self):
+        import urllib.request
+
+        def explode(*a, **k):
+            raise AssertionError("network call attempted in --offline mode")
+
+        buf = io.StringIO()
+        with mock.patch.object(readiness, "OFFLINE", True), \
+             mock.patch.object(urllib.request, "urlopen", side_effect=explode), \
+             contextlib.redirect_stdout(buf):
+            code = readiness.main()
+        return buf.getvalue(), code
+
+    def test_offline_touches_no_network_and_still_renders(self):
+        report, code = self._render_offline()  # raises if any urlopen fires
+        self.assertIn("Offline mode", report)
+        # Vendored grammars are introspected from the repo → real ABI 14, not a miss.
+        for name in readiness.VENDORED_NAMES:
+            row = next(l for l in report.splitlines() if l.startswith(f"| `{name}` |"))
+            cells = [c.strip() for c in row.strip().strip("|").split("|")]
+            self.assertRegex(cells[5], r"^\d+$", f"{name} vendored ABI missing offline")
+
+    def test_offline_marks_npm_grammars_offline_not_fetch_failed(self):
+        report, _ = self._render_offline()
+        self.assertIn("(offline)", report)
+        self.assertNotIn("fetch failed", report)  # honest: skipped, not failed
+
+    def test_offline_report_has_no_bare_question_mark(self):
+        report, _ = self._render_offline()
+        sanitized = report.replace("Satisfies 0.25?", "Satisfies 0.25")
+        self.assertNotIn("?", sanitized)
+
+
+class VendoredAbiBranches(TestCase):
+    """main()'s vendored-ABI classification reads through vendored_abi_from_repo
+    (the same local-read seam --assert-current uses), so a single patch drives the
+    out-of-range and prebuilt-only branches that no real vendor dir can trigger
+    today (all ship parser.c at ABI 14)."""
+
+    def _render_with_vendored_abi(self, override):
+        """Render main() with the standard production-faithful network mock plus a
+        vendored_abi_from_repo override (dict: name -> int|None; others read real)."""
+        real = readiness.vendored_abi_from_repo
+
+        def abi_seam(name, parser_path):
+            return override[name] if name in override else real(name, parser_path)
+
+        def fake_npm(pkg):
+            return {"version": "9.9.9", "peerDependencies": {"tree-sitter": "^0.25.0"}}
+
+        def fake_fetch(url, timeout=8):
+            if "parser.c" in url and "alex-pinkus" not in url:
+                return "#define LANGUAGE_VERSION 14\n"
+            if "/commits/" in url:
+                return json.dumps({"sha": "0123456789abcdef"})
+            return None
+
+        buf = io.StringIO()
+        with mock.patch.object(readiness, "vendored_abi_from_repo", side_effect=abi_seam), \
+             mock.patch.object(readiness, "npm_view_json", side_effect=fake_npm), \
+             mock.patch.object(readiness, "fetch_text", side_effect=fake_fetch), \
+             contextlib.redirect_stdout(buf):
+            code = readiness.main()
+        return buf.getvalue(), code
+
+    def _row(self, report, name):
+        line = next(l for l in report.splitlines() if l.startswith(f"| `{name}` |"))
+        return [c.strip() for c in line.strip().strip("|").split("|")]
+
+    def test_out_of_range_vendored_abi_is_a_blocker(self):
+        # Force tree-sitter-dart's vendored ABI outside the target range (13–15).
+        report, code = self._render_with_vendored_abi({"tree-sitter-dart": 99})
+        cells = self._row(report, "tree-sitter-dart")
+        self.assertEqual(cells[-1], "Vendored (ABI out of range)")
+        self.assertEqual(cells[5], "99")
+        self.assertEqual(code, 1)  # out-of-range vendored grammar is a blocker
+
+    def test_prebuilt_only_vendored_abi_renders_prebuilt_not_question(self):
+        # vendored_abi None (a future binary-only vendor with no parser.c).
+        report, _ = self._render_with_vendored_abi({"tree-sitter-dart": None})
+        cells = self._row(report, "tree-sitter-dart")
+        self.assertEqual(cells[5], "prebuilt")  # labeled, never a bare '?'
+        self.assertEqual(cells[4], "Yes")  # prebuilt is assumed target-compatible
+
+
+if __name__ == "__main__":
+    main()
@@ -42,17 +42,52 @@ const COMPATIBLE_ABI = new Set([13, 14]); // tree-sitter@0.21.1 LANGUAGE_VERSION
 // github grammars (no usable npm release) track the default branch HEAD. A `hold`
 // reason makes a grammar report-only: updates are detected + surfaced but never
 // auto-applied (c is ABI-pinned and must not move without a runtime upgrade).
-const GRAMMARS = {
-  c: {
-    name: 'tree-sitter-c',
-    npm: 'tree-sitter-c',
-    hold: 'ABI-pinned at 0.21.4 (#1242/#858) — needs a tree-sitter runtime upgrade before bumping',
-  },
-  swift: { name: 'tree-sitter-swift', npm: 'tree-sitter-swift' },
-  kotlin: { name: 'tree-sitter-kotlin', npm: 'tree-sitter-kotlin' },
-  dart: { name: 'tree-sitter-dart', github: 'UserNobody14/tree-sitter-dart' },
-  proto: { name: 'tree-sitter-proto', github: 'coder3101/tree-sitter-proto' },
-};
+//
+// The vendored set lives in .github/vendored-grammars.json — the SHARED source of
+// truth this monitor and .github/scripts/check-tree-sitter-upgrade-readiness.py both
+// read, so the two tree-sitter workflows can never disagree about which grammars are
+// vendored or where their upstream lives. We reshape the manifest's
+// `{ upstream: { npm | github } }` form into the flat `{ npm? , github? }` shape the
+// rest of this script consumes. This is a local file read (import-safe, no network).
+const MANIFEST = path.join(REPO_ROOT, '.github', 'vendored-grammars.json');
+// `raw` is injectable for testing; production reads the manifest file.
+function loadManifestGrammars(raw = null) {
+  if (raw === null) {
+    // Fail loud with a pointer, not a bare ENOENT/SyntaxError: this runs at import.
+    try {
+      raw = JSON.parse(fs.readFileSync(MANIFEST, 'utf8'));
+    } catch (e) {
+      throw new Error(
+        `Could not load the vendored-grammars manifest at ${MANIFEST} ` +
+          `(shared source of truth — see CONTRIBUTING.md → CI automation contracts): ${e.message}`,
+      );
+    }
+  }
+  return Object.fromEntries(
+    Object.entries(raw.grammars || {}).map(([key, g]) => {
+      if (!g.name)
+        throw new Error(`manifest entry '${key}' is missing a 'name' field (${MANIFEST})`);
+      // Defense-in-depth: `name` is joined into gitnexus/vendor/<name> paths (and
+      // apply() WRITES there), so reject anything that isn't a plain grammar name
+      // before it can traverse the filesystem (#2187).
+      if (!/^tree-sitter-[a-z0-9-]+$/.test(g.name))
+        throw new Error(
+          `manifest entry '${key}' has an invalid grammar name '${g.name}' ` +
+            `(must match tree-sitter-[a-z0-9-]+)`,
+        );
+      return [
+        key,
+        {
+          name: g.name,
+          ...(g.upstream?.npm ? { npm: g.upstream.npm } : {}),
+          ...(g.upstream?.github ? { github: g.upstream.github } : {}),
+          ...(g.hold ? { hold: g.hold } : {}),
+        },
+      ];
+    }),
+  );
+}
+const GRAMMARS = loadManifestGrammars();

 const sh = (cmd, args, opts = {}) =>
  execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts }).trim();
@@ -62,6 +97,26 @@ const clean = (v) =>
    .replace(/^[v^~]/, '')
    .trim();

+// Shared "is the candidate newer than what we ship?" check, used by BOTH detect()
+// and apply() so they can never disagree. up.version is the comparable identity for
+// both kinds: a plain semver for npm, and the `<base>-g<sha7>` provenance string for
+// github (which apply() also writes to package.json). detect() previously compared
+// the bare sha7 for github, so after the bot re-vendored a github grammar once it
+// reported a perpetual false "update available" while apply() saw "already current"
+// (#2187 review). Comparing up.version on both sides removes that asymmetry.
+const isNewer = (up, have) => !have || up.version !== have;
+
+// apply() throws this (instead of calling process.exit) so its error branches are
+// exercisable in-process by tests; the CLI entrypoint maps `.code` back to the
+// original exit code, keeping the monitor's subprocess contract identical (#2187).
+class ApplyExit extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'ApplyExit';
+    this.code = code;
+  }
+}
+
 function vendoredVersion(g) {
  const p = path.join(VENDOR, g.name, 'package.json');
  return clean(JSON.parse(fs.readFileSync(p, 'utf8')).version);
@@ -136,22 +191,30 @@ function readAbi(srcRoot) {
  return null; // unknown (e.g. parser.c only generated at build time)
 }

-function detect() {
+// `deps` injects the network/filesystem seams (vendoredVersion / resolveUpstream /
+// fetchSource / readAbi) so the classification logic — newer-detection, the ABI
+// gate, and the policy-hold gate — can be unit-tested offline with fixtures, never
+// touching live npm/GitHub. Production passes nothing and gets the real functions.
+function detect(deps = {}) {
+  const getVendored = deps.vendoredVersion || vendoredVersion;
+  const resolveUp = deps.resolveUpstream || resolveUpstream;
+  const fetchSrc = deps.fetchSource || fetchSource;
+  const readAbiFn = deps.readAbi || readAbi;
  const report = [];
  for (const [key, g] of Object.entries(GRAMMARS)) {
-    const have = vendoredVersion(g);
+    const have = getVendored(g);
    let up;
    try {
-      up = resolveUpstream(g);
+      up = resolveUp(g);
    } catch (err) {
      report.push({ grammar: key, error: String(err.message || err) });
      continue;
    }
-    const newer = up.kind === 'npm' ? up.version !== have : !have || up.ref.slice(0, 7) !== have;
+    const newer = isNewer(up, have);
    let abi = null;
    if (newer) {
      try {
-        abi = readAbi(fetchSource(g, up.ref));
+        abi = readAbiFn(fetchSrc(g, up.ref));
      } catch {
        /* fetch/abi best-effort; null = unknown */
      }
@@ -190,34 +253,48 @@ const copyFile = (srcRoot, dest, rel) => {
 * notice), LICENSE, and prebuilds/ (the build workflow refreshes those). Bumps the
 * stripped vendor package.json version + provenance — never re-introduces
 * scripts/dependencies (#836/#1728). Returns the new version.
+ *
+ * opts.dryRun resolves + ABI-validates the candidate but writes NOTHING — it logs
+ * what it would re-vendor and returns the version, so the flow can be rehearsed
+ * (locally or in CI) without mutating gitnexus/vendor/. opts.deps injects the
+ * network/fs seams for offline testing (same shape as detect()).
 */
-function apply(key) {
+function apply(key, opts = {}) {
+  const dryRun = opts.dryRun || false;
+  const deps = opts.deps || {};
+  const getVendored = deps.vendoredVersion || vendoredVersion;
+  const resolveUp = deps.resolveUpstream || resolveUpstream;
+  const fetchSrc = deps.fetchSource || fetchSource;
+  const readAbiFn = deps.readAbi || readAbi;
  const g = GRAMMARS[key];
-  if (!g) {
-    console.error(`unknown grammar '${key}'`);
-    process.exit(2);
-  }
-  if (g.hold) {
-    console.error(
+  if (!g) throw new ApplyExit(`unknown grammar '${key}'`, 2);
+  if (g.hold)
+    throw new ApplyExit(
      `${key}: report-only (${g.hold}); not auto-applied. Re-vendor manually if intended.`,
+      3,
    );
-    process.exit(3);
-  }
-  const have = vendoredVersion(g);
-  const up = resolveUpstream(g);
-  const newer = up.kind === 'npm' ? up.version !== have : !have || up.version !== have;
+  const have = getVendored(g);
+  const up = resolveUp(g);
+  const newer = isNewer(up, have);
  if (!newer) {
+    // Already current: nothing to apply. Return (exit 0 via the CLI) — NOT an error.
    console.error(`${key}: already current (${have}); nothing to apply.`);
-    process.exit(0);
+    return have;
  }
-  const srcRoot = fetchSource(g, up.ref);
-  const abi = readAbi(srcRoot);
-  if (abi == null || !COMPATIBLE_ABI.has(abi)) {
-    console.error(
+  const srcRoot = fetchSrc(g, up.ref);
+  const abi = readAbiFn(srcRoot);
+  if (abi == null || !COMPATIBLE_ABI.has(abi))
+    throw new ApplyExit(
      `${key}: candidate ${up.version} is ABI ${abi ?? 'unknown'} — not tree-sitter@0.21.1 ` +
        `compatible (need 13/14); refusing to re-vendor. Handle manually.`,
+      3,
    );
-    process.exit(3);
+
+  if (dryRun) {
+    console.log(
+      `${key}: [dry-run] would re-vendor ${g.name} → ${up.version} (ABI ${abi}); no files written.`,
+    );
+    return up.version;
  }

  const dest = path.join(VENDOR, g.name);
@@ -256,11 +333,31 @@ function apply(key) {
 // makes live network calls, so importing must be side-effect-free.
 const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isMain) {
-  if (process.argv[2] === '--apply') {
-    apply(process.argv[3]);
+  const args = process.argv.slice(2);
+  const dryRun = args.includes('--dry-run');
+  if (args[0] === '--apply') {
+    // `--apply <grammar> [--dry-run]` — --dry-run previews without writing.
+    // Map apply()'s thrown ApplyExit back to the original exit codes (0/2/3) so
+    // the monitor workflow's subprocess (which only distinguishes zero vs non-zero)
+    // sees identical behavior.
+    try {
+      apply(args[1], { dryRun });
+    } catch (e) {
+      console.error(e.message);
+      process.exit(e instanceof ApplyExit ? e.code : 1);
+    }
  } else {
    process.stdout.write(JSON.stringify(detect(), null, 2) + '\n');
  }
 }

-export { detect, apply, resolveUpstream, readAbi, vendoredVersion, GRAMMARS, COMPATIBLE_ABI };
+export {
+  detect,
+  apply,
+  resolveUpstream,
+  readAbi,
+  vendoredVersion,
+  loadManifestGrammars,
+  GRAMMARS,
+  COMPATIBLE_ABI,
+};
@@ -0,0 +1,26 @@
+{
+  "_comment": "Single source of truth for the VENDORED SET + policy holds, read by BOTH .github/scripts/update-vendored-grammars.mjs (weekly auto-PR bot) and .github/scripts/check-tree-sitter-upgrade-readiness.py (daily readiness report -> issue #858). The monitor also resolves each grammar's upstream from the `upstream` field here; the readiness report reads vendored ABIs from gitnexus/vendor/<name>/src/parser.c and keeps its own upstream-drift coords. A consistency-guard test asserts this set equals the gitnexus/vendor/tree-sitter-* directories. See CONTRIBUTING.md.",
+  "grammars": {
+    "c": {
+      "name": "tree-sitter-c",
+      "upstream": { "npm": "tree-sitter-c" },
+      "hold": "ABI-pinned at 0.21.4 (#1242/#858) — needs a tree-sitter runtime upgrade before bumping"
+    },
+    "swift": {
+      "name": "tree-sitter-swift",
+      "upstream": { "npm": "tree-sitter-swift" }
+    },
+    "kotlin": {
+      "name": "tree-sitter-kotlin",
+      "upstream": { "npm": "tree-sitter-kotlin" }
+    },
+    "dart": {
+      "name": "tree-sitter-dart",
+      "upstream": { "github": "UserNobody14/tree-sitter-dart" }
+    },
+    "proto": {
+      "name": "tree-sitter-proto",
+      "upstream": { "github": "coder3101/tree-sitter-proto" }
+    }
+  }
+}
@@ -102,7 +102,7 @@ jobs:
      matrix: ${{ steps.decide.outputs.matrix }}
      release_app: ${{ steps.relapp.outputs.configured }}
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          fetch-depth: 0 # need base history to diff recorded versions
          persist-credentials: false
@@ -270,7 +270,7 @@ jobs:
    # and compiling them under emulation on the arm runners is slow.
    timeout-minutes: 45
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false # this job uploads artifacts (artipacked)

@@ -280,7 +280,7 @@ jobs:

      - name: Ensure Python (arm64 Windows only)
        if: matrix.platform_arch == 'win32-arm64'
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: '3.12'

@@ -431,7 +431,7 @@ jobs:
          app-id: ${{ secrets.RELEASE_APP_ID }}
          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}

-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          token: ${{ steps.app-token.outputs.token }}
          persist-credentials: false
@@ -477,7 +477,7 @@ jobs:
          NODE

      - name: Attest build provenance (SLSA)
-        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2.4.0
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
        with:
          subject-path: 'gitnexus/vendor/tree-sitter-*/prebuilds/**/*.node'

@@ -36,7 +36,7 @@ jobs:
      # persist-credentials: false — this job only reads (tests and syntax
      # checks) and never pushes. The setting keeps GITHUB_TOKEN out of
      # .git/config, which zizmor flags as the "artipacked" issue.
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -57,7 +57,7 @@ jobs:
      # persist-credentials: false — this is a read-only build smoke that
      # never pushes. The setting keeps GITHUB_TOKEN out of .git/config,
      # which zizmor flags as the "artipacked" issue.
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -14,7 +14,7 @@ jobs:
    outputs:
      web_changed: ${{ steps.filter.outputs.web }}
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v3
        id: filter
        with:
@@ -29,7 +29,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3

      - name: Configure e2e GitNexus home
        run: echo "GITNEXUS_HOME=${RUNNER_TEMP}/gitnexus-home" >> "$GITHUB_ENV"
@@ -11,7 +11,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: 22
@@ -24,7 +24,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: 22
@@ -37,7 +37,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
      - uses: ./.github/actions/setup-gitnexus
      - run: npx tsc --noEmit
        working-directory: gitnexus
@@ -46,7 +46,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
      - uses: ./.github/actions/setup-gitnexus-web
      - run: npx tsc -b --noEmit
        working-directory: gitnexus-web
@@ -67,7 +67,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
      - name: Validate workflow concurrency convention
        shell: bash
        run: |
@@ -125,7 +125,7 @@ jobs:

      - name: Checkout (for vitest config)
        if: steps.meta.outputs.skip != 'true'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          sparse-checkout: gitnexus/vitest.config.ts
          sparse-checkout-cone-mode: false
@@ -16,7 +16,7 @@ jobs:
      # test-reports artifact (if: always()). The default-persisted token in
      # .git/config must not be capturable through that upload (zizmor
      # credential-persistence / artipacked audit). The job never pushes.
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup-gitnexus
@@ -80,7 +80,7 @@ jobs:
    steps:
      # persist-credentials: false — runs tests only, never pushes (zizmor
      # credential-persistence / artipacked audit).
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup-gitnexus
@@ -106,7 +106,7 @@ jobs:
    runs-on: ${{ matrix.os }}
    timeout-minutes: 20
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
      - uses: ./.github/actions/setup-gitnexus
        with:
          build: 'true'
@@ -138,7 +138,7 @@ jobs:
      # from a tarball and never pushes back; the token in .git/config would
      # be at risk of leaking through any future artifact-upload step
      # (zizmor artipacked audit). Disable upfront.
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup-gitnexus
@@ -246,7 +246,7 @@ jobs:
      # and never pushes; the default-persisted token in .git/config would be at
      # risk of leaking through an artifact upload (zizmor credential-persistence
      # / artipacked audit). Mirrors the packaged-install-smoke job below.
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup-gitnexus
@@ -266,6 +266,34 @@ jobs:
        run: node --import tsx bench/scope-capture/measure.mjs --check
        working-directory: gitnexus

+      - name: CFG construction time / disk / memory guards (#2081 M1)
+        # Build-free: asserts collectFunctionCfgs output is unchanged
+        # (fingerprint) and that wall-time, cfgSideChannel disk bytes, AND
+        # retained heap all stay sub-quadratic for the straight-line /
+        # many-functions / branchy scenarios. Catches an O(n^2) re-regression in
+        # the per-function CFG builder (e.g. an extendBlock concat chain) and a
+        # memory/disk blow-up. --expose-gc enables the retained-heap measurement.
+        run: node --expose-gc --import tsx bench/cfg/measure.mjs --check
+        working-directory: gitnexus
+
+      - name: Emit-persistence throughput / byte-identity guards (#2203)
+        # Build-free: asserts streamAllCSVsToDisk output is byte-identical
+        # (order-independent CSV-line fingerprint — the #2203 U2/U3 emit
+        # optimisations must not change graph content) and that emit wall-time
+        # stays linear in node+edge count. The LadybugDB COPY half needs a real
+        # DB, so its timing lives in the runtime PROF_LBUG_LOAD breakdown.
+        run: node --import tsx bench/emit-persistence/measure.mjs --check
+        working-directory: gitnexus
+
+      - name: Streaming PDG-emit byte-identity / bounded-RSS guards (#2202)
+        # Build-free: asserts the streaming PdgEmitSink emits a CSV row SET
+        # byte-identical to the whole-graph streamAllCSVsToDisk emit, AND that
+        # the in-memory graph retains zero BasicBlock nodes (the O(chunk) peak-RSS
+        # bound that unblocks full-kernel-scale repos). Fails on fingerprint drift
+        # or any resident BasicBlock.
+        run: node --import tsx bench/emit-persistence/measure-streaming.mjs --check
+        working-directory: gitnexus
+
      - name: Cross-language pipeline benchmarks (GITNEXUS_BENCH, serial)
        env:
          GITNEXUS_BENCH: '1'
@@ -129,7 +129,7 @@ jobs:
            core.setOutput('code_review', isCodeReview ? 'true' : 'false');

      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          repository: ${{ steps.pr.outputs.is_pr == 'true' && steps.pr.outputs.repo || github.repository }}
          ref: ${{ steps.pr.outputs.is_pr == 'true' && steps.pr.outputs.sha || '' }}
@@ -42,13 +42,13 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        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@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4.36.0
+        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
        with:
          languages: ${{ matrix.language }}
          queries: security-and-quality
@@ -65,10 +65,14 @@ jobs:
              - '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.
+              # findings here are noise, not real bugs. The second glob also
+              # covers fixtures nested deeper in the test tree, e.g.
+              # test/integration/cfg/fixtures/ (the CFG/PDG hazard inputs that
+              # deliberately contain use-before-init / unused-variable shapes).
              - '**/test/fixtures/**'
+              - '**/test/**/fixtures/**'

      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4.36.0
+        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
        with:
          category: '/language:${{ matrix.language }}'
@@ -28,7 +28,7 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false

@@ -101,7 +101,7 @@ jobs:
      # When triggered by workflow_call the caller passes the RC tag as an input;
      # we check out that tag so the Dockerfile and package.json match the built image.
      # For tag-push events github.ref is already the tag ref — no override needed.
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          ref: ${{ inputs.tag || github.ref }}

@@ -138,7 +138,7 @@ jobs:

      # Required for multi-platform (linux/arm64) emulation.
      - name: Set up QEMU
-        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
+        uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3 # v4.1.0

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
@@ -29,7 +29,7 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        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.
@@ -53,7 +53,7 @@ jobs:
      # 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
+        uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_ENABLE_UPLOAD_ARTIFACT: true
@@ -14,6 +14,13 @@ name: Vendored grammar update monitor
 # never auto-bumped — a maintainer re-vendors it deliberately after a runtime
 # upgrade.
 #
+# The vendored set + per-grammar upstream coords + the tree-sitter-c hold live in
+# .github/vendored-grammars.json — the SHARED source of truth this monitor and
+# tree-sitter-upgrade-readiness.yml both read, so the two workflows can never
+# disagree about which grammars are vendored (#858). This monitor additionally
+# resolves each grammar's upstream from it; the readiness report reads vendored
+# ABIs from gitnexus/vendor/ and keeps its own upstream-drift coords.
+#
 # Concurrency convention: see CONTRIBUTING.md -> "GitHub Actions — Concurrency Convention".

 on:
@@ -37,7 +44,7 @@ jobs:
    permissions:
      contents: read
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false

@@ -0,0 +1,71 @@
+name: Impact PDG Mutation Report
+
+# Off-the-fast-path mutation oracle for the PDG-backed `impact` mode.
+#
+# The `--mutation` oracle (bench/impact-pdg/measure.mjs) is a ~280s dynamic
+# value-diff check: it mutates each fixture, re-analyzes with `--pdg`, and scores
+# the realized recall of the statement slice against the behavioral diff. It is
+# far too slow for the PR critical path, so it runs on a nightly schedule (and on
+# demand via workflow_dispatch) and uploads the JSON report as an artifact rather
+# than gating merges.
+#
+# The harness shells out to `gitnexus analyze --pdg`, which spawns workers from
+# dist/, so dist must be built first — setup-gitnexus with build: 'true' does
+# that (mirrors ci-tests.yml).
+
+on:
+  schedule:
+    - cron: '0 3 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  mutation-report:
+    name: impact-pdg mutation oracle
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    permissions:
+      contents: read
+    steps:
+      # persist-credentials: false — this job runs the bench + uploads an
+      # artifact and never pushes; the default-persisted token in .git/config
+      # must not be capturable through that upload (zizmor credential-persistence
+      # / artipacked audit). Mirrors ci-tests.yml.
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      # setup-gitnexus is the repo's composite install action (Node 22 + npm ci);
+      # build: 'true' runs `node scripts/build.js` so dist/ exists for the
+      # analyze workers the mutation harness spawns.
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'true'
+
+      - name: Run PDG impact mutation oracle (~280s)
+        run: node --import tsx bench/impact-pdg/measure.mjs --mutation --json > mutation-report.json
+        working-directory: gitnexus
+
+      # Regression gate: write a recall summary to the run AND fail if the
+      # minimum realized recall drops below the (tunable) floor, so a recall
+      # regression surfaces instead of sitting unread in the artifact. Runs
+      # before the (always) upload so the artifact is preserved even on a fail.
+      - name: Gate on mutation recall regression
+        run: node bench/impact-pdg/gate-mutation-recall.mjs mutation-report.json
+        working-directory: gitnexus
+        env:
+          MUTATION_RECALL_FLOOR: '0.5'
+
+      - name: Upload mutation report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: impact-pdg-mutation-report
+          path: gitnexus/mutation-report.json
+          retention-days: 14
@@ -336,7 +336,7 @@ jobs:
      # Push auth is provided inline at push time via the URL.
      - name: Checkout PR head
        if: steps.locate.outputs.found == 'true'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v5.0.4
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v5.0.4
        with:
          repository: ${{ steps.locate.outputs.head_repo }}
          ref: ${{ steps.locate.outputs.head_sha }}
@@ -51,7 +51,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          # PR head commit (not the synthetic merge ref) — we need the
          # exact tree the contributor pushed so suggestions line up.
@@ -108,7 +108,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@c2e2804cc59f45f57076a99af580d0fedb697927 # v7.3.0
+      - uses: release-drafter/release-drafter@693d20e7c1ce1a81d3a41962f85914253b518449 # v7.3.1
        with:
          config-name: release-drafter.yml
          dry-run: true
@@ -162,7 +162,7 @@ jobs:
      should_run: ${{ steps.decide.outputs.should_run }}
      head_sha: ${{ steps.decide.outputs.head_sha }}
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          fetch-depth: 0
          fetch-tags: true
@@ -332,7 +332,7 @@ jobs:
      # on the RC path.
      - name: Checkout (RC)
        if: needs.route.outputs.mode == 'rc'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          fetch-depth: 0
          fetch-tags: true
@@ -349,7 +349,7 @@ jobs:

      - name: Checkout (stable)
        if: needs.route.outputs.mode == 'stable'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        # No `token:` — actions/checkout uses GITHUB_TOKEN by default. Stable
        # path performs no git pushes; the default scope is sufficient.
        with:
@@ -33,7 +33,7 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false

@@ -53,6 +53,6 @@ jobs:
          retention-days: 5

      - name: Upload to Security tab
-        uses: github/codeql-action/upload-sarif@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4.36.0
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
        with:
          sarif_file: results.sarif
@@ -1,12 +1,21 @@
 name: Tree-sitter Upgrade Readiness

 # Monitors readiness for upgrading tree-sitter to 0.25.x. Tracks:
-#   1. Peer-dep compatibility — can each grammar install cleanly with
-#      tree-sitter@0.25.0 without --legacy-peer-deps?
-#   2. Vendored proto drift — has coder3101/tree-sitter-proto moved
-#      ahead of our vendored snapshot?
+#   1. Peer-dep compatibility — can each NPM-installed grammar install cleanly
+#      with tree-sitter@0.25.0 without --legacy-peer-deps?
+#   2. Vendored grammars — each grammar in .github/vendored-grammars.json
+#      (c/swift/kotlin/dart/proto) is classified by its vendored ABI, read
+#      straight from gitnexus/vendor/<name>/src/parser.c (NOT node_modules,
+#      which is never populated for vendored grammars — that mismatch is why
+#      the report used to render bare "?" placeholders, #858).
 # See .github/scripts/check-tree-sitter-upgrade-readiness.py for the logic.
 #
+# .github/vendored-grammars.json is the SHARED source of truth for the vendored
+# SET + policy holds: this readiness report and grammar-update-monitor.yml both
+# read it, so the two workflows can never disagree about which grammars are
+# vendored. (The monitor also resolves upstreams from it; this report keeps its
+# own upstream-drift coords and reads vendored ABIs from gitnexus/vendor/.)
+#
 # Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".

 on:
@@ -18,6 +27,8 @@ on:
  pull_request:
    paths:
      - '.github/scripts/check-tree-sitter-upgrade-readiness.py'
+      - '.github/scripts/test_check_tree_sitter_upgrade_readiness.py'
+      - '.github/vendored-grammars.json'
      - '.github/workflows/tree-sitter-upgrade-readiness.yml'

 concurrency:
@@ -28,21 +39,36 @@ permissions:
  contents: read

 jobs:
-  readiness:
+  report:
    name: Check upgrade readiness
    runs-on: ubuntu-latest
    timeout-minutes: 10
+    # Least privilege: rendering the report needs no write. The issue mutation
+    # lives in the schedule-only `upsert-issue` job below, so PR runs (incl. forks)
+    # never receive `issues: write` (#2187 review).
    permissions:
      contents: read
-      # Needed to open/update the tracking issue on scheduled runs.
-      issues: write
+    outputs:
+      report: ${{ steps.readiness.outputs.report }}
+      exit_code: ${{ steps.readiness.outputs.exit_code }}
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3

      - uses: ./.github/actions/setup-gitnexus
        with:
          build: 'false'

+      # Guard the readiness script's logic (vendored classification, no bare "?",
+      # the manifest⇄vendor-dir consistency guard). Stdlib-only, so no extra deps;
+      # node_modules is populated by setup-gitnexus above, which the npm-path ABI
+      # reads need. Runs only on validation events (PR / manual), not the daily
+      # scheduled report.
+      - name: Run readiness script unit tests
+        if: github.event_name != 'schedule'
+        shell: bash
+        working-directory: .github/scripts
+        run: python3 -m unittest test_check_tree_sitter_upgrade_readiness -v
+
      - name: Run upgrade readiness check
        id: readiness
        shell: bash
@@ -54,10 +80,15 @@ jobs:
          code=$?
          set -e
          echo "exit_code=$code" >> "$GITHUB_OUTPUT"
+          # Unguessable per-run heredoc delimiter: the report includes the manifest's
+          # `hold` field, which a fork PR can edit — a fixed delimiter (e.g. DRIFT_EOF)
+          # in a hold value could close the heredoc early and inject $GITHUB_OUTPUT keys.
+          # A random hex delimiter the report cannot contain neutralizes that.
+          DELIM="DRIFT_EOF_$(openssl rand -hex 16)"
          {
-            echo 'report<<DRIFT_EOF'
+            echo "report<<${DELIM}"
            cat drift-report.md
-            echo 'DRIFT_EOF'
+            echo "${DELIM}"
          } >> "$GITHUB_OUTPUT"
          echo "=== Report ==="
          cat drift-report.md
@@ -69,13 +100,22 @@ jobs:
        run: |
          echo "::warning::Tree-sitter 0.25 upgrade has blockers. See job output for the full readiness report."

-      - name: Upsert tracking issue on scheduled runs
-        if: >
-          github.event_name == 'schedule' &&
-          steps.readiness.outputs.exit_code != '0'
+  # Issue mutation is isolated here so `issues: write` is only ever granted on the
+  # scheduled run (never on PRs). Consumes the report + exit_code via job outputs.
+  upsert-issue:
+    name: Upsert tracking issue
+    needs: report
+    if: github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      issues: write
+    steps:
+      - name: Upsert tracking issue on blockers
+        if: needs.report.outputs.exit_code != '0'
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
-          REPORT: ${{ steps.readiness.outputs.report }}
+          REPORT: ${{ needs.report.outputs.report }}
        with:
          script: |
            const title = 'Tree-sitter 0.25 upgrade readiness';
@@ -93,11 +133,32 @@ jobs:
            const existing = open.find(i => i.title === title);
            if (existing) {
              // Extract ready/total count for the changelog comment.
-              const readyMatch = report.match(/\*\*(\d+)\/(\d+)\*\* grammars ready/);
-              const blockerMatch = report.match(/\*\*(\d+) blocker/);
-              const ready = readyMatch ? readyMatch[1] : '?';
-              const total = readyMatch ? readyMatch[2] : '?';
-              const blockers = blockerMatch ? blockerMatch[1] : '?';
+              // The two report.match() regexes below are mirrored as
+              // _ISSUE_READY_RE / _ISSUE_BLOCKER_RE in
+              // .github/scripts/test_check_tree_sitter_upgrade_readiness.py, which is
+              // the ONLY place the contract is asserted against the rendered report.
+              // Keep all three in sync: changing the report prose means updating both
+              // these literals AND the test mirror, or requireMatch throws on the next
+              // scheduled run (the silent "?" fallback that used to hide drift is gone).
+              const requireMatch = (name, match) => {
+                if (!match) {
+                  throw new Error(
+                    `Could not extract ${name} from tree-sitter readiness report`,
+                  );
+                }
+                return match;
+              };
+              const readyMatch = requireMatch(
+                'ready npm grammar count',
+                report.match(/- (\d+)\/(\d+) npm-installed grammars already accept tree-sitter@/),
+              );
+              const blockerMatch = requireMatch(
+                'blocker count',
+                report.match(/\*\*Blocked\*\* — (\d+) grammars? /),
+              );
+              const ready = readyMatch[1];
+              const total = readyMatch[2];
+              const blockers = blockerMatch[1];

              // Find grammars whose status changed by diffing the old and
              // new table rows.  Each row looks like:
@@ -105,7 +166,11 @@ jobs:
              //   | `tree-sitter-foo` | ... | Blocking |
              const parseRows = (md) => {
                const map = {};
-                for (const m of md.matchAll(/\| `(tree-sitter-[^`]+)` \|.*?\| (\S+(?:\s\S+)*?) \|$/gm)) {
+                // Group 2 captures ONLY the Status cell ([^|]+? before the final
+                // `|$`), so change-detection fires on status transitions, not on
+                // unrelated cell drift (e.g. an upstream-ABI bump). Mirror this in
+                // _ROW_DIFF_RE in test_check_tree_sitter_upgrade_readiness.py.
+                for (const m of md.matchAll(/\| `(tree-sitter-[^`]+)` \|.*\| ([^|]+?) \|$/gm)) {
                  map[m[1]] = m[2].trim();
                }
                return map;
@@ -121,7 +186,7 @@ jobs:
              }

              const today = new Date().toISOString().slice(0, 10);
-              let comment = `**${today}:** ${ready}/${total} ready. ${blockers} blocker(s) remaining.`;
+              let comment = `**${today}:** ${ready}/${total} npm-installed ready. ${blockers} blocker(s) remaining.`;
              if (changes.length > 0) {
                comment += '\n\nChanges:\n' + changes.map(c => `- ${c}`).join('\n');
              } else {
@@ -152,10 +217,8 @@ jobs:
              core.info(`Opened issue #${created.number}`);
            }

-      - name: Close tracking issue on clean scheduled runs
-        if: >
-          github.event_name == 'schedule' &&
-          steps.readiness.outputs.exit_code == '0'
+      - name: Close tracking issue on clean runs
+        if: needs.report.outputs.exit_code == '0'
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        with:
          script: |
@@ -59,7 +59,7 @@ jobs:
    timeout-minutes: 30
    steps:
      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
        with:
          sparse-checkout: .github/scripts/triage
          sparse-checkout-cone-mode: false
@@ -45,7 +45,7 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false

@@ -76,7 +76,7 @@ jobs:
          exit-code: '0'

      - name: Upload to Security tab
-        uses: github/codeql-action/upload-sarif@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4.36.0
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
        with:
          sarif_file: trivy-${{ matrix.image.name }}.sarif
          category: trivy-${{ matrix.image.name }}
@@ -31,7 +31,7 @@ jobs:
      contents: read
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false

@@ -53,7 +53,7 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false

@@ -76,7 +76,7 @@ jobs:
        continue-on-error: true

      - name: Upload SARIF
-        uses: github/codeql-action/upload-sarif@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4.36.0
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
        with:
          sarif_file: zizmor.sarif
          category: zizmor
@@ -3,10 +3,17 @@ title = "GitNexus"
 [extend]
 useDefault = true

-# Fake embedding API keys in unit tests (current probe + historical placeholder).
+# Fake credentials in unit tests — none are real secrets:
+#   - embedding API keys in the http-embedder tests (regexes below)
+#   - synthetic GitHub PAT fixtures in the git-clone PAT-injection tests
+#     (e.g. ghp_secret123, ghp_uniqueRawSecret_98765) — allowlisted by path
+#     so the exception is bounded to that one test file.
 [allowlist]
-description = "fake embedding API keys in http-embedder unit tests"
+description = "fake credentials in unit tests (no real secrets)"
 regexes = [
  '''secret-key-12345''',
  '''test-api-key-redaction-check''',
 ]
+paths = [
+  '''gitnexus/test/unit/git-clone\.test\.ts''',
+]
@@ -83,7 +83,7 @@ This project is indexed by GitNexus as **GitNexus** (26675 symbols, 35395 relati
 - **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
 - **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
 - **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
- When exploring unfamiliar code, use `query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When exploring unfamiliar code, use `query({search_query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
 - When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `context({name: "symbolName"})`.

 ## Never Do
@@ -38,9 +38,12 @@ Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).
 | `detect_changes` | Map git diffs to affected symbols and processes |
 | `rename` | Graph-assisted multi-file rename with `dry_run` preview |
 | `api_impact` | Pre-change impact report for an API route handler |
+| `trace` | Shortest directed path between two symbols (call + class-member edges) |
 | `route_map` | API route → handler → consumer mappings |
 | `tool_map` | MCP/RPC tool definitions and handlers |
 | `shape_check` | Response shape vs consumer property access mismatches |
+| `explain` | Persisted taint findings (source→sink data flows) — needs `analyze --pdg` |
+| `pdg_query` | Control/data dependence — CDG (`mode: controls`) / REACHING_DEF (`mode: flows`) — needs `analyze --pdg` |
 | `group_list` | List repo groups or details for one group |
 | `group_sync` | Rebuild group Contract Registry (`contracts.json`) and bridge graph |

@@ -204,6 +207,18 @@ Language-agnostic scope-resolution resolver. This is the resolution path for eve
 Orchestrator: `runScopeResolution(input, provider)` in `scope-resolution/pipeline/run.ts`.
 Pipeline phase: `scopeResolutionPhase` in `scope-resolution/pipeline/phase.ts` — iterates the registered `SCOPE_RESOLVERS` over the worker-serialized `ParsedFile`s. (Per-language `emitScopeCaptures` hooks may reuse a cached Tree via the orchestrator's `treeCache`, but in worker-pool runs that cache is empty — Trees can't cross MessageChannels — so they consume the pre-extracted `ParsedFile` instead; § Performance notes.)

+### Optional CFG/PDG emission (`--pdg`, #2081–#2086)
+
+On a `--pdg` run the parse worker builds a per-function control-flow graph from the tree-sitter AST (`LanguageProvider.cfgVisitor`; TypeScript/JavaScript today) and serializes it onto `ParsedFile.cfgSideChannel` as plain data. Scope-resolution then emits the program-dependence layers from that side-channel **inside Phase 4 of `runScopeResolution`, while the disk-backed ParsedFile store is still live** — the only window where the worker-built CFGs are loaded (the store is cleared right after the phase returns). A standalone post-`mro` phase would read an empty store, so the emit deliberately lives in-phase, mirroring the `applyCaptureSideChannel` pattern. The opt-in is off by default (graph byte-identical), folded into the parse-cache key (a pdg-off warm cache is never reused on a `--pdg` run), and each layer is bounded by a per-function edge cap that logs any dropped edges. All layers are `BasicBlock → BasicBlock` edges in the single `CodeRelation` table, keyed by `type`; there is **no** `Function → BasicBlock` edge — the symbol↔block join is reconstructed from the BasicBlock id prefix + line span. The layers build on each other:
+
+- **M1 — CFG** (#2081): `BasicBlock` nodes + `CFG` edges. Edge *kind* (`seq`/`cond-true`/`loop-back`/…) rides the `reason` column (CFG is one `CodeRelation` type, not one per kind).
+- **M2 — REACHING_DEF** (#2082): GEN/KILL def→use data dependence from a pure fixpoint solver; the variable name rides `reason`.
+- **M3/M4 — TAINTED / SANITIZES / TAINT_PATH** (#2083–#2084): intra- and inter-procedural taint (source→sink) — the `explain` tool's data.
+- **M5 — CDG** (#2085): Ferrante control dependence over a Cooper–Harvey–Kennedy post-dominator tree (the EXIT-rooted reverse CFG); branch sense (`'T'`/`'F'`) rides `reason`. A CFG whose EXIT is unreachable from some block is skipped for CDG (post-dominance would be unsound) while its CFG/REACHING_DEF layers are kept.
+- **M6 — read surface** (#2086): the `pdg_query` MCP tool answers "what gates X?" (CDG, `mode: controls`) and "where does Y flow?" (REACHING_DEF, `mode: flows`); `explain` is the taint consumer. Both are always anchored + `LIMIT`-bounded (LadybugDB has no rel-property index) and share one `resolveBlockAnchor` helper. These PDG edge types are deliberately kept out of the default `VALID_RELATION_TYPES` / web schema.
+
+See `core/ingestion/cfg/` (emit + the pure CFG / post-dominator / control-dependence / reaching-defs / taint passes) and `mcp/local/local-backend.ts` (`_pdgQueryImpl`, `_explainImpl`, the shared `resolveBlockAnchor`).
+
 ### `ScopeResolver` contract

 Single interface a language implements to plug into the pipeline. Contract fully documented in `scope-resolution/contract/scope-resolver.ts`.
@@ -379,6 +394,8 @@ Defined in `lbug/schema.ts`. Separate node tables per type, single `CodeRelation

 **Relation types** (`CodeRelation.type`): CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES, METHOD_IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF.

+**Optional `--pdg` additions** (off by default, opt-in via `gitnexus analyze --pdg`; see _Optional CFG/PDG emission_ above): a `BasicBlock` node table, plus the PDG relation types `CFG`, `REACHING_DEF`, `CDG`, `TAINTED`, `SANITIZES`, and `TAINT_PATH` on the same `CodeRelation` table. These are deliberately kept out of the default `VALID_RELATION_TYPES` / web graph schema — query them via `cypher`, `explain`, or `pdg_query`.
+
 ## Embeddings and search

 **Embeddings** (`src/core/embeddings/`): Snowflake arctic-embed-xs (384D). Embeddable: File, Function, Class, Method, Interface. Incremental via SHA1 content hash. Separate `Embedding` table.
@@ -4,12 +4,6 @@ All notable changes to GitNexus will be documented in this file.

 ## [Unreleased]

-### Changed
- Migrated from KuzuDB to LadybugDB v0.15 (`@ladybugdb/core`, `@ladybugdb/wasm-core`)
- Renamed all internal paths from `kuzu` to `lbug` (storage: `.gitnexus/kuzu` → `.gitnexus/lbug`)
- Added automatic cleanup of stale KuzuDB index files
- LadybugDB v0.15 requires explicit VECTOR extension loading for semantic search
-
 ## [1.5.3] - 2026-04-01

 ### Added
@@ -65,7 +65,7 @@ This project is indexed by GitNexus as **GitNexus** (26675 symbols, 35395 relati
 - **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
 - **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
 - **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
- When exploring unfamiliar code, use `query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When exploring unfamiliar code, use `query({search_query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
 - When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `context({name: "symbolName"})`.

 ## Never Do
@@ -144,6 +144,15 @@ Re-invoking `/autofix` after a successful apply is a safe no-op — the workflow

 **Sensitive paths.** The apply workflow refuses any patch that touches `.github/` (workflow files, CODEOWNERS, dependabot config). A malicious PR could ship a custom prettier or ESLint config that reformats workflow YAML; if accepted, those edits would be pushed under `contents: write` without human review. Apply formatter changes to files under `.github/` manually in a normal commit so they get the same review every other workflow change gets.

+### Vendored tree-sitter grammars
+
+`.github/vendored-grammars.json` is the **single source of truth** for the vendored tree-sitter grammar **set** and each grammar's policy `hold` (the ones shipped from `gitnexus/vendor/<name>` rather than installed from npm). It lists each grammar's name, upstream coords (`npm` or `github`), and any `hold`. The monitor resolves upstreams from it; the readiness report keeps its own upstream-drift coords and reads vendored ABIs from `gitnexus/vendor/`. Two workflows read it:
+
+- `grammar-update-monitor.yml` (`.github/scripts/update-vendored-grammars.mjs`) — weekly; opens auto-PRs re-vendoring ABI-compatible upstream updates.
+- `tree-sitter-upgrade-readiness.yml` (`.github/scripts/check-tree-sitter-upgrade-readiness.py`) — daily; renders the tree-sitter-0.25 readiness report (issue #858), reading each vendored grammar's ABI from `gitnexus/vendor/<name>/src/parser.c`.
+
+Sharing the manifest keeps the two aligned: a consistency-guard test asserts the manifest set equals the `gitnexus/vendor/tree-sitter-*` directories. **When you vendor a new grammar (or remove one), update `.github/vendored-grammars.json` in the same change** — otherwise that guard fails CI and the readiness report regresses to `?` placeholders.
+
 ## AI-assisted contributions

 If you use coding agents, follow project context files (e.g. `AGENTS.md`, `CLAUDE.md`) and avoid drive-by refactors unrelated to the issue. Prefer incremental, test-backed changes.
@@ -100,6 +100,22 @@ ENV HOME=/home/node \
 RUN su node -s /bin/sh -c "HOME=/home/node node /app/gitnexus/scripts/install-duckdb-extension.mjs fts" \
 && su node -s /bin/sh -c "HOME=/home/node node /app/gitnexus/scripts/install-duckdb-extension.mjs fts --verify-only"

+# Published runtime assets (in package.json `files`). Placed AFTER the DuckDB
+# FTS-extension RUN above so editing hook/skill content does not invalidate that
+# network-fetching cache layer; they have no input dependency on it.
+# `hooks/`: dist/cli/resolve-invocation.js does
+# `require('../../hooks/claude/resolve-analyze-cmd.cjs')` at module load — the
+# single source of truth for the npm-11 npx-crash invocation decision (#1939).
+# Without it, `gitnexus analyze` inside the image crashes with MODULE_NOT_FOUND
+# before it does any work (#2130). `skills/`: the CLI reads the bundled SKILL.md
+# templates from `<pkg>/skills/` for `gitnexus analyze --skills` and `gitnexus
+# setup`/`uninstall`; absent, those degrade silently (placeholder content / zero
+# skills installed). (The web UI bundle `web/`, also in `files`, is deliberately
+# NOT shipped: this builder never builds gitnexus-web, so the image is API-only;
+# the UI is the separate Dockerfile.web image / hosted app.)
+COPY --from=builder --chown=node:node /app/gitnexus/hooks ./gitnexus/hooks
+COPY --from=builder --chown=node:node /app/gitnexus/skills ./gitnexus/skills
+
 USER node

 # The web UI defaults to http://localhost:4747 - keep that contract.
@@ -123,7 +123,7 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up

 ### MCP Setup

-`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
+`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once. To configure only selected integrations, pass `--coding-agent`/`-c` with a comma-separated list or repeat the option, for example `gitnexus setup -c cursor,codex`.

 ### Editor Support

@@ -224,7 +224,7 @@ args = ["-y", "gitnexus@latest", "mcp"]
 ### CLI Commands

 ```bash
-gitnexus setup                   # Configure MCP for your editors (one-time)
+gitnexus setup                   # Configure MCP for detected editors (one-time; use -c to select)
 gitnexus uninstall               # Preview removal of GitNexus MCP/skills/hooks (add --force to apply)
 gitnexus analyze [path]          # Index a repository (or update stale index)
 gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
@@ -324,6 +324,7 @@ Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max
 | `GITNEXUS_VERBOSE`                     | unset                     | When `1`, enables verbose ingestion logs (skipped-file warnings, per-chunk throughput, parse-cache stats). Equivalent to `--verbose`.                      | Debugging an analyze that "completed" but seems to have missed files; tuning `--workers` / chunk concurrency against observable throughput. |
 | `GITNEXUS_PROFILE_DEFERRED`            | unset                     | When `1`, emits `[deferred-profile]` timing/progress logs for the post-chunk deferred resolution band (imports → heritage → buildHeritageMap → legacy call resolution). Implied by `GITNEXUS_VERBOSE`. | Diagnosing analyze stalls in "Resolving calls (all chunks)" on large Java/Kotlin repos (issue #1741) without the full verbose ingestion noise. |
 | `GITNEXUS_PROFILE_DEFERRED_SLOW_MS`    | `3000` (verbose) / `5000` | Per-file threshold in ms above which `processCallsFromExtracted` emits a `slow file …` log line. Parsed via `Number()`: accepts integers (`5000`), scientific notation (`2.5e3`), decimals (`.5`), and hex (`0x10`). Non-finite or non-positive values fall back to the default. | Hunting a few outlier files dominating the deferred call-resolution stage; lower to surface more, raise to focus only on the worst.          |
+| `PROF_LBUG_LOAD`                       | unset                     | When `1`, emits one `[lbug-load prof]` summary line per `loadGraphToLbug` call breaking the graph-DB persistence wall into stages (`csv-emit` / `copy-nodes` / `copy-rels` / `fallback` / `total`) plus node & edge counts. Zero-cost when unset. | Attributing large-repo analyze wall time across CSV generation vs. LadybugDB `COPY` (issue #2203) — the analyze "emit" timing is the scope-resolution bucket, not this DB-write path. |
 | `GITNEXUS_MAX_FILE_SIZE`               | `512` (KB)                | Walker skip threshold in KB. Hard cap is `32768` (tree-sitter buffer ceiling). Equivalent to `--max-file-size <kb>`.                                       | Indexing repos with intentionally-large source files (generated parsers, vendored bundles) that should still be parsed.                     |
 | `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS` | `30000`                   | Worker idle timeout in milliseconds before retry/fallback. Equivalent to `--worker-timeout <seconds>` × 1000.                                              | Slow-parsing files (large minified JS, deeply-nested TS types) that legitimately need more than 30s.                                        |
 | `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`       | `67108864` (64 MiB)       | LadybugDB WAL auto-checkpoint threshold in bytes. Equivalent to `--wal-checkpoint-threshold <bytes>`. `-1` keeps LadybugDB's stock threshold (~16 MiB). Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments. | You need a larger or smaller WAL auto-checkpoint threshold for your analyze workload.                                                         |
@@ -360,7 +361,7 @@ It is opt-in and a no-op without `UNDERSTAND_QUICKLY_TOKEN` — a fine-grained G
 | `group_query`     | Search execution flows across all repos in a group               | —            |
 | `group_status`    | Check staleness of repos in a group                              | —            |

-> When only one repo is indexed, the `repo` parameter is optional. With multiple repos, specify which one: `query({query: "auth", repo: "my-app"})`.
+> When only one repo is indexed, the `repo` parameter is optional. With multiple repos, specify which one: `query({search_query: "auth", repo: "my-app"})`.

 **Resources** for instant context:

@@ -703,6 +704,8 @@ GitNexus builds a complete knowledge graph of your codebase through a multi-phas

 **Imports** — cross-file import resolution · **Named Bindings** — `import { X as Y }` / re-export tracking · **Exports** — public/exported symbol detection · **Heritage** — class inheritance, interfaces, mixins · **Type Annotations** — explicit type extraction for receiver resolution · **Constructor Inference** — infer receiver type from constructor calls (`self`/`this` resolution included for all languages) · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics

+**Control flow (CFG, opt-in `--pdg`)** — per-function control-flow graphs (`BasicBlock` nodes + `CFG` edges) feeding the PDG/taint substrate, currently **TypeScript & JavaScript** (#2081 M1); other languages planned. Off by default.
+
 ---

 ## Tool Examples
@@ -736,7 +739,7 @@ gitnexus impact get_embeddings --uid "Function:src/embed.py:get_embeddings"  # e
 ### Process-Grouped Search

 ```
-query({query: "authentication middleware"})
+query({search_query: "authentication middleware"})

 processes:
  - summary: "LoginFlow"
@@ -21,7 +21,7 @@ wheels = [

 [[package]]
 name = "aiohttp"
-version = "3.14.0"
+version = "3.14.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "aiohappyeyeballs" },
@@ -33,108 +33,108 @@ dependencies = [
    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
    { name = "yarl" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/ee/ab/93ce242f899b68c51b0578c027aafa791ab3614cb9345fa5d37b5f5c8e3e/aiohttp-3.14.0.tar.gz", hash = "sha256:2882de819734c715fd1b9c11c97e09fa020d14438203d1d354d8ed1702791c9b", size = 7940674, upload-time = "2026-06-01T19:41:02.763Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/82/78/8ea7308cac6934de8c74a14f3d5f65d1c89287426688be79538d0e5c013d/aiohttp-3.14.1.tar.gz", hash = "sha256:307f2cff90a764d329e77040603fa032db89c5c24fdad50c4c15334cba744035", size = 7955794, upload-time = "2026-06-07T21:09:35.529Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/67/47/7727bfe8db93f8835a001bd4359d8480cc68d1259b8bce334668f8be97bd/aiohttp-3.14.0-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:54bf3522d6f7351e55f89a62d5c2bf138ad557b031670266c5df604ae88e0b5a", size = 759147, upload-time = "2026-06-01T19:37:12.918Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/f2/cd3fedff6fade73d71df9ec908c210cec518ef90fd00289250684b90aecf/aiohttp-3.14.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:0746d9fb0ac4fdef643a84494efe3f06d50335dd8c7a530228b86448aae0a803", size = 513705, upload-time = "2026-06-01T19:37:14.633Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/fe/49746b6b610144a06323bebd8e1211a390310d8c69b98dd6d52df341bc3e/aiohttp-3.14.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:9f3a96b6d39a4872222beee72e1df41d2ff886ae96152cf3e757ef8c5673ef0e", size = 509627, upload-time = "2026-06-01T19:37:16.385Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/3f/28f2f6cf3d5c0e7b01b27140d0e7873fd11fb341169ad3ce78ad04aba628/aiohttp-3.14.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d336820adbb914debbc90a1d8c1bfc4bea55996aecf64866a989d35d1f9fd903", size = 1769293, upload-time = "2026-06-01T19:37:18.067Z" },
-    { url = "https://files.pythonhosted.org/packages/97/6f/2e5f1b525d5474b12b3c60abf733a755845f3bceff21542081ada515f837/aiohttp-3.14.0-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:71b2604c9bfc1b115547d63a094d5244b3f02799833513a99a68aaa7b167c4cb", size = 1732363, upload-time = "2026-06-01T19:37:20.138Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/ce/596120faa85ca7b19cd061e3f2f3be23aa8f11a0aedf9191db9e0da1bd76/aiohttp-3.14.0-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:610d68800435903e303ca0542b9d3e4eb72a12ff33a6d471a070c1d81eebd3c2", size = 1840375, upload-time = "2026-06-01T19:37:22.104Z" },
-    { url = "https://files.pythonhosted.org/packages/72/3c/a7ffe05a757a4a7867643da69357ec41f506879fbd1b231d2ed90af246b2/aiohttp-3.14.0-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:514db9a79337068981ee2137310283a07b4b885c584991097a91a4da419bcb81", size = 1921484, upload-time = "2026-06-01T19:37:24.068Z" },
-    { url = "https://files.pythonhosted.org/packages/93/fa/2c861170bbd4a491de93a69e081db1d971092569e0d593a98ef62c384dc1/aiohttp-3.14.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c452d17eeb95d563fc8b936f3050301dbd1d268126c4632d8b70ede9696202ee", size = 1774153, upload-time = "2026-06-01T19:37:26.256Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/da/1d2f5a165f47ec9b1f69d37b8b977fdc4d501aa72ffb7930db27bb9e49ea/aiohttp-3.14.0-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:ed94a81506e3d1bdbad5108f497a58f2a2354aedb4ca314d5326f07d1fd1ac2d", size = 1632569, upload-time = "2026-06-01T19:37:28.192Z" },
-    { url = "https://files.pythonhosted.org/packages/46/1d/7a6e295c4257252f70f69e90864fdad74b6a1293054fb3f9e65a15de6d63/aiohttp-3.14.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:1394dce36e0f0d260ac0b555a654de19cb989f3c1b8bdd24f505314dfea18a00", size = 1740325, upload-time = "2026-06-01T19:37:30.08Z" },
-    { url = "https://files.pythonhosted.org/packages/f1/7e/e1899b1ca3ec62f1eab2a5cbde14039b97493f7f53eb88d9b668562ffa8d/aiohttp-3.14.0-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:d1467d1e7b48a73ca7237e0ee4335f3d02b923dbc27b82fd254bc301c97d4026", size = 1748691, upload-time = "2026-06-01T19:37:32.211Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/54/4e6b61c1fe7d3433f82bcc6bd7e4d7c683a742a10c9b12a025fd3695c047/aiohttp-3.14.0-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:6a5f3532125233c261cf61f32df4059cfcf482eb793c7d3db8452e3142028b86", size = 1814477, upload-time = "2026-06-01T19:37:34.173Z" },
-    { url = "https://files.pythonhosted.org/packages/9c/38/86fd51be2e08d8e45c83d879d255f10391903cd9fe2a16512f7591a15873/aiohttp-3.14.0-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:3ea81eb518a2ecb319d8ec6d1424a37c773f6634bd87d6985eb606b2faac419f", size = 1623393, upload-time = "2026-06-01T19:37:36.281Z" },
-    { url = "https://files.pythonhosted.org/packages/78/49/466e947a42a88ee23c486d036e7e5d1b097f1bafd8084ad9c9a0a92f0f43/aiohttp-3.14.0-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:32e735c3182de7b64f6941a4ede48b38c7f47d9437bd615dd30b5bda8fa1bc93", size = 1824097, upload-time = "2026-06-01T19:37:38.421Z" },
-    { url = "https://files.pythonhosted.org/packages/f3/89/35f3410bc284682338a1be6b6ea0c5abfa05f063942cfaa9256608440434/aiohttp-3.14.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:c21ca9a1c63d4509158f478aeb9d02914dcc52adc68d1bc9dee2452284ee5996", size = 1764790, upload-time = "2026-06-01T19:37:40.755Z" },
-    { url = "https://files.pythonhosted.org/packages/42/80/2d4291bd5724d3d17e5951aff5a3e02281483fb47295f0788276ee66cd73/aiohttp-3.14.0-cp311-cp311-win32.whl", hash = "sha256:19ca5fc84130675ba11c6ca5c7da5cb65f7bf8a32cdd2b616bf49cd334688aae", size = 454176, upload-time = "2026-06-01T19:37:42.837Z" },
-    { url = "https://files.pythonhosted.org/packages/59/ed/41d0ad4f6ececffc32bdf1f7b494e5498f7ca5c849ea2e3cc9bbd1668251/aiohttp-3.14.0-cp311-cp311-win_amd64.whl", hash = "sha256:d488e6e9d3bb8ba5ae7066d5be885ae9670eba021b8c6ccb9a3a568e6b19d6e5", size = 479334, upload-time = "2026-06-01T19:37:44.776Z" },
-    { url = "https://files.pythonhosted.org/packages/d1/86/c0b5e305c770053f8c3d069bb52b8196917ba91949d1962d52eb307fb0d2/aiohttp-3.14.0-cp311-cp311-win_arm64.whl", hash = "sha256:8b93618102caf12801638a01a2b478a55410ddd71bd41cfaf6f707953a49ac43", size = 450262, upload-time = "2026-06-01T19:37:46.461Z" },
-    { url = "https://files.pythonhosted.org/packages/89/97/2b6889bfb6b6847520d50d95eb8c4307a45e28aaca39faf4a9454b3d1b2f/aiohttp-3.14.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:b29518c9c2ec7e373e68259206a137c7f4f5439c58baaec4b5ab3ab799850a4e", size = 750194, upload-time = "2026-06-01T19:37:48.164Z" },
-    { url = "https://files.pythonhosted.org/packages/21/e2/62634b7fff918ed98c3c6b2f0e70d520f7f28846cb412d451b04354c6459/aiohttp-3.14.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:dbec68ce61b64cb73cab4d33df9433427b1713c8bcccb181dce695c1b6f8e87c", size = 506966, upload-time = "2026-06-01T19:37:50.014Z" },
-    { url = "https://files.pythonhosted.org/packages/dd/fb/5ce075150828c797a5106f1c2fb26034e709d4289b9d2bf8b07f1e59fac6/aiohttp-3.14.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:3cdf534aa455593e589302990c5097aa5c92c06c4262a20da22934f9186a5fff", size = 507527, upload-time = "2026-06-01T19:37:51.96Z" },
-    { url = "https://files.pythonhosted.org/packages/01/d5/405a0ae4e6b081754a3609c1c97c63a950e000a2def16046f1e736933a0e/aiohttp-3.14.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:cb6c657104393b5fbff01a5f59b2023db74058a8077d94475d6c25d03882a108", size = 1762420, upload-time = "2026-06-01T19:37:53.839Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/1d/e05a7c896b15a6bc6fb8fc5319eb437861c2c49c34559ef928add6590315/aiohttp-3.14.0-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:46fbbec4e4fab7428d4396a3823f9320e4560aa3113b89eeebce712c27c9ed5a", size = 1733672, upload-time = "2026-06-01T19:37:55.791Z" },
-    { url = "https://files.pythonhosted.org/packages/cc/22/a72f7c459e195fa41bf4f7abd1f925b91fe91f8097e51c654229ba144a33/aiohttp-3.14.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2c2c7e05dd5335b298085abf45ddf98673934c3ee1c083d0b9ea13d4186ad500", size = 1805064, upload-time = "2026-06-01T19:37:57.931Z" },
-    { url = "https://files.pythonhosted.org/packages/80/50/e85bdaba0be59ca4838005ebfef4048fcdd5f35a02b07057a9a123394440/aiohttp-3.14.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:3c7139100fbaae76515b73051d8f0aa3a3ff02e415eec8a8eee8e2223d9ba955", size = 1902125, upload-time = "2026-06-01T19:38:00.225Z" },
-    { url = "https://files.pythonhosted.org/packages/19/d8/51de5c6b971c27bb1ef620293b8d1ca611ec78736b34b3f6ccf68e4c8785/aiohttp-3.14.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:78d6f9286a629ce52728430afe18f8ed2b6c39a1fddb3802d7244b9983910ad2", size = 1783112, upload-time = "2026-06-01T19:38:02.641Z" },
-    { url = "https://files.pythonhosted.org/packages/73/ae/b4402bfde77e43dfb1b6ccff83c7b7ab63ed06b50c4754f0c5423fb374fe/aiohttp-3.14.0-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:cc3c3e12cdaeb92d7dcf13db00e9f6b1956b910e47256e696df1cfa946d02159", size = 1586356, upload-time = "2026-06-01T19:38:04.637Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/05/750a3265ca4dc54a460bd0cb1121a8f2ce9171fce4a135fb47ea7fd594d2/aiohttp-3.14.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:4d6a998191f5ebe3b8c28463ff72bc030250008b3193c402464efadd08b5ca02", size = 1723119, upload-time = "2026-06-01T19:38:06.713Z" },
-    { url = "https://files.pythonhosted.org/packages/37/01/8c0812c50b3b1b1c37b323bf170d6be8847a8f234060485b7d1e71953f60/aiohttp-3.14.0-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:0fc2b75ae8d169d853be2862d960be8550da6c5c65711d5476407eb3fdb006bd", size = 1757216, upload-time = "2026-06-01T19:38:08.736Z" },
-    { url = "https://files.pythonhosted.org/packages/47/2a/50fb98028a26887cbe48dcc1df92a90825615bc73b5584301304090cded8/aiohttp-3.14.0-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:16eee56bcc72d04600bc56c1759982c2385ec0b41d3fd3521f836bf64a0957ef", size = 1770500, upload-time = "2026-06-01T19:38:11.111Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/32/0ffd598a2fa2b9a423daf242e700cfdabda35d6e602394ad9ae58972c1c7/aiohttp-3.14.0-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:5a2e7ca615c3ddc15b82687e05a624e5f5cba3f1d6c20cb81172d70ea498451e", size = 1576224, upload-time = "2026-06-01T19:38:13.391Z" },
-    { url = "https://files.pythonhosted.org/packages/0b/f9/b9fc381dd9b66afb33f2634c40e229d106467be0afcabe79648631ab6712/aiohttp-3.14.0-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:f0b7b8bbbec3ce9467ee0ebe334622fd90624f593edd3136c567811453fc4fae", size = 1794252, upload-time = "2026-06-01T19:38:15.498Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/fb/05d9214c975f23225a8cd5c439325e338c7c377b315480ef3871db51f54e/aiohttp-3.14.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:5ba10966d4f03dd96a14365be4b8e37c327c76f11c3ca867116966cdd9f98066", size = 1760193, upload-time = "2026-06-01T19:38:17.624Z" },
-    { url = "https://files.pythonhosted.org/packages/d9/4b/02992fc4fb9e1b6673ee3f888a8e587a6447afda1f6f4aca776c148c2876/aiohttp-3.14.0-cp312-cp312-win32.whl", hash = "sha256:101df7779c80c0636014a6b2c6642acd3efb5b355d48347c9d7dfb720aee9430", size = 448650, upload-time = "2026-06-01T19:38:19.545Z" },
-    { url = "https://files.pythonhosted.org/packages/39/e9/246532214c3abda518477cbaaf16d420295ad8effa5233844cbb38f299ab/aiohttp-3.14.0-cp312-cp312-win_amd64.whl", hash = "sha256:b0a5747586d4467efd1f932710b269131c9717a872dce082cd92a00c1c13123a", size = 476145, upload-time = "2026-06-01T19:38:21.505Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/c3/63f8c20090048915711598b0adf475b149216d736157961de06480a45b15/aiohttp-3.14.0-cp312-cp312-win_arm64.whl", hash = "sha256:5f1c5be60add78fabb4aacd13c5a348ae79d2fcbfc7fa78da8f1eb192273b370", size = 444250, upload-time = "2026-06-01T19:38:24.027Z" },
-    { url = "https://files.pythonhosted.org/packages/21/61/d11f7d9a3144bffe825247d6367cd93053666da50b94707c9129c78868d5/aiohttp-3.14.0-cp313-cp313-android_21_arm64_v8a.whl", hash = "sha256:25400d710641a8040bf022a8a99f579e581ffa1c5bd42c33255d7d6f3957c127", size = 502399, upload-time = "2026-06-01T19:38:25.955Z" },
-    { url = "https://files.pythonhosted.org/packages/4f/9b/a7e317625d36356844f8bb022cabd305b541f968856cc3c2e0b58e53ee6e/aiohttp-3.14.0-cp313-cp313-android_21_x86_64.whl", hash = "sha256:c5492b9929826e07cc3fcb9739ae87aab05dff6b5e67a9b73fd1700c6d008981", size = 510068, upload-time = "2026-06-01T19:38:27.828Z" },
-    { url = "https://files.pythonhosted.org/packages/11/41/cc2d2cfbfbdc3126ba258f3cd27d1ac8a33492ae3c35a4583ee21f0ba7f1/aiohttp-3.14.0-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:3366751d68d237c621264233a32f3078bbc21b7904ab90a77e03d21390c742c6", size = 481670, upload-time = "2026-06-01T19:38:29.836Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/07/381f4023c3b08cb616e520f566d8c58957abad54e56441d41fe67cfb0195/aiohttp-3.14.0-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:57ea07d28695a7a40304d42251892a8df765e5588c10ee32afeddcd5df33c0a2", size = 487591, upload-time = "2026-06-01T19:38:31.704Z" },
-    { url = "https://files.pythonhosted.org/packages/fb/4d/4506fdb7a022bdf70011a3bbb4ca00c5c570026ef6a3c5bd7bc70c39089c/aiohttp-3.14.0-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:076cb014191ae2e65d949e1ad01f1dcfe33e32789b5172510f3e79c79fc04d50", size = 496503, upload-time = "2026-06-01T19:38:33.6Z" },
-    { url = "https://files.pythonhosted.org/packages/ef/7d/c814111e04894a45d9e2defc94443879a6f118d9633d5fedfe6e2e8af5f0/aiohttp-3.14.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:2f3fc37054564dee64a855b5b092d87ec35dcddfaabf7dacb1c8a2b1f83dc0a9", size = 745870, upload-time = "2026-06-01T19:38:36.013Z" },
-    { url = "https://files.pythonhosted.org/packages/c6/ee/80eee0efddfe187e7cd05027086b7ce1c0e492e82a4eda58f5c5543a44a0/aiohttp-3.14.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8fcaef74d2ab0f607d7ff85a0d15e21bb5a258c4a58df1908396eb50d7f4ed3c", size = 505588, upload-time = "2026-06-01T19:38:38.282Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/f8/0f28f04eef75d52fc9c715dde7ce9c0abb810fd20cfeb0fea7afd2ab1e98/aiohttp-3.14.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e4c01b0bfc6209590960e68eac083cd22d5d87c21f974dd6208cafa5d3542bc8", size = 504492, upload-time = "2026-06-01T19:38:40.611Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/db/44c755232085545065c94378dfce38641b1aee647f4939fcd32f5b32e719/aiohttp-3.14.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f12eb7896e81caf403a2b18c9406426f1207361e7239c057ab29c076d4257e83", size = 1752111, upload-time = "2026-06-01T19:38:42.682Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/6a/42e030a46743841414402a3b00cd3d78419055e86c66fb5822c14b5abfc6/aiohttp-3.14.0-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:6c79a044cacf360ec46738d863d2f41c9300d2a06ef4a7402ea0df306a350e61", size = 1729674, upload-time = "2026-06-01T19:38:44.79Z" },
-    { url = "https://files.pythonhosted.org/packages/34/26/3199beb415202e3108e7b83ecebe10914d806d33fb9860c3e4aa60a19be3/aiohttp-3.14.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:85e0675f47be4eff0636bf88c02140ea89168ae0df3ff1f3f464e9de9610d277", size = 1798808, upload-time = "2026-06-01T19:38:47.01Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/94/b9b6fcf0ee17c21d0d19fb8c22bf83ad18f82e702a9c3bd901a868f5e446/aiohttp-3.14.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:7b33e751cab03fdc960095b1e326cb5a03f5ee577d6ded59f3d1c100f8668882", size = 1891921, upload-time = "2026-06-01T19:38:49.233Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/a3/3800dbd095cb2bb165a7ea5d94d790914677e27f45638c7d80e3f34c8945/aiohttp-3.14.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:26d9224c6dd7f5c749aba4f61315a894601448b28d94d12f4dea0903e26d2096", size = 1777241, upload-time = "2026-06-01T19:38:52.04Z" },
-    { url = "https://files.pythonhosted.org/packages/21/2a/45be91ad1b860508557448d4cc2e165a2ee68dd865657b73bf66cc5a00fb/aiohttp-3.14.0-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:6281aecdf2732940f4fe06bd6adec5ae4d59b78b080b8e3a6b81467301010988", size = 1579554, upload-time = "2026-06-01T19:38:54.508Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/3d/dc94df99ed1511fdf28314f722643ed334112643cab00223577085e788c4/aiohttp-3.14.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:23e8314e7aed8576fbe33314d218bd81447a3adbc91dc36f1163bf583cd3084c", size = 1714864, upload-time = "2026-06-01T19:38:56.788Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/e4/1f1c8acbb3acd5c8f795473b92c9c3d44eb60a5692c6104256c8a1c83a0c/aiohttp-3.14.0-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:3b54fbff46127aeafdd764cecd0d99fa2f24a0e37ea5c18a7c3a4ac450df1db3", size = 1749803, upload-time = "2026-06-01T19:38:59.367Z" },
-    { url = "https://files.pythonhosted.org/packages/0b/c8/c45ea6e7ed84cebba939b9c334498a045ba19d79c61b0110df5f21580de3/aiohttp-3.14.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:b27d89af91a555f58e08e4902dbcbc48862fd40095720ca705990476bd93b7ac", size = 1765023, upload-time = "2026-06-01T19:39:01.651Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/a1/a932941784432962fe390e1066823aaef64b4e5ac9fa595df57b5fe472a9/aiohttp-3.14.0-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:25d2326a4967bf705a9f9913a13005e93b6020ad8a9f6bd6bd78850d5171332e", size = 1571671, upload-time = "2026-06-01T19:39:04.044Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/01/e1280feac522597a4d46eb67a0cdfa053cfae263033030b761ab146f29fb/aiohttp-3.14.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:a1d209375c503472b3c0a340cdf3c55fcd82e84b46dda7caeaced59faba373ec", size = 1789904, upload-time = "2026-06-01T19:39:06.294Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/10/ab28818262f4d26bdb47ed5f1fc7999b69e2fc6e0370b02d0f49011f45ea/aiohttp-3.14.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:666c7c5036df57b693026398b69b41874a1931ac5b3485fd910e57bfac253869", size = 1754516, upload-time = "2026-06-01T19:39:08.788Z" },
-    { url = "https://files.pythonhosted.org/packages/af/cc/c122eabd7a1b7e0c9bbdd6be60e4715905b858399145d9df872bb94f1427/aiohttp-3.14.0-cp313-cp313-win32.whl", hash = "sha256:23f094a1ef64823fd35854ddf5c7a80a078162f37f9d2f7c6142b51a6affa456", size = 448656, upload-time = "2026-06-01T19:39:11.171Z" },
-    { url = "https://files.pythonhosted.org/packages/41/a5/bab07d79848a00eedd8ed979ccb302aaea3ac6eb9fa16bd0ed87135869b4/aiohttp-3.14.0-cp313-cp313-win_amd64.whl", hash = "sha256:e03abdaa17d553f17e1d1d06bb266b3970106c78051d06795723e748d8e49d11", size = 475803, upload-time = "2026-06-01T19:39:13.439Z" },
-    { url = "https://files.pythonhosted.org/packages/d1/a0/f03ade8566c153666a3871afccbedf6d99911da006325e1fc6cf72a2de99/aiohttp-3.14.0-cp313-cp313-win_arm64.whl", hash = "sha256:acdb400538cf4769543548bb5d1eb23d39bed4f96554a6078cb728c7cb2c268b", size = 443889, upload-time = "2026-06-01T19:39:15.945Z" },
-    { url = "https://files.pythonhosted.org/packages/28/03/5f36ab196a88ba5e9648ae5643e6531e67a3a8c0e96f9c6510ff41540fec/aiohttp-3.14.0-cp314-cp314-android_24_arm64_v8a.whl", hash = "sha256:363ef9e91014e7891679bfb2ac0a7c6ea93435dbbfd10ecf41b9f06fcf506c5f", size = 503330, upload-time = "2026-06-01T19:39:18.195Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/ce/8b49ec2f30f68e02f314f4832186cd45e583360a5a386058be36855d23b6/aiohttp-3.14.0-cp314-cp314-android_24_x86_64.whl", hash = "sha256:884a4edbdad77be9d0ef36142c8b504351b170df0bf62b51e784fadabf311c42", size = 509822, upload-time = "2026-06-01T19:39:20.396Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/fe/6edbf5d39bf29322b6816365b17ed8ede4dace164a3aea1abcd30110eb78/aiohttp-3.14.0-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:70ea956f6cc4a37620966b56c2e205d88ca3e6d85ec063277e414b1035cddad3", size = 483329, upload-time = "2026-06-01T19:39:22.607Z" },
-    { url = "https://files.pythonhosted.org/packages/1b/5a/fae531bdbc6456fb6241f46b7b81e4d8a0dd3fc09118a0055dc7141ac1ec/aiohttp-3.14.0-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:ea3b9806c89f61da22fddf1f12dd524fb368e5e28f1261fbdafe5c3cd8ce893b", size = 489502, upload-time = "2026-06-01T19:39:24.881Z" },
-    { url = "https://files.pythonhosted.org/packages/36/f4/48a7b0414db7fed77a03d5dde34508c026afd83510ab6bca08c313855776/aiohttp-3.14.0-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:a071be341c2bd9b0188e62d173509f024e0a35b1c342c53c50f8daaeda8c3bd8", size = 497357, upload-time = "2026-06-01T19:39:27.197Z" },
-    { url = "https://files.pythonhosted.org/packages/75/75/e85a13a370acc007fca5feb1fd1b88ac2d8426e6dadd625479b7cadd55a3/aiohttp-3.14.0-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:198cfe61bf253b19da1fb3e0fa122249dc4f14c12709493fed8054aa0411cc76", size = 750898, upload-time = "2026-06-01T19:39:29.563Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/e4/3d637f800c724eff0e2bed64df72557444482366fd0a35b0cec0e6968f6c/aiohttp-3.14.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:9dc203d6ce6b9106d54e2a93f41dfdfebfbca2d99962ba503bfd3e5921a6549e", size = 506986, upload-time = "2026-06-01T19:39:31.872Z" },
-    { url = "https://files.pythonhosted.org/packages/1d/df/35161f3598bf7501d2b2a805b41ab4f45a2e34150c421bcb4ef8c0d281a7/aiohttp-3.14.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:9e19d17ab02bf16832a2c8c0d55a486792c5b1645665652ee9531aebcc30cb72", size = 508033, upload-time = "2026-06-01T19:39:34.137Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/39/b36e5d3d31e850fb4691dd3e941684ac490a2559249f6fa634b6b0fdf020/aiohttp-3.14.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d925fba0c14d5b498a8028b0107beebdfd16c5d48d702ff54f879cb017aaaca3", size = 1746213, upload-time = "2026-06-01T19:39:36.654Z" },
-    { url = "https://files.pythonhosted.org/packages/b1/28/24e1409e605a9aa5d84abe0e2acb365354b70ae56d40948101cabe3341ab/aiohttp-3.14.0-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:d33e61021222ce7f9792bcac870d6f58d8adfceda33ab857b01264f4560f2c5f", size = 1705862, upload-time = "2026-06-01T19:39:38.968Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/d0/e5eb3ff1daeaf644c7e36a957517672494122628e067c38b263fa04eda77/aiohttp-3.14.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:44eca38755d0105bb32f47d085f5dd449846a449e1245fc105889e3279dcf8e3", size = 1798909, upload-time = "2026-06-01T19:39:41.334Z" },
-    { url = "https://files.pythonhosted.org/packages/d3/ba/8943f906f0570342886ababb9a722a44e360f786a028c5e0b0e29e3f735b/aiohttp-3.14.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f13087e06f68fea4941c21a0c541c00553aa16e4f8fd7bbe2b198df761e964d6", size = 1868892, upload-time = "2026-06-01T19:39:43.807Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/05/27df32c844b2156e1675a8d8ec22d963e3c8ba469ed7ceb1863320c7b521/aiohttp-3.14.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ff82be7f1ef73634cb77890a770743239bc3d487b848669be1c599889336dc0a", size = 1751659, upload-time = "2026-06-01T19:39:46.398Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/62/da182e5910ab912b2e88aa919b61a16046a37a95714a5795b02eb57b2d18/aiohttp-3.14.0-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:a150c0875ac8fd87f1c398650841308a30d65facf7416b12dbdb9cfdcbe5a48c", size = 1578775, upload-time = "2026-06-01T19:39:48.902Z" },
-    { url = "https://files.pythonhosted.org/packages/66/e3/53c67097e8a5ce98625e91e3fa7f43c9c6940de680345d03b3509a72a078/aiohttp-3.14.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:edc01ea4e1ec5a1649a28866262bf24195889ff7b27bdd947029a6086741de9b", size = 1710090, upload-time = "2026-06-01T19:39:51.392Z" },
-    { url = "https://files.pythonhosted.org/packages/dd/55/0e2732ca598c7a4dfe8a775662376d0ca2977cb1030e48386d4da5d9a456/aiohttp-3.14.0-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:540632bf882ff8fc88f2e1697be0761578e89e0d79fb4a8a6d65dc5da7e729d4", size = 1715016, upload-time = "2026-06-01T19:39:53.807Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/96/f0b73730798c9ca525afc30b39f1f81bbe24e245d9654c54d3b39d63212d/aiohttp-3.14.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:860a86bc2c80237f5dff52edcf427e10a8d8352271fd84845429a3e60199e02c", size = 1763810, upload-time = "2026-06-01T19:39:56.31Z" },
-    { url = "https://files.pythonhosted.org/packages/71/cc/11acb6c4518f448323405a7312b6f255d0f974a34373ad1db7633c4aadc8/aiohttp-3.14.0-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:5cbd50e6a50d6b99283a826b18cbdebf65b0797689a7535cb0e9dd37be0f63c3", size = 1573064, upload-time = "2026-06-01T19:39:58.718Z" },
-    { url = "https://files.pythonhosted.org/packages/de/2d/28c31dde0a7dc98c0ee7d0da2ddcec3f7688c4fc131e5989e278d0c03c0a/aiohttp-3.14.0-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:20144819e99db593e22bbd2f3f2691a5e149f879142d6b8670254708853ff4fb", size = 1775765, upload-time = "2026-06-01T19:40:01.195Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/69/155c4ef3aec96417d47024800472b33b16c5d8a665371dcd044c2afdf25d/aiohttp-3.14.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:26b6d79aa54cb4ed50cc7d41ed14e99e0f1fc8e7c2d42f2e05b37aea897b2b52", size = 1733716, upload-time = "2026-06-01T19:40:03.631Z" },
-    { url = "https://files.pythonhosted.org/packages/5f/44/6126116fd8a316b712bb615660b855c78466bb67ba1bb1742427eafcf7ac/aiohttp-3.14.0-cp314-cp314-win32.whl", hash = "sha256:106ed074a856f3e21d186b8579e2c8afb6da598e267cdaab01059e13db2fc44d", size = 453684, upload-time = "2026-06-01T19:40:06.277Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/d7/eff4c58a88c5cac5e38b55f44fb8a6d3929c3cbd77356e383e094d3220bd/aiohttp-3.14.0-cp314-cp314-win_amd64.whl", hash = "sha256:4f770846edae8f00ecc57af825bce811f787f87a7dcf0e90d191790efe5b31f7", size = 481758, upload-time = "2026-06-01T19:40:08.653Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/ed/17b5bd9fbcb46e688f02e572f517754a9a75831e7b54702f027761dc4fa5/aiohttp-3.14.0-cp314-cp314-win_arm64.whl", hash = "sha256:acf1581c4f21ed4b80a2dded504d87b055a071a84d5737ea966435f768275ac6", size = 450557, upload-time = "2026-06-01T19:40:11.03Z" },
-    { url = "https://files.pythonhosted.org/packages/12/34/6180103ce9aabc8ebff3f7bb55a1228ffe60f61042823031d9692cb7b101/aiohttp-3.14.0-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:6aa1a40f9cbb3da9f80714c5966b8946c21e6a2530d809b9498b33161e3c8733", size = 787878, upload-time = "2026-06-01T19:40:13.401Z" },
-    { url = "https://files.pythonhosted.org/packages/92/e9/08954a40e8b7baa3d8beadd2b074b186e9b1e9c8ddabc288678a6265de50/aiohttp-3.14.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:b62af5a8cc96a194eaa01a9ed7b34a3ffa58d3d8daaa1a0d7a749353ad12d228", size = 524400, upload-time = "2026-06-01T19:40:15.972Z" },
-    { url = "https://files.pythonhosted.org/packages/08/6a/b5965a634ac4d5ba99a463314cf4ab214ca073fcdc38a15e0294273701fc/aiohttp-3.14.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:6eb63b1417efaf7d1002a6ad034a40d44376afcc16508a57f8e74b49ad26a095", size = 527904, upload-time = "2026-06-01T19:40:18.28Z" },
-    { url = "https://files.pythonhosted.org/packages/06/b4/932bcdd850c354d9bcca30f360e475d7852e30413fbbd44b182782ed5432/aiohttp-3.14.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c20b9ad156a79eb97be5cf9e069eec01d2f0dc8472ffbd75299a8b2d4c2cbbde", size = 1912162, upload-time = "2026-06-01T19:40:20.825Z" },
-    { url = "https://files.pythonhosted.org/packages/c6/85/ce79bab0310d2e3fd2d7bc7e44412abeff7c8338f8a21dd0f2f1714989e5/aiohttp-3.14.0-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:40ae7b0642c25632c7eabc4a04754012691864d2a1b93becf7cddb76027b838a", size = 1778813, upload-time = "2026-06-01T19:40:23.726Z" },
-    { url = "https://files.pythonhosted.org/packages/05/54/ba62ac2d1bc87e010aad23751e383b8794e45d931df67677313a2da78823/aiohttp-3.14.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:95f5217e76a046b9f228a101717ef8d42b1eb3d9d196d15202db5bf41df88936", size = 1899969, upload-time = "2026-06-01T19:40:26.406Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/82/7cc7907725d83a19f31551334061e1ab8e108b1d7ac52632a2a844a4acb5/aiohttp-3.14.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:1a4a9f17e85b80878c176695c1998c790e83731d8271881e5d356488652a1f9e", size = 1991771, upload-time = "2026-06-01T19:40:29.061Z" },
-    { url = "https://files.pythonhosted.org/packages/d0/1c/a57de71a4508c93a830b77c28af3d08cd97f606dedfc6b94275347744508/aiohttp-3.14.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:145262119b07d7f95abc1839add35ba2bfc84551d4b4660ca11542c0b215455b", size = 1868606, upload-time = "2026-06-01T19:40:31.843Z" },
-    { url = "https://files.pythonhosted.org/packages/9c/ae/3839726cd49150a53ed340cc24ce5ba09d4c2117020ef9d45542bec5eb2f/aiohttp-3.14.0-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:49a33ded29b0b2fa7a367a02cf0fb89af602bb87542a16177ec8ce1c9c51d12a", size = 1665437, upload-time = "2026-06-01T19:40:35.01Z" },
-    { url = "https://files.pythonhosted.org/packages/35/1e/c237923232c7da7f0392ea25d89fc5e60c0e93f685f4ebca8e7bcdd5271c/aiohttp-3.14.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:2cc736a9c9fc2bc4dd71fd404815741b6573df27c3f985948ec4076989ac57de", size = 1834090, upload-time = "2026-06-01T19:40:37.733Z" },
-    { url = "https://files.pythonhosted.org/packages/98/02/a5a7a2524f92d3911761b405a7c067c751891942144adc13e2ad79611e39/aiohttp-3.14.0-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:b4141a3e5342ee3053a9cab54d25b64ed28289c1041e4c54b3d99839314d90ce", size = 1816907, upload-time = "2026-06-01T19:40:40.46Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/76/a8b9f0d09234d516af9f2d7dd715557f33b5da3b0b56ead41d1170e86e3c/aiohttp-3.14.0-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:e30871b2d58996cb81aac52d2b1d15ac05257131ef0f90f18c2115a380fbfe7c", size = 1840382, upload-time = "2026-06-01T19:40:43.48Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/8e/140e715a0a4bbc211979ea30ec8396ad2ed5bf90ab87d8058fc4668b1923/aiohttp-3.14.0-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:667b881d083ccae3900ea5a241e17e5007ca78844c53ed389bb63d48f729d9c7", size = 1659497, upload-time = "2026-06-01T19:40:46.265Z" },
-    { url = "https://files.pythonhosted.org/packages/10/c7/7ba5de8af9650b9767b063c675427b8685f43fa7ce563673a7bc3af60f08/aiohttp-3.14.0-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:b584dfe615d151e9b8f0a8ecb3aee6147f2927ec5b95ba25fe621f5377510928", size = 1870829, upload-time = "2026-06-01T19:40:49.583Z" },
-    { url = "https://files.pythonhosted.org/packages/cc/bc/2aaab2f85cadb26ea59c091fa2b8e370d625154b5c14b478f1b489d07551/aiohttp-3.14.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6199707cc40e0e9cd39c36fbc97bec416c704e1d0ddce03412bb3b3e6a90ccd0", size = 1832281, upload-time = "2026-06-01T19:40:52.303Z" },
-    { url = "https://files.pythonhosted.org/packages/39/98/31b9ad9fbc01f0075ee7221002df5fd2d10b647f451ca5f30edc802d9dd6/aiohttp-3.14.0-cp314-cp314t-win32.whl", hash = "sha256:a8d93334d4961c9d566b1f046c81dee475b7c21eb730728d38237bfa70d1c8e6", size = 490597, upload-time = "2026-06-01T19:40:54.937Z" },
-    { url = "https://files.pythonhosted.org/packages/59/1f/299b21441c8de42ff70fddc7cfe65e92f810abcf740739a09b56f7835364/aiohttp-3.14.0-cp314-cp314t-win_amd64.whl", hash = "sha256:2d2ffe9b614f50f069068b3b52e73414e4107fc10b7efc939a76acff9251fdd2", size = 525789, upload-time = "2026-06-01T19:40:57.306Z" },
-    { url = "https://files.pythonhosted.org/packages/70/11/7f83fcba9ee05d4c54d61b3f8104da0d43a59adac44dd28effc0c9a10422/aiohttp-3.14.0-cp314-cp314t-win_arm64.whl", hash = "sha256:7a3fc4358e65826c515350f199c210de747cf669998211b1ee6c2e46de364b24", size = 467399, upload-time = "2026-06-01T19:40:59.993Z" },
+    { url = "https://files.pythonhosted.org/packages/26/dd/bf526e6f0a1120dd6f2df2e97bacfe4d358f13d17a0ff5847301a1375a51/aiohttp-3.14.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:aa00140699487bd435fde4342d85c94cb256b7cd3a5b9c3396c67f19922afda2", size = 765225, upload-time = "2026-06-07T21:06:07.957Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/e1/a2872aa55495a70f61310d411541c6ee23812d9a884e000c716e1bc3edbf/aiohttp-3.14.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:1c1af67559445498b502030c35c59db59966f47041ca9de5b4e707f86bd10b5f", size = 518743, upload-time = "2026-06-07T21:06:09.749Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/e7/c60c7b209e509cc787de3cea0550a518538cfc08003e1c1e14c1c63fff71/aiohttp-3.14.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:d44ec478e713ee7f29b439f7eb8dc2b9d4079e11ae114d2c2ac3d5daf30516c8", size = 514139, upload-time = "2026-06-07T21:06:11.26Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/8d/614ace2f579702c9840ab1e1447fd8509e35b0b904f7196418fa2f57b25d/aiohttp-3.14.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d3b1a184a9a8f548a6b73f1e26b96b052193e4b3175ed7342aaf1151a1f00a04", size = 1784088, upload-time = "2026-06-07T21:06:12.887Z" },
+    { url = "https://files.pythonhosted.org/packages/49/e0/726e90f99542bf292f81a96a12cc4847deb86f3ccf62c6f4014a201f4d33/aiohttp-3.14.1-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:5f2504bc0322437c9a1ff6d3333ca56c7477b727c995f036b976ae17b98372c8", size = 1737835, upload-time = "2026-06-07T21:06:14.564Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/4b/d176d5c4db9d33dacf0543102ea59503bc1d528af4cfd0b719949ca49389/aiohttp-3.14.1-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:73f05ea02013e02512c3bf42714f1208c57168c779cc6fe23516e4543089d0a6", size = 1842801, upload-time = "2026-06-07T21:06:16.228Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/d6/5a99b563690ea0cbed912ae94a2ce33993a5709a651a3a4fe761e7dd973a/aiohttp-3.14.1-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:797457503c2d426bee06eef808d07b31ede30b65e054444e7de64cad0061b7af", size = 1929992, upload-time = "2026-06-07T21:06:17.947Z" },
+    { url = "https://files.pythonhosted.org/packages/76/7f/a987b14a3859094b3cea3f4825219c3e5536242564af6e3f9c2f6c994eb2/aiohttp-3.14.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b821a1f7dedf7e37450654e620038ac3b2e81e8fa6ea269337e97101978ec730", size = 1786989, upload-time = "2026-06-07T21:06:19.677Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/1a/420e5c85a3e73349372ed22ce0b6af86bfa6ce16a4b20a64a2e94608c781/aiohttp-3.14.1-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:4cd96b5ba05d67ed0cf00b5b405c8cd99586d8e3481e8ee0a831057591af7621", size = 1640129, upload-time = "2026-06-07T21:06:22.558Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/80/18a592ed3be0a402cc03670bd72ee1f8563ddbe1d8d5542dbf868f274136/aiohttp-3.14.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:1d459b98a932296c6f0e94f87511a0b1b90a8a02c30a50e60a297619cd5a58ee", size = 1756576, upload-time = "2026-06-07T21:06:24.8Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/0b/8b3d5713373858ff71a617daf6e3b0e81ad63e79d09a3cf2f6b6b983939c/aiohttp-3.14.1-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:764457a7be60825fb770a644852ff717bcbb5042f189f2bd16df61a81b3f6573", size = 1754668, upload-time = "2026-06-07T21:06:26.528Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/49/fd564575cf225821d7ba5a117cb8bc27213d8a7e1811162afb43ae077039/aiohttp-3.14.1-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:f7a16ef45b081454ef844502d87a848876c490c4cb5c650c230f6ec79ed2c1e7", size = 1817019, upload-time = "2026-06-07T21:06:28.297Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/1b/e850c9ae6fc91356552ae668bb6c51e93fa29c8aef13398a10b56678557f/aiohttp-3.14.1-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:2fbc3ed048b3475b9f0cbcb9978e9d2d3511acd91ead203af26ed9f0056004cf", size = 1631638, upload-time = "2026-06-07T21:06:30.242Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/94/3c337ba72451a89806ace6f75bddc92bafc5b8d53d90115a512858024b63/aiohttp-3.14.1-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:bedb0cd073cc2dc035e30aeb99444389d3cd2113afe4ef9fcd23d439f5bade85", size = 1835660, upload-time = "2026-06-07T21:06:31.943Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/9c/9c18cf367a0498212d9ba7daf990b504a5e8ae064cda4b504e2647c89c03/aiohttp-3.14.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:b6feea921016eb3d4e04d65fc4e9ca402d1a3801f562aef94989f54694917af3", size = 1775698, upload-time = "2026-06-07T21:06:33.72Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/63/a251a9d2a6cb45065b2ddc0bde2b3dd10108740a9a42f632c66405a761a2/aiohttp-3.14.1-cp311-cp311-win32.whl", hash = "sha256:313701e488100074ce99850404ee36e741abf6330179fec908a1944ecf570126", size = 458386, upload-time = "2026-06-07T21:06:35.279Z" },
+    { url = "https://files.pythonhosted.org/packages/17/ca/69274c51dcd6e8947d77b2806cf47a4a15f2c846e2cbeb1882547d3da283/aiohttp-3.14.1-cp311-cp311-win_amd64.whl", hash = "sha256:03ab4530fdcb3a543a122ba4b65ac9919da9fe9f78a03d328a6e38ff962f7aa5", size = 483406, upload-time = "2026-06-07T21:06:36.824Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/8a/c25904f77690c3688ec140f87591ef11a0cfe36bf3d5c0f1f38056fb62b3/aiohttp-3.14.1-cp311-cp311-win_arm64.whl", hash = "sha256:486f7d16ed54c39c2cbd7ca71fd8ba2b8bb7860df65bd7b6ed640bab96a38a8b", size = 452987, upload-time = "2026-06-07T21:06:38.371Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/21/151624b51cd92553d95424daf4bf19f19ce9be9002d19253e7e7ce67197b/aiohttp-3.14.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:d35143e27778b4bb0fb189562d7f275bff79c62ab8e98459717c0ea617ff2480", size = 757402, upload-time = "2026-06-07T21:06:40.311Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/82/280619e0bd7bf2454987e19282616e84762255dd9c8468f62382e8c191f1/aiohttp-3.14.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:bcfb80a2cc36fba2534e5e5b5264dc7ae6fcd9bf15256da3e53d2f499e6fa29d", size = 512310, upload-time = "2026-06-07T21:06:42.207Z" },
+    { url = "https://files.pythonhosted.org/packages/55/b2/2aac325583aaa1353045f96dffa586d8a34e8322e14a7ba49cffeb103ab4/aiohttp-3.14.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:27fd7c91e51729b4f7e1577865fa6d34c9adccbc39aabe9000285b48af9f0ec2", size = 512448, upload-time = "2026-06-07T21:06:43.813Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/72/a60607cb849faa8af8a356c9329ea2eb6f395d49e82cc82ccba1fd8deb8f/aiohttp-3.14.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:64c567bf9eaf664280116a8688f63016e6b32db2505908e2bdaca1b6438142f2", size = 1766854, upload-time = "2026-06-07T21:06:45.391Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/d3/d9fe1c9ec7557ab4d0d82bebaa728c6418f0b93295ec2f4ab015f7710cc7/aiohttp-3.14.1-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:f5e6ff2bdbb8f4cd3fbe41f99e25bbcd58e3bf9f13d3dd31a11e7917251cc77a", size = 1740884, upload-time = "2026-06-07T21:06:47.413Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/dc/f2cecfaf9337ba3e63f181500814ff502aa3d00d9c7ec93a9d23d10a27b2/aiohttp-3.14.1-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2f73e01dc37122325caf079982621262f96d74823c179038a82fddfc50359264", size = 1810034, upload-time = "2026-06-07T21:06:50.165Z" },
+    { url = "https://files.pythonhosted.org/packages/66/d7/2ff65c5e65c0d7476daf7e15c032e0805e36811185b9623e3238ad6c763e/aiohttp-3.14.1-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:bb2c0c80d431c0d03f2c7dbf125150fedd4f0de17366a7ca33f7ccb822391842", size = 1904054, upload-time = "2026-06-07T21:06:52.035Z" },
+    { url = "https://files.pythonhosted.org/packages/20/9c/d445818389df371f56d141d881153ba23183c4735a03f7356ffb43f7757d/aiohttp-3.14.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:3e6fc1a85fa7194a1a7d19f44e8609180f4a8eb5fa4c7ed8b4355f080fad235c", size = 1790278, upload-time = "2026-06-07T21:06:54.049Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/aa/bf04cb4d865fc6101c2229a294ad744973b72e513fdc5a6b791e6983d72a/aiohttp-3.14.1-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:686b6c0d3911ec387b444ddf5dc62fb7f7c0a7d5186a7861626496a5ab4aff95", size = 1591795, upload-time = "2026-06-07T21:06:55.911Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/b4/4dac0038960427ba832f6609dfb4ea5437d7fd80c72001b9e48f834f428b/aiohttp-3.14.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:c6fa4dc7ad6f8109c70bb1499e589f76b0b792baf39f9b017eb92c8a81d0a199", size = 1728397, upload-time = "2026-06-07T21:06:57.777Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/f9/7cd4e8ad7aa3b75f17d56bb5498dd604a93d4e6eece822ba0568c413fff0/aiohttp-3.14.1-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:87a5eea1b2a5e21e1ebdbb33ad4165359189327e63fc4e4894693e7f821ac817", size = 1766504, upload-time = "2026-06-07T21:07:00.009Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/df/fc01d9fcad0f73fed3f3d361f1f94f975947b50dff82919f6dc2bf4316cc/aiohttp-3.14.1-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:1c1421eb01d4fd608d88cc8290211d177a58532b55ad94076fb349c5bf467f0a", size = 1777806, upload-time = "2026-06-07T21:07:02.064Z" },
+    { url = "https://files.pythonhosted.org/packages/41/09/47e2d090bddcc8fb4ccb4c314aadc32d7c5d9bb55f50f6ad1c92fc15d501/aiohttp-3.14.1-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:34b257ec41345c1e8f2df68fa908a7952f5de932723871eb633ecbbff396c9a4", size = 1580707, upload-time = "2026-06-07T21:07:03.942Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/36/f1a4ce904ae0b6930cfe9afc96d0896f7ec1a620c400405d63783bb95a9c/aiohttp-3.14.1-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:de538791a80e5d862addbc183f70f0158ac9b9bb872bb147f1fd2a683691e087", size = 1798121, upload-time = "2026-06-07T21:07:05.987Z" },
+    { url = "https://files.pythonhosted.org/packages/70/0a/e0075ce9ca0279ee1d4f0c0b85f54fea02ebc83c3007651a72bece658fec/aiohttp-3.14.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:6f71173be42d3241d428f760122febb748de0623f44308a6f120d0dd9ec572e3", size = 1767580, upload-time = "2026-06-07T21:07:07.873Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/61/a0c0a8f327a9c52095cdd8e312391b00d3ed64ab6c72bb5c33d8ec251cf7/aiohttp-3.14.1-cp312-cp312-win32.whl", hash = "sha256:ec8dc383ee57ea3e883477dcca3f11b65d58199f1080acaf4cd6ad9a99698be4", size = 452771, upload-time = "2026-06-07T21:07:09.669Z" },
+    { url = "https://files.pythonhosted.org/packages/df/d9/ea367c75f16ac9c6cdc8febb25e8318fa21a2b1bc8d6514d4b2d890bface/aiohttp-3.14.1-cp312-cp312-win_amd64.whl", hash = "sha256:2aa92c87868cd13674989f9ee83e5f9f7ea4237589b728048e1f0c8f6caa3271", size = 479873, upload-time = "2026-06-07T21:07:11.538Z" },
+    { url = "https://files.pythonhosted.org/packages/03/64/8d96784a7851156db8a4c6c3f6f91042fdf39fb15a4cc38c8b3c14833c45/aiohttp-3.14.1-cp312-cp312-win_arm64.whl", hash = "sha256:2c840c90759922cb5e6dda94596e079a30fb5a5ba548e7e0dc00574703940847", size = 448073, upload-time = "2026-06-07T21:07:13.637Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/97/bd137012dd97e1649162b099135a80e1fd59aaa807b2430fc448d1029aff/aiohttp-3.14.1-cp313-cp313-android_21_arm64_v8a.whl", hash = "sha256:b3a03285a7f9c7b016324574a6d92a1c895da6b978cb8f1deee3ac72bc6da178", size = 506882, upload-time = "2026-06-07T21:07:15.501Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/79/e5cc690e9d922a66887ceeaca53a8ffd5a7b0be3816142b7abc433742d89/aiohttp-3.14.1-cp313-cp313-android_21_x86_64.whl", hash = "sha256:2a73f487ab8ef5abbb24b7aa9b73e98eaba9e9e031804ff2416f02eca315ccaf", size = 515270, upload-time = "2026-06-07T21:07:17.53Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/22/a73ccbf9dbd6e26dda0b24d5fd5db7da92ee3383a79f47677ffb834c5c5b/aiohttp-3.14.1-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:915fbb7b41b115192259f8c9ae58f3ddc444d2b5579917270211858e606a4afd", size = 485841, upload-time = "2026-06-07T21:07:19.555Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/b9/57ed8eaf596321c2ad747bd480fb1700dbd7177c60dfc9e4c187f629662e/aiohttp-3.14.1-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:7fb4bdf95b0561a79f259f9d28fbc109728c5ee7f27aff6391f0ca703a329abe", size = 492088, upload-time = "2026-06-07T21:07:21.581Z" },
+    { url = "https://files.pythonhosted.org/packages/78/c0/5ebe5270a7c140d7c6f79dcb018640225f14d406c149e4eec04a7d82fe71/aiohttp-3.14.1-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:1b9748363260121d2927704f5d4fc498150669ca3ae93625986ee89c8f80dcd4", size = 501564, upload-time = "2026-06-07T21:07:23.388Z" },
+    { url = "https://files.pythonhosted.org/packages/75/7f/8cdaa24fc7983865e0915153b96a9ac5bcdd3548d64c5a27d17cecccad2d/aiohttp-3.14.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:86a6dab78b0e43e2897a3bbe15745aa60dc5423ca437b7b0b164c069bf91b876", size = 751998, upload-time = "2026-06-07T21:07:25.046Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/f4/c4227aacfacc5cb0cc2d119b65301d177912a6842cd64e120c47af76064f/aiohttp-3.14.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:4dfd6e47d3c44c2279907607f73a4240b88c69eb8b90da7e2441a8045dfd21da", size = 510918, upload-time = "2026-06-07T21:07:27.28Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/01/a2d5f96cd4e74424864d30bc0a7e44d0a12dacdcfa91b5b2d1bd3dca6bf3/aiohttp-3.14.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:317acd9f8602858dc7d59679812c376c7f0b97bcbbf16e0d6237f54141d8a8a6", size = 508657, upload-time = "2026-06-07T21:07:29.252Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/ed/3c0fb5c500fdd8e7ebc10d1889c04384fffa1a9163eac1356088ca9da1b1/aiohttp-3.14.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:bd869c427324e5cb15195793de951295710db28be7d818247f3097b4ab5d4b96", size = 1757907, upload-time = "2026-06-07T21:07:31.03Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/ab/d4c924d9bd5be3050c226612413ce68cb54c70d2c31b661bfc8d9a5b6a70/aiohttp-3.14.1-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:93b032b5ec3255473c143627d21a69ac74ae12f7f33974cb587c564d11b1066f", size = 1737565, upload-time = "2026-06-07T21:07:33.031Z" },
+    { url = "https://files.pythonhosted.org/packages/19/2a/37326821ff779084020cdc33224d20b19f42f4183a500ff92022a739eda7/aiohttp-3.14.1-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f234b4deb12f3ad59127e037bc57c40c21e45b45282df7d3a55a0f409f595296", size = 1799018, upload-time = "2026-06-07T21:07:35.003Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/4f/6e947ba73e4ce09070761c05ed3a8ceb7c21f5e46798671d8b2aac0e4626/aiohttp-3.14.1-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:9af6779bfb46abf124068327abcdf9ce95c9ef8287a3e8da76ccf2d0f16c28fa", size = 1894416, upload-time = "2026-06-07T21:07:36.956Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/6e/dbf1d0625dc711fb2851f4f3c3055c39ed58bae92082d8c627dbe6013736/aiohttp-3.14.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:faccab372e66bc76d5731525e7f1143c922271725b9d38c9f97edcc66266b451", size = 1783881, upload-time = "2026-06-07T21:07:39.063Z" },
+    { url = "https://files.pythonhosted.org/packages/44/c2/5e25098a67268ed369483ae7d1a58bd0a13d03aab860d2a0e4a6eb25b046/aiohttp-3.14.1-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f380468b09d2a81633ee863b0ec5648d364bd17bb8ecfb8c2f387f7ac1faf42c", size = 1587572, upload-time = "2026-06-07T21:07:41.058Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/bd/cf9cee17e140f942a3de73e658a543aa8fbf35a5fc67a9d2538d52d77f0b/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:97e704dcd26271f5bda3fa07c3ce0fb76d6d3f8659f4baa1a24442cc9ba177ca", size = 1722137, upload-time = "2026-06-07T21:07:43.014Z" },
+    { url = "https://files.pythonhosted.org/packages/89/6d/5684f8c59045c96f81a18cefbc1fbbd79d25b88f1c622f2a5c5c08fcb632/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:269b76ac5394092b95bc4a098f4fc6c191c083c3bd12775d1e30e663132f6a09", size = 1755953, upload-time = "2026-06-07T21:07:45.933Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/40/35caf3170f8359760740a7d9aa0fff2e344bef98e1d1186f5a0f6dec17e6/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:5c0b3e614340c889d575451696374c9d17affd54cd607ca0babed8f8c37b9397", size = 1766479, upload-time = "2026-06-07T21:07:48.047Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/a1/b0c61e7a137f0d81de49a82023a6df73c3c16d6fefb0f8e4a93d21639002/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:5663ee9257cfa1add7253a7da3035a02f31b6600ec48261585e1800a81533080", size = 1580077, upload-time = "2026-06-07T21:07:50.069Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/41/194ea4623693009fcefebef7aef63c141754f153e9cd0d39d3b9e36c175c/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:603a2c834142172ffddc054067f5ec0ca65d57a0aa98a71bc81952573208e345", size = 1791688, upload-time = "2026-06-07T21:07:52.106Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/45/4de841f005cfe1fd63e2a2fe011262c515e2a62aa6994b15947e7d717ac9/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:cb21957bb8aca671c1765e32f58164cf0c50e6bf41c0bbbd16da20732ecaf588", size = 1761094, upload-time = "2026-06-07T21:07:54.113Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/ae/dbce10533d3896d544d5053939ed75b7dc31a1b0973d959b1b5ae21028d6/aiohttp-3.14.1-cp313-cp313-win32.whl", hash = "sha256:e509a55f681e6158c20f70f102f9cf61fb20fbc382272bc6d94b7343f2582780", size = 452662, upload-time = "2026-06-07T21:07:56.06Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/d9/0bf1a19362c32f06229da5e7ddfcec91f93474d6307f7a2d3135e9c674dc/aiohttp-3.14.1-cp313-cp313-win_amd64.whl", hash = "sha256:1ac8531b638959718e18c2207fbfe297819875da46a740b29dfa29beba64355a", size = 479748, upload-time = "2026-06-07T21:07:58.319Z" },
+    { url = "https://files.pythonhosted.org/packages/22/0a/62e7232dc9484fbec112ceb32efb6a624cc7994ec6e2b019286f17c4e8f2/aiohttp-3.14.1-cp313-cp313-win_arm64.whl", hash = "sha256:250d14af67f6b6a1a4a811049b1afa69d61d617fca6bf33149b3ab1a6dbcf7b8", size = 447723, upload-time = "2026-06-07T21:08:00.154Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/a1/5fafa04e1ca91ddb47608699d60649c1c6db3cf41c99e78fc4056f9513db/aiohttp-3.14.1-cp314-cp314-android_24_arm64_v8a.whl", hash = "sha256:7c106c26852ca1c2047c6b80384f17100b4e439af276f21ef3d4e2f450ae7e15", size = 508531, upload-time = "2026-06-07T21:08:02.093Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/2e/bfa02f699d87ffc86d5959270b28f1cb410add3ccaced8ed2e0b8a5238fc/aiohttp-3.14.1-cp314-cp314-android_24_x86_64.whl", hash = "sha256:20205f7f5ade7aaec9f4b500549bbc071b046453aed72f9c06dcab87896a83e8", size = 514718, upload-time = "2026-06-07T21:08:04.476Z" },
+    { url = "https://files.pythonhosted.org/packages/85/a5/9594ad6289eebbc97d167c44213d557807f90e59115caad24de21ad2c3b1/aiohttp-3.14.1-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:62a759436b29e677181a9e76bab8b8f689a29cb9c535f45f7c48c9c830d3f8c3", size = 487918, upload-time = "2026-06-07T21:08:06.377Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/61/16a32c36c3c49edec122a3dc811f2057df2f94d3b14aa107c8017d981618/aiohttp-3.14.1-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:2964cbf553df4d7a57348da44d961d871895fc1ee4e8c322b2a95612c7b17fba", size = 494014, upload-time = "2026-06-07T21:08:08.263Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/89/3ebcf96ed99c05bec9c434aaac6963fd3cbab4a786ae739908a144d9ce44/aiohttp-3.14.1-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:237651caadc3a59badd39319c54642b5299e9cc98a3a194310e55d5bb9f5e397", size = 502398, upload-time = "2026-06-07T21:08:10.244Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/3d/b74870a0c2d40c355928cd5b96c7a11fa821b8a40fc41365e64479b151fb/aiohttp-3.14.1-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:896e12dfdbbab9d8f7e16d2b28c6769a60126fa92095d1ebf9473d02593a2448", size = 758018, upload-time = "2026-06-07T21:08:12.447Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/66/f42f5c984d99e49c6cff5f26f590750f2e2f7ef1fcfb99966ab5be1b632e/aiohttp-3.14.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:d03f281ed22579314ba00821ce20115a7c0ac430660b4cc05704a3f818b3e004", size = 512462, upload-time = "2026-06-07T21:08:14.624Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/a7/248e1aebe0c7810b0271e021a0f2a5eb6e78a051885b3c9df49f42a5802d/aiohttp-3.14.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:07eabb979d236335fed927e137a928c9adfb7df3b9ec7aa31726f133a62be983", size = 512824, upload-time = "2026-06-07T21:08:16.572Z" },
+    { url = "https://files.pythonhosted.org/packages/26/97/2aa0e5ba0727dc3bd5aaebb7ccbc510f7dfb7fb961ec87497cd496635ab1/aiohttp-3.14.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4fe1f1087cbadb280b5e1bb054a4f00d1423c74d6626c5e48400d871d34ecefe", size = 1749898, upload-time = "2026-06-07T21:08:18.635Z" },
+    { url = "https://files.pythonhosted.org/packages/00/8d/e97f6c96c891d457c8479d92a514ba194d0412f981d72c70341ee18488ed/aiohttp-3.14.1-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:367a9314fdc79dab0fac96e216cb41dd73c85bdca85306ce8999118ba7e0f333", size = 1710114, upload-time = "2026-06-07T21:08:20.892Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/e6/aa8d7e863048c8fceb5cd6ce74017311cec3ead07847387e12265fb4444e/aiohttp-3.14.1-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a24f677ebe83749039e7bdf862ff0bbb16818ae4193d4ef96505e269375bcce0", size = 1802541, upload-time = "2026-06-07T21:08:23.044Z" },
+    { url = "https://files.pythonhosted.org/packages/83/a8/72193137de57fda4ebfae4563182d082c8856e3b6e9871d0b46f028fb369/aiohttp-3.14.1-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c83afe0ba876be7e943d2e0ba645809ad441575d2840c895c21ee5de93b9377a", size = 1875776, upload-time = "2026-06-07T21:08:25.288Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/18/938441025db6769a3464596b2410af3afde0b21eb2f204c6f766f68af4bd/aiohttp-3.14.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:634e385930fb6d2d479cf3aa66515955863b77a5e3c2b5894ca259a25b308602", size = 1760329, upload-time = "2026-06-07T21:08:27.363Z" },
+    { url = "https://files.pythonhosted.org/packages/60/29/bf2496b4065e76e09fe48015aaffe5ce161d8f089b06ac6982070f653076/aiohttp-3.14.1-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:eeea07c4397bbc57719c4eed8f9c284874d4f175f9b6d57f7a1546b976d455ca", size = 1587293, upload-time = "2026-06-07T21:08:29.805Z" },
+    { url = "https://files.pythonhosted.org/packages/49/a2/2136674d52123b1354bd05dd5753c318db47dc0c927cc70b27bab3755456/aiohttp-3.14.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:335c0cc3e3545ce98dcb9cfcb836f40c3411f43fa03dab757597d80c89af8a35", size = 1714756, upload-time = "2026-06-07T21:08:32.094Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/b9/e5fd2e6f915503081c0f9b1e8540947037929c70c191da2e4d54b31a21a1/aiohttp-3.14.1-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:ae6be797afdef264e8a84864a85b196ca06045586481b3df8a967322fd2fa844", size = 1721052, upload-time = "2026-06-07T21:08:34.167Z" },
+    { url = "https://files.pythonhosted.org/packages/63/5a/2833e324a2263e104e31e2e91bc5bbee81bc499afd32203faee048a883f0/aiohttp-3.14.1-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:8560b4d712474335d08907db7973f71912d3a9a8f1dee992ec06b5d2fe359496", size = 1766888, upload-time = "2026-06-07T21:08:36.95Z" },
+    { url = "https://files.pythonhosted.org/packages/57/fa/dea6511870913162f3b2e8c42a7614eb203a4540b8c2da43e0bfb0548f3c/aiohttp-3.14.1-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:2b7edd08e0a5deb1e8564a2fcd8f4561014a3f05252334671bbf55ddd47db0e5", size = 1581679, upload-time = "2026-06-07T21:08:39.292Z" },
+    { url = "https://files.pythonhosted.org/packages/14/bd/3cf0d55e71784b33534e9710a67d382d900598b4787fbce6cc7317f8c42a/aiohttp-3.14.1-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:b6ff7fcee63287ae57b5df3e4f5957ce032122802509246dec1a5bcc55904c95", size = 1782021, upload-time = "2026-06-07T21:08:41.407Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/af/14bb5843eccbe234f4dfb78ab73e549d99727247e62ae5d62cbd22eaf5b0/aiohttp-3.14.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:6ffbb2f4ec1ceaff7e07d43922954da26b223d188bf30658e561b98e23089444", size = 1742574, upload-time = "2026-06-07T21:08:43.795Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/1e/fbeb7af9210a67ac0f9c9bec0f8f4568497924e33137a3d5b48e1cf85f3f/aiohttp-3.14.1-cp314-cp314-win32.whl", hash = "sha256:a9875b46d910cff3ea2f5962f9d266b465459fe634e22556ab9bd6fc1192eea0", size = 457773, upload-time = "2026-06-07T21:08:46.168Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/2b/13e8d741a9ec5db7d900c060554cf8352ab85e44e2a4469ebb9d377bda17/aiohttp-3.14.1-cp314-cp314-win_amd64.whl", hash = "sha256:af8b4b81a960eeaf1234971ac3cd0ba5901f3cd42eae42a46b4d089a8b492719", size = 485001, upload-time = "2026-06-07T21:08:48.401Z" },
+    { url = "https://files.pythonhosted.org/packages/df/30/491acfa2c4d6c3ff59c49a14fc1b50be3241e25bbb0c84c09e2da4d11395/aiohttp-3.14.1-cp314-cp314-win_arm64.whl", hash = "sha256:cf4491381b1b57425c315a56a439251b1bdac07b2275f19a8c44bc57744532ec", size = 453809, upload-time = "2026-06-07T21:08:50.7Z" },
+    { url = "https://files.pythonhosted.org/packages/34/e3/19dbe1a1f4cc6230eb9e314de7fe68053b0992f9302b27d12141a0b5db53/aiohttp-3.14.1-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:819c054312f1af92947e6a55883d1b66feefab11531a7fc45e0fb9b63880b5c2", size = 793320, upload-time = "2026-06-07T21:08:52.775Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/20/1b7182219ba1b108430d6e4dc53d25ae02dcfcf5a045b33af4e8c5167527/aiohttp-3.14.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:10ee9c1753a8f706345b22496c79fbddb5be0599e0823f3738b1534058e25340", size = 529077, upload-time = "2026-06-07T21:08:55Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/c8/14ce60ec31a2e5f5274bb17d383a6f7a3aabca31ac04eee05585bbadab16/aiohttp-3.14.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1601cc37baf5750ccacae618ec2daf020769581695550e3b654a911f859c563d", size = 532476, upload-time = "2026-06-07T21:08:57.176Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/02/9ac85e081e53da2e061b02fa7758fe0a12d17b8ce2d1f5e6c7cb76730328/aiohttp-3.14.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4d6e0ac9da31c9c04c84e1c0182ad8d6df35965a85cae29cd71d089621b3ae94", size = 1922347, upload-time = "2026-06-07T21:08:59.563Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/3e/d3ba07a0ab38b5389e10bec4362d21e10a4f667cba2d79ba30837b3a5059/aiohttp-3.14.1-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:9e8f2d660c350b3d0e259c7a7e3d9b7fc8b41210cbcc3d4a7076ff0a5e5c2fdc", size = 1786465, upload-time = "2026-06-07T21:09:01.909Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/cb/e2ee978a00cfb2df829704a69528b18154eba5939f45bc1efa8f33aee4c5/aiohttp-3.14.1-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:4691802dda97be727f79d86818acaad7eb8e9252626a1d6b519fedbb92d5e251", size = 1909423, upload-time = "2026-06-07T21:09:04.357Z" },
+    { url = "https://files.pythonhosted.org/packages/73/5d/1430334858b1022b58ae50399a918f0bd6fe8fa7fa183598d657ff61e040/aiohttp-3.14.1-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c389c482a7e9b9dc3ee2701ac46c4125297a3818875b9c305ddb603c04828fd1", size = 2001906, upload-time = "2026-06-07T21:09:06.722Z" },
+    { url = "https://files.pythonhosted.org/packages/66/4e/560c7472d3d198a23aa5c8b19a5115bf6a9b77b7d3e4bb363da320430ad2/aiohttp-3.14.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fc0cacab7ba4e56f0f81c82a98c09bed2f39c940107b03a34b168bdf7597edd3", size = 1877095, upload-time = "2026-06-07T21:09:09.011Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/f1/4745806578d447db4a784a8591e2dae3afdfc2bcb96f8f81271b13df6543/aiohttp-3.14.1-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:979ed4717f59b8bb12e3963378fa285d93d367e15bcd66c721311826d3c44a6c", size = 1676222, upload-time = "2026-06-07T21:09:11.461Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/c9/48255813cca749a229ef0ab476004ec623728ad79a9c0840616f6c076325/aiohttp-3.14.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:38e1e7daaea81df51c952e18483f323d878499a1e2bfe564790e0f9701d6f203", size = 1842922, upload-time = "2026-06-07T21:09:14.118Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/c0/bbd054e2bee909f529523a5af3891052606af5143c09f5f183ec3b234676/aiohttp-3.14.1-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:4132e72c608fe9fecb8f409113567605915b83e9bdd3ea56538d2f9cd35002f1", size = 1825035, upload-time = "2026-06-07T21:09:16.447Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/ae/90395d4376deceb74e09ec26b6adf7d2015a6f8802d6d84446af860fef04/aiohttp-3.14.1-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:eefd9cc9b6d4a2db5f00a26bc3e4f9acf71926a6ec557cd56c9c6f27c290b665", size = 1849512, upload-time = "2026-06-07T21:09:18.742Z" },
+    { url = "https://files.pythonhosted.org/packages/93/bd/fb25f3049957553d4ce0ba6ae480aa2f592a6985497fca590837d16c1be0/aiohttp-3.14.1-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:b165790117eea512d7f3fb22f1f6dad3d55a7189571993eb015591c1401276d1", size = 1668571, upload-time = "2026-06-07T21:09:21.458Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/22/7f73303d64dd567ff3addca90b556690ed1233a47b8f55d242fb90af3681/aiohttp-3.14.1-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:ed09c7eb1c391271c2ed0314a51903e72a3acb653d5ccfc264cdf3ef11f8269d", size = 1881159, upload-time = "2026-06-07T21:09:23.813Z" },
+    { url = "https://files.pythonhosted.org/packages/44/be/0474c5a8b5640e1e4aa1923430a91f4151be82e511373fe764189b89aef5/aiohttp-3.14.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:99abd37084b82f5830c635fddd0b4993b9742a66eb746dacf433c8590e8f9e3c", size = 1841409, upload-time = "2026-06-07T21:09:26.207Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/3c/bb4a7cba26956cb3da4553cc2056cf67be5b5ff6e6d8fa4fbdff73bfb7ae/aiohttp-3.14.1-cp314-cp314t-win32.whl", hash = "sha256:47ddf841cdecc810749921d25606dee45857d12d2ad5ddb7b5bd7eab12e4b365", size = 494166, upload-time = "2026-06-07T21:09:28.505Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/84/ec80c2c1f66a952555a9f86df6b33af65108a6febfa0471b69013a12f807/aiohttp-3.14.1-cp314-cp314t-win_amd64.whl", hash = "sha256:5e78b522b7a6e27e0b25d19b247b75039ac4c94f99823e3c9e53ae1603a9f7e9", size = 530255, upload-time = "2026-06-07T21:09:30.843Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/71/6e22be134a4061ada85a92951b842f2657f17d926b727f3f94c56ae963d6/aiohttp-3.14.1-cp314-cp314t-win_arm64.whl", hash = "sha256:90d53f1609c29ccc2193945ef732428382a28f78d0456ae4d3daf0d48b74f0f6", size = 469640, upload-time = "2026-06-07T21:09:33.028Z" },
 ]

 [[package]]
@@ -1,7 +1,7 @@
 {
  "name": "gitnexus",
  "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase.",
-  "version": "1.6.7",
+  "version": "1.6.8",
  "author": {
    "name": "GitNexus"
  },
@@ -15,7 +15,10 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { acquireHookSlot } = require('./hook-lock.js');
-const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
+const {
+  hasGitNexusDbLockedByGitNexusServer,
+  resolveUnixGuardTimeout,
+} = require('./hook-db-lock-probe.cjs');
 const { formatAnalyzeCommand } = require('./resolve-analyze-cmd.cjs');

 /**
@@ -110,10 +113,20 @@ function hasGitNexusServerOwner(gitNexusDir) {
  return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid);
 }

+/**
+ * Whether opt-in diagnostics should be written to the hook's stderr. Strict
+ * hook runners (e.g. Codex `PreToolUse`) validate hook output, so normal,
+ * non-error skip paths must stay silent unless the operator explicitly asks
+ * for diagnostics via GITNEXUS_DEBUG. See issue #1913.
+ */
+function isDebugEnabled() {
+  return process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+}
+
 function extractAugmentContext(stderr) {
  const output = (stderr || '').trim();
  const marker = output.indexOf('[GitNexus]');
-  const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+  const debug = isDebugEnabled();
  if (debug && output.length > 0) {
    // Emit the FULL discarded prefix (everything before the marker, or all of
    // it when no marker is present) so suppressed diagnostics — LadybugDB lock
@@ -186,18 +199,90 @@ function extractPattern(toolName, toolInput) {
  return null;
 }

+// Debounce for the unguarded-CLI diagnostic below (#2163 follow-up review):
+// at most one line per (short-lived) hook process, even if a future change
+// runs the CLI more than once.
+let unguardedCliWarned = false;
+
 /**
 * Spawn a gitnexus CLI command synchronously.
 * Detects binary on PATH once, then runs exactly once.
 *
 * SECURITY: Never use shell: true with user-controlled arguments.
 * On Windows, invoke gitnexus.cmd directly (no shell needed).
+ *
+ * Unix orphan containment (#2163 follow-up): the augment CLI is the
+ * longest-lived hook child (inner spawnSync timeout 7s locally, 12s via
+ * npx), so on Unix every CLI-running branch gets the same SIGKILL-surviving
+ * coreutils `timeout` wrapper as the probe's lsof/ps (the cheap which/where
+ * PATH check stays unwrapped). The wrapper budget is ceil(inner/1000)+1
+ * seconds — STRICTLY greater than the inner spawnSync timeout, so on the
+ * supervised path Node's SIGTERM always fires first and the existing
+ * error/status contract is untouched. Once the hook itself has been
+ * SIGKILLed (exactly the orphan case the wrapper exists for), the guard
+ * semantics differ per branch:
+ *   - direct exec (GITNEXUS_HOOK_CLI_PATH / PATH-installed `gitnexus`; the
+ *     CLI is the guard's CHILD): `-k 1` TERM-first — a SIGTERM-immune CLI
+ *     can hold the guard ~1s past the inner timeout before the `-k` SIGKILL
+ *     escalation reaps it.
+ *   - npx (the CLI is a GRANDCHILD: guard → npx → CLI): `-s KILL` — the
+ *     budget expiry SIGKILLs the whole process group outright. TERM-first
+ *     would kill only the obedient npx parent, making `timeout` reap it and
+ *     return before the `-k` escalation ever fires, stranding a
+ *     SIGTERM-immune CLI grandchild unbounded (reproduced on coreutils
+ *     9.x). `-k 1` is retained alongside `-s KILL` as a harmless belt: with
+ *     `-s KILL` the `-k` escalation signal is also KILL. Two residual gaps
+ *     on this branch, both bounded by "no worse than pre-fix" (where the
+ *     grandchild received no signal at all): the group-wide SIGKILL is
+ *     coreutils semantics — a busybox `timeout` passes the self-test (it
+ *     has `-k` and propagates exit status) but signals only its direct
+ *     child, so a busybox guard cannot reach the grandchild; and on the
+ *     SUPERVISED path (hook alive, inner spawnSync timeout SIGTERMs the
+ *     guard) coreutils forwards TERM rather than the `-s` signal, npx dies,
+ *     and the guard exits before any KILL fires — so a SIGTERM-immune CLI
+ *     grandchild still escapes in those two cases.
+ * If the sibling probe predates the resolveUnixGuardTimeout export (version
+ * skew), the adapter degrades to the unwrapped invocation instead of
+ * throwing. Windows is deliberately NOT wrapped — there is no coreutils
+ * timeout to resolve there and the resolver's self-test spawns /bin/sh — so
+ * on win32 (the gitnexus.cmd / npx.cmd paths) and whenever the guard
+ * resolves to null (e.g. macOS without Homebrew coreutils — reported once
+ * under GITNEXUS_DEBUG) the argv stays byte-identical to the pre-wrap
+ * invocation.
 */
 function runGitNexusCli(args, cwd, timeout) {
  const isWin = process.platform === 'win32';
+  // Version-skew guard (#2163 follow-up review): an older sibling probe
+  // without the resolveUnixGuardTimeout export must degrade to the unwrapped
+  // invocation — a TypeError here would be swallowed by the caller's catch
+  // and silently kill the augment.
+  const guard =
+    isWin || typeof resolveUnixGuardTimeout !== 'function' ? null : resolveUnixGuardTimeout();
+  if (!isWin && !guard && !unguardedCliWarned && isDebugEnabled()) {
+    // Diagnose the "stays unwrapped" Unix paths once per hook process: no
+    // usable coreutils timeout/gtimeout (e.g. macOS without Homebrew
+    // coreutils), GITNEXUS_HOOK_TIMEOUT_PATH=disabled, or probe skew above.
+    unguardedCliWarned = true;
+    process.stderr.write(
+      '[GitNexus hook] no usable timeout/gtimeout guard; augment CLI child runs unguarded\n',
+    );
+  }
  const hookCli = process.env.GITNEXUS_HOOK_CLI_PATH;
  if (hookCli !== undefined && String(hookCli).trim() && fs.existsSync(String(hookCli))) {
-    return spawnSync(process.execPath, [String(hookCli), ...args], {
+    const [cmd, cmdArgs] = guard
+      ? [
+          guard,
+          [
+            '-k',
+            '1',
+            String(Math.ceil(timeout / 1000) + 1),
+            process.execPath,
+            String(hookCli),
+            ...args,
+          ],
+        ]
+      : [process.execPath, [String(hookCli), ...args]];
+    return spawnSync(cmd, cmdArgs, {
      encoding: 'utf-8',
      timeout,
      cwd,
@@ -221,7 +306,12 @@ function runGitNexusCli(args, cwd, timeout) {
  }

  if (useDirectBinary) {
-    return spawnSync(isWin ? 'gitnexus.cmd' : 'gitnexus', args, {
+    // A non-null guard implies non-Windows, so the wrapped arm can hardcode
+    // plain `gitnexus` (the guard resolves it via PATH, like spawnSync does).
+    const [cmd, cmdArgs] = guard
+      ? [guard, ['-k', '1', String(Math.ceil(timeout / 1000) + 1), 'gitnexus', ...args]]
+      : [isWin ? 'gitnexus.cmd' : 'gitnexus', args];
+    return spawnSync(cmd, cmdArgs, {
      encoding: 'utf-8',
      timeout,
      cwd,
@@ -229,8 +319,27 @@ function runGitNexusCli(args, cwd, timeout) {
      windowsHide: true,
    });
  }
-  // npx fallback needs shell on Windows since npx is a .cmd script
-  return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], {
+  // npx fallback needs shell on Windows since npx is a .cmd script. The
+  // wrapped arm leads with `-s KILL` (NOT TERM-first like the direct
+  // branches above): the CLI here is a grandchild behind npx — see the
+  // docblock.
+  const [cmd, cmdArgs] = guard
+    ? [
+        guard,
+        [
+          '-s',
+          'KILL',
+          '-k',
+          '1',
+          String(Math.ceil((timeout + 5000) / 1000) + 1),
+          'npx',
+          '-y',
+          'gitnexus',
+          ...args,
+        ],
+      ]
+    : [isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args]];
+  return spawnSync(cmd, cmdArgs, {
    encoding: 'utf-8',
    timeout: timeout + 5000,
    cwd,
@@ -266,16 +375,34 @@ function handlePreToolUse(input) {

  const pattern = extractPattern(toolName, toolInput);
  if (!pattern || pattern.length < 3) return;
-  if (hasGitNexusServerOwner(gitNexusDir)) {
-    process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+
+  // Acquire the per-repo slot BEFORE the DB-owner probe (#2163): the probe
+  // itself spawns lsof/ps, so it must be bounded by the same ≤3-per-repo cap
+  // as the augment, or concurrent sessions fan out unbounded probe
+  // subprocesses. Keep the acquire right after the cheap guards above —
+  // moving it earlier would churn slot files on tool calls that never probe.
+  const release = acquireHookSlot(gitNexusDir);
+  if (!release) {
+    // Normal skip path: all per-repo hook slots are held by concurrent
+    // sessions. Stay silent for strict hook runners (issue #1913); surface
+    // the reason only when diagnostics are explicitly requested.
+    if (isDebugEnabled()) {
+      process.stderr.write('[GitNexus] augment skipped: hook slots saturated\n');
+    }
    return;
  }

-  const release = acquireHookSlot(gitNexusDir);
-  if (!release) return;
-
  let result = '';
  try {
+    if (hasGitNexusServerOwner(gitNexusDir)) {
+      // Normal skip path: the MCP server owns the DB, so the CLI augment would
+      // contend on the lock. Stay silent for strict hook runners (issue #1913);
+      // surface the reason only when diagnostics are explicitly requested.
+      if (isDebugEnabled()) {
+        process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+      }
+      return;
+    }
    const child = runGitNexusCli(['augment', '--', pattern], cwd, 7000);
    if (!child.error && child.status === 0) {
      result = extractAugmentContext(child.stderr || '');
@@ -366,7 +493,7 @@ function main() {
    const handler = handlers[input.hook_event_name || ''];
    if (handler) handler(input);
  } catch (err) {
-    if (process.env.GITNEXUS_DEBUG) {
+    if (isDebugEnabled()) {
      console.error('GitNexus hook error:', (err.message || '').slice(0, 200));
    }
  }
@@ -3,14 +3,57 @@
 * with a command line that looks like a GitNexus MCP/serve server?
 *
 * Backends (no user-installed Sysinternals):
- * - Linux: scan procfs under /proc (per-PID fd entries) via stat(2) (dev+inode); works without lsof;
- *   optional lsof fallback when proc scan finds nothing.
+ * - Linux: cmdline-first procfs scan under /proc, no lsof at all (#2180). Three
+ *   phases, cheapest first: (0) read /proc/<pid>/comm — a tiny task->comm read
+ *   that never touches the target's mm — and keep only PIDs whose comm is a
+ *   plausible node/gitnexus server; (1) read up to GITNEXUS_HOOK_PROC_CMDLINE_MAX
+ *   bytes of /proc/<pid>/cmdline via openSync+readSync (bounded, so a D-state
+ *   holder stuck on mmap_lock or a giant argv can't wedge the hook) and prefilter
+ *   with isGitNexusServerCommand; (2) only for the 0..N survivors, stat their
+ *   /proc/<pid>/fd/* and compare dev+inode against the target lbug. The lbug
+ *   handle is fd-visible (a @ladybugdb/core property), so this finds every real
+ *   owner without scanning every fd of every process.
 * - macOS / *BSD / etc.: trusted lsof + ps (absolute paths first).
 * - Windows: Restart Manager (rstrtmgr) via bundled PowerShell script +
 *   Win32_Process for command lines; trusted powershell.exe under %SystemRoot%.
 *
- * Fail-open on most errors; fail-closed only on lsof ETIMEDOUT (Unix) or
- * PowerShell ETIMEDOUT (Windows), matching the hook contract.
+ * Fail matrix:
+ * - Linux proc scan: owner found -> fail-closed (skip augment); budget exhausted
+ *   (GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS) -> fail-CLOSED (#2180). This is a
+ *   deliberate change from the old "timeout -> fail-open then try lsof" path.
+ *   End-to-end the busy-host outcome is unchanged: the old code's lsof fallback
+ *   ETIMEDOUT'd on the very hosts where the scan ran out of budget and ALSO
+ *   failed closed there — the lsof leg only ever added 1-2s of dead work plus
+ *   the orphan-storm risk it caused (#2163). What changes is that an overloaded
+ *   host now self-throttles immediately (the throttle the incident needed)
+ *   instead of paying for a doomed lsof. Mid-load hosts that used to fall
+ *   through to a successful lsof now answer from the scan directly (faster) or,
+ *   if even the scan can't finish in budget, fail closed (self-throttle) — a
+ *   bounded, documented tradeoff, never an orphan.
+ * - macOS / other Unix: fail-open on most errors; fail-closed only on lsof
+ *   ETIMEDOUT, matching the hook contract.
+ * - Windows: fail-closed only on PowerShell ETIMEDOUT.
+ *
+ * Unix subprocess containment contract (#2163):
+ * - lsof/ps are wrapped in coreutils `timeout`/`gtimeout` when a working
+ *   wrapper is found (`timeout -k 1 <budget> lsof ...`). If this hook process
+ *   is itself SIGKILLed (e.g. by the runner's 10s hook timeout) the wrapper
+ *   survives, SIGTERMs its child at the budget (2s lsof / 1s ps) and SIGKILLs
+ *   it 1s later — orphan lifetime is bounded at ~3s instead of unbounded.
+ * - GITNEXUS_HOOK_TIMEOUT_PATH: the sentinel value `disabled` switches the
+ *   wrapper off deterministically; any other value is adopted only when it
+ *   exists AND passes a one-shot `-k` exit-propagation self-test — otherwise
+ *   resolution FALLS THROUGH to the built-in candidate list (first self-test
+ *   pass wins), so no malformed value of any shape can silently disable
+ *   orphan containment.
+ * - The gitnexus server is lazy-open + sticky-hold: an idle MCP server holds
+ *   ZERO lbug fds until the repo's first MCP query, then keeps the fd open.
+ *   A probe before that first query is therefore always false — a known,
+ *   pre-existing race, not a bug in this probe.
+ * - resolveUnixGuardTimeout is exported so the hook adapters can wrap the
+ *   `gitnexus augment` CLI child — the longest-lived hook subprocess (7s
+ *   local / 12s npx inner budgets) — in the same guard; see runGitNexusCli
+ *   in the adapters (#2163 follow-up).
 */

 const fs = require('fs');
@@ -25,6 +68,16 @@ function isGitNexusServerCommand(command) {
  return hasServerMode && hasGitNexus;
 }

+// GITNEXUS_DEBUG-gated stderr diagnostics. Reuses the exact gating predicate the
+// Windows ps1-load warning already uses (===' 1' / ==='true') so there is one
+// debug convention in this file, and writes via process.stderr.write (NOT a
+// spawn) so it never perturbs the windowsHide spawn-count invariant.
+function debugLog(msg) {
+  if (process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true') {
+    process.stderr.write(`[GitNexus hook] ${msg}\n`);
+  }
+}
+
 function resolveHookBinary(tool) {
  const envKey = tool === 'lsof' ? 'GITNEXUS_HOOK_LSOF_PATH' : 'GITNEXUS_HOOK_PS_PATH';
  const fromEnv = process.env[envKey];
@@ -46,6 +99,106 @@ function resolveHookBinary(tool) {
  return tool;
 }

+function hasMissingHookBinaryOverride(tool) {
+  const envKey = tool === 'lsof' ? 'GITNEXUS_HOOK_LSOF_PATH' : 'GITNEXUS_HOOK_PS_PATH';
+  const fromEnv = process.env[envKey];
+  if (!fromEnv || !String(fromEnv).trim()) return false;
+  try {
+    return !fs.existsSync(String(fromEnv).trim());
+  } catch {
+    return true;
+  }
+}
+
+// Sentinel:
+//   undefined = not resolved yet (resolve lazily, on first lsof/ps fallback)
+//   string    = self-tested coreutils timeout/gtimeout path (use as wrapper)
+//   null      = no usable wrapper (disabled, none found, or self-test failed)
+let unixGuardTimeoutCache;
+
+/**
+ * Resolve a coreutils `timeout`/`gtimeout` binary to wrap lsof/ps with
+ * (#2163). Unix-only by contract: the probe's win32 dispatch returns before
+ * reaching it, and the exported callers (the adapters' runGitNexusCli,
+ * #2163 follow-up) must check the platform first — the self-test below
+ * spawns /bin/sh. The memoized result is module-wide, so probe and adapter
+ * share one lazy self-test per hook process.
+ *
+ * GITNEXUS_HOOK_TIMEOUT_PATH semantics: the sentinel `disabled` turns the
+ * wrapper off; any other value is only a CANDIDATE — an existing file path
+ * is tried first, but it must pass the `-k` exit-propagation self-test to
+ * be adopted. On any failure (non-existent path, directory, non-executable
+ * file, wrapper without `-k` support, always-exit-0 stub, …) resolution
+ * falls through to the built-in candidates below, tried in order, first
+ * self-test pass wins. This is strictly stronger than the sibling
+ * GITNEXUS_HOOK_LSOF_PATH / GITNEXUS_HOOK_PS_PATH overrides (which only
+ * check existence): no bad env value of ANY shape can silently disable
+ * orphan containment.
+ *
+ * Lazy self-test: candidates are probed only when the lsof/ps fallback is
+ * first reached, and the result is memoized. A candidate is adopted only
+ * when `timeout -k 1 1 /bin/sh -c 'exit 42'` exits 42 — i.e. it must RUN
+ * the wrapped command AND PROPAGATE its exit status. This rejects two
+ * failure shapes: wrappers without the coreutils `-k` flag — busybox <1.34,
+ * toybox, broken symlinks — which would exit with a usage error without
+ * ever running lsof, silently converting the lsof-ETIMEDOUT fail-closed
+ * contract into fail-open (#1492 regression); and always-exit-0 stubs
+ * (/bin/true shapes), which would otherwise be adopted and "succeed" every
+ * wrapped spawn instantly without running it — a constant no-owner probe
+ * answer and, worse, a silently dead augment (status 0, empty stderr passes
+ * the adapters' success check with no context; #2163 follow-up review).
+ * Only when EVERY candidate fails does the probe fall back to the unwrapped
+ * status quo (memoized null). busybox ≥1.34 passes the test and is fully
+ * usable for everything THIS file spawns (lsof/ps are the guard's direct
+ * children) and for the adapters' direct-exec arm. The adapters' npx arm
+ * additionally relies on coreutils' process-GROUP signalling for its
+ * `-s KILL` grandchild reaping; busybox signals only its direct child, and
+ * this self-test deliberately does not probe that capability — see the
+ * adapter docblocks for the residual-gap statement.
+ */
+function passesGuardSelfTest(guard) {
+  try {
+    const selfTest = spawnSync(guard, ['-k', '1', '1', '/bin/sh', '-c', 'exit 42'], {
+      encoding: 'utf-8',
+      timeout: 3000,
+      stdio: ['ignore', 'ignore', 'ignore'],
+      windowsHide: true,
+    });
+    return !selfTest.error && selfTest.status === 42;
+  } catch {
+    return false;
+  }
+}
+
+function resolveUnixGuardTimeout() {
+  if (unixGuardTimeoutCache !== undefined) return unixGuardTimeoutCache;
+  unixGuardTimeoutCache = null;
+  const fromEnv = process.env.GITNEXUS_HOOK_TIMEOUT_PATH;
+  const trimmed = fromEnv ? String(fromEnv).trim() : '';
+  if (trimmed === 'disabled') return unixGuardTimeoutCache;
+  const candidates = [];
+  if (trimmed && fs.existsSync(trimmed)) candidates.push(trimmed);
+  for (const builtin of [
+    '/usr/bin/timeout',
+    '/bin/timeout',
+    '/opt/homebrew/bin/gtimeout',
+    '/usr/local/bin/gtimeout',
+  ]) {
+    try {
+      if (fs.existsSync(builtin)) candidates.push(builtin);
+    } catch {
+      /* ignore */
+    }
+  }
+  for (const candidate of candidates) {
+    if (passesGuardSelfTest(candidate)) {
+      unixGuardTimeoutCache = candidate;
+      break;
+    }
+  }
+  return unixGuardTimeoutCache;
+}
+
 function resolveWindowsPowerShellPath() {
  const fromEnv = process.env.GITNEXUS_HOOK_POWERSHELL_PATH;
  if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv).trim())) {
@@ -132,76 +285,374 @@ function hasGitNexusServerOwnerWindows(dbPathAbs, myPid) {
  return false;
 }

-function readLinuxCmdline(pidStr) {
+// The procfs root every Linux scan path reads from. Production is always /proc;
+// GITNEXUS_HOOK_PROC_ROOT only exists so unit tests can inject a fixture tree
+// (comm + cmdline + fd symlinks) and assert the three-phase logic without
+// scanning the real, ~hundreds-of-process /proc of the test host.
+//
+// Test-only gate (F4): the override is honored ONLY under a test runner —
+// vitest injects VITEST="true" and NODE_ENV="test" into every worker (verified;
+// a production hook is `node <file>.cjs` with neither set). Without the gate, a
+// production env that accidentally leaked GITNEXUS_HOOK_PROC_ROOT (pointing at an
+// empty/bad tree) would make readdirSync find no pids -> 'not-owned' -> Linux
+// owner detection silently OFF (fail-OPEN: augment races the real server for the
+// lbug, the #1492 class). Gating to the test signal makes that leak inert in
+// production (always /proc) while the fake-procfs unit tests, which run under
+// vitest, still inject freely. Unset env (or non-test context) => /proc, so the
+// production path is byte-for-byte the historical behavior.
+function isTestContext() {
+  return (
+    process.env.VITEST === 'true' || process.env.VITEST === '1' || process.env.NODE_ENV === 'test'
+  );
+}
+function getProcRoot() {
+  if (!isTestContext()) return '/proc';
+  const raw = process.env.GITNEXUS_HOOK_PROC_ROOT;
+  return raw && String(raw).trim() ? String(raw) : '/proc';
+}
+
+// Max bytes read from /proc/<pid>/cmdline in Phase 1. Bounded by default so a
+// D-state holder wedged on mmap_lock, or a process with a pathological multi-MB
+// argv, can't stall the hook. 16 KiB comfortably clears a realistic
+// `node <abs path to .../node_modules/gitnexus/dist/cli/index.js> mcp` line
+// (the `mcp`/`serve` mode token lives at the very tail, so the cap must be large
+// enough to reach it — see PROC_CMDLINE_FLOOR escalation below). Overridable for
+// tests; never goes below PROC_CMDLINE_FLOOR.
+const PROC_CMDLINE_FLOOR = 4096;
+function getCmdlineMaxBytes() {
+  const raw = process.env.GITNEXUS_HOOK_PROC_CMDLINE_MAX;
+  // Number() (not parseInt) so "8e3" reads as 8000, not 8 (parseInt stops at
+  // 'e'). The `raw && String(raw).trim()` guard keeps empty/whitespace on the
+  // default; trailing garbage ("8abc") now -> NaN -> default (stricter).
+  const n = raw && String(raw).trim() ? Number(String(raw).trim()) : NaN;
+  if (Number.isFinite(n) && n >= PROC_CMDLINE_FLOOR) return n;
+  return 16384;
+}
+
+// Phase 0 comm prefilter. /proc/<pid>/comm is the kernel task->comm string,
+// capped at 16 bytes INCLUDING the trailing NUL — i.e. at most 15 visible
+// chars, truncated by the kernel with no marker. So a process whose real name
+// is longer than 15 chars shows a 15-char prefix here. The match below is
+// therefore truncation-safe in BOTH directions (a whitelist name that is a
+// prefix of comm, or comm that is a prefix of a whitelist name, both count) to
+// guarantee we never drop a real owner at this cheap stage — Phase 2's dev+ino
+// fd check is the real authority; Phase 0/1 only exist to skip the overwhelming
+// majority (kernel threads, shells, editors) cheaply.
+//
+// The whitelist is calibrated against what a real `gitnexus mcp`/`serve` server
+// actually reports for comm. Observed on production hosts: the server renames
+// its main thread, so comm reads `MainThread` (via @ladybugdb/core's
+// worker_threads setup), NOT `node` — omitting it would blind the probe to
+// every real server (#1492-class owner miss). We also keep the plausible
+// launcher/runtime basenames in case a future build does not rename the thread.
+// Conservative by design: over-collecting a few extra candidates only costs a
+// bounded number of Phase 1 cmdline reads.
+const COMM_CANDIDATES = ['node', 'gitnexus', 'bun', 'deno', 'npm', 'npx', 'MainThread'];
+function commLooksLikeServer(comm) {
+  const c = comm.trim();
+  if (!c) return false;
+  for (const name of COMM_CANDIDATES) {
+    if (name === c || name.startsWith(c) || c.startsWith(name)) return true;
+  }
+  return false;
+}
+
+function readProcComm(procRoot, pidStr) {
  try {
-    return fs.readFileSync(`/proc/${pidStr}/cmdline`, 'utf8').replace(/\0+/g, ' ').trim();
+    return fs
+      .readFileSync(path.join(procRoot, pidStr, 'comm'), 'utf8')
+      .replace(/\0+/g, '')
+      .trim();
  } catch {
    return '';
  }
 }

-function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) {
+// Timeout sentinel for readLinuxCmdline (F3). MUST be distinct from the
+// "unreadable/empty" return value (''): '' flows through isGitNexusServerCommand
+// as a NON-candidate (both regexes are false on ''), so the Phase 1 caller
+// `continue`s past it — correct for a raced/openSync-failed pid, but a FAIL-OPEN
+// bug if it ever meant "I ran out of budget mid-read" (a real owner whose
+// escalation timed out would be silently dropped, racing the lbug -> #1492). A
+// unique Symbol can never collide with any cmdline string, so the caller can
+// branch on it explicitly and map a mid-read timeout to the tri-state 'timeout'
+// (fail-CLOSED) instead of swallowing it as a non-candidate.
+const CMDLINE_TIMEOUT = Symbol('gitnexus.cmdline.timeout');
+
+// Bounded /proc/<pid>/cmdline read for Phase 1. openSync+readSync (not
+// readFileSync) so a D-state holder cannot stall the hook on a huge or
+// never-EOF argv: we read at most `cap` bytes and stop. cmdline separates argv
+// with NULs; convert to spaces for isGitNexusServerCommand.
+//
+// Owner-miss guard for the 4 KB cap: the `gitnexus` token usually sits in the
+// first path component while the `mcp`/`serve` mode token is the LAST argv, so
+// a naive 4 KB read could clip the mode token off a server launched with a very
+// long interpreter path and silently miss a real owner. We mitigate two ways:
+// (a) the default cap (16 KiB) already clears realistic lines; (b) if the first
+// read fills the cap AND already contains the `gitnexus` token but no mode
+// token yet, we keep reading in bounded chunks (up to a hard ceiling) until the
+// mode token appears or the file ends — so a genuine server is never missed for
+// want of a few more bytes, while non-candidates still pay only the initial
+// bounded read.
+//
+// Budget (F3): the escalation loop above is the one place a SINGLE pathological
+// candidate could read up to HARD_CEIL (256 KiB) before the next scan-level
+// budget check, weakening the timeout contract. `outOfBudget` (the scan's shared
+// deadline callback) is checked once per escalation iteration; on expiry we
+// return CMDLINE_TIMEOUT (NOT '') so the caller can fail-closed honestly rather
+// than mistake the partial read for a non-candidate. Reads that simply can't
+// open / error out still return '' (genuinely "not a readable candidate").
+function readLinuxCmdline(procRoot, pidStr, cap, outOfBudget) {
+  const file = path.join(procRoot, pidStr, 'cmdline');
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+  } catch {
+    return '';
+  }
+  try {
+    const HARD_CEIL = 262144; // 256 KiB absolute ceiling for the escalation path
+    let collected = Buffer.alloc(0);
+    let offset = 0;
+    let chunkCap = cap;
+    for (;;) {
+      // allocUnsafe is safe here: readSync fills exactly [0, bytes), only
+      // buf.subarray(0, bytes) is consumed, and Buffer.concat deep-copies that
+      // slice into `collected`, so the uninitialized tail never reaches decode.
+      const buf = Buffer.allocUnsafe(chunkCap);
+      const bytes = fs.readSync(fd, buf, 0, chunkCap, offset);
+      if (bytes <= 0) break;
+      collected = Buffer.concat([collected, buf.subarray(0, bytes)]);
+      offset += bytes;
+      const text = collected.toString('utf8').replace(/\0+/g, ' ');
+      // Stop early when we can already decide "owner": has both the gitnexus
+      // token and a mode token. Keep going only when gitnexus is present but
+      // the mode token might be just past the boundary.
+      const hasGitNexus =
+        /(?:^|[/\\\s])gitnexus(?:\.cmd)?(?:\s|$)/.test(text) ||
+        /node_modules[/\\]gitnexus[/\\]/.test(text);
+      const hasMode = /(?:^|\s)(mcp|serve)(?:\s|$)/.test(text);
+      if (hasMode) break; // decided (positive); isGitNexusServerCommand re-checks below
+      if (bytes < chunkCap) break; // EOF: full cmdline read, definitive
+      if (!hasGitNexus) break; // not a candidate; do not escalate the read
+      if (offset >= HARD_CEIL) break; // bounded escalation only
+      // Budget gate the escalation: a single huge-argv candidate must not burn
+      // the whole scan deadline before we re-check. Return the timeout sentinel
+      // (never '') so the caller fails closed instead of treating us as a
+      // non-candidate. The sole caller (linuxProcScanFindGitNexusServer) always
+      // passes outOfBudget, so no presence guard is needed.
+      if (outOfBudget()) return CMDLINE_TIMEOUT;
+      chunkCap = cap; // keep reading more in cap-sized chunks
+    }
+    return collected.toString('utf8').replace(/\0+/g, ' ').trim();
+  } catch {
+    return '';
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+function resolveLinuxProcBudgetMs() {
  const raw = process.env.GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS;
-  const budget = Number(raw && String(raw).trim()) ? Number.parseInt(String(raw), 10) : 1200;
+  // Gate on the STRING's emptiness, NOT the parsed number's truthiness — the
+  // old `Number(raw && trim()) ? ... : 1200` form treated "0" as falsy and
+  // silently fell back to 1200 (#2180). Use Number() (not parseInt) so "16e3"
+  // reads as 16000, not 16 (parseInt stops at 'e'). The `&& String(raw).trim()`
+  // guard is load-bearing: without it a set-but-empty/whitespace value would be
+  // `Number("")===0` => budget 0 => immediate fail-CLOSED timeout (augment
+  // permanently skipped). With it, ''/whitespace => NaN => 1200 default, while a
+  // finite "0" still parses to an explicit, deterministic "no budget" =>
+  // immediate timeout. Non-numeric / unset => default 1200.
+  const n = raw != null && String(raw).trim() ? Number(String(raw).trim()) : NaN;
+  if (!Number.isFinite(n)) return 1200;
+  return n; // may be <= 0, meaning "out of budget on the first check"
+}
+
+// Returns one of: 'owned' (a non-self process with a GitNexus-server cmdline
+// holds the target lbug fd), 'not-owned' (scan completed, no such owner), or
+// 'timeout' (the per-scan budget was exhausted before a verdict). The name is
+// pinned by a source-contract test; only the return TYPE changed (#2180:
+// boolean -> tri-state, so the dispatcher can fail-closed on 'timeout').
+function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) {
+  const budget = resolveLinuxProcBudgetMs();
+  // A non-positive budget is an explicit, deterministic "no time to scan" =>
+  // immediate timeout (the #2180 test vector, and the only correct reading of
+  // the fixed parse: "0" must NOT mean 1200). Returning before any procfs read
+  // keeps it instantaneous regardless of host load.
+  if (budget <= 0) return 'timeout';
+  const procRoot = getProcRoot();
+  const cmdlineCap = getCmdlineMaxBytes();
  const start = Date.now();
+  const outOfBudget = () => Date.now() - start > budget;
+
  let targetStat;
  try {
    targetStat = fs.statSync(dbPathAbs);
  } catch {
-    return false;
+    // Caller already existsSync'd the path; a stat failure here is a transient
+    // race, treat as no owner (historical semantics).
+    return 'not-owned';
  }
+
  let procEntries;
  try {
-    procEntries = fs.readdirSync('/proc', { withFileTypes: true });
+    procEntries = fs.readdirSync(procRoot, { withFileTypes: true });
  } catch {
-    return false;
+    return 'not-owned';
  }
+
+  // Phase 0 + Phase 1: collect the few PIDs whose comm AND cmdline look like a
+  // GitNexus server, without touching any fd yet.
+  const candidates = [];
  for (const ent of procEntries) {
-    if (Date.now() - start > budget) return false;
+    if (outOfBudget()) return 'timeout';
    if (!ent.isDirectory() || !/^\d+$/.test(ent.name)) continue;
    const pid = Number.parseInt(ent.name, 10);
    if (!Number.isFinite(pid) || pid === myPid) continue;
-    const fdDir = path.join('/proc', ent.name, 'fd');
+
+    // Phase 0: cheap comm prefilter.
+    const comm = readProcComm(procRoot, ent.name);
+    if (!comm) continue; // unreadable comm (kernel thread, raced exit) -> skip
+    if (!commLooksLikeServer(comm)) continue;
+
+    // Phase 1: bounded cmdline read + isGitNexusServerCommand prefilter.
+    if (outOfBudget()) return 'timeout';
+    const cmdline = readLinuxCmdline(procRoot, ent.name, cmdlineCap, outOfBudget);
+    // F3: a mid-read budget timeout returns the CMDLINE_TIMEOUT sentinel (a
+    // Symbol, never a string). Fail CLOSED on it rather than letting it fall
+    // through isGitNexusServerCommand as a non-candidate — a real owner whose
+    // escalation timed out must not be silently dropped (would fail-OPEN).
+    if (cmdline === CMDLINE_TIMEOUT) return 'timeout';
+    if (!isGitNexusServerCommand(cmdline)) continue;
+    candidates.push(ent.name);
+  }
+
+  // Phase 2: only now stat the fds of the (typically 0-2) survivors.
+  for (const pidStr of candidates) {
+    if (outOfBudget()) return 'timeout';
+    const fdDir = path.join(procRoot, pidStr, 'fd');
    let fds;
    try {
      fds = fs.readdirSync(fdDir);
-    } catch {
+    } catch (err) {
+      // F1: the old code returned 'owned' for EVERY non-ENOENT error. That was
+      // a correctness bug: /proc/<pid>/fd is owner-only (mode 0500), so a
+      // cross-user/root `gitnexus mcp` serving a DIFFERENT repo passes Phase 0+1
+      // (its cmdline matches) and then EACCES'es here — yet its dev+ino was
+      // NEVER compared against THIS lbug. Claiming 'owned' lets it permanently,
+      // silently suppress augment for a repo it does not actually lock. We now
+      // distinguish the failure shapes (all still fail-closed where we can't
+      // prove non-ownership, but 'timeout' is the HONEST verdict for
+      // "inconclusive", not the false-positive 'owned'):
+      const code = err && err.code;
+      if (code === 'ENOENT') {
+        // Process raced away between the candidate scan and now -> genuinely no
+        // longer an owner. Move on.
+        continue;
+      }
+      if (code === 'EACCES' || code === 'EPERM') {
+        // Permission-denied fd dir: cannot read fds, so ownership is
+        // UNVERIFIABLE. Fail closed honestly via 'timeout' (the dispatcher maps
+        // timeout -> true, same protective skip as before) WITHOUT lying that we
+        // confirmed ownership. Do NOT degrade to not-owned/fail-open: if this
+        // really is the owner, fail-open re-opens the #1492 lbug race; augment
+        // is optional context, so a conservative skip costs little.
+        debugLog(
+          `fd dir unreadable for candidate pid ${pidStr} (${code}); ownership ` +
+            `unverifiable, probe inconclusive -> fail-closed (timeout)`,
+        );
+        return 'timeout';
+      }
+      if (code === 'EIO' || code === 'ESTALE') {
+        // Genuine transient I/O against this candidate's fd dir — not evidence
+        // it does NOT hold the lbug. Treat as inconclusive and fail closed
+        // (timeout) rather than continue, so a real owner mid-I/O-blip is not
+        // dropped (would fail-open).
+        debugLog(
+          `fd dir transient I/O error for candidate pid ${pidStr} (${code}); ` +
+            `probe inconclusive -> fail-closed (timeout)`,
+        );
+        return 'timeout';
+      }
+      // Any other shape (ENOTDIR — fd path is not a directory at all, so this
+      // is not a plausible live-procfs owner — and the long tail) is treated as
+      // "this candidate is not an owner": move to the next candidate instead of
+      // the old blanket 'owned'. If no other candidate owns the lbug the scan
+      // ends not-owned (dispatcher fail-open) — acceptable because ENOTDIR means
+      // the fd entry is structurally not a real /proc/<pid>/fd.
+      debugLog(
+        `fd dir not a readable directory for candidate pid ${pidStr} ` +
+          `(${code || 'unknown'}); treating candidate as non-owner -> continue`,
+      );
      continue;
    }
-    let holds = false;
    for (const fd of fds) {
-      if (Date.now() - start > budget) return false;
+      if (outOfBudget()) return 'timeout';
      try {
        const st = fs.statSync(path.join(fdDir, fd));
        if (st.dev === targetStat.dev && st.ino === targetStat.ino) {
-          holds = true;
-          break;
+          return 'owned';
        }
      } catch {
-        /* ignore */
+        /* fd raced closed; ignore */
      }
    }
-    if (!holds) continue;
-    if (isGitNexusServerCommand(readLinuxCmdline(ent.name))) return true;
  }
-  return false;
+
+  return 'not-owned';
 }

 function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
+  const guard = resolveUnixGuardTimeout();
+  // An explicit missing override models ENOENT and must fail open instead of
+  // falling through to a host binary with different process-table visibility.
+  if (hasMissingHookBinaryOverride('lsof')) return false;
  const lsofPath = resolveHookBinary('lsof');
-  const lsof = spawnSync(lsofPath, ['-nP', '-t', '--', dbPathAbs], {
+  // The spawnSync timeouts below (lsof 1000ms / ps 500ms) are deliberately
+  // SHORTER than the wrapper budgets (2s / 1s): on the supervised path Node's
+  // SIGTERM always fires first, so `error.code === 'ETIMEDOUT'` and the
+  // fail-closed contract are untouched. The wrapper only matters once this
+  // hook process has been SIGKILLed and can no longer deliver that SIGTERM.
+  const [lsofCmd, lsofArgs] = guard
+    ? [guard, ['-k', '1', '2', lsofPath, '-nP', '-t', '--', dbPathAbs]]
+    : [lsofPath, ['-nP', '-t', '--', dbPathAbs]];
+  const lsof = spawnSync(lsofCmd, lsofArgs, {
    encoding: 'utf-8',
    timeout: 1000,
    stdio: ['ignore', 'pipe', 'ignore'],
    windowsHide: true,
  });
  if (lsof.error) return lsof.error.code === 'ETIMEDOUT';
+  // Guard-mediated deaths map to "unresponsive holder" (fail-closed). Three
+  // result shapes, verified against coreutils 9.1:
+  //   - signal-death: when `-k` escalates to SIGKILL, coreutils timeout
+  //     SELF-RAISES the signal, so spawnSync reports {status: null, signal}
+  //     with no .error (spawnSync's own ETIMEDOUT was handled above). The
+  //     same shape appears when this hook is frozen >2s (SIGSTOP, laptop
+  //     suspend) and the guard expires while it sleeps. By construction, a
+  //     guard-wrapped probe that died by signal without spawnSync ETIMEDOUT
+  //     is a budget/kill outcome.
+  //   - 124: budget expired and the child exited after the plain SIGTERM.
+  //   - 137: NOT the coreutils -k path — only exit-code-propagating wrappers,
+  //     or a child SIGKILLed externally (e.g. the OOM killer).
+  if (guard && lsof.status === null && lsof.signal) return true;
+  if (guard && (lsof.status === 124 || lsof.status === 137)) return true;

  const pids = (lsof.stdout || '').split(/\s+/).filter(Boolean);
+  const psMissing = hasMissingHookBinaryOverride('ps');
  const psPath = resolveHookBinary('ps');
  for (const pid of pids) {
    if (Number(pid) === myPid) continue;
-    const ps = spawnSync(psPath, ['-p', pid, '-o', 'command='], {
+    // Missing ps means we cannot verify that this pid is a GitNexus server.
+    if (psMissing) continue;
+    const [psCmd, psArgs] = guard
+      ? [guard, ['-k', '1', '1', psPath, '-p', pid, '-o', 'command=']]
+      : [psPath, ['-p', pid, '-o', 'command=']];
+    const ps = spawnSync(psCmd, psArgs, {
      encoding: 'utf-8',
      timeout: 500,
      stdio: ['ignore', 'pipe', 'ignore'],
@@ -211,6 +662,11 @@ function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
      if (ps.error.code === 'ETIMEDOUT') return true;
      continue;
    }
+    // Same guard-mediated-death mapping as the lsof call above (signal-death
+    // from the -k escalation or a frozen hook; 124 budget expiry; 137 only
+    // for exit-code-propagating wrappers / external SIGKILL).
+    if (guard && ps.status === null && ps.signal) return true;
+    if (guard && (ps.status === 124 || ps.status === 137)) return true;
    if (isGitNexusServerCommand(ps.stdout || '')) return true;
  }
  return false;
@@ -229,8 +685,13 @@ function hasGitNexusDbLockedByGitNexusServer(dbPath, myPid) {
  }

  if (process.platform === 'linux') {
-    if (linuxProcScanFindGitNexusServer(dbPathAbs, myPid)) return true;
-    return unixLsofPsFindGitNexusServer(dbPathAbs, myPid);
+    // #2180: cmdline-first procfs scan, no lsof. 'timeout' fails CLOSED
+    // (overloaded host self-throttles — the throttle the orphan-storm incident
+    // needed; the old lsof fallback ETIMEDOUT'd and failed closed on these same
+    // hosts anyway, only slower and with the orphan risk). 'not-owned' is the
+    // only false. See the fail matrix in the file header.
+    const verdict = linuxProcScanFindGitNexusServer(dbPathAbs, myPid);
+    return verdict !== 'not-owned';
  }

  return unixLsofPsFindGitNexusServer(dbPathAbs, myPid);
@@ -238,4 +699,30 @@ function hasGitNexusDbLockedByGitNexusServer(dbPath, myPid) {

 module.exports = {
  hasGitNexusDbLockedByGitNexusServer,
+  // Exported for white-box unit tests that must assert the tri-state verdict
+  // ('owned' | 'not-owned' | 'timeout') directly — the dispatcher collapses
+  // timeout and owned to the same boolean true, so the boolean API alone cannot
+  // distinguish the F1 EACCES->timeout fix from the old EACCES->owned bug. The
+  // Probe interface already declares this optional. Linux-only by contract; the
+  // name is pinned by a source-contract test.
+  linuxProcScanFindGitNexusServer,
+  // #2163 follow-up: the hook adapters wrap the augment CLI in the same
+  // guard. Returns a self-tested wrapper path — the built-in candidates are
+  // always absolute; a GITNEXUS_HOOK_TIMEOUT_PATH override is adopted as the
+  // exact string that passed the self-test. Same string is also the same
+  // RESOLUTION for absolute paths and for slashless names (PATH lookup is
+  // cwd-independent); a slash-containing RELATIVE override, however, is
+  // existsSync-checked and self-tested against this process's cwd while the
+  // adapters spawn the CLI with a `cwd` option (chdir-before-exec), so such
+  // a value can pass here yet ENOENT at the augment call site — set the
+  // override to an absolute path. Returns null when the wrapper is
+  // disabled/unavailable. Never call on win32 (see its JSDoc).
+  resolveUnixGuardTimeout,
+  // Exported for white-box unit tests of the numeric-env parsing (#2183 review):
+  // Number()-not-parseInt so "16e3" reads as 16000, plus the empty/whitespace
+  // guard that keeps a set-but-empty budget on the 1200 default instead of an
+  // immediate fail-closed timeout. Tested directly because the values are
+  // otherwise only observable indirectly through scan timing/escalation.
+  getCmdlineMaxBytes,
+  resolveLinuxProcBudgetMs,
 };
@@ -16,10 +16,10 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 ## Workflow

 ```
-1. query({query: "<error or symptom>"})            → Find related execution flows
+1. query({search_query: "<error or symptom>"})            → Find related execution flows
 2. context({name: "<suspect>"})                    → See callers/callees/processes
 3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
-4. cypher({query: "MATCH path..."})                 → Custom traces if needed
+4. cypher({statement: "MATCH path..."})                 → Custom traces if needed
 ```

 > If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
@@ -45,13 +45,14 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 | Intermittent failure | `context` → look for external calls, async deps            |
 | Performance issue    | `context` → find symbols with many callers (hot paths)     |
 | Recent regression    | `detect_changes` to see what your changes affect           |
+| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |

 ## Tools

 **query** — find code related to error:

 ```
-query({query: "payment validation error"})
+query({search_query: "payment validation error"})
 → Processes: CheckoutFlow, ErrorHandling
 → Symbols: validatePayment, handlePaymentError, PaymentException
 ```
@@ -72,10 +73,21 @@ MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "valid
 RETURN [n IN nodes(path) | n.name] AS chain
 ```

+**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
+
+```
+trace({ from: "processCheckout", to: "fetchRates" })
+→ status: ok, hopCount: 3
+→ hops: processCheckout → validatePayment → verifyCard → fetchRates
+→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
+```
+
+When no path exists, `trace` reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).
+
 ## Example: "Payment endpoint returns 500 intermittently"

 ```
-1. query({query: "payment error handling"})
+1. query({search_query: "payment error handling"})
   → Processes: CheckoutFlow, ErrorHandling
   → Symbols: validatePayment, handlePaymentError

@@ -18,7 +18,7 @@ description: "Use when the user asks how code works, wants to understand archite
 ```
 1. READ gitnexus://repos                          → Discover indexed repos
 2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. query({query: "<what you want to understand>"})  → Find related execution flows
+3. query({search_query: "<what you want to understand>"})  → Find related execution flows
 4. context({name: "<symbol>"})            → Deep dive on specific symbol
 5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
 ```
@@ -50,7 +50,7 @@ description: "Use when the user asks how code works, wants to understand archite
 **query** — find execution flows related to a concept:

 ```
-query({query: "payment processing"})
+query({search_query: "payment processing"})
 → Processes: CheckoutFlow, RefundFlow, WebhookHandler
 → Symbols grouped by flow with file locations
 ```
@@ -68,7 +68,7 @@ context({name: "validateUser"})

 ```
 1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
-2. query({query: "payment processing"})
+2. query({search_query: "payment processing"})
   → CheckoutFlow: processPayment → validateCard → chargeStripe
   → RefundFlow: initiateRefund → calculateRefund → processRefund
 3. context({name: "processPayment"})
@@ -35,10 +35,14 @@ For any task involving code understanding, debugging, impact analysis, or refact
 | `query`          | Process-grouped code intelligence — execution flows related to a concept |
 | `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
 | `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `trace`          | Shortest path between two symbols — "how does A reach B?" in one call     |
 | `detect_changes` | Git-diff impact — what do your current changes affect                    |
 | `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
 | `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
-| `list_repos`     | Discover indexed repos (paginated — `limit`/`offset`)                   |
+| `explain`        | Persisted taint findings — source→sink data flows (needs `analyze --pdg`) |
+| `pdg_query`      | Control/data dependence — what gates X (CDG) / where Y flows (REACHING_DEF); needs `analyze --pdg` |
+| `check`          | Check graph invariants such as circular imports                          |
+| `list_repos`     | Discover indexed repos (paginated — `limit`/`offset`)                    |

 ### Paginating `list_repos`

@@ -71,6 +75,35 @@ list_repos { offset: 400 }  → repos 401–437,                 hasMore false

 Notes: `offset` ≥ `total` returns an empty page (with `total` still reported). Out-of-range or malformed `limit`/`offset` (non-integer, `limit` outside `[1, 200]`, `offset < 0`) are rejected with a clear error — `limit` above the max is rejected, not silently capped. The order is deterministic (lower-cased name, then path), so paging never skips or duplicates an entry while the registry is unchanged.

+### Taint findings (`explain`)
+
+`explain` returns intra-procedural taint findings (`TAINTED` edges) recorded by `gitnexus analyze --pdg` — each with a sink category (command-injection, code-injection, path-traversal, sql-injection, xss), source/sink lines, and the ordered hop path with the variable carried on each hop.
+
+- `explain {}` — enumerate all findings for the repo (bounded by `limit`, deterministic order)
+- `explain { target: "src/vuln.ts" }` — findings in a file (suffix path match accepted)
+- `explain { target: "runUserCommand" }` — findings in a function (resolved like `context`; ambiguous names return ranked candidates)
+
+A repo indexed without `--pdg` returns a clear "no taint layer" note. Caveats: findings are intra-procedural only — cross-function, closure/callback, property/field, and implicit flows are not modeled, so the absence of a finding is **not** proof of safety. `SANITIZES` (sanitizer-kill) edges are queryable via `cypher`.
+
+### Control & data dependence (`pdg_query`)
+
+`pdg_query` reads the control/data-dependence layers `gitnexus analyze --pdg` records (CDG + REACHING_DEF, basic-block granular) — the control/data analog of `explain`. It is **always anchored** (a `target` file path or symbol, resolved like `context`) and has two modes:
+
+- `pdg_query { mode: "controls", target: "..." }` — CDG: "under what condition does X run?". Each edge is a controlling predicate block → dependent block with the branch sense (`'T'`/`'F'`) in `reason`; an edge into an early `return`/`throw` is flagged `guard: true` (guard-clause discovery — the sense depends on the predicate, so don't filter guards by a fixed label).
+- `pdg_query { mode: "flows", target: "...", variable?: "..." }` — REACHING_DEF def→use edges within the function; pass `variable` to trace one binding.
+
+A repo indexed without `--pdg` returns a "no PDG layer" note (or "status unknown" when the layer can't be confirmed). Intra-procedural only — cross-function flow is taint's domain (`explain`). The raw CDG/REACHING_DEF edges are also queryable via `cypher`. See the `gitnexus-pdg-query` skill for the full query surface.
+
+### Shortest path between two symbols (`trace`)
+
+`trace` answers "how does A reach B?" in one call — the shortest directed path over `CALLS` (plus `HAS_METHOD`, so a class-rooted trace descends into its methods) instead of chaining 3–8 `context`/`impact` hops by hand.
+
+- `trace { from: "validateUser", to: "executeQuery" }` — shortest path between two symbols.
+- Disambiguate common names with `from_uid`/`to_uid` (zero-ambiguity) or `from_file`/`to_file`; an ambiguous name returns ranked candidates.
+- `maxDepth` (default 10, max 30) bounds the search; `includeTests` (default false) lets the traversal pass through test-file symbols.
+
+Returns ordered `hops` (each `{ name, filePath, startLine }`) and an aligned `edges[]` of `{ relType, confidence }`, so call hops and containment (`HAS_METHOD`) hops stay distinguishable. When no path exists it reports the **furthest** reachable node (where the chain breaks) and sets `truncated: true` if a traversal cap was hit first. Every result carries a `status`: `ok` / `no_path` / `ambiguous` / `not_found` / `error`.
+
 ## Resources Reference

 Lightweight reads (~100-500 tokens) for navigation:
@@ -0,0 +1,89 @@
+---
+name: gitnexus-pdg-query
+description: "Use when querying or extending GitNexus's PDG control/data-dependence surface (the `pdg_query` MCP tool, CDG/REACHING_DEF edges), or reasoning about \"what controls X\" / \"where does Y flow\" / guard clauses. Examples: \"what guards this statement?\", \"trace this variable within the function\", \"why is the pdg_query result empty?\", \"add a CDG query\"."
+---
+
+# PDG query surface with GitNexus
+
+Expert knowledge for the `pdg_query` MCP tool and the control/data-dependence
+edges it reads — the opt-in `--pdg` program-dependence layers. Read this before
+touching `gitnexus/src/mcp/local/local-backend.ts` (`_pdgQueryImpl`) or the
+`pdg_query` tool def, or when explaining a `pdg_query` result.
+
+## When to Use
+
+- "Under what condition does this statement run?" (guarding predicates).
+- "Where does this variable flow inside the function?" (def→use).
+- Guard-clause discovery (early-return guards — subsumes the #559 heuristic).
+- Extending or reviewing `pdg_query` / the CDG / REACHING_DEF read path.
+- Debugging an empty or surprising `pdg_query` result.
+
+## The layered substrate (build order)
+
+`pdg_query` runs **on** the same graph taint runs on. Each layer is opt-in
+behind `--pdg`; a default `analyze` run records none of them (byte-identical).
+
+```
+L1  CFG            per-function basic blocks + control-flow edges   (M1 #2081)
+L2  REACHING_DEF   GEN/KILL def→use data dependence (pure solver)   (M2 #2082)
+L5  CDG            Ferrante control dependence (post-dominators)    (M5 #2085)
+```
+
+All three are `BasicBlock → BasicBlock` edges in the single `CodeRelation` table
+(keyed by the `type` property). There is **no** `Function → BasicBlock` edge.
+
+## The two modes
+
+- `pdg_query({ mode: 'controls', target })` — CDG. For the anchored function,
+  each edge: controlling predicate block → dependent block + branch sense in
+  `label` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An
+  edge into an early-return/throw block is flagged `guard: true`.
+- `pdg_query({ mode: 'flows', target, variable? })` — REACHING_DEF def→use
+  edges; `variable` filters to one binding.
+
+`target` is **required** — a file path or a symbol/function name (resolved like
+`context()`). There is no anchorless mode (see below).
+
+## The corrected guard-clause Cypher
+
+The RFC #567 §2 form (`[:CDG {label:'F'}]`) does **not** run as written. Edges
+are values of the single `CodeRelation` table's `type` property, and the branch
+sense is in `reason`, NOT a `label` column:
+
+```cypher
+MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock)
+WHERE dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw'
+RETURN pred.startLine, r.reason AS branch, dep.startLine, dep.text
+```
+
+`r.reason` is the sense the predicate took to reach the early exit. For
+`if (!ok) return;` the return rides the predicate's **true** arm (`'T'`) and the
+protected body rides the **false** arm (`'F'`) — polarity depends on the guard,
+so don't hard-code one sense.
+
+## Gotchas (the load-bearing ones)
+
+- **Always anchored + LIMIT-bounded.** LadybugDB has no rel-property index, so
+  an unanchored `[:CDG*]`/`[:REACHING_DEF*]` path scan is unbounded. `pdg_query`
+  requires `target` and bounds the page; raw `cypher` callers must anchor on a
+  file id-prefix or symbol span themselves.
+- **BasicBlock↔symbol join is reconstructed.** No `Function→BasicBlock` edge:
+  the block is matched by its id-prefix (`BasicBlock:<file>:<fnStartLine>:…`)
+  plus `startLine` within the symbol's span. BasicBlock `startLine` is **1-based**
+  while the symbol node's `startLine`/`endLine` are **0-based**, so **both** bounds
+  are shifted `+1` (`[symStart+1, symEnd+1]`): the upper `+1` keeps a guard/def/use
+  on the function's **final line**, the lower `+1` excludes an adjacent function's
+  block on the line directly **above**. Same-line / nested functions anchor coarsely.
+- **No PDG layer ⇒ a note, not an error.** If the repo wasn't indexed with
+  `--pdg` the tool returns `{ results: [], note: "no PDG layer …" }` (cheap meta
+  probe on `RepoMeta.pdg.maxCdgEdgesPerFunction` / `maxReachingDefEdgesPerFunction`).
+- **CDG labels are binary in M5/M6.** Every `switch`-case arm is `'T'`; per-case
+  conditions are not yet distinguished.
+- **Intra-procedural only.** Cross-function flow is taint's domain (`explain`).
+
+## Mirror, don't fork
+
+`_pdgQueryImpl` is the front half of `_explainImpl` (WAL wrapper, meta no-layer
+probe, limit validation, `resolveSymbolCandidates` anchoring) with CDG/
+REACHING_DEF instead of TAINTED — and none of taint's path-codec / interproc
+`TAINT_PATH` machinery. Reuse those shared helpers; do not re-implement them.
@@ -17,7 +17,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru

 ```
 1. impact({target: "X", direction: "upstream"})  → Map all dependents
-2. query({query: "X"})                            → Find execution flows involving X
+2. query({search_query: "X"})                            → Find execution flows involving X
 3. context({name: "X"})                           → See all incoming/outgoing refs
 4. Plan update order: interfaces → implementations → callers → tests
 ```
@@ -0,0 +1,178 @@
+---
+name: gitnexus-taint-analysis
+description: "Use when working on, reviewing, or extending GitNexus's CFG/taint/PDG subsystem (the `--pdg` layers), or when reasoning about source→sink data-flow findings. Examples: \"How does taint analysis work here?\", \"Why didn't explain find this flow?\", \"Add a new sink/source\", \"Review the interprocedural taint code\"."
+---
+
+# CFG & Taint Analysis with GitNexus
+
+Expert knowledge for the opt-in `--pdg` program-analysis subsystem: control-flow
+graphs, reaching definitions, and intra- + inter-procedural taint. Read this
+before touching `gitnexus/src/core/ingestion/cfg/**` or
+`gitnexus/src/core/ingestion/taint/**`, or when explaining a finding.
+
+## When to Use
+
+- "How does the taint engine work / why is this flow (not) reported?"
+- Adding a source, sink, or sanitizer to the model.
+- Extending or reviewing the CFG / reaching-defs / taint / summary code.
+- Understanding the `explain` MCP tool's findings (intra- vs inter-procedural).
+- Debugging a false positive or false negative in `--pdg` output.
+
+## The layered substrate (build order)
+
+Taint runs **on** the graph, not beside it. Each layer is opt-in behind `--pdg`
+and a default `analyze` run is **byte-identical** (the golden parity gate is the
+hard floor for every change here).
+
+```
+L1  CFG            per-function basic blocks + control-flow edges   (M1 #2081)
+L2  REACHING_DEF   GEN/KILL def→use data dependence (pure solver)   (M2 #2082)
+L3  Taint (intra)  source→sink over RD facts, minus sanitizers      (M3 #2083)
+L4  Taint (inter)  per-function summaries composed over CALLS       (M4 #2084)
+```
+
+- **Worker-built, main-thread-solved.** The parse worker builds each function's
+  CFG + harvests def/use + call-site facts onto `ParsedFile.cfgSideChannel`
+  (plain, structured-clone-safe data — never AST nodes). The main thread runs
+  the pure solvers. NEVER re-parse on the main thread (re-introduces the #1983
+  OOM).
+- **In-phase emit (KTD1).** L1–L4-harvest all run INSIDE the scope-resolution
+  pdg window (`scope-resolution/pipeline/run.ts`, gated `input.pdg === true`),
+  because the disk-backed ParsedFile store is cleared when that phase ends — a
+  standalone post-`mro` phase would read empty data. The cross-function fixpoint
+  (L4) is the exception: it runs in its OWN registered phase (`taintSummaries`)
+  AFTER scope-resolution, because it needs the COMPLETE call graph, and consumes
+  small plain summary data threaded out via `ScopeResolutionOutput`.
+- **Pure-solver contract.** `computeReachingDefs`, `computeTaintFlows`,
+  `harvestFunctionSummary`, and `solveInterprocTaint` are pure and deterministic
+  (no graph, no I/O, no logger; sorted outputs). Snapshot tests and
+  content-derived edge ids depend on it.
+
+## Intra-procedural taint (L3)
+
+Forward reachability over RD facts from matched **sources** to matched **sinks**,
+killed by **sanitizers**. Key design points worth internalizing:
+
+- **Occurrence-tagged sites.** A flat per-arg binding set cannot tell
+  `exec(escape(x))` (safe) from `exec(x)` (finding); the harvest records nested
+  call structure (`SiteRecord.parent`/via-tags) so sanitizer interposition is
+  precise.
+- **Kind-set sanitizer model.** A taint carries a set of *neutralized*
+  `SinkKind`s; a sink fires unless its kind is in the set. So `escape(req.body)`
+  suppresses `res.send` (xss) but STILL fires `db.query` (sql) — a kind-blind
+  kill would be a suppressed live injection (the forbidden FN direction).
+  `path.basename(t)` neutralizes path-traversal only, not command-injection.
+- **Statement-level finding identity.** NOT block-pair (block conflation drops
+  distinct findings; `exec(req.body, req.query)` is two findings).
+- Persisted as `TAINTED` edges (BasicBlock→BasicBlock); the path rides the
+  `reason` column via the shared versioned codec (`taint/path-codec.ts`).
+
+## Interprocedural taint (L4) — the functional/summary method
+
+The production approach (Sharir-Pnueli 1981; the same shape as Meta's Pysa and
+Mariana Trench, and FB Infer) — NOT full IFDS tabulation. Each function is
+reduced to a compact **summary**, and summaries are composed over the already-
+resolved `CALLS` graph.
+
+**Summary shape** (`taint/summary-model.ts`, whole-parameter granularity):
+
+| Edge | Meaning | Analogue |
+|------|---------|----------|
+| `param→return` | a param flows to the return value | TITO — **reserved** (the floor already covers its recall; precision pass deferred) |
+| `param→callee-arg` | a param flows into arg *j* of a call (carries the path's neutralized sink kinds) | TITO into callee |
+| `param→sink` | a param reaches a modelled sink | partial/triggered sink |
+| `source→return` | the function generates+returns a source | generative — **composed** via the caller's `callResults` |
+| `source→callee-arg` | a generated source flows into a call | fixpoint SEED |
+| `callResults` | a user-function call's result flows to a sink/return/callee-arg in the caller | composes with callee `source→return` |
+
+**The fixpoint** (`taint/interproc-solver.ts`): the unit is `(function,
+parameter, source)`. Seed from `source→callee-arg`, propagate via
+`param→callee-arg`, fire a finding when a tainted param meets `param→sink`.
+
+- **Cycle-safe by monotonicity.** The tainted-set is monotone over a finite
+  lattice (`fn × param × source`), so the worklist converges — a recursive call
+  just re-proposes an already-visited entry. SCC condensation would only refine
+  processing order; correctness/termination don't require it.
+- **Source-discriminated state (load-bearing).** Key the state by the SOURCE
+  too. Keying only by `(fn, param)` collapses multi-source flows: a sink param
+  tainted by source A is marked visited and a later flow from source B is dropped
+  before firing — the recurring multi-source bug class. (Bit M3; bit M4 U9.)
+- **Name-based call join.** Match a summary's call-arg edge to a `CALLS` edge by
+  CALLEE NAME, not call-site line — line-base parity (CFG 1-based vs reference
+  site) is fragile; the callee identity is exact and context-insensitivity
+  taints the callee's param identically at every call site.
+- Persisted as `TAINT_PATH` edges (Function→Function), function-level hop chain
+  in `reason` via the same codec; confidence < the intra-procedural 1.0.
+
+**Context-insensitivity** is the accepted trade-off at this tier: one summary
+per function, return/call-site merging accepted (security-conservative). Expect
+some FP from merging; the bigger FN sources are unmodeled features (below).
+
+## Known false-negative classes (documented, deferred)
+
+The largest is **closures/callbacks** (`arr.forEach(() => sink(y))`) — taint
+into a callback is dropped without per-library models (true of CodeQL's JS libs
+too). Also deferred: field/property flows (`obj.x = taint; sink(obj.y)`),
+field-sensitive access paths, guard-style sanitizers, implicit/control-dependence
+flows, promise/async-await threading, and **destructured/rest params before a
+tainted simple param** (the summary port index is the binding ordinal, not the
+formal arg position — needs a formal-param index threaded from the worker
+`BindingEntry`). The interprocedural join is also context-insensitive: when one
+caller invokes two distinct **same-named callees**, a flow into one
+over-attributes to both (sound — over-report, never a missed flow). Absence of a
+finding is NOT proof of safety.
+
+## GitNexus-specific gotchas
+
+- **Function↔CFG join.** `FunctionCfg.functionStartLine` is 1-based; `Function`/
+  `Method` node `startLine` is 0-based — join at `startLine - 1`. Function nodes
+  have no column, so same-line functions (`{a:()=>x(), b:()=>y()}`) are
+  ambiguous → drop (the summary driver counts `unresolved`) rather than
+  cross-wire.
+- **No rel-property index (S1).** Kuzu has no secondary index on relationship
+  properties, and unanchored `[:TAINTED*]`/`[:TAINT_PATH*]` queries explode.
+  TAINT_PATH is therefore MATERIALIZED + anchored at analyze time, never
+  traversed live; `explain` reads it source-anchored + LIMIT-guarded.
+- **`explain` is the only discovery surface.** `TAINTED`/`TAINT_PATH` are
+  deliberately OUT of `VALID_RELATION_TYPES` (impact's allow-list) and the web
+  schema (pinned in `security.test.ts`). `explain` enumerates both layers
+  (cross-function findings carry `interprocedural: true`).
+- **One shared codec.** Both the emit path and `explain` import
+  `taint/path-codec.ts`. Two hand-rolled copies of a wire format drift — never
+  fork it. New metadata extends the format WITHIN the version when writer +
+  reader ship together.
+- **Cache versioning.** A worker-harvest shape change bumps the parse-cache pdg
+  NAMESPACE (`pdg:N`), NOT `SCHEMA_BUMP` (which cold-invalidates every user).
+  Persisted-graph/config changes ride `RepoMeta.pdg`'s key-union mismatch →
+  full writeback. Model content rides `taintModelVersion`.
+
+## Adding a source / sink / sanitizer
+
+Edit the language model in `taint/typescript-model.ts` (registered via the
+explicit `registerBuiltinTaintModels` seam, keyed by `SupportedLanguages`). The
+spec is hashable data (no functions). A sanitizer's `neutralizes` lists the
+EXACT sink kinds it defends — never a blanket kill. Add a fixture + assert the
+finding (or its absence) in `test/unit/taint/` (real-source harness:
+`test/helpers/ts-cfg-harness.ts`); the end-to-end proof is
+`test/integration/cfg/`.
+
+## Validation checklist for any `--pdg` change
+
+```
+1. tsc clean (schema additions are exhaustiveness-checked; watch the
+   api.ts getNodeQuery runtime read-path if a node label is added).
+2. Targeted vitest by directory (test/unit/taint, test/unit/cfg,
+   test/integration/cfg) — verify by ISOLATION, not full-suite exit
+   (known load-flakes). `node scripts/build.js` before worker/integration runs.
+3. Flag-off golden byte-identical (pipeline-graph-golden.test.ts).
+4. bench/cfg/measure.mjs --check (no fingerprint drift / budget regression).
+5. detect_changes() before commit; impact({direction:'upstream'}) before
+   editing shared symbols (KnowledgeGraph, RepoMeta, RelationshipType, codec).
+```
+
+## Prior art (for deeper design questions)
+
+Sharir & Pnueli 1981 (functional approach); Reps-Horwitz-Sagiv IFDS (POPL 1995);
+FlowDroid/StubDroid (access-path summaries); Pysa & Mariana Trench (TITO /
+propagations, parallel SCC fixpoint); CodeQL Models-as-Data (the richest port
+notation, incl. callback ports); Infer (content-keyed incremental summaries).
@@ -241,7 +241,18 @@ function main() {
    if (!pattern || pattern.length < 3) return;

    const release = acquireHookSlot(gitNexusDir);
-    if (!release) return;
+    if (!release) {
+      // Normal skip path: all per-repo hook slots are held by concurrent
+      // sessions. Stays silent by default; surfaced only under the cursor
+      // hook's own GITNEXUS_DEBUG (truthy) convention. NOTE: unlike the
+      // claude/plugin/antigravity adapters this integration does not install
+      // hook-db-lock-probe.cjs, so its augment child is not guard-wrapped
+      // yet — tracked on the #2163 follow-up list ("cursor probe").
+      if (process.env.GITNEXUS_DEBUG) {
+        process.stderr.write('[GitNexus] augment skipped: hook slots saturated\n');
+      }
+      return;
+    }

    const cliPath = resolveCliPath();
    let result = '';
@@ -15,10 +15,10 @@ description: Trace bugs through call chains using knowledge graph
 ## Workflow

 ```
-1. query({query: "<error or symptom>"})            → Find related execution flows
+1. query({search_query: "<error or symptom>"})            → Find related execution flows
 2. context({name: "<suspect>"})                    → See callers/callees/processes
 3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
-4. cypher({query: "MATCH path..."})                 → Custom traces if needed
+4. cypher({statement: "MATCH path..."})                 → Custom traces if needed
 ```

 > If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
@@ -44,12 +44,13 @@ description: Trace bugs through call chains using knowledge graph
 | Intermittent failure | `context` → look for external calls, async deps |
 | Performance issue | `context` → find symbols with many callers (hot paths) |
 | Recent regression | `detect_changes` to see what your changes affect |
+| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |

 ## Tools

 **query** — find code related to error:
 ```
-query({query: "payment validation error"})
+query({search_query: "payment validation error"})
 → Processes: CheckoutFlow, ErrorHandling
 → Symbols: validatePayment, handlePaymentError, PaymentException
 ```
@@ -68,10 +69,20 @@ MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "valid
 RETURN [n IN nodes(path) | n.name] AS chain
 ```

+**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
+```
+trace({ from: "processCheckout", to: "fetchRates" })
+→ status: ok, hopCount: 3
+→ hops: processCheckout → validatePayment → verifyCard → fetchRates
+→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
+```
+
+When no path exists, `trace` reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).
+
 ## Example: "Payment endpoint returns 500 intermittently"

 ```
-1. query({query: "payment error handling"})
+1. query({search_query: "payment error handling"})
   → Processes: CheckoutFlow, ErrorHandling
   → Symbols: validatePayment, handlePaymentError

@@ -17,7 +17,7 @@ description: Navigate unfamiliar code using GitNexus knowledge graph
 ```
 1. READ gitnexus://repos                          → Discover indexed repos
 2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. query({query: "<what you want to understand>"})  → Find related execution flows
+3. query({search_query: "<what you want to understand>"})  → Find related execution flows
 4. context({name: "<symbol>"})            → Deep dive on specific symbol
 5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
 ```
@@ -48,7 +48,7 @@ description: Navigate unfamiliar code using GitNexus knowledge graph

 **query** — find execution flows related to a concept:
 ```
-query({query: "payment processing"})
+query({search_query: "payment processing"})
 → Processes: CheckoutFlow, RefundFlow, WebhookHandler
 → Symbols grouped by flow with file locations
 ```
@@ -65,7 +65,7 @@ context({name: "validateUser"})

 ```
 1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
-2. query({query: "payment processing"})
+2. query({search_query: "payment processing"})
   → CheckoutFlow: processPayment → validateCard → chargeStripe
   → RefundFlow: initiateRefund → calculateRefund → processRefund
 3. context({name: "processPayment"})
@@ -16,7 +16,7 @@ description: Plan safe refactors using blast radius and dependency mapping

 ```
 1. impact({target: "X", direction: "upstream"})  → Map all dependents
-2. query({query: "X"})                            → Find execution flows involving X
+2. query({search_query: "X"})                            → Find execution flows involving X
 3. context({name: "X"})                           → See all incoming/outgoing refs
 4. Plan update order: interfaces → implementations → callers → tests
 ```
@@ -94,6 +94,9 @@ export type NodeProperties = {
  middleware?: string[];
  // BasicBlock (taint/PDG substrate, issue #2080) — reuses filePath/startLine/endLine.
  text?: string;
+  /** BasicBlock: space-joined leaf callee names invoked in the block — the
+   *  statement-precise inter-procedural reach substrate for impact mode. */
+  callees?: string;
  // Extensible
  [key: string]: unknown;
 };
@@ -157,7 +160,34 @@ export type RelationshipType =
  | 'SANITIZES'
  /** Materialized source→sink taint path. Working name — final name/representation
   *  is confirmed when M3/M4 emits it; no persisted edge exists before then. */
-  | 'TAINT_PATH';
+  | 'TAINT_PATH'
+  /** Control-dependence edge (PDG, issue #2085 M5): block `dependent` (target)
+   *  executes only because the branch at block `controller` (source) took a
+   *  given side. The branch sense (`'T'` | `'F'`) rides the relation's existing
+   *  `reason` column — mirroring how `CFG` stores its edge kind there — since
+   *  the single `CodeRelation` table has no dedicated label column. */
+  | 'CDG'
+  /** Debug-only post-dominator-tree edge (#2085 M5): a block → its immediate
+   *  post-dominator, emitted behind the `GITNEXUS_PDG_EMIT_POST_DOMINATE` env
+   *  flag for inspection. Never emitted in a normal `--pdg` run. Note: as a
+   *  member of this exported union it is a forward-compatibility commitment —
+   *  removing it later is a breaking schema change — and it is deliberately
+   *  excluded from `VALID_RELATION_TYPES` so it never enters impact-style
+   *  symbol-space traversal (same posture as the taint substrate edges). */
+  | 'POST_DOMINATE'
+  /** Per-callee dependence SUMMARY edge (PDG FU-C): a self-loop on a
+   *  Function/Method/Constructor node carrying that callee's RETURN-VALUE
+   *  ASCENT — which formal-parameter indices flow to the function's return
+   *  value, encoded as a versioned bitset in the relation's existing `reason`
+   *  column (the same single-channel pattern `CFG`/`REACHING_DEF`/`CDG` use,
+   *  since the lone `CodeRelation` table has no dedicated label column). A
+   *  later consumer phase lets an interprocedural slice ascend a callee's
+   *  return effect into the caller continuation. Like the taint substrate
+   *  edges it is an internal PDG-engine edge: deliberately EXCLUDED from
+   *  `VALID_RELATION_TYPES` and the web schema so it never leaks into
+   *  callgraph-style impact/relationship surfaces. Emitted only under `--pdg`;
+   *  a default analyze emits zero. */
+  | 'CALL_SUMMARY';

 export interface GraphNode {
  id: string;
@@ -32,7 +32,17 @@ const EXTENSION_MAP: Record<SupportedLanguages, readonly string[]> = {
  [SupportedLanguages.Python]: ['.py'],
  [SupportedLanguages.Java]: ['.java'],
  [SupportedLanguages.C]: ['.c'],
-  [SupportedLanguages.CPlusPlus]: ['.cpp', '.cc', '.cxx', '.h', '.hpp', '.hxx', '.hh'],
+  [SupportedLanguages.CPlusPlus]: [
+    '.cpp',
+    '.cc',
+    '.cxx',
+    '.h',
+    '.hpp',
+    '.hxx',
+    '.hh',
+    '.cu',
+    '.cuh',
+  ],
  [SupportedLanguages.CSharp]: ['.cs'],
  [SupportedLanguages.Go]: ['.go'],
  [SupportedLanguages.Ruby]: ['.rb', '.rake', '.gemspec'],
@@ -77,6 +77,12 @@ export const REL_TYPES = [
  'TAINTED',
  'SANITIZES',
  'TAINT_PATH',
+  // Control dependence (PDG, issue #2085 M5) — CDG carries its 'T'|'F' branch
+  // label in the relation's `reason` column; POST_DOMINATE is debug-only
+  // (behind GITNEXUS_PDG_EMIT_POST_DOMINATE). Both are BasicBlock→BasicBlock,
+  // reusing the existing FROM BasicBlock TO BasicBlock pair in RELATION_SCHEMA.
+  'CDG',
+  'POST_DOMINATE',
 ] as const;

 export type RelType = (typeof REL_TYPES)[number];
@@ -98,4 +98,26 @@ export interface ParsedFile {
   * side effects — the contract default) leave this undefined.
   */
  readonly captureSideChannel?: unknown;
+
+  /**
+   * Per-function control-flow graphs for this file (#2081 M1, PDG/taint
+   * substrate). A DISTINCT field from {@link captureSideChannel} — different
+   * producer, consumer, and lifecycle: the worker builds it from the
+   * tree-sitter AST via `LanguageProvider.cfgVisitor` (only on a `--pdg` run),
+   * and scope-resolution emits BasicBlock nodes + CFG edges from it while the
+   * disk-backed ParsedFile store is still live (it is NOT a capture-time
+   * marker the resolver restores into module maps). Kept separate so a future
+   * change to either channel's shape invalidates independently.
+   *
+   * Shared / ingestion code treats this as opaque (`unknown`) per AGENTS.md.
+   * Concretely it is a `readonly FunctionCfg[]` (see
+   * `core/ingestion/cfg/types.ts`) — plain JSON-serializable data (no AST
+   * refs, no class instances) so it round-trips through the parse cache and
+   * the `parsedfile-store` (whose interning reviver keys on `nodeId`, which
+   * these blocks/edges deliberately lack).
+   *
+   * Optional: `undefined` on non-`--pdg` runs and for languages with no
+   * `cfgVisitor` — the default for every run today.
+   */
+  readonly cfgSideChannel?: unknown;
 }
@@ -20,6 +20,8 @@ export interface ParameterTypeClass {
  indirection: 'value' | 'lvalue-ref' | 'rvalue-ref' | 'pointer' | 'unknown';
  /** Number of pointer markers when indirection is `pointer`; otherwise 0. */
  pointerDepth: number;
+  /** Normalized top-level template arguments, when a language preserves them. */
+  templateArguments?: string[];
 }

 export interface SymbolDefinition {
@@ -57,6 +59,10 @@ export interface SymbolDefinition {
   *  Currently used by C++ overload ranking to exclude explicit constructors
   *  from implicit user-defined conversion candidates. */
  isExplicit?: boolean;
+  /** True when the callable is declared unavailable (for example C++ `= delete`).
+   *  Unavailable callables still participate in overload selection, but a
+   *  selected unavailable target must suppress edge emission. */
+  isDeleted?: boolean;
  /** Links Method/Constructor/Property to owning Class/Struct/Trait nodeId */
  ownerId?: string;
  /** #1982/#1993: bridge-held enclosing-namespace path (e.g. `NS1`, `Outer.Inner`)
@@ -0,0 +1,112 @@
+import { test, expect } from '@playwright/test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * E2E for the browser folder-upload flow (replaces the removed server-side
+ * directory picker). Mocks the backend so no live gitnexus server is needed.
+ */
+
+const BACKEND_URL = 'http://localhost:4747';
+
+let fixtureDir: string;
+
+test.beforeAll(() => {
+  // A tiny "repo" folder; Playwright sets webkitRelativePath = <folder>/<file>.
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-upload-e2e-'));
+  fixtureDir = path.join(root, 'myrepo');
+  fs.mkdirSync(path.join(fixtureDir, 'src'), { recursive: true });
+  fs.writeFileSync(path.join(fixtureDir, 'README.md'), '# hi\n');
+  fs.writeFileSync(path.join(fixtureDir, 'src', 'index.ts'), 'export const x = 1;\n');
+});
+
+test.beforeEach(async ({ page }) => {
+  await page.route(`${BACKEND_URL}/api/repos`, (route) => route.fulfill({ json: [] }));
+  await page.route(`${BACKEND_URL}/api/info`, (route) =>
+    route.fulfill({ json: { version: '1.0.0', launchContext: 'npx', nodeVersion: 'v22.0.0' } }),
+  );
+  await page.route(`${BACKEND_URL}/api/heartbeat`, (route) =>
+    route.fulfill({
+      status: 200,
+      headers: { 'Content-Type': 'text/event-stream' },
+      body: ':ok\n\n',
+    }),
+  );
+});
+
+test('uploading a folder posts a multipart upload and starts analysis', async ({ page }) => {
+  let uploadContentType = '';
+  await page.route(`${BACKEND_URL}/api/analyze/upload`, async (route) => {
+    uploadContentType = route.request().headers()['content-type'] ?? '';
+    await route.fulfill({ json: { jobId: 'job-e2e', status: 'analyzing' } });
+  });
+  // SSE progress → immediately complete.
+  await page.route(`${BACKEND_URL}/api/analyze/job-e2e/progress`, (route) =>
+    route.fulfill({
+      status: 200,
+      headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },
+      body: 'event: complete\ndata: {"repoName":"myrepo"}\n\n',
+    }),
+  );
+
+  await page.goto('/');
+  await expect(page.getByRole('tab', { name: 'Local Folder' })).toBeVisible({ timeout: 20_000 });
+  await page.getByRole('tab', { name: 'Local Folder' }).click();
+
+  await expect(page.locator('[data-testid="upload-folder"]')).toBeVisible();
+
+  // Select the fixture folder via the hidden webkitdirectory input.
+  await page.locator('[data-testid="folder-upload-input"]').setInputFiles(fixtureDir);
+
+  // The upload endpoint should be hit with a multipart body, and the UI should
+  // leave the input phase (upload button no longer shown).
+  await expect.poll(() => uploadContentType).toContain('multipart/form-data');
+  await expect(page.locator('[data-testid="upload-folder"]')).toBeHidden({ timeout: 10_000 });
+});
+
+test('switching modes mid-upload aborts it and never shows progress', async ({ page }) => {
+  // Hold the upload response until the test releases it, so the mode switch
+  // happens while the POST is in flight (the review 4470339833 repro).
+  let releaseUpload!: () => void;
+  const uploadGate = new Promise<void>((res) => (releaseUpload = res));
+  let uploadAborted = false;
+  let progressOpened = false;
+
+  // The client-side AbortController kills the POST at mode-switch time; that
+  // surfaces as a failed request (net::ERR_ABORTED), not as a response.
+  page.on('requestfailed', (req) => {
+    if (req.url().includes('/api/analyze/upload') && /ABORTED/.test(req.failure()?.errorText ?? ''))
+      uploadAborted = true;
+  });
+  await page.route(`${BACKEND_URL}/api/analyze/upload`, async (route) => {
+    await uploadGate;
+    await route.fulfill({ json: { jobId: 'job-stale', status: 'analyzing' } }).catch(() => {}); // the request may already be gone — that's the point
+  });
+  await page.route(`${BACKEND_URL}/api/analyze/job-stale/progress`, (route) => {
+    progressOpened = true;
+    return route.fulfill({
+      status: 200,
+      headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },
+      body: 'event: complete\ndata: {"repoName":"myrepo"}\n\n',
+    });
+  });
+
+  await page.goto('/');
+  await expect(page.getByRole('tab', { name: 'Local Folder' })).toBeVisible({ timeout: 20_000 });
+  await page.getByRole('tab', { name: 'Local Folder' }).click();
+  await page.locator('[data-testid="folder-upload-input"]').setInputFiles(fixtureDir);
+  await expect(page.locator('[data-testid="upload-progress"]')).toBeVisible();
+
+  // Switch back to GitHub while the upload POST is still pending, then let
+  // the (now-stale) route handler finish.
+  await page.getByRole('tab', { name: 'GitHub URL' }).click();
+  await expect.poll(() => uploadAborted, { timeout: 10_000 }).toBe(true);
+  releaseUpload();
+
+  // The GitHub form stays clean (no error, immediately usable), and no SSE
+  // progress stream is ever opened by the stale upload.
+  await expect(page.getByPlaceholder('https://github.com/owner/repo')).toBeEditable();
+  await expect(page.locator('[data-testid="upload-progress"]')).toBeHidden();
+  expect(progressOpened).toBe(false);
+});
@@ -218,8 +218,8 @@ test.describe('Flow 3: Analyze form', () => {
    // Switch to Local Folder tab
    await page.getByRole('tab', { name: 'Local Folder' }).click();

-    // Browse button should be visible
-    await expect(page.getByText('Browse for folder')).toBeVisible();
+    // Upload-a-folder button should be visible (browser folder upload)
+    await expect(page.locator('[data-testid="upload-folder"]')).toBeVisible();
    await page.screenshot({ path: testInfo.outputPath('local-folder-tab.png') });
  });

@@ -21,14 +21,14 @@
    "@langchain/anthropic": "^1.3.29",
    "@langchain/core": "^1.1.44",
    "@langchain/google-genai": "^2.1.30",
-    "@langchain/langgraph": "^1.3.2",
-    "@langchain/ollama": "^1.2.6",
+    "@langchain/langgraph": "^1.4.1",
+    "@langchain/ollama": "^1.2.7",
    "@langchain/openai": "^1.4.5",
    "@sigma/edge-curve": "^3.1.0",
    "@tailwindcss/vite": "^4.3.0",
    "axios": "^1.16.1",
    "d3": "^7.9.0",
-    "dompurify": "^3.4.7",
+    "dompurify": "^3.4.11",
    "gitnexus-shared": "file:../gitnexus-shared",
    "graphology": "^0.26.0",
    "graphology-indices": "^0.17.0",
@@ -38,20 +38,20 @@
    "graphology-utils": "^2.3.0",
    "i18next": "^26.3.0",
    "i18next-browser-languagedetector": "^8.2.1",
-    "langchain": "^1.4.2",
+    "langchain": "^1.4.4",
    "lru-cache": "^11.2.4",
-    "lucide-react": "^1.16.0",
+    "lucide-react": "^1.17.0",
    "mermaid": "^11.15.0",
-    "mnemonist": "^0.39.0",
+    "mnemonist": "^0.40.4",
    "pandemonium": "^2.4.0",
    "react": "^19.2.5",
-    "react-dom": "^19.2.6",
+    "react-dom": "^19.2.7",
    "react-i18next": "^17.0.8",
    "react-markdown": "^10.1.0",
    "react-syntax-highlighter": "^16.1.1",
    "react-zoom-pan-pinch": "^4.0.3",
    "remark-gfm": "^4.0.1",
-    "sigma": "^3.0.2",
+    "sigma": "^3.0.3",
    "tailwindcss": "^4.2.4",
    "uuid": "^14.0.0",
    "zod": "^4.4.3"
@@ -67,13 +67,13 @@
    "@types/react": "^19.2.14",
    "@types/react-dom": "^19.2.3",
    "@types/react-syntax-highlighter": "^15.5.13",
-    "@vercel/node": "^5.8.8",
+    "@vercel/node": "^5.8.12",
    "@vitejs/plugin-react": "^5.1.4",
-    "@vitest/coverage-v8": "^4.1.5",
+    "@vitest/coverage-v8": "^4.1.8",
    "jsdom": "^29.1.1",
    "tree-sitter-wasms": "^0.1.13",
    "typescript": "^5.4.5",
-    "vite": "^8.0.11",
+    "vite": "^8.0.16",
    "vitest": "^4.1.5",
    "wait-on": "^9.0.5"
  },
@@ -10,7 +10,7 @@ import { StatusBar } from './components/StatusBar';
 import { FileTreePanel } from './components/FileTreePanel';
 import { CodeReferencesPanel } from './components/CodeReferencesPanel';
 import { getActiveProviderConfig } from './core/llm/settings-service';
-import { createKnowledgeGraph } from './core/graph/graph';
+import { buildGraphFromConnectResult } from './lib/apply-connect-result';
 import {
  connectToServer,
  fetchRepos,
@@ -21,6 +21,7 @@ import {
  type BackendRepo,
 } from './services/backend-client';
 import { ERROR_RESET_DELAY_MS } from './config/ui-constants';
+import { parseSkipGraphParam } from './lib/graph-load-decision';
 import { formatBackendError } from './i18n/error-messages';
 import { useTranslation } from 'react-i18next';

@@ -30,6 +31,8 @@ const AppContent = () => {
    viewMode,
    setViewMode,
    setGraph,
+    setGraphMode,
+    setChatOnlyNodeCount,
    setProgress,
    setProjectName,
    progress,
@@ -66,15 +69,14 @@ const AppContent = () => {
      setProjectName(projectName);
      setCurrentRepo(projectName);

-      // Build KnowledgeGraph from server data for visualization
-      const graph = createKnowledgeGraph();
-      for (const node of result.nodes) {
-        graph.addNode(node);
-      }
-      for (const rel of result.relationships) {
-        graph.addRelationship(rel);
-      }
-      setGraph(graph);
+      // Build KnowledgeGraph from server data for visualization. In chat-only
+      // mode the graph download was skipped, so the shared builder keeps an
+      // empty (but non-null) graph and flags the mode so the UI shows the
+      // chat-only empty state, with the node count captured for its notice.
+      const built = buildGraphFromConnectResult(result);
+      setGraph(built.graph);
+      setGraphMode(built.graphMode);
+      setChatOnlyNodeCount(built.graphMode === 'chatOnly' ? built.nodeCount : null);

      // Persist the active project in the URL for bookmarkability and F5 refresh resilience
      const urlObj = new URL(window.location.href);
@@ -84,10 +86,11 @@ const AppContent = () => {
      // Transition directly to exploring view
      setViewMode('exploring');

-      // Initialize agent with backend queries, then start embeddings
+      // Initialize agent with backend queries, then start embeddings. Pass the
+      // chat-only flag so the agent's prompt matches the loaded/skipped graph (#2178).
      try {
        if (getActiveProviderConfig()) {
-          await initializeAgent(projectName);
+          await initializeAgent(projectName, { chatOnly: result.graphSkipped });
        }
        startEmbeddingsWithFallback();
      } catch (err) {
@@ -97,6 +100,8 @@ const AppContent = () => {
    [
      setViewMode,
      setGraph,
+      setGraphMode,
+      setChatOnlyNodeCount,
      setProjectName,
      setCurrentRepo,
      initializeAgent,
@@ -116,6 +121,9 @@ const AppContent = () => {
    const params = new URLSearchParams(window.location.search);
    const serverUrlParam = params.get('server');
    const projectParam = params.get('project');
+    // `?skipGraph=1` forces chat-only, `?skipGraph=0` forces a full graph;
+    // absent → auto-detect by node count. Bookmarkable / survives F5 (#2178).
+    const skipGraphParam = parseSkipGraphParam(params.get('skipGraph'));

    if (!serverUrlParam && !projectParam) return;
    autoConnectRan.current = true;
@@ -162,15 +170,19 @@ const AppContent = () => {
        },
        undefined,
        projectParam || undefined,
-        { awaitAnalysis: true }, // enable backend hold-queue for repos still being analyzed
+        { awaitAnalysis: true, skipGraph: skipGraphParam }, // hold-queue + chat-only control (#2178)
      );
    };

    tryConnect()
      .then(async (result) => {
+        // Set serverBaseUrl BEFORE handleServerConnect: the latter transitions
+        // to 'exploring' (rendering the chat-only overlay + its "Load graph
+        // anyway" button) and then awaits agent init, leaving a window where
+        // loadGraphAnyway would silently no-op on a still-null serverBaseUrl.
+        setServerBaseUrl(baseUrl);
        await handleServerConnect(result);
        setProgress(null);
-        setServerBaseUrl(baseUrl);
        fetchRepos()
          .then((repos) => setAvailableRepos(repos))
          .catch((e) => console.warn('Failed to fetch repo list:', e));
@@ -261,6 +273,9 @@ const AppContent = () => {
            try {
              const repos = await fetchRepos();
              setAvailableRepos(repos);
+              // Auto-detect by size for a freshly-analyzed repo (#2178). A stale
+              // ?skipGraph from a previously-viewed repo must NOT leak in here —
+              // that would bypass the size guard and could re-trigger the hang.
              const result = await connectToServer(url, undefined, undefined, repoName);
              await handleServerConnect(result);
              setServerBaseUrl(normalizeServerUrl(url));
@@ -3,7 +3,7 @@
 *
 * The "empty state" card rendered inside DropZone's Crossfade when the server
 * is connected but zero repos are indexed. Replaces the generic error message
- * with a first-class GitHub URL input flow.
+ * with a first-class repository URL input flow.
 *
 * Rendering context:
 *   DropZone (Crossfade, phase="analyze")
@@ -15,7 +15,7 @@
 * the app to the graph explorer.
 */

-import { Sparkles, Github } from '@/lib/lucide-icons';
+import { Sparkles, GitBranch } from '@/lib/lucide-icons';
 import { RepoAnalyzer } from './RepoAnalyzer';
 import { useTranslation } from 'react-i18next';

@@ -46,7 +46,7 @@ export const AnalyzeOnboarding = ({ onComplete }: AnalyzeOnboardingProps) => {

          {/* Icon */}
          <div className="mx-auto mb-4 flex h-14 w-14 items-center justify-center rounded-2xl border border-accent/30 bg-gradient-to-br from-accent/20 to-accent-dim/10 shadow-glow-soft">
-            <Github className="h-7 w-7 text-accent" />
+            <GitBranch className="h-7 w-7 text-accent" />
          </div>

          <h2 className="text-lg leading-snug font-semibold text-text-primary">
@@ -206,6 +206,10 @@ export const DropZone = ({ onServerConnect }: DropZoneProps) => {
      const abortController = new AbortController();
      abortControllerRef.current = abortController;
      try {
+        // Landing-screen repo selection auto-detects by size (#2178). The
+        // ?skipGraph URL param is a bookmark hint for the initial auto-connect
+        // only; honoring a stale value for a different repo here would risk the
+        // hang it is meant to prevent.
        const result = await connectToServer(
          detectedBackendUrl,
          (p, downloaded, total) => {
@@ -27,6 +27,8 @@ import type { GraphNode } from 'gitnexus-shared';
 import { QueryFAB } from './QueryFAB';
 import Graph from 'graphology';
 import { useTranslation } from 'react-i18next';
+import { LARGE_GRAPH_NODE_THRESHOLD } from '../config/ui-constants';
+import { shouldConfirmGraphLoad } from '../lib/graph-load-decision';

 export interface GraphCanvasHandle {
  focusNode: (nodeId: string) => void;
@@ -55,6 +57,9 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
    animatedNodes,
    graphViewMode,
    setGraphViewMode,
+    graphMode,
+    chatOnlyNodeCount,
+    loadGraphAnyway,
  } = useAppState();
  const [hoveredNodeName, setHoveredNodeName] = useState<string | null>(null);

@@ -193,7 +198,10 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {

  // Update Sigma graph when KnowledgeGraph changes
  useEffect(() => {
-    if (!graph) return;
+    // Skip layout work in chat-only mode: `graph` is non-null but empty, the
+    // overlay covers the canvas, and this guard also future-proofs against a
+    // transient where a populated graph is set while mode is still chat-only.
+    if (!graph || graphMode === 'chatOnly') return;

    let sigmaGraph: Graph<SigmaNodeAttributes, SigmaEdgeAttributes>;

@@ -218,7 +226,7 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
    }

    setSigmaGraph(sigmaGraph);
-  }, [graph, nodeById, setSigmaGraph, graphViewMode]);
+  }, [graph, graphMode, nodeById, setSigmaGraph, graphViewMode]);

  // Update node visibility when filters change
  useEffect(() => {
@@ -256,6 +264,37 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
    resetZoom();
  }, [setSelectedNode, setSigmaSelectedNode, resetZoom]);

+  // Chat-only mode (#2178): the graph download was skipped. `chatOnlyNodeCount`
+  // comes from app state (captured at connect time), so it is authoritative and
+  // available immediately — not derived from the async `availableRepos` list.
+  const handleLoadGraphAnyway = useCallback(() => {
+    // Warn before re-triggering a potentially browser-hanging download. Confirm
+    // whenever the count is large OR unknown — never silently re-load a graph we
+    // can't size, which would risk re-introducing the original #2178 hang. Skip
+    // the prompt only when the count is known to be below the threshold (a small
+    // repo force-skipped via ?skipGraph=1).
+    const needsConfirm = shouldConfirmGraphLoad(chatOnlyNodeCount, LARGE_GRAPH_NODE_THRESHOLD);
+    if (needsConfirm) {
+      // Fail SAFE, not open: if there's no usable confirm dialog (some embedded
+      // webviews) or it throws, treat it as declined rather than loading a
+      // graph we couldn't warn about (#2178).
+      const canPrompt = typeof window !== 'undefined' && typeof window.confirm === 'function';
+      if (!canPrompt) return;
+      let confirmed = false;
+      try {
+        confirmed = window.confirm(
+          chatOnlyNodeCount != null
+            ? t('canvas.chatOnly.loadAnywayWarning', { count: chatOnlyNodeCount.toLocaleString() })
+            : t('canvas.chatOnly.loadAnywayWarningUnknown'),
+        );
+      } catch {
+        return;
+      }
+      if (!confirmed) return;
+    }
+    void loadGraphAnyway();
+  }, [chatOnlyNodeCount, loadGraphAnyway, t]);
+
  return (
    <div className="relative h-full w-full bg-void">
      {/* Background gradient */}
@@ -324,6 +363,32 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
        className="sigma-container h-full w-full cursor-grab active:cursor-grabbing"
      />

+      {/* Chat-only empty state (#2178): graph download was skipped for a large
+          project. Chat works normally; offer an explicit "load anyway" escape. */}
+      {graphMode === 'chatOnly' && (
+        <div className="absolute inset-0 z-20 flex items-center justify-center p-6">
+          <div className="max-w-md rounded-xl border border-border-subtle bg-elevated/95 p-6 text-center shadow-lg backdrop-blur-sm">
+            <h3 className="text-lg font-semibold text-text-primary">
+              {t('canvas.chatOnly.title')}
+            </h3>
+            <p className="mt-2 text-sm text-text-secondary">
+              {chatOnlyNodeCount != null
+                ? t('canvas.chatOnly.descriptionWithCount', {
+                    count: chatOnlyNodeCount.toLocaleString(),
+                  })
+                : t('canvas.chatOnly.description')}
+            </p>
+            <p className="mt-2 text-xs text-text-muted">{t('canvas.chatOnly.citationNote')}</p>
+            <button
+              onClick={handleLoadGraphAnyway}
+              className="mt-4 rounded-md border border-accent/30 bg-accent/20 px-4 py-2 text-sm font-medium text-accent transition-colors hover:bg-accent/30"
+            >
+              {t('canvas.chatOnly.loadAnyway')}
+            </button>
+          </div>
+        </div>
+      )}
+
      {/* Hovered node tooltip - only show when NOT selected */}
      {hoveredNodeName && !sigmaSelectedNode && (
        <div className="pointer-events-none absolute top-4 left-1/2 z-20 -translate-x-1/2 animate-fade-in rounded-lg border border-border-subtle bg-elevated/95 px-3 py-1.5 backdrop-blur-sm">
@@ -27,6 +27,7 @@ import { EmbeddingStatus } from './EmbeddingStatus';
 import { RepoAnalyzer } from './RepoAnalyzer';
 import { LanguageSwitcher } from './LanguageSwitcher';
 import { translateProgressMessage } from '../i18n/progress';
+import { formatBackendError } from '../i18n/error-messages';

 // Color mapping for node types in search results
 const NODE_TYPE_COLORS: Record<string, string> = {
@@ -58,10 +59,11 @@ export const Header = ({
  onAnalyzeComplete,
  onReposChanged,
 }: HeaderProps) => {
-  const { t } = useTranslation(['common', 'header']);
+  const { t } = useTranslation(['common', 'header', 'errors']);
  const {
    projectName,
    graph,
+    graphMode,
    openChatPanel,
    isRightPanelOpen,
    rightPanelTab,
@@ -72,6 +74,7 @@ export const Header = ({
  const [isRepoDropdownOpen, setIsRepoDropdownOpen] = useState(false);
  const [showAnalyzer, setShowAnalyzer] = useState(false);
  const [reanalyzing, setReanalyzing] = useState<string | null>(null); // repo name being re-analyzed
+  const [deleteError, setDeleteError] = useState<string | null>(null); // surfaced when a delete is rejected (e.g. origin-blocked 403)
  const [reanalyzeProgress, setReanalyzeProgress] = useState<JobProgress | null>(null);
  const reanalyzeSseRef = useRef<AbortController | null>(null);
  const repoDropdownRef = useRef<HTMLDivElement>(null);
@@ -305,6 +308,7 @@ export const Header = ({
                                  setReanalyzeProgress(null);
                                  reanalyzeSseRef.current = null;
                                }
+                                setDeleteError(null);
                                try {
                                  await deleteRepo(repo.name);
                                  const updated = await fetchRepos();
@@ -317,7 +321,11 @@ export const Header = ({
                                    window.location.reload();
                                  }
                                } catch (err) {
+                                  // Surface the failure instead of silently no-opping —
+                                  // e.g. an origin-blocked 403 when driving a local
+                                  // backend from the hosted UI.
                                  console.error('Failed to delete repo:', err);
+                                  setDeleteError(formatBackendError(err, t));
                                }
                              }}
                              className="cursor-pointer rounded p-1 text-text-muted/0 transition-all group-hover:text-text-muted hover:!text-red-400"
@@ -330,6 +338,13 @@ export const Header = ({
                      </div>
                    )}

+                    {/* Surfaced delete failure (e.g. origin-blocked 403) */}
+                    {deleteError && (
+                      <div className="px-3 py-2 text-xs text-red-400" role="alert">
+                        {deleteError}
+                      </div>
+                    )}
+
                    {/* Re-analyze progress bar */}
                    {reanalyzing && reanalyzeProgress && (
                      <div className="border-t border-border-subtle bg-accent/5 px-4 py-2.5">
@@ -453,8 +468,9 @@ export const Header = ({
          <span className="hidden sm:inline">✨</span>
        </a>

-        {/* Stats */}
-        {graph && (
+        {/* Stats — hidden in chat-only mode, where the empty-but-non-null graph
+            would otherwise show a misleading "0 nodes / 0 edges" (#2178). */}
+        {graph && graphMode !== 'chatOnly' && (
          <div className="mr-2 flex items-center gap-4 text-xs text-text-muted">
            <span>{t('common:counts.nodes', { count: nodeCount })}</span>
            <span>{t('common:counts.edges', { count: edgeCount })}</span>
@@ -10,28 +10,36 @@ import { useState, useRef, useEffect, useId } from 'react';
 import {
  Github,
  Gitlab,
+  AzureDevops,
  FolderOpen,
  Loader2,
  Check,
  ArrowRight,
  AlertCircle,
  Sparkles,
+  Key,
 } from '@/lib/lucide-icons';
 import {
  startAnalyze,
  cancelAnalyze,
  streamAnalyzeProgress,
+  uploadFolder,
  type JobProgress,
 } from '../services/backend-client';
 import { AnalyzeProgress } from './AnalyzeProgress';
+import { filterRepoFiles } from '@/lib/upload-filter';
 import { useTranslation } from 'react-i18next';

 // ── Helpers ──────────────────────────────────────────────────────────────────

-type InputMode = 'github' | 'gitlab' | 'local';
+type InputMode = 'github' | 'gitlab' | 'azure' | 'local';

 const GITHUB_RE = /^https?:\/\/(www\.)?github\.com\/[^/\s]+\/[^/\s]+/i;
 const GITLAB_RE = /^https?:\/\/[^/\s]+\/[^/\s]+\/[^/\s]+(\/.*)?$/i;
+// One-or-more path segments before `/_git/`, so the legacy single-project
+// cloud form (myorg.visualstudio.com/project/_git/repo) is accepted too —
+// the backend already supports it (isAzureDevOpsUrl / extractRepoName).
+const AZURE_RE = /^https?:\/\/[^/\s]+\/(?:[^/\s]+\/)+_git\/[^/\s]+/i;
 const IS_WINDOWS = navigator.userAgent.toLowerCase().includes('win');

 function isValidGithubUrl(value: string): boolean {
@@ -42,6 +50,10 @@ function isValidGitlabUrl(value: string): boolean {
  return GITLAB_RE.test(value.trim());
 }

+function isValidAzureUrl(value: string): boolean {
+  return AZURE_RE.test(value.trim());
+}
+
 // ── Mode tabs ────────────────────────────────────────────────────────────────

 function ModeTabs({ mode, onChange }: { mode: InputMode; onChange: (m: InputMode) => void }) {
@@ -79,6 +91,19 @@ function ModeTabs({ mode, onChange }: { mode: InputMode; onChange: (m: InputMode
        <Gitlab className="h-3 w-3" />
        {t('repoAnalyzer.gitlabUrl')}
      </button>
+      <button
+        role="tab"
+        aria-selected={mode === 'azure'}
+        onClick={() => onChange('azure')}
+        className={`flex flex-1 cursor-pointer items-center justify-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-all duration-150 ${
+          mode === 'azure'
+            ? 'bg-accent text-white shadow-sm'
+            : 'text-text-muted hover:text-text-secondary'
+        } `}
+      >
+        <AzureDevops className="h-3 w-3" />
+        {t('repoAnalyzer.azureDevOpsUrl')}
+      </button>
      <button
        role="tab"
        aria-selected={mode === 'local'}
@@ -165,10 +190,15 @@ export interface RepoAnalyzerProps {
 export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProps) => {
  const { t } = useTranslation(['common', 'errors', 'onboarding']);
  const inputId = useId();
-  const folderInputRef = useRef<HTMLInputElement>(null);
  const [mode, setMode] = useState<InputMode>('github');
+  const [uploading, setUploading] = useState(false);
+  const [uploadSummary, setUploadSummary] = useState<{ count: number; dropped: number } | null>(
+    null,
+  );
  const [githubUrl, setGithubUrl] = useState('');
+  const [githubToken, setGithubToken] = useState('');
  const [gitlabUrl, setGitlabUrl] = useState('');
+  const [azureUrl, setAzureUrl] = useState('');
  const [localPath, setLocalPath] = useState('');
  const [phase, setPhase] = useState<InternalPhase>('input');
  const [validationError, setValidationError] = useState<string | null>(null);
@@ -181,35 +211,84 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp

  const jobIdRef = useRef<string | null>(null);
  const sseControllerRef = useRef<AbortController | null>(null);
+  // Owns the in-flight analyze/upload request. The controller doubles as the
+  // staleness token: each request captures its own controller in a closure and
+  // bails after the await when that controller was aborted, so a resolution
+  // arriving after a mode switch / cancel / unmount can never drive state.
+  const requestControllerRef = useRef<AbortController | null>(null);
  const completeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const folderInputRef = useRef<HTMLInputElement>(null);

  useEffect(() => {
    return () => {
      sseControllerRef.current?.abort();
+      requestControllerRef.current?.abort();
      if (completeTimerRef.current) clearTimeout(completeTimerRef.current);
    };
  }, []);

-  const handleModeChange = (m: InputMode) => {
-    setMode(m);
-    setGithubUrl('');
-    setGitlabUrl('');
-    setLocalPath('');
-    setValidationError(null);
+  // Abort any in-flight analyze/upload request so its settlement can't drive
+  // state. Aborting is load-bearing: once a mode switch resets `uploading`,
+  // the `uploading || isLoading` re-entry guard no longer covers the stale
+  // request — only its aborted signal does.
+  const invalidateRequest = (): void => {
+    requestControllerRef.current?.abort();
+    requestControllerRef.current = null;
  };

-  // Use the browser's native directory picker (webkitdirectory doesn't give paths,
-  // so we use a text input + a "Browse" button that opens a standard file input
-  // to let users pick files from the folder — the path is typed manually since
-  // browsers don't expose absolute paths for security reasons).
-  // For local paths, the user types or pastes the absolute path.
+  // Invalidate the previous request and hand the caller a fresh controller.
+  const renewRequestController = (): AbortController => {
+    invalidateRequest();
+    const controller = new AbortController();
+    requestControllerRef.current = controller;
+    return controller;
+  };
+
+  // An upload that resolved after invalidation has still created a server-side
+  // job; cancel it so the single analyze slot isn't held for the job's full
+  // duration. Upload-path only: every upload owns a fresh job (the server
+  // stages each upload into a unique dir, never dedup-aliasing), whereas URL
+  // analyzes dedup-alias by repo — the returned jobId may belong to a job
+  // another session (or this user's own resubmit) is actively watching, so
+  // cancelling on that path could kill a live analysis. A stale URL job is
+  // left to finish: a same-URL resubmit re-attaches to it via dedup, and the
+  // server's job timeout/TTL sweep bounds the slot occupancy.
+  const cancelStaleUploadJob = (jobId: string): void => {
+    void cancelAnalyze(jobId).catch(() => {});
+  };
+
+  const handleModeChange = (m: InputMode) => {
+    // ModeTabs fires onChange on every click, including the already-active
+    // tab — never abort the user's own in-flight request for a no-op click.
+    if (m === mode) return;
+    invalidateRequest();
+    setMode(m);
+    setGithubUrl('');
+    setGithubToken('');
+    setGitlabUrl('');
+    setAzureUrl('');
+    setLocalPath('');
+    setValidationError(null);
+    setUploadSummary(null);
+    setUploading(false);
+    // An aborted request no longer resolves to move `phase` off 'starting';
+    // reset so the new mode's form is immediately usable (also clears a stale
+    // 'error' phase). Only reachable while showInput is true.
+    setPhase('input');
+  };
+
+  // Local-folder mode uploads the selected folder's files (the browser never
+  // exposes an absolute path, so the old typed-path/browse approach couldn't
+  // work — see handleFolderUpload). A typed server path is also still accepted.

  const canSubmit =
    mode === 'github'
      ? isValidGithubUrl(githubUrl) && (phase === 'input' || phase === 'error')
      : mode === 'gitlab'
        ? isValidGitlabUrl(gitlabUrl) && (phase === 'input' || phase === 'error')
-        : localPath.trim().length > 1 && (phase === 'input' || phase === 'error');
+        : mode === 'azure'
+          ? isValidAzureUrl(azureUrl) && (phase === 'input' || phase === 'error')
+          : localPath.trim().length > 1 && (phase === 'input' || phase === 'error');

  const handleAnalyze = async () => {
    if (mode === 'github' && !isValidGithubUrl(githubUrl)) {
@@ -220,6 +299,10 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
      setValidationError('Please enter a valid GitLab repository URL.');
      return;
    }
+    if (mode === 'azure' && !isValidAzureUrl(azureUrl)) {
+      setValidationError(t('errors:invalidAzureDevOpsUrl'));
+      return;
+    }
    if (mode === 'local' && localPath.trim().length < 2) {
      setValidationError(t('errors:missingFolderPath'));
      return;
@@ -228,46 +311,114 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
    setValidationError(null);
    setPhase('starting');

+    // Staleness guard only (no wire abort): the POST is short-lived and
+    // self-terminates, but its resolution must not drive state after a mode
+    // switch / cancel / unmount invalidated this request.
+    const controller = renewRequestController();
    try {
      const request =
        mode === 'github'
-          ? { url: githubUrl.trim() }
+          ? {
+              url: githubUrl.trim(),
+              ...(githubToken.trim() ? { token: githubToken.trim() } : {}),
+            }
          : mode === 'gitlab'
            ? { url: gitlabUrl.trim() }
-            : { path: localPath.trim() };
+            : mode === 'azure'
+              ? { url: azureUrl.trim() }
+              : { path: localPath.trim() };
      const { jobId } = await startAnalyze(request);
-      jobIdRef.current = jobId;
-      setPhase('analyzing');
+      // Stale resolution: return without cancelling — URL jobIds may be
+      // dedup-aliased to a job another session owns (see cancelStaleUploadJob).
+      if (controller.signal.aborted) return;

      const nameSource =
        mode === 'github'
          ? githubUrl.trim()
          : mode === 'gitlab'
            ? gitlabUrl.trim()
-            : localPath.trim();
-      const controller = streamAnalyzeProgress(
-        jobId,
-        (p) => setProgress(p),
-        (data) => {
-          const name =
-            data.repoName ??
-            nameSource.split(/[/\\]/).filter(Boolean).at(-1) ??
-            t('onboarding:repoAnalyzer.defaultRepoName');
-          setCompletedRepoName(name);
-          setPhase('done');
-          sseControllerRef.current = null;
-          completeTimerRef.current = setTimeout(() => {
-            completeTimerRef.current = null;
-            onComplete(name);
-          }, 1200);
-        },
-        (errMsg) => {
-          setValidationError(errMsg || t('errors:analysisFailed'));
-          setPhase('error');
-        },
-      );
-      sseControllerRef.current = controller;
+            : mode === 'azure'
+              ? azureUrl.trim()
+              : localPath.trim();
+      trackJob(jobId, nameSource);
    } catch (err) {
+      // Unmount aborts the controller, so this also covers the unmounted case.
+      if (controller.signal.aborted) return;
+      setValidationError(err instanceof Error ? err.message : t('errors:startAnalysisFailed'));
+      setPhase('error');
+    }
+  };
+
+  // Drive an already-created analysis job through the SSE progress stream to
+  // completion. Shared by the path/URL analyze flow and the folder-upload flow.
+  const trackJob = (jobId: string, fallbackNameSource: string | null) => {
+    // Callers reach here only with a live (non-aborted) request controller, so
+    // the component is mounted — unmount aborts the controller.
+    jobIdRef.current = jobId;
+    setPhase('analyzing');
+    const controller = streamAnalyzeProgress(
+      jobId,
+      (p) => setProgress(p),
+      (data) => {
+        const name =
+          data.repoName ??
+          (fallbackNameSource
+            ? fallbackNameSource.split(/[/\\]/).filter(Boolean).at(-1)
+            : undefined) ??
+          t('onboarding:repoAnalyzer.defaultRepoName');
+        setCompletedRepoName(name);
+        setGithubToken('');
+        setPhase('done');
+        sseControllerRef.current = null;
+        completeTimerRef.current = setTimeout(() => {
+          completeTimerRef.current = null;
+          onComplete(name);
+        }, 1200);
+      },
+      (errMsg) => {
+        setValidationError(errMsg || t('errors:analysisFailed'));
+        setPhase('error');
+      },
+    );
+    sseControllerRef.current = controller;
+  };
+
+  // Upload a browser-selected folder (webkitdirectory) and start analysis. The
+  // upload endpoint returns a jobId, which then joins the normal SSE flow.
+  const handleFolderUpload = async (fileList: FileList) => {
+    if (uploading || isLoading) return; // guard against a concurrent upload
+    const { files, manifest, droppedCount } = filterRepoFiles(fileList);
+    if (files.length === 0) {
+      setValidationError(t('onboarding:repoAnalyzer.upload.empty'));
+      return;
+    }
+    setValidationError(null);
+    setUploadSummary({ count: files.length, dropped: droppedCount });
+    setUploading(true);
+    setPhase('starting');
+    // The selected folder's name (manifest entries are `<folder>/<rest>`) is a
+    // sensible fallback if the server's complete event omits repoName.
+    const folderName = manifest[0]?.split('/')[0] ?? null;
+    const controller = renewRequestController();
+    try {
+      const { jobId } = await uploadFolder(files, manifest, controller.signal);
+      if (controller.signal.aborted) {
+        // The abort raced the response: the server already created the job.
+        // (Unmount aborts the controller, so this also covers unmounted.)
+        cancelStaleUploadJob(jobId);
+        return;
+      }
+      setUploading(false);
+      trackJob(jobId, folderName);
+    } catch (err) {
+      // An abort surfaces in two shapes — BackendError('Request aborted')
+      // when it lands during fetch, raw AbortError when it lands during the
+      // response-body read — so branch on the closure controller's signal,
+      // never on the error identity. In the second shape the server may have
+      // already launched a job whose id we never learn; that orphan is bounded
+      // by the server's job timeout and terminal-job TTL sweep.
+      if (controller.signal.aborted) return;
+      setUploading(false);
      setValidationError(err instanceof Error ? err.message : t('errors:startAnalysisFailed'));
      setPhase('error');
    }
@@ -276,14 +427,21 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
  const handleCancel = async () => {
    sseControllerRef.current?.abort();
    sseControllerRef.current = null;
+    // Defensive: no UI path can reach handleCancel while a request is in
+    // flight (the cancel affordance renders only at phase === 'analyzing'),
+    // but invalidate it anyway so the guard topology has no holes.
+    invalidateRequest();
    if (jobIdRef.current) {
      try {
        await cancelAnalyze(jobIdRef.current);
      } catch {}
      jobIdRef.current = null;
    }
+    setGithubToken('');
    setPhase('input');
    setProgress({ phase: 'queued', percent: 0, message: t('common:analyzePhases.queued') });
+    setUploading(false);
+    setUploadSummary(null);
  };

  const isLoading = phase === 'starting';
@@ -344,6 +502,39 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
              </div>
            )}
          </div>
+
+          {/* Optional GitHub Personal Access Token for private repos */}
+          <div className="space-y-1.5 pt-1">
+            <label
+              htmlFor={`${inputId}-token`}
+              className="block text-xs font-medium tracking-wider text-text-secondary uppercase"
+            >
+              {t('onboarding:repoAnalyzer.githubTokenLabel')}
+            </label>
+            <div className="flex items-center gap-3 rounded-xl border border-border-default bg-void px-4 py-3 transition-all duration-200 focus-within:border-accent/40">
+              <Key className="h-4 w-4 shrink-0 text-text-muted" />
+              <input
+                id={`${inputId}-token`}
+                type="password"
+                value={githubToken}
+                onChange={(e) => setGithubToken(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' && canSubmit && !isLoading) {
+                    e.preventDefault();
+                    handleAnalyze();
+                  }
+                }}
+                disabled={isLoading}
+                placeholder={t('onboarding:repoAnalyzer.githubTokenPlaceholder')}
+                autoComplete="off"
+                spellCheck={false}
+                className="flex-1 border-none bg-transparent font-mono text-sm text-text-primary outline-none placeholder:text-text-muted disabled:opacity-50"
+              />
+            </div>
+            <p className="text-xs text-text-muted">
+              {t('onboarding:repoAnalyzer.githubTokenHelp')}
+            </p>
+          </div>
        </div>
      )}

@@ -400,6 +591,61 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
        </div>
      )}

+      {/* Azure DevOps URL input */}
+      {showInput && mode === 'azure' && (
+        <div className="space-y-2">
+          <label
+            htmlFor={inputId}
+            className="block text-xs font-medium tracking-wider text-text-secondary uppercase"
+          >
+            {t('onboarding:repoAnalyzer.azureDevOpsRepositoryUrl')}
+          </label>
+          <div
+            className={`flex items-center gap-3 rounded-xl border bg-void px-4 py-3.5 transition-all duration-200 ${
+              validationError && phase === 'error'
+                ? 'border-red-500/50'
+                : isValidAzureUrl(azureUrl)
+                  ? 'border-accent/50 shadow-[0_0_0_3px_rgba(124,58,237,0.08)]'
+                  : 'border-border-default focus-within:border-accent/40'
+            } `}
+          >
+            <AzureDevops className="h-4 w-4 shrink-0 text-text-muted" />
+            <input
+              id={inputId}
+              type="url"
+              value={azureUrl}
+              onChange={(e) => {
+                setAzureUrl(e.target.value);
+                if (validationError) setValidationError(null);
+              }}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter' && canSubmit && !isLoading) {
+                  e.preventDefault();
+                  handleAnalyze();
+                }
+              }}
+              disabled={isLoading}
+              placeholder="http://azuredevops.example.com/Collection/Project/_git/Repo"
+              autoComplete="url"
+              spellCheck={false}
+              className="flex-1 border-none bg-transparent font-mono text-sm text-text-primary outline-none placeholder:text-text-muted disabled:opacity-50"
+            />
+            {azureUrl.length > 10 && (
+              <div className="shrink-0">
+                {isValidAzureUrl(azureUrl) ? (
+                  <Check className="h-3.5 w-3.5 text-emerald-400" />
+                ) : (
+                  <AlertCircle className="h-3.5 w-3.5 text-text-muted" />
+                )}
+              </div>
+            )}
+          </div>
+          <p className="text-xs text-text-muted">
+            {t('onboarding:repoAnalyzer.azureDevOpsSupported')}
+          </p>
+        </div>
+      )}
+
      {/* Local folder input */}
      {showInput && mode === 'local' && (
        <div className="space-y-2">
@@ -443,35 +689,51 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
              <Check className="h-3.5 w-3.5 shrink-0 text-emerald-400" />
            )}
          </div>
-          {/* Native folder picker + Browse button — below the input */}
+          {/* Upload a folder from your computer — no server path or mount needed.
+              The browser can't expose an absolute path, so we upload the files. */}
          <input
            ref={folderInputRef}
            type="file"
            // @ts-expect-error -- webkitdirectory is non-standard but widely supported
            webkitdirectory=""
+            multiple
            className="hidden"
+            data-testid="folder-upload-input"
            onChange={(e) => {
-              const files = e.target.files;
-              if (files && files.length > 0) {
-                const rel = files[0].webkitRelativePath;
-                const folderName = rel.split('/')[0];
-                if (folderName) {
-                  setLocalPath(folderName);
-                  setValidationError(null);
-                }
+              if (e.target.files && e.target.files.length > 0) {
+                handleFolderUpload(e.target.files);
              }
              e.target.value = '';
            }}
          />
          <button
            type="button"
+            data-testid="upload-folder"
            onClick={() => folderInputRef.current?.click()}
            disabled={isLoading}
            className="flex w-full cursor-pointer items-center justify-center gap-2 rounded-lg border border-border-subtle bg-elevated px-3 py-2 text-xs font-medium text-text-secondary transition-all duration-150 hover:bg-hover hover:text-text-primary disabled:opacity-50"
          >
            <FolderOpen className="h-3.5 w-3.5" />
-            {t('onboarding:repoAnalyzer.browseForFolder')}
+            {t('onboarding:repoAnalyzer.upload.button')}
          </button>
+          {uploading && (
+            <div role="status" aria-busy="true" data-testid="upload-progress" className="space-y-1">
+              <div className="h-1.5 w-full overflow-hidden rounded-full bg-elevated">
+                <div className="h-full w-1/3 animate-pulse rounded-full bg-accent" />
+              </div>
+              <p className="text-xs text-text-muted">
+                {t('onboarding:repoAnalyzer.upload.uploading')}
+              </p>
+            </div>
+          )}
+          {uploadSummary && !uploading && phase !== 'error' && (
+            <p className="text-xs text-text-muted" data-testid="upload-summary">
+              {t('onboarding:repoAnalyzer.upload.selected', {
+                fileCount: uploadSummary.count,
+                dropped: uploadSummary.dropped,
+              })}
+            </p>
+          )}
        </div>
      )}

@@ -23,6 +23,7 @@ export const RightPanel = () => {
    isRightPanelOpen,
    setRightPanelOpen,
    graph,
+    graphMode,
    addCodeReference,
    // LLM / chat state
    chatMessages,
@@ -283,6 +284,14 @@ export const RightPanel = () => {
            </div>
          </div>

+          {/* Chat-only notice: the graph wasn't loaded for this large project, so
+              inline node citations won't pin in the (absent) graph view (#2178). */}
+          {graphMode === 'chatOnly' && (
+            <div className="border-b border-amber-500/20 bg-amber-500/10 px-4 py-2 text-[11px] text-amber-200/90">
+              {t('chat:chatOnly.banner')}
+            </div>
+          )}
+
          {/* Status / errors */}
          {agentError && (
            <div className="flex items-center gap-2 border-b border-rose-500/30 bg-rose-500/10 px-4 py-3 text-sm text-rose-100">
@@ -5,7 +5,7 @@ import { useTranslation } from 'react-i18next';
 import { translateProgressMessage } from '../i18n/progress';

 export const StatusBar = () => {
-  const { graph, progress } = useAppState();
+  const { graph, graphMode, progress } = useAppState();
  const { t } = useTranslation(['common', 'graph']);

  const nodeCount = graph?.nodes.length ?? 0;
@@ -68,7 +68,9 @@ export const StatusBar = () => {

      {/* Right - Stats */}
      <div className="flex items-center gap-3" data-testid="graph-stats">
-        {graph && (
+        {/* Suppress counts in chat-only mode: the empty-but-non-null graph would
+            otherwise show a misleading "0 nodes / 0 edges" for a large repo (#2178). */}
+        {graph && graphMode !== 'chatOnly' && (
          <>
            <span>{t('common:counts.nodes', { count: nodeCount })}</span>
            <span className="text-border-default">•</span>
@@ -8,6 +8,40 @@ export const DEFAULT_BACKEND_URL =
 export const DEFAULT_OLLAMA_BASE_URL = 'http://localhost:11434';
 export const DEFAULT_OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';

+/**
+ * Default node-count above which the WebUI connects in chat-only mode (skips
+ * the full graph download). Grounded in sigma.js/graphology prior art: ~10K
+ * nodes render smoothly, complex-styled rendering struggles past ~5K, and the
+ * force-layout degrades beyond ~50K edges. GitNexus renders labeled nodes with
+ * force layout and has ~1.7x more edges than nodes, so the edge cliff is crossed
+ * around ~25-30K nodes. Override at deploy time via
+ * window.__GITNEXUS_CONFIG__.largeGraphNodeThreshold. See issue #2178.
+ */
+const DEFAULT_LARGE_GRAPH_NODE_THRESHOLD = 25_000;
+
+/**
+ * Default edge-count above which the WebUI connects in chat-only mode. The
+ * browser force-layout cliff is edge-driven (degrades beyond ~50K edges), and
+ * GitNexus graphs carry more edges than nodes, so an edge-heavy but node-light
+ * repo can still hang even when under the node threshold. Override via
+ * window.__GITNEXUS_CONFIG__.largeGraphEdgeThreshold. See issue #2178.
+ */
+const DEFAULT_LARGE_GRAPH_EDGE_THRESHOLD = 50_000;
+
+const resolveThreshold = (override: number | undefined, fallback: number): number =>
+  // Ignore non-finite, NaN, or non-positive overrides — fall back to the default.
+  typeof override === 'number' && Number.isFinite(override) && override > 0 ? override : fallback;
+
+export const LARGE_GRAPH_NODE_THRESHOLD = resolveThreshold(
+  typeof window !== 'undefined' ? window.__GITNEXUS_CONFIG__?.largeGraphNodeThreshold : undefined,
+  DEFAULT_LARGE_GRAPH_NODE_THRESHOLD,
+);
+
+export const LARGE_GRAPH_EDGE_THRESHOLD = resolveThreshold(
+  typeof window !== 'undefined' ? window.__GITNEXUS_CONFIG__?.largeGraphEdgeThreshold : undefined,
+  DEFAULT_LARGE_GRAPH_EDGE_THRESHOLD,
+);
+
 /** Minimum Node.js version required by the gitnexus CLI (injected by Vite from package.json engines). */
 declare const __REQUIRED_NODE_VERSION__: string;
 export const REQUIRED_NODE_VERSION = __REQUIRED_NODE_VERSION__;
@@ -33,7 +33,11 @@ import type {
  AgentStreamChunk,
  AgentHistoryMessage,
 } from './types';
-import { type CodebaseContext, buildDynamicSystemPrompt } from './context-builder';
+import {
+  type CodebaseContext,
+  buildDynamicSystemPrompt,
+  CHAT_ONLY_PROMPT_NOTE,
+} from './context-builder';
 import { DEFAULT_OLLAMA_BASE_URL, DEFAULT_OPENROUTER_BASE_URL } from '../../config/ui-constants';
 import {
  DeepSeekChatOpenAI,
@@ -357,14 +361,20 @@ export const createGraphRAGAgent = (
  config: ProviderConfig,
  backend: GraphRAGBackend,
  codebaseContext?: CodebaseContext,
+  chatOnly = false,
 ) => {
  const model = createChatModel(config);
  const tools = createGraphRAGTools(backend);

-  // Use dynamic prompt if context is provided, otherwise use base prompt
+  // Use dynamic prompt if context is provided, otherwise use base prompt. The
+  // chat-only note (graph not loaded, #2178) must apply in BOTH branches — when
+  // codebaseContext is absent, buildDynamicSystemPrompt is never called, so
+  // append the note here too.
  const systemPrompt = codebaseContext
-    ? buildDynamicSystemPrompt(BASE_SYSTEM_PROMPT, codebaseContext)
-    : BASE_SYSTEM_PROMPT;
+    ? buildDynamicSystemPrompt(BASE_SYSTEM_PROMPT, codebaseContext, chatOnly)
+    : chatOnly
+      ? `${BASE_SYSTEM_PROMPT}${CHAT_ONLY_PROMPT_NOTE}`
+      : BASE_SYSTEM_PROMPT;

  // Log the full prompt for debugging
  if (import.meta.env.DEV) {
@@ -413,7 +413,27 @@ export function formatContextForPrompt(context: CodebaseContext): string {
 * Build the complete dynamic system prompt
 * Context is appended at the END so core instructions remain at the top
 */
-export function buildDynamicSystemPrompt(basePrompt: string, context: CodebaseContext): string {
+/**
+ * Note appended in chat-only mode (graph download skipped for a large project,
+ * #2178). It supersedes the static VISUAL GROUNDING section in BASE_SYSTEM_PROMPT
+ * so the agent stops claiming the user sees a graph or that node citations
+ * highlight — neither is true when the in-memory graph is empty.
+ */
+export const CHAT_ONLY_PROMPT_NOTE = `
+
+---
+
+## ⚠️ CHAT-ONLY MODE (graph not loaded)
+The knowledge graph is NOT loaded in the UI for this project (it was too large to render). This OVERRIDES the VISUAL GROUNDING section above:
+- \`[[Type:Name]]\` node citations will NOT highlight anything — avoid relying on them.
+- Prefer \`[[path:START-END]]\` file citations, which still resolve and open the file.
+- All your tools (search, cypher, grep, read) work normally against the backend; only the visual graph is absent.`;
+
+export function buildDynamicSystemPrompt(
+  basePrompt: string,
+  context: CodebaseContext,
+  chatOnly = false,
+): string {
  const contextSection = formatContextForPrompt(context);

  // Append context at the END - keeps core instructions at top for better adherence
@@ -422,5 +442,5 @@ export function buildDynamicSystemPrompt(basePrompt: string, context: CodebaseCo
 ---

 ## 📦 CURRENT CODEBASE
-${contextSection}`;
+${contextSection}${chatOnly ? CHAT_ONLY_PROMPT_NOTE : ''}`;
 }
@@ -19,4 +19,21 @@ describe('GraphState', () => {
    });
    expect(result.current.graphViewMode).toBe('tree');
  });
+
+  it('should default graphMode to "full"', () => {
+    const { result } = renderHook(() => useGraphState(), { wrapper });
+    expect(result.current.graphMode).toBe('full');
+  });
+
+  it('should switch graphMode to "chatOnly" and back', () => {
+    const { result } = renderHook(() => useGraphState(), { wrapper });
+    act(() => {
+      result.current.setGraphMode('chatOnly');
+    });
+    expect(result.current.graphMode).toBe('chatOnly');
+    act(() => {
+      result.current.setGraphMode('full');
+    });
+    expect(result.current.graphMode).toBe('full');
+  });
 });
@@ -2,6 +2,9 @@ import { createContext, useContext, useCallback, useMemo, useState, ReactNode }
 import type { GraphNode, NodeLabel } from 'gitnexus-shared';
 import type { KnowledgeGraph } from '../../core/graph/types';
 import { DEFAULT_VISIBLE_LABELS, DEFAULT_VISIBLE_EDGES, type EdgeType } from '../../lib/constants';
+import type { GraphMode } from '../../lib/apply-connect-result';
+
+export type { GraphMode };

 interface GraphStateContextValue {
  graph: KnowledgeGraph | null;
@@ -18,6 +21,22 @@ interface GraphStateContextValue {
  setHighlightedNodeIds: (ids: Set<string>) => void;
  graphViewMode: 'force' | 'tree' | 'circles';
  setGraphViewMode: (mode: 'force' | 'tree' | 'circles') => void;
+  /**
+   * Whether the in-memory graph was downloaded ('full') or skipped for a large
+   * project ('chatOnly'). In chat-only mode `graph` is an empty-but-non-null
+   * KnowledgeGraph so existing `graph?.` consumers keep working; this flag is
+   * the explicit signal that drives the chat-only empty-state UI. See #2178.
+   */
+  graphMode: GraphMode;
+  setGraphMode: (mode: GraphMode) => void;
+  /**
+   * Node count of the connected repo when in chat-only mode (from the connect
+   * result's repo stats), or null when unknown. Used to size and gate the
+   * chat-only empty-state notice and its "load anyway" warning without waiting
+   * on the async `availableRepos` list. See #2178.
+   */
+  chatOnlyNodeCount: number | null;
+  setChatOnlyNodeCount: (count: number | null) => void;
 }

 const GraphStateContext = createContext<GraphStateContextValue | null>(null);
@@ -30,6 +49,8 @@ export const GraphStateProvider = ({ children }: { children: ReactNode }) => {
  const [depthFilter, setDepthFilter] = useState<number | null>(null);
  const [highlightedNodeIds, setHighlightedNodeIds] = useState<Set<string>>(new Set());
  const [graphViewMode, setGraphViewMode] = useState<'force' | 'tree' | 'circles'>('force');
+  const [graphMode, setGraphMode] = useState<GraphMode>('full');
+  const [chatOnlyNodeCount, setChatOnlyNodeCount] = useState<number | null>(null);

  const toggleLabelVisibility = useCallback((label: NodeLabel) => {
    setVisibleLabels((prev) =>
@@ -59,6 +80,10 @@ export const GraphStateProvider = ({ children }: { children: ReactNode }) => {
      setHighlightedNodeIds,
      graphViewMode,
      setGraphViewMode,
+      graphMode,
+      setGraphMode,
+      chatOnlyNodeCount,
+      setChatOnlyNodeCount,
    }),
    [
      graph,
@@ -68,6 +93,8 @@ export const GraphStateProvider = ({ children }: { children: ReactNode }) => {
      depthFilter,
      highlightedNodeIds,
      graphViewMode,
+      graphMode,
+      chatOnlyNodeCount,
    ],
  );

@@ -10,7 +10,7 @@ import {
 } from 'react';
 import type { GraphNode, NodeLabel, PipelineProgress } from 'gitnexus-shared';
 import type { KnowledgeGraph } from '../core/graph/types';
-import { createKnowledgeGraph } from '../core/graph/graph';
+import { buildGraphFromConnectResult } from '../lib/apply-connect-result';
 import type {
  LLMSettings,
  AgentStreamChunk,
@@ -43,7 +43,7 @@ import { ERROR_RESET_DELAY_MS } from '../config/ui-constants';
 import i18n from '../i18n';
 import { normalizePath } from '../lib/path-resolution';
 import { FILE_REF_REGEX, NODE_REF_REGEX } from '../lib/grounding-patterns';
-import { GraphStateProvider, useGraphState } from './app-state/graph';
+import { GraphStateProvider, useGraphState, type GraphMode } from './app-state/graph';

 export const AUTO_START_EMBEDDINGS_STORAGE_KEY = 'gitnexus.autoStartEmbeddings';

@@ -127,6 +127,13 @@ interface AppState {
  graphViewMode: 'force' | 'tree' | 'circles';
  setGraphViewMode: (mode: 'force' | 'tree' | 'circles') => void;

+  // Graph load mode (full download vs chat-only / skipped graph)
+  graphMode: GraphMode;
+  setGraphMode: (mode: GraphMode) => void;
+  // Connected repo's node count while in chat-only mode (null when unknown)
+  chatOnlyNodeCount: number | null;
+  setChatOnlyNodeCount: (count: number | null) => void;
+
  // Query state
  highlightedNodeIds: Set<string>;
  setHighlightedNodeIds: (ids: Set<string>) => void;
@@ -163,6 +170,8 @@ interface AppState {
  setAvailableRepos: (repos: BackendRepo[]) => void;
  switchRepo: (repoName: string) => Promise<void>;
  setCurrentRepo: (repoName: string) => void;
+  /** Download the full graph for the current repo after a chat-only connect (#2178). */
+  loadGraphAnyway: () => Promise<void>;

  // Worker API (shared across app)
  runQuery: (cypher: string) => Promise<any[]>;
@@ -195,7 +204,7 @@ interface AppState {

  // LLM methods
  refreshLLMSettings: () => void;
-  initializeAgent: (overrideProjectName?: string) => Promise<void>;
+  initializeAgent: (overrideProjectName?: string, opts?: { chatOnly?: boolean }) => Promise<void>;
  sendChatMessage: (message: string) => Promise<void>;
  stopChatResponse: () => void;
  clearChat: () => void;
@@ -238,6 +247,10 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
    setHighlightedNodeIds,
    graphViewMode,
    setGraphViewMode,
+    graphMode,
+    setGraphMode,
+    chatOnlyNodeCount,
+    setChatOnlyNodeCount,
  } = useGraphState();

  // Right Panel
@@ -591,13 +604,24 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
  const chatAbortRef = useRef<AbortController | null>(null);
  const chatStateRef = useRef<'idle' | 'streaming' | 'aborting'>('idle');

+  // Mirror graphMode into a ref so initializeAgent's deferred callers (lazy chat
+  // init, settings-driven re-init) can read the current mode without re-creating
+  // the callback; connect-flow callers pass an explicit chatOnly flag. (#2178)
+  const graphModeRef = useRef(graphMode);
+  useEffect(() => {
+    graphModeRef.current = graphMode;
+  }, [graphMode]);
+
  const initializeAgent = useCallback(
-    async (overrideProjectName?: string): Promise<void> => {
+    async (overrideProjectName?: string, opts?: { chatOnly?: boolean }): Promise<void> => {
      const config = getActiveProviderConfig();
      if (!config) {
        setAgentError('Please configure an LLM provider in settings');
        return;
      }
+      // Explicit flag from connect-flow callers (race-safe); otherwise fall back
+      // to live mode via the ref so deferred callers stay correct too. (#2178)
+      const chatOnly = opts?.chatOnly ?? graphModeRef.current === 'chatOnly';

      setIsAgentInitializing(true);
      setAgentError(null);
@@ -628,7 +652,7 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
            backendReadFile(filePath, { repo }).then((r) => r.content),
        };

-        agentRef.current = createGraphRAGAgent(config, backend, codebaseContext);
+        agentRef.current = createGraphRAGAgent(config, backend, codebaseContext, chatOnly);
        setIsAgentReady(true);
        setAgentError(null);
        if (import.meta.env.DEV) {
@@ -1153,9 +1177,15 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
      setCodeReferences([]);
      setCodePanelOpen(false);
      setCodeReferenceFocus(null);
+      // Reset graph-load mode up front so a FAILED switch can't leave the
+      // previous repo's stale chat-only overlay showing (#2178). The success
+      // path re-derives the mode from the connect result below.
+      setGraphMode('full');
+      setChatOnlyNodeCount(null);

      let connectedRepo: BackendRepo | undefined;
      let pNameStr = repoName || 'server-project';
+      let connectedChatOnly = false;

      try {
        const result: ConnectResult = await connectToServer(
@@ -1205,10 +1235,14 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
        connectedRepo = result.repoInfo;
        pNameStr = pName;

-        const newGraph = createKnowledgeGraph();
-        for (const node of result.nodes) newGraph.addNode(node);
-        for (const rel of result.relationships) newGraph.addRelationship(rel);
-        setGraph(newGraph);
+        // In chat-only mode the graph download was skipped; the shared builder
+        // keeps an empty (but non-null) graph so existing `graph?.` consumers
+        // stay happy, and reports the mode + node count in lockstep.
+        const built = buildGraphFromConnectResult(result);
+        setGraph(built.graph);
+        setGraphMode(built.graphMode);
+        setChatOnlyNodeCount(built.graphMode === 'chatOnly' ? built.nodeCount : null);
+        connectedChatOnly = built.graphMode === 'chatOnly';
      } catch (err: unknown) {
        console.error('Repo switch failed:', err);
        setProgress({
@@ -1227,9 +1261,13 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
      }

      if (pNameStr) {
-        // Persist the selected project in the URL so a refresh re-opens it
+        // Persist the selected project in the URL so a refresh re-opens it.
+        // Drop any `?skipGraph` override: a deliberate repo switch should make a
+        // fresh per-repo decision (auto-detect) on the next refresh rather than
+        // carry the previous repo's forced mode (#2178).
        const urlObj = new URL(window.location.href);
        urlObj.searchParams.set('project', pNameStr);
+        urlObj.searchParams.delete('skipGraph');
        window.history.replaceState(null, '', urlObj.toString());
      }

@@ -1241,7 +1279,7 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
      // Re-initialize agent with the new repo's graph context
      try {
        if (getActiveProviderConfig()) {
-          await initializeAgent(pNameStr);
+          await initializeAgent(pNameStr, { chatOnly: connectedChatOnly });
        }
        setViewMode('exploring');
        startEmbeddingsWithFallback();
@@ -1261,6 +1299,8 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
      setViewMode,
      setProjectName,
      setGraph,
+      setGraphMode,
+      setChatOnlyNodeCount,
      initializeAgent,
      startEmbeddingsWithFallback,
      setHighlightedNodeIds,
@@ -1276,6 +1316,102 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
    ],
  );

+  // Load the full graph for the current repo after a chat-only connection.
+  // This is the escape hatch behind the chat-only empty state (#2178). It
+  // forces `skipGraph: false` so the size-based auto-detect cannot re-skip it.
+  // The override is session-scoped (deliberately NOT persisted to the URL): a
+  // persisted `?skipGraph=0` would leak onto a different repo via the other
+  // connect entry points and could silently re-trigger the hang on refresh.
+  const loadGraphInFlightRef = useRef(false);
+  // Cancels the in-flight load-anyway download; mountedRef gates post-await
+  // state writes so an unmount mid-download can't setState on a dead instance.
+  const loadGraphAbortRef = useRef<AbortController | null>(null);
+  const loadGraphMountedRef = useRef(true);
+  useEffect(() => {
+    return () => {
+      loadGraphMountedRef.current = false;
+      loadGraphAbortRef.current?.abort();
+    };
+  }, []);
+  const loadGraphAnyway = useCallback(async (): Promise<void> => {
+    if (!serverBaseUrl) return;
+    // Guard against a double-trigger (rapid double-click or a racing
+    // programmatic call) starting two concurrent full-graph downloads.
+    if (loadGraphInFlightRef.current) return;
+    loadGraphInFlightRef.current = true;
+    const repo = repoRef.current;
+    const controller = new AbortController();
+    loadGraphAbortRef.current = controller;
+
+    setProgress({
+      phase: 'extracting',
+      percent: 0,
+      message: i18n.t('common:progress.downloadingGraph'),
+      detail: i18n.t('common:progress.validating'),
+    });
+    setViewMode('loading');
+
+    try {
+      const result = await connectToServer(
+        serverBaseUrl,
+        (phase, downloaded, total) => {
+          if (phase === 'downloading') {
+            const pct = total ? Math.round((downloaded / total) * 90) + 5 : 50;
+            const mb = (downloaded / (1024 * 1024)).toFixed(1);
+            setProgress({
+              phase: 'extracting',
+              percent: pct,
+              message: i18n.t('common:progress.downloadingGraph'),
+              detail: i18n.t('common:progress.downloadedMb', { mb }),
+            });
+          }
+        },
+        controller.signal,
+        repo,
+        { awaitAnalysis: true, skipGraph: false },
+      );
+
+      // Bail if we unmounted, or if a concurrent switchRepo changed the active
+      // repo while this load was in flight (the late result must not clobber the
+      // new repo's state). Guard keyed on the ref — an abort surfaces as a
+      // BackendError, not a DOMException AbortError.
+      if (!loadGraphMountedRef.current || repoRef.current !== repo) return;
+
+      const built = buildGraphFromConnectResult(result);
+      setGraph(built.graph);
+      setGraphMode(built.graphMode);
+      // Full download succeeded → leave chat-only mode; clear the cached count.
+      setChatOnlyNodeCount(built.graphMode === 'chatOnly' ? built.nodeCount : null);
+
+      setProgress(null);
+      setViewMode('exploring');
+
+      // The graph is now loaded — re-init the agent so its system prompt drops
+      // the chat-only note (#2178, KTD2). Guarded on a configured provider, like
+      // switchRepo; runs inside the mounted/stale guard above.
+      if (getActiveProviderConfig()) {
+        await initializeAgent(repo, { chatOnly: false });
+      }
+    } catch (err) {
+      if (!loadGraphMountedRef.current || repoRef.current !== repo) return;
+      console.error('Load graph anyway failed:', err);
+      // Stay in chat-only mode (the overlay reappears) and return to the view.
+      setProgress(null);
+      setViewMode('exploring');
+    } finally {
+      if (loadGraphAbortRef.current === controller) loadGraphAbortRef.current = null;
+      loadGraphInFlightRef.current = false;
+    }
+  }, [
+    serverBaseUrl,
+    setProgress,
+    setViewMode,
+    setGraph,
+    setGraphMode,
+    setChatOnlyNodeCount,
+    initializeAgent,
+  ]);
+
  const removeCodeReference = useCallback(
    (id: string) => {
      setCodeReferences((prev) => {
@@ -1334,6 +1470,10 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
    setDepthFilter,
    graphViewMode,
    setGraphViewMode,
+    graphMode,
+    setGraphMode,
+    chatOnlyNodeCount,
+    setChatOnlyNodeCount,
    highlightedNodeIds,
    setHighlightedNodeIds,
    aiCitationHighlightedNodeIds,
@@ -1362,6 +1502,7 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
    setAvailableRepos,
    switchRepo,
    setCurrentRepo,
+    loadGraphAnyway,
    runQuery,
    isDatabaseReady,
    // Embedding state and methods
@@ -14,6 +14,8 @@ export function formatBackendError(error: unknown, t: TFunction): string {
        return t('errors:backend.rateLimited', { seconds, defaultValue: fallback });
      case 'not_found':
        return t('errors:backend.notFound', { defaultValue: fallback });
+      case 'origin_blocked':
+        return t('errors:backend.originBlocked', { defaultValue: fallback });
      case 'client':
        return t('errors:backend.client', { message: error.message, defaultValue: fallback });
      case 'server':
@@ -0,0 +1,46 @@
+import type { ConnectResult } from '../services/backend-client';
+import type { KnowledgeGraph } from '../core/graph/types';
+import { createKnowledgeGraph } from '../core/graph/graph';
+
+/**
+ * Whether the in-memory graph was downloaded ('full') or skipped for a large
+ * project ('chatOnly'). Defined here (not in the graph state slice) so the
+ * shared connect-result builder and the state slice agree on one source. In
+ * chat-only mode `graph` is an empty-but-non-null KnowledgeGraph so existing
+ * `graph?.` consumers keep working; the flag drives the chat-only UI. See #2178.
+ */
+export type GraphMode = 'full' | 'chatOnly';
+
+export interface BuiltGraph {
+  graph: KnowledgeGraph;
+  graphMode: GraphMode;
+  /**
+   * Node count for the connected repo (from `repoInfo.stats.nodes`), or null
+   * when the backend did not report it. Captured here at connect time so the
+   * chat-only notice and its size warning have an authoritative value that does
+   * not depend on the async `availableRepos` list having loaded yet.
+   */
+  nodeCount: number | null;
+}
+
+/**
+ * Build the in-memory KnowledgeGraph from a connect result and derive the
+ * graph mode + node count. In chat-only mode (`graphSkipped`) the node/relation
+ * loops are skipped, leaving an empty-but-non-null graph.
+ *
+ * Shared by every connect entry point — App.handleServerConnect, switchRepo,
+ * and loadGraphAnyway — so the build, the mode flag, and the node count stay in
+ * lockstep instead of drifting across three near-identical copies. See #2178.
+ */
+export function buildGraphFromConnectResult(result: ConnectResult): BuiltGraph {
+  const graph = createKnowledgeGraph();
+  if (!result.graphSkipped) {
+    for (const node of result.nodes) graph.addNode(node);
+    for (const rel of result.relationships) graph.addRelationship(rel);
+  }
+  return {
+    graph,
+    graphMode: result.graphSkipped ? 'chatOnly' : 'full',
+    nodeCount: result.repoInfo.stats?.nodes ?? null,
+  };
+}
@@ -0,0 +1,84 @@
+/**
+ * Pure decision logic for the WebUI's chat-only / skip-graph connection mode
+ * (issue #2178). Kept free of React and network concerns so it can be unit
+ * tested directly and reused at every connect entry point.
+ *
+ * The WebUI hangs on very large projects because the connect flow downloads the
+ * entire knowledge graph into memory. The AI chat does not need that graph (it
+ * calls the backend HTTP API directly), so we skip the download when the user
+ * asked for chat-only mode or when the project is large enough to auto-detect.
+ */
+
+export interface SkipGraphDecisionInput {
+  /**
+   * Explicit user/URL choice, if any. `true` forces chat-only, `false` forces a
+   * full graph download, `undefined` defers to auto-detection by size.
+   */
+  explicit: boolean | undefined;
+  /** Node count reported by the backend (`repoInfo.stats.nodes`), if known. */
+  nodeCount: number | null | undefined;
+  /** Node auto-detect threshold (LARGE_GRAPH_NODE_THRESHOLD). */
+  threshold: number;
+  /** Edge count reported by the backend (`repoInfo.stats.edges`), if known. */
+  edgeCount?: number | null | undefined;
+  /** Edge auto-detect threshold (LARGE_GRAPH_EDGE_THRESHOLD). */
+  edgeThreshold?: number;
+}
+
+const isOver = (count: number | null | undefined, threshold: number | undefined): boolean =>
+  typeof threshold === 'number' &&
+  typeof count === 'number' &&
+  Number.isFinite(count) &&
+  count > threshold;
+
+/**
+ * Decide whether to skip the graph download.
+ *
+ * - An explicit boolean choice always wins (override in both directions).
+ * - Otherwise auto-detect: skip when EITHER the node count OR the edge count is
+ *   known and strictly greater than its threshold. Edges matter because the
+ *   browser force-layout cliff is edge-driven and GitNexus graphs carry more
+ *   edges than nodes — an edge-heavy but node-light repo can still hang.
+ * - Missing/unknown counts fail open to a full download (we never skip purely
+ *   because we couldn't read the size).
+ */
+export function decideSkipGraph({
+  explicit,
+  nodeCount,
+  threshold,
+  edgeCount,
+  edgeThreshold,
+}: SkipGraphDecisionInput): boolean {
+  if (typeof explicit === 'boolean') return explicit;
+  return isOver(nodeCount, threshold) || isOver(edgeCount, edgeThreshold);
+}
+
+/**
+ * Whether to prompt for confirmation before loading the full graph from the
+ * chat-only escape hatch ("Load graph anyway"). Confirm whenever the node count
+ * is large OR unknown — never silently re-load a graph we cannot size, which
+ * would risk re-introducing the original browser hang (#2178). Skip the prompt
+ * only when the count is known to be at or below the threshold (a small repo
+ * that was force-skipped via `?skipGraph=1`).
+ */
+export function shouldConfirmGraphLoad(
+  nodeCount: number | null | undefined,
+  threshold: number,
+): boolean {
+  if (typeof nodeCount !== 'number' || !Number.isFinite(nodeCount)) return true;
+  return nodeCount > threshold;
+}
+
+/**
+ * Parse the `?skipGraph` URL parameter into the tri-state used by
+ * {@link decideSkipGraph}. Accepts `1`/`true` (chat-only) and `0`/`false`
+ * (full graph), case-insensitively. Anything else — including a missing
+ * parameter — yields `undefined` (auto-detect).
+ */
+export function parseSkipGraphParam(value: string | null | undefined): boolean | undefined {
+  if (value == null) return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === '1' || normalized === 'true') return true;
+  if (normalized === '0' || normalized === 'false') return false;
+  return undefined;
+}
@@ -185,6 +185,41 @@ export const Gitlab = forwardRef<SVGSVGElement, LucideProps>(function Gitlab(
  );
 });

+/**
+ * Azure DevOps mark — SVG path data from simple-icons (CC0-1.0).
+ *
+ * The Azure DevOps logo is a registered trademark of Microsoft Corporation.
+ * We use it here only to indicate Azure DevOps source-repo integration.
+ *
+ * API-compatible with `lucide-react` icons (`LucideProps`).
+ */
+export const AzureDevops = forwardRef<SVGSVGElement, LucideProps>(function AzureDevops(
+  {
+    size = 24,
+    color = 'currentColor',
+    className,
+    strokeWidth: _strokeWidth,
+    absoluteStrokeWidth: _absoluteStrokeWidth,
+    ...rest
+  },
+  ref,
+) {
+  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="M0 8.877L2.247 5.91l8.405-3.416V.022l7.37 5.393L2.966 8.338v8.225L0 15.707zm24-4.45v14.651l-5.753 4.9-9.303-3.057v3.056l-5.978-7.416 15.057 1.798V5.415z" />
+    </svg>
+  );
+});
+
 export const Github = forwardRef<SVGSVGElement, LucideProps>(function Github(
  {
    size = 24,
@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { filterRepoFiles, MAX_FILE_BYTES } from './upload-filter';
+
+type FileLike = { name: string; size: number; webkitRelativePath?: string };
+
+function f(webkitRelativePath: string, size = 10): FileLike {
+  const name = webkitRelativePath.split('/').pop() ?? webkitRelativePath;
+  return { name, size, webkitRelativePath };
+}
+
+describe('filterRepoFiles', () => {
+  it('keeps source files and builds an order-aligned manifest', () => {
+    const input = [f('repo/src/index.ts', 100), f('repo/README.md', 50)];
+    const r = filterRepoFiles(input);
+    expect(r.files).toHaveLength(2);
+    expect(r.manifest).toEqual(['repo/src/index.ts', 'repo/README.md']);
+    expect(r.totalBytes).toBe(150);
+    expect(r.droppedCount).toBe(0);
+  });
+
+  it('excludes .git / node_modules / build dirs anywhere in the path', () => {
+    const input = [
+      f('repo/.git/HEAD'),
+      f('repo/node_modules/x/index.js'),
+      f('repo/dist/bundle.js'),
+      f('repo/src/app.ts'),
+      f('repo/.gitnexus/meta.json'),
+    ];
+    const r = filterRepoFiles(input);
+    expect(r.manifest).toEqual(['repo/src/app.ts']);
+    expect(r.droppedCount).toBe(4);
+  });
+
+  it('drops files over the per-file size cap', () => {
+    const input = [f('repo/big.bin', MAX_FILE_BYTES + 1), f('repo/small.ts', 10)];
+    const r = filterRepoFiles(input);
+    expect(r.manifest).toEqual(['repo/small.ts']);
+    expect(r.droppedCount).toBe(1);
+  });
+
+  it('falls back to name when webkitRelativePath is absent', () => {
+    const r = filterRepoFiles([{ name: 'lone.ts', size: 5 }]);
+    expect(r.manifest).toEqual(['lone.ts']);
+  });
+});
@@ -0,0 +1,73 @@
+/**
+ * Client-side pre-filter for a webkitdirectory folder upload.
+ *
+ * Drops VCS metadata, dependency/build directories, and oversized files before
+ * upload — `.git` alone is often larger than the working tree — so payloads
+ * stay small and the upload matches what the analyzer actually needs. Produces
+ * an order-aligned `manifest` of webkitRelativePaths (the server keys on this,
+ * not the multipart filename, which browsers rewrite).
+ */
+
+/** Directory names excluded anywhere in a file's path. */
+export const EXCLUDED_DIRS = new Set([
+  '.git',
+  '.hg',
+  '.svn',
+  'node_modules',
+  'vendor',
+  '.venv',
+  '__pycache__',
+  'target',
+  'dist',
+  'build',
+  'out',
+  '.next',
+  '.nuxt',
+  '.cache',
+  'coverage',
+  '.idea',
+  '.gitnexus',
+]);
+
+/** Per-file size cap; matches the server's per-file limit. */
+export const MAX_FILE_BYTES = 25 * 1024 * 1024;
+
+export interface FilterResult {
+  files: File[];
+  manifest: string[];
+  droppedCount: number;
+  totalBytes: number;
+}
+
+type FileLike = Pick<File, 'name' | 'size'> & { webkitRelativePath?: string };
+
+/**
+ * Filter a webkitdirectory `FileList` (or array) into the files to upload plus
+ * their relative-path manifest.
+ */
+export function filterRepoFiles(input: ArrayLike<FileLike>): FilterResult {
+  const files: File[] = [];
+  const manifest: string[] = [];
+  let droppedCount = 0;
+  let totalBytes = 0;
+
+  for (let i = 0; i < input.length; i++) {
+    const f = input[i];
+    const rel =
+      f.webkitRelativePath && f.webkitRelativePath.length > 0 ? f.webkitRelativePath : f.name;
+    const segments = rel.split('/');
+    if (segments.some((s) => EXCLUDED_DIRS.has(s))) {
+      droppedCount++;
+      continue;
+    }
+    if (f.size > MAX_FILE_BYTES) {
+      droppedCount++;
+      continue;
+    }
+    files.push(f as File);
+    manifest.push(rel);
+    totalBytes += f.size;
+  }
+
+  return { files, manifest, droppedCount, totalBytes };
+}
@@ -29,6 +29,9 @@
    "configureAI": "Configure AI",
    "connecting": "Connecting"
  },
+  "chatOnly": {
+    "banner": "Graph not loaded (large project). Chat works normally; inline node citations won't highlight in the graph view."
+  },
  "roles": {
    "you": "You",
    "assistant": "Nexus AI"
@@ -6,6 +6,7 @@
  "analysisFailed": "Analysis failed. Check server logs.",
  "startAnalysisFailed": "Failed to start analysis",
  "invalidGithubUrl": "Please enter a valid GitHub repository URL.",
+  "invalidAzureDevOpsUrl": "Please enter a valid Azure DevOps repository URL.",
  "missingFolderPath": "Please enter a folder path.",
  "backend": {
    "reconnecting": "Server connection lost. Reconnecting…",
@@ -13,6 +14,7 @@
    "timeout": "The server took too long to respond. Try again in a moment.",
    "rateLimited": "Too many requests. Try again in {{seconds}}s.",
    "notFound": "The requested repository or resource was not found.",
+    "originBlocked": "This action isn't available from the hosted UI. Open GitNexus from the server's own address (e.g. http://localhost:4747) to continue.",
    "client": "Request failed: {{message}}",
    "server": "Server error: {{message}}"
  }
@@ -129,7 +129,16 @@
    "runLayout": "Run Layout Again",
    "layoutOptimizing": "Layout optimizing...",
    "turnOffHighlights": "Turn off all highlights",
-    "turnOnHighlights": "Turn on AI highlights"
+    "turnOnHighlights": "Turn on AI highlights",
+    "chatOnly": {
+      "title": "Graph not loaded",
+      "description": "This is a large project, so the graph was skipped to keep the browser responsive. AI chat works normally.",
+      "descriptionWithCount": "This project has {{count}} nodes, so the graph was skipped to keep the browser responsive. AI chat works normally.",
+      "citationNote": "While the graph is unloaded, inline file citations from chat won't auto-open in the Code panel.",
+      "loadAnyway": "Load graph anyway",
+      "loadAnywayWarning": "This project has {{count}} nodes. Loading the full graph may make the browser slow or unresponsive. Continue?",
+      "loadAnywayWarningUnknown": "This may be a large project. Loading the full graph may make the browser slow or unresponsive. Continue?"
+    }
  },
  "processes": {
    "unknownStep": "Unknown",
@@ -31,7 +31,7 @@
  },
  "analyzeFirst": {
    "title": "Analyze your first repository",
-    "description": "Paste a GitHub URL and GitNexus will clone it, parse the code, and build a live knowledge graph — right in your browser.",
+    "description": "Paste a repository URL and GitNexus will clone it, parse the code, and build a live knowledge graph — right in your browser.",
    "footer": "Public repos only · Cloned locally by the server · No data leaves your machine"
  },
  "landing": {
@@ -51,6 +51,7 @@
    "inputType": "Input type",
    "githubUrl": "GitHub URL",
    "gitlabUrl": "GitLab URL",
+    "azureDevOpsUrl": "Azure DevOps",
    "localFolder": "Local Folder",
    "starting": "Starting analysis...",
    "analyzeRepository": "Analyze Repository",
@@ -58,10 +59,20 @@
    "loadingGraph": "Loading graph...",
    "defaultRepoName": "repository",
    "githubRepositoryUrl": "GitHub Repository URL",
+    "githubTokenLabel": "Personal Access Token (optional)",
+    "githubTokenPlaceholder": "ghp_… or github_pat_…",
+    "githubTokenHelp": "Required for private repos. Needs the 'repo' (or fine-grained Contents:read) scope. Sent once, not stored.",
    "gitlabRepositoryUrl": "GitLab Repository URL",
    "gitlabSupported": "Supports GitLab.com and self-hosted GitLab instances.",
+    "azureDevOpsRepositoryUrl": "Azure DevOps Repository URL",
+    "azureDevOpsSupported": "Format: https://dev.azure.com/organization/project/_git/repository",
    "localFolderPath": "Local Folder Path",
-    "browseForFolder": "Browse for folder",
-    "hideBackground": "Hide (analysis continues in background)"
+    "hideBackground": "Hide (analysis continues in background)",
+    "upload": {
+      "button": "Upload a folder",
+      "uploading": "Uploading…",
+      "selected": "{{fileCount}} files ready ({{dropped}} skipped: .git, node_modules, build output)",
+      "empty": "No analyzable files found in that folder."
+    }
  }
 }
@@ -29,6 +29,9 @@
    "configureAI": "配置 AI",
    "connecting": "连接中"
  },
+  "chatOnly": {
+    "banner": "图谱未加载（大型项目）。对话功能正常；内联节点引用不会在图谱视图中高亮。"
+  },
  "roles": {
    "you": "你",
    "assistant": "Nexus AI"
@@ -6,6 +6,7 @@
  "analysisFailed": "分析失败，请检查服务器日志。",
  "startAnalysisFailed": "启动分析失败",
  "invalidGithubUrl": "请输入有效的 GitHub 仓库 URL。",
+  "invalidAzureDevOpsUrl": "请输入有效的 Azure DevOps 仓库 URL。",
  "missingFolderPath": "请输入文件夹路径。",
  "backend": {
    "reconnecting": "服务器连接已断开，正在重连…",
@@ -13,6 +14,7 @@
    "timeout": "服务器响应超时，请稍后重试。",
    "rateLimited": "请求过于频繁，请在 {{seconds}} 秒后重试。",
    "notFound": "未找到请求的仓库或资源。",
+    "originBlocked": "此操作无法从托管界面执行。请通过服务器自身地址（例如 http://localhost:4747）打开 GitNexus 后再继续。",
    "client": "请求失败：{{message}}",
    "server": "服务器错误：{{message}}"
  }
@@ -129,7 +129,16 @@
    "runLayout": "重新运行布局",
    "layoutOptimizing": "正在优化布局...",
    "turnOffHighlights": "关闭全部高亮",
-    "turnOnHighlights": "开启 AI 高亮"
+    "turnOnHighlights": "开启 AI 高亮",
+    "chatOnly": {
+      "title": "图谱未加载",
+      "description": "这是一个大型项目，已跳过图谱加载以保持浏览器响应。AI 对话功能正常可用。",
+      "descriptionWithCount": "该项目包含 {{count}} 个节点，已跳过图谱加载以保持浏览器响应。AI 对话功能正常可用。",
+      "citationNote": "图谱未加载时，对话中的内联文件引用不会自动在代码面板中打开。",
+      "loadAnyway": "仍然加载图谱",
+      "loadAnywayWarning": "该项目包含 {{count}} 个节点。加载完整图谱可能导致浏览器变慢或无响应。是否继续？",
+      "loadAnywayWarningUnknown": "这可能是一个大型项目。加载完整图谱可能导致浏览器变慢或无响应。是否继续？"
+    }
  },
  "processes": {
    "unknownStep": "未知",
@@ -31,7 +31,7 @@
  },
  "analyzeFirst": {
    "title": "分析你的第一个仓库",
-    "description": "粘贴 GitHub URL，GitNexus 会克隆仓库、解析代码，并直接在浏览器中构建实时知识图谱。",
+    "description": "粘贴仓库 URL，GitNexus 会克隆仓库、解析代码，并直接在浏览器中构建实时知识图谱。",
    "footer": "仅支持公开仓库 · 服务器本地克隆 · 数据不会离开你的机器"
  },
  "landing": {
@@ -51,6 +51,7 @@
    "inputType": "输入类型",
    "githubUrl": "GitHub URL",
    "gitlabUrl": "GitLab URL",
+    "azureDevOpsUrl": "Azure DevOps",
    "localFolder": "本地文件夹",
    "starting": "正在启动分析...",
    "analyzeRepository": "分析仓库",
@@ -58,10 +59,20 @@
    "loadingGraph": "正在加载图数据...",
    "defaultRepoName": "仓库",
    "githubRepositoryUrl": "GitHub 仓库 URL",
+    "githubTokenLabel": "个人访问令牌（可选）",
+    "githubTokenPlaceholder": "ghp_… 或 github_pat_…",
+    "githubTokenHelp": "私有仓库需要此项。需 'repo' 范围（或细粒度 Contents:read）。仅发送一次，不会保存。",
    "gitlabRepositoryUrl": "GitLab 仓库 URL",
    "gitlabSupported": "支持 GitLab.com 和自托管 GitLab 实例。",
+    "azureDevOpsRepositoryUrl": "Azure DevOps 仓库 URL",
+    "azureDevOpsSupported": "格式: http://server/Collection/Project/_git/Repository",
    "localFolderPath": "本地文件夹路径",
-    "browseForFolder": "浏览文件夹",
-    "hideBackground": "隐藏（分析继续在后台进行）"
+    "hideBackground": "隐藏（分析继续在后台进行）",
+    "upload": {
+      "button": "上传文件夹",
+      "uploading": "上传中…",
+      "selected": "已准备 {{fileCount}} 个文件（已跳过 {{dropped}} 个：.git、node_modules、构建产物）",
+      "empty": "该文件夹中未找到可分析的文件。"
+    }
  }
 }
@@ -8,6 +8,8 @@

 import type { GraphNode, GraphRelationship } from 'gitnexus-shared';
 import { CircuitOpenError, ResilientFetchExhaustedError, resilientFetch } from 'gitnexus-shared';
+import { LARGE_GRAPH_NODE_THRESHOLD, LARGE_GRAPH_EDGE_THRESHOLD } from '../config/ui-constants';
+import { decideSkipGraph } from '../lib/graph-load-decision';

 // ── Types ──────────────────────────────────────────────────────────────────

@@ -79,7 +81,11 @@ export class BackendError extends Error {
      | 'client'
      | 'not_found'
      | 'timeout'
-      | 'rate_limited',
+      | 'rate_limited'
+      // The write-route same-host Origin guard rejected this request (HTTP 403
+      // with `{ code: 'origin_not_allowed' }`). Distinct from a generic `client`
+      // 403 so the UI can show actionable "open the local UI" guidance.
+      | 'origin_blocked',
    /**
     * Milliseconds until the caller should retry. Populated for rate-limited
     * responses (HTTP 429) from the server's `Retry-After` header. `undefined`
@@ -92,6 +98,24 @@ export class BackendError extends Error {
  }
 }

+/**
+ * Thrown by the graph stream parser when the streamed node/relationship count
+ * crosses the size limit mid-download (#2178). It is the backstop for the case
+ * pre-fetch stats can't cover (absent/stale `stats.nodes`/`stats.edges` on a
+ * genuinely large repo). `connectToServer` catches it and falls into chat-only
+ * mode instead of letting the full graph hang the browser.
+ */
+export class GraphTooLargeError extends Error {
+  constructor(
+    message: string,
+    public readonly nodeCount: number,
+    public readonly relationshipCount: number,
+  ) {
+    super(message);
+    this.name = 'GraphTooLargeError';
+  }
+}
+
 // ── SSE Utility ────────────────────────────────────────────────────────────

 export interface SSEHandlers<T = unknown> {
@@ -283,12 +307,11 @@ const fetchWithTimeout = async (
 ): Promise<Response> => {
  // Merge the external caller signal (if any) with an
  // `AbortSignal.timeout()` so a timer-fired abort produces a
-  // `DOMException` with `name === 'TimeoutError'` — which
-  // `resilientFetch` correctly classifies as terminal-network (no
-  // retry, no breaker hit). A manual `AbortController.abort()` would
-  // produce `name === 'AbortError'` and route through the
-  // retryable-network branch, which mis-penalizes the breaker for
-  // user-side network slowness.
+  // `DOMException` with `name === 'TimeoutError'`. Both shapes are
+  // breaker-safe: `resilientFetch` classifies TimeoutError AND a manual
+  // `AbortController.abort()`'s AbortError as terminal-network (no
+  // retry, breaker-neutral via recordNeutral), so caller-driven
+  // cancellation never penalizes the breaker.
  const timeoutSignal = AbortSignal.timeout(timeoutMs);
  const externalSignal = init.signal;
  const signal = externalSignal ? AbortSignal.any([timeoutSignal, externalSignal]) : timeoutSignal;
@@ -362,6 +385,7 @@ const assertOk = async (response: Response): Promise<void> => {
  if (response.ok) return;

  let message = response.statusText;
+  let bodyCode: string | undefined;
  try {
    const body = await response.json();
    if (body && typeof body.error === 'string') {
@@ -369,6 +393,9 @@ const assertOk = async (response: Response): Promise<void> => {
    } else if (body && typeof body.message === 'string') {
      message = body.message;
    }
+    if (body && typeof body.code === 'string') {
+      bodyCode = body.code;
+    }
  } catch {
    // Response body was not JSON
  }
@@ -378,9 +405,13 @@ const assertOk = async (response: Response): Promise<void> => {
      ? 'not_found'
      : response.status === 429
        ? 'rate_limited'
-        : response.status >= 400 && response.status < 500
-          ? 'client'
-          : 'server';
+        : // The write-route Origin guard returns 403 with this discriminator;
+          // surface it as a distinct code so the UI can give actionable guidance.
+          bodyCode === 'origin_not_allowed'
+          ? 'origin_blocked'
+          : 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.
@@ -528,13 +559,18 @@ export const fetchRepoInfo = async (
  return { ...data, repoPath: data.repoPath ?? data.path };
 };

-/** Fetch the graph (nodes + relationships). Content stripped by default. */
+/** Fetch the graph (nodes + relationships). Content stripped by default.
+ * `maxNodes`/`maxEdges` arm a streaming circuit breaker (#2178): if the streamed
+ * count crosses either limit, the download aborts with a GraphTooLargeError
+ * instead of materializing a graph that would hang the browser. Off by default. */
 export const fetchGraph = async (
  repo?: string,
  opts?: {
    includeContent?: boolean;
    signal?: AbortSignal;
    onProgress?: (downloaded: number, total: number | null) => void;
+    maxNodes?: number;
+    maxEdges?: number;
  },
 ): Promise<{ nodes: GraphNode[]; relationships: GraphRelationship[] }> => {
  const params = [repoParam(repo), opts?.includeContent ? 'includeContent=true' : '', 'stream=true']
@@ -547,7 +583,7 @@ export const fetchGraph = async (

  const contentType = response.headers.get('Content-Type') || '';
  if (contentType.includes('application/x-ndjson')) {
-    return parseNdjsonGraphResponse(response, opts?.onProgress);
+    return parseNdjsonGraphResponse(response, opts?.onProgress, opts?.maxNodes, opts?.maxEdges);
  }

  if (!opts?.onProgress || !response.body) {
@@ -581,6 +617,8 @@ export const fetchGraph = async (
 const parseNdjsonGraphResponse = async (
  response: Response,
  onProgress?: (downloaded: number, total: number | null) => void,
+  maxNodes?: number,
+  maxEdges?: number,
 ): Promise<{ nodes: GraphNode[]; relationships: GraphRelationship[] }> => {
  if (!response.body) {
    throw new BackendError('No response body', response.status, 'server');
@@ -595,6 +633,14 @@ const parseNdjsonGraphResponse = async (
  let buffer = '';
  let downloaded = 0;

+  // Streaming circuit breaker (#2178): enforce the size limits mid-download as a
+  // backstop when pre-fetch stats were missing. Same `> threshold` comparison as
+  // decideSkipGraph. Throwing immediately after the offending push means a later
+  // error record in the same chunk is never reached — the breaker wins.
+  const overLimit = (): boolean =>
+    (typeof maxNodes === 'number' && nodes.length > maxNodes) ||
+    (typeof maxEdges === 'number' && relationships.length > maxEdges);
+
  const parseLine = (line: string) => {
    const trimmed = line.trim();
    if (!trimmed) return;
@@ -617,6 +663,20 @@ const parseNdjsonGraphResponse = async (
    }
  };

+  const tripBreaker = async () => {
+    // Free the socket promptly; never let a cancel rejection mask the breaker.
+    try {
+      await reader.cancel();
+    } catch {
+      // ignore — we're aborting anyway
+    }
+    throw new GraphTooLargeError(
+      `Graph exceeds the size limit (nodes=${nodes.length}, relationships=${relationships.length})`,
+      nodes.length,
+      relationships.length,
+    );
+  };
+
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
@@ -629,11 +689,13 @@ const parseNdjsonGraphResponse = async (
    buffer = lines.pop() || '';
    for (const line of lines) {
      parseLine(line);
+      if (overLimit()) await tripBreaker();
    }
  }

  buffer += decoder.decode();
  parseLine(buffer);
+  if (overLimit()) await tripBreaker();

  return { nodes, relationships };
 };
@@ -755,6 +817,35 @@ export const fetchClusterDetail = async (repo: string, name: string): Promise<un
  return response.json();
 };

+// ── Upload API ─────────────────────────────────────────────────────────────
+
+/**
+ * Upload a folder (selected via `<input webkitdirectory>`) and start analysis.
+ * Sends the file blobs plus a JSON `manifest` of their relative paths — the
+ * multipart filename can't carry the path (browsers strip separators), so the
+ * manifest is the source of truth. Routed through fetchWithTimeout (the shared,
+ * origin-validated request path) rather than a raw XHR; returns the analysis
+ * jobId, which the caller drives through the normal SSE flow.
+ */
+export const uploadFolder = async (
+  files: File[],
+  manifest: string[],
+  signal?: AbortSignal,
+): Promise<{ jobId: string; status: string }> => {
+  const form = new FormData();
+  // Manifest MUST precede the file parts (the server enforces this).
+  form.append('manifest', JSON.stringify(manifest));
+  for (const f of files) form.append('files', f);
+
+  const response = await fetchWithTimeout(
+    `${_backendUrl}/api/analyze/upload`,
+    { method: 'POST', body: form, signal },
+    5 * 60_000, // up to 5 min for large repos
+  );
+  await assertOk(response);
+  return response.json() as Promise<{ jobId: string; status: string }>;
+};
+
 // ── Analyze API ────────────────────────────────────────────────────────────

 /** Start a server-side analysis job. */
@@ -763,6 +854,7 @@ export const startAnalyze = async (request: {
  path?: string;
  force?: boolean;
  embeddings?: boolean;
+  token?: string;
 }): Promise<{ jobId: string; status: string }> => {
  const response = await fetchWithTimeout(
    `${_backendUrl}/api/analyze`,
@@ -864,6 +956,14 @@ export interface ConnectResult {
  nodes: GraphNode[];
  relationships: GraphRelationship[];
  repoInfo: BackendRepo;
+  /**
+   * True when the graph download was skipped (chat-only mode) — either because
+   * the caller asked for it or because the project exceeded the auto-detect
+   * node threshold. When true, `nodes`/`relationships` are empty and graph
+   * visualization is unavailable, but AI chat and all backend-API features
+   * work normally. See issue #2178.
+   */
+  graphSkipped: boolean;
 }

 /**
@@ -871,13 +971,15 @@ export interface ConnectResult {
 * Content is NOT included (use readFile/grep for file access).
 * Pass `awaitAnalysis: true` when the repo may still be cloning/analyzing —
 * this enables the backend hold-queue and a 5-minute fetch timeout.
+ * Pass `skipGraph: true`/`false` to force chat-only / full-graph mode; omit it
+ * to auto-detect from the project's node count (LARGE_GRAPH_NODE_THRESHOLD).
 */
 export async function connectToServer(
  url: string,
  onProgress?: (phase: string, downloaded: number, total: number | null) => void,
  signal?: AbortSignal,
  repoName?: string,
-  opts?: { awaitAnalysis?: boolean },
+  opts?: { awaitAnalysis?: boolean; skipGraph?: boolean },
 ): Promise<ConnectResult> {
  const baseUrl = normalizeServerUrl(url);
  setBackendUrl(baseUrl);
@@ -885,11 +987,45 @@ export async function connectToServer(
  onProgress?.('validating', 0, null);
  const repoInfo = await fetchRepoInfo(repoName, { awaitAnalysis: opts?.awaitAnalysis });

-  onProgress?.('downloading', 0, null);
-  const { nodes, relationships } = await fetchGraph(repoName, {
-    signal,
-    onProgress: (downloaded, total) => onProgress?.('downloading', downloaded, total),
+  // Decide whether to skip the (potentially huge) graph download. The AI chat
+  // talks to the backend HTTP API directly and does not need the in-memory
+  // graph, so for large projects — or when the caller explicitly asked for
+  // chat-only mode — we connect instantly without materializing the graph.
+  // repoInfo is already fetched above, so the node-count check costs no extra
+  // round-trip. See issue #2178.
+  const skipGraph = decideSkipGraph({
+    explicit: opts?.skipGraph,
+    nodeCount: repoInfo.stats?.nodes,
+    threshold: LARGE_GRAPH_NODE_THRESHOLD,
+    edgeCount: repoInfo.stats?.edges,
+    edgeThreshold: LARGE_GRAPH_EDGE_THRESHOLD,
  });

-  return { nodes, relationships, repoInfo };
+  if (skipGraph) {
+    return { nodes: [], relationships: [], repoInfo, graphSkipped: true };
+  }
+
+  // Arm the streaming circuit breaker for auto-detect downloads as a backstop
+  // for the no-stats fail-open case (#2178). An explicit "load anyway"
+  // (skipGraph === false) opts out — the user has accepted the cost.
+  const enforceLimits = opts?.skipGraph !== false;
+
+  onProgress?.('downloading', 0, null);
+  try {
+    const { nodes, relationships } = await fetchGraph(repoName, {
+      signal,
+      onProgress: (downloaded, total) => onProgress?.('downloading', downloaded, total),
+      maxNodes: enforceLimits ? LARGE_GRAPH_NODE_THRESHOLD : undefined,
+      maxEdges: enforceLimits ? LARGE_GRAPH_EDGE_THRESHOLD : undefined,
+    });
+    return { nodes, relationships, repoInfo, graphSkipped: false };
+  } catch (err) {
+    // The breaker tripped mid-stream → fall into chat-only, the same result the
+    // pre-fetch skip path produces. Re-throw every other error (genuine
+    // BackendErrors must still surface to the caller's catch).
+    if (err instanceof GraphTooLargeError) {
+      return { nodes: [], relationships: [], repoInfo, graphSkipped: true };
+    }
+    throw err;
+  }
 }
@@ -3,5 +3,19 @@
 interface Window {
  __GITNEXUS_CONFIG__?: {
    backendUrl?: string;
+    /**
+     * Node-count above which the WebUI connects in chat-only mode by default
+     * (skips the full graph download to avoid hanging the browser on very
+     * large projects). Override at deploy time; falls back to
+     * LARGE_GRAPH_NODE_THRESHOLD in config/ui-constants.ts. See issue #2178.
+     */
+    largeGraphNodeThreshold?: number;
+    /**
+     * Edge-count above which the WebUI connects in chat-only mode by default.
+     * The browser force-layout cliff is edge-driven, so this guards edge-heavy
+     * repos that fall under the node threshold. Falls back to
+     * LARGE_GRAPH_EDGE_THRESHOLD in config/ui-constants.ts. See issue #2178.
+     */
+    largeGraphEdgeThreshold?: number;
  };
 }
@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { BASE_SYSTEM_PROMPT } from '../../src/core/llm/agent';
+import { buildDynamicSystemPrompt, type CodebaseContext } from '../../src/core/llm/context-builder';
 import {
  createGraphRAGTools,
  GRAPH_RAG_TOOL_NAMES,
@@ -7,6 +8,19 @@ import {
 } from '../../src/core/llm/tools';
 import { NODE_REF_REGEX } from '../../src/lib/grounding-patterns';

+const MINIMAL_CONTEXT: CodebaseContext = {
+  stats: {
+    projectName: 'proj',
+    fileCount: 0,
+    functionCount: 0,
+    classCount: 0,
+    interfaceCount: 0,
+    methodCount: 0,
+  },
+  hotspots: [],
+  folderTree: '',
+};
+
 /** Legacy or phantom tool names that must not appear in the system prompt. */
 const FORBIDDEN_TOOL_NAMES = [
  'hybrid_search',
@@ -80,3 +94,19 @@ describe('BASE_SYSTEM_PROMPT tool parity', () => {
    expect(BASE_SYSTEM_PROMPT).not.toMatch(/\b(?:use|call|invoke)\s+`?highlight_in_graph/i);
  });
 });
+
+describe('buildDynamicSystemPrompt chat-only mode (#2178)', () => {
+  it('appends a chat-only note that overrides VISUAL GROUNDING when chatOnly', () => {
+    const prompt = buildDynamicSystemPrompt(BASE_SYSTEM_PROMPT, MINIMAL_CONTEXT, true);
+    expect(prompt).toContain('CHAT-ONLY MODE');
+    expect(prompt).toMatch(/node citations will NOT highlight/i);
+    expect(prompt).toContain('[[path:START-END]]');
+  });
+
+  it('leaves the prompt unchanged when chatOnly is false/omitted', () => {
+    const full = buildDynamicSystemPrompt(BASE_SYSTEM_PROMPT, MINIMAL_CONTEXT);
+    const explicitFalse = buildDynamicSystemPrompt(BASE_SYSTEM_PROMPT, MINIMAL_CONTEXT, false);
+    expect(full).toBe(explicitFalse);
+    expect(full).not.toContain('CHAT-ONLY MODE');
+  });
+});
@@ -13,7 +13,12 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { getBreaker } from 'gitnexus-shared';
 import { __resetBreakerRegistry__ } from 'gitnexus-shared/test-helpers';
-import { fetchRepos, setBackendUrl, startAnalyze } from '../../src/services/backend-client';
+import {
+  deleteRepo,
+  fetchRepos,
+  setBackendUrl,
+  startAnalyze,
+} from '../../src/services/backend-client';

 const BASE = 'http://localhost:4747';

@@ -89,6 +94,40 @@ describe('backend-client retry budget (method-aware)', () => {
    expect(getBreaker(bKey).getConsecutiveFailures()).toBe(0);
  });

+  it('maps an origin-blocked 403 to BackendError code "origin_blocked"', async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(
+          JSON.stringify({
+            error: 'This endpoint is restricted to same-host origins',
+            code: 'origin_not_allowed',
+          }),
+          { status: 403, headers: { 'Content-Type': 'application/json' } },
+        ),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(deleteRepo('my-repo')).rejects.toMatchObject({
+      status: 403,
+      code: 'origin_blocked',
+    });
+    // 403 is a terminal client error — never retried.
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('maps a generic 403 (no recognized code) to BackendError code "client" (back-compat)', async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(JSON.stringify({ error: 'forbidden' }), {
+          status: 403,
+          headers: { 'Content-Type': 'application/json' },
+        }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(deleteRepo('my-repo')).rejects.toMatchObject({ status: 403, code: 'client' });
+  });
+
  it('breaker not incremented when timeout fires (TimeoutError, not AbortError)', async () => {
    // Reject directly with a TimeoutError DOMException, mimicking what
    // `fetch` produces when its `AbortSignal.timeout()`-wired signal
--- a/Show More
+++ b/Show More