@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/dist/clients/govulncheck-client.js

@@ -22,11 +22,15 @@ import * as path from "node:path";
 import { safeSpawnAsync } from "./safe-spawn.js";
 import { assertInstallAllowed } from "./project-trust.js";
 import { SecurityScanClient } from "./security-scan-client.js";
+import { classifyProbeFailure, describeProbeEvidence, INSTALL_TRANSIENT_MAX_ATTEMPTS, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
+import { recordDegradationOnce } from "./degradation-ledger.js";
 const EMPTY_RESULT = {
     success: false,
     findings: [],
 };
 const SCAN_TIMEOUT_MS = 120_000;
+/** Budget for the `go install` auto-install, ms. */
+const INSTALL_TIMEOUT_MS = 60_000;
 // --- Client ---
 export class GovulncheckClient extends SecurityScanClient {
     constructor(verbose = false) {
@@ -54,6 +58,16 @@ export class GovulncheckClient extends SecurityScanClient {
             this.available = true;
             return true;
         }
+        if (this.probeWasTransient()) {
+            // #1467: a timed-out/killed probe says nothing about whether
+            // govulncheck is on PATH. Latching `false` here disabled it for the
+            // life of the process; a `go install` here would be a heavyweight
+            // reaction to a host hiccup. probeVersion has already recorded the
+            // expiring verdict and its retry schedule (#1501) — re-marking it
+            // here would double-escalate the cooldown. Retry later.
+            this.log("govulncheck probe timed out; retrying later (not installing)");
+            return false;
+        }
         if (!assertInstallAllowed("govulncheck go install")) {
             // Deliberately NOT latching `available = false` (#1350 delta review):
             // trust denial is policy, not tool absence -- a later trust grant
@@ -67,30 +81,172 @@ export class GovulncheckClient extends SecurityScanClient {
         // project has a go.mod the user has the Go toolchain by definition.
         // Same shape as rust-clippy / cargo: lean on the language's own
         // install mechanism rather than adding a new installer strategy.
-        const goOnPath = await safeSpawnAsync("go", ["version"], {
-            timeout: 5000,
-        });
+        const goProbeStartedAt = Date.now();
+        const goSampler = startHostStallSampler();
+        let goOnPath;
+        let goHostStallMs;
+        try {
+            goOnPath = await safeSpawnAsync("go", ["version"], {
+                timeout: 5000,
+            });
+        }
+        finally {
+            goHostStallMs = goSampler.stop();
+        }
         if (goOnPath.error || goOnPath.status !== 0) {
+            const { outcome, cause } = classifyProbeFailure(goOnPath, {
+                hostStallMs: goHostStallMs,
+            });
+            if (outcome === "transient") {
+                this.log("`go version` probe timed out; retrying govulncheck later");
+                const retryAfterMs = this.markTransientlyUnavailable(cause);
+                logAvailabilityDecision({
+                    tool: "govulncheck",
+                    verdict: "unavailable",
+                    outcome,
+                    cause,
+                    elapsedMs: Date.now() - goProbeStartedAt,
+                    latched: false,
+                    hostStallMs: goHostStallMs,
+                    ...(retryAfterMs > 0 && { retryAfterMs }),
+                    budgetMs: 5000,
+                });
+                return false;
+            }
             this.log("go binary not on PATH — cannot auto-install govulncheck");
-            this.available = false;
+            // Derived from the `go version` probe above, and recorded with it: a
+            // reader can see WHY govulncheck went quiet without re-running it (#1500).
+            // The evidence names `go`, because that is what was spawned — a row that
+            // carried go's errno unlabelled under `tool: "govulncheck"` invited the
+            // exact misreading the field exists to prevent.
+            this.noteDurableAbsence({
+                ...describeProbeEvidence(goOnPath, "go"),
+                install: "not-attempted",
+            });
             return false;
         }
         this.log("govulncheck not found, attempting auto-install via go install");
-        const install = await safeSpawnAsync("go", ["install", "golang.org/x/vuln/cmd/govulncheck@latest"], { timeout: 60_000 });
+        const installStartedAt = Date.now();
+        const installSampler = startHostStallSampler();
+        let install;
+        let installHostStallMs;
+        try {
+            install = await safeSpawnAsync("go", ["install", "golang.org/x/vuln/cmd/govulncheck@latest"], { timeout: INSTALL_TIMEOUT_MS });
+        }
+        finally {
+            installHostStallMs = installSampler.stop();
+        }
         if (install.error || install.status !== 0) {
             this.log(`govulncheck auto-install failed: ${(install.stderr ?? "").slice(0, 200)}`);
-            this.available = false;
+            // #1476: `go install` runs against a 60 s budget over the network. A
+            // timed-out or killed install says nothing about whether govulncheck
+            // can ever be installed here, so it must not latch the durable
+            // "tool is not installed" verdict the way a real install refusal does.
+            // A non-zero exit (module not found, compile error) still latches:
+            // that IS evidence about this machine, and retrying it every turn
+            // would be a `go install` storm.
+            const { outcome, cause } = classifyProbeFailure(install, {
+                hostStallMs: installHostStallMs,
+            });
+            if (outcome === "transient") {
+                // #1497: the retried operation here is a ≤60s network compile,
+                // not a cheap probe, so it escalates on the install-class
+                // schedule and latches at the attempt ceiling instead of
+                // re-compiling every few minutes forever.
+                const retryAfterMs = this.markTransientlyUnavailable(cause, {
+                    operationClass: "install",
+                });
+                const exhausted = retryAfterMs === 0;
+                const ceilingReason = `go install timed out ${INSTALL_TRANSIENT_MAX_ATTEMPTS} times; install retries disabled until the next session`;
+                if (exhausted) {
+                    // The symptom a user notices is an unexplained busy core, not a
+                    // missing tool — so the terminal verdict gets the louder record.
+                    // Once per session, matching the latch's own lifetime: both re-arm
+                    // at `session_start` (review F3).
+                    recordDegradationOnce({
+                        kind: "install-retry-exhausted",
+                        subject: "govulncheck",
+                        reason: ceilingReason,
+                    });
+                }
+                // One record per decision, so an install that keeps timing out is
+                // readable in latency.log the same day (#1467's forensic trail).
+                logAvailabilityDecision({
+                    tool: "govulncheck",
+                    verdict: "unavailable",
+                    outcome,
+                    // At the ceiling the latch rewrote the cause; a row still saying
+                    // `probe-timeout` would read as "cooling down" (#1497 review F5).
+                    cause: exhausted ? (this.latchedCause() ?? cause) : cause,
+                    elapsedMs: Date.now() - installStartedAt,
+                    latched: exhausted,
+                    hostStallMs: installHostStallMs,
+                    ...(retryAfterMs > 0 && { retryAfterMs }),
+                    budgetMs: INSTALL_TIMEOUT_MS,
+                    // The ceiling verdict is an ASSERTION by this call site, not a
+                    // classification of one spawn, and #1534's convention is that such a
+                    // row says so and carries the install facts behind it. Every retry
+                    // DID run a `go install` that failed, so `install: "failed"` is
+                    // earned, and the reason names the ceiling rather than the spawn.
+                    ...(exhausted && {
+                        classifiedBy: "caller",
+                        evidence: {
+                            ...describeProbeEvidence(install, "go install"),
+                            install: "failed",
+                            installReason: ceilingReason,
+                        },
+                    }),
+                });
+                return false;
+            }
+            // A non-transient install failure (module not found, compile error) IS
+            // evidence about this machine, so it latches — but the row says the
+            // install was tried and failed, which a plain absence never does (#1500).
+            this.noteDurableAbsence({
+                ...describeProbeEvidence(install, "go install"),
+                install: "failed",
+            }, { elapsedMs: Date.now() - installStartedAt });
             return false;
         }
         // `go install` writes to `$GOBIN` or `$GOPATH/bin`. The user may not
         // have that on `$PATH`. Re-probe by name (works when it is on PATH)
         // then fall back to the canonical bin dirs.
-        const reprobe = await safeSpawnAsync("govulncheck", ["-version"], {
-            timeout: 5000,
-        });
+        const reprobeStartedAt = Date.now();
+        const reprobeSampler = startHostStallSampler();
+        let reprobe;
+        let reprobeHostStallMs;
+        try {
+            reprobe = await safeSpawnAsync("govulncheck", ["-version"], {
+                timeout: 5000,
+            });
+        }
+        finally {
+            reprobeHostStallMs = reprobeSampler.stop();
+        }
         if (!reprobe.error && reprobe.status === 0) {
             this.log("govulncheck auto-installed and found on PATH");
             this.available = true;
+            // The initial PATH probe already wrote a latched `unavailable` row
+            // (#1500's own assertion doesn't fire here — the reprobe SUCCEEDED —
+            // but that first probe's verdict still logged, before `go install`
+            // ever ran). Without a compensating row here, the durable record says
+            // govulncheck is off when `go install` just put it on PATH (#1606).
+            logAvailabilityDecision({
+                tool: "govulncheck",
+                verdict: "available",
+                outcome: "success",
+                cause: "ok",
+                elapsedMs: Date.now() - reprobeStartedAt,
+                latched: true,
+                hostStallMs: reprobeHostStallMs,
+                budgetMs: 5000,
+                classifiedBy: "caller",
+                evidence: {
+                    install: "succeeded",
+                    binary: "govulncheck",
+                    source: "go-install",
+                },
+            });
             return true;
         }
         // Look in the canonical install locations and remember the absolute
@@ -111,6 +267,24 @@ export class GovulncheckClient extends SecurityScanClient {
                     this.binaryPath = candidate;
                     this.available = true;
                     this.log(`govulncheck auto-installed at ${candidate}`);
+                    // Same compensating row as the on-PATH reprobe arm above (#1606):
+                    // the initial probe already latched `unavailable`, and this arm
+                    // is the OTHER way to recover — the canonical $GOBIN/$GOPATH walk
+                    // found it after the on-PATH reprobe missed.
+                    logAvailabilityDecision({
+                        tool: "govulncheck",
+                        verdict: "available",
+                        outcome: "success",
+                        cause: "ok",
+                        elapsedMs: Date.now() - installStartedAt,
+                        latched: true,
+                        classifiedBy: "caller",
+                        evidence: {
+                            install: "succeeded",
+                            binary: path.basename(candidate),
+                            source: "go-install",
+                        },
+                    });
                     return true;
                 }
             }
@@ -118,8 +292,43 @@ export class GovulncheckClient extends SecurityScanClient {
                 // fall through to next candidate
             }
         }
+        // The install SUCCEEDED, so the tool is on this machine somewhere. If the
+        // re-probe merely timed out, latching "not installed" would be the #1467
+        // mistake one step later in the same function (#1476).
+        const { outcome, cause } = classifyProbeFailure(reprobe, {
+            hostStallMs: reprobeHostStallMs,
+        });
+        if (outcome === "transient") {
+            this.log("govulncheck installed but the re-probe timed out; retrying later");
+            const retryAfterMs = this.markTransientlyUnavailable(cause);
+            logAvailabilityDecision({
+                tool: "govulncheck",
+                verdict: "unavailable",
+                outcome,
+                cause,
+                // The re-probe's own wall time. A hard-coded 0 here was the #1474
+                // defect verbatim: a duration field that measures nothing.
+                elapsedMs: Date.now() - reprobeStartedAt,
+                latched: false,
+                hostStallMs: reprobeHostStallMs,
+                ...(retryAfterMs > 0 && { retryAfterMs }),
+                budgetMs: 5000,
+            });
+            return false;
+        }
+        // The third silent arm (#1500 review): the install SUCCEEDED and the binary
+        // is nowhere the re-probe or the canonical bin dirs could find it. That is a
+        // durable, actionable fact — and until now it latched with no record at all,
+        // so a $GOBIN misconfiguration was indistinguishable from govulncheck simply
+        // not being installed. `install: "succeeded"` also appears on the two success
+        // arms above (#1606's compensating `available` rows) — this is the durable
+        // FAILURE counterpart, an install that worked but left nothing locatable.
         this.log("govulncheck auto-install succeeded but binary not locatable — check $GOBIN / $GOPATH");
-        this.available = false;
+        this.noteDurableAbsence({
+            ...describeProbeEvidence(reprobe, "govulncheck"),
+            install: "succeeded",
+            installReason: "installed binary not found on PATH, $GOBIN or $GOPATH/bin",
+        }, { elapsedMs: Date.now() - reprobeStartedAt });
         return false;
     }
     /**

package/node_modules/pi-lens/dist/clients/grammar-source.js

@@ -9,9 +9,12 @@
  *    import this compiled module (it runs before the TS build), so it keeps a
  *    mirror — guarded against drift by `tests/clients/grammar-source.test.ts`.
  */
+import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeFileAtomic } from "./atomic-write.js";
+import { recordDegradationOnce } from "./degradation-ledger.js";
+import { getPackageRoot } from "./package-root.js";
 /** tree-sitter-wasms release the grammars are pulled from. */
 export const TREE_SITTER_WASMS_VERSION = "0.1.13";
 /** unpkg mirror of the tree-sitter-wasms artifacts. */
@@ -32,6 +35,59 @@ export const GRAMMAR_SOURCE_OVERRIDES = {
 export function grammarSourceUrl(filename) {
     return GRAMMAR_SOURCE_OVERRIDES[filename]?.url ?? `${GRAMMAR_CDN_BASE}/${filename}`;
 }
+/**
+ * Grammars built in-house and committed to `vendor/grammars/`.
+ *
+ * tree-sitter-cue: CUE has no published wasm anywhere — not on npm
+ * (`tree-sitter-cue` there is a native binding only), not in the
+ * `tree-sitter-wasms` aggregator, and upstream cuts no releases (#1522).
+ * Building it ourselves, with a modern `dylink.0` section, is the only way to
+ * give `.cue` structural analysis, so the artifact is committed and pinned
+ * rather than fetched. Mirrored by `VENDORED_GRAMMARS` in
+ * scripts/download-grammars.
+ */
+export const VENDORED_GRAMMARS = {
+    "tree-sitter-cue.wasm": {
+        repo: "https://github.com/eonpatapon/tree-sitter-cue",
+        commit: "dd7b90e0770ff18070c515937ba3c3d6d93db00e",
+        license: "MIT",
+        buildCommand: "npx tree-sitter-cli build --wasm",
+    },
+};
+/** Is `filename` built in-house rather than fetched from a CDN? */
+export function isVendoredGrammar(filename) {
+    return Object.hasOwn(VENDORED_GRAMMARS, filename);
+}
+/**
+ * The verdict for a vendored grammar that isn't on disk. It ships in
+ * `vendor/grammars/`, which the resolve path searches first, so needing to
+ * "fetch" one means the committed file is missing from the install: a
+ * packaging fault, not a network one. No retry, no cooldown ladder, and above
+ * all no fetch of a CDN URL that would 404 forever. Non-retryable is the
+ * honest verdict precisely because a later attempt cannot change it.
+ *
+ * Shared so that every caller answers identically. `tree-sitter-client.ts`'s
+ * `fetchGrammar` has to consult this BEFORE it resolves a write directory:
+ * that resolution can fail on its own (web-tree-sitter not locatable yet) and
+ * would otherwise return the generic RETRYABLE environment verdict, hiding a
+ * missing vendored asset behind a transient-looking download failure.
+ */
+export function vendoredGrammarRefusal(filename) {
+    return {
+        ok: false,
+        retryable: false,
+        reason: `${filename} is built in-house and ships in vendor/grammars/; it has no ` +
+            `download source, so a missing copy means the install is incomplete.`,
+    };
+}
+/**
+ * Absolute path to the committed `vendor/grammars` directory. Resolved from the
+ * package root for the same reason `grammarManifestPath` is (#1564): an
+ * `import.meta.url` offset collapses once `dist/index.js` is bundled.
+ */
+export function vendoredGrammarsDir() {
+    return path.join(getPackageRoot(import.meta.url), "vendor", "grammars");
+}
 /** Language id → grammar wasm filename. */
 export const LANGUAGE_TO_GRAMMAR = {
     typescript: "tree-sitter-typescript.wasm",
@@ -60,6 +116,7 @@ export const LANGUAGE_TO_GRAMMAR = {
     vue: "tree-sitter-vue.wasm",
     yaml: "tree-sitter-yaml.wasm",
     zig: "tree-sitter-zig.wasm",
+    cue: "tree-sitter-cue.wasm",
 };
 /** The full set of grammar wasm filenames (deduped). */
 export const GRAMMAR_FILES = [
@@ -110,13 +167,216 @@ export function grammarBlockReason(filename, rt = currentGrammarRuntime()) {
     const block = BLOCKED_GRAMMARS[filename];
     return block?.blocked(rt) ? block.reason : null;
 }
+/**
+ * The four-byte WebAssembly module preamble, `\0asm` — the first bytes of
+ * every valid `.wasm` file. Single source of truth for the #1548 validation:
+ * both the download path (validate before writing) and the on-disk path
+ * (`fileHasWasmMagic`, for a file poisoned before this shipped) key off it.
+ */
+export const WASM_MAGIC = [0x00, 0x61, 0x73, 0x6d];
+/** Do `bytes` start with the wasm magic number? */
+export function hasWasmMagic(bytes) {
+    if (bytes.length < WASM_MAGIC.length)
+        return false;
+    return WASM_MAGIC.every((byte, i) => bytes[i] === byte);
+}
+/**
+ * Does the file at `filePath` start with the wasm magic number? `false` if it
+ * doesn't, is shorter than four bytes, or cannot be read at all — every one of
+ * those means "do not hand this path to `Language.load`".
+ *
+ * Reads four bytes, so it is cheap enough to run on a resolve path; callers
+ * that resolve repeatedly should still memoize the positive answer.
+ */
+export function fileHasWasmMagic(filePath) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, "r");
+        const head = Buffer.alloc(WASM_MAGIC.length);
+        const read = fs.readSync(fd, head, 0, head.length, 0);
+        return read === head.length && hasWasmMagic(head);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* nothing useful to do */
+            }
+        }
+    }
+}
+const HTML_PREFIXES = ["<!doctype html", "<html", "<head", "<?xml"];
+/**
+ * A short, log-safe sentence naming what arrived instead of a wasm module
+ * (#1548). Never echoes the body — only its shape, byte count and the first
+ * four bytes in hex — so a proxy's login page cannot smuggle content into a
+ * user-facing notification.
+ */
+export function describeNonWasmBody(bytes) {
+    if (bytes.length === 0) {
+        return "The download returned an empty body (0 bytes) instead of a wasm module.";
+    }
+    const head = Buffer.from(bytes.subarray(0, Math.min(16, bytes.length))).toString("latin1");
+    const lead = head.trimStart().toLowerCase();
+    const shape = HTML_PREFIXES.some((prefix) => lead.startsWith(prefix))
+        ? "an HTML page (a captive portal or proxy intercepted the request)"
+        : "non-wasm data";
+    const magic = Buffer.from(bytes.subarray(0, WASM_MAGIC.length))
+        .toString("hex")
+        .replace(/../g, "$& ")
+        .trim();
+    // Kept short on purpose: this is spliced into a user notification and into
+    // the degradation ledger, whose fields truncate at 200 characters.
+    return (`The download returned ${shape} — ` +
+        `${bytes.length} bytes starting ${magic}, not a wasm module.`);
+}
+/**
+ * Override applied for tests only (`_setGrammarManifestForTests`): `undefined`
+ * means "no override — use the real cached/loaded manifest", so `null` is a
+ * distinct, deliberate value (simulates a missing/corrupt lock file).
+ */
+let manifestOverride;
+let cachedManifest;
+/**
+ * `scripts/grammars.lock.json`'s absolute path, resolved from the installed
+ * PACKAGE ROOT rather than a fixed relative offset from this module (#1564).
+ * `import.meta.url` collapses to the bundle's own file once `dist/index.js`
+ * is esbuild-bundled (every merged module reports the bundle's URL, not its
+ * own), so a `join(dirname(fileURLToPath(import.meta.url)), "../scripts/...")`
+ * offset — correct in the unbundled repo/`npm run build` layout — resolves to
+ * the wrong directory once bundled. `getPackageRoot` instead walks up from
+ * wherever this module actually loaded from until it finds `package.json`,
+ * which lands on the package root under both layouts; `scripts/grammars.lock.json`
+ * is committed and shipped there (see `files` in package.json), so both the
+ * repo checkout and an installed npm package resolve it correctly.
+ */
+function grammarManifestPath() {
+    return path.join(getPackageRoot(import.meta.url), "scripts", "grammars.lock.json");
+}
+/**
+ * The manifest, without the missing-manifest degradation report — split out
+ * so `loadGrammarManifest` can report on every `null` return (cached misses
+ * included), while this half stays a pure cache lookup.
+ */
+function resolveGrammarManifest() {
+    if (manifestOverride !== undefined)
+        return manifestOverride;
+    if (cachedManifest !== undefined)
+        return cachedManifest;
+    try {
+        const raw = fs.readFileSync(grammarManifestPath(), "utf-8");
+        cachedManifest = JSON.parse(raw);
+    }
+    catch {
+        cachedManifest = null;
+    }
+    return cachedManifest;
+}
+/**
+ * Load + cache `scripts/grammars.lock.json`. Returns `null` (never throws) if
+ * the file is missing or malformed — an installed package predating this fix,
+ * or a corrupted lock file, degrades to the Content-Length check
+ * (`downloadGrammarDetailed`) instead of blocking every runtime grammar
+ * fetch. That fallback is silent to the CALLER by design (it's not a fetch
+ * failure), so it would otherwise never reach the record a bug report shows —
+ * report once per session that the STRONGEST check (sha256) is being skipped
+ * repo-wide, so a downgrade to the weaker Content-Length-only path is on the
+ * record rather than invisible.
+ */
+function loadGrammarManifest() {
+    const manifest = resolveGrammarManifest();
+    if (manifest === null) {
+        recordDegradationOnce({
+            kind: "grammar-blocked",
+            subject: "grammars.lock.json",
+            reason: "the pinned sha256 manifest is unavailable — runtime grammar downloads " +
+                "fall back to the weaker Content-Length check (or no integrity check at " +
+                "all for a source with neither).",
+        });
+    }
+    return manifest;
+}
+/** Test-only manifest injection — see `manifestOverride` above. */
+export function _setGrammarManifestForTests(manifest) {
+    manifestOverride = manifest;
+}
+/** `sha256:<hex>` digest of `data`, matching the manifest's format. */
+function sha256Hex(data) {
+    return `sha256:${createHash("sha256").update(data).digest("hex")}`;
+}
+/**
+ * Pinned sha256 for `filename` from `scripts/grammars.lock.json`, or
+ * `undefined` when the manifest is unavailable or has no entry for it — the
+ * same "can't verify" fallback `downloadGrammarDetailed`'s own hash check
+ * already applies. `manifest.grammars[filename]` is keyed by filename
+ * regardless of a `GRAMMAR_SOURCE_OVERRIDES` entry (see the comment on that
+ * check), so a single lookup covers both the aggregator and override cases.
+ *
+ * This is the single source of truth a version bump (`TREE_SITTER_WASMS_VERSION`,
+ * or a `SOURCE_OVERRIDES` entry) reaches through: `--write-manifest` regenerates
+ * the pinned hash for the new build, so a cached file's sha256 no longer
+ * matching this value IS the version-changed signal — no separate "which
+ * version produced this file" bookkeeping is needed (#1760).
+ */
+export function pinnedGrammarHash(filename) {
+    return loadGrammarManifest()?.grammars[filename];
+}
+/**
+ * sha256 of the file at `filePath`, or `undefined` if it cannot be read (does
+ * not exist, a directory, a permission error). Callers that cannot verify
+ * must treat that the same as "no pinned hash" — never as a mismatch, which
+ * would force an unbounded refetch loop against an unreadable path.
+ */
+export function grammarFileSha256(filePath) {
+    try {
+        return sha256Hex(fs.readFileSync(filePath));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * First 12 hex characters of a `sha256:<hex>` digest, for log/ledger/
+ * notification strings. Printing the full 64-hex digest on BOTH sides of a
+ * mismatch overran the degradation ledger's 200-character field cap (the
+ * truncation `describeNonWasmBody` above already designs around) and left
+ * the user notification — 579 characters, almost entirely hex — clipping the
+ * more diagnostic PINNED hash mid-string before a reader ever saw it. 12 hex
+ * characters (48 bits) is more than enough to tell "genuinely the wrong
+ * file" from a coincidence in a log line; it is not a security boundary.
+ */
+function shortHash(hash) {
+    const hex = hash.startsWith("sha256:") ? hash.slice("sha256:".length) : hash;
+    return `sha256:${hex.slice(0, 12)}…`;
+}
 /**
  * Fetch one grammar wasm into `destDir`, staged and renamed via
- * `atomic-write.ts` so a reader never sees a half-written wasm. Returns true
- * on success. Never throws — a failed fetch (offline, 4xx) degrades to "grammar
- * unavailable" so callers can decide how to handle it. A grammar that crashes the
- * runtime is protected at LOAD time (BLOCKED_GRAMMARS / grammarBlockReason), not
- * by refusing to download it.
+ * `atomic-write.ts` so a reader never sees a half-written wasm. Never
+ * throws — a failed fetch (offline, 4xx) degrades to "grammar unavailable"
+ * so callers can decide how to handle it.
+ *
+ * #1548: the response BODY is validated against the wasm magic number before
+ * anything is written, so a 200-with-HTML from a captive portal is a failed
+ * (retryable) download rather than a poisoned file on disk. A grammar that
+ * crashes the runtime
+ * is protected at LOAD time (BLOCKED_GRAMMARS / grammarBlockReason), not by
+ * refusing to download it.
+ *
+ * #1564: the magic-number check alone lets a TRUNCATED-but-genuine wasm body
+ * through — a connection dropped mid-transfer still starts with `\0asm`. Two
+ * further checks close that: (1) when the pinned manifest
+ * (`scripts/grammars.lock.json`, already trusted by the postinstall path) has
+ * a sha256 for this grammar, the full body must match it; (2) when the
+ * response reports `Content-Length`, the received byte count must match it —
+ * cheaper, and the only check available when no pinned hash exists (an
+ * override not yet in the manifest, or a future grammar added before
+ * `--write-manifest` is re-run). Both are retryable failures, same shape as a
+ * captive portal: the CDN answered, but the bytes are not trustworthy.
  *
  * #1217: the staging name used to be hand-rolled `.${filename}.${pid}.tmp` —
  * per-process, so two concurrent fetches of one grammar shared a staging inode
@@ -124,19 +384,82 @@ export function grammarBlockReason(filename, rt = currentGrammarRuntime()) {
  * which made that hard to reach through the runtime path but did not cover
  * direct callers.
  */
-export async function downloadGrammar(destDir, filename) {
+export async function downloadGrammarDetailed(destDir, filename) {
+    if (isVendoredGrammar(filename))
+        return vendoredGrammarRefusal(filename);
     try {
         fs.mkdirSync(destDir, { recursive: true });
         const res = await fetch(grammarSourceUrl(filename));
-        if (!res.ok)
-            throw new Error(`HTTP ${res.status}`);
+        if (!res.ok) {
+            // 404/410: the CDN has authoritatively answered "this wasm does not
+            // exist at this URL" — a retry hits the same answer. Every other
+            // non-ok status (429, 5xx) is retryable. A captive portal answers
+            // 200, so it never reaches here; the magic-number check below is
+            // what catches it (#1548).
+            const retryable = res.status !== 404 && res.status !== 410;
+            return { ok: false, retryable };
+        }
         const data = Buffer.from(await res.arrayBuffer());
+        // #1548: `res.ok` says the transport succeeded, NOT that the body is a
+        // grammar. A captive portal (airport wifi, corporate proxy) answers 200
+        // with its own login page; writing that to disk as tree-sitter-<lang>.wasm
+        // poisons the path permanently, because every later resolve finds the
+        // (garbage) file and reports the grammar as available while
+        // `Language.load` fails on every parse. Validate the wasm preamble BEFORE
+        // writing, and classify a non-wasm body as a retryable failure — the same
+        // shape as an offline fetch, so it flows through #1536's cooldown ladder.
+        if (!hasWasmMagic(data)) {
+            return { ok: false, retryable: true, reason: describeNonWasmBody(data) };
+        }
+        // #1564 cheap check: a body shorter (or longer) than the server's own
+        // declared Content-Length is a truncated/corrupted transfer, regardless
+        // of whether a pinned hash exists for this grammar.
+        const declaredLength = res.headers.get("content-length");
+        if (declaredLength !== null) {
+            const expectedBytes = Number.parseInt(declaredLength, 10);
+            if (Number.isFinite(expectedBytes) && expectedBytes !== data.length) {
+                return {
+                    ok: false,
+                    retryable: true,
+                    reason: `The download reported Content-Length: ${expectedBytes} but only ` +
+                        `${data.length} bytes arrived — a truncated transfer.`,
+                };
+            }
+        }
+        // #1564 primary check: verify the full body against the pinned sha256,
+        // closing the gap Content-Length can't (a proxy that sets a matching
+        // Content-Length on a truncated body, or a chunked response with none at
+        // all). `manifest.grammars[filename]` is keyed by filename regardless of
+        // override — an overridden grammar's hash was generated against the
+        // override's own URL (`scripts/download-grammars.ts --write-manifest`
+        // fetches via the same `SOURCE_OVERRIDES` map), so no extra alignment is
+        // needed here. No entry (manifest missing, or a grammar added before the
+        // manifest was regenerated) falls back to the Content-Length check above.
+        const expectedHash = loadGrammarManifest()?.grammars[filename];
+        if (expectedHash) {
+            const actualHash = sha256Hex(data);
+            if (actualHash !== expectedHash) {
+                return {
+                    ok: false,
+                    retryable: true,
+                    reason: `The download's sha256 (${shortHash(actualHash)}) does not match the ` +
+                        `pinned manifest (${shortHash(expectedHash)}) — a corrupt or truncated transfer.`,
+                };
+            }
+        }
         // bestEffort: false — a swallowed write failure would return true for a
         // grammar that never landed.
         writeFileAtomic(path.join(destDir, filename), data, { bestEffort: false });
-        return true;
+        return { ok: true, retryable: true };
     }
     catch {
-        return false;
+        // A thrown fetch (offline, DNS failure, aborted, ECONNRESET) or a write
+        // failure is transient by construction — the CDN never got to answer.
+        return { ok: false, retryable: true };
     }
 }
+/** Back-compat boolean-only wrapper for callers that only need pass/fail
+ * (the postinstall script, prewarm-grammars test helper). */
+export async function downloadGrammar(destDir, filename) {
+    return (await downloadGrammarDetailed(destDir, filename)).ok;
+}