pi-lens 3.8.71 → 3.8.72

package/dist/clients/project-scale.js

@@ -0,0 +1,239 @@
+/**
+ * Single "project scale" knob deriving pi-lens's five independent
+ * project-size budgets (#776).
+ *
+ * Before this module, five subsystems each hardcoded their own file/entry
+ * ceiling and degraded independently as a repo grew:
+ *
+ *   - project-diagnostics scanner: 500 files  (clients/project-diagnostics/scanner.ts)
+ *   - review graph:               1,000 files (clients/runtime-config.ts)
+ *   - startup scan:               2,000 source files (clients/startup-scan.ts)
+ *   - jscpd:                      6,000 dir entries (clients/jscpd-client.ts)
+ *   - word index:                 6,000 files (clients/word-index.ts)
+ *
+ * A large-but-healthy (monorepo-scale) repo would trip these one at a time,
+ * silently, with no single lever to say "this repo is big; believe in it".
+ *
+ * This module centralizes the base value (`maxProjectFiles`, default 2,000 —
+ * chosen so every ratio below reproduces today's five defaults exactly) and
+ * exposes one `deriveBudget(ratio, cwd)` helper subsystems call instead of
+ * declaring their own local constant. Raising `maxProjectFiles` in one place
+ * scales all five budgets coherently; this refactor changes no default value.
+ *
+ * Ratio table (documents today's five defaults at the default base of 2,000):
+ *
+ *   | Subsystem                    | Ratio | Derived @ base 2,000 | Today  |
+ *   |-------------------------------|-------|----------------------|--------|
+ *   | project-diagnostics scanner   | 0.25× | 500                  | 500    |
+ *   | review graph (#775 R1: tapered above 4,000, see below) | 0.5× | 1,000 | 1,000 |
+ *   | startup scan (source files)   | 1×    | 2,000                | 2,000  |
+ *   | jscpd (dir entries)           | 3×    | 6,000                | 6,000  |
+ *   | word index (files)            | 3×    | 6,000                | 6,000  |
+ *
+ * The review graph is the ONE budget in this table that stops being a flat
+ * ratio above a threshold: {@link getReviewGraphMaxFilesDerived} tapers its
+ * growth toward a hard ceiling instead of scaling linearly forever (or
+ * cliff-dropping like the pre-#775 flat cap did) — see that function's doc
+ * comment for the full rationale. Every OTHER row in this table (and the
+ * review graph itself at or below the taper's linear boundary) is still the
+ * flat ratio shown.
+ *
+ * `maxProjectFiles` resolution order (highest priority first) — NOTE this is
+ * the base-value chain only; each subsystem's own PRE-EXISTING per-subsystem
+ * env override (e.g. `PI_LENS_REVIEW_GRAPH_MAX_FILES`,
+ * `PI_LENS_STARTUP_SCAN_MAX_ENTRIES`) is still checked at the call site
+ * BEFORE falling back to this module's derived value, so it always wins:
+ *
+ *   1. `maxProjectFiles` in the project's `.pi-lens.json` (per-project — see
+ *      `clients/project-lens-config.ts`). Requires a `cwd`; a call site with
+ *      no cwd in hand skips straight to (2).
+ *   2. `PI_LENS_MAX_PROJECT_FILES` environment variable.
+ *   3. Default: {@link DEFAULT_PROJECT_SCALE_BASE} (2,000).
+ *
+ * Two entry-UNIT budgets were deliberately left OUT of this derivation:
+ * `startup-scan.ts`'s `MAX_STARTUP_SCAN_ENTRIES` (50,000 directory entries)
+ * and `source-filter.ts`'s `DEFAULT_MAX_SCAN_ENTRIES` (200,000 directory
+ * entries). Both bound directory entries VISITED (a raw tree-walk safety
+ * valve, #758/#760), not source files KEPT — a very different quantity whose
+ * healthy ratio to file count varies wildly by project shape (a repo with a
+ * huge non-source data/asset tree needs a much larger entries budget than its
+ * source-file count would suggest). Coupling them to `maxProjectFiles` would
+ * risk silently changing behavior on exactly the pathological-tree shapes
+ * these ceilings exist to protect, for no behavior-neutral gain; they already
+ * have their own env overrides for callers who need to retune them. Left
+ * standalone per the issue's "derive or standalone, justify" instruction.
+ */
+import { lazyEnvNumber, toPositiveFinite } from "./env-utils.js";
+import { loadPiLensProjectConfig } from "./project-lens-config.js";
+/**
+ * Default base value: chosen so every ratio in the table above reproduces
+ * today's five hardcoded defaults exactly. Do not change without re-deriving
+ * every subsystem's default (that re-tuning is explicitly out of scope here —
+ * see #775).
+ */
+export const DEFAULT_PROJECT_SCALE_BASE = 2_000;
+const _envBase = lazyEnvNumber("PI_LENS_MAX_PROJECT_FILES", DEFAULT_PROJECT_SCALE_BASE);
+/** Test-only: clears the memoized `PI_LENS_MAX_PROJECT_FILES` read so a
+ * subsequent call re-reads the env var (matching the `_resetForTests`
+ * convention used across `env-utils.ts` consumers). */
+export function _resetProjectScaleBaseForTests() {
+    _envBase._resetForTests();
+}
+/**
+ * Resolve the base `maxProjectFiles` value.
+ *
+ * Pass the caller's project root as `cwd` whenever one is available — that's
+ * what lets a per-project `.pi-lens.json` override win. Call sites that only
+ * have a bare module-level constant today (no cwd in hand) may omit it; they
+ * fall back to the `PI_LENS_MAX_PROJECT_FILES` env var / default chain only
+ * (documented per-call-site in each subsystem's own comment).
+ */
+export function getProjectScaleBase(cwd) {
+    if (cwd) {
+        const config = loadPiLensProjectConfig(cwd);
+        const configBase = toPositiveFinite(config.maxProjectFiles);
+        if (configBase > 0)
+            return Math.floor(configBase);
+    }
+    return _envBase.get();
+}
+/**
+ * Ratios calibrated to reproduce today's five hardcoded defaults exactly at
+ * {@link DEFAULT_PROJECT_SCALE_BASE}. The unit each budget is expressed in
+ * stays subsystem-appropriate (files vs. directory entries); this table is
+ * the single place that encodes the relationship between them.
+ */
+export const PROJECT_SCALE_RATIOS = {
+    /** project-diagnostics scanner: files kept. 0.25 * 2,000 = 500. */
+    projectDiagnosticsScanner: 0.25,
+    /** review graph: files kept. 0.5 * 2,000 = 1,000. */
+    reviewGraph: 0.5,
+    /** startup scan: source files counted. 1 * 2,000 = 2,000. */
+    startupScan: 1,
+    /** jscpd: directory entries visited (its own gate, not source-filter's). 3 * 2,000 = 6,000. */
+    jscpd: 3,
+    /** word index: files indexed. 3 * 2,000 = 6,000. */
+    wordIndex: 3,
+};
+/**
+ * Scale a ratio from {@link PROJECT_SCALE_RATIOS} by the resolved base,
+ * rounding to the nearest integer and flooring at 1 (a budget of 0 would
+ * degrade every scan to "nothing scanned", never the intent of a large-repo
+ * knob).
+ */
+export function deriveBudget(ratio, cwd) {
+    return Math.max(1, Math.round(getProjectScaleBase(cwd) * ratio));
+}
+/** Derived project-diagnostics scanner budget (files). See {@link deriveBudget}. */
+export function getProjectDiagnosticsScannerMaxFiles(cwd) {
+    return deriveBudget(PROJECT_SCALE_RATIOS.projectDiagnosticsScanner, cwd);
+}
+/**
+ * Review-graph budget: adaptive taper (#775 R1).
+ *
+ * At or below {@link REVIEW_GRAPH_LINEAR_CEILING_BASE} this is IDENTICAL to
+ * the flat `PROJECT_SCALE_RATIOS.reviewGraph` (0.5x) ratio every other
+ * caller of {@link deriveBudget} still uses — every existing small/medium
+ * project derivation (including the default-base 1,000-file case) is
+ * bit-for-bit unchanged by this function.
+ *
+ * Above that base, growth SLOWS instead of continuing linearly (a monorepo
+ * with a huge `maxProjectFiles` would otherwise get an equally huge,
+ * untested review-graph budget) or cutting off at a cliff (today's actual
+ * bug: a flat cap truncates the graph to empty above it, per #775's top
+ * risk). A hyperbolic taper closes the gap to
+ * {@link REVIEW_GRAPH_HARD_CEILING} asymptotically, never reaching or
+ * exceeding it: at `base = REVIEW_GRAPH_LINEAR_CEILING_BASE +
+ * REVIEW_GRAPH_TAPER_SCALE`, exactly HALF the remaining gap to the ceiling
+ * is closed (a standard property of this taper shape) — e.g. base 12,000
+ * (6x default) derives ~3,500 files; base 20,000 (10x default) derives
+ * ~4,000.
+ *
+ * {@link REVIEW_GRAPH_HARD_CEILING} (5,000) is grounded FIRST by the
+ * strongest real constraint on this number — `review-graph/builder.ts`'s
+ * persist circuit-breaker (`GRAPH_PERSIST_MAX_ELEMENTS_DEFAULT`, 200,000
+ * graph elements: file/symbol nodes + cross-file edges). Above that element
+ * count the graph is NEVER persisted to disk (logged + skipped, #260's OOM
+ * guard) — not "slow", but PERMANENTLY uncached, so every session pays a
+ * full cold build instead of the ~20 ms cached path (see the CHANGELOG
+ * timing note below) engaging exactly once. For symbol-dense repos, element
+ * count runs on the order of ~30/file (file node + per-symbol nodes +
+ * import/call/reference edges), so a hard ceiling must leave real headroom
+ * below 200,000 elements, not creep up to it: 5,000 files x ~30 ⇒ ~150,000
+ * elements, a ~25% margin. The earlier 6,000-file candidate (~180,000
+ * elements) left too little margin — a slightly denser-than-average repo at
+ * exactly the ceiling could tip over and silently lose persistence forever,
+ * the opposite of this issue's "no silent caps" goal. 5,000 is also still
+ * coherent with the jscpd/wordIndex 3x-ratio precedent (6,000 at the
+ * default base) as "the ceiling sits just below that established top
+ * tier" rather than an exact match, so it isn't a fresh unrelated
+ * constant either.
+ *
+ * SECOND, independently, the number is consistent with the review graph's
+ * own measured per-file BUILD cost: CHANGELOG 3.8.43 ("Persist review graph
+ * to disk") documents a full cold tree-sitter + import-fact build taking
+ * "2-4 s" at the then-1,000-file cap — roughly 2-4 ms/file. 5,000 files at
+ * that rate is a ~10-20 s worst-case cold build — tolerable as a rare
+ * one-time cost when the persist cap above is respected (the disk-cached
+ * path costs "~20 ms JSON parse + rebuildIndexes" instead, and per-edit
+ * builds are incremental — see `diffSignatureMaps`). This build-time
+ * argument alone would tolerate a larger ceiling; the persist-cap margin
+ * above is the binding constraint.
+ */
+export const REVIEW_GRAPH_LINEAR_CEILING_BASE = 4_000;
+/**
+ * At `base = REVIEW_GRAPH_LINEAR_CEILING_BASE + REVIEW_GRAPH_TAPER_SCALE`
+ * the taper has closed exactly half the remaining gap to
+ * {@link REVIEW_GRAPH_HARD_CEILING} — see {@link taperedReviewGraphMaxFiles}.
+ */
+export const REVIEW_GRAPH_TAPER_SCALE = 8_000;
+/** See the rationale in {@link taperedReviewGraphMaxFiles}'s doc comment. */
+export const REVIEW_GRAPH_HARD_CEILING = 5_000;
+/**
+ * Pure taper function — see {@link getReviewGraphMaxFilesDerived}'s doc
+ * comment for the full rationale. Exported standalone so tests can probe
+ * the shape (below/at/above the linear boundary, ceiling asymptote)
+ * independent of `getProjectScaleBase`'s env/config resolution.
+ */
+export function taperedReviewGraphMaxFiles(base) {
+    const linearValue = base * PROJECT_SCALE_RATIOS.reviewGraph;
+    if (base <= REVIEW_GRAPH_LINEAR_CEILING_BASE) {
+        return Math.max(1, Math.round(linearValue));
+    }
+    const boundaryValue = REVIEW_GRAPH_LINEAR_CEILING_BASE * PROJECT_SCALE_RATIOS.reviewGraph;
+    const excess = base - REVIEW_GRAPH_LINEAR_CEILING_BASE;
+    const taperedExtra = (REVIEW_GRAPH_HARD_CEILING - boundaryValue) *
+        (excess / (excess + REVIEW_GRAPH_TAPER_SCALE));
+    return Math.max(1, Math.round(boundaryValue + taperedExtra));
+}
+/**
+ * Derived review-graph budget (files), honoring — in priority order — the
+ * project's `.pi-lens.json#reviewGraph.maxFiles` knob (#775 R2, an explicit
+ * opt-in for repos that want a bigger graph than the taper would derive;
+ * see `project-lens-config.ts`), then {@link taperedReviewGraphMaxFiles} of
+ * the resolved `maxProjectFiles` base. Callers still check their own
+ * PRE-EXISTING `PI_LENS_REVIEW_GRAPH_MAX_FILES` env override BEFORE calling
+ * this (see `review-graph/builder.ts#getReviewGraphMaxFiles`) — that always
+ * wins outright, unchanged by this function.
+ */
+export function getReviewGraphMaxFilesDerived(cwd) {
+    if (cwd) {
+        const config = loadPiLensProjectConfig(cwd);
+        const configOverride = config.reviewGraph?.maxFiles;
+        if (configOverride !== undefined)
+            return configOverride;
+    }
+    return taperedReviewGraphMaxFiles(getProjectScaleBase(cwd));
+}
+/** Derived startup-scan budget (source files). See {@link deriveBudget}. */
+export function getStartupScanMaxSourceFilesDerived(cwd) {
+    return deriveBudget(PROJECT_SCALE_RATIOS.startupScan, cwd);
+}
+/** Derived jscpd budget (directory entries). See {@link deriveBudget}. */
+export function getJscpdMaxEntriesDerived(cwd) {
+    return deriveBudget(PROJECT_SCALE_RATIOS.jscpd, cwd);
+}
+/** Derived word-index budget (files). See {@link deriveBudget}. */
+export function getWordIndexMaxFilesDerived(cwd) {
+    return deriveBudget(PROJECT_SCALE_RATIOS.wordIndex, cwd);
+}

package/dist/clients/project-scan-policy.js

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectIgnoreMatcher, isExcludedDirName, } from "./file-utils.js";
 import { isGeneratedArtifactDirectoryName, isGeneratedOrArtifact, } from "./generated-artifacts.js";
-import { collectSourceFiles, collectSourceFilesAsync, } from "./source-filter.js";
+import { collectSourceFiles, collectSourceFilesAsync, collectSourceFilesWithBudgetAsync, } from "./source-filter.js";
 export function shouldSkipProjectPath(filePath, options) {
     const isDirectory = options.isDirectory === true;
     const matcher = options.ignoreMatcher ?? getProjectIgnoreMatcher(options.rootDir);
@@ -47,3 +47,13 @@ export function collectProjectSourceFiles(rootDir, options) {
 export function collectProjectSourceFilesAsync(rootDir, options) {
     return collectSourceFilesAsync(rootDir, options);
 }
+/**
+ * Budget-aware twin of {@link collectProjectSourceFilesAsync} (#760): same
+ * walk, but returns `{ files, entryBudgetExceeded }` so a caller on a hot
+ * path (e.g. the per-edit cascade graph rebuild) can observe that the walk
+ * stopped at its `maxScanEntries` entry budget and got a truncated
+ * best-effort list rather than a complete enumeration.
+ */
+export function collectProjectSourceFilesWithBudgetAsync(rootDir, options) {
+    return collectSourceFilesWithBudgetAsync(rootDir, options);
+}

package/dist/clients/recent-touches.js

@@ -32,6 +32,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { writeFileAtomicAsync } from "./atomic-write.js";
 import { getProjectDataDir } from "./file-utils.js";
 import { normalizeFilePath } from "./path-utils.js";
 export const RECENT_TOUCHES_MAX_ENTRIES = 50;
@@ -71,27 +72,21 @@ async function readRecentTouchesAsync(cwd) {
         return { entries: [] };
     }
 }
-// --- Write (atomic tmp + rename, same pattern as instance-registry.ts) ---
+// --- Write (atomic tmp + rename via clients/atomic-write.ts, #762) ---
 async function writeRecentTouchesAsync(cwd, file) {
     const dir = getProjectDataDir(cwd);
     const target = recentTouchesPath(cwd);
-    const tmpPath = `${target}.tmp-${process.pid}`;
     try {
         await fs.promises.mkdir(dir, { recursive: true });
-        await fs.promises.writeFile(tmpPath, JSON.stringify(file), "utf-8");
-        await fs.promises.rename(tmpPath, target);
     }
     catch {
-        // Best-effort record — a failed write just means this batch of touches
+        // Best-effort record — a failed mkdir just means this batch of touches
         // never reaches other instances; never throw for the caller (the
         // producer seam is the fire-and-forget bus-publish path).
-        try {
-            await fs.promises.rm(tmpPath, { force: true });
-        }
-        catch {
-            // ignore
-        }
+        return;
     }
+    // bestEffort (default): same reasoning as the mkdir failure above.
+    await writeFileAtomicAsync(target, JSON.stringify(file));
 }
 /**
  * Append this process's touched paths to the shared record (read-modify-

package/dist/clients/review-graph/builder.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { writeFileAtomic } from "../atomic-write.js";
 import { fileContentProvider } from "../dispatch/facts/file-content.js";
+import { lazyEnvNumber } from "../env-utils.js";
 import { featureHintMetadata } from "../feature-hints.js";
 import { detectFileKind, KIND_EXTENSIONS } from "../file-kinds.js";
 import { detectFileRole } from "../file-role.js";
@@ -9,8 +11,9 @@ import { getProjectDataDir } from "../file-utils.js";
 import { collectUntrackedIgnoredIds } from "../git-tracked-ignore.js";
 import { logLatency } from "../latency-logger.js";
 import { isAtOrAboveHomeDir, normalizeFilePath, normalizeMapKey, } from "../path-utils.js";
-import { collectProjectSourceFilesAsync } from "../project-scan-policy.js";
-import { jsTsCandidatePaths, resolveImportToFiles } from "./import-resolvers.js";
+import { collectProjectSourceFilesWithBudgetAsync } from "../project-scan-policy.js";
+import { getReviewGraphMaxFilesDerived } from "../project-scale.js";
+import { jsTsCandidatePaths, resolveAliasedImport, resolveImportToFiles, resolveProjectReferenceImport, resolveWorkspacePackageImport, } from "./import-resolvers.js";
 import { RUNTIME_CONFIG } from "../runtime-config.js";
 import { buildQualifiedName, findOwnerName } from "../symbol-containment.js";
 import { getSharedTreeSitterClient } from "../tree-sitter-shared.js";
@@ -104,6 +107,7 @@ export function clearGraphCache() {
 export function clearReviewGraphWorkspaceCache() {
     _buildCache.clear();
     _workspaceGraphCache.clear();
+    _sizeSkipVerdicts.clear();
     _lastGraphBuildInfo = { reused: false, mode: "full", graphChanged: true };
 }
 // #300 Edge 2: the review-graph's cross-worktree isolation is INCIDENTAL to
@@ -169,6 +173,16 @@ function ensureIndexed(graph) {
  */
 export function getCachedReviewGraph(cwd) {
     const key = normalizeMapKey(cwd);
+    // #782: a fresh size-skip verdict means the LAST build attempt found the
+    // repo over the file cap — any graph cached/persisted from before that
+    // (necessarily built over a smaller file set, since the too_many_files
+    // branch never populates either cache tier) would silently under-report
+    // fan-in/blastRadius as if the repo were still that small. Stop serving it
+    // while the verdict is fresh rather than let it look current; it comes back
+    // automatically the moment the verdict expires (repo shrunk, or the cap was
+    // raised) and a build succeeds again.
+    if (getReviewGraphSizeSkipVerdict(cwd))
+        return undefined;
     const cached = _workspaceGraphCache.get(key);
     if (cached) {
         ensureIndexed(cached.graph);
@@ -360,11 +374,17 @@ function diffSignatureMaps(previous, next) {
     }
     return { added, removed, changed };
 }
-function getReviewGraphMaxFiles() {
+// #776: `PI_LENS_REVIEW_GRAPH_MAX_FILES` (the existing per-subsystem env
+// override) still wins outright; below it, the derived `maxProjectFiles`
+// scale-knob value (see `project-scale.ts`) replaces the old hardcoded
+// `RUNTIME_CONFIG.reviewGraph.maxFiles` constant as the fallback — the ratio
+// table reproduces that same 1,000-file default at the default base, so this
+// is behavior-neutral when nothing is configured.
+function getReviewGraphMaxFiles(cwd) {
     const override = Number.parseInt(process.env.PI_LENS_REVIEW_GRAPH_MAX_FILES ?? "", 10);
     return Number.isFinite(override) && override > 0
         ? override
-        : RUNTIME_CONFIG.reviewGraph.maxFiles;
+        : getReviewGraphMaxFilesDerived(cwd);
 }
 function getReviewGraphMaxFileBytes() {
     const override = Number.parseInt(process.env.PI_LENS_REVIEW_GRAPH_MAX_FILE_BYTES ?? "", 10);
@@ -380,6 +400,66 @@ function isWithinReviewGraphSizeLimit(file) {
         return false;
     }
 }
+// #782: a size-skipped build (too_many_files below) is otherwise
+// indistinguishable, at the read layer, from an ordinary cold cache — and a
+// graph cached/persisted BEFORE the repo crossed the cap kept being served by
+// getCachedReviewGraph forever. Recording a TTL'd "size-skip verdict" per cwd
+// fixes both: getCachedReviewGraph consults it below to stop serving a
+// pre-cap graph while the repo is confirmed over cap, and consumers
+// (project_report) can read it to render an honest "disabled, not cold" hint
+// instead of "retry shortly".
+//
+// In-memory only, per cwd, mirroring `_workspaceGraphCache` — not persisted
+// to disk. Every real caller either rebuilds within a session (the edit
+// pipeline, project_report's background trigger) or restarts the process (a
+// fresh in-memory verdict is recomputed on the very next build attempt), so
+// there's no cross-process staleness gap worth the extra persistence
+// machinery `too-many-source-files` needed (that verdict is cached across
+// process starts specifically to skip a slow walk — this one is a cheap
+// flag alongside a walk that already ran).
+//
+// TTL default matches project-report.ts's STALE_THRESHOLD_MS (15 minutes):
+// long enough that a single flag isn't thrashed by back-to-back builds, short
+// enough that a repo shrink or a `.pi-lens.json`/env cap raise is noticed
+// without restarting the process.
+const DEFAULT_REVIEW_GRAPH_SIZE_SKIP_TTL_MS = 15 * 60_000;
+const _sizeSkipTtl = lazyEnvNumber("PI_LENS_REVIEW_GRAPH_SIZE_SKIP_TTL_MS", DEFAULT_REVIEW_GRAPH_SIZE_SKIP_TTL_MS);
+/** Test-only: clears the memoized TTL so a subsequent call re-reads the env var. */
+export const _resetReviewGraphSizeSkipTtlForTests = _sizeSkipTtl._resetForTests;
+const _sizeSkipVerdicts = new Map();
+/** Test-only: clears every recorded size-skip verdict. */
+export function _resetReviewGraphSizeSkipVerdictsForTests() {
+    _sizeSkipVerdicts.clear();
+}
+function recordReviewGraphSizeSkip(cwd, sourceFileCount, maxFileCount) {
+    _sizeSkipVerdicts.set(normalizeMapKey(cwd), {
+        sourceFileCount,
+        maxFileCount,
+        skippedAt: Date.now(),
+    });
+}
+function clearReviewGraphSizeSkip(cwd) {
+    _sizeSkipVerdicts.delete(normalizeMapKey(cwd));
+}
+/**
+ * The most recent size-skip verdict for `cwd`, if one was recorded and it's
+ * still within its TTL — undefined once expired (a shrink or a raised cap
+ * gets re-checked on the next build attempt) or if no skip has ever been
+ * recorded. Consumers (project_report) use this to tell "graph disabled
+ * because the repo is over the file cap" apart from "cold cache, build in
+ * progress".
+ */
+export function getReviewGraphSizeSkipVerdict(cwd, now = Date.now()) {
+    const key = normalizeMapKey(cwd);
+    const verdict = _sizeSkipVerdicts.get(key);
+    if (!verdict)
+        return undefined;
+    if (now - verdict.skippedAt >= _sizeSkipTtl.get()) {
+        _sizeSkipVerdicts.delete(key);
+        return undefined;
+    }
+    return verdict;
+}
 async function getGraphSourceFiles(cwd) {
     // Async, chunked-yield walk (identical output to the sync collector) so the
     // per-edit cascade graph rebuild doesn't block the event loop on a large repo.
@@ -389,13 +469,28 @@ async function getGraphSourceFiles(cwd) {
     // and paying a statSync per file before the caller bails on count (#250). When
     // the cap is hit the caller skips the build on count alone, so the unfiltered
     // over-limit list is all it needs — see _doBuildGraph's too_many_files branch.
-    const maxGraphFiles = getReviewGraphMaxFiles();
-    const collected = await collectProjectSourceFilesAsync(cwd, {
+    const maxGraphFiles = getReviewGraphMaxFiles(cwd);
+    // #760: the maxFiles cap above bounds results FOUND, not entries VISITED —
+    // a mixed tree with few source files among a huge pile of non-source files
+    // never trips it. The walk's default entry budget (DEFAULT_MAX_SCAN_ENTRIES)
+    // bounds the visit count; a truncated best-effort list is acceptable for the
+    // graph (it degrades to a partial graph, same as maxFiles trimming), so just
+    // log the truncation for observability rather than failing the build.
+    const { files: collected, entryBudgetExceeded } = await collectProjectSourceFilesWithBudgetAsync(cwd, {
         // Only walk graph-relevant extensions so the cap counts what the graph
         // keeps (post-filter), not JSON/YAML/MD noise it would discard anyway.
         extensions: MAIN_KIND_EXTENSIONS,
         maxFiles: maxGraphFiles + 1,
     });
+    if (entryBudgetExceeded) {
+        logLatency({
+            type: "phase",
+            phase: "review_graph_source_walk_entry_budget",
+            filePath: cwd,
+            durationMs: 0,
+            metadata: { cwd, collectedFiles: collected.length },
+        });
+    }
     if (collected.length > maxGraphFiles) {
         // Contents are unused by the too_many_files branch; return the capped list
         // so the caller's `length > maxGraphFiles` check still trips.
@@ -616,6 +711,20 @@ function writePending(key) {
         // corrupt and silently forces a full rebuild. rename() replaces the
         // destination atomically on both POSIX and Windows (libuv uses
         // MOVEFILE_REPLACE_EXISTING).
+        //
+        // #762: intentionally NOT migrated onto clients/atomic-write.ts's
+        // writeFileAtomic/writeFileAtomicAsync. This callback-style writer
+        // (fs.mkdir/writeFile/rename, not fs.promises) logs a DIFFERENT,
+        // step-specific console.error per failure (mkdir vs write vs rename) so
+        // operators can tell which stage failed; the shared helper collapses all
+        // failures into one silent (bestEffort) or one rethrown (non-bestEffort)
+        // outcome and has no hook for per-step logging. Forcing this onto the
+        // helper would either lose that diagnostic granularity or require
+        // awaiting a promise-based helper from a plain `void`-returning
+        // fire-and-forget function, changing this path from non-blocking
+        // callback I/O to an async microtask chain. The sync exit-hook writer
+        // just below (`ensurePersistExitHook`) uses the shared helper instead —
+        // it has no per-step logging to preserve.
         const tmpPath = `${pending.cachePath}.tmp-${process.pid}`;
         fs.writeFile(tmpPath, json, "utf-8", (writeErr) => {
             if (writeErr) {
@@ -643,11 +752,10 @@ function ensurePersistExitHook() {
         for (const [, pending] of _pendingPersist) {
             try {
                 fs.mkdirSync(pending.cacheDir, { recursive: true });
-                // Same atomic tmp+rename as writePending: even at teardown a crash
-                // mid-write must not leave a truncated snapshot for the next start.
-                const tmpPath = `${pending.cachePath}.tmp-${process.pid}`;
-                fs.writeFileSync(tmpPath, JSON.stringify(pending.data), "utf-8");
-                fs.renameSync(tmpPath, pending.cachePath);
+                // Same atomic tmp+rename as writePending (via clients/atomic-write.ts,
+                // #762): even at teardown a crash mid-write must not leave a
+                // truncated snapshot for the next start.
+                writeFileAtomic(pending.cachePath, JSON.stringify(pending.data));
             }
             catch {
                 // Teardown is best-effort; a missed persist just re-confirms next start.
@@ -726,10 +834,30 @@ export function flushReviewGraphPersistsForTests() {
  * invariant (#243) reaches import-resolution-created nodes too, not just the
  * initial file walk. Undefined ⇒ no filtering (the fetch degraded or wasn't
  * requested).
+ *
+ * A bare specifier (`react`, `@scope/pkg[/subpath]`) is resolved against
+ * known workspace package names (#775) via `resolveWorkspacePackageImport` —
+ * the same resolver the cold module_report path (`resolveJsTs`) uses — before
+ * falling back to `undefined` (external dep, unchanged behavior).
  */
 function localImportToFile(cwd, filePath, source, ignoredIds) {
-    if (!source.startsWith("."))
+    if (!source.startsWith(".")) {
+        const aliased = resolveAliasedImport(cwd, source, path.dirname(filePath));
+        const referenced = aliased.length
+            ? []
+            : resolveProjectReferenceImport(cwd, source, path.dirname(filePath));
+        const resolved = aliased.length
+            ? aliased
+            : referenced.length
+                ? referenced
+                : resolveWorkspacePackageImport(cwd, source);
+        for (const normalized of resolved) {
+            if (ignoredIds?.has(normalized))
+                continue;
+            return normalized;
+        }
         return undefined;
+    }
     const root = path.resolve(cwd);
     for (const candidate of jsTsCandidatePaths(filePath, source)) {
         if (!candidate.startsWith(root) || !fs.existsSync(candidate))
@@ -772,6 +900,7 @@ async function ensureReviewGraphFacts(filePath, cwd, facts) {
         // populated before the graph reads them.
         await importFactProvider.run(ctx, facts);
         await functionFactProvider.run(ctx, facts);
+        // pi-lens-ignore: missing-error-propagation
     }
     catch (err) {
         console.error(`[pi-lens] review-graph structural facts disabled (degraded mode): ${err?.message ?? String(err)}`);
@@ -1689,7 +1818,7 @@ async function _doBuildGraph(cwd, changedFiles, facts, seqHint) {
     }
     const filesToBuild = await getGraphSourceFiles(cwd);
     const ignoredIds = await ignoredIdsPromise;
-    const maxGraphFiles = getReviewGraphMaxFiles();
+    const maxGraphFiles = getReviewGraphMaxFiles(cwd);
     if (filesToBuild.length > maxGraphFiles) {
         const graph = createEmptyGraph();
         graph.version = REVIEW_GRAPH_VERSION;
@@ -1697,6 +1826,29 @@ async function _doBuildGraph(cwd, changedFiles, facts, seqHint) {
         for (const file of normalizedChanged) {
             upsertChangedSymbols(graph, facts, file);
         }
+        // #782: record a TTL'd verdict so getCachedReviewGraph can stop serving
+        // any graph cached/persisted from before the repo crossed the cap, and so
+        // project_report can render an honest "disabled at N files" hint instead
+        // of "retry shortly" — see getReviewGraphSizeSkipVerdict.
+        recordReviewGraphSizeSkip(cwd, filesToBuild.length, maxGraphFiles);
+        // #775 R3: `_lastGraphBuildInfo`/the size-skip verdict above are only
+        // SURFACED by callers that happen to read them (dispatch/integration.ts's
+        // cascade path logs a `graph_build` phase; lens-map.ts, project-report.ts,
+        // mcp/analyze.ts, runtime-session.ts, and tree-sitter.ts's runner do not).
+        // Log unconditionally here, at the one place every caller funnels through,
+        // so a monorepo crossing the cap is never a SILENT truncation — no caller
+        // wiring required (AGENTS.md: no silent caps).
+        logLatency({
+            type: "phase",
+            phase: "review_graph_size_skip",
+            filePath: cwd,
+            durationMs: 0,
+            metadata: {
+                cwd,
+                sourceFileCount: filesToBuild.length,
+                maxFileCount: maxGraphFiles,
+            },
+        });
         _lastGraphBuildInfo = {
             reused: false,
             mode: "skipped",
@@ -1713,6 +1865,11 @@ async function _doBuildGraph(cwd, changedFiles, facts, seqHint) {
         facts.setSessionFact("session.reviewGraph", graph);
         return graph;
     }
+    // #782: the repo is within the cap on this build attempt — drop any
+    // previously recorded size-skip verdict immediately (rather than waiting
+    // out the TTL) so a shrink or a raised cap re-enables reads the moment a
+    // build actually succeeds.
+    clearReviewGraphSizeSkip(cwd);
     const fileSignatures = await sourceSignatureMapAsync(filesToBuild);
     const signature = sourceSignatureFromMap(fileSignatures);
     // Tier 1: in-memory cache (hot path — same process, already built this session)