@herbertgao/pi-extensions 2026.9.14 → 2026.9.16

package/node_modules/pi-lens/dist/clients/warm-attach.js

@@ -7,6 +7,7 @@ import { logLatency } from "./latency-logger.js";
 import { touchCoverageGap } from "./lsp/diagnostic-binding.js";
 import { loadLspService } from "./lsp-lazy.js";
 import { contentHash, createWarmIpcLineReader, diagnosticsIpcPathForCwd, requestWarmCodeActions, requestWarmDiagnostics, WARM_CODE_ACTION_LOOKUP_LIMIT, WARM_DIAGNOSTICS_SCHEMA_VERSION, } from "./mcp/ipc.js";
+import { incrementDegradationCount, recordDegradationOnce, } from "./degradation-ledger.js";
 import { normalizeFilePath } from "./path-utils.js";
 const state = { local: true, servedDiagnosticHashes: new Map() };
 function record(event, cwd, reason, pid, source) {
@@ -138,6 +139,33 @@ function startServer(cwd) {
     }
     const server = net.createServer((socket) => {
         socket.setEncoding("utf8");
+        // #3389: an ACCEPTED socket with no `error` listener rethrows, and
+        // `server.on("error")` below covers only the listener. A client that walks
+        // away while this incumbent is answering — every `requestWarmDiagnostics`
+        // timeout, schema refusal and validation refusal destroys its socket
+        // (`clients/mcp/ipc.ts:312`) — therefore turned a routine
+        // `read ECONNRESET` into an uncaught exception in THIS host, the same
+        // ending #3375 closed for an unbounded `data` handler. The handler does NOT
+        // tear the connection down: a real system failure has already destroyed the
+        // stream before this runs (measured: `destroyed` is true at entry), and an
+        // `error` emitted with no errno leaves a socket that is still answering
+        // (review round 1) — destroying that one would drop a live request. So the
+        // handler exists to keep the event catchable and to leave the peer's
+        // behavior visible in the ledger.
+        socket.on("error", (failure) => {
+            incrementDegradationCount({
+                // Subject is the errno, so one peer's repeated resets stay one row.
+                // No `?? "unknown"` fallback: `normalizeForLedger`
+                // (`clients/ledger-bounds.ts:29`) already maps a missing value to
+                // `"unknown"`, and a second copy of that rule here was a branch no
+                // mutation could red (#3389 review round 1, F3395-01) — an error
+                // emitted with no `code` is pinned end-to-end in
+                // `tests/clients/warm-attach-socket-error.test.ts`.
+                kind: "warm-attach-socket-error",
+                subject: failure.code,
+                reason: String(failure),
+            });
+        });
         // One-shot per connection (#1219 family): the same defect shape as the
         // MCP warm socket — clients write exactly one request and read one
         // reply, so a handler that kept re-reading the same buffered line
@@ -153,6 +181,11 @@ function startServer(cwd) {
                     socket.end(`${JSON.stringify({ error: String(error) })}\n`);
                 }
             })();
+        }, {
+            label: "warm-attach-server",
+            // #3383: an unterminated request line is answered like any other
+            // unusable request rather than buffered without a ceiling.
+            onOverflow: () => socket.end(`${JSON.stringify({ error: "warm request line exceeded the framing limit" })}\n`),
         }));
     });
     server.on("error", (error) => {
@@ -191,6 +224,20 @@ export async function tryWarmAttachedDiagnostics(file, content, timeoutMs, sourc
     }
     const result = await requestWarmDiagnostics(state.cwd, state.incumbentPid, file, content, timeoutMs);
     if (!result.available) {
+        // #3255 H1: a confirmed-alive incumbent whose endpoint has no listener is
+        // the upgrade-stranded shape — narrowing the workspace-id case fold
+        // renamed the socket, so a peer that registered before the upgrade is
+        // still serving the previous name. `promoteToLocal` alone left that in the
+        // latency log only; this is the entry `/lens-perf` renders. Bounded twice
+        // over: once per kind/subject by the ledger, and once per session by
+        // `promoteToLocal`'s latch, which returns early on every later call.
+        if (result.reason === "no-listener") {
+            recordDegradationOnce({
+                kind: "warm-ipc-endpoint-missing",
+                subject: diagnosticsIpcPathForCwd(state.cwd, state.incumbentPid),
+                reason: "the registry confirms this incumbent is alive but nothing is listening on its derived endpoint — if pi-lens was upgraded while it was running, restart it",
+            });
+        }
         promoteToLocal(result.reason);
     }
     else {
@@ -231,6 +278,18 @@ export function _resetWarmAttachForTests() {
     state.local = true;
     state.servedDiagnosticHashes.clear();
 }
+/**
+ * The live diagnostics server, exposed for tests (#3389 review round 1,
+ * F3395-01). The `error` handler on an ACCEPTED socket has exactly one input
+ * channel — an `error` event on that socket — and a test cannot reach the
+ * socket any other way: it is created by `net.createServer` inside the closure
+ * above, and Node's ESM namespace for `node:net` is not configurable, so the
+ * factory cannot be wrapped from a test either. A test observes the server's
+ * own `connection` event through this accessor; nothing in production reads it.
+ */
+export function _warmAttachServerForTests() {
+    return state.server;
+}
 export function _setWarmAttachForTests(cwd, incumbentPid) {
     state.cwd = path.resolve(cwd);
     state.incumbentPid = incumbentPid;

package/node_modules/pi-lens/dist/clients/widget-state.js

@@ -13,7 +13,7 @@ import { normalizeMessage } from "./finding-identity.js";
 import { freshnessFromMtime } from "./freshness.js";
 import { PAST_EOF_STALE_MARKER } from "./diagnostic-line-freshness.js";
 import { STALE_LINE_MARKER } from "./stale-marker.js";
-import { anchorsForDiagnostic, applyDispositions, getDisposition, registerWidgetDispositionReconciler, } from "./diagnostic-dispositions.js";
+import { anchorsForDiagnostic, applyDispositions, getDisposition, registerWidgetDispositionReconciler, strictAnchorSpan, strictAnchorSpansIn, } from "./diagnostic-dispositions.js";
 import { recordDegradationOnce } from "./degradation-ledger.js";
 /**
  * Canonical key for the `files` map (and `diagnosticsWriteGuard`) — #1020.
@@ -174,8 +174,23 @@ export function reconcileWidgetDisposition(cwd, target, _disposition, content) {
         if (!active.has(diagnostic) &&
             (entry?.disposition === "false-positive" ||
                 entry?.disposition === "suppress")) {
+            // #3183: stamp the strict anchor's own SPAN so the row's lifetime can
+            // later ask the mark instead of the file's mtime. `source` is the content
+            // the anchors above were derived from, so the span is the one the mark
+            // itself binds to. Only the STRICT arm has a span — a weak `suppress`
+            // mark hashes no line — and re-tagging always re-derives it, so a stale
+            // span from an earlier tag can never survive into a new disposition.
+            const { anchorSpan: _previousSpan, ...base } = diagnostic;
+            const span = entry.disposition === "false-positive"
+                ? strictAnchorSpan(source, diagnostic.line)
+                : undefined;
             return [
-                { ...diagnostic, disposition: entry.disposition, flagged: false },
+                {
+                    ...base,
+                    disposition: entry.disposition,
+                    flagged: false,
+                    ...(span === undefined ? {} : { anchorSpan: span }),
+                },
             ];
         }
         // #3158 retirement rule 3: a row the store holds ONLY because it was
@@ -186,7 +201,11 @@ export function reconcileWidgetDisposition(cwd, target, _disposition, content) {
         // currently present.
         if (diagnostic.suppressedRetained)
             return [];
-        const { disposition: _disposition, flagged: _flagged, ...baseDiagnostic } = diagnostic;
+        const { disposition: _disposition, flagged: _flagged, 
+        // #3183: a row that is no longer disposition-tagged has no mark to
+        // anchor, so its span goes with the tag — leaving it would exempt a LIVE
+        // row from the sweep's mtime gate.
+        anchorSpan: _anchorSpan, ...baseDiagnostic } = diagnostic;
         return entry?.disposition === "flagged"
             ? [{ ...baseDiagnostic, flagged: true }]
             : [baseDiagnostic];
@@ -538,6 +557,16 @@ function normalizeDiagnostics(filePath, diagnostics, observedTs) {
  * file — so it would discriminate nothing. `normalizeMessage` is the shared
  * derivation from `clients/finding-identity.ts` that the anchor uses, imported
  * rather than re-spelled.
+ *
+ * #3183: this identity is OCCURRENCE-BLIND, and for a STRICT (`false-positive`)
+ * row that is not enough on its own. Two findings of one rule with identical
+ * messages on different lines collapse onto it, so a scan reporting only the
+ * UNMARKED one matched the marked row and replaced it — the chip lost a mark
+ * that was still applying. A collision is therefore resolved by the second half
+ * of {@link WidgetDiagnostic.anchorSpan}'s contract, in `retainSuppressedRows`:
+ * only a colliding incoming finding sitting ON the marked line is the same
+ * finding. That test, not this one, is what keeps the round-2 F2 case above
+ * closed — the marked line's TEXT moved, so its span still matches.
  */
 function retentionIdentity(d) {
     return JSON.stringify([
@@ -546,6 +575,39 @@ function retentionIdentity(d) {
         normalizeMessage(d.message),
     ]);
 }
+/** `filePath`'s current content, or `undefined` when it cannot be read. */
+function readContentOrUndefined(filePath) {
+    try {
+        return readFileSync(filePath, "utf8");
+    }
+    catch {
+        // Only reached once this module has established there IS a span-carrying row
+        // to ask about, so the record is bounded by that population — and worth
+        // making: with no content both callers fall back to the pre-#3183 rules (the
+        // per-entry mtime gate, the coarse retention identity), which is the
+        // conservative direction but can retire a mark that still stands.
+        recordDegradationOnce({
+            kind: "widget-mark-anchor-unreadable",
+            subject: filePath,
+            reason: "the marked file could not be read, so its suppressed rows fall back to the file-mtime retirement gate and the footer chip may under-count it",
+        });
+        return undefined;
+    }
+}
+/**
+ * {@link strictAnchorSpansIn} over `filePath`'s current content (#3183), or
+ * `undefined` when it cannot be read.
+ *
+ * Synchronous in both callers, matching `applyCachedDispositions`
+ * (`tools/lens-diagnostics.ts`) — the seam that asks the very same question on
+ * the very same read path, with `statSync`/`readFileSync`. An async read here
+ * would add two unbounded awaits to a module a registered hook handler imports
+ * directly (`tests/config/hook-await-bounds.test.ts`) for no behavioural gain.
+ */
+function readAnchorSpans(filePath) {
+    const content = readContentOrUndefined(filePath);
+    return content === undefined ? undefined : strictAnchorSpansIn(content);
+}
 /**
  * #3158: carry the record's disposition-tagged rows across a whole-replace
  * write when the incoming set no longer reports them, so a `false-positive` /
@@ -564,8 +626,46 @@ function retainSuppressedRows(previous, incoming, filePath) {
     const tagged = previous.filter((d) => d.disposition !== undefined);
     if (tagged.length === 0)
         return incoming;
-    const reported = new Set(incoming.map(retentionIdentity));
-    const retained = tagged.filter((d) => !reported.has(retentionIdentity(d)));
+    const reported = new Map();
+    for (const d of incoming) {
+        const id = retentionIdentity(d);
+        const bucket = reported.get(id);
+        if (bucket)
+            bucket.push(d);
+        else
+            reported.set(id, [d]);
+    }
+    // #3183: the ONE file read on this path, and only for the state the coarse
+    // identity genuinely cannot resolve — a strict-anchored row whose identity an
+    // incoming finding collides with. Every other write (no marks at all, a mark
+    // with no collision, a weak `suppress` mark) stays zero-I/O, which is what
+    // keeps this off the per-edit `recordDiagnostics` cost.
+    const content = tagged.some((d) => d.anchorSpan !== undefined && reported.has(retentionIdentity(d)))
+        ? readContentOrUndefined(filePath)
+        : undefined;
+    const spans = content === undefined ? undefined : strictAnchorSpansIn(content);
+    const retained = tagged.filter((d) => {
+        const collisions = reported.get(retentionIdentity(d));
+        // Nothing re-reported this finding, so retention rule 2 has nothing to say.
+        if (collisions === undefined)
+            return true;
+        // No span to ask (a weak `suppress` mark, or a row from an older build), or
+        // the file is unreadable: fall back to the pre-#3183 coarse rule. The safe
+        // direction is to UNDER-count, never to leave a phantom duplicate standing
+        // beside a live finding.
+        if (d.anchorSpan === undefined || spans === undefined)
+            return false;
+        // The mark stopped applying — its line is gone from the file — so the
+        // colliding finding IS this one, re-reported now that the filter no longer
+        // drops it (retirement rule 2, and the same verdict the sweep reaches).
+        if (!spans.has(d.anchorSpan))
+            return false;
+        // The mark still applies. Only a collision sitting ON the marked line is
+        // the same finding (its line number may have shifted under an edit — #3158
+        // round 2 F2); any other is a DIFFERENT occurrence this strict anchor never
+        // covered, and replacing the row with it loses a live mark (#3183).
+        return !collisions.some((i) => strictAnchorSpan(content, i.line) === d.anchorSpan);
+    });
     if (retained.length > MAX_RETAINED_SUPPRESSED_PER_FILE) {
         // Freshest observations win the cap. One record per FILE, never one per
         // dropped row (AGENTS.md "bounded observability"): the chip under-counts
@@ -886,13 +986,24 @@ export async function reconcileStaleWidgetFiles() {
         // at dispatch/integration.ts). A missing per-entry stamp (a migrated
         // pre-#1186 record) inherits the record's `touchedAt`. Tolerance matches
         // the Windows host-clock skew rationale above.
-        const survivors = rec.allDiagnostics.filter((d) => {
-            const v = freshnessFromMtime({
-                mtimeMs,
-                referenceMs: d.observedAt ?? rec.touchedAt,
-            });
-            return v.verdict !== "stale";
-        });
+        const mtimeStale = (d) => freshnessFromMtime({
+            mtimeMs,
+            referenceMs: d.observedAt ?? rec.touchedAt,
+        }).verdict === "stale";
+        // #3183: a disposition-tagged row carrying a strict anchor span is gated
+        // on its MARK, not on the file's mtime (retirement rule 1 — see
+        // `WidgetDiagnostic.suppressedRetained`): it survives while the marked
+        // LINE is still somewhere in the file, and is retired when it is not.
+        // The content read is gated on a span-carrying row the mtime gate WOULD
+        // have dropped — the only state where reading can change an outcome — so
+        // the debounced render sweep stays off the disk both for a file with no
+        // marks and for a marked file nothing has touched.
+        const spans = rec.allDiagnostics.some((d) => d.anchorSpan !== undefined && mtimeStale(d))
+            ? readAnchorSpans(rec.filePath)
+            : undefined;
+        const survivors = rec.allDiagnostics.filter((d) => d.anchorSpan !== undefined && spans !== undefined
+            ? spans.has(d.anchorSpan)
+            : !mtimeStale(d));
         if (survivors.length === rec.allDiagnostics.length) {
             return { mapKey, action: "keep" }; // nothing stale
         }
@@ -1185,18 +1296,38 @@ export function scheduleStaleReconcile() {
  * Used by lens_diagnostics tool (mode: "all"). Exposes the FULL per-file
  * diagnostic set — decoupled from the widget's display cap — so the agent sees
  * everything, not just the 12 the TUI keeps for rendering.
+ *
+ * #3183: "everything" means every row a live scan stands behind.
+ * `disposition`-tagged rows are the store's own bookkeeping for a mark — the
+ * scan that produced this record did not report them — and they are excluded
+ * here. That is the same predicate `countDiagnostics` and `isBlocking` have
+ * always used, so this makes the projected array agree with the counts beside
+ * it; before #3183 the array disagreed, and once retirement rule 1 let a row
+ * outlive the file's mtime, `applyCachedDispositions` reached it in the
+ * WEAK-fallback branch — which can never match a STRICT `false-positive`
+ * anchor — and `mode=all` served a marked finding as a live warning (#3158 AC3).
+ * The exclusion lives HERE, at the one projection every cache-only surface and
+ * the mode=full merge read, rather than as a second disposition rule inside
+ * `summarizeDiagnostics`' tally: that tally still skips `stale` only, and the
+ * disposition filter still reaches it pre-applied through the shared
+ * `applyCachedDispositions` seam.
+ *
+ * Deliberately NOT applied to {@link getFileDiagnostics}, the per-file read:
+ * `reconcileWidgetDisposition` needs the tagged rows to enforce retirement
+ * rule 3, and `lens_diagnostic_mark`'s cross-check re-marks through them.
  */
 export function getFileDiagnosticSummaries() {
     return [...files.values()].map((rec) => {
         applyPastEofGate(rec);
+        const live = rec.allDiagnostics.filter((d) => d.disposition === undefined);
         return {
             filePath: rec.filePath,
             blocking: rec.diagnosticCounts.blocking,
             errors: rec.diagnosticCounts.errors,
             warnings: rec.diagnosticCounts.warnings,
-            advisories: countAdvisories(rec.allDiagnostics),
+            advisories: countAdvisories(live),
             hasFinalSnapshot: rec.hasFinalDiagnosticsSnapshot,
-            diagnostics: rec.allDiagnostics.map((d) => ({ ...d })),
+            diagnostics: live.map((d) => ({ ...d })),
         };
     });
 }

package/node_modules/pi-lens/dist/clients/workspace-topology.js

@@ -39,7 +39,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { PROJECT_CONFIG_BASENAMES } from "./config-locations.js";
+import { PROJECT_CONFIG_BASENAMES, isResolvedGlobalConfigPath, } from "./config-locations.js";
 import { logLatency } from "./latency-logger.js";
 import { isAtOrAboveHomeDir, nameMatchesMarkerGlob, walkUpDirs, } from "./path-utils.js";
 /** Depth cap on any upward marker walk — mirrors `findNearestMarkerRoot`'s bound. */
@@ -214,9 +214,53 @@ export function getDirectoryMarkers(dir) {
 function walkCacheKey(startDir, markerKey) {
     return `${path.resolve(startDir)}\0${markerKey}`;
 }
-function walkStillFresh(dirMtimes) {
+export function dirMtimesStillFresh(dirMtimes) {
     return dirMtimes.every(({ dir, mtimeMs }) => safeDirMtimeMs(dir) === mtimeMs);
 }
+/**
+ * Async arm of `dirMtimesStillFresh` — same records, same comparison, stats
+ * issued in parallel. It exists for the async marker walk in
+ * `clients/lsp/server.ts`'s `NearestRoot`, whose own marker probes are
+ * `fs/promises` and which runs on the per-file LSP touch path: a `statSync` per
+ * directory there would block the event loop the walk deliberately keeps free.
+ * Both arms live here so "is this recorded walk still current" has one owner
+ * (#3412).
+ *
+ * Written with promise combinators rather than `await`, along with the two
+ * readers below, so the ONLY place that waits on these stats is the caller's
+ * `await bounded(...)` — a hook-path await that a later editor cannot leave
+ * unbounded, instead of an inner await bounded only by a registry admission
+ * (#3412 review round 1, M-3421-02).
+ */
+export function dirMtimesStillFreshAsync(dirMtimes) {
+    return Promise.all(dirMtimes.map(({ dir }) => dirMtimeMsAsync(dir))).then((current) => dirMtimes.every(({ mtimeMs }, index) => current[index] === mtimeMs));
+}
+/**
+ * Current mtime of `dir`, or `-1` when it cannot be stat'ed — the async arm of
+ * `safeDirMtimeMs`. A recorder and `dirMtimesStillFreshAsync` MUST read through
+ * the same function so the absent-directory sentinel is the same value on both
+ * sides: `prisma/` not existing yet is a recordable state, and the record must
+ * compare unequal once it is created (#3412).
+ */
+function dirMtimeMsAsync(dir) {
+    return fs.promises.stat(dir).then((stats) => stats.mtimeMs, () => -1);
+}
+/** One freshness record per directory, read in parallel (#3412). */
+export function dirMtimeRecordsAsync(dirs) {
+    return Promise.all(dirs.map((dir) => dirMtimeMsAsync(dir).then((mtimeMs) => ({ dir, mtimeMs }))));
+}
+/**
+ * Records for directories whose mtime could NOT be read — because the caller's
+ * bound fired, so the answer is unknown rather than absent. `NaN` compares
+ * unequal to every mtime including itself, so an entry carrying one of these
+ * can never be served: the walk's answer is still returned, it is simply not
+ * memoized. Unknown must never be spelled as a number a directory could
+ * actually have, and dropping the directory from the signature (recording
+ * nothing) would hide every later change in it (#3412 review round 1, S9).
+ */
+export function unknownDirMtimeRecords(dirs) {
+    return dirs.map((dir) => ({ dir, mtimeMs: Number.NaN }));
+}
 /**
  * Shared core of the two nearest-marker walkers below: the cache check, the
  * home-guarded/depth-capped upward loop, per-directory mtime recording, and
@@ -229,7 +273,7 @@ function walkStillFresh(dirMtimes) {
 function walkToNearestMatch(startDir, cacheSuffix, matches, capMetadata, homeDir) {
     const key = walkCacheKey(startDir, cacheSuffix);
     const cached = walkCache.get(key);
-    if (cached && walkStillFresh(cached.dirMtimes)) {
+    if (cached && dirMtimesStillFresh(cached.dirMtimes)) {
         touchWalk(key, cached);
         return cached.dir;
     }
@@ -339,11 +383,21 @@ export function findNearestDirWithAnyBasename(startDir, basenames, homeDir = os.
  * `.pi-lens.json`/`pi-lens.json` directly IN `dir` — no upward walk. The
  * shared-index equivalent of `project-lens-config.ts`'s old private
  * `findPiLensConfigInDir` probe loop.
+ *
+ * A candidate that IS the resolved global config path is refused
+ * (global-config-location PR, refs #2457): the global tier reads that file by
+ * absolute path, and discovering it here a second time made the nested ignore
+ * layering full-validate it and warn that its global-only keys are "not
+ * honored in a project config" — including the notice advising the user to
+ * set them in the very file being ignored. The refusal is observable through
+ * the marker staying absent, the same shape as a directory with no marker.
  */
 export function findPiLensConfigMarkerInDir(dir) {
     const markers = getDirectoryMarkers(dir);
     if (!markers.piLensConfigPath)
         return undefined;
+    if (isResolvedGlobalConfigPath(markers.piLensConfigPath))
+        return undefined;
     const stat = (() => {
         try {
             return fs.statSync(markers.piLensConfigPath);

package/node_modules/pi-lens/dist/clients/zizmor-config.js

@@ -157,10 +157,12 @@ function classifyGhTokenFailure(res, hostStallMs) {
         classifiedBy: "caller",
     };
 }
-async function deriveGhCliToken() {
+async function deriveGhCliToken(consumer) {
     const sampler = startHostStallSampler();
     const startedAt = Date.now();
-    // Best-effort: a missing/unauthenticated `gh` just leaves zizmor offline.
+    // Best-effort: a missing/unauthenticated `gh` leaves the requesting
+    // consumer without a derived token; only the zizmor wrapper turns that into
+    // an offline-mode degradation.
     // ignoreAmbientSignal so a mid-turn Esc can't silently drop the server into
     // offline mode; short timeout so a wedged `gh` never stalls the warm spawn.
     // safeSpawnAsync never rejects (every failure resolves into `res`), so no
@@ -176,7 +178,7 @@ async function deriveGhCliToken() {
         if (token.length > 0) {
             ghTokenLatch.noteAvailable();
             logAvailabilityDecision({
-                tool: "zizmor-gh-token",
+                tool: consumer === "zizmor" ? "zizmor-gh-token" : "github-token",
                 verdict: "available",
                 outcome: "success",
                 cause: "ok",
@@ -195,13 +197,13 @@ async function deriveGhCliToken() {
         // regardless of whether `token` was empty, so the record claimed the
         // online audits ran while zizmor was actually about to launch offline
         // — the #1535 silence moved into the telemetry instead of being fixed.
-        return recordGhTokenUnavailable({
+        return recordGhTokenUnavailable(consumer, {
             outcome: "non-installable",
             cause: "empty-result",
             classifiedBy: "caller",
         }, elapsedMs, hostStallMs);
     }
-    return recordGhTokenUnavailable(classifyGhTokenFailure(res, hostStallMs), elapsedMs, hostStallMs);
+    return recordGhTokenUnavailable(consumer, classifyGhTokenFailure(res, hostStallMs), elapsedMs, hostStallMs);
 }
 /**
  * Shared tail for every "no token" verdict: latches (or cools down) the
@@ -209,13 +211,13 @@ async function deriveGhCliToken() {
  * and logs the decision. Centralized so the empty-answer and failure paths
  * can't drift on which fields get set.
  */
-function recordGhTokenUnavailable({ outcome, cause, classifiedBy }, elapsedMs, hostStallMs) {
+function recordGhTokenUnavailable(consumer, { outcome, cause, classifiedBy }, elapsedMs, hostStallMs) {
     const retryAfterMs = ghTokenLatch.noteUnavailable(outcome, cause);
-    if (outcome === "transient") {
+    if (consumer === "zizmor" && outcome === "transient") {
         recordZizmorOfflineDegradation(`gh auth token probe ${cause}; running offline until the next zizmor start (retry allowed in ${Math.round(retryAfterMs / 1000)}s)`);
     }
     logAvailabilityDecision({
-        tool: "zizmor-gh-token",
+        tool: consumer === "zizmor" ? "zizmor-gh-token" : "github-token",
         verdict: "unavailable",
         outcome,
         cause,
@@ -278,14 +280,25 @@ export async function resolveZizmorGitHubToken() {
     // Respect an explicit offline request — never derive a token then.
     if (process.env.ZIZMOR_OFFLINE)
         return undefined;
-    const fromEnv = process.env.ZIZMOR_GITHUB_TOKEN ||
-        process.env.GH_TOKEN ||
-        process.env.GITHUB_TOKEN;
+    return resolveGitHubToken(["ZIZMOR_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"], { consumer: "zizmor" });
+}
+/**
+ * Resolve a GitHub token for an API client. Explicit environment variables are
+ * checked in the caller's order; when none is present, reuse the bounded,
+ * session-reset `gh auth token` resolver above rather than spawning once per
+ * request. The returned token is ephemeral and callers must not persist or
+ * send it to non-API hosts.
+ */
+export async function resolveGitHubToken(envKeys = ["GITHUB_TOKEN", "GH_TOKEN"], options = {}) {
+    const consumer = options.consumer ?? "github-api";
+    const fromEnv = envKeys.map((key) => process.env[key]).find(Boolean);
     if (fromEnv)
         return fromEnv;
     const memo = ghTokenLatch.read();
     if (memo !== null) {
-        if (memo === false && ghTokenLatch.getOutcome() === "transient") {
+        if (consumer === "zizmor" &&
+            memo === false &&
+            ghTokenLatch.getOutcome() === "transient") {
             // Served straight from the still-cooling latch: no new probe runs,
             // so `deriveGhCliToken`'s own logging never fires. Without this, once
             // the cooldown ladder crosses zizmor's own respawn cadence (bounded
@@ -322,6 +335,6 @@ export async function resolveZizmorGitHubToken() {
         }
         return memo ? cachedToken : undefined;
     }
-    cachedToken = await deriveGhCliToken();
+    cachedToken = await deriveGhCliToken(consumer);
     return cachedToken;
 }