@herbertgao/pi-extensions 2026.9.15 → 2026.9.17

package/node_modules/pi-lens/dist/clients/inline-blocker-dispositions.js

@@ -0,0 +1,186 @@
+/**
+ * Disposition/rule/inline-suppression policy for the turn-end
+ * "Unresolved from this turn" blocker replay (#3246).
+ *
+ * `runtime-turn.ts` re-serves every live `InlineBlockerRecord` the turn's
+ * dispatches left behind. Until this module, it pushed the record's
+ * ALREADY-RENDERED `summary` string verbatim, so a `lens_diagnostic_mark`
+ * made after the record was written had nothing to act on: the durable
+ * disposition store was honored by `lens_diagnostics`, the widget, the cached
+ * scanner lanes, late auxiliary and cascade, while this one surface replayed
+ * the pre-mark text on every later turn — including turns that edited only an
+ * unrelated file. That is #3246's report.
+ *
+ * The fix is the same shape `blocker-past-eof.ts` already argued for the
+ * `lines` field: carry the STRUCTURED diagnostics the summary was rendered
+ * from (`dispatchResult.blockers`, via `PipelineResult.inlineBlockerDiagnostics`
+ * and `InlineBlockerRecord.diagnostics`) and re-derive at read time, rather
+ * than regex-parsing a string built for human display. With the diagnostics in
+ * hand this module runs the ONE filter stack every other findings surface runs
+ * — `clients/dispatch/finding-policy.ts`'s inline `pi-lens-ignore` → stored
+ * dispositions → `.pi-lens.json` rule policy — against the file's CURRENT
+ * bytes, and re-renders the survivors with `formatDiagnostics(..., "blocking")`,
+ * the SAME renderer `dispatcher.ts` used to build the stored summary. No second
+ * anchor implementation and no second renderer: an unmarked record therefore
+ * re-renders byte-identically to what dispatch produced.
+ *
+ * Ordering (#3246 mutation (c)): the policy runs over the WHOLE candidate set
+ * and `formatDiagnostics` applies its 10-row display cap to the survivors.
+ * Filtering after the cap would leave a marked finding occupying a display slot
+ * and hide an unmarked one behind "... and N more" — the cap-before-policy
+ * shape `cascade-format.ts` already avoids.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { recordDegradationOnce } from "./degradation-ledger.js";
+import { hasAnyDispositionMarks } from "./diagnostic-dispositions.js";
+import { applyFindingPolicy, inlineBlockerIdentities, loadProjectRulePolicyMap, } from "./dispatch/finding-policy.js";
+import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
+import { formatDiagnostics } from "./dispatch/utils/format-utils.js";
+/**
+ * The file's CURRENT bytes, or `""` when they cannot be read.
+ *
+ * `""` is `FindingPolicyOptions.content`'s documented fail-open input: inline
+ * suppression becomes a no-op and the STRICT anchor hashes an empty line, so it
+ * cannot match a mark made against real content and the finding stays VISIBLE.
+ * Never hide a blocking finding over an I/O error (AGENTS.md shape 48).
+ */
+function readCurrentContent(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Apply the shared finding policy to one live inline-blocker record.
+ *
+ * Diagnostics are grouped by the file they were raised AGAINST, not by the
+ * record's own path: `dispatchResult.blockers` is pooled across every runner
+ * dispatched for the edited file, and a chart-wide runner (helm-lint,
+ * helm-render) reports blocking diagnostics against sibling files — the same
+ * cross-file population `pipeline.ts` filters out of `inlineBlockerLines`.
+ * Anchoring those against the record's path would derive the wrong strict
+ * anchor and read the wrong file's `pi-lens-ignore` comments.
+ */
+export function applyInlineBlockerPolicy(record, cwd) {
+    const diagnostics = record.diagnostics;
+    if (!diagnostics || diagnostics.length === 0) {
+        // Bounded per (kind, subject) by the ledger itself — this condition
+        // recurs every turn end for the same record, so a counted row would
+        // grow without adding information (AGENTS.md shapes 13/17). Recorded
+        // ONLY when the project actually holds marks: with an empty store there
+        // is nothing this record failed to honor, and a row every session for
+        // every unstructured record would be noise, not a degradation.
+        if (hasAnyDispositionMarks(cwd)) {
+            recordDegradationOnce({
+                kind: "inline-blocker-unstructured",
+                subject: `inline-blocker:${toRunnerDisplayPath(cwd, record.filePath)}`,
+                reason: "record carries no structured diagnostics; disposition marks cannot be applied to its rendered summary",
+            });
+        }
+        return {
+            body: record.summary,
+            candidates: 0,
+            kept: 0,
+            suppressed: 0,
+            unstructured: true,
+        };
+    }
+    const byFile = new Map();
+    for (const diagnostic of diagnostics) {
+        // Resolved against the PROJECT root, never `process.cwd()`: a runner that
+        // reports a project-relative path would otherwise be grouped under the
+        // agent host's working directory and read the wrong file's bytes. No
+        // case/separator fold on the key (catalog shape 1): two spellings of one
+        // file would only cost a duplicate read here — `anchorsForDiagnostic`
+        // canonicalizes both the cwd and the file path itself, so the anchors,
+        // and therefore the verdict, are identical either way.
+        const owner = path.resolve(cwd, diagnostic.filePath);
+        const group = byFile.get(owner);
+        if (group)
+            group.push(diagnostic);
+        else
+            byFile.set(owner, [diagnostic]);
+    }
+    // `loadPiLensProjectConfig` is mtime-cached, so several groups cost one stat.
+    const policyMap = loadProjectRulePolicyMap(cwd);
+    const dropped = new Set();
+    for (const [filePath, group] of byFile) {
+        const { kept } = applyFindingPolicy(group, {
+            cwd,
+            filePath,
+            content: readCurrentContent(filePath),
+            policyMap,
+            identities: inlineBlockerIdentities,
+        });
+        const survivors = new Set(kept);
+        for (const diagnostic of group) {
+            if (!survivors.has(diagnostic))
+                dropped.add(diagnostic);
+        }
+    }
+    const kept = dropped.size === 0
+        ? [...diagnostics]
+        : diagnostics.filter((diagnostic) => !dropped.has(diagnostic));
+    return {
+        body: kept.length === 0
+            ? undefined
+            : formatDiagnostics(kept, "blocking").trim(),
+        candidates: diagnostics.length,
+        kept: kept.length,
+        suppressed: dropped.size,
+        unstructured: false,
+    };
+}
+/**
+ * How many file/tool identities {@link summarizeInlineBlockerPolicy}'s one
+ * per-turn record names. The COUNTS are always exact; only the identity lists
+ * are capped, so a turn that touched a hundred files writes a bounded row
+ * rather than a file listing (AGENTS.md shape 17).
+ */
+const IDENTITY_CAP = 10;
+/**
+ * The ONE bounded record the turn writes for this pass — never one per
+ * finding. Derived here rather than accumulated at the call site so the shape
+ * and its bound live with the policy they describe.
+ */
+export function summarizeInlineBlockerPolicy(entries) {
+    const files = [];
+    const tools = new Set();
+    let stale = 0;
+    let candidates = 0;
+    let kept = 0;
+    let suppressed = 0;
+    let unstructured = 0;
+    for (const entry of entries) {
+        for (const tool of entry.sources ?? [])
+            tools.add(tool);
+        if (entry.stale)
+            stale += 1;
+        const outcome = entry.outcome;
+        if (outcome === undefined)
+            continue;
+        candidates += outcome.candidates;
+        kept += outcome.kept;
+        suppressed += outcome.suppressed;
+        if (outcome.unstructured)
+            unstructured += 1;
+        // The files a mark actually acted on — the identity a reader needs to
+        // reconstruct a replay report.
+        if (outcome.suppressed > 0 && files.length < IDENTITY_CAP) {
+            files.push(entry.displayPath);
+        }
+    }
+    return {
+        records: entries.length,
+        stale,
+        candidates,
+        kept,
+        dispositionSuppressed: suppressed,
+        unstructured,
+        files,
+        tools: [...tools].slice(0, IDENTITY_CAP),
+    };
+}

package/node_modules/pi-lens/dist/clients/install-diagnostics.js

@@ -13,6 +13,10 @@ import { createRequire } from "node:module";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+// The shared web-tree-sitter ladder imports nothing but node:fs/node:path, so
+// importing it keeps this module's "loads even when the deps that failed are
+// unreachable" property intact.
+import { resolveWebTreeSitterPackageDir } from "../scripts/lib/web-tree-sitter-dir.mjs";
 const require = createRequire(import.meta.url);
 const ISSUES_URL = "https://github.com/apmantza/pi-lens/issues";
 /** Runtime third-party deps whose resolution is the documented failure surface. */
@@ -88,12 +92,21 @@ export function collectInstallDiagnostics() {
         return ["ast-grep", "ast-grep.exe", "sg", "sg.exe"].some((b) => fs.existsSync(path.join(dir, b)));
     }, false);
     const grammars = safe(() => {
-        let dir = path.dirname(require.resolve("web-tree-sitter"));
-        while (path.basename(dir) !== "web-tree-sitter" &&
-            dir !== path.dirname(dir)) {
-            dir = path.dirname(dir);
-        }
-        return fs.existsSync(path.join(dir, "grammars", "tree-sitter-typescript.wasm"));
+        // #3409 (sweep sibling of the same shape): this probe used to walk up from
+        // the BARE `web-tree-sitter` specifier, so on the host pi ships — a `bun
+        // build --compile` binary, where a bare specifier throws MODULE_NOT_FOUND
+        // — it reported `grammars: false` for an install whose grammars were
+        // present. The one report a user pastes when the long tail of grammars is
+        // dead has to measure the same directory the client does, through the same
+        // ladder.
+        const dir = resolveWebTreeSitterPackageDir({
+            resolve: (specifier) => require.resolve(specifier),
+            // `root` is this probe's own walk to the package root, computed above.
+            packageRoot: () => root,
+            cwd: () => process.cwd(),
+        });
+        return (!!dir &&
+            fs.existsSync(path.join(dir, "grammars", "tree-sitter-typescript.wasm")));
     }, false);
     if (deps.some((d) => !d.resolved)) {
         notes.push("One or more runtime dependencies did not resolve. This is the #285/#335 failure mode — usually a package-manager layout (pnpm symlink store / nested install) the runtime's resolver can't traverse, or an outdated runtime.");

package/node_modules/pi-lens/dist/clients/installer/index.js

@@ -68,8 +68,10 @@ import { createGenerationMap } from "../generation-guard.js";
 import { resolveToolCwd } from "../tool-cwd.js";
 import { allAvailableGlobalBinDirs, installArgs, pmBinary, resolveNodePackageManager, } from "../package-manager.js";
 import { resetSafeSpawnWindowsCommandCache, safeSpawnAsync, } from "../safe-spawn.js";
+import { createBoundedOutputSink, DEFAULT_MAX_OUTPUT_BYTES, } from "../spawn-output-cap.js";
 import { probeToolAsync } from "../tool-probe.js";
 import { logSessionStart } from "../sessionstart-logger.js";
+import { resolveGitHubToken } from "../zizmor-config.js";
 // Global installation directory for pi-lens tools
 const TOOLS_DIR = path.join(getGlobalPiLensDir(), "tools");
 const INSTALL_LOCK_PATH = path.join(TOOLS_DIR, ".install.lock");
@@ -247,7 +249,15 @@ const MANAGED_PACKAGE_FORMATTERS = [
         id: "cmake-format",
         name: "cmake-format",
         installStrategy: "pip",
-        packageName: "cmakelang",
+        // The `yaml` EXTRA, never the bare distribution (#3312). cmakelang reads a
+        // `.cmake-format.yaml` project config through `import yaml`, and upstream
+        // puts PyYAML behind an extra: cmakelang 0.6.13's PyPI metadata declares
+        // `pyyaml (>=5.3) ; extra == 'yaml'`. A bare install still answers
+        // `cmake-format --version` with status 0 and then dies with
+        // `ModuleNotFoundError: No module named 'yaml'` on the first YAML config —
+        // the nightly's red cmake row. Every rung of the pip ladder passes this
+        // string verbatim to pip/pipx, which both accept the `pkg[extra]` spec.
+        packageName: "cmakelang[yaml]",
     },
     { id: "oxfmt", name: "oxfmt", installStrategy: "npm", packageName: "oxfmt" },
 ];
@@ -465,7 +475,7 @@ export const TOOLS = [
         checkCommand: "jscpd",
         checkArgs: ["--version"],
         installStrategy: "npm",
-        packageName: "jscpd@5.0.12", // v4's packaging bug (reprism dep missing lib/languages/) is gone in v5's ground-up Rust rewrite — verified: real per-platform native binary (jscpd-windows-x64-msvc etc. via optionalDependencies, no missing-dir regression), --min-lines/--min-tokens/--reporters/--output/--ignore all unchanged, JSON schema fields read by clients/jscpd-client.ts's parseReport() (statistics.total.*, duplicates[].firstFile/secondFile.name+start, .lines, .tokens) are identical, and it's ~50x faster on this repo (4.1s -> 76ms detection time) — closes #582
+        packageName: "jscpd@5.3.0", // v5.3.0 is the repository's exact devDependency; the v4 packaging defect that required the older v5.0.12 pin is gone, and parseReport() reads the unchanged clone-report fields.
         binaryName: "jscpd",
     },
     // Structural search and dead code detection
@@ -549,6 +559,15 @@ export const TOOLS = [
         installStrategy: "pip",
         packageName: "cmake-language-server",
         binaryName: "cmake-language-server",
+        // Upstream 0.1.11 (the latest release) imports `LanguageServer` from
+        // `pygls.server`, a symbol pygls 2 removed, while declaring only
+        // `pygls>=1.1.1` — so an unconstrained install resolves pygls 2.1.1 and
+        // produces a launcher that cannot start. Measured against PyPI for the
+        // nightly's interpreter (#3311): `pip download --python-version 3.12
+        // cmake-language-server` → `pygls-2.1.1`; with this constraint →
+        // `pygls-1.3.1` + `lsprotocol-2023.0.1`, and `cmake-language-server
+        // --version` then prints `cmake-language-server 0.1.11` and exits 0.
+        pipConstraints: ["pygls<2"],
     },
     {
         id: "yaml-language-server",
@@ -2585,9 +2604,58 @@ async function getToolPathResolved(toolId, onTransient) {
         if (githubPath)
             return githubPath;
     }
-    // Check if global
-    if (await isCommandAvailable(tool.checkCommand, tool.checkArgs)) {
-        return tool.checkCommand;
+    // Check if global. `isCommandAvailable` is a PATH walk plus a stat — it
+    // ignores its `_args` parameter by construction — so it answers "a file with
+    // that name is on PATH", never "that command runs". Every OTHER rung of this
+    // ladder spawn-verifies its candidate with the entry's own `checkArgs` before
+    // resolving to it; this rung did not, and a PATH entry that is a file but
+    // cannot run then SHADOWED the managed install that would have worked
+    // (#3311 lane C):
+    //   - rust-analyzer: rustup's `DUP_TOOLS` proxy (rustup 1.29.1 src/lib.rs:32)
+    //     sits in ~/.cargo/bin on every rustup box whether or not the
+    //     `rust-analyzer` COMPONENT is installed. Where it is not, the proxy
+    //     errors out instead of speaking LSP — and the github-release install
+    //     pi-lens would have downloaded was never attempted.
+    //   - cmake-language-server: `pipx install` exits 0 and drops a launcher on
+    //     PATH whose venv resolved pygls 2.x, which removed the symbol the 0.1.11
+    //     server imports. This rung returned it ahead of the pip-user rung, whose
+    //     verification would have caught it.
+    // A VERDICT — the binary ran and rejected its own check (nonzero exit) —
+    // falls through to the rungs below and, for an installable strategy, to the
+    // managed install. A STALL (timeout/signal, or a spawn-boundary refusal the
+    // binary never saw) and an INCONCLUSIVE probe are not verdicts (#1569/#2722
+    // semantics), so those keep the pre-#3311 behaviour and resolve to PATH —
+    // dropping a working-but-slow tool on a kill would be a worse lie than the
+    // one this fixes. `recordVersion` is deliberately NOT passed: version-pin
+    // drift (#589) is about pi-lens's own managed installs, and feeding a
+    // system-installed version into it would turn every PATH tool at another
+    // version into a forced reinstall.
+    if (await isCommandAvailable(tool.checkCommand)) {
+        // A `verification: "package-entry"` entry (#2722) is verified from the
+        // installed tree BESIDE its shim — `verifyNpmPackageEntry` derives the
+        // package dir from `<…>/node_modules/.bin/<shim>`. A bare PATH name has no
+        // such tree to read, so that evidence is unavailable here and its absence
+        // says nothing about the command: this rung keeps the pre-#3311 behaviour
+        // for those entries rather than inventing a verdict from a failed lookup.
+        if (packageEntryVerification(tool) !== undefined)
+            return tool.checkCommand;
+        let probeStalled = false;
+        const verified = await verifyToolBinary(tool.checkCommand, undefined, () => {
+            probeStalled = true;
+            onTransient();
+        }, getToolVerificationTimeout(tool), tool.checkArgs, undefined, () => {
+            probeStalled = true;
+        });
+        if (verified || probeStalled)
+            return tool.checkCommand;
+        // One record per tool per session: the rejected candidate and the check
+        // that rejected it. verifyToolBinary already logged the kind/exit code.
+        recordDegradationOnce({
+            kind: "installer-path-candidate-unrunnable",
+            subject: toolId,
+            reason: `${tool.checkCommand} on PATH failed its own check (${tool.checkArgs.join(" ")}); ignoring PATH for this tool`,
+        });
+        logSessionStart(`auto-install ${toolId}: PATH candidate ${tool.checkCommand} failed ${tool.checkArgs.join(" ")} — ignoring PATH, trying managed install`);
     }
     if (tool.installStrategy === "npm") {
         const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id, onTransient, tool.checkArgs, getToolVerificationTimeout(tool));
@@ -2775,6 +2843,39 @@ async function findPipUserToolPath(binaryName, onTransient, verificationArgs = [
     }
     return undefined;
 }
+/**
+ * The verdict of one `<interpreter> -m site --user-base` probe (#3383).
+ *
+ * Both probes accumulate through {@link createBoundedOutputSink} instead of
+ * `stdout += data`: the concatenation ran inside a `data` handler, where V8's
+ * `RangeError: Invalid string length` is an uncaught exception rather than this
+ * promise's value, and nothing bounded an interpreter that decides to write
+ * forever. A TRUNCATED probe resolves EMPTY rather than trimming a prefix,
+ * because the prefix of a path is a different path: `addBinToPath` would put a
+ * plausible-looking wrong directory on PATH. Empty is the value both probes
+ * already resolve when an interpreter is missing, and every caller handles it.
+ *
+ * Exported for `tests/clients/off-seam-output-bounds.test.ts`: both `data`
+ * handlers that feed it sit inside module-private probe loops that only a real
+ * `python3` on PATH can drive, so this is the seam the bound is pinned at.
+ */
+export function userBaseProbeResult(command, code, stdout) {
+    if (stdout.truncated) {
+        recordDegradationOnce({
+            kind: "spawn-output-cap-truncated",
+            subject: `user-base-probe:${command}`,
+            reason: `\`${command} -m site --user-base\` reached the ${DEFAULT_MAX_OUTPUT_BYTES}-byte default cap after ${stdout.observedBytes} bytes; the probed user base is unusable`,
+            metadata: {
+                capBytes: DEFAULT_MAX_OUTPUT_BYTES,
+                capSource: "default",
+                observedBytes: stdout.observedBytes,
+                killed: false,
+            },
+        });
+        return "";
+    }
+    return code === 0 ? stdout.text.trim() : "";
+}
 async function getPythonUserBaseCandidates() {
     const candidates = [];
     const seen = new Set();
@@ -2821,9 +2922,9 @@ async function getPythonUserBaseCandidates() {
                 resolve("");
                 return;
             }
-            let stdout = "";
-            proc.stdout?.on("data", (data) => (stdout += data));
-            proc.on("exit", (code) => resolve(code === 0 ? stdout.trim() : ""));
+            const stdout = createBoundedOutputSink();
+            proc.stdout?.on("data", (data) => stdout.append(data));
+            proc.on("exit", (code) => resolve(userBaseProbeResult(probe.command, code, stdout)));
             proc.on("error", () => resolve(""));
         });
         add(userBase);
@@ -2839,10 +2940,42 @@ async function getPythonUserBaseCandidates() {
  * call, never the asset download (see installGitHubTool) — the release CDN must
  * not receive the token.
  */
-function githubApiAuthHeaders() {
-    const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+async function githubApiAuthHeaders() {
+    const token = await resolveGitHubToken();
     return token ? { Authorization: `Bearer ${token}` } : {};
 }
+class HttpStatusError extends Error {
+    statusCode;
+    constructor(statusCode, url) {
+        super(url ? `HTTP ${statusCode} for ${url}` : `HTTP ${statusCode}`);
+        this.name = "HttpStatusError";
+        this.statusCode = statusCode;
+    }
+}
+class GitHubHttpError extends HttpStatusError {
+    anonymousRateLimitExhausted;
+    constructor(statusCode, requestHeaders, responseHeaders) {
+        super(statusCode);
+        this.name = "GitHubHttpError";
+        this.message = `GitHub API HTTP ${statusCode}`;
+        this.anonymousRateLimitExhausted =
+            statusCode === 403 &&
+                !Object.keys(requestHeaders).some((key) => key.toLowerCase() === "authorization") &&
+                readHeader(responseHeaders, "x-ratelimit-remaining") === "0";
+    }
+}
+function readHeader(headers, name) {
+    const entry = Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1];
+    return Array.isArray(entry) ? entry[0]?.trim() : entry?.trim();
+}
+function isGitHubApiUrl(url) {
+    try {
+        return new URL(url).host.toLowerCase() === "api.github.com";
+    }
+    catch {
+        return false;
+    }
+}
 function sameHost(a, b) {
     try {
         return new URL(a).host === new URL(b).host;
@@ -2891,7 +3024,9 @@ function httpsGetWithMeta(url, maxRedirects = 5, headers = {}) {
             }
             if (res.statusCode !== 200) {
                 res.resume();
-                return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+                return reject(isGitHubApiUrl(url)
+                    ? new GitHubHttpError(res.statusCode ?? 0, headers, res.headers)
+                    : new HttpStatusError(res.statusCode ?? 0, url));
             }
             const chunks = [];
             res.on("data", (chunk) => chunks.push(chunk));
@@ -2967,11 +3102,21 @@ prefetchedRelease) {
     else {
         logSessionStart(`github-install ${tool.id}: fetching release metadata from ${spec.repo}`);
         try {
-            const body = await httpsGet(`https://api.github.com/repos/${spec.repo}/releases/latest`, 5, githubApiAuthHeaders());
+            const body = await httpsGet(`https://api.github.com/repos/${spec.repo}/releases/latest`, 5, await githubApiAuthHeaders());
             releaseJson = JSON.parse(body.toString("utf8"));
         }
         catch (err) {
-            logSessionStart(`github-install ${tool.id}: release fetch failed: ${err.message}`);
+            const reason = err instanceof GitHubHttpError && err.anonymousRateLimitExhausted
+                ? "GitHub API rate limit exhausted; authenticate with `gh auth login` or set GITHUB_TOKEN/GH_TOKEN and retry"
+                : `release fetch failed: ${err.message}`;
+            if (err instanceof GitHubHttpError && err.anonymousRateLimitExhausted) {
+                recordDegradationOnce({
+                    kind: "github-api-rate-limit",
+                    subject: tool.id,
+                    reason,
+                });
+            }
+            logSessionStart(`github-install ${tool.id}: ${reason}`);
             return undefined;
         }
     }
@@ -3524,15 +3669,25 @@ async function refreshGitHubManagedTool(tool, known) {
     let response;
     try {
         response = await httpsGetWithMeta(`https://api.github.com/repos/${spec.repo}/releases/latest`, 5, {
-            ...githubApiAuthHeaders(),
+            ...(await githubApiAuthHeaders()),
             ...(known.etag ? { "If-None-Match": known.etag } : {}),
         });
     }
     catch (err) {
+        const reason = err instanceof GitHubHttpError && err.anonymousRateLimitExhausted
+            ? "GitHub API rate limit exhausted; authenticate with `gh auth login` or set GITHUB_TOKEN/GH_TOKEN and retry"
+            : `release query failed: ${err.message}`;
+        if (err instanceof GitHubHttpError && err.anonymousRateLimitExhausted) {
+            recordDegradationOnce({
+                kind: "github-api-rate-limit",
+                subject: tool.id,
+                reason,
+            });
+        }
         return {
             ok: false,
             unchanged: true,
-            reason: `release query failed: ${err.message}`,
+            reason,
         };
     }
     if (response.statusCode === 304) {
@@ -4349,6 +4504,77 @@ export function pipScriptsDir(base, platform = installerPlatform()) {
     return path.join(base, platform === "win32" ? "Scripts" : "bin");
 }
 const pipPep668LoggedRefusals = createGenerationMap("installer-pep668-log");
+/**
+ * The constraints environment for `toolId` — `PIP_CONSTRAINT` **and**
+ * `UV_CONSTRAINT`, both naming the same written file — or `{}` when its registry
+ * entry declares no `pipConstraints` (#3311).
+ *
+ * Each resolver's own mechanism, not a pi-lens one, and BOTH are needed because
+ * `installPipTool`'s first rung is pipx, which chooses its own resolver:
+ * - `PIP_CONSTRAINT` is pip's environment form of `-c/--constraint`, and covers
+ *   pipx's pip backend, the pi-lens venv rung, `pip --user` and the
+ *   private-prefix rung.
+ * - `UV_CONSTRAINT` is uv's ("Equivalent to the `--constraints` command-line
+ *   argument", uv 0.12.10 `crates/uv-static/src/env_vars.rs`, added in uv
+ *   0.1.36) and covers pipx's uv backend — which pipx 1.17.6 makes the DEFAULT
+ *   "when uv is available … else 'pip'" (`pipx install --help`). That backend
+ *   ignores `PIP_CONSTRAINT` entirely, and its `--pip-args` translation covers
+ *   an allowlist (`--index-url`, `--extra-index-url`, `--find-links`,
+ *   `--trusted-host`, `--no-binary`, `--only-binary`, `--pre`, `--upgrade`,
+ *   `--no-cache-dir`) that does not include constraints — so neither the pip env
+ *   var nor a pip argv flag can reach it. Measured on pipx 1.17.6 + uv 0.12.10;
+ *   the transcripts are in the PR body (#3396 round 2).
+ *
+ * Both variables carry a WHITESPACE-SEPARATED LIST of files, so a path with a
+ * space in it is not a path to either resolver: uv fails the install outright
+ * (`error: File not found: …/space`, measured). The file therefore goes to the
+ * first whitespace-free directory, and without one the install proceeds
+ * unconstrained rather than broken — which the ladder's PATH verification then
+ * judges on its merits.
+ *
+ * The file is (re)written from the registry on every install, so a constraint
+ * that is edited or removed in the registry cannot be served from a stale file.
+ * A write failure is recorded and the install proceeds unconstrained — the same
+ * resolution as before this field existed.
+ */
+async function pipConstraintEnvFor(toolId) {
+    const constraints = TOOLS.find((t) => t.id === toolId)?.pipConstraints;
+    if (!constraints || constraints.length === 0)
+        return {};
+    const directories = [
+        path.join(getGlobalPiLensDir(), "pip-constraints"),
+        path.join(os.tmpdir(), "pi-lens-pip-constraints"),
+    ];
+    const directory = directories.find((candidate) => !/\s/.test(candidate));
+    if (!directory) {
+        recordDegradationOnce({
+            kind: "pip-constraint-path-unusable",
+            subject: toolId,
+            reason: `no whitespace-free directory for the constraints file (tried ${directories.join(", ")}); installing unconstrained`,
+        });
+        return {};
+    }
+    const file = path.join(directory, `${toolId}.txt`);
+    try {
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        // The shared atomic seam (#1609), not a raw write: a second pi-lens process
+        // may be reading this file as pip's `PIP_CONSTRAINT` while this one
+        // rewrites it, and a torn read would silently under-constrain the install.
+        await writeFileAtomicAsync(file, `${constraints.join("\n")}\n`, {
+            bestEffort: false,
+        });
+    }
+    catch (err) {
+        recordDegradationOnce({
+            kind: "pip-constraint-file-unwritable",
+            subject: toolId,
+            reason: `${file}: ${err instanceof Error ? err.message : String(err)}`,
+        });
+        return {};
+    }
+    logSessionStart(`auto-install pip ${toolId}: constraining resolution with ${constraints.join(", ")} (${file})`);
+    return { PIP_CONSTRAINT: file, UV_CONSTRAINT: file };
+}
 /**
  * Install a pip package tool
  */
@@ -4363,6 +4589,10 @@ options = {}) {
     try {
         const isWindows = installerPlatform() === "win32";
         const verb = options.upgrade ? ["install", "-U"] : ["install"];
+        // Read from the registry entry rather than added to this function's
+        // signature: every pip rung below, and pipx's OWN internal pip, is bounded
+        // by one env var, so there is nothing per-call to thread through.
+        const pipConstraintEnv = await pipConstraintEnvFor(toolId);
         // Built from `pipCommandCandidates()` — the single source of truth this
         // module and any other caller (the tool-smoke lane's toolchain-presence
         // probe, #2661 review) share, rather than a second, independently
@@ -4397,16 +4627,28 @@ options = {}) {
             });
             return binaryPath;
         };
-        const run = (command, args, env) => safeSpawnAsync(command, args, {
-            timeout: 120_000,
-            ignoreAmbientSignal: true,
-            lifetimeCoupled: true,
-            cwd: resolveToolCwd("runner", toolId, getGlobalPiLensDir(), {
-                cwd: getGlobalPiLensDir(),
-                suppressTelemetry: true,
-            }).cwd,
-            ...(env ? { env } : {}),
-        });
+        const run = (command, args, env) => {
+            // `pipConstraintEnv` is empty unless the entry declares
+            // `pipConstraints`, and it is applied HERE — the single spawn seam every
+            // rung of the ladder (pipx, venv, --user, private-prefix) goes through —
+            // so no rung can be reached with the constraint missing. pipx forwards
+            // it: its `run_subprocess` starts from `dict(os.environ)` and blocklists
+            // only PYTHONPATH/__PYVENV_LAUNCHER__ (pipx 1.16.7 src/pipx/util.py
+            // `_fix_subprocess_env`), so PIP_CONSTRAINT reaches the pip it drives.
+            const spawnEnv = Object.keys(pipConstraintEnv).length > 0
+                ? { ...(env ?? process.env), ...pipConstraintEnv }
+                : env;
+            return safeSpawnAsync(command, args, {
+                timeout: 120_000,
+                ignoreAmbientSignal: true,
+                lifetimeCoupled: true,
+                cwd: resolveToolCwd("runner", toolId, getGlobalPiLensDir(), {
+                    cwd: getGlobalPiLensDir(),
+                    suppressTelemetry: true,
+                }).cwd,
+                ...(spawnEnv ? { env: spawnEnv } : {}),
+            });
+        };
         const addBinToPath = async (binDir) => {
             try {
                 await fs.access(binDir);
@@ -4441,10 +4683,17 @@ options = {}) {
             return undefined;
         };
         if (await isCommandAvailable("pipx")) {
-            const result = await run("pipx", [
-                options.upgrade ? "upgrade" : "install",
-                packageName,
-            ]);
+            // `--force` on the install verb (#3312): this function runs ONLY when the
+            // tool was not resolvable, yet plain `pipx install <pkg>` over an
+            // existing venv exits 0 while printing "not modifying existing
+            // installation. Pass '--force' …" — so an install that changes nothing
+            // reports success and hands back the same unusable launcher. That is the
+            // #2638/#2661 shape (an install that installs nothing reporting like a
+            // real one) and it also swallows a changed package spec, e.g. a venv
+            // created before `cmakelang` grew its `[yaml]` extra above.
+            const result = await run("pipx", options.upgrade
+                ? ["upgrade", packageName]
+                : ["install", "--force", packageName]);
             const error = (result.error?.message ?? result.stderr).trim();
             if (result.status === 0) {
                 const location = await run("pipx", [
@@ -4523,9 +4772,9 @@ options = {}) {
                         resolve("");
                         return;
                     }
-                    let stdout = "";
-                    probe.stdout?.on("data", (data) => (stdout += data));
-                    probe.on("exit", (code) => resolve(code === 0 ? stdout.trim() : ""));
+                    const stdout = createBoundedOutputSink();
+                    probe.stdout?.on("data", (data) => stdout.append(data));
+                    probe.on("exit", (code) => resolve(userBaseProbeResult(candidate.command, code, stdout)));
                     probe.on("error", () => resolve(""));
                 });
                 const binaryPath = base