pi-lens 4.1.2 → 4.1.4

package/dist/clients/dispatch/dispatcher.js

@@ -17,26 +17,33 @@ import { logExtension } from "../extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { recordRunner } from "../widget-state.js";
+import { incrementDegradationCount, recordDegradationOnce, } from "../degradation-ledger.js";
 import { detectFileKind } from "../file-kinds.js";
 import { detectFileRole } from "../file-role.js";
+import { classifyGeneratedOrArtifactDetailed, } from "../generated-artifacts.js";
 import { isTestFile } from "../file-utils.js";
 import { getPrimaryDispatchGroup } from "../language-policy.js";
 import { resolveLanguageRootForFile } from "../language-profile.js";
 import { logLatency, phaseFinished, phaseStarted } from "../latency-logger.js";
 import { isSpawnableCommand } from "../installer/index.js";
-import { normalizeMapKey } from "../path-utils.js";
+import { isAbsoluteFilePath, normalizeEphemeralMapKey, normalizeMapKey, } from "../path-utils.js";
 import { loadPiLensProjectConfig } from "../project-lens-config.js";
 import { RUNTIME_CONFIG, getRunnerTimeoutFloorMs } from "../runtime-config.js";
 import { safeSpawnAsync } from "../safe-spawn.js";
 import { classifyDiagnostic } from "./diagnostic-taxonomy.js";
 import { classifyProbeFailure, logAvailabilityDecision, startHostStallSampler, transientRetryDelayMs, } from "./runners/utils/availability-policy.js";
+import { recordAvailabilityProbeOverrun, getDispatchAvailabilityGeneration, } from "./runners/utils/runner-helpers.js";
+import { createAvailabilityProbeFlight } from "../availability-probe-flight.js";
 import { applyDispositions } from "../diagnostic-dispositions.js";
 import { applyInlineSuppressions } from "./inline-suppressions.js";
 import { getToolPlan } from "./plan.js";
 import { resolveRunnerPath } from "./runner-context.js";
+import { classifyObservedRunner, COLLECT_LATER_THRESHOLD_MS, observeRunnerLatency, } from "./collect-later-tier.js";
+import { deferRunnerFindings } from "./pending-runner-findings.js";
 import { applyRulePolicy, rulePolicyMapFromConfig } from "./rule-policy.js";
 import { getToolProfile } from "./tool-profile.js";
 import { isRunnerSkipReason } from "./types.js";
+const dispatcherProbeFlights = createAvailabilityProbeFlight({ generation: () => getDispatchAvailabilityGeneration() });
 import { formatDiagnostics } from "./utils/format-utils.js";
 // --- Runner Registry ---
 export class RunnerRegistry {
@@ -55,7 +62,7 @@ export class RunnerRegistry {
         for (const runner of this.runners.values()) {
             if (isTest && runner.skipTestFiles)
                 continue;
-            if (runner.appliesTo.includes(kind) || runner.appliesTo.length === 0) {
+            if (runnerAppliesToKind(runner, kind)) {
                 matching.push(runner);
             }
         }
@@ -68,6 +75,10 @@ export class RunnerRegistry {
         this.runners.clear();
     }
 }
+function runnerAppliesToKind(runner, kind) {
+    return (runner.appliesTo.length === 0 ||
+        (kind !== undefined && runner.appliesTo.includes(kind)));
+}
 // --- Tool Availability Cache ---
 /**
  * Normalize a command name to a FactStore session key.
@@ -134,15 +145,19 @@ export async function checkToolAvailability(command, facts) {
         const startedAt = Date.now();
         let result;
         let hostStallMs;
+        let probeJoined = false;
         try {
-            result = await safeSpawnAsync(command, ["--version"], {
+            const shared = dispatcherProbeFlights.run(`dispatcher:${key}`, () => safeSpawnAsync(command, ["--version"], {
                 timeout: TOOL_PROBE_TIMEOUT_MS,
-            });
+            }));
+            probeJoined = shared.joined;
+            result = await shared.promise;
         }
         finally {
             hostStallMs = sampler.stop();
         }
         const elapsedMs = Date.now() - startedAt;
+        recordAvailabilityProbeOverrun(command, key, elapsedMs, TOOL_PROBE_TIMEOUT_MS, result.failure);
         if (result.status === 0) {
             facts.setSessionFact(key, true);
             // The tool answered: retire the cooldown facts rather than leaving a
@@ -156,6 +171,7 @@ export async function checkToolAvailability(command, facts) {
                 cause: "ok",
                 elapsedMs,
                 latched: true,
+                classifiedBy: probeJoined ? "joined" : "probe",
                 hostStallMs,
                 budgetMs: TOOL_PROBE_TIMEOUT_MS,
             });
@@ -188,7 +204,7 @@ export async function checkToolAvailability(command, facts) {
             hostStallMs,
             ...(retryAfterMs !== undefined && { retryAfterMs }),
             budgetMs: TOOL_PROBE_TIMEOUT_MS,
-            classifiedBy: "probe",
+            classifiedBy: probeJoined ? "joined" : "probe",
             evidence,
         });
         return false;
@@ -234,7 +250,19 @@ telemetryModel, telemetryProvider) {
     const normalizedCwd = normalizeMapKey(resolveLanguageRootForFile(absoluteFilePath, cwd));
     const normalizedFilePath = normalizeMapKey(absoluteFilePath);
     const kind = detectFileKind(normalizedFilePath);
-    const fileRole = detectFileRole(normalizedFilePath, readFilePrefix(normalizedFilePath));
+    const contentPrefix = readFilePrefix(normalizedFilePath);
+    const fileRole = detectFileRole(normalizedFilePath, contentPrefix);
+    // Captured once here so the generated short-circuit below can emit a
+    // `dispatch_skipped_generated` record carrying the deciding evidence tier
+    // and the measured line-shape statistic — without re-reading the file
+    // (refs #2346). The content passed is the same 4096-byte prefix already
+    // read for role detection, so this classification costs no extra I/O.
+    const generatedDetail = fileRole === "generated"
+        ? classifyGeneratedOrArtifactDetailed(normalizedFilePath, {
+            content: contentPrefix,
+            includeDeclarations: false,
+        })
+        : undefined;
     const projectConfig = loadPiLensProjectConfig(normalizedCwd);
     return {
         filePath: normalizedFilePath,
@@ -242,6 +270,8 @@ telemetryModel, telemetryProvider) {
         cwd: normalizedCwd,
         kind,
         fileRole,
+        generatedEvidence: generatedDetail?.evidence,
+        generatedLineShapeMean: generatedDetail?.lineShapeMean,
         pi,
         autofix: false,
         deltaMode: !pi.getFlag("no-delta"),
@@ -419,13 +449,19 @@ function buildCoverageNotice(ctx, runnerLatencies) {
         // The marker describes this exact silent-scanner set. A scanner can
         // recover while another goes dark on the same file, so the set belongs
         // in the session dedupe identity rather than only kind and path.
+        // #2016: these are SCANNER IDS, not filesystem paths. `normalizeMapKey`
+        // would realpath each one; on Windows that fails, falls through to
+        // `resolveNonExisting`, and resolves the id against the CURRENT process
+        // cwd, so the dedupe key differed by platform and by cwd (the #2219
+        // non-path-sentinel class). The cheap syntactic fold is what this
+        // session-scoped dedupe key actually needs.
         const silentScannerSet = [...new Set(unconfirmedServerIds)]
-            .map(normalizeMapKey)
+            .map(normalizeEphemeralMapKey)
             // Code-unit comparator: the sorted set is a dedupe KEY, so ordering
             // must be deterministic across locales — localeCompare is not.
             .sort((a, b) => Number(a > b) - Number(a < b))
             .join(",");
-        const onceKey = `${ctx.kind}:${normalizeMapKey(ctx.filePath)}:${silentScannerSet}`;
+        const onceKey = `${ctx.kind}:${ctx.filePath}:${silentScannerSet}`;
         if (coverageNoticeSeen.has(onceKey))
             return undefined;
         coverageNoticeSeen.add(onceKey);
@@ -445,7 +481,9 @@ function buildCoverageNotice(ctx, runnerLatencies) {
     const primaryHasCoverage = relevant.some((r) => r.status === "succeeded" || r.status === "failed");
     if (primaryHasCoverage)
         return undefined;
-    const allPrimarySkipped = relevant.every((r) => r.status === "skipped" || r.status === "when_skipped");
+    const allPrimarySkipped = relevant.every((r) => r.status === "skipped" ||
+        r.status === "when_skipped" ||
+        r.status === "test_file_skipped");
     if (!allPrimarySkipped)
         return undefined;
     const plan = getToolPlan(ctx.kind);
@@ -467,7 +505,7 @@ function buildCoverageNotice(ctx, runnerLatencies) {
         (r.status === "succeeded" || r.status === "failed"));
     if (anyLinterHasCoverage)
         return undefined;
-    const onceKey = `${ctx.kind}:${normalizeMapKey(ctx.filePath)}`;
+    const onceKey = `${ctx.kind}:${ctx.filePath}`;
     if (coverageNoticeSeen.has(onceKey))
         return undefined;
     coverageNoticeSeen.add(onceKey);
@@ -482,6 +520,11 @@ function buildCoverageNotice(ctx, runnerLatencies) {
 }
 const latencyReports = [];
 const coverageNoticeSeen = new Set();
+// One `dispatch_skipped_generated` phase record per file per process (refs
+// #2346): a generated file dispatched repeatedly must not spam latency.log,
+// so only the first skip of each file emits the row; the degradation ledger
+// below still tallies every repetition with a bounded per-subject count.
+const generatedSkipRecorded = new Set();
 export function getLatencyReports() {
     return [...latencyReports];
 }
@@ -490,6 +533,7 @@ export function clearLatencyReports() {
 }
 export function clearCoverageNoticeState() {
     coverageNoticeSeen.clear();
+    generatedSkipRecorded.clear();
 }
 export function formatLatencyReport(report) {
     const lines = [];
@@ -571,6 +615,59 @@ async function runGroup(ctx, group, registry, onRunnerResult) {
             });
             continue;
         }
+        // Same skipTestFiles gate RunnerRegistry.getForKind applies for the
+        // per-edit path (#2337): the plan/group path resolves runners by id via
+        // registry.get() instead, which bypasses getForKind entirely, so a
+        // runner declaring skipTestFiles never had it enforced here.
+        if (runner.skipTestFiles && isTestFile(ctx.filePath)) {
+            latencies.push({
+                runnerId,
+                startTime: runnerStart,
+                endTime: Date.now(),
+                durationMs: Date.now() - runnerStart,
+                status: "test_file_skipped",
+                diagnosticCount: 0,
+                semantic: "none",
+            });
+            logLatency({
+                type: "runner",
+                filePath: ctx.filePath,
+                runnerId,
+                durationMs: 0,
+                status: "test_file_skipped",
+                diagnosticCount: 0,
+                semantic: "none",
+            });
+            continue;
+        }
+        // Keep explicit groups aligned with RunnerRegistry.getForKind(): an empty
+        // appliesTo list means every kind, while a populated list must contain the
+        // current kind. A filtered runner remains visible as skipped telemetry so
+        // language mismatches cannot be mistaken for runner failures.
+        const appliesToCurrentKind = runnerAppliesToKind(runner, ctx.kind);
+        if (!appliesToCurrentKind) {
+            const runnerEnd = Date.now();
+            latencies.push({
+                runnerId,
+                startTime: runnerStart,
+                endTime: runnerEnd,
+                durationMs: 0,
+                status: "skipped",
+                diagnosticCount: 0,
+                semantic: "unknown",
+            });
+            logLatency({
+                type: "runner",
+                filePath: ctx.filePath,
+                runnerId,
+                durationMs: 0,
+                status: "skipped",
+                diagnosticCount: 0,
+                semantic: "unknown",
+                metadata: { reason: "applies_to", kind: ctx.kind },
+            });
+            continue;
+        }
         // Check preconditions
         let shouldRun = true;
         if (runner.when) {
@@ -603,10 +700,123 @@ async function runGroup(ctx, group, registry, onRunnerResult) {
             });
             continue;
         }
+        const projectRoot = ctx.projectRoot ?? ctx.cwd;
+        // Only post-write dispatches participate. Project scans and direct API
+        // callers must retain their existing synchronous semantics.
+        const observedTier = ctx.writeIndex === undefined
+            ? "inline"
+            : classifyObservedRunner(projectRoot, runner.id);
+        if (observedTier === "collect-later") {
+            const markedAtMs = Date.now();
+            const deferred = runRunner(ctx, runner, semantic).then((result) => {
+                const durationMs = Date.now() - markedAtMs;
+                const tier = observeRunnerLatency({
+                    projectRoot,
+                    runnerId: runner.id,
+                    durationMs,
+                    timedOut: result.failureKind === "timeout",
+                });
+                if (tier !== observedTier) {
+                    logLatency({
+                        type: "phase",
+                        filePath: ctx.filePath,
+                        phase: "runner_collect_later_tier_flip",
+                        durationMs: 0,
+                        metadata: {
+                            runnerId: runner.id,
+                            from: observedTier,
+                            to: tier,
+                            projectRoot,
+                        },
+                    });
+                }
+                if (tier === "collect-later") {
+                    incrementDegradationCount({
+                        kind: "runner-collect-later",
+                        subject: `${projectRoot}:${runner.id}`,
+                        reason: `observed ${durationMs}ms, threshold ${COLLECT_LATER_THRESHOLD_MS}ms`,
+                    });
+                }
+                logLatency({
+                    type: "runner",
+                    filePath: ctx.filePath,
+                    runnerId: runner.id,
+                    startedAt: new Date(markedAtMs).toISOString(),
+                    durationMs,
+                    status: result.status,
+                    diagnosticCount: result.diagnostics.length,
+                    semantic: result.semantic ?? semantic,
+                    metadata: { tier: "collect-later", delivered: "turn_end" },
+                });
+                return result;
+            });
+            deferRunnerFindings({
+                filePath: ctx.filePath,
+                cwd: ctx.cwd,
+                projectRoot,
+                runnerId: runner.id,
+                markedAtMs,
+                writeIndex: ctx.writeIndex,
+                promise: deferred,
+            });
+            // A deferred runner is still an observed runner. Keep it visible in
+            // both the edit latency report and the widget until its turn-end result
+            // replaces this pending state (#2122 F1).
+            latencies.push({
+                runnerId: runner.id,
+                startTime: runnerStart,
+                endTime: runnerStart,
+                durationMs: 0,
+                status: "pending",
+                diagnosticCount: 0,
+                semantic: semantic,
+            });
+            recordRunner(ctx.filePath, runner.id, "pending", 0, 0, ctx.writeIndex);
+            logLatency({
+                type: "runner",
+                filePath: ctx.filePath,
+                runnerId: runner.id,
+                durationMs: 0,
+                status: "pending",
+                diagnosticCount: 0,
+                semantic,
+                metadata: { tier: "collect-later", delivered: "turn_end" },
+            });
+            continue;
+        }
         const result = await runRunner(ctx, runner, semantic);
         onRunnerResult?.(runnerId, result);
         const runnerEnd = Date.now();
         const duration = runnerEnd - runnerStart;
+        const tier = ctx.writeIndex === undefined
+            ? "inline"
+            : observeRunnerLatency({
+                projectRoot,
+                runnerId: runner.id,
+                durationMs: duration,
+                timedOut: result.failureKind === "timeout",
+            });
+        if (tier !== observedTier) {
+            logLatency({
+                type: "phase",
+                filePath: ctx.filePath,
+                phase: "runner_collect_later_tier_flip",
+                durationMs: 0,
+                metadata: {
+                    runnerId: runner.id,
+                    from: observedTier,
+                    to: tier,
+                    projectRoot,
+                },
+            });
+        }
+        if (tier === "collect-later") {
+            incrementDegradationCount({
+                kind: "runner-collect-later",
+                subject: `${projectRoot}:${runner.id}`,
+                reason: `observed ${duration}ms, threshold ${COLLECT_LATER_THRESHOLD_MS}ms`,
+            });
+        }
         // Runner definitions are a typed API, but embedders/plugins can still
         // return untyped objects at runtime. Admit only the closed taxonomy and
         // only on actual skips so free text cannot enter durable latency metadata.
@@ -672,6 +882,31 @@ async function runGroup(ctx, group, registry, onRunnerResult) {
 export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
     const _overallStart = Date.now();
     if (ctx.fileRole === "generated") {
+        // The generated short-circuit (refs #2346): never ran before this fix
+        // for name-less machine-emitted files (a scraped/minified page has no
+        // `.min.js` pattern to catch it), so the classification now also has a
+        // content-shape tier. The skip is observable — one `dispatch_skipped_generated`
+        // phase record per file per process carrying the deciding evidence tier
+        // and the measured line-shape statistic. Deliberately NOT a degradation
+        // ledger entry: skipping a generated file is healthy behavior working
+        // as designed, and the ledger's bounded kind slots are reserved for
+        // genuine degradations (#2348 review F3 — the ledger precedent at the
+        // collect-later tier flip below records an actual capability loss).
+        const evidence = ctx.generatedEvidence;
+        const lineShapeMean = ctx.generatedLineShapeMean;
+        if (!generatedSkipRecorded.has(ctx.filePath)) {
+            generatedSkipRecorded.add(ctx.filePath);
+            logLatency({
+                type: "phase",
+                filePath: ctx.filePath,
+                phase: "dispatch_skipped_generated",
+                durationMs: 0,
+                metadata: {
+                    evidence: evidence ?? "unknown",
+                    ...(lineShapeMean !== undefined && { lineShapeMean }),
+                },
+            });
+        }
         return {
             diagnostics: [],
             blockers: [],
@@ -706,12 +941,46 @@ export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
     // group order so output is deterministic.
     const groupResults = await Promise.all(groups.map((group) => runGroup(ctx, group, registry, onRunnerResult)));
     // Count baseline warnings before filtering (for delta count display)
-    const relativeKey = path.relative(ctx.cwd, ctx.filePath).replace(/\\/g, "/");
-    const baselineAbsKey = `session.baseline.${normalizeMapKey(ctx.filePath)}`;
-    const baselineRelKey = `session.baseline.${normalizeMapKey(relativeKey)}`;
-    const previousBaseline = ctx.deltaMode
-        ? (ctx.facts.getSessionFact(baselineAbsKey) ??
-            ctx.facts.getSessionFact(baselineRelKey))
+    //
+    // #2489: `ctx.filePath` is `createDispatchContext`'s `normalizedFilePath`
+    // (`resolveRunnerPath` -> `path.resolve` -> `normalizeMapKey`), which is
+    // ALWAYS absolute — the #2016 invariant this seam already relies on. A
+    // prior relative-path fallback key (`session.baseline.<path relative to
+    // ctx.cwd>`) existed here for self-consistency across the abs/rel read
+    // and write, but on `ctx.facts` singletons that outlive one project root
+    // (`dispatch/integration.ts`'s module-scope `sessionFacts`, reached by
+    // the warm `pilens_analyze` MCP route across any number of cwds) two
+    // different projects dispatching files that share a relative path (e.g.
+    // both have `src/index.ts`) collided on that fallback key, so project
+    // B's first-ever delta baseline read could silently return project A's
+    // stored diagnostics. Since the absolute key can never collide across
+    // projects (an absolute path is unique on the filesystem) and both
+    // writes always land together, the relative fallback is both unneeded
+    // and the sole source of the collision — removed rather than cwd-scoped
+    // (`cwd` is not a stable identity across this seam's callers, #2494).
+    //
+    // #2489 round 2: the #2016 invariant above is enforced by
+    // `createDispatchContext`, the sole real constructor, but nothing enforced
+    // it AT THIS SEAM — a hand-built `DispatchContext` (test scaffolding, a
+    // future caller) carrying a relative `filePath` would silently key the
+    // baseline under a value the constructor could never produce, and every
+    // subsequent same-session dispatch of the real (absolute-keyed) file would
+    // read back `undefined`, never the collision itself. Mirrors the sibling
+    // guard `recordEntitySnapshotDiff` already enforces for the entity-snapshot
+    // seam (`clients/review-graph/service.ts`, #2477): reject visibly and skip
+    // the baseline read/write for this dispatch rather than compute one under
+    // an unreachable key.
+    const baselinePathSafe = isAbsoluteFilePath(ctx.filePath);
+    if (ctx.deltaMode && !baselinePathSafe) {
+        recordDegradationOnce({
+            kind: "dispatch-non-absolute-baseline-path",
+            subject: ctx.filePath,
+            reason: "dispatchForFile requires an absolute ctx.filePath to key the delta baseline (refs #2489)",
+        });
+    }
+    const baselineAbsKey = `session.baseline.${ctx.filePath}`;
+    const previousBaseline = ctx.deltaMode && baselinePathSafe
+        ? ctx.facts.getBoundedSessionFact(baselineAbsKey)
         : undefined;
     const baselineWarnings = previousBaseline?.filter((d) => d.semantic === "warning" || d.semantic === "none");
     const baselineWarningCount = baselineWarnings?.length ?? 0;
@@ -778,9 +1047,12 @@ export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
         resolvedCount = filtered.fixed.length;
     }
     // Persist full current snapshot for next run (not delta-filtered subset).
-    if (ctx.deltaMode) {
-        ctx.facts.setSessionFact(baselineAbsKey, [...dedupedDiagnostics]);
-        ctx.facts.setSessionFact(baselineRelKey, [...dedupedDiagnostics]);
+    // Gated on `baselinePathSafe` too: a non-absolute `ctx.filePath` already
+    // skipped the read above (the degradation record fired there), and writing
+    // under that same unreachable key here would just seed a baseline no real
+    // reader (always absolute) could ever read back.
+    if (ctx.deltaMode && baselinePathSafe) {
+        ctx.facts.setBoundedSessionFact(baselineAbsKey, [...dedupedDiagnostics]);
     }
     // Categorize results
     const blockers = visibleDiagnostics.filter((d) => d.semantic === "blocking");
@@ -819,6 +1091,12 @@ export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
         output += formatDiagnostics([coverageNotice], "warning", 1);
         warnings.push(coverageNotice);
     }
+    const pendingRunners = runnerLatencies
+        .filter((runner) => runner.status === "pending")
+        .map((runner) => runner.runnerId);
+    if (pendingRunners.length > 0) {
+        output += `\n⏳ Pending runners (reported at turn end): ${pendingRunners.join(", ")}\n`;
+    }
     // Generate and store latency report
     const overallEnd = Date.now();
     const latencyReport = {
@@ -862,6 +1140,13 @@ export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
             })),
             totalDiagnostics: visibleDiagnostics.length,
             blockers: blockers.length,
+            // #2489 round 2: distinguishes a delta baseline HIT (a prior snapshot
+            // was read for this file this session) from a MISS (first dispatch, or
+            // the non-absolute-path guard above skipped the read) — `dispatch_start`
+            // (above, `metadata: { groupCount, kind, runners }`) fires before the
+            // baseline read ever runs and cannot carry either value.
+            baselineHit: previousBaseline !== undefined,
+            baselineWarningCount,
         },
     });
     return {