@herbertgao/pi-extensions 2026.9.1 → 2026.9.3

package/node_modules/pi-lens/dist/clients/runtime-turn.js

@@ -13,6 +13,7 @@ import { getKnipIgnorePatterns } from "./file-utils.js";
 import { formatCacheAgeLabel } from "./finding-delivery-gate.js";
 import { getFullScanWallClockMs, isWorkspaceSweepActive, runWhenWorkspaceSweepIdle, SWEEP_IDLE_SAFETY_MARGIN_MS, } from "./lsp/workspace-sweep-hold.js";
 import { isTestRoleCollateral } from "./collateral-test-role.js";
+import { classifyAndFilterFindings, } from "./gitleaks-client.js";
 import { dedupeSecretFindings, fromAstGrepWarnings, fromGitleaks, fromTrivySecrets, isSecretWarning, secretLocationKey, } from "./secret-findings.js";
 import { deadCodeIssueKey, deadCodeIssues, formatDeadCodeDelta, stableFindingKey, } from "./dead-code-client.js";
 import { logDeadCodeScan } from "./dead-code-logger.js";
@@ -49,6 +50,8 @@ import { emitBounded } from "./bounded-telemetry.js";
 import { degradeDemotedFindingBody, formatDeliveryCapNote, formatRetirementNote, } from "./demoted-finding-render.js";
 import { STALE_LINE_MARKER } from "./stale-marker.js";
 import { getActiveSessionId } from "./session-lifecycle.js";
+import { bounded } from "./deadline-utils.js";
+import { HOOK_WALL_BUDGET_MS } from "./hook-budgets.js";
 import { drainRenderedDependencyDriftFilePaths, getWidgetBlockingFilesForSweep, incrementWidgetDependencyDriftDelivery, markWidgetFileBlockersStale, recordRunner, retireWidgetDependencyDriftBlockers, } from "./widget-state.js";
 /** Maximum detailed notify-stall coverage-gap rows emitted in one turn. */
 const LATE_AUX_COVERAGE_GAP_DETAIL_CAP_PER_TURN = 20;
@@ -1483,6 +1486,26 @@ export async function handleTurnEnd(deps) {
     // provenance) — a blocker, since credentials need rotation before merge.
     const gitleaksData = cacheManager.readCache("gitleaks", cwd)?.data;
     const trivySecretsData = trivyCacheEntry?.data;
+    // Gitleaks deliberately scans gitignored local files and nested repositories
+    // so an explicit security audit can still inspect them. The adapter is the
+    // source of truth for whether a finding belongs in a blocking delivery lane;
+    // filter here before freshness handling so demoted findings cannot leak into
+    // either the blocker or stale-secret turn context.
+    const boundedClassification = await bounded(classifyAndFilterFindings(gitleaksData?.findings ?? [], cwd), {
+        ms: HOOK_WALL_BUDGET_MS.turn_end,
+        signal: deps.signal,
+        hook: "turn_end",
+        label: "classifyAndFilterFindings",
+    });
+    const classifiedGitleaksFindings = boundedClassification ?? gitleaksData?.findings ?? [];
+    if (boundedClassification === undefined) {
+        recordDegradationOnce({
+            kind: "gitleaks_classification_timeout",
+            subject: cwd,
+            reason: "gitleaks classification exceeded the turn_end budget; retained raw findings to fail open",
+        });
+    }
+    const blockingGitleaksFindings = classifiedGitleaksFindings.filter((finding) => gitleaksFindingToProjectDiagnostic(cwd, finding).semantic === "blocking");
     // #1461 slice 1 (#1460): the gitleaks cache is TTL-only, so a finding for a
     // file deleted after the scan is still served as a 🔴 blocker for the rest
     // of the 30-minute window — the live case, and 119 of 126 findings in
@@ -1497,7 +1520,7 @@ export async function handleTurnEnd(deps) {
     // would let any edit — malicious or accidental — mute a real secret.
     const gitleaksGate = gateFindingsByPathFreshness({
         store: "gitleaks",
-        findings: gitleaksData?.findings ?? [],
+        findings: blockingGitleaksFindings,
         cwd,
         scannedAt: gitleaksData?.scannedAt,
         citedPath: (finding) => finding.file,
@@ -2882,6 +2905,7 @@ export async function handleTurnEnd(deps) {
     let lateAuxCoverageGapDropCount = 0;
     const lateAuxStuckPairs = [];
     if (drainedPairs.length > 0) {
+        const lateObserverDeadline = Date.now() + HOOK_WALL_BUDGET_MS.turn_end;
         const byFile = new Map();
         for (const pair of drainedPairs) {
             const list = byFile.get(pair.filePath);
@@ -2993,6 +3017,19 @@ export async function handleTurnEnd(deps) {
                         }
                         continue;
                     }
+                    // A demoted auxiliary still answers through this late path. Feed the
+                    // publication-minus-mark interval into the re-promotion streak. This is
+                    // delivery latency observed by the drain, not the scanner's total scan
+                    // latency. Cache priming is
+                    // below the freshness gate so a changed file cannot resurrect stale data.
+                    if (typeof service.observeLateAuxiliaryAnswer === "function") {
+                        await bounded(service.observeLateAuxiliaryAnswer(lateAuxPath, pair.serverId, cachedEntry.publishedAt - pair.markedAtMs), {
+                            ms: Math.max(1, lateObserverDeadline - Date.now()),
+                            signal: deps.signal /* late observer */,
+                            hook: "turn_end",
+                            label: "observeLateAuxiliaryAnswer",
+                        });
+                    }
                     if (rawDiags.length === 0) {
                         lateAuxCleanConfirmed += 1;
                         continue;
@@ -3045,6 +3082,16 @@ export async function handleTurnEnd(deps) {
                         }
                         continue;
                     }
+                    // #2810 round 4: this drain does NOT write the hash-bound
+                    // last-known record. The prime it used to call could only fire when
+                    // a record already existed at the pair's hash — which requires a
+                    // FULLY covered touch of those exact bytes, the one case where the
+                    // scanner's findings are already in the record — so it was a no-op
+                    // in the demoted steady state it was added for, and a #570/#1470
+                    // hazard everywhere else (an auxiliary-only array replacing the
+                    // merged one). Late findings reach the agent as the gated advisory
+                    // below; the turn-end hash-guarded fast path stays cold for a file
+                    // whose touch was partial, which is exactly what #1470 requires.
                     const lines = gate.live.map((f) => `  ${displayLateAuxPath}:${f.line}:${f.column} [${f.rule}] ${f.message}`);
                     lateAuxDelivered += gate.live.length;
                     lateAuxAnswered += 1;

package/node_modules/pi-lens/dist/clients/sanitize.js

@@ -43,17 +43,6 @@ const DETAIL_PATTERNS = [
 export function stripAnsi(text) {
     return text.replace(ANSI_ESCAPE, "").replace(ANSI_ESCAPE_EXTENDED, "");
 }
-/**
- * Normalize whitespace in a string.
- * Collapses multiple spaces/tabs to single space, trims lines.
- */
-export function normalizeWhitespace(text) {
-    return text
-        .split(/\r?\n/)
-        .map((line) => line.replace(/\s+/g, " ").trim())
-        .filter((line) => line.length > 0)
-        .join("\n");
-}
 /**
  * Check if a line contains error indicators.
  */

package/node_modules/pi-lens/dist/clients/scan-utils.js

@@ -1,59 +1,4 @@
-import { isExcludedDirName, isTestFile } from "./file-utils.js";
-import { collectSourceFiles, collectSourceFilesAsync, isBuildArtifact, } from "./source-filter.js";
-/**
- * Common parsing logic for ast-grep JSON output (handles both array and NDJSON).
- */
-// biome-ignore lint/suspicious/noExplicitAny: ast-grep JSON output is untyped
-export function parseAstGrepJson(raw) {
-    if (!raw)
-        return [];
-    const trimmed = raw.trim();
-    if (trimmed.startsWith("[")) {
-        try {
-            return JSON.parse(trimmed);
-        }
-        catch {
-            return [];
-        }
-    }
-    return trimmed.split("\n").flatMap((l) => {
-        try {
-            return [JSON.parse(l)];
-        }
-        catch {
-            return [];
-        }
-    });
-}
-/**
- * Check if a file should be ignored based on project type and common patterns.
- *
- * @deprecated Use `isBuildArtifact()` from `source-filter.js` instead for artifact
- * detection, or compose your own filter using `collectSourceFiles()`. This function
- * is kept for backward compatibility.
- */
-export function shouldIgnoreFile(filePath, isTsProject) {
-    const relPath = filePath.replace(/\\/g, "/");
-    // Use new source-filter module for artifact detection
-    if (isTsProject && isBuildArtifact(filePath))
-        return true;
-    // Legacy: simple JS check for non-TS projects (hand-written JS)
-    const isJs = relPath.endsWith(".js") ||
-        relPath.endsWith(".mjs") ||
-        relPath.endsWith(".cjs");
-    if (isTsProject && isJs)
-        return true;
-    // Ignore test scripts and common test patterns
-    if (isTestFile(filePath))
-        return true;
-    // Ignore hidden directories and common build outputs
-    const pathParts = relPath.split("/").filter(Boolean);
-    for (const segment of pathParts.slice(0, -1)) {
-        if (isExcludedDirName(segment))
-            return true;
-    }
-    return false;
-}
+import { collectSourceFiles, collectSourceFilesAsync, } from "./source-filter.js";
 /**
  * Recursively find source files in a directory, respecting common excludes.
  *

package/node_modules/pi-lens/dist/clients/security-scan-client.js

@@ -14,7 +14,7 @@
  */
 import * as path from "node:path";
 import { createSubsystemLogger } from "./extension-log.js";
-import { safeSpawnAsync } from "./safe-spawn.js";
+import { probeToolAsync } from "./tool-probe.js";
 import { classifyProbeFailure, createAvailabilityLatch, describeInstallAttempt, describeProbeEvidence, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 import { createAvailabilityProbeFlight } from "./availability-probe-flight.js";
 import { createSingleFlight } from "./single-flight.js";
@@ -132,7 +132,7 @@ export class SecurityScanClient {
                 const { findManagedToolBinary } = await import("./installer/index.js");
                 const managed = await findManagedToolBinary(this.toolName);
                 return {
-                    probe: await safeSpawnAsync(managed ?? this.toolName, versionArgs, {
+                    probe: await probeToolAsync(managed ?? this.toolName, versionArgs, {
                         timeout: 5000,
                     }),
                     binaryPath: managed ?? null,

package/node_modules/pi-lens/dist/clients/session-event-guard.js

@@ -64,7 +64,22 @@
  * wrapper narrows nothing else: a handler bug must stay as loud as it was.
  */
 import { emitBounded } from "./bounded-telemetry.js";
+import { recordDegradationOnce } from "./degradation-ledger.js";
 import { probeCtxActive } from "./session-lifecycle.js";
+import { runWithTurnContext } from "./turn-context.js";
+function stableSessionId(ctx) {
+    try {
+        return ctx?.sessionManager?.getSessionId?.();
+    }
+    catch {
+        recordDegradationOnce({
+            kind: "turn-context-identity-fallback",
+            subject: "session-event-guard",
+            reason: "stable session identity resolution failed; using detached turn context",
+        });
+        return undefined;
+    }
+}
 /**
  * The pi SDK invalidates a captured `pi`/command ctx after a session
  * replacement or reload; every later `pi.*` call then throws with this
@@ -99,6 +114,59 @@ function recordStaleSkip(eventName, detectedAt) {
         reason: `${eventName} skipped: extension ctx is stale (${detectedAt})`,
     });
 }
+/**
+ * The one policy for "a pi hook handler threw and production swallows it"
+ * (#2884).
+ *
+ * Nine catch sites in `index.ts` absorb a crashed handler so a pi-lens bug
+ * can never take down the host's session. Each of them used to write only
+ * `dbg(...)`, and `dbg` writes nothing under vitest — so a crashed handler was
+ * indistinguishable from a completed one. #2859 is what that costs: fourteen
+ * `session_start` awaits in `tests/index-integration.test.ts` rejected into
+ * one of those catches, every assertion after them was vacuous, and the file
+ * stayed green. #2866 closed the hole for `session_start` with an inline
+ * `if (process.env.VITEST) throw`; this function is that guard folded into one
+ * place so the remaining eight cannot drift from it.
+ *
+ * Two things happen on every crash, in this order:
+ *
+ * 1. **The production record.** One bounded `hook-handler-crash` row per
+ *    handler per session (`recordDegradationOnce`), so a handler that crashes
+ *    on every turn leaves one durable row and an exact ledger tally instead of
+ *    a silent no-op. It is written BEFORE the rethrow, so a test can assert the
+ *    production observability the runner path would otherwise hide.
+ * 2. **The runner rethrow.** Under vitest the crash is rethrown, so the test
+ *    whose `await` caused it fails with the real error instead of resolving.
+ *    In production nothing is rethrown and the caller's swallow stands.
+ *
+ * Deliberately `process.env.VITEST` and not `isTestMode()` (kept from #2859):
+ * the question is whether a TEST is awaiting this handler, and the #2815 R7
+ * case runs under vitest with `PI_LENS_TEST_MODE=0`.
+ *
+ * The stale-ctx class is NOT this function's business. Callers that classify
+ * it (`session_start`, `agent_end`, `turn_end`, the `agent_settled` drain)
+ * rethrow `isStaleExtensionCtxError` themselves BEFORE calling in, so a benign
+ * session swap keeps its own single record and never lands here as a crash.
+ * The quiet-window site is intentionally the exception to the test-runner
+ * rethrow: it is fire-and-forget, so a rethrow would be an unhandled rejection
+ * that can terminate the pi host before its caller can observe the failure.
+ */
+export function surfaceHandlerCrash(handler, err, options = {}) {
+    try {
+        options.dbg?.(`${handler} crashed: ${err}`);
+        options.dbg?.(`${handler} crash stack: ${err?.stack}`);
+    }
+    catch {
+        // A debug sink must never decide whether a crash is recorded.
+    }
+    recordDegradationOnce({
+        kind: "hook-handler-crash",
+        subject: handler,
+        reason: `${handler} handler crashed and was swallowed: ${String(err)}`,
+    });
+    if (process.env.VITEST && options.rethrow !== false)
+        throw err;
+}
 function isThenable(value) {
     return (typeof value?.then === "function");
 }
@@ -131,7 +199,7 @@ function guardSessionEvent(eventName, handler, onStaleResult, options) {
             // below.
             return skip(event, "pre-dispatch");
         try {
-            const result = handler(event, ctx);
+            const result = runWithTurnContext(stableSessionId(ctx), () => handler(event, ctx));
             if (isThenable(result)) {
                 // Recover the rejection in place. The host awaits the same promise
                 // it would have awaited anyway; it just resolves instead.

package/node_modules/pi-lens/dist/clients/session-summary.js

@@ -1,30 +1,6 @@
 /**
  * Session Summary — generates turn_end and session-end summaries
  */
-export function formatSessionSummary(stats) {
-    if (stats.totalShown === 0)
-        return "";
-    const lines = [
-        "## Diagnostic Summary",
-        "",
-        `Shown to agent: ${stats.totalShown}`,
-        `Auto-fixed: ${stats.totalAutoFixed} (${pct(stats.totalAutoFixed, stats.totalShown)}%)`,
-        `Fixed by agent: ${stats.totalAgentFixed} (${pct(stats.totalAgentFixed, stats.totalShown)}%)`,
-        "",
-    ];
-    if (stats.topViolations.length > 0) {
-        lines.push("Top violations:");
-        for (const { ruleId, count } of stats.topViolations.slice(0, 5)) {
-            lines.push(`  - ${ruleId} (${count}x)`);
-        }
-    }
-    return lines.join("\n");
-}
-function pct(part, total) {
-    if (total === 0)
-        return "0";
-    return Math.round((part / total) * 100).toString();
-}
 export function formatSlopScoreSummary(summary) {
     if (summary.totalRuleDiagnostics === 0 || summary.totalKlocWritten <= 0) {
         return "";

package/node_modules/pi-lens/dist/clients/sg-runner.js

@@ -12,6 +12,7 @@ import { getSgCommand, resolveManagedToolClient, } from "./dispatch/runners/util
 import { getProjectIgnoreGlobs } from "./file-utils.js";
 import { findGlobalBinary } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { probeToolAsync } from "./tool-probe.js";
 import { truncatedByOutputCap } from "./spawn-output-cap.js";
 import { createSingleFlight } from "./single-flight.js";
 import { classifyProbeFailure, describeInstallAttempt, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
@@ -459,7 +460,7 @@ export class SgRunner {
         let result;
         let hostStallMs;
         try {
-            result = await safeSpawnAsync(cmd, [...argsPrefix, "--version"], {
+            result = await probeToolAsync(cmd, [...argsPrefix, "--version"], {
                 timeout: PROBE_TIMEOUT_MS,
             });
         }

package/node_modules/pi-lens/dist/clients/sgconfig.js

@@ -8,7 +8,7 @@ import { findLocalToolConfig } from "./path-utils.js";
 // ast-grep's root config marker. The `ast-grep lsp` server is workspace-gated:
 // it only operates in a project that has an `sgconfig.y[a]ml` at (or above) the
 // file. These are the names ast-grep itself looks for as root markers.
-export const SGCONFIG_NAMES = ["sgconfig.yml", "sgconfig.yaml"];
+const SGCONFIG_NAMES = ["sgconfig.yml", "sgconfig.yaml"];
 /**
  * Nearest `sgconfig.y[a]ml` walking up from `startDir`, or undefined if none.
  * Deliberately UNCEILINGED at $HOME (refs #2472 review round 3, F1): ast-grep
@@ -65,10 +65,6 @@ export function getAstGrepRuleSources(projectRoot = process.cwd()) {
         return true;
     });
 }
-/** Compatibility export retained for callers that only need ordered dirs. */
-export function shippedRuleDirsInPrecedenceOrder(projectRoot = process.cwd()) {
-    return getAstGrepRuleSources(projectRoot).map((source) => source.dir);
-}
 function findYamlFiles(dir) {
     const files = [];
     let entries;

package/node_modules/pi-lens/dist/clients/shared-checkout-guard.js

@@ -115,7 +115,7 @@ function isCleanDryRun(argsAfterVerb) {
  * replacement for the forbidden `git stash`. Blocking it would push
  * operators back toward stash.
  */
-export const WORKTREE_MUTATING_GIT_MATCHER = {
+const WORKTREE_MUTATING_GIT_MATCHER = {
     id: "worktree-mutating",
     indirectAlwaysMatches: false,
     // `git checkout --help` opens documentation and changes nothing. This

package/node_modules/pi-lens/dist/clients/situational-tool-telemetry.js

@@ -0,0 +1,108 @@
+import { logExtension } from "./extension-log.js";
+import { TOOL_REGISTRY } from "./tool-config.js";
+const situationalTools = TOOL_REGISTRY.filter((tool) => "situational" in tool && tool.situational === true).map((tool) => tool.name);
+const situationalToolSet = new Set(situationalTools);
+const activated = new Set();
+const called = new Set();
+let sessionStarted = false;
+let emitted = false;
+// MCP-only connection-terminal latch: once the connection's row is recorded,
+// repeated initialize/tool-call starts must not reopen the session.
+let connectionEnded = false;
+// Which host owns the open session; only MCP may arm connectionEnded. Pi state
+// belongs to the conversation and survives in-process session rebuilds.
+let sessionHost = "mcp";
+function observe(set, name) {
+    if (situationalToolSet.has(name)) {
+        set.add(name);
+    }
+}
+function clearObservations() {
+    activated.clear();
+    called.clear();
+}
+export function observeSituationalToolActivation(names) {
+    for (const name of names)
+        observe(activated, name);
+}
+export function observeSituationalToolCall(name) {
+    observe(called, name);
+}
+export function resetSituationalToolTelemetry() {
+    // A live telemetry session owns its observation sets: both hosts open the
+    // session (which resets the sets) BEFORE handleSessionStart runs, and a
+    // repeated MCP session_start refresh legitimately re-runs that handler —
+    // clearing here would wipe the calls recorded before the refresh. This
+    // registered reset therefore only acts when no session is open.
+    if (sessionStarted)
+        return;
+    clearObservations();
+    emitted = false;
+}
+/**
+ * Open the telemetry session for one host.
+ *
+ * Pi owns one observation set per session file. A shutdown with a
+ * `targetSessionFile` emits the conversation that is ending before the host
+ * opens the replacement. Reload keeps the same file, so its factory rebuild
+ * does not split the row. A process restart opens an empty set and recovers nothing:
+ * pi-lens's own activation memory (`rememberedLazyTools` in `index.ts`) is
+ * empty in a new process, so the restore deactivates every situational tool,
+ * and the host's restored active set is evidence of REGISTRATION, not of
+ * model activation (#2866 review F1). MCP remains connection-scoped.
+ */
+export function startSituationalToolTelemetrySession(host) {
+    if (host === "mcp") {
+        if (connectionEnded)
+            return;
+        if (sessionStarted)
+            return;
+        sessionHost = "mcp";
+        clearObservations();
+        emitted = false;
+        sessionStarted = true;
+        return;
+    }
+    if (sessionStarted) {
+        sessionHost = "pi";
+        return;
+    }
+    sessionHost = "pi";
+    clearObservations();
+    emitted = false;
+    sessionStarted = true;
+}
+/** Emit the one session-end row and make repeated shutdown calls harmless. */
+export function endSituationalToolTelemetry() {
+    if (!sessionStarted)
+        return;
+    emitSituationalDeadWeight();
+    if (sessionHost === "mcp")
+        connectionEnded = true;
+    clearObservations();
+    emitted = false;
+    sessionStarted = false;
+}
+export function emitSituationalDeadWeight() {
+    if (emitted)
+        return;
+    emitted = true;
+    const used = new Set([...activated, ...called]);
+    logExtension({
+        subsystem: "tools",
+        level: "debug",
+        message: "situational tool dead weight",
+        metadata: {
+            tools: situationalTools.filter((name) => !used.has(name)),
+        },
+    });
+}
+/** Test-only view of the module's state, for the #1635 session-state registry probe. */
+export function _getSituationalToolTelemetryStateForTests() {
+    return {
+        activated: activated.size,
+        called: called.size,
+        emitted,
+        sessionStarted,
+    };
+}

package/node_modules/pi-lens/dist/clients/smells-rollup.js

@@ -58,11 +58,11 @@ import * as path from "node:path";
 import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 /** Bounded tail-read budget PER source log file — never a full-file scan. */
 export const SMELLS_TAIL_BYTES_PER_FILE = 64 * 1024;
-export const SMELLS_ROLLING_WINDOW_MS = 24 * 60 * 60_000;
+const SMELLS_ROLLING_WINDOW_MS = 24 * 60 * 60_000;
 /** Re-check cadence at `turn_end`, mirroring `memory-sampler.ts`'s pattern —
  *  cheap enough (bounded ~128KB I/O) not to need finer throttling, but a
  *  fixed interval keeps it from running on every single turn. */
-export const SMELLS_TURN_CHECK_INTERVAL = 20;
+const SMELLS_TURN_CHECK_INTERVAL = 20;
 /** Trivial threshold constants (#1123 item 3's explicit design ask). Counts
  *  strictly below these never surface anywhere. */
 export const SMELLS_THRESHOLDS = {

package/node_modules/pi-lens/dist/clients/startup-scan.js

@@ -16,7 +16,7 @@ import { isAtOrAboveHomeDir } from "./path-utils.js";
 import { getStartupScanMaxSourceFilesDerived } from "./project-scale.js";
 import { shouldRecurseIntoDir, walkTreeStackAsync, walkTreeStackSync, } from "./source-walker.js";
 import { getDirectoryMarkers, registerWorkspaceTopologyReset, } from "./workspace-topology.js";
-export const PROJECT_ROOT_MARKERS = [
+const PROJECT_ROOT_MARKERS = [
     ".git",
     "package.json",
     "pyproject.toml",
@@ -24,16 +24,8 @@ export const PROJECT_ROOT_MARKERS = [
     "go.mod",
     "composer.json",
 ];
-// Deprecated (#776): no longer read directly below — `computeStartupScanContext`
-// / `resolveStartupScanContextAsync` now default `maxSourceFiles` to
-// `getStartupScanMaxSourceFilesDerived(cwd)` (project-scale.ts's
-// `maxProjectFiles` knob), which reproduces this same 2,000 value at the
-// default base. Kept exported for tests/callers that still reference the
-// literal.
-export const MAX_STARTUP_SOURCE_FILES = 2000;
 // #758: hard ceiling on the number of directory entries the startup source
 // count walk will visit before it gives up and declares the tree too big to
-// warm. The source-file early-exit (MAX_STARTUP_SOURCE_FILES) only fires when
 // a project has MANY source files — a repo with FEW source files but a huge
 // pile of non-source files (e.g. a game mod: 300 scripts among 84k data files)
 // never trips it, so the pre-#758 walk traversed the entire tree, dominated by
@@ -77,7 +69,7 @@ export const _resetStartupScanMaxEntriesForTests = _maxEntries._resetForTests;
  *
  * The content-derived reasons `too-many-source-files` and `too-many-entries`
  * (#758) are the ones that are TTL'd. They can go stale on their own: the repo
- * can shrink below `MAX_STARTUP_SOURCE_FILES` (or below the entry ceiling)
+ * can shrink below the source-file cap (or below the entry ceiling)
  * between sessions, and nothing else would notice
  * — the seq-based freshness check that guards every other
  * `project-snapshot.json` field never fires for them, because pi-lens never