pi-supernova 0.10.1 → 0.11.0

package/src/bridge/host-bridge.js

@@ -4,9 +4,10 @@ import {traceArgs,finishRecord} from './trace.js';
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { packageHostResult } from "../output/bottleneck.js";
+import { READ_FILES } from "../shared/result.js";
 
 import { errorMessage, isString, isFunction } from "../shared/decode.js";
-import { isMutatingTool, runParallelWave, createNativeScheduler } from "../runtime/parallel.js";
+import { isMutatingTool, createNativeScheduler } from "../runtime/parallel.js";
 import { unknownToolMessage } from "./catalog.js";
 import { resolveInvokeTarget } from "./invoke.js";
 import { buildWriteDiff } from "../fs/diff.js";
@@ -15,7 +16,7 @@ import { SeenLedger } from "../context/ledger.js";
 import { CausalVfs, resolveCommitTarget } from "../fs/vfs.js";
 import { resolveWorkspacePath, runCommand, clearPathCache, relativeSlash } from "../fs/workspace.js";
 import { createNativeAdapters } from "../adapters/index.js";
-import { resultDiff, boundedWriteDiff, writeSnapshot } from "../fs/text-ops.js";
+import { resultDiff, boundedWriteDiff, writeSnapshot, resolveReadPath } from "../fs/text-ops.js";
 
 export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedger, budget, terminalIdentity }) {
   const index = registry?.index ?? new WorkspaceIndex((argv, opts) => runCommand(argv, opts));
@@ -26,6 +27,8 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     notifyWorkspaceChanged(paths);
   }, target => resolveWorkspacePath(getCwd(), target, "commit", false, true), assertSession);
 
+  vfs.bestEffort = true;
+
   const executors = registry?.executors ?? new Map();
   const definitions = registry?.definitions ?? new Map();
   const sharedRegistry = registry ?? { executors, definitions, index, callSeq: 0 };
@@ -39,12 +42,15 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
   let activeCtx = null;
   let activeSignal = undefined;
   let trace = [];
+  const readFiles = new Set();
+  // Write protection is independent of optional, bounded disk-read receipts.
+  const openedPaths = new Set();
   let callListener = null;
   const scheduler = createNativeScheduler();
 
-  // Advisory host event, not a tool or a transaction participant. Consumers
-  // invalidate synchronously; failures must never affect committed bytes.
-  function notifyWorkspaceChanged(paths = null) {
+  // Advisory host events, not transaction participants. Observer failures
+  // cannot fail reads or change committed bytes.
+  function notifyWorkspace(name, paths) {
     if (!isFunction(pi?.events?.emit)) return;
 
     const event = Object.freeze({
@@ -52,7 +58,80 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
       paths: paths === null ? null : Object.freeze([...new Set(paths)]),
     });
 
-    try { pi.events.emit("workspace:changed", event)?.catch?.(() => {}); } catch {}
+    try { pi.events.emit(name, event)?.catch?.(() => {}); } catch {}
+  }
+
+  function notifyWorkspaceChanged(paths = null) { notifyWorkspace("workspace:changed", paths); }
+
+  function rememberReads(raw, result) {
+    if (!result.ok || !isFunction(pi?.events?.emit)) return;
+
+    for (const file of raw?.[READ_FILES] ?? []) {
+      if (readFiles.size === 256) break;
+      readFiles.add(file);
+    }
+  }
+
+  async function fileIdentities(input, existingOnly = false) {
+    if (!isString(input)) return [];
+    let logical;
+
+    try { logical = resolveReadPath(getCwd(), input); }
+    catch { return existingOnly ? [] : [input]; }
+
+    let canonical;
+
+    try { canonical = await vfs.resolvePath(logical, false); }
+    catch {
+      if (existingOnly && await vfs.getOverlay(logical) === undefined) return [];
+      canonical = await vfs.resolvePath(logical).catch(() => logical);
+    }
+
+    // Captured tools can serve virtual paths; retain lexical identity too.
+    // This is path-based protection, not an inode lease or cross-process lock.
+    return logical === canonical ? [logical] : [logical, canonical];
+  }
+
+  function readPaths(args, result) {
+    const paths = [];
+
+    // A resolved missing-file probe must not forbid creation. Actual source
+    // provenance also covers staged files that do not exist on disk yet.
+    if (args?.query === undefined && args?.evidence !== true && isString(args?.path)) paths.push({path:args.path,existingOnly:args.resolve===true});
+
+    if (isString(result.sourcePath)) paths.push({path:result.sourcePath,existingOnly:false});
+
+    return paths;
+  }
+
+  async function rememberOpenedPaths(args, result) {
+    if (result.streamed) return;
+
+    const paths = Array.isArray(args?.path) && Array.isArray(result.items)
+      ? args.path.flatMap((input, i) => result.itemErrors?.[i] ? [] : readPaths({...args,path:input},{sourcePath:result.sourcePaths?.[i]}))
+      : result.ok ? readPaths(args, result) : [];
+
+    const unique = new Map();
+
+    for (const entry of paths) {
+      if (!unique.has(entry.path) || !entry.existingOnly) unique.set(entry.path, entry);
+    }
+
+    const entries = [...unique.values()];
+
+    for (let i = 0; i < entries.length; i += 8) {
+      await Promise.all(entries.slice(i, i + 8).map(async entry => {
+        for (const identity of await fileIdentities(entry.path, entry.existingOnly)) openedPaths.add(identity);
+      }));
+    }
+  }
+
+  async function assertUnreadWrite(args) {
+    if (args?.replace === true || args?.append === true || !openedPaths.size) return;
+
+    if ((await fileIdentities(args?.path)).some(identity => openedPaths.has(identity))) {
+      throw new Error("file was already read this program; use edit(oldText, newText) or edit(view, ...). write({path,content,replace:true}) replaces anyway");
+    }
   }
 
   hooks.terminalOwner = () => terminalOwner;
@@ -99,6 +178,8 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     vfs.closed = false;
     callCount = 0;
     trace = [];
+    readFiles.clear();
+    openedPaths.clear();
     // Files may change between programs (editor, git); never serve a stale run.
     vfs.invalidateObserved();
     clearPathCache();
@@ -168,6 +249,8 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
   }
 
   function assertOwnedOverride(name, args) {
+    if (name === "read" && args?.indexed === true) throw new Error("indexed source retrieval requires the Supernova-owned read adapter");
+
     if (name === "bash" && (args?.background === true || args?.action !== undefined)) throw new Error("background terminals require the Supernova-owned bash adapter, not an external override");
 
     if (name === "read" && (args?.json !== undefined || /^(agent|artifact):\/\/.*\?/i.test(String(args?.path)))) throw new Error("JSON projection requires the Supernova-owned read adapter, not an external override");
@@ -188,7 +271,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     assertSession();
 
     try {
-      const res = await target.exec(`supernova:${name}:${callId}`, args || {}, activeSignal, undefined, target.delegated
+      const res = await target.exec(`supernova:${name}:${callId}`, args || {}, activeSignal, undefined, target.delegated && tools.session
         ? { ...activeCtx, settings: tools.session.settings, toolNames: evalToolNames(), autoApprove: false }
         : activeCtx);
 
@@ -202,6 +285,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
 
   async function invokeNative(target, args, record, onItem) {
     assertSession();
+    vfs.bindMutationRecord(record);
     const res = await target.native(target.argvOwned ? { ...args, args: args.args.map(String) } : args || {}, activeSignal, onItem);
     completeRecord(record, res);
 
@@ -221,7 +305,9 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     assertCallableTarget(name);
 
     if (!isCallable(name)) throw new Error(unknownToolMessage(name, [...definitions.keys(), ...Object.keys(natives)].filter(isCallable)));
+
     // Refused calls are free: only charge the budget once a target will run.
+    if (name === "write") await assertUnreadWrite(args);
     chargeCallBudget();
 
     const command = { apply_patch: "edit", surface: "read", evidence: "read", snap: "read" }[name] ?? name;
@@ -230,7 +316,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     notifyCall(record);
 
     try {
-      const target = resolveInvokeTarget(name, args, { hostTool, hostSession: tools.session, executors, natives });
+      const target = resolveInvokeTarget(name, args, { hostTool, hostSession: tools.session, modern: tools.modern, executors, natives });
 
       if (target.kind === "override") return await invokeOverride(target, name, args, record, callId);
 
@@ -243,11 +329,21 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     }
   }
 
+  // Candidate discovery uses the existing permission, trace and budget boundary.
+  // It cannot grant a read observation or invoke a mutating provider.
+  hooks.indexedSearch = async args => {
+    refreshTools();
+
+    if (!isCallable("isearch") || isMutatingTool("isearch", config, args, definitions.get("isearch"))) throw new Error("indexed read requires a callable read-only isearch; enable/promote isearch or omit indexed:true");
+
+    return invokeRaw("isearch", args);
+  };
+
   function fileMutationKey(name, args) {
     if (!["edit", "write", "apply_patch"].includes(name) || !isString(args?.path)) return;
 
     // Overrides can mutate more than their declared path: keep them global.
-    if (hostTool(name) || executors.has(name)) return;
+    if (hostTool(name) || (!tools.modern && executors.has(name))) return;
 
     return async () => {
       const target = await resolveWorkspacePath(getCwd(), args.path, name, false, true);
@@ -259,40 +355,32 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
 
   async function call(name, args, onItem) {
     if (!isString(name) || !name) throw new Error("nova.call requires a tool name");
-    const deliver = onItem ? (index, raw) => onItem(index, packageHostResult(raw, config)) : undefined;
-    const invoke = async () => packageHostResult(await invokeRaw(name, args, deliver), config);
-    const kind = isMutatingTool(name, config, args, definitions.get(name)) ? "write" : "read";
+    const packageResult = raw => packageHostResult(raw, config, definitions.get(name)?.outputSchema !== undefined);
 
-    return scheduler.schedule(kind, invoke, activeSignal, fileMutationKey(name, args));
-  }
+    const deliver = onItem ? async (index, raw) => {
+      const result = packageResult(raw);
 
-  async function callMany(calls) {
-    if (!Array.isArray(calls)) throw new TypeError("nova.callMany requires an array");
-    const list = calls;
+      if (name === "read") await rememberOpenedPaths({...args,path:args.path[index]}, result);
+      await onItem(index, result);
+      rememberReads(raw, result);
+    } : undefined;
 
-    if (list.some(item => !isString(item?.name) || !item.name)) throw new TypeError("nova.callMany entries require a tool name");
+    const invoke = () => vfs.withPathScope(async () => {
+      const raw = await invokeRaw(name, args, deliver);
+      const result = packageResult(raw);
 
-    const thunks = list.map((item) => {
-      const n = item?.name;
-      const a = item?.args;
+      if (name === "read") await rememberOpenedPaths(args, result);
+      rememberReads(raw, result);
 
-      return () => call(n, a);
+      return result;
     });
 
-    const names = list.map((item) => item?.name).filter((n) => isString(n));
-    const wave = await runParallelWave(thunks, { names, calls: list, definitions: names.map(name => definitions.get(name)) }, { mode: "auto", config });
-    // Return a results array that also carries .mode/.reason, and is directly
-    // iterable so `for (const r of await nova.callMany([...]))` works.
-    const results = Array.isArray(wave.results) ? wave.results.slice() : [];
-    Object.defineProperties(results, {
-      mode: { value: wave.mode, enumerable: false },
-      reason: { value: wave.reason, enumerable: false },
-      results: { value: results, enumerable: false },
-    });
+    const kind = isMutatingTool(name, config, args, definitions.get(name)) ? "write" : "read";
 
-    return results;
+    return scheduler.schedule(kind, invoke, activeSignal, fileMutationKey(name, args));
   }
 
+
   return {
     executors,
     definitions,
@@ -300,9 +388,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     refreshTools,
     isCallable,
     externalNames,
-    supportsBatchRead: () => !hostTool("read") && !executors.has("read"),
-    // Windows command shims need shell handling; preserve the existing route there.
-    supportsNativeArgv: () => process.platform !== "win32" && !hostTool("bash") && !executors.has("bash"),
+    supportsBatchRead: () => !hostTool("read") && (tools.modern || !executors.has("read")),
     summarizeEdit: (target, before, after, diff) => hooks.summarizeEdit(getCwd(), target, before, after, diff),
     invalidateFiles() { vfs.invalidateObserved(); index.invalidate(); clearPathCache(); },
     describeMemory() {
@@ -348,12 +434,39 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     async commitSpeculation() {
       assertSession();
 
-      return await vfs.commit();
+      const depth = vfs.getOverlayDepth();
+      const result = await vfs.commit();
+
+      for (const record of trace) {
+        if (record.mutationState !== "pending" || record.mutationDepth < depth) continue;
+        record.mutationState = result.depth <= 1 ? "saved" : "pending";
+        record.mutationDepth = result.depth;
+      }
+
+      // The outer success commit follows guest completion/delivery. Checkpoint
+      // merges and failed programs must not publish provisional read credit.
+      if (vfs.getOverlayDepth() === 0 && readFiles.size) {
+        const paths = [...readFiles];
+        readFiles.clear();
+        notifyWorkspace("workspace:read", paths);
+      }
+
+      return result;
+    },
+    rollbackSpeculation() {
+      const depth = vfs.getOverlayDepth();
+      const result = vfs.rollback();
+
+      for (const record of trace) {
+        if (record.mutationState === "pending" && record.mutationDepth >= depth) record.mutationState = vfs.mutations.recoveryFailed ? "uncertain" : "rolled back";
+      }
+
+      if (vfs.getOverlayDepth() === 0) readFiles.clear();
+
+      return result;
     },
-    rollbackSpeculation: () => vfs.rollback(),
     getOverlayDepth: () => vfs.getOverlayDepth(),
     call,
-    callMany,
     ledger,
   };
 }

package/src/bridge/invoke.js

@@ -8,6 +8,8 @@ export function toolIsCallable(name, env) {
 
   if (env.nativeOwned(name)) return true;
 
+  if (env.modern) return env.modernAllows(name);
+
   if (env.hostSession) return env.evalAllows(name);
 
   return env.listed(name);
@@ -23,7 +25,7 @@ function hostExecutor(name, env) {
 
   if (delegated) return { exec: delegated.execute.bind(delegated), delegated };
 
-  if (env.hostSession) return { exec: undefined, delegated };
+  if (env.modern || env.hostSession) return { exec: undefined, delegated };
 
   return { exec: env.executors.get(name), delegated };
 }

package/src/bridge/tool-registry.js

@@ -1,8 +1,12 @@
 import {isString,isFunction} from '../shared/decode.js';
 import {toolIsCallable} from './invoke.js';
 
+// Executor maps outlive individual program bridges.
+const indexerExecutors = new WeakMap();
+
 export function createToolRegistry({pi,config,registry,natives,executors,definitions}) {
-  let hostSession = null, boundSessionId;
+  let hostSession = null, boundSessionId, invocationContext = null;
+
 function captureHostTool(tool, excluded) {
   return tool && isString(tool.name) && isFunction(tool.execute) && tool.name !== "supernova" && !excluded.has(tool.name);
 }
@@ -26,12 +30,34 @@ function evalToolNames() {
   catch { return []; }
 }
 
+function invocationTools() {
+  if (!invocationContext) return [];
+
+  try { return Array.isArray(invocationContext.tools) ? invocationContext.tools : []; }
+  catch { return []; }
+}
+
 function hostTool(name) {
-  if (!hostSession) return undefined;
   const metadata = definitions.get(name);
 
+  if (invocationContext) {
+    if (nativeAdapterOwns(name, metadata, true)) return undefined;
+
+    if (!invocationTools().some(tool => tool.name === name)) return undefined;
+
+    // Never call an AgentTool executor directly: the invocation owns validation,
+    // exposure, permissions, cancellation, nested receipts and usage accounting.
+    return {async execute(_id, args, signal, onUpdate) {
+      const outcome = await invocationContext.executeTool(name, args, {signal, onUpdate});
+
+      return {...outcome.result, isError:outcome.isError};
+    }};
+  }
+
+  if (!hostSession) return undefined;
+
   // Keep Supernova's transactional adapters for ordinary built-ins. Respect overrides.
-  if (Object.hasOwn(natives, name) && metadata?.sourceInfo?.source === "builtin") return undefined;
+  if (nativeAdapterOwns(name, metadata, false)) return undefined;
 
   try { return hostSession.getToolForEvalBridge?.(name); }
   catch { return undefined; }
@@ -41,11 +67,12 @@ function callableEnv() {
   return {
     excluded: new Set(config.excludeTools || []),
     hostSession,
+    modern: invocationContext !== null,
+    modernAllows: name => invocationTools().some(tool => tool.name === name),
     natives,
     executors,
-    sessionInvalid: () => hostSession && (hostSession.isDisposed || hostSession.sessionManager?.getSessionId?.() !== boundSessionId),
-    nativeOwned: name => Object.hasOwn(natives, name) && !executors.has(name)
-      && (!hostSession || !definitions.has(name) || definitions.get(name).sourceInfo?.source === "builtin"),
+    sessionInvalid,
+    nativeOwned,
     evalAllows: name => {
       if (!evalToolNames().includes(name) && definitions.has(name)) return false;
 
@@ -68,37 +95,126 @@ function isCallable(name) {
   return toolIsCallable(name, callableEnv());
 }
 
-function refreshTools() {
+// Pi's public catalog intentionally omits executors. The optional indexer
+// handshake is synchronous and read-only, never a fallback around a host
+// session's eval/approval gate. Withdrawn or ambiguous capabilities fail closed.
+function withdrawIndexer() {
+  const previous = indexerExecutors.get(executors);
+
+  if (previous && executors.get('isearch') === previous) executors.delete('isearch');
+  indexerExecutors.delete(executors);
+}
+
+function discoverIndexer(tools) {
+  withdrawIndexer();
+  const metadata = tools.find(tool=>tool?.name==='isearch');
+
+  if (invocationContext || hostSession || executors.has('isearch') || !indexerMetadataAllowed(metadata)) return;
+  const providers = [];
+
+  try {
+    if (!pi.getActiveTools?.().includes('isearch')) return;
+    pi.events.emit('pi-indexer:readonly-provider',{version:1,parameters:metadata.parameters,sessionId:boundSessionId,accept(provider) {
+      if (provider?.name === 'isearch' && provider.parameters === metadata.parameters && provider.annotations?.readOnlyHint === true && isFunction(provider.execute)) providers.push(provider);
+    }});
+  } catch { return; }
+
+  if (providers.length !== 1) return;
+  definitions.set('isearch',{...definitions.get('isearch'),...providers[0]});
+  indexerExecutors.set(executors,providers[0].execute);
+  executors.set('isearch',providers[0].execute);
+}
+
+function listedTools() {
   let listed = [];
 
   try { listed = pi?.getAllTools?.() ?? []; } catch {}
-  const tools = Array.isArray(listed) ? listed : [];
+
+  return Array.isArray(listed) ? listed : [];
+}
+
+function refreshTools() {
+  const tools = [...listedTools(), ...invocationTools()];
 
   for (const tool of tools) {
     if (!isString(tool?.name)) continue;
     definitions.set(tool.name, { ...definitions.get(tool.name), ...tool });
 
-    if (!hostSession && isFunction(tool.execute)) executors.set(tool.name, tool.execute.bind(tool));
+    if (!invocationContext && !hostSession && isFunction(tool.execute)) executors.set(tool.name, tool.execute.bind(tool));
   }
 
+  discoverIndexer(tools);
+
   return [...definitions.values()].filter(tool => isCallable(tool.name));
 }
 
 function externalNames() {
   return [...definitions.keys()].filter(name => !!hostTool(name) || executors.has(name));
 }
+
 function bindSession(ctx) {
-  const sessionId = ctx?.sessionManager?.getSessionId?.();
+  const sessionId = sessionIdOf(ctx);
   boundSessionId = sessionId;
-  const registry = pi?.pi?.AgentRegistry?.global?.();
+  invocationContext = isFunction(ctx?.executeTool) ? ctx : null;
+
+  if (invocationContext) {
+    hostSession = null;
+
+    return;
+  }
+
+  hostSession = findSession(sessionId);
+}
+
+function nativeAdapterOwns(name, metadata, allowMissing) {
+  return Object.hasOwn(natives, name) && ((allowMissing && !metadata) || metadata?.sourceInfo?.source === "builtin");
+}
+
+function knownBuiltin(name) {
+  return !definitions.has(name) || definitions.get(name).sourceInfo?.source === "builtin";
+}
+
+function nativeOwned(name) {
+  if (!Object.hasOwn(natives,name)) return false;
+
+  if (invocationContext) return knownBuiltin(name);
+
+  return !executors.has(name) && (!hostSession || knownBuiltin(name));
+}
+
+function sessionIdOf(ctx) {
+  return ctx?.sessionManager?.getSessionId?.();
+}
+
+function sessionInvalid() {
+  return invocationContext ? sessionIdOf(invocationContext) !== boundSessionId
+    : hostSession && (hostSession.isDisposed || sessionIdOf(hostSession) !== boundSessionId);
+}
+
+function indexerMetadataAllowed(metadata) {
+  return metadata && metadata.exposure === undefined && metadata.annotations?.readOnlyHint !== false && isFunction(pi?.events?.emit);
+}
+
+function agentRegistry() {
+  return pi?.pi?.AgentRegistry?.global?.();
+}
+
+function registrySessions() {
+  const registry = agentRegistry();
   let sessions = [];
 
   try { sessions = registry?.list?.() ?? []; } catch {}
-  if (!Array.isArray(sessions)) sessions = [];
-  hostSession = sessionId
-    ? sessions.map(ref => ref.session).find(session => !session?.isDisposed && session?.sessionManager?.getSessionId?.() === sessionId) ?? null
-    : null;
+
+  return Array.isArray(sessions) ? sessions : [];
 }
+
+function findSession(sessionId) {
+  const sessions = registrySessions();
+
+  return sessionId ? sessions.map(ref => ref.session).find(session => !session?.isDisposed && sessionIdOf(session) === sessionId) ?? null : null;
+}
+
   wrapHostRegister();
-  return {refreshTools,isCallable,externalNames,hostTool,evalToolNames,bindSession,get session(){return hostSession;}};
+
+  return {refreshTools,isCallable,externalNames,hostTool,evalToolNames,bindSession,get modern(){return invocationContext !== null;},get session(){return hostSession;}};
 }

package/src/context/evidence-graph.js

@@ -246,4 +246,5 @@ function pageRank(spans, graph, eta, prior, { gamma, pprIterations }) {
 
   return pi;
 }
+
 export { splitIdentifier, spanLines, buildGraph, activateEntities, propagate, pageRank };

package/src/context/evidence-rank.js

@@ -150,4 +150,5 @@ function pickEvidence(spans, fileScores, profile, opts) {
 
   return { picks: closure(main, spans, graph, fused, opts.k), fused };
 }
+
 export { pickEvidence };

package/src/context/evidence.js

@@ -1,5 +1,5 @@
 import {pickEvidence} from "./evidence-rank.js";
-import {pendingInScope,overlaySearchEntry} from './search-files.js';
+import {pendingInScope,overlaySearchEntry,overlaySnapshot} from './search-files.js';
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { WorkspaceIndex } from "./repo-index.js";
@@ -237,7 +237,9 @@ export async function selectEvidence({ query, root, searchDir, index, overlayTex
   const profile = profileQuery(query);
 
   if (profile.keywords.length === 0) throw new Error("evidence requires at least one searchable concept keyword");
-  const { files: chosenFiles, fileScores } = candidateFiles(await listedFiles(root, searchDir, pendingPaths, index), profile, index, opts.maxCandidateFiles, overlayText);
+  const files = await listedFiles(root, searchDir, pendingPaths, index);
+  overlayText = await overlaySnapshot(files, overlayText);
+  const { files: chosenFiles, fileScores } = candidateFiles(files, profile, index, opts.maxCandidateFiles, overlayText);
   const spans = usageSpans(collectSpans(chosenFiles, overlayText, index, opts.maxSpanLines), profile, opts.maxSpanLines);
 
   if (spans.length === 0) return { route: profile.route, spans: [] };

package/src/context/fuzzy.js

@@ -15,6 +15,7 @@ const AI_DECAY = Math.LN2 / 3;            // per day
 const AI_MAX_HISTORY_DAYS = 7;
 
 const MAX_TIMESTAMPS_PER_FILE = 128;
+
 const MAX_FRECENCY_FILES = 10000;
 
 const AI_MODIFICATION_THRESHOLDS = [[16, 30], [8, 300], [4, 900], [2, 3600], [1, 14400]]; // [boost, seconds]
@@ -31,6 +32,10 @@ export class Frecency {
       if (this.access.size >= MAX_FRECENCY_FILES) this.access.delete(this.access.keys().next().value);
       this.access.set(filePath, (list = []));
     }
+
+    // Existing keys must move to the newest position before capacity eviction.
+    this.access.delete(filePath);
+    this.access.set(filePath, list);
     list.push(at);
 
     if (list.length > MAX_TIMESTAMPS_PER_FILE) list.splice(0, list.length - MAX_TIMESTAMPS_PER_FILE);
@@ -64,6 +69,23 @@ export class Frecency {
   }
 }
 
+// Fuzzy offsets index the original UTF-16 string. Keep lowercase expansion
+// marks out of the positional projection (not full Unicode normalization).
+function foldCase(text) {
+  const lower = text.toLowerCase();
+
+  if (lower.length === text.length) return lower;
+
+  let out = "", offset = 0;
+
+  for (const char of text) {
+    out += lower.slice(offset, offset + char.length);
+    offset += char.toLowerCase().length;
+  }
+
+  return out;
+}
+
 const SEPARATORS = new Set(["/", "\\", "_", "-", ".", " "]);
 
 function isBoundary(hay, i) {
@@ -177,7 +199,7 @@ function matchWithTypos(part, pCmp, partLower, hay, hayCmp, hayLowerOrNull, maxT
         start = hayCmp.lastIndexOf(subCmp[ni], start - 1);
       }
 
-      if (hayLower === null) hayLower = hay.toLowerCase();
+      if (hayLower === null) hayLower = foldCase(hay);
       best = {
         score: scoreAlignment(sub, subCmp, hay, hayCmp, start),
         start,
@@ -202,7 +224,7 @@ function matchPart(part, pCmp, partLower, hay, hayCmp, hayLowerOrNull, maxTypos)
   const direct = matchOnce(part, pCmp, hay, hayCmp);
 
   if (direct) {
-    const hayLower = hayLowerOrNull === null ? hay.toLowerCase() : hayLowerOrNull;
+    const hayLower = hayLowerOrNull === null ? foldCase(hay) : hayLowerOrNull;
 
     return { ...direct, typos: 0, exact: hayLower === partLower };
   }
@@ -214,10 +236,10 @@ function matchPart(part, pCmp, partLower, hay, hayCmp, hayLowerOrNull, maxTypos)
 
 /** Best match allowing up to maxTypos skipped needle characters. */
 export function fuzzyMatch(needle, hay, { maxTypos = 0, caseSensitive = false } = {}) {
-  if (caseSensitive) return matchPart(needle, needle, needle.toLowerCase(), hay, hay, null, maxTypos);
+  if (caseSensitive) return matchPart(needle, needle, foldCase(needle), hay, hay, null, maxTypos);
 
-  const needleLower = needle.toLowerCase();
-  const hayLower = hay.toLowerCase();
+  const needleLower = foldCase(needle);
+  const hayLower = foldCase(hay);
 
   return matchPart(needle, needleLower, needleLower, hay, hayLower, hayLower, maxTypos);
 }
@@ -258,7 +280,7 @@ function partTypos(parts, ctx) {
 }
 
 function scoredPath(rel, parts, partLower, maxTypos, caseSensitive, ctx, currentSegs, dirCache) {
-  const hayCmp = caseSensitive ? rel : rel.toLowerCase();
+  const hayCmp = caseSensitive ? rel : foldCase(rel);
   const matched = matchParts(parts, partLower, rel, hayCmp, caseSensitive ? null : hayCmp, maxTypos, caseSensitive);
 
   if (!matched) return null;
@@ -278,7 +300,7 @@ export function rankPaths(query, paths, ctx = {}) {
   // Per-query hoists: lowered parts once (not once per path per part), the
   // current directory split once (not once per candidate), plus a
   // per-call cache for candidate directory segments (paths share dirs).
-  const partLower = parts.map((p) => p.toLowerCase());
+  const partLower = parts.map(foldCase);
   const currentDir = ctx.currentFile ? ctx.currentFile.slice(0, ctx.currentFile.lastIndexOf("/") + 1) : "";
   const currentSegs = currentDir ? splitDirSegs(currentDir) : null;
   const dirCache = new Map();
@@ -317,7 +339,7 @@ function matchParts(parts, partLower, rel, hayCmp, hayLowerOrNull, maxTypos, cas
 function filenameBonus(base, rel, filenameStart, first, needleLower) {
   if (first.start < filenameStart) return 0;
 
-  return rel.slice(filenameStart).toLowerCase() === needleLower ? Math.floor((base * 2) / 5) : Math.floor(base / 5);
+  return foldCase(rel.slice(filenameStart)) === needleLower ? Math.floor((base * 2) / 5) : Math.floor(base / 5);
 }
 
 /** fff: frecency boost base·f/100 and +15% for git-modified files. */
@@ -325,6 +347,7 @@ function contextBoost(base, rel, ctx) {
   let frecency = 0;
 
   try { frecency = ctx.frecency ? ctx.frecency.score(rel, ctx.mtimeOf?.(rel)) : 0; } catch {}
+
   const gitBoost = ctx.modified?.has(rel) ? Math.floor((base * 15) / 100) : 0;
 
   return Math.floor((base * frecency) / 100) + gitBoost;