pi-lens 3.8.22 → 3.8.24

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to pi-lens will be documented in this file.
 
+## [Unreleased]
+
+## [3.8.24] - 2026-04-12
+
+### Changed
+- **Lazy bootstrap client loading** — startup now defers heavy client initialization behind a shared bootstrap promise, reducing first-turn startup overhead while preserving tool behavior.
+- **LSP config discovery scope** — `.pi-lens/lsp.json` (and related config paths) are now resolved from the current directory up through parent directories, improving nested-workspace support.
+- **Ruby server fallback chain** — Ruby LSP startup now tries `ruby-lsp`, then `solargraph`, then `rubocop --lsp` for broader environment compatibility.
+
+### Fixed
+- **LSP config activation timing** — LSP server config initialization now runs reliably at `session_start` and before LSP-backed `tool_call` operations, so server enable/disable overrides apply in one-shot and interactive sessions.
+
+## [3.8.23] - 2026-04-12
+
+### Added
+- **LSP auto-touch warm-up** — tool-call flow now proactively opens/syncs supported files (`read`/`write`/`edit`/`lsp_navigation`) so LSP clients warm up earlier and first semantic requests are less likely to return cold-start empties.
+
+### Changed
+- **Ruby LSP spawn resilience on Windows** — Ruby command discovery now tries `ruby-lsp`/`solargraph` from PATH plus common Ruby install locations before marking servers unavailable.
+- **LSP diagnostics dedupe strategy** — multi-server diagnostics aggregation now dedupes using a simpler key (`line`, `character`, `message`) to better collapse equivalent findings across servers.
+- **Windows LSP PATH fallback** — language-server spawns now augment PATH with common user-level tool locations (`.cargo\bin`, `go\bin`, common Ruby bin dirs) to improve server discovery on Windows shells.
+
+### Fixed
+- **LSP diagnostics key normalization** — publish diagnostics now store/update using normalized file-path keys, fixing Windows path mismatches that could hide diagnostics in some languages.
+- **Pull diagnostics fallback path** — when a server advertises pull diagnostics, `textDocument/diagnostic` is now attempted before push-wait fallback.
+- **Navigation diagnostics/health observability** — `lsp_navigation` and diagnostics aggregation now emit explicit `failureKind`/health metadata to latency logs and tool details for faster root-cause triage (`no_server`, `unsupported`, `empty_result`, `lsp_error`, etc.).
+- **Scoped workspaceDiagnostics collection** — `workspaceDiagnostics` with `filePath` now forces file-level diagnostics collection (instead of only returning tracked snapshots), including pull-mode aggregation metadata.
+- **Rust pull diagnostics cold-start handling** — pull diagnostics now retry briefly and then fall back to push-wait if pull responses remain empty, improving first-hit Rust diagnostic reliability.
+- **Context injection message role validity** — session-start guidance is now injected as `user` context (valid `AgentMessage` role), preventing dropped context on providers that reject/ignore `system` in this path.
+
 ## [3.8.22] - 2026-04-09
 
 ### Changed

package/clients/bootstrap.ts

@@ -0,0 +1,106 @@
+import type { AgentBehaviorClient } from "./agent-behavior-client.js";
+import type { ArchitectClient } from "./architect-client.js";
+import type { BiomeClient } from "./biome-client.js";
+import type { ComplexityClient } from "./complexity-client.js";
+import type { DependencyChecker } from "./dependency-checker.js";
+import type { GoClient } from "./go-client.js";
+import type { JscpdClient } from "./jscpd-client.js";
+import type { KnipClient } from "./knip-client.js";
+import type { MetricsClient } from "./metrics-client.js";
+import type { RuffClient } from "./ruff-client.js";
+import type { RustClient } from "./rust-client.js";
+import type { TestRunnerClient } from "./test-runner-client.js";
+import type { TodoScanner } from "./todo-scanner.js";
+import type { TypeCoverageClient } from "./type-coverage-client.js";
+
+export interface BootstrapClients {
+	ruffClient: RuffClient;
+	biomeClient: BiomeClient;
+	knipClient: KnipClient;
+	todoScanner: TodoScanner;
+	jscpdClient: JscpdClient;
+	typeCoverageClient: TypeCoverageClient;
+	depChecker: DependencyChecker;
+	testRunnerClient: TestRunnerClient;
+	metricsClient: MetricsClient;
+	complexityClient: ComplexityClient;
+	architectClient: ArchitectClient;
+	goClient: GoClient;
+	rustClient: RustClient;
+	agentBehaviorClient: AgentBehaviorClient;
+}
+
+let bootstrapPromise: Promise<BootstrapClients> | null = null;
+
+function createArchitectFallback(): ArchitectClient {
+	return {
+		loadConfig: () => false,
+		isUserDefined: () => false,
+		hasConfig: () => false,
+		getRulesForFile: () => [],
+		checkFile: () => [],
+		checkFileSize: () => null,
+		getHints: () => [],
+	} as unknown as ArchitectClient;
+}
+
+export function loadBootstrapClients(): Promise<BootstrapClients> {
+	bootstrapPromise ??= (async () => {
+		const [
+			ruffMod,
+			biomeMod,
+			knipMod,
+			todoMod,
+			jscpdMod,
+			typeCoverageMod,
+			depCheckerMod,
+			testRunnerMod,
+			metricsMod,
+			complexityMod,
+			goMod,
+			rustMod,
+			agentBehaviorMod,
+		] = await Promise.all([
+			import("./ruff-client.js"),
+			import("./biome-client.js"),
+			import("./knip-client.js"),
+			import("./todo-scanner.js"),
+			import("./jscpd-client.js"),
+			import("./type-coverage-client.js"),
+			import("./dependency-checker.js"),
+			import("./test-runner-client.js"),
+			import("./metrics-client.js"),
+			import("./complexity-client.js"),
+			import("./go-client.js"),
+			import("./rust-client.js"),
+			import("./agent-behavior-client.js"),
+		]);
+
+		let architectClient: ArchitectClient;
+		try {
+			const architectMod = await import("./architect-client.js");
+			architectClient = new architectMod.ArchitectClient();
+		} catch {
+			architectClient = createArchitectFallback();
+		}
+
+		return {
+			ruffClient: new ruffMod.RuffClient(),
+			biomeClient: new biomeMod.BiomeClient(),
+			knipClient: new knipMod.KnipClient(),
+			todoScanner: new todoMod.TodoScanner(),
+			jscpdClient: new jscpdMod.JscpdClient(),
+			typeCoverageClient: new typeCoverageMod.TypeCoverageClient(),
+			depChecker: new depCheckerMod.DependencyChecker(),
+			testRunnerClient: new testRunnerMod.TestRunnerClient(),
+			metricsClient: new metricsMod.MetricsClient(),
+			complexityClient: new complexityMod.ComplexityClient(),
+			architectClient,
+			goClient: new goMod.GoClient(),
+			rustClient: new rustMod.RustClient(),
+			agentBehaviorClient: new agentBehaviorMod.AgentBehaviorClient(),
+		};
+	})();
+
+	return bootstrapPromise;
+}

package/clients/dispatch/dispatcher.ts

@@ -25,9 +25,10 @@ import { normalizeMapKey } from "../path-utils.js";
 import { RUNTIME_CONFIG } from "../runtime-config.js";
 import { safeSpawnAsync } from "../safe-spawn.js";
 import { classifyDiagnostic } from "./diagnostic-taxonomy.js";
+import { FactStore } from "./fact-store.js";
 import { resolveRunnerPath } from "./runner-context.js";
+import { getToolProfile } from "./tool-profile.js";
 import type {
-	BaselineStore,
 	Diagnostic,
 	DispatchContext,
 	DispatchResult,
@@ -35,88 +36,78 @@ import type {
 	PiAgentAPI,
 	RunnerDefinition,
 	RunnerGroup,
+	RunnerRegistry as RunnerRegistryContract,
 	RunnerResult,
 } from "./types.js";
 import { formatDiagnostics } from "./utils/format-utils.js";
 
-// --- In-Memory Baseline Store ---
+// --- Runner Registry ---
 
-export function createBaselineStore(): BaselineStore {
-	const baselines = new Map<string, unknown[]>();
+export class RunnerRegistry implements RunnerRegistryContract {
+	private readonly runners = new Map<string, RunnerDefinition>();
 
-	return {
-		get(filePath) {
-			return baselines.get(normalizeMapKey(filePath));
-		},
-		set(filePath, diagnostics) {
-			baselines.set(normalizeMapKey(filePath), diagnostics);
-		},
-		clear() {
-			baselines.clear();
-		},
-	};
-}
-
-// --- Runner Registry ---
+	register(runner: RunnerDefinition): void {
+		if (this.runners.has(runner.id)) return;
+		this.runners.set(runner.id, runner);
+	}
 
-const globalRegistry = new Map<string, RunnerDefinition>();
+	get(id: string): RunnerDefinition | undefined {
+		return this.runners.get(id);
+	}
 
-export function registerRunner(runner: RunnerDefinition): void {
-	if (globalRegistry.has(runner.id)) return; // Already registered, skip silently
-	globalRegistry.set(runner.id, runner);
-}
+	getForKind(kind: FileKind, filePath?: string): RunnerDefinition[] {
+		const matching: RunnerDefinition[] = [];
+		const isTest = filePath ? isTestFile(filePath) : false;
 
-export function getRunner(id: string): RunnerDefinition | undefined {
-	return globalRegistry.get(id);
-}
+		for (const runner of this.runners.values()) {
+			if (isTest && runner.skipTestFiles) continue;
+			if (runner.appliesTo.includes(kind) || runner.appliesTo.length === 0) {
+				matching.push(runner);
+			}
+		}
 
-export function getRunnersForKind(
-	kind: FileKind | undefined,
-	filePath?: string,
-): RunnerDefinition[] {
-	if (!kind) return [];
-	const runners: RunnerDefinition[] = [];
-	const isTest = filePath ? isTestFile(filePath) : false;
+		return matching.sort((a, b) => a.priority - b.priority);
+	}
 
-	for (const runner of globalRegistry.values()) {
-		// Skip runners that shouldn't run on test files
-		if (isTest && runner.skipTestFiles) continue;
+	list(): RunnerDefinition[] {
+		return Array.from(this.runners.values());
+	}
 
-		if (runner.appliesTo.includes(kind) || runner.appliesTo.length === 0) {
-			runners.push(runner);
-		}
+	clear(): void {
+		this.runners.clear();
 	}
-	return runners.sort((a, b) => a.priority - b.priority);
 }
 
-export function listRunners(): RunnerDefinition[] {
-	return Array.from(globalRegistry.values());
-}
+// --- Tool Availability Cache ---
 
 /**
- * Clear all registered runners. Used primarily for testing.
+ * Normalize a command name to a FactStore session key.
+ * Strips .cmd/.exe suffixes (case-insensitive) and lowercases,
+ * then prefixes with "session.toolCache.".
  */
-export function clearRunnerRegistry(): void {
-	globalRegistry.clear();
+export function normalizeCacheKey(cmd: string): string {
+	const normalized = cmd.replace(/\.(cmd|exe)$/i, "").toLowerCase();
+	return `session.toolCache.${normalized}`;
 }
 
-// --- Tool Availability Cache ---
-
-const toolCache = new Map<string, boolean>();
-
-async function checkToolAvailability(command: string): Promise<boolean> {
-	if (toolCache.has(command)) {
-		return toolCache.get(command)!;
+async function checkToolAvailability(
+	command: string,
+	facts: FactStore,
+): Promise<boolean> {
+	const key = normalizeCacheKey(command);
+	const cached = facts.getSessionFact<boolean>(key);
+	if (cached !== undefined) {
+		return cached;
 	}
 	try {
 		const result = await safeSpawnAsync(command, ["--version"], {
 			timeout: 5000,
 		});
 		const available = result.status === 0;
-		toolCache.set(command, available);
+		facts.setSessionFact(key, available);
 		return available;
 	} catch {
-		toolCache.set(command, false);
+		facts.setSessionFact(key, false);
 		return false;
 	}
 }
@@ -127,7 +118,7 @@ export function createDispatchContext(
 	filePath: string,
 	cwd: string,
 	pi: PiAgentAPI,
-	baselines?: BaselineStore,
+	facts: FactStore,
 	blockingOnly?: boolean,
 	modifiedRanges?: import("./types.js").ModifiedRange[],
 ): DispatchContext {
@@ -144,12 +135,12 @@ export function createDispatchContext(
 		pi,
 		autofix: !!(pi.getFlag("autofix-biome") || pi.getFlag("autofix-ruff")),
 		deltaMode: !pi.getFlag("no-delta"),
-		baselines: baselines ?? createBaselineStore(),
+		facts,
 		blockingOnly,
 		modifiedRanges,
 
 		async hasTool(command: string): Promise<boolean> {
-			return checkToolAvailability(command);
+			return checkToolAvailability(command, facts);
 		},
 
 		log(message: string): void {
@@ -186,14 +177,7 @@ function semanticRank(semantic: OutputSemantic): number {
 }
 
 function toolPriority(tool: string, defectClass: string): number {
-	const t = tool.toLowerCase();
-	if (defectClass === "silent-error" && t === "tree-sitter") return 200;
-	if (t === "lsp" || t === "ts-lsp") return 120;
-	if (t === "eslint") return 110;
-	if (t.includes("biome")) return 100;
-	if (t === "tree-sitter") return 90;
-	if (t.includes("ast-grep")) return 80;
-	return 50;
+	return getToolProfile(tool, defectClass).dedupPriority;
 }
 
 function dedupeOverlappingDiagnostics(diagnostics: Diagnostic[]): Diagnostic[] {
@@ -228,19 +212,7 @@ function suppressLintOverlapsWithLsp(diagnostics: Diagnostic[]): Diagnostic[] {
 	const lspBySpanClass = new Set<string>();
 	const lspByLine = new Set<string>();
 	const isLintTool = (tool: string): boolean => {
-		const t = tool.toLowerCase();
-		return (
-			t === "eslint" ||
-			t.includes("biome") ||
-			t === "ruff-lint" ||
-			t === "oxlint" ||
-			t === "rubocop" ||
-			t === "go-vet" ||
-			t === "golangci-lint" ||
-			t === "rust-clippy" ||
-			t === "shellcheck" ||
-			t === "type-safety"
-		);
+		return getToolProfile(tool).lintLike;
 	};
 
 	for (const d of diagnostics) {
@@ -455,6 +427,7 @@ interface GroupResult {
 async function runGroup(
 	ctx: DispatchContext,
 	group: RunnerGroup,
+	registry: RunnerRegistryContract,
 ): Promise<GroupResult> {
 	const diagnostics: Diagnostic[] = [];
 	const latencies: RunnerLatency[] = [];
@@ -463,16 +436,16 @@ async function runGroup(
 	// Filter runners by kind if specified
 	const runnerIds = group.filterKinds
 		? group.runnerIds.filter((id) => {
-				const runner = getRunner(id);
+				const runner = registry.get(id);
 				return runner && ctx.kind && group.filterKinds?.includes(ctx.kind);
-			})
+		  })
 		: group.runnerIds;
 
 	const semantic = group.semantic ?? "warning";
 
 	for (const runnerId of runnerIds) {
 		const runnerStart = Date.now();
-		const runner = getRunner(runnerId);
+		const runner = registry.get(runnerId);
 
 		if (!runner) {
 			latencies.push({
@@ -576,6 +549,7 @@ async function runGroup(
 export async function dispatchForFile(
 	ctx: DispatchContext,
 	groups: RunnerGroup[],
+	registry: RunnerRegistryContract,
 ): Promise<DispatchResult> {
 	const _overallStart = Date.now();
 	const allDiagnostics: Diagnostic[] = [];
@@ -602,14 +576,16 @@ export async function dispatchForFile(
 	// preserved (sequential first-success). Results are merged in original
 	// group order so output is deterministic.
 	const groupResults = await Promise.all(
-		groups.map((group) => runGroup(ctx, group)),
+		groups.map((group) => runGroup(ctx, group, registry)),
 	);
 
 	// 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.baselines.get(ctx.filePath) as Diagnostic[] | undefined) ??
-			(ctx.baselines.get(relativeKey) as Diagnostic[] | undefined))
+		? (ctx.facts.getSessionFact<Diagnostic[]>(baselineAbsKey) ??
+			ctx.facts.getSessionFact<Diagnostic[]>(baselineRelKey))
 		: undefined;
 	const baselineWarnings = previousBaseline?.filter(
 		(d) => d.semantic === "warning" || d.semantic === "none",
@@ -641,8 +617,8 @@ export async function dispatchForFile(
 
 	// Persist full current snapshot for next run (not delta-filtered subset).
 	if (ctx.deltaMode) {
-		ctx.baselines.set(ctx.filePath, [...dedupedDiagnostics]);
-		ctx.baselines.set(relativeKey, [...dedupedDiagnostics]);
+		ctx.facts.setSessionFact(baselineAbsKey, [...dedupedDiagnostics]);
+		ctx.facts.setSessionFact(baselineRelKey, [...dedupedDiagnostics]);
 	}
 
 	// Categorize results
@@ -805,17 +781,25 @@ async function runRunner(
 
 // --- Simple Integration Helper ---
 
+/**
+ * @internal
+ * Low-level dispatch entry point. Use `dispatchLint` from `./integration.js` instead —
+ * that version provides session-persistent baselines and FactStore.
+ * This function creates an ephemeral FactStore per call; facts do not persist across calls.
+ */
 export async function dispatchLint(
 	filePath: string,
 	cwd: string,
 	pi: PiAgentAPI,
-	baselines?: BaselineStore,
+	facts: FactStore,
+	registry: RunnerRegistryContract,
 ): Promise<string> {
 	// By default, only run BLOCKING rules for fast feedback on file write
-	const ctx = createDispatchContext(filePath, cwd, pi, baselines, true);
+	const ctx = createDispatchContext(filePath, cwd, pi, facts, true);
 
 	// Get runners for this file kind
-	const runners = getRunnersForKind(ctx.kind);
+	if (!ctx.kind) return "";
+	const runners = registry.getForKind(ctx.kind, ctx.filePath);
 	if (runners.length === 0) {
 		return "";
 	}
@@ -828,6 +812,6 @@ export async function dispatchLint(
 		},
 	];
 
-	const result = await dispatchForFile(ctx, groups);
+	const result = await dispatchForFile(ctx, groups, registry);
 	return result.output;
 }

package/clients/dispatch/fact-provider-types.ts

@@ -0,0 +1,22 @@
+import type { FactStore, ReadonlyFactStore } from "./fact-store.js";
+import type { DispatchContext } from "./types.js";
+
+export interface FactProvider {
+  /** e.g. "fact.file.content" */
+  id: string;
+  /** Keys this provider writes, e.g. ["file.content", "file.lineCount"] */
+  provides: string[];
+  /** Keys that must exist in the store before this provider runs */
+  requires: string[];
+  appliesTo(ctx: DispatchContext): boolean;
+  run(ctx: DispatchContext, store: FactStore): Promise<void> | void;
+}
+
+export interface FactRule {
+  /** e.g. "rule.defensive.error-obscuring" */
+  id: string;
+  /** Keys required from the store — rule is skipped if any are absent */
+  requires: string[];
+  appliesTo(ctx: DispatchContext): boolean;
+  evaluate(ctx: DispatchContext, store: ReadonlyFactStore): import("./types.js").Diagnostic[];
+}

package/clients/dispatch/fact-rule-runner.ts

@@ -0,0 +1,22 @@
+import type { FactRule } from "./fact-provider-types.js";
+import type { Diagnostic, DispatchContext } from "./types.js";
+
+const rules: FactRule[] = [];
+
+export function registerRule(r: FactRule): void {
+  rules.push(r);
+}
+
+export function clearRules(): void {
+  rules.length = 0;
+}
+
+export function evaluateRules(ctx: DispatchContext): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  for (const rule of rules) {
+    if (!rule.appliesTo(ctx)) continue;
+    const results = rule.evaluate(ctx, ctx.facts);
+    diagnostics.push(...results);
+  }
+  return diagnostics;
+}

package/clients/dispatch/fact-runner.ts

@@ -0,0 +1,28 @@
+import type { FactProvider } from "./fact-provider-types.js";
+import type { DispatchContext } from "./types.js";
+import { scheduleProviders } from "./fact-scheduler.js";
+
+const providers: FactProvider[] = [];
+
+export function registerProvider(p: FactProvider): void {
+  providers.push(p);
+}
+
+export function clearProviders(): void {
+  providers.length = 0;
+}
+
+export async function runProviders(ctx: DispatchContext): Promise<void> {
+  const applicable = providers.filter((p) => p.appliesTo(ctx));
+  const ordered = scheduleProviders(applicable);
+
+  for (const provider of ordered) {
+    // Skip if all provided facts are already present
+    const allPresent = provider.provides.every((key) =>
+      ctx.facts.hasFileFact(ctx.filePath, key),
+    );
+    if (allPresent) continue;
+
+    await provider.run(ctx, ctx.facts);
+  }
+}

package/clients/dispatch/fact-scheduler.ts

@@ -0,0 +1,78 @@
+import type { FactProvider } from "./fact-provider-types.js";
+
+/**
+ * Orders providers topologically so each provider's `requires` are satisfied
+ * before it runs. Tie-breaks alphabetically by `id`. Detects cycles.
+ *
+ * Only deps that have a provider in the input list count toward in-degree;
+ * external facts (provided outside this list) are treated as always available.
+ */
+export function scheduleProviders(providers: FactProvider[]): FactProvider[] {
+  if (providers.length <= 1) return providers.slice();
+
+  // Map: factKey → provider that provides it
+  const factToProvider = new Map<string, FactProvider>();
+  for (const p of providers) {
+    for (const key of p.provides) {
+      factToProvider.set(key, p);
+    }
+  }
+
+  // For each provider, track in-degree and which providers depend on it
+  const inDegree = new Map<string, number>();
+  // dependents[id] = set of provider ids that require a fact provided by this provider
+  const dependents = new Map<string, Set<string>>();
+
+  for (const p of providers) {
+    if (!inDegree.has(p.id)) inDegree.set(p.id, 0);
+    if (!dependents.has(p.id)) dependents.set(p.id, new Set());
+  }
+
+  for (const p of providers) {
+    const seenDeps = new Set<string>();
+    for (const req of p.requires) {
+      const dep = factToProvider.get(req);
+      if (dep && dep.id !== p.id && !seenDeps.has(dep.id)) {
+        seenDeps.add(dep.id);
+        inDegree.set(p.id, (inDegree.get(p.id) ?? 0) + 1);
+        dependents.get(dep.id)!.add(p.id);
+      }
+    }
+  }
+
+  const idToProvider = new Map<string, FactProvider>(providers.map((p) => [p.id, p]));
+
+  // Start with providers that have no unsatisfied deps, sorted by id
+  let wave = providers
+    .filter((p) => (inDegree.get(p.id) ?? 0) === 0)
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const result: FactProvider[] = [];
+
+  while (wave.length > 0) {
+    const nextWave: FactProvider[] = [];
+    for (const p of wave) {
+      result.push(p);
+      for (const depId of dependents.get(p.id) ?? []) {
+        const newDegree = (inDegree.get(depId) ?? 0) - 1;
+        inDegree.set(depId, newDegree);
+        if (newDegree === 0) {
+          nextWave.push(idToProvider.get(depId)!);
+        }
+      }
+    }
+    wave = nextWave.sort((a, b) => a.id.localeCompare(b.id));
+  }
+
+  if (result.length < providers.length) {
+    const cycleParticipants = providers
+      .filter((p) => !result.includes(p))
+      .map((p) => p.id)
+      .sort();
+    throw new Error(
+      `Cycle detected among FactProviders: ${cycleParticipants.join(", ")}`,
+    );
+  }
+
+  return result;
+}

package/clients/dispatch/fact-store.ts

@@ -0,0 +1,67 @@
+import { normalizeMapKey } from "../path-utils.js";
+
+type FactValue = unknown;
+
+export interface ReadonlyFactStore {
+  getFileFact<T>(filePath: string, factId: string): T | undefined;
+  hasFileFact(filePath: string, factId: string): boolean;
+  getSessionFact<T>(factId: string): T | undefined;
+  hasSessionFact(factId: string): boolean;
+}
+
+export class FactStore implements ReadonlyFactStore {
+  private readonly fileFacts = new Map<string, Map<string, FactValue>>();
+  private readonly sessionFacts = new Map<string, FactValue>();
+
+  // All file-keyed methods normalize the path internally via normalizeMapKey().
+  // Callers always pass raw/resolved paths — normalization is not their concern.
+
+  getFileFact<T>(filePath: string, factId: string): T | undefined {
+    return this.fileFacts.get(normalizeMapKey(filePath))?.get(factId) as T | undefined;
+  }
+
+  setFileFact(filePath: string, factId: string, value: FactValue): void {
+    const key = normalizeMapKey(filePath);
+    let facts = this.fileFacts.get(key);
+    if (!facts) {
+      facts = new Map();
+      this.fileFacts.set(key, facts);
+    }
+    facts.set(factId, value);
+  }
+
+  hasFileFact(filePath: string, factId: string): boolean {
+    return this.fileFacts.get(normalizeMapKey(filePath))?.has(factId) ?? false;
+  }
+
+  /** Clear facts for one specific file only. Use at the start of each per-file dispatch call.
+   *  Preserves facts for other files computed in the same turn.
+   *  Normalizes filePath internally — callers pass raw paths. */
+  clearFileFactsFor(filePath: string): void {
+    this.fileFacts.delete(normalizeMapKey(filePath));
+  }
+
+  /** Clear all file facts across all paths. Reserve for explicit full resets only —
+   *  do NOT use in the normal per-file dispatch path. */
+  clearFileFacts(): void {
+    this.fileFacts.clear();
+  }
+
+  getSessionFact<T>(factId: string): T | undefined {
+    return this.sessionFacts.get(factId) as T | undefined;
+  }
+
+  setSessionFact(factId: string, value: FactValue): void {
+    this.sessionFacts.set(factId, value);
+  }
+
+  hasSessionFact(factId: string): boolean {
+    return this.sessionFacts.has(factId);
+  }
+
+  /** Call on session reset only. Clears everything including tool cache and baselines. */
+  clearAll(): void {
+    this.fileFacts.clear();
+    this.sessionFacts.clear();
+  }
+}