@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/dist/clients/tree-sitter-client.js

@@ -19,16 +19,17 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
+import { getDegradationLedgerGeneration, incrementDegradationCount, recordDegradation, recordDegradationOnce, } from "./degradation-ledger.js";
 import { loadWebTreeSitter } from "./deps/web-tree-sitter.js";
+import { transientRetryDelayMs } from "./dispatch/runners/utils/availability-policy.js";
 import { getProjectIgnoreMatcher, isExcludedDirName } from "./file-utils.js";
-import { downloadGrammar, grammarBlockReason, LANGUAGE_TO_GRAMMAR, } from "./grammar-source.js";
+import { downloadGrammarDetailed, fileHasWasmMagic, grammarBlockReason, grammarFileSha256, isVendoredGrammar, LANGUAGE_TO_GRAMMAR, pinnedGrammarHash, vendoredGrammarRefusal, vendoredGrammarsDir, } from "./grammar-source.js";
 import { resolvePackagePath } from "./package-root.js";
-import { recordDegradation } from "./degradation-ledger.js";
 import { assertInstallAllowed, getProjectTrustGeneration, } from "./project-trust.js";
 import { logTreeSitterDiagnostic } from "./tree-sitter-logger.js";
 import { notifyUserDegradation } from "./user-notify.js";
 const _require = createRequire(import.meta.url);
-import { createTreeCacheCounters, TreeCache, } from "./tree-sitter-cache.js";
+import { createTreeCacheCounters, deriveScanTreeCacheCapacity, TreeCache, } from "./tree-sitter-cache.js";
 import { TreeSitterNavigator } from "./tree-sitter-navigator.js";
 import { TreeSitterQueryLoader, } from "./tree-sitter-query-loader.js";
 // Hard cap on a single structural-search file walk. Bounds a misrooted scan so
@@ -53,21 +54,215 @@ function createParserCounters() {
         parserFailures: 0,
     };
 }
+/**
+ * `size:mtimeMs` identity for a grammar candidate, or undefined when the path
+ * is absent or not a regular file. Doubles as the existence check on the
+ * resolve path and as the invalidation key for the verified-preamble memo
+ * (#1548) — `size` + `mtimeMs` is the codebase's standard cheap stamp.
+ */
+function grammarFileStamp(filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        return stat.isFile() ? `${stat.size}:${stat.mtimeMs}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function isTreeSitterWasmAbortError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.includes("Aborted") || message.includes("abort()");
 }
+/**
+ * Positively-identified RESOLUTION-failure codes for a dynamic `import()`:
+ * the specifier couldn't be found/resolved, or a transient fs error hit
+ * before `import()` got as far as evaluating the target module. All of
+ * these recover once whatever was missing/busy appears — they say nothing
+ * durable about the module itself (mirrors the errno allowlist in
+ * clients/dispatch/runners/ast-grep-napi.ts's `classifyAstGrepLoadFailure`,
+ * kept local here rather than shared because that file is owned by an
+ * in-flight PR, #1701, at the time of writing).
+ */
+const RESOLUTION_ERROR_CODES = new Set([
+    "ERR_MODULE_NOT_FOUND",
+    "MODULE_NOT_FOUND",
+    "ERR_INVALID_MODULE_SPECIFIER",
+    "ERR_UNSUPPORTED_DIR_IMPORT",
+    "ENOENT",
+    "EMFILE",
+    "EBUSY",
+    "EAGAIN",
+    "EPERM",
+    "ETXTBSY",
+]);
+/** Walk an error's `.cause` chain, collecting every `code` seen along the
+ * way — a resolution failure's `code` can be wrapped in a cause rather than
+ * sitting on the top-level thrown Error. */
+function collectErrorCodes(err) {
+    const codes = [];
+    let current = err;
+    const seen = new Set();
+    while (current instanceof Error && !seen.has(current)) {
+        seen.add(current);
+        const code = current.code;
+        if (typeof code === "string")
+            codes.push(code);
+        current = current.cause;
+    }
+    return codes;
+}
+/**
+ * Classify a `loadWebTreeSitter()` rejection (#1592). RESOLUTION failures
+ * (a positively-identified code above) are recoverable: the module gets a
+ * fresh `import()` attempt on the very next `init()` call, same as before
+ * this fix, because whatever blocked resolution can plausibly clear on its
+ * own. Everything else is treated as EVALUATION-shaped and latches — an
+ * unrecognized error is far more likely to be the target module's own
+ * top-level code throwing (which Node's ESM loader then memoizes as a
+ * permanently-rejected module record for that URL) than an unclassified
+ * resolution hiccup, so "unknown" defaults to the case a retry cannot fix.
+ */
+function classifyWebTreeSitterLoadFailure(err) {
+    const codes = collectErrorCodes(err);
+    return codes.some((code) => RESOLUTION_ERROR_CODES.has(code))
+        ? "resolution"
+        : "evaluation";
+}
 // --- Parser Manager ---
 export class TreeSitterClient {
     initialized = false;
     initPromise = null;
+    /**
+     * Set when `loadWebTreeSitter()` itself rejects with an EVALUATION-shaped
+     * error (#1592, review round 2 F1/F2) — `classifyWebTreeSitterLoadFailure`
+     * above draws that line. That call is a dynamic `import()` of a fixed
+     * resolved URL, and Node's ESM loader permanently memoizes a module
+     * record that threw during evaluation — a later `import()` of the SAME
+     * URL from a later `init()` call would just replay the cached rejection,
+     * not re-attempt the load. Without this latch, every `withTreeSitterRoot()`
+     * call (one per file parse) would re-invoke `init()`, see `initPromise`
+     * cleared by the previous attempt's `finally`, and dynamically re-import —
+     * a dead retry on the hot path. A RESOLUTION-shaped rejection does NOT
+     * set this: it leaves `initPromise` cleared as before, so the next
+     * `init()` call retries for real, because that class of failure can
+     * plausibly clear before the next call arrives.
+     *
+     * SESSION-scoped, not process-lifetime (round 2 F2, the #1567/#1575
+     * `sgSessionHold` precedent): re-armed by `resetLoadStateForSession()`,
+     * wired into `resetDispatchBaselines()` via `tree-sitter-shared.ts`'s
+     * `resetTreeSitterClientLoadState()`. Re-arming does not guarantee the
+     * next attempt succeeds — if the process itself didn't restart between
+     * sessions, Node's module cache is unchanged and the replay will just
+     * fail fast again — but it gives a fresh degradation record for the new
+     * session (the ledger's own `onceKeys` are cleared at session_start too)
+     * instead of silently reusing a stale verdict forever, and it does let a
+     * genuinely fixed install (process WAS restarted) recover.
+     *
+     * Distinct from `wasmAborted`, which stays process-lifetime and is
+     * deliberately NOT included in the session reset: that flag means the
+     * Emscripten WASM heap itself aborted mid-use — a runtime that DID load
+     * and then corrupted its own memory. Reusing that heap after a "session"
+     * boundary that isn't an actual process restart is not a retry, it's
+     * operating on data already documented (tree-sitter-shared.ts) as
+     * requiring a real restart to recover. `webTreeSitterLoadFailed` only
+     * ever covers a runtime that never loaded in the first place, so nothing
+     * corrupted survives a re-arm.
+     */
+    webTreeSitterLoadFailed = false;
     languages = new Map();
     parsers = new Map();
     treeCache;
     navigator = new TreeSitterNavigator();
     grammarsDir;
-    /** In-flight/settled lazy grammar fetches, keyed by wasm filename. */
+    /** In-flight lazy grammar fetches, keyed by wasm filename. Evicted on
+     * settle (#1536) — a rejected/false attempt must not be remembered as the
+     * permanent answer for the session; only concurrent demands during the
+     * SAME probe share it. */
     grammarEnsurePromises = new Map();
+    /** Epoch ms before which a failed grammar download is not retried
+     * (#1536). A transient download failure — offline, DNS hiccup, CDN blip —
+     * says nothing durable about the grammar, so it gets a bounded cooldown
+     * (the `transientRetryDelayMs` shape from availability-policy.ts) instead
+     * of latching for the process lifetime. */
+    grammarRetryAtMs = new Map();
+    /**
+     * Grammar path → the `size:mtimeMs` stamp at which its wasm preamble was
+     * verified (#1548). A POSITIVE-only memo, so the steady-state resolve costs
+     * one `stat` (which the old `existsSync` already paid) and re-reads the
+     * header only when the stamp moves. Stamped rather than a bare `Set`
+     * because a memo that never expires is defect-shape 6: the file it vouches
+     * for can be replaced under it. Failures are deliberately NOT memoized — a
+     * poisoned path must be re-examined on the next resolve so a successful
+     * re-download over it is picked up immediately.
+     */
+    verifiedGrammarPaths = new Map();
+    /**
+     * Grammar path → the `size:mtimeMs` stamp at which `Language.load` failed
+     * on it despite passing the wasm-preamble check (#1564) — e.g. a truncated
+     * download whose first four bytes are a genuine `\0asm` preamble but whose
+     * body decodes short ("Code section extends past end of the module"). The
+     * preamble check alone can't see this; only a real decode attempt can.
+     * `resolveGrammarFile` treats a path recorded here (at the SAME stamp) as
+     * absent, so the next demand re-fetches instead of reusing the same broken
+     * file forever. Stamped so a fresh download (new mtime) is re-examined
+     * rather than permanently distrusted — same shape as `verifiedGrammarPaths`.
+     */
+    decodeFailedGrammarPaths = new Map();
+    /**
+     * Grammar path → the `size:mtimeMs` stamp at which its bytes were verified
+     * to match the CURRENTLY PINNED sha256 manifest (#1760). Positive-only,
+     * same discipline as `verifiedGrammarPaths`: the hash is computed once per
+     * stamp (not per parse), and a stamp change — a fresh download — forces a
+     * re-check rather than trusting a memo made for different bytes.
+     */
+    verifiedGrammarVersionAt = new Map();
+    /**
+     * Grammar path → the `size:mtimeMs` stamp at which it was found to no
+     * longer match the pinned manifest hash — a version bump
+     * (`TREE_SITTER_WASMS_VERSION`, or a `SOURCE_OVERRIDES` entry), or on-disk
+     * corruption (#1760). `resolveGrammarFile` treats a path recorded here (at
+     * the SAME stamp) as absent, exactly like `decodeFailedGrammarPaths`, so
+     * the next demand re-fetches instead of serving the stale/corrupt file for
+     * the rest of the process's life. A fresh download (new stamp) is
+     * re-examined rather than permanently distrusted.
+     */
+    staleGrammarVersionAt = new Map();
+    /**
+     * Paths already reported as version-stale THIS SESSION, to log/record them
+     * once each (#1801 review F1). Deliberately separate from
+     * `staleGrammarVersionAt`: that map is a pure hash-verdict memo whose whole
+     * point is to persist for the process's life (re-hashing an unchanged file
+     * is exactly what it exists to avoid), so it must never double as a report
+     * gate — a gate riding on process-lifetime state can't re-arm at a session
+     * boundary. Cleared in `refreshGrammarSessionLatches`, mirroring
+     * `poisonedGrammarPaths`.
+     */
+    staleReportedGrammarPaths = new Set();
+    /** Paths already reported as non-wasm, to log/record them once each. */
+    poisonedGrammarPaths = new Set();
+    /** Consecutive download failures per grammar, for the exponential
+     * cooldown; reset on success. */
+    grammarFailureAttempts = new Map();
+    /**
+     * Retry delay (ms) last SHOWN to the user for this grammar, or `-1` for a
+     * durable (non-retryable) failure already announced. The cooldown lets
+     * the ensure loop retry silently in the background — only the delay's
+     * FIRST appearance, and any later escalation the user was never told
+     * about, needs to interrupt them (#1536 review F6): a fresh 30s cooldown
+     * re-notifies the same as an escalated 300s one once it's a genuinely new
+     * number, but two consecutive 30s cooldowns (identical, nothing new to
+     * say) do not. Absence means "not yet notified this streak."
+     *
+     * Session-scoped (#1536 review F5): cleared whenever the degradation
+     * ledger's own generation moves past `grammarNotificationsLedgerGen`,
+     * mirroring `trustBlockedGrammarNotifications` below — a lazy
+     * compare-at-use-time against a monotonic counter, not a listener. Tied to
+     * the LEDGER's generation (bumped by `resetDegradationLedger`, which
+     * `handleSessionStart` calls first thing) rather than trust, since this
+     * is a session boundary, not a trust transition.
+     */
+    grammarLastNotifiedDelayMs = new Map();
+    grammarNotificationsLedgerGen = getDegradationLedgerGeneration();
     trustBlockedGrammarNotifications = new Set();
     trustNotificationsGeneration = getProjectTrustGeneration();
     // biome-ignore lint/suspicious/noExplicitAny: Optional dependency loaded dynamically
@@ -180,6 +375,19 @@ export class TreeSitterClient {
             ...this.parserCounters,
         };
     }
+    /**
+     * Grow the tree cache to span a full-project scan's working set (#1715).
+     * The interactive default (50 entries) can't hold a mid/large project's
+     * file count, so a second scan re-parses everything the first scan's LRU
+     * evicted — live dogfood evidence showed every miss on a second 110-file
+     * scan was a `capacityMisses` one. Bounded by
+     * `TREE_CACHE_SCAN_CAPACITY_CEILING` (see `deriveScanTreeCacheCapacity`'s
+     * heap-cost note) and monotonic — a smaller scan never shrinks a capacity
+     * an earlier, larger one already grew.
+     */
+    ensureTreeCacheCapacity(fileCount) {
+        this.treeCache.setMaxSize(deriveScanTreeCacheCapacity(fileCount, this.treeCache.getMaxSize()));
+    }
     async withParseCacheMeasurement(work, onComplete) {
         const measurement = {
             ...createTreeCacheCounters(),
@@ -283,10 +491,33 @@ export class TreeSitterClient {
             return undefined;
         }
     }
+    _vendoredGrammarsDir;
+    /**
+     * The committed `vendor/grammars` dir, if it exists. Cached only on a hit,
+     * mirroring `bundledGrammarsDir`.
+     */
+    vendoredGrammarsDir() {
+        if (this._vendoredGrammarsDir)
+            return this._vendoredGrammarsDir;
+        try {
+            const dir = vendoredGrammarsDir();
+            if (fs.existsSync(dir))
+                this._vendoredGrammarsDir = dir;
+            return this._vendoredGrammarsDir;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * All directories that may hold grammar wasms, in precedence order: the
-     * bundled core dir, the resolved `this.grammarsDir`, and the web-tree-sitter
-     * grammars dir (the lazy-fetch write target). Deduped.
+     * committed vendor dir, the bundled core dir, the resolved
+     * `this.grammarsDir`, and the web-tree-sitter grammars dir (the lazy-fetch
+     * write target). Deduped.
+     *
+     * `vendor/grammars` comes first because it is the ONLY source for a grammar
+     * we build ourselves (`VENDORED_GRAMMARS`) — nothing downloads into the
+     * later dirs for it, so a miss here is a miss everywhere.
      */
     grammarSourceDirs() {
         const dirs = [];
@@ -294,20 +525,184 @@ export class TreeSitterClient {
             if (d && !dirs.includes(d))
                 dirs.push(d);
         };
+        push(this.vendoredGrammarsDir());
         push(this.bundledGrammarsDir());
         push(this.grammarsDir || undefined);
         push(this.resolveWebTreeSitterAsset("grammars"));
         return dirs;
     }
-    /** Absolute path to `grammarFile` across all source dirs, else undefined. */
+    /**
+     * Absolute path to `grammarFile` across all source dirs, else undefined.
+     *
+     * Existence is not enough (#1548): a file whose first four bytes aren't the
+     * wasm preamble is not a grammar, and returning it would report the language
+     * as available while every `Language.load` fails — the permanent-poisoning
+     * shape this issue is about. #1548 stops NEW poisoned files from being
+     * written, but a file poisoned before that shipped is already on disk, so
+     * the resolve path has to reject it too: a rejected candidate is treated as
+     * absent, which lets `ensureGrammar` re-download over it.
+     */
     resolveGrammarFile(grammarFile) {
         for (const dir of this.grammarSourceDirs()) {
             const candidate = path.join(dir, grammarFile);
-            if (fs.existsSync(candidate))
-                return candidate;
+            const stamp = grammarFileStamp(candidate);
+            if (!stamp)
+                continue;
+            // #1564: a file that passed the preamble check but failed
+            // `Language.load` at this exact stamp is known-bad — treat it as
+            // absent so `ensureGrammar` re-fetches over it, same as the
+            // non-wasm-magic case below. A stamp mismatch (the file changed —
+            // re-downloaded) falls through to re-examine it fresh.
+            if (this.decodeFailedGrammarPaths.get(candidate) === stamp)
+                continue;
+            if (this.verifiedGrammarPaths.get(candidate) === stamp) {
+                if (this.isGrammarVersionCurrent(candidate, grammarFile, stamp)) {
+                    return candidate;
+                }
+                continue;
+            }
+            if (fileHasWasmMagic(candidate)) {
+                this.verifiedGrammarPaths.set(candidate, stamp);
+                if (this.isGrammarVersionCurrent(candidate, grammarFile, stamp)) {
+                    return candidate;
+                }
+                continue;
+            }
+            this.verifiedGrammarPaths.delete(candidate);
+            this.reportPoisonedGrammarFile(candidate, grammarFile);
         }
         return undefined;
     }
+    /**
+     * Clear the once-per-session grammar report gates when the degradation
+     * ledger's own generation has moved (#1536 review F5). Lazy
+     * compare-at-use-time against a monotonic counter, bumped by
+     * `resetDegradationLedger`, which `handleSessionStart` calls first thing —
+     * no listener, no retention. Every gate keyed to a SESSION rather than to
+     * the process lives here, so a new one cannot forget to re-arm: a gate that
+     * outlives the ledger it guards silently swallows the record it was only
+     * ever meant to de-duplicate (#1560 review F1).
+     */
+    refreshGrammarSessionLatches() {
+        const ledgerGen = getDegradationLedgerGeneration();
+        if (ledgerGen === this.grammarNotificationsLedgerGen)
+            return;
+        this.grammarNotificationsLedgerGen = ledgerGen;
+        this.grammarLastNotifiedDelayMs.clear();
+        this.poisonedGrammarPaths.clear();
+        this.staleReportedGrammarPaths.clear();
+    }
+    /**
+     * Log + record a grammar file on disk that isn't a wasm module, once per
+     * path per session. No user notification here: the caller goes on to attempt
+     * a re-download, and `recordGrammarFailure` is what interrupts the user if
+     * that also fails. A silent recovery should stay silent.
+     */
+    reportPoisonedGrammarFile(candidate, grammarFile) {
+        // Per SESSION, not per process (#1560 review F1). The file is still
+        // poisoned after a session boundary and still degrades the language, so
+        // the new session's ledger has to carry the entry — a client-lifetime
+        // gate would leave `resetDegradationLedger` with a permanently empty
+        // grammar-blocked group and no record of why the language is degraded.
+        this.refreshGrammarSessionLatches();
+        if (this.poisonedGrammarPaths.has(candidate))
+            return;
+        this.poisonedGrammarPaths.add(candidate);
+        logTreeSitterDiagnostic({
+            subsystem: "tree-sitter-client",
+            level: "warn",
+            message: `ignoring ${candidate}: the file is not a wasm module (missing the \\0asm preamble) — ` +
+                `most likely a captive-portal or proxy page written by an earlier download (#1548). ` +
+                `pi-lens will treat the grammar as missing and try to fetch it again.`,
+            metadata: { grammarFile, path: candidate, outcome: "not-wasm" },
+        });
+        incrementDegradationCount({
+            kind: "grammar-blocked",
+            subject: grammarFile,
+            reason: "on-disk grammar file is not a wasm module — ignored, re-fetching",
+        });
+    }
+    /**
+     * Is the cached grammar at `candidate` (whose wasm preamble already passed)
+     * still current against the pinned sha256 manifest (#1760)?
+     *
+     * A grammar downloaded once is never revisited when this repo bumps
+     * `TREE_SITTER_WASMS_VERSION` or changes a `SOURCE_OVERRIDES` entry — the
+     * cached file's name carries no version, so a stale build serves forever.
+     * The check is cheap and NEVER touches the network: it compares the
+     * on-disk sha256 (hashed once per `size:mtimeMs` stamp, memoized exactly
+     * like `verifiedGrammarPaths` above so a hot parse loop never re-hashes an
+     * unchanged file) against `pinnedGrammarHash`, which itself is a pure
+     * in-memory manifest lookup. A mismatch also catches on-disk corruption,
+     * which nothing detected before this.
+     *
+     * Vendored grammars (`VENDORED_GRAMMARS`) are skipped: they have no CDN
+     * pin to drift against, and their bytes are already guarded by the
+     * separate build-provenance check (`scripts/check-grammar-provenance.mjs`).
+     * No pinned hash for this filename (manifest missing, or a grammar added
+     * before `--write-manifest` was re-run) is treated as "can't verify" and
+     * trusted, the same fallback `downloadGrammarDetailed`'s own hash check
+     * already uses — never as a forced, unbounded refetch loop.
+     */
+    isGrammarVersionCurrent(candidate, grammarFile, stamp) {
+        if (isVendoredGrammar(grammarFile))
+            return true;
+        if (this.staleGrammarVersionAt.get(candidate) === stamp) {
+            // #1801 review F1: the hash-verdict memo above is process-lifetime by
+            // design (re-hashing an unchanged file on every resolve is the exact
+            // cost this whole check exists to avoid), so an early return here must
+            // NOT skip the report — a still-stale grammar has to keep showing up
+            // in every NEW session's ledger, not just the session that first
+            // discovered the mismatch.
+            this.reportStaleGrammarVersion(candidate, grammarFile);
+            return false;
+        }
+        if (this.verifiedGrammarVersionAt.get(candidate) === stamp)
+            return true;
+        const pinnedHash = pinnedGrammarHash(grammarFile);
+        if (!pinnedHash) {
+            this.verifiedGrammarVersionAt.set(candidate, stamp);
+            return true;
+        }
+        const actualHash = grammarFileSha256(candidate);
+        if (actualHash === pinnedHash) {
+            this.verifiedGrammarVersionAt.set(candidate, stamp);
+            return true;
+        }
+        this.verifiedGrammarVersionAt.delete(candidate);
+        this.staleGrammarVersionAt.set(candidate, stamp);
+        this.reportStaleGrammarVersion(candidate, grammarFile);
+        return false;
+    }
+    /**
+     * Log + record a version-stale (or corrupt) cached grammar, once per path
+     * per SESSION (#1801 review F1). Called from BOTH the memoized-stale path
+     * and the fresh-mismatch path in `isGrammarVersionCurrent`, so the report
+     * gate is independent of `staleGrammarVersionAt`'s own process-lifetime
+     * memo — a grammar that is STILL stale in a later session must still emit
+     * a fresh record into that session's ledger, exactly like
+     * `reportPoisonedGrammarFile` already does for the non-wasm case.
+     */
+    reportStaleGrammarVersion(candidate, grammarFile) {
+        this.refreshGrammarSessionLatches();
+        if (this.staleReportedGrammarPaths.has(candidate))
+            return;
+        this.staleReportedGrammarPaths.add(candidate);
+        logTreeSitterDiagnostic({
+            subsystem: "tree-sitter-client",
+            level: "warn",
+            message: `ignoring ${candidate}: its sha256 no longer matches the pinned grammar ` +
+                `manifest — the pinned tree-sitter-wasms version (or a SOURCE_OVERRIDES entry) ` +
+                `moved since this file was downloaded. pi-lens will treat the grammar as ` +
+                `missing and re-fetch the current build (#1760).`,
+            metadata: { grammarFile, path: candidate, outcome: "stale-version" },
+        });
+        incrementDegradationCount({
+            kind: "grammar-blocked",
+            subject: grammarFile,
+            reason: "cached grammar no longer matches the pinned manifest hash — ignored, re-fetching",
+        });
+    }
     /** Find tree-sitter grammar directory */
     findGrammarsDir() {
         const grammarsDir = this.resolveWebTreeSitterAsset("grammars");
@@ -392,65 +787,284 @@ export class TreeSitterClient {
         const inflight = this.grammarEnsurePromises.get(grammarFile);
         if (inflight)
             return inflight;
+        // A failed download only stays refused for its cooldown window (#1536):
+        // past that, fall through and retry rather than remembering an offline
+        // moment for the life of the process. No download is attempted while the
+        // cooldown is live, so a hard-down CDN is not re-hit on every parse. A
+        // DURABLE failure (grammarBlockDurable below) sets this to +Infinity,
+        // which reads the same as "still cooling down" here — it just never
+        // expires, matching the issue's "a genuinely unavailable grammar may
+        // still latch" allowance.
+        const retryAt = this.grammarRetryAtMs.get(grammarFile);
+        if (retryAt !== undefined && Date.now() < retryAt) {
+            return false;
+        }
         const task = (async () => {
-            const dir = this.grammarsDir && fs.existsSync(this.grammarsDir)
-                ? this.grammarsDir
-                : this.grammarsWriteDir();
-            if (!dir)
-                return false;
-            // Reuse the shared single-file downloader (same CDN/source as the
-            // postinstall) — see clients/grammar-source.ts.
-            const ok = await downloadGrammar(dir, grammarFile);
-            if (ok) {
-                if (!this.grammarsDir)
-                    this.grammarsDir = dir;
-                logTreeSitterDiagnostic({
-                    subsystem: "tree-sitter-client",
-                    level: "warn",
-                    message: `fetched missing tree-sitter grammar ${grammarFile} at runtime (install scripts were skipped by the package manager)`,
-                    metadata: { grammarFile, outcome: "fetched" },
-                });
+            try {
+                return await this.fetchGrammar(grammarFile);
             }
-            else {
-                // Surface the degradation once per grammar (the promise cache dedupes)
-                // instead of failing silently — otherwise pnpm/bun users offline get
-                // no signal that a language's tree-sitter features are unavailable.
-                const unavailable = `tree-sitter grammar '${grammarFile}' is unavailable — ` +
-                    `symbol search, module reports and structural rules for this language will be degraded. ` +
-                    `The package manager skipped install scripts and the runtime download failed (offline or CDN unreachable). ` +
-                    `Fix: reinstall with a manager that runs postinstall, allow its build scripts ` +
-                    `(pnpm approve-builds / bun trustedDependencies), or restore network access.`;
-                logTreeSitterDiagnostic({
-                    subsystem: "tree-sitter-client",
-                    message: unavailable,
-                    metadata: { grammarFile, outcome: "unavailable" },
-                });
-                recordDegradation({
-                    kind: "grammar-blocked",
-                    subject: grammarFile,
-                    reason: "runtime grammar download failed",
-                });
-                // HUMAN-audience: an offline grammar fetch silently degrades this
-                // language's features, so it reaches the user through the HOST's
-                // render path (#1333) rather than a raw terminal write.
-                notifyUserDegradation(`pi-lens: ${unavailable}`);
+            catch (err) {
+                // Defensive (#1548): nothing in `fetchGrammar` throws today —
+                // `downloadGrammarDetailed` catches internally. But a thrown error
+                // here used to skip the whole `else` arm, so NO cooldown was armed
+                // and the rejection escaped through `task.finally` — the exact
+                // pre-#1536 shape (no cooldown, possible unhandled rejection). Funnel
+                // it into the same retryable failure path instead, so a future
+                // refactor that lets an exception out cannot regress to it.
+                const message = err instanceof Error ? err.message : String(err);
+                this.recordGrammarFailure(grammarFile, `The runtime grammar fetch threw an unexpected error (${message}).`, 
+                /* retryable */ true);
+                return false;
             }
-            return ok;
         })();
         this.grammarEnsurePromises.set(grammarFile, task);
+        // Evict on settle regardless of outcome (#1536): a resolved TRUE is
+        // superseded by resolveGrammarFile() finding the file on disk on the
+        // next call, and a resolved FALSE must not be remembered as the
+        // permanent verdict — only concurrent callers during the SAME in-flight
+        // attempt should ever observe this promise.
+        //
+        // The trailing `.catch` is UNFALSIFIABLE scaffolding, not verified
+        // defence (#1560 review F3): `finally` returns a DERIVED promise that
+        // rejects whenever `task` does, but the task's own try/catch above means
+        // it cannot reject, so no test can make this handler fire and removing it
+        // changes nothing today. It is here for the day the try/catch above stops
+        // being exhaustive — or the eviction callback itself throws — because at
+        // that point the fork becomes an unhandled rejection nobody is awaiting.
+        void task
+            .finally(() => {
+            if (this.grammarEnsurePromises.get(grammarFile) === task) {
+                this.grammarEnsurePromises.delete(grammarFile);
+            }
+        })
+            .catch(() => {
+            /* see above: the task's own catch is the real handler */
+        });
         return task;
     }
+    /**
+     * One grammar-fetch attempt: locate a writable dir, download, and record the
+     * outcome. Split out of `ensureGrammar` so the whole body sits under one
+     * try/catch that funnels any throw into `recordGrammarFailure` (#1548).
+     */
+    async fetchGrammar(grammarFile) {
+        // BEFORE resolving a write directory: a vendored grammar is never
+        // downloaded, so the write dir has no bearing on its verdict. Resolving
+        // first let the "no writable grammars directory" branch below answer
+        // RETRYABLE for a missing vendored wasm on any host where
+        // web-tree-sitter isn't locatable — reporting a packaging fault as a
+        // transient download failure, and arming a cooldown for a fetch that can
+        // never happen.
+        if (isVendoredGrammar(grammarFile)) {
+            const { reason } = vendoredGrammarRefusal(grammarFile);
+            this.recordGrammarFailure(grammarFile, reason ?? `${grammarFile} is missing from vendor/grammars/.`, 
+            /* retryable */ false);
+            return false;
+        }
+        const dir = this.grammarsDir && fs.existsSync(this.grammarsDir)
+            ? this.grammarsDir
+            : this.grammarsWriteDir();
+        if (!dir) {
+            // No writable grammars directory could be located (e.g. pi compiled
+            // this module to a temp dir and web-tree-sitter isn't resolvable
+            // from there yet). This is an environment condition, not a CDN
+            // verdict — #1536 review F2: it must get the same cooldown +
+            // notification treatment as a download failure, not a silent
+            // unmemoized `false` that re-does the same failing resolution
+            // sweep on every single demand.
+            this.recordGrammarFailure(grammarFile, "No writable grammars directory could be located for the runtime fetch.", 
+            /* retryable */ true);
+            return false;
+        }
+        // Reuse the shared single-file downloader (same CDN/source as the
+        // postinstall) — see clients/grammar-source.ts.
+        const { ok, retryable, reason } = await downloadGrammarDetailed(dir, grammarFile);
+        if (ok) {
+            if (!this.grammarsDir)
+                this.grammarsDir = dir;
+            this.grammarRetryAtMs.delete(grammarFile);
+            this.grammarFailureAttempts.delete(grammarFile);
+            this.grammarLastNotifiedDelayMs.delete(grammarFile);
+            logTreeSitterDiagnostic({
+                subsystem: "tree-sitter-client",
+                level: "warn",
+                message: `fetched missing tree-sitter grammar ${grammarFile} at runtime (install scripts were skipped by the package manager)`,
+                metadata: { grammarFile, outcome: "fetched" },
+            });
+        }
+        else {
+            // `retryable` distinguishes a durable CDN verdict (404/410 — a
+            // retry hits the same answer) from everything else (offline, DNS,
+            // a down CDN, a 5xx, a timeout), which says nothing durable about
+            // the grammar (#1536 review F4). Only the retryable case gets the
+            // bounded cooldown; a durable failure keeps the pre-#1536 latched
+            // behavior, matching the issue's own allowance.
+            //
+            // `reason`, when the downloader supplies one, names the actual failure
+            // shape (#1548: "returned an HTML page, not a wasm module") instead of
+            // the generic guess — the difference between a diagnosable log line
+            // and one that sends the user to inspect their package manager while a
+            // captive portal is the real cause.
+            this.recordGrammarFailure(grammarFile, reason ??
+                "The package manager skipped install scripts and the runtime download failed.", retryable);
+        }
+        return ok;
+    }
+    /**
+     * Record one failed grammar-ensure attempt: arm (or extend) the retry
+     * cooldown, record the degradation, and notify the user at most once per
+     * session per DISTINCT retry delay (#1536 review F1/F2/F4/F5/F6). Shared
+     * by the "no writable directory" and "download failed" arms of
+     * `ensureGrammar` — both are failures of the SAME ensure attempt, just
+     * with a different point of failure.
+     */
+    recordGrammarFailure(grammarFile, detail, retryable) {
+        const attempts = (this.grammarFailureAttempts.get(grammarFile) ?? 0) + 1;
+        this.grammarFailureAttempts.set(grammarFile, attempts);
+        // A durable verdict (404/410) never expires -- matches the issue's "a
+        // genuinely unavailable grammar may still latch" allowance. Everything
+        // else gets the bounded exponential cooldown.
+        const retryDelayMs = retryable
+            ? transientRetryDelayMs(attempts, "probe-timeout")
+            : undefined;
+        this.grammarRetryAtMs.set(grammarFile, retryDelayMs === undefined
+            ? Number.POSITIVE_INFINITY
+            : Date.now() + retryDelayMs);
+        const unavailable = retryable
+            ? `tree-sitter grammar '${grammarFile}' is unavailable — symbol search, ` +
+                `module reports and structural rules for this language will be degraded. ` +
+                `${detail} pi-lens will retry automatically in ${Math.round(retryDelayMs / 1000)}s; ` +
+                `if the problem persists, allow the package manager's build scripts ` +
+                `(pnpm approve-builds / bun trustedDependencies) or restore network access.`
+            : `tree-sitter grammar '${grammarFile}' is unavailable — symbol search, ` +
+                `module reports and structural rules for this language will be degraded. ` +
+                `${detail} The grammar source reports it does not exist (not a network problem), so this will not ` +
+                `resolve on retry. Fix: reinstall with a manager that runs postinstall, allow its build scripts ` +
+                `(pnpm approve-builds / bun trustedDependencies), or restore network access.`;
+        logTreeSitterDiagnostic({
+            subsystem: "tree-sitter-client",
+            message: unavailable,
+            metadata: {
+                grammarFile,
+                outcome: "unavailable",
+                retryable,
+                retryDelayMs,
+                attempts,
+            },
+        });
+        // #1536 review F1: incrementDegradationCount keeps ONE ring-buffer slot
+        // per subject (bumping its count in place) instead of recordDegradation's
+        // one-new-entry-per-call — a grammar retrying every cooldown window would
+        // otherwise flood the shared "grammar-blocked" kind's 20-slot ring and
+        // evict unrelated entries (e.g. a different grammar's V8-crash block
+        // reason from loadLanguage/grammarBlockReason) after ~20 cycles.
+        incrementDegradationCount({
+            kind: "grammar-blocked",
+            subject: grammarFile,
+            // #1548: carry `detail` into the RETRYABLE reason too. All retryable
+            // failures used to share one string, so the ledger could not tell an
+            // offline laptop from a captive portal serving HTML — the two need
+            // different user actions, and the ledger is what a bug report shows.
+            reason: retryable
+                ? `runtime grammar download failed — retryable (${detail.trim()})`
+                : `runtime grammar download failed — durable (${detail.trim()})`,
+        });
+        this.refreshGrammarSessionLatches();
+        // HUMAN-audience: an offline grammar fetch silently degrades this
+        // language's features, so it reaches the user through the HOST's render
+        // path (#1333) rather than a raw terminal write. Notify once per DISTINCT
+        // retry delay this session (#1536 review F6) -- a fresh failure streak or
+        // an escalated backoff is new information worth surfacing; an unchanged
+        // repeat during the same cooldown tier is not.
+        const notifyKey = retryDelayMs ?? -1;
+        if (this.grammarLastNotifiedDelayMs.get(grammarFile) !== notifyKey) {
+            this.grammarLastNotifiedDelayMs.set(grammarFile, notifyKey);
+            notifyUserDegradation(`pi-lens: ${unavailable}`);
+        }
+    }
+    /**
+     * Record a `Language.load` failure on a file `resolveGrammarFile` had just
+     * vouched for (#1564) — the diagnosis gap #1548 left open: the preamble
+     * check proves the first four bytes are `\0asm`, not that the whole body
+     * decodes. A decode error here (a truncated download, on-disk corruption)
+     * is evidence the FILE is bad, so it gets the exact same treatment as an
+     * ensure-time download failure: invalidate the resolve memo so the next
+     * demand re-fetches instead of reusing the same broken file forever, and
+     * reuse `recordGrammarFailure`'s cooldown/degradation/notification
+     * machinery rather than hand-rolling a parallel one — a persistently
+     * truncated CDN response would otherwise re-download and re-fail on every
+     * single parse.
+     *
+     * A DURABLE decode failure (the bytes are complete and correct, but ABI-
+     * incompatible with the installed `web-tree-sitter` — a version drift, not
+     * a truncation) is classified `retryable` here too, same as everything
+     * else this method sees: there is no way to tell "truncated" from "wrong
+     * ABI" from the error message alone, so it re-downloads and re-fails once
+     * per cooldown tier instead of latching forever. That is bounded by the
+     * cooldown ladder (this never re-fetches faster than #1536's backoff) and
+     * by `BLOCKED_GRAMMARS` for the narrower case that's fatal to the process
+     * rather than just wrong (`grammar-source.ts`). The redownload only helps
+     * if a fresh fetch could actually be a DIFFERENT (compatible) build,
+     * which is exactly what the `grammar-source.test.ts` version/lock sync
+     * guard (`lock.version === TREE_SITTER_WASMS_VERSION`) exists to keep
+     * true — without it, a version bump with a stale lock would make every
+     * redownload land the identical bytes and spin the ladder against a file
+     * that can never pass.
+     */
+    recordGrammarLoadFailure(grammarPath, grammarFile, err) {
+        const stamp = grammarFileStamp(grammarPath);
+        this.verifiedGrammarPaths.delete(grammarPath);
+        if (stamp)
+            this.decodeFailedGrammarPaths.set(grammarPath, stamp);
+        const message = err instanceof Error ? err.message : String(err);
+        logTreeSitterDiagnostic({
+            subsystem: "tree-sitter-client",
+            level: "warn",
+            message: `Language.load failed for ${grammarPath} even though the wasm preamble check ` +
+                `passed (${message}) — most likely a truncated download (#1564). Treating the ` +
+                `grammar as missing so the next demand re-fetches it.`,
+            metadata: { grammarFile, path: grammarPath, outcome: "load-failed" },
+        });
+        this.recordGrammarFailure(grammarFile, `Language.load failed on a resolved grammar file (${message}).`, 
+        /* retryable */ true);
+    }
     /** Initialize tree-sitter WASM runtime */
     async init() {
         if (this.wasmAborted)
             return false;
         if (this.initialized)
             return true;
+        if (this.webTreeSitterLoadFailed)
+            return false;
         if (this.initPromise)
             return this.initPromise;
         this.initPromise = (async () => {
             try {
-                const mod = await loadWebTreeSitter();
+                let mod;
+                try {
+                    mod = await loadWebTreeSitter();
+                }
+                catch (err) {
+                    // See webTreeSitterLoadFailed's doc: an EVALUATION-shaped
+                    // rejection is a dead retry, so latch instead of leaving
+                    // initPromise clearable (the finally below would otherwise let
+                    // the very next parse call re-import the same doomed URL). A
+                    // RESOLUTION-shaped rejection is left alone — initPromise still
+                    // clears below, so the next init() call retries for real.
+                    const classification = classifyWebTreeSitterLoadFailure(err);
+                    if (classification === "evaluation") {
+                        this.webTreeSitterLoadFailed = true;
+                    }
+                    recordDegradationOnce({
+                        kind: "web-tree-sitter-load-failed",
+                        subject: "web-tree-sitter",
+                        reason: (err instanceof Error ? err.message : String(err)) +
+                            (classification === "resolution"
+                                ? " (resolution failure — retryable)"
+                                : " (evaluation failure — latched for the session)"),
+                    });
+                    throw err;
+                }
                 // biome-ignore lint/suspicious/noExplicitAny: web-tree-sitter module shape varies (Parser direct / default-wrapped)
                 const anyMod = mod;
                 const ParserClass = anyMod.Parser || anyMod.default || anyMod;
@@ -492,6 +1106,17 @@ export class TreeSitterClient {
         })();
         return this.initPromise;
     }
+    /**
+     * Re-arm the web-tree-sitter load latch for a new session (#1592 review
+     * round 2 F2). Deliberately does NOT touch `wasmAborted` or `initialized`
+     * — see `webTreeSitterLoadFailed`'s doc for why the abort case stays
+     * process-lifetime, and a successful init has nothing to re-arm. Called
+     * from `resetTreeSitterClientLoadState()` (tree-sitter-shared.ts), wired
+     * into `resetDispatchBaselines()` beside `resetAstGrepNapiLoadState()`.
+     */
+    resetLoadStateForSession() {
+        this.webTreeSitterLoadFailed = false;
+    }
     /** Load language grammar */
     async loadLanguage(languageId) {
         if (this.wasmAborted)
@@ -552,7 +1177,16 @@ export class TreeSitterClient {
             return language;
         }
         catch (err) {
-            this.reportWasmAbort(err);
+            // An uncatchable-shaped WASM abort poisons the whole process (#402) —
+            // `reportWasmAbort` already records + handles it. Everything else
+            // (#1564) is a DECODE failure on a file `resolveGrammarFile` just
+            // vouched for — e.g. "Code section extends past end of the module" on
+            // a truncated-but-magic-valid download. That is evidence the file
+            // itself is bad, not the runtime, so record it and stop vouching for
+            // this exact file so the next demand can re-fetch it.
+            if (!this.reportWasmAbort(err)) {
+                this.recordGrammarLoadFailure(grammarPath, grammarFile, err);
+            }
             this.dbg(`Language load error: ${err}`);
             return null;
         }
@@ -2350,20 +2984,18 @@ export class TreeSitterClient {
                 return !hasExceptionSpec;
             }
             case "eq_mod_fn": {
-                // Workaround for web-tree-sitter not auto-applying #eq? predicates
-                // on the structural pattern of a query that has predicates. The
-                // query captures @MOD, @FN but the predicates aren't enforced
-                // (see evaluatePredicates in clients/tree-sitter-client.ts).
+                // Belt-and-braces re-check of the #eq? predicates that
+                // evaluatePredicates already enforces (clients/tree-sitter-client.ts).
                 // This filter re-applies the #eq? checks at post_filter time.
                 const mod = captures.MOD?.text ?? "";
                 const fn = captures.FN?.text ?? "";
                 return mod === "threading" && fn === "Thread";
             }
             case "regex_first_arg_identifier": {
-                // Workaround for web-tree-sitter not auto-applying #eq?/#match?
-                // predicates on the structural pattern (see evaluatePredicates).
-                // This post_filter re-applies both predicate checks AND
-                // the first-argument check:
+                // Belt-and-braces re-check of the #eq?/#match? predicates that
+                // evaluatePredicates already enforces, plus the first-argument
+                // check that predicates can't express. This post_filter re-applies
+                // both predicate checks AND the first-argument check:
                 // 1. MOD must be "re"  (would-be #eq? @MOD "re")
                 // 2. FUNC must match the regex method pattern (#match? @FUNC ...)
                 // 3. First arg must be an identifier (dynamic pattern)
@@ -3135,12 +3767,83 @@ export class TreeSitterClient {
         });
     }
     /**
-     * Evaluate text predicates (#match?, #eq?) for a query match.
-     * web-tree-sitter stores these as compiled functions in query.textPredicates[patternIndex]
-     * and does NOT apply them automatically via .matches().
+     * Latch so the "textPredicates is malformed" diagnostic log line fires once
+     * per `TreeSitterClient` instance for the life of the process (this client is
+     * a process-wide singleton in production — see clients/tree-sitter-shared.ts),
+     * not once per call. This gates ONLY the log line: process-wide log volume is
+     * the concern here, not the user-facing degradation record below, which must
+     * re-arm every session (see recordDegradationOnce) — including for a Query
+     * object the LRU query cache (queryCache/queryBatchCache above) kept alive
+     * across a session boundary, since the cache is evicted, never cleared.
+     */
+    textPredicatesInvalidLogged = false;
+    /**
+     * Typed accessor for `query.textPredicates`. If the property is missing or the
+     * wrong shape — e.g. a future web-tree-sitter upgrade renames or removes it —
+     * `query.textPredicates?.[i] ?? []` would silently mean "no predicates for this
+     * pattern," passing every match through unfiltered. That's a silent fail-open on
+     * #match?/#eq? predicates that rules rely on for correctness, and because this
+     * runs for every match of every query, it would zero out ALL structural matches
+     * across every language while pi-lens reports "no issues found." Fail loud (log
+     * once per client instance, record a degradation so it reaches the user) and
+     * closed (report the query has no usable predicates) instead of guessing.
+     *
+     * No WeakSet short-circuit for already-known-bad queries here (#1523 review
+     * R1): `Array.isArray` is O(1), so memoizing it buys nothing, and a
+     * process-lifetime WeakSet would make the SAME cached Query object (the query
+     * cache is LRU-evicted, never cleared) skip straight past
+     * `recordDegradationOnce` on every call after the first — which is exactly
+     * what made the degradation record fail to re-arm across a session boundary
+     * for a query the cache kept warm. `recordDegradationOnce` itself is called
+     * unconditionally on every invalid check; the ledger's own once-per-kind/
+     * subject dedupe (cleared by resetDegradationLedger, which handleSessionStart
+     * calls first thing — clients/runtime-session.ts) is the single source of
+     * truth for "how often does this actually get recorded."
+     */
+    // biome-ignore lint/suspicious/noExplicitAny: web-tree-sitter Query instances
+    hasValidTextPredicates(query) {
+        const valid = Array.isArray(query?.textPredicates);
+        if (!valid) {
+            if (!this.textPredicatesInvalidLogged) {
+                this.textPredicatesInvalidLogged = true;
+                logTreeSitterDiagnostic({
+                    subsystem: "tree-sitter-client",
+                    message: "web-tree-sitter Query.textPredicates is missing or not an array — " +
+                        "#match?/#eq? predicates cannot be evaluated. Failing CLOSED: matches " +
+                        "for this query are dropped rather than reported unfiltered.",
+                    metadata: { textPredicatesType: typeof query?.textPredicates },
+                });
+            }
+            // User-facing signal (#1523 review F1). Called unconditionally on every
+            // invalid check (not gated by a client-lifetime latch) so it re-arms
+            // every session, per the R1 fix above.
+            recordDegradationOnce({
+                kind: "query-predicates-invalid",
+                subject: "web-tree-sitter",
+                reason: "Query.textPredicates is missing or not an array — #match?/#eq? " +
+                    "predicates cannot be evaluated; structural matches relying on them " +
+                    "are dropped fail-closed",
+            });
+        }
+        return valid;
+    }
+    /**
+     * Evaluate text predicates (#match?, #eq?) for a query match. web-tree-sitter
+     * 0.25's `Query.matches()` DOES apply these predicates itself (probed on the
+     * shipped grammars — see clients/tree-sitter-symbol-extractor.ts), so this is a
+     * belt-and-braces re-filter, not a workaround for missing enforcement. It also
+     * doubles as the fail-closed guard (#1523): if `query.textPredicates` is ever
+     * missing or malformed, this drops the match instead of assuming it already
+     * passed upstream.
      */
     // biome-ignore lint/suspicious/noExplicitAny: web-tree-sitter types
     evaluatePredicates(query, match) {
+        if (!this.hasValidTextPredicates(query))
+            return false;
+        // `?.` guards a post-validation removal of the property (e.g. a later
+        // mutation strips it after the first successful check) so the read can't
+        // throw here — an uncaught throw would be swallowed by the outer try/catch
+        // in searchFileWithQuery and silently zero out matches for the whole file.
         const predicates = query.textPredicates?.[match.patternIndex] ?? [];
         return predicates.every((fn) => fn(match.captures));
     }
@@ -3161,7 +3864,9 @@ export class TreeSitterClient {
                             captures[capture.name] = capture.node;
                         }
                     }
-                    // Evaluate #match? and #eq? predicates that web-tree-sitter doesn't enforce automatically
+                    // Belt-and-braces re-check of #match?/#eq? predicates (web-tree-sitter
+                    // 0.25's Query.matches() already applies them) plus the fail-closed
+                    // guard for a malformed query.textPredicates (see evaluatePredicates).
                     if (!this.evaluatePredicates(query, match)) {
                         continue;
                     }