@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/spawn-outcome.js

@@ -1,22 +1,97 @@
+import { LEDGER_FIELD_MAX } from "../../../ledger-bounds.js";
+/**
+ * The first non-empty line of a tool's output, bounded.
+ *
+ * Replaces six hand-rolled copies that spelled the same idea two ways —
+ * `text.trim().split("\n")[0]` and `(text ?? "").trim().split("\n")[0] ||
+ * fallback` — with differing (or absent) length caps. Two behaviours the
+ * copies got wrong and this does not: a leading blank line no longer yields an
+ * empty "first line", and `\r\n` output no longer keeps its carriage return.
+ *
+ * Returns `""` when the text is empty or all-whitespace, so callers keep using
+ * `firstOutputLine(x) || fallback`.
+ */
+export function firstOutputLine(text, max = LEDGER_FIELD_MAX) {
+    for (const line of String(text ?? "").split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed;
+    }
+    return "";
+}
+/**
+ * Decide whether a tool ran, and if not, why (#1816).
+ *
+ * The defect this closes (the #1736 class): a runner that reads only its
+ * parsed diagnostics reports a CLEAN file whenever the parse yields nothing —
+ * including when the tool exited non-zero on an unknown flag, was killed by a
+ * signal, or never spawned at all. An empty result must distinguish clean from
+ * errored.
+ *
+ * Classification order, most specific first:
+ *   1. `result.error` or a signal — the process never completed. `did-not-run`.
+ *   2. `status === null` with no error — no exit status ever arrived, so no
+ *      analysis can be claimed. `did-not-run`.
+ *   3. `reportMissing` — an artifact tool wrote no report. Nonzero exit means
+ *      `report-missing`; exit 0 means a genuinely clean run that had nothing
+ *      to write.
+ *   4. A nonzero status outside the caller's declared `ran` table.
+ *      `rejected-invocation`.
+ *   5. A nonzero status with nothing to parse. `did-not-run` — a tool that
+ *      analysed the file says SOMETHING, so silence plus failure is evidence
+ *      it never got that far.
+ * Everything else ran.
+ *
+ * Note what is deliberately NOT a non-ran path: a nonzero status WITH output
+ * and no contradicting table. Most linters exit non-zero precisely because
+ * they found something, and their findings are on stdout.
+ */
+export function classifyRunOutcome(input) {
+    const { result, exitCodes, reportMissing } = input;
+    const status = result.status ?? null;
+    const signal = result.signal ?? null;
+    const output = input.output ?? result.stdout;
+    const base = {
+        status,
+        signal,
+        firstOutputLine: firstOutputLine(result.stderr) ||
+            firstOutputLine(result.stdout) ||
+            firstOutputLine(result.error?.message),
+    };
+    if (result.error || signal)
+        return { kind: "did-not-run", ...base };
+    if (status === null)
+        return { kind: "did-not-run", ...base };
+    if (reportMissing) {
+        return status === 0
+            ? { kind: "ran", ...base }
+            : { kind: "report-missing", ...base };
+    }
+    if (status !== 0 && exitCodes && !exitCodes.ran.includes(status)) {
+        return { kind: "rejected-invocation", ...base };
+    }
+    if (status !== 0 && !output?.trim()) {
+        return { kind: "did-not-run", ...base };
+    }
+    return { kind: "ran", ...base };
+}
 /**
  * True when a tool both failed and produced nothing to parse — it never got as
  * far as linting the file. Callers map this to `skipped`, never `succeeded`.
  *
- * Guarding on `result.error` alone covers only half of it: safe-spawn sets
- * `error` for spawn/timeout/signal failures and resolves a NORMAL exit with no
- * `error` at any status (see `SpawnResult.failure` — "nonzero exit statuses are
- * not spawn failures"). An unknown subcommand, a rejected flag, or a config
- * that fails to load exits non-zero with the message on stderr and an empty
- * stdout, so an `error`-only guard falls through, parses "" into zero
- * diagnostics, and reports a clean file that nothing ever checked.
- *
- * Tools that exit non-zero *because* they found something are unaffected: their
- * findings are on stdout, so the output half of the test is false.
+ * Kept as its own export because callers outside the dispatch runners use it
+ * (`dead-code-client.ts`, `knip-client.ts`). It now DELEGATES to
+ * `classifyRunOutcome` rather than restating the rule, but keeps its exact
+ * historical semantics: the `!output.trim()` conjunct stays here so a spawn
+ * error that still produced partial output keeps reaching the parser, which is
+ * what today's callers depend on. `classifyRunOutcome` is the stricter,
+ * outcome-typed reading; migrate callers to it deliberately, not by accident.
  *
  * `output` defaults to stdout. Runners that parse stderr too pass the exact
  * string they are about to hand the parser, so "nothing to parse" means both
  * streams rather than just one.
  */
 export function spawnFailedWithNoOutput(result, output = result.stdout) {
-    return (Boolean(result.error) || result.status !== 0) && !output?.trim();
+    return (classifyRunOutcome({ result, output }).kind !== "ran" && !output?.trim());
 }

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/tool-failure.js

@@ -0,0 +1,72 @@
+/**
+ * One wording for a tool that produced no usable result, and the runner gate
+ * that emits it to the degradation ledger (#1816).
+ */
+import { incrementDegradationCount } from "../../../degradation-ledger.js";
+import { truncateForLedger } from "../../../ledger-bounds.js";
+import { classifyRunOutcome, firstOutputLine, } from "./spawn-outcome.js";
+/**
+ * One wording for "this tool did not produce a usable result" (#1816).
+ *
+ * Before this, five reason builders spelled the same sentence five ways and
+ * twelve sites truncated with their own literal, and NONE of them named the
+ * signal — so a SIGKILLed tool read exactly like a clean exit 0. The wording
+ * here is fixed, the truncation is the ledger's own `LEDGER_FIELD_MAX` policy
+ * applied once at the end, and the signal is always named when present.
+ *
+ * Shape: `tool (k=v, k=v) <what happened> with <what was missing>: <detail>`
+ */
+export function formatToolFailure(input) {
+    const entries = Object.entries(input.fields ?? {}).filter(([, value]) => value !== undefined && value !== "");
+    const identity = entries.length
+        ? `${input.tool} (${entries.map(([key, value]) => `${key}=${value}`).join(", ")})`
+        : input.tool;
+    // A signal is the strongest available explanation, so it displaces the exit
+    // status rather than sitting beside a `null` one.
+    const what = input.signal
+        ? `was killed by ${input.signal}`
+        : input.status === null
+            ? "did not run (spawn failure)"
+            : `exited ${input.status}`;
+    const missing = input.reportMissing ? "no report file" : "no output";
+    const detail = firstOutputLine(input.stderr) || firstOutputLine(input.stdout) || "no stderr";
+    return truncateForLedger(`${identity} ${what} with ${missing}: ${detail}`);
+}
+/**
+ * `formatToolFailure` fed straight from a `classifyRunOutcome` verdict — the
+ * path every migrated runner takes, so the outcome and the wording can never
+ * disagree about the status or the signal.
+ */
+export function formatRunOutcomeFailure(tool, outcome, fields) {
+    return formatToolFailure({
+        tool,
+        status: outcome.status,
+        signal: outcome.signal,
+        stderr: outcome.firstOutputLine,
+        reportMissing: outcome.kind === "report-missing",
+        fields: { outcome: outcome.kind, ...fields },
+    });
+}
+/**
+ * The migrated runners' one call: classify the spawn, and when the tool did
+ * NOT run, record a bounded `runner-empty-result` row and hand back the
+ * `skipped` verdict. Returns `null` when the tool ran, meaning "carry on and
+ * parse".
+ *
+ * `incrementDegradationCount` keeps the record bounded — one latest-reason
+ * entry per (kind, subject) with an exact event tally — so a permanently
+ * broken tool costs one ledger row, not one per dispatched file. `subject` is
+ * the tool id, which is the discriminating identity a reader needs: WHICH tool
+ * is silently contributing nothing.
+ */
+export function skipUnlessToolRan(tool, input, fields) {
+    const outcome = classifyRunOutcome(input);
+    if (outcome.kind === "ran")
+        return null;
+    incrementDegradationCount({
+        kind: "runner-empty-result",
+        subject: tool,
+        reason: formatRunOutcomeFailure(tool, outcome, fields),
+    });
+    return { status: "skipped", diagnostics: [], semantic: "none" };
+}

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/toolchain-availability.js

@@ -0,0 +1,106 @@
+/**
+ * Shared toolchain-availability lifecycle (#1476 Sonar follow-up).
+ *
+ * `candidate-probe.ts` factored out the PATH sweep the Go and Rust clients ran,
+ * but the LIFECYCLE around it stayed written twice: the transient-aware latch,
+ * the in-flight dedupe that keeps concurrent first-time callers to one sweep,
+ * the path memo, and the two `availability_decision` records. Two copies of one
+ * rule is how #1467's fix missed seven sites, so the rule lives here once and
+ * each client contributes only its configuration.
+ *
+ * Callers keep their own public method names — `isGoAvailableAsync`,
+ * `findCargoPathAsync` — because other modules call them; only the body moves.
+ */
+import { createAvailabilityLatch, logAvailabilityDecision, } from "./availability-policy.js";
+import { probeAvailabilityCandidates } from "./candidate-probe.js";
+/**
+ * Own one toolchain's availability: sweep the platform candidate list, memoize
+ * the path that answered, and park the verdict behind the shared latch so a
+ * timed-out probe expires instead of latching "the toolchain is not installed"
+ * for the life of the process.
+ */
+export function createToolchainAvailability(config) {
+    const availabilityLatch = createAvailabilityLatch();
+    let toolPath = null;
+    /** Classification of the candidate sweep, for the retry decision. */
+    let sweepSawTransient = false;
+    let sweepTransientCause = "probe-timeout";
+    let sweepHostStallMs = 0;
+    /** What the last classified candidate returned, for the decision record. */
+    let sweepEvidence;
+    let ensureInFlight = null;
+    async function findPath() {
+        if (toolPath)
+            return toolPath;
+        const paths = process.platform === "win32" ? config.windowsPaths : config.unixPaths;
+        const sweep = await probeAvailabilityCandidates(paths, config.probeArgs, config.budgetMs);
+        sweepSawTransient = sweep.sawTransient;
+        sweepTransientCause = sweep.transientCause;
+        sweepHostStallMs = sweep.hostStallMs;
+        sweepEvidence = sweep.evidence;
+        if (sweep.foundPath)
+            toolPath = sweep.foundPath;
+        return sweep.foundPath;
+    }
+    async function resolveAvailability() {
+        const startedAt = Date.now();
+        const found = (await findPath()) !== null;
+        if (found) {
+            availabilityLatch.noteAvailable();
+            config.log(`${config.label} found: ${toolPath}`);
+            logAvailabilityDecision({
+                tool: config.tool,
+                verdict: "available",
+                outcome: "success",
+                cause: "ok",
+                elapsedMs: Date.now() - startedAt,
+                latched: true,
+                hostStallMs: sweepHostStallMs,
+                budgetMs: config.budgetMs,
+                classifiedBy: "probe",
+                ...(sweepEvidence !== undefined && { evidence: sweepEvidence }),
+            });
+            return true;
+        }
+        // A timed-out version probe is evidence about this moment, not about
+        // whether the toolchain is installed; it expires instead of latching.
+        const outcome = sweepSawTransient ? "transient" : "missing";
+        const cause = sweepSawTransient ? sweepTransientCause : "not-found";
+        const retryAfterMs = availabilityLatch.noteUnavailable(outcome, cause);
+        logAvailabilityDecision({
+            tool: config.tool,
+            verdict: "unavailable",
+            outcome,
+            cause,
+            elapsedMs: Date.now() - startedAt,
+            latched: outcome !== "transient",
+            hostStallMs: sweepHostStallMs,
+            ...(retryAfterMs > 0 && { retryAfterMs }),
+            budgetMs: config.budgetMs,
+            // Derived from the sweep's own candidate probes, and carrying what the
+            // last of them returned (#1500).
+            classifiedBy: "probe",
+            ...(sweepEvidence !== undefined && { evidence: sweepEvidence }),
+        });
+        return false;
+    }
+    async function isAvailable() {
+        // `read()` returns null when the last verdict was transient and its
+        // cooldown expired, which re-enters the candidate sweep (#1476).
+        const memo = availabilityLatch.read();
+        if (memo !== null)
+            return memo;
+        // Now that a verdict can expire, concurrent callers arriving just after a
+        // cooldown must share ONE sweep rather than each spawning their own.
+        if (ensureInFlight)
+            return ensureInFlight;
+        ensureInFlight = resolveAvailability();
+        try {
+            return await ensureInFlight;
+        }
+        finally {
+            ensureInFlight = null;
+        }
+    }
+    return { findPath, isAvailable };
+}

package/node_modules/pi-lens/dist/clients/dispatch/runners/vale.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { safeSpawnAsync } from "../../safe-spawn.js";
 import { PRIORITY } from "../priorities.js";
 import { createAvailabilityChecker, resolveToolCommandWithInstallFallback, } from "./utils/runner-helpers.js";
+import { skipUnlessToolRan } from "./utils/tool-failure.js";
 const vale = createAvailabilityChecker("vale", ".exe");
 /**
  * Check for a .vale.ini config file in cwd or parent dirs.
@@ -89,6 +90,14 @@ const valeRunner = {
             return { status: "skipped", diagnostics: [], semantic: "none" };
         // Vale exits 0 even on findings, non-zero only on errors
         const result = await safeSpawnAsync(cmd, ["--output", "JSON", ctx.filePath], { cwd, timeout: 15000 });
+        // #1816: this runner read `result.status` zero times, so a Vale that
+        // rejected its config exited nonzero with an empty stdout, parsed to
+        // zero alerts, and reported clean prose. No exit-code table: Vale's
+        // nonzero codes vary with --minAlertLevel, so the conservative
+        // nothing-to-parse rule is the only safe discriminator here.
+        const skipped = skipUnlessToolRan("vale", { result });
+        if (skipped)
+            return skipped;
         const raw = result.stdout || "";
         const diagnostics = parseValeOutput(raw, ctx.filePath);
         if (diagnostics.length === 0) {

package/node_modules/pi-lens/dist/clients/dispatch/runners/yamllint.js

@@ -2,6 +2,7 @@ import { safeSpawnAsync } from "../../safe-spawn.js";
 import { getLinterPolicyForCwd, hasYamllintConfig } from "../../tool-policy.js";
 import { PRIORITY } from "../priorities.js";
 import { createAvailabilityChecker, resolveToolCommandWithInstallFallback, } from "./utils/runner-helpers.js";
+import { skipUnlessToolRan } from "./utils/tool-failure.js";
 const yamllint = createAvailabilityChecker("yamllint", ".exe");
 export { hasYamllintConfig };
 function parseYamllintParsable(raw, filePath) {
@@ -55,7 +56,23 @@ const yamllintRunner = {
         const result = await safeSpawnAsync(cmd, ["-f", "parsable", ctx.filePath], {
             timeout: 15000,
         });
-        const diagnostics = parseYamllintParsable(`${result.stdout ?? ""}${result.stderr ?? ""}`, ctx.filePath);
+        // #1816: this runner read `result.status` zero times, so a yamllint
+        // that rejected its config reported a clean YAML file.
+        //
+        // No exit-code table: yamllint returns 2 both for "warnings only" and
+        // for an argparse usage error, so declaring 2 a rejection would discard
+        // real warnings. The discriminator is the STREAM instead. `-f parsable`
+        // writes findings to stdout and nothing else; stderr carries usage text
+        // and tracebacks. So the gate judges "nothing to parse" on stdout alone,
+        // while the parser still reads both streams.
+        const raw = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+        const skipped = skipUnlessToolRan("yamllint", {
+            result,
+            output: result.stdout,
+        });
+        if (skipped)
+            return skipped;
+        const diagnostics = parseYamllintParsable(raw, ctx.filePath);
         if (diagnostics.length === 0) {
             return { status: "succeeded", diagnostics: [], semantic: "none" };
         }

package/node_modules/pi-lens/dist/clients/dispatch/runners/zig-check.js

@@ -24,7 +24,9 @@ function parseZigOutput(raw, filePath) {
             line: Number.parseInt(lineStr, 10) || 1,
             column: Number.parseInt(colStr, 10) || 1,
             severity,
-            semantic: severity === "error" ? "blocking" : "warning",
+            // `zig build-exe <file>` does not load build.zig module/import context.
+            // Its findings are useful evidence, but cannot prove a project blocker.
+            semantic: "warning",
             tool: "zig",
             rule: `zig-${level}`,
             fixable: false,
@@ -82,7 +84,7 @@ const zigCheckRunner = {
         return {
             status: hasErrors ? "failed" : "succeeded",
             diagnostics,
-            semantic: hasErrors ? "blocking" : "warning",
+            semantic: "warning",
         };
     },
 };

package/node_modules/pi-lens/dist/clients/disposition-publish.js

@@ -24,7 +24,7 @@
 import { logBusEvent } from "./bus-events-logger.js";
 import { isBusPublishEnabled } from "./bus-publish.js";
 import { normalizeFilePath } from "./path-utils.js";
-import { createLiveBusEmitter, recordStaleBusFailure, } from "./live-bus-emitter.js";
+import { createLiveBusEmitter, recordStaleBusFailure, resolveLiveBusEmitter, } from "./live-bus-emitter.js";
 export const BUS_DISPOSITION_EVENT = "pilens:diagnostic:disposition";
 export const BUS_DISPOSITION_VERSION = 1;
 const liveEmitter = createLiveBusEmitter();
@@ -67,8 +67,13 @@ export function publishDisposition(args) {
         }
         return;
     }
-    const busEmit = liveEmitter.get();
-    if (!busEmit) {
+    const resolution = resolveLiveBusEmitter(liveEmitter, () => ({
+        event: BUS_DISPOSITION_EVENT,
+        cwd: normalizeFilePath(args.cwd),
+    }));
+    if (resolution.outcome === "stale-session")
+        return;
+    if (resolution.outcome === "unwired") {
         if (!hasLoggedUnwired) {
             hasLoggedUnwired = true;
             logBusEvent({
@@ -79,6 +84,7 @@ export function publishDisposition(args) {
         }
         return;
     }
+    const busEmit = resolution.emit;
     try {
         const payload = {
             v: BUS_DISPOSITION_VERSION,
@@ -106,6 +112,7 @@ export function publishDisposition(args) {
             outcome: "emit_failed",
             cwd: normalizeFilePath(args.cwd),
             error: String(err),
+            ctxSource: resolution.ctxSource,
         });
         if (!hasLoggedFailure) {
             hasLoggedFailure = true;

package/node_modules/pi-lens/dist/clients/eval-timestamp.js

@@ -0,0 +1,17 @@
+import { performance } from "node:perf_hooks";
+/**
+ * The moment pi-lens's module graph started evaluating, captured as this
+ * module's first statement (#1374 host-boot vs extension-eval split).
+ *
+ * This module is otherwise side-effect-free by design (#1434 S3d review): it
+ * does nothing but capture a timestamp. `clients/console-guard-install.ts`
+ * imports it as its FIRST import so the capture happens before the guard's
+ * own install work, and `clients/startup-timing.ts` imports it too, for the
+ * constant alone. Before this split, `startup-timing.ts` imported the
+ * constant FROM `console-guard-install.ts` — which meant importing
+ * startup-timing anywhere (e.g. a test measuring load time) silently
+ * installed the console guard as a side effect. Splitting the constant out
+ * means importing this module, or `startup-timing.ts`, never installs
+ * anything.
+ */
+export const PI_LENS_EVAL_STARTED_MS = performance.now();

package/node_modules/pi-lens/dist/clients/event-loop-monitor.js

@@ -143,15 +143,38 @@ export function resetEventLoopMonitor() {
     windowStartCpuMs = cpuTotalMs();
 }
 /**
- * Decide whether a freeze is worth persisting to `latency.log`. Pure so the
- * threshold logic is testable without the (vitest-flaky) native histogram.
- * Logs only a *new* worst block (`maxMs > lastLoggedMs + deltaMs`) above a
- * floor (`minMs`), so a turn that froze worse than ever before is recorded
- * once — not the same growing max every turn.
+ * Decide whether THIS block beats the session's running high-water. Pure so
+ * the threshold logic is testable without the (vitest-flaky) native
+ * histogram. Requires `maxMs > lastLoggedMs + deltaMs` above a floor
+ * (`minMs`) so noise near the current max doesn't keep re-triggering the
+ * high-water bookkeeping.
+ *
+ * NOTE (#1723): this is no longer the logging gate — see
+ * `shouldLogLoopBlock` for that. This function now answers a narrower
+ * question ("is this a new session worst?", used for the `worstSoFar`
+ * metadata flag and for deciding whether to advance the high-water), because
+ * gating the LOG on it hid every sub-maximum block after a session's first
+ * large one, which made loop_block-vs-pull-timeout correlation undecidable.
  */
 export function shouldLogWorstBlock(maxMs, lastLoggedMs, minMs = 60, deltaMs = 25) {
     return maxMs >= minMs && maxMs > lastLoggedMs + deltaMs;
 }
+/**
+ * Decide whether a block is worth persisting to `latency.log` AT ALL (#1723).
+ * Every block at or above the floor (`minMs`) qualifies — not only a new
+ * session worst — because a session's later blocks can be smaller than an
+ * early spike yet still be exactly the ones that starved an LSP pull
+ * (#1549/#1713) and are otherwise invisible to the correlation.
+ *
+ * Volume is bounded by CALL CADENCE, not by this gate: the `turn_end` caller
+ * invokes this at most once per turn (the histogram window is reset every
+ * turn), so the natural cap is one `loop_block` record per turn — a jittery
+ * session cannot flood the log because there is nowhere for a second sample
+ * to come from within the same turn.
+ */
+export function shouldLogLoopBlock(maxMs, minMs = 60) {
+    return maxMs >= minMs;
+}
 /** Test-only: stop and clear the monitor so cases don't leak into each other. */
 export function _stopEventLoopMonitorForTest() {
     histogram?.disable();