pi-lens 3.8.71 → 3.8.73

package/dist/clients/lsp-budget.js

@@ -20,9 +20,9 @@
  * the primary language server per file. Auxiliaries are cross-cutting
  * scanners layered on top of (not required for) core diagnostics, so this is
  * the cheapest, highest-signal thing to shed under machine-wide pressure.
- * The issue's OTHER suggested mechanism — shortening this session's own
- * idle-reaper timeout — is a documented follow-up, not implemented here (see
- * the module docstring's "Not implemented" note below).
+ * The cached decision also shortens this session's idle reset and lets
+ * pull-capable servers skip their push fallback. All three degrade mechanisms
+ * read the same session-boundary snapshot; pressure never changes mid-touch.
  *
  * Ceiling default (`DEFAULT_LSP_BUDGET_CEILING = 16`): a rough RAM-budget
  * back-of-envelope, not a measured figure (#620's CPU/RSS sampling had not
@@ -43,10 +43,11 @@
  * (session-lifecycle.ts / runtime-config.ts).
  */
 import { isInstanceRegistryEnabled, readInstanceRegistry, } from "./instance-registry.js";
-import { realIsPidAlive } from "./instance-reaper.js";
+import { realIsPidAlive, STALE_HEARTBEAT_MS } from "./instance-reaper.js";
 import { logLatency } from "./latency-logger.js";
 /** See the module docstring for the derivation. */
 export const DEFAULT_LSP_BUDGET_CEILING = 16;
+export const DEFAULT_LSP_BUDGET_IDLE_TIMEOUT_MS = 60_000;
 /** `PI_LENS_CROSS_PROCESS_BUDGET=0` disables the budget check entirely —
  *  lazy env read (house style), never memoized so tests can flip it mid-run. */
 export function isCrossProcessBudgetEnabled() {
@@ -60,6 +61,17 @@ export function getLspBudgetCeiling() {
     const raw = Number(process.env.PI_LENS_LSP_BUDGET_CEILING);
     return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LSP_BUDGET_CEILING;
 }
+/** Optional aggregate host + LSP-child RSS ceiling. Undefined means disabled. */
+export function getLspBudgetRssCeilingBytes() {
+    const raw = Number(process.env.PI_LENS_LSP_BUDGET_RSS_MB);
+    return Number.isFinite(raw) && raw > 0 ? raw * 1024 * 1024 : undefined;
+}
+export function getLspBudgetIdleTimeoutMs() {
+    const raw = Number(process.env.PI_LENS_LSP_BUDGET_IDLE_TIMEOUT_MS);
+    return Number.isFinite(raw) && raw > 0
+        ? raw
+        : DEFAULT_LSP_BUDGET_IDLE_TIMEOUT_MS;
+}
 /**
  * PURE decision function — no I/O. Mirrors `decideOrphanReaping`'s shape
  * (clients/instance-reaper.ts) for the same reason: injectable liveness
@@ -72,14 +84,37 @@ export function getLspBudgetCeiling() {
  * already being cleaned up (or was already cleaned up and the entry just
  * hasn't been pruned from this snapshot yet).
  */
-export function decideLspBudget(registry, isPidAlive, ceiling) {
-    const totalLiveLspServers = registry.reduce((sum, instance) => isPidAlive(instance.pid) ? sum + instance.lspChildren.length : sum, 0);
-    const overBudget = totalLiveLspServers >= ceiling;
+export function decideLspBudget(registry, isPidAlive, ceiling, rssCeilingBytes, now = Date.now()) {
+    const liveInstances = registry.filter((instance) => isPidAlive(instance.pid));
+    const totalLiveLspServers = liveInstances.reduce((sum, instance) => sum + instance.lspChildren.length, 0);
+    const hasCompleteFreshSamples = rssCeilingBytes !== undefined &&
+        liveInstances.length > 0 &&
+        liveInstances.every((instance) => {
+            const heartbeatMs = Date.parse(instance.heartbeatAt);
+            return (Number.isFinite(heartbeatMs) &&
+                now - heartbeatMs <= STALE_HEARTBEAT_MS &&
+                Number.isFinite(instance.rssBytes) &&
+                instance.lspChildren.every((child) => Number.isFinite(child.rssBytes)));
+        });
+    const totalRssBytes = hasCompleteFreshSamples
+        ? liveInstances.reduce((sum, instance) => sum +
+            instance.rssBytes +
+            instance.lspChildren.reduce((childSum, child) => childSum + (child.rssBytes ?? 0), 0), 0)
+        : undefined;
+    const rssPressure = totalRssBytes !== undefined &&
+        rssCeilingBytes !== undefined &&
+        totalRssBytes >= rssCeilingBytes;
+    const overBudget = totalLiveLspServers >= ceiling || rssPressure;
     return {
         totalLiveLspServers,
         ceiling,
+        totalRssBytes,
+        rssCeilingBytes,
+        rssPressure,
         overBudget,
         degradeAuxiliary: overBudget,
+        shortenIdleTimeout: overBudget,
+        preferPullOnly: overBudget,
     };
 }
 // --- Module-scope decision cache, read by clients/dispatch/auxiliary-lsp.ts ---
@@ -98,6 +133,12 @@ let cachedDecision;
 export function shouldDegradeAuxiliaryLsp() {
     return cachedDecision?.degradeAuxiliary ?? false;
 }
+export function shouldShortenLspIdleTimeout() {
+    return cachedDecision?.shortenIdleTimeout ?? false;
+}
+export function shouldPreferPullOnlyDiagnostics() {
+    return cachedDecision?.preferPullOnly ?? false;
+}
 /** Test-only: reset the module-scope cache between tests. */
 export function _resetLspBudgetDecisionForTests() {
     cachedDecision = undefined;
@@ -110,22 +151,16 @@ export function _resetLspBudgetDecisionForTests() {
  * default, matching every other best-effort registry consumer in this
  * codebase (registerInstance/sweepOrphans).
  *
- * Not implemented in this prototype (documented follow-up, see the issue):
- * shortening THIS session's own idle-reaper timeout when over budget. Skip-
- * auxiliary was chosen as the single mechanism for the first slice because
- * it's a pure spawn-time decision (no interaction with already-warm clients),
- * whereas an idle-timeout change would need to reach into already-configured
- * per-server wait/reap state.
  */
-export async function checkCrossProcessLspBudget() {
+export async function checkCrossProcessLspBudget(testOverrides = {}) {
     if (!isCrossProcessBudgetEnabled() || !isInstanceRegistryEnabled())
         return;
     try {
-        const registry = await readInstanceRegistry();
+        const registry = testOverrides.registry ?? (await readInstanceRegistry());
         if (registry.length === 0)
             return; // nothing to be over budget against
         const ceiling = getLspBudgetCeiling();
-        const decision = decideLspBudget(registry, realIsPidAlive, ceiling);
+        const decision = decideLspBudget(registry, testOverrides.isPidAlive ?? realIsPidAlive, ceiling, getLspBudgetRssCeilingBytes());
         cachedDecision = decision;
         if (decision.overBudget) {
             logLatency({
@@ -136,6 +171,9 @@ export async function checkCrossProcessLspBudget() {
                 metadata: {
                     totalLiveLspServers: decision.totalLiveLspServers,
                     ceiling: decision.ceiling,
+                    totalRssBytes: decision.totalRssBytes,
+                    rssCeilingBytes: decision.rssCeilingBytes,
+                    rssPressure: decision.rssPressure,
                     instanceCount: registry.length,
                 },
             });

package/dist/clients/mcp/analyze.js

@@ -147,7 +147,7 @@ export async function analyzeFile(filePath, cwd, options = {}) {
         : path.resolve(cwd, filePath);
     // no-delta by default → a full snapshot every call (not delta-filtered);
     // caller flags win over the default.
-    const host = createMcpHost({ "no-delta": true, ...(options.flags ?? {}) });
+    const host = createMcpHost({ "no-delta": true, ...(options.flags ?? {}) }, cwd);
     if (options.warmLsp !== false) {
         await warmLspForFile(absPath, host);
     }

package/dist/clients/mcp/host-shim.js

@@ -3,25 +3,29 @@
  *
  * pi-lens's dispatch core only couples to the host through a single-method
  * interface — `PiAgentAPI.getFlag`. When pi-lens runs *inside pi*, that flag
- * resolver is backed by pi's CLI flags + global config. When it runs as an MCP
- * server (no pi process, no CLI flags), we back it by the global config + env +
- * optional per-call overrides instead. This is the *entire* host coupling the
- * MCP path has to satisfy — everything else under `clients/` is host-neutral.
+ * resolver is backed by pi's CLI flags + project/global config. When it runs as
+ * an MCP server (no pi process, no CLI flags), we back it by project/global
+ * config + env + optional per-call overrides instead. This is the *entire* host
+ * coupling the MCP path has to satisfy — everything else under `clients/` is
+ * host-neutral.
  */
 import { loadPiLensGlobalConfig, resolvePiLensFlag, } from "../lens-config.js";
+import { loadPiLensProjectConfig } from "../project-lens-config.js";
 /**
  * Build a `PiAgentAPI` for the MCP path. `overrides` lets a single MCP tool call
  * pin flags for that analysis (e.g. `no-lsp: true` to bench the non-LSP path)
- * without mutating global config. Precedence: override → global config default.
+ * without mutating config. Precedence: override → project config → global
+ * config default.
  */
-export function createMcpHost(overrides) {
+export function createMcpHost(overrides, projectRoot = process.cwd()) {
     const config = loadPiLensGlobalConfig();
+    const projectConfig = loadPiLensProjectConfig(projectRoot);
     return {
-        getFlag(name) {
+        getFlag(name, filePath) {
             if (overrides && Object.hasOwn(overrides, name)) {
                 return overrides[name];
             }
-            return resolvePiLensFlag(name, undefined, config);
+            return resolvePiLensFlag(name, undefined, config, projectConfig, filePath, projectRoot);
         },
     };
 }

package/dist/clients/mcp/ipc.js

@@ -16,6 +16,8 @@ import * as crypto from "node:crypto";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
+export const WARM_DIAGNOSTICS_SCHEMA_VERSION = 1;
+export const WARM_CODE_ACTION_LOOKUP_LIMIT = 6;
 /**
  * Stable per-workspace endpoint path. The server (from its launch cwd) and the
  * hook (from the PostToolUse cwd) must resolve the same path — both hash the
@@ -36,6 +38,122 @@ export function ipcPathForCwd(cwd) {
     }
     return path.join(os.tmpdir(), `pi-lens-mcp-${hash}.sock`);
 }
+/** PID-scoped endpoint used by pi sessions. The legacy MCP analyze endpoint
+ * remains workspace-scoped for compatibility with the PostToolUse hook. */
+export function diagnosticsIpcPathForCwd(cwd, pid) {
+    const base = ipcPathForCwd(cwd);
+    if (process.platform === "win32")
+        return `${base}-diagnostics-${pid}`;
+    return base.replace(/\.sock$/, `-diagnostics-${pid}.sock`);
+}
+export function contentHash(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+/**
+ * Shared one-shot request/response transport for the warm-attach IPC routes
+ * (#822): connect to the incumbent's PID-scoped endpoint, write one JSON
+ * line, read one JSON line back, classify. The per-route `validate` callback
+ * returns a failure reason for an on-time but unusable reply (schema skew,
+ * staleness) or `undefined` to accept it; transport failures map uniformly to
+ * timeout/ipc-error. One transport, N routes — the diagnostics and
+ * code-action clients cannot drift apart.
+ */
+function requestOverWarmIpc(cwd, incumbentPid, timeoutMs, buildRequest, validate) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(value);
+        };
+        const deadlineAt = Date.now() + timeoutMs;
+        const socket = net.createConnection(diagnosticsIpcPathForCwd(cwd, incumbentPid));
+        socket.setEncoding("utf8");
+        let buffer = "";
+        const timer = setTimeout(() => finish({ available: false, reason: "timeout" }), timeoutMs);
+        timer.unref();
+        socket.on("connect", () => {
+            socket.write(`${JSON.stringify(buildRequest(deadlineAt))}\n`);
+        });
+        socket.on("data", (chunk) => {
+            buffer += chunk;
+            const newline = buffer.indexOf("\n");
+            if (newline === -1)
+                return;
+            try {
+                const message = JSON.parse(buffer.slice(0, newline));
+                const result = message.result;
+                if (message.error || !result) {
+                    finish({ available: false, reason: "ipc-error" });
+                    return;
+                }
+                const reason = validate(result, deadlineAt);
+                if (reason === undefined) {
+                    finish({ available: true, response: result });
+                }
+                else {
+                    finish({ available: false, reason });
+                }
+            }
+            catch {
+                finish({ available: false, reason: "schema-mismatch" });
+            }
+        });
+        socket.on("error", () => finish({ available: false, reason: "ipc-error" }));
+        socket.on("close", () => finish({ available: false, reason: "ipc-error" }));
+    });
+}
+export function requestWarmDiagnostics(cwd, incumbentPid, file, content, timeoutMs) {
+    const expectedHash = contentHash(content);
+    return requestOverWarmIpc(cwd, incumbentPid, timeoutMs, (deadlineAt) => ({
+        route: "diagnostics",
+        version: WARM_DIAGNOSTICS_SCHEMA_VERSION,
+        file,
+        cwd,
+        content,
+        contentHash: expectedHash,
+        deadlineAt,
+    }), (result, deadlineAt) => {
+        if (result.route !== "diagnostics" ||
+            result.version !== WARM_DIAGNOSTICS_SCHEMA_VERSION) {
+            return "schema-mismatch";
+        }
+        if (!result.fresh ||
+            result.inconclusive ||
+            result.contentHash !== expectedHash ||
+            result.servedAt > deadlineAt) {
+            return "stale-answer";
+        }
+        return undefined;
+    });
+}
+export function requestWarmCodeActions(cwd, incumbentPid, file, expectedContentHash, ranges, timeoutMs) {
+    return requestOverWarmIpc(cwd, incumbentPid, timeoutMs, (deadlineAt) => ({
+        route: "code-actions",
+        version: WARM_DIAGNOSTICS_SCHEMA_VERSION,
+        file,
+        cwd,
+        contentHash: expectedContentHash,
+        ranges,
+        deadlineAt,
+    }), (result, deadlineAt) => {
+        if (result.route !== "code-actions" ||
+            result.version !== WARM_DIAGNOSTICS_SCHEMA_VERSION ||
+            !Array.isArray(result.actions) ||
+            result.actions.length !== ranges.length ||
+            result.actions.some((actions) => !Array.isArray(actions))) {
+            return "schema-mismatch";
+        }
+        if (result.contentHash !== expectedContentHash ||
+            result.servedAt > deadlineAt) {
+            return "stale-answer";
+        }
+        return undefined;
+    });
+}
 /**
  * Ask the warm server to analyze a file. Resolves the server's result, or
  * `undefined` on ANY failure (no server, refused, stale socket, timeout, bad

package/dist/clients/mcp/session.js

@@ -58,7 +58,7 @@ function joinMessages(consumed) {
  */
 export async function runSessionStart(cwd) {
     const ctx = await getMcpSessionContext();
-    const host = createMcpHost();
+    const host = createMcpHost(undefined, cwd);
     await handleSessionStart({
         ctxCwd: cwd,
         // The MCP server has no TUI keystroke latency to protect, so the
@@ -112,7 +112,7 @@ export async function runSessionStart(cwd) {
  */
 export async function runTurnEnd(cwd, files = []) {
     const ctx = await getMcpSessionContext();
-    const host = createMcpHost();
+    const host = createMcpHost(undefined, cwd);
     let registered = 0;
     for (const file of files) {
         const abs = path.isAbsolute(file) ? file : path.resolve(cwd, file);

package/dist/clients/pipeline.js

@@ -315,9 +315,9 @@ async function tryDartFix(filePath) {
     return diffProjectSnapshot(pubspecDir, before);
 }
 // --- Pipeline phase helpers ---
-export async function runAutofix(filePath, cwd, getFlag, dbg, deps) {
+export async function runAutofix(filePath, cwd, getFlag, dbg, deps, getFlagSource) {
     const { biomeClient, ruffClient, fixedThisTurn } = deps;
-    const noAutofix = getFlag("no-autofix");
+    const noAutofix = getFlag("no-autofix", filePath);
     let fixedCount = 0;
     const autofixTools = [];
     const attemptedTools = [];
@@ -336,7 +336,8 @@ export async function runAutofix(filePath, cwd, getFlag, dbg, deps) {
         };
     }
     if (noAutofix) {
-        dbg(`autofix: skipped for ${filePath} (--no-autofix)`);
+        const source = getFlagSource?.("no-autofix", filePath);
+        dbg(`autofix: skipped for ${filePath} (--no-autofix${source ? `, source=${source}` : ""})`);
         return {
             fixedCount,
             autofixTools,
@@ -758,7 +759,7 @@ function buildEnrichedBlockerOutput(blockers, fileContent) {
 }
 // --- Main Pipeline ---
 export async function runPipeline(ctx, deps) {
-    const { filePath, cwd, toolName, getFlag, dbg } = ctx;
+    const { filePath, cwd, toolName, getFlag, getFlagSource, dbg } = ctx;
     const { getFormatService } = deps;
     const phase = createPhaseTracker(toolName, filePath);
     const pipelineStart = Date.now();
@@ -780,7 +781,7 @@ export async function runPipeline(ctx, deps) {
     let formattersUsed = [];
     let formatFailures = [];
     const piChangedFiles = new Set();
-    const autoformatDisabled = !!getFlag("no-autoformat");
+    const autoformatDisabled = !!getFlag("no-autoformat", filePath);
     const immediateFormat = !!getFlag("immediate-format");
     const formatDeferred = !autoformatDisabled && !immediateFormat && !!fileContent;
     if (!autoformatDisabled && immediateFormat && fileContent) {
@@ -808,6 +809,10 @@ export async function runPipeline(ctx, deps) {
     else if (formatDeferred) {
         dbg(`autoformat: deferred until agent_end for ${filePath}`);
     }
+    else if (autoformatDisabled) {
+        const source = getFlagSource?.("no-autoformat", filePath);
+        dbg(`autoformat: skipped for ${filePath} (--no-autoformat${source ? `, source=${source}` : ""})`);
+    }
     phase.end("format", {
         formattersUsed,
         formatChanged,
@@ -815,7 +820,7 @@ export async function runPipeline(ctx, deps) {
     });
     // --- 3. Auto-fix ---
     phase.start("autofix");
-    const { fixedCount, autofixTools, attemptedTools, changedFiles: autofixChangedFiles, needsContentRefresh: fixRefresh, skipReason: autofixSkipReason, } = await runAutofix(filePath, cwd, getFlag, dbg, deps);
+    const { fixedCount, autofixTools, attemptedTools, changedFiles: autofixChangedFiles, needsContentRefresh: fixRefresh, skipReason: autofixSkipReason, } = await runAutofix(filePath, cwd, getFlag, dbg, deps, getFlagSource);
     for (const changedFile of autofixChangedFiles) {
         piChangedFiles.add(path.resolve(changedFile));
     }

package/dist/clients/project-diagnostics/fresh-fetch.js

@@ -69,6 +69,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getKnipIgnorePatterns } from "../file-utils.js";
+import { isAtOrAboveHomeDir } from "../path-utils.js";
 import { GitleaksClient } from "../gitleaks-client.js";
 import { GovulncheckClient } from "../govulncheck-client.js";
 import { TrivyClient } from "../trivy-client.js";
@@ -107,8 +108,26 @@ function pushUnique(list, id) {
  * (see the module header for why this races rather than cancels in-flight
  * spawns).
  */
-export async function fetchFreshProjectDiagnostics(cacheManager, cwd, clients, signal) {
+export async function fetchFreshProjectDiagnostics(cacheManager, cwd, clients, signal, options = {}) {
     const analysisRoot = path.resolve(cwd);
+    // #747: refuse to spawn any heavyweight analyzer when the analysis root is
+    // at — or above — the home directory (the #250/#253 escape class). Every
+    // analyzer here treats `analysisRoot` as a whole tree to walk; from $HOME
+    // that means scanning every unrelated repo under it (observed: a jscpd run
+    // from a WSL home reached 44 GB RSS and OOM-killed the whole instance).
+    // Same ceiling as startup-scan.ts / runtime-session.ts's resolveSnapshotRoot
+    // / review-graph's buildOrUpdateGraph; like the latter, there is no safe
+    // substitute root to fall back to — the caller's `paths` scope only filters
+    // REPORTED results, it never narrows what these analyzers walk.
+    if (isAtOrAboveHomeDir(analysisRoot, options.homeDir)) {
+        return {
+            diagnostics: [],
+            runners: [],
+            cold: [...ANALYZER_IDS],
+            timings: {},
+            unsafeRoot: true,
+        };
+    }
     const diagnostics = [];
     const runners = [];
     const cold = [];

package/dist/clients/project-diagnostics/scanner.js

@@ -6,13 +6,14 @@ import { runProviders } from "../dispatch/fact-runner.js";
 import { FactStore } from "../dispatch/fact-store.js";
 import { canHandle as astGrepCanHandle, evaluateAstGrepRules, getLang as astGrepGetLang, loadSg, } from "../dispatch/runners/ast-grep-napi.js";
 import { isTestFile } from "../file-utils.js";
-import { collectSourceFilesAsync } from "../source-filter.js";
+import { isAtOrAboveHomeDir } from "../path-utils.js";
+import { getProjectDiagnosticsScannerMaxFiles } from "../project-scale.js";
+import { collectSourceFilesWithBudgetAsync } from "../source-filter.js";
 import { getSharedTreeSitterClient } from "../tree-sitter-shared.js";
 import { TreeSitterQueryLoader } from "../tree-sitter-query-loader.js";
 import { PROJECT_DIAGNOSTICS_CACHE_VERSION, saveProjectDiagnosticsSnapshot, } from "./cache.js";
 // Side-effect import: registers fact providers and fact rules.
 import "../dispatch/integration.js";
-const DEFAULT_MAX_FILES = 500;
 // Skip files this large: matches the per-edit ast-grep runner's guard so a single
 // generated megafile can't dominate a project scan.
 const AST_GREP_MAX_FILE_BYTES = 1024 * 1024;
@@ -196,10 +197,36 @@ async function scanAstGrepNapi(cwd, files) {
 export async function scanProjectDiagnostics(options) {
     const cwd = path.resolve(options.cwd);
     const { signal } = options;
-    const maxFiles = Math.max(1, options.maxFiles ?? DEFAULT_MAX_FILES);
-    const files = options.files
-        ? options.files.slice(0, maxFiles)
-        : await collectSourceFilesAsync(cwd, { maxFiles });
+    // #747/#250: refuse to WALK from a cwd at — or above — the home directory.
+    // The cheap tier is bounded by DEFAULT_MAX_FILES, but from $HOME it still
+    // traverses a huge unrelated tree until it happens to keep that many source
+    // files. An explicit `files` list (#461) is a caller-chosen subset, not a
+    // walk, so it is never refused here. Same ceiling as fresh-fetch.ts.
+    if (!options.files && isAtOrAboveHomeDir(cwd, options.homeDir)) {
+        return {
+            version: PROJECT_DIAGNOSTICS_CACHE_VERSION,
+            cwd,
+            tier: options.tier,
+            scannedAt: new Date().toISOString(),
+            diagnostics: [],
+            filesScanned: 0,
+            runners: [],
+            unsafeRoot: true,
+        };
+    }
+    const maxFiles = Math.max(1, options.maxFiles ?? getProjectDiagnosticsScannerMaxFiles(cwd));
+    // #760: bound the walk by entries VISITED, not just files kept — a mixed
+    // tree with few source files among a huge pile of non-source files never
+    // trips `maxFiles`. Unlike `unsafeRoot` this is not a refusal: when the
+    // budget trips we scan the truncated best-effort list and flag the snapshot
+    // so callers don't read the partial result as a complete sweep.
+    const collected = options.files
+        ? { files: options.files.slice(0, maxFiles), entryBudgetExceeded: false }
+        : await collectSourceFilesWithBudgetAsync(cwd, {
+            maxFiles,
+            maxScanEntries: options.maxScanEntries,
+        });
+    const files = collected.files;
     // Check cancellation at each phase boundary so a full-mode scan stops
     // promptly when the agent/user aborts (#341). The per-phase runners are
     // already file-capped, so phase granularity is enough to bound the work.
@@ -226,6 +253,10 @@ export async function scanProjectDiagnostics(options) {
         filesScanned: files.length,
         runners,
     };
+    // #760: only present when true — keeps existing snapshots/serializations
+    // byte-identical for the untruncated (normal) case.
+    if (collected.entryBudgetExceeded)
+        snapshot.scanTruncated = true;
     // A cancelled scan yields a partial snapshot; don't persist it as the
     // authoritative cross-session cache — only a complete run is cacheable.
     // Likewise, an explicit `files` scan (#461) only covers a caller-chosen