pi-supernova 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-04
+
+### Changed
+
+- `read`, `write`, `edit`, and `bash` are the main interface. Source questions and directory selection use `read`; no separate search-tool discovery is needed.
+- Internal adapters remain callable when the host hides their top-level tools. Explicit exclusions, delegated-tool permissions, and session guards still apply.
+- Source selection favors declarations over callers. It reports ambiguous, missing, and incomplete results instead of arbitrary file choices.
+- Bounded ripgrep searches replace whole-repository content loading for source questions. Large source files remain searchable; context and signatures have explicit limits.
+
+### Fixed
+
+- Directory reads include staged entries before commit. Explicit test-directory searches include test files without extra query words.
+
 ## [0.1.0] - 2026-09-04
 
 ### Fixed

package/README.md

@@ -5,7 +5,7 @@
 [![node](https://img.shields.io/node/v/pi-supernova.svg)](https://nodejs.org)
 [![pi-package](https://img.shields.io/badge/pi--package-extension-7aa2f7)](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md)
 
-**CodeMode for [Pi](https://pi.dev) and [OMP](https://omp.sh).** One tool, one guest program: progressive discovery, a hard result bottleneck, and Amdahl-aware parallel waves.
+**CodeMode for [Pi](https://pi.dev) and [OMP](https://omp.sh).** One program with `read`, `write`, `edit`, and `bash`. Search, source context, and result limits stay inside these commands.
 
 ```bash
 pi install npm:pi-supernova
@@ -18,7 +18,9 @@ Pi 0.85.0 supplies tool schemas but has no cross-extension execution API. Supern
 
 An unrelated Pi extension’s tools are not callable through Supernova. OMP 18.1.10 supports those calls through its session registry.
 
-The runtime, transaction, patch, output-limit, and renderer fixes share the same code on both hosts. Disabled configured tools are not callable.
+Both hosts use the same runtime, transactions, and result limits. Hiding a top-level native tool does not remove its internal Supernova adapter.
+
+Use `excludeTools` to disable an internal adapter. Delegated extension tools still require host permission and active status. Replaced or disposed sessions cannot call tools.
 
 ---
 
@@ -26,7 +28,7 @@ The runtime, transaction, patch, output-limit, and renderer fixes share the same
 
 | | Stock multi-tool prompt | **pi-supernova** |
 |--|-------------------------|------------------|
-| Schema tax | Every tool in context | Thin catalog + on-demand `describe` |
+| Schema tax | Every tool in context | Four known commands; optional host schemas on demand |
 | Multi-step | Model stitches turns | One in-process program |
 | Parallel reads | Ad hoc | `callMany` Auto / `parallel()` |
 | Hosts | Separate packages | Same tarball for Pi **and** OMP |
@@ -42,27 +44,47 @@ A completed worker cannot supply callbacks or globals to another program. Concur
 ## Quick example
 
 ```js
-async () => {
-  const hits = await nova.search("read file contents");
-  await nova.describe("read");
+const hit = JSON.parse(await read("src", {about: "validateJwtRefreshToken"}));
+if (hit.status !== "found") return hit;
+return await read(hit.path, {about: "expired tokens"});
+```
 
-  const a = await nova.call("read", { path: "src/index.ts" });
-  const wave = await nova.callMany([
-    { name: "read", args: { path: "a.ts" } },
-    { name: "read", args: { path: "b.ts" } },
-  ]);
+No catalog lookup or separate search command is needed.
 
-  return { preview: a.value.slice(0, 200), mode: wave.mode, n: wave.length };
-}
-```
+| Command | Result |
+|---------|--------|
+| `read(file, offset?, limit?)` | File text; line numbers start at one |
+| `read(files)` | An array of file texts |
+| `read(directory)` | Direct directory entries |
+| `read("symbol or question")` | JSON text with source status, path, line, signature, and context |
+| `read(path, {about: question})` | Relevant file bodies, or source selection inside a directory |
+| `write(path, text)` | Write a file |
+| `edit(path, oldText, newText)` | Post-edit lines, a structural check, and references |
+| `bash(command, options?)` | Bounded command output; failure throws |
+
+### Source selection
+
+`read` reports `found`, `ambiguous`, `not_found`, or `incomplete`.
+Only `found` selects a path. Uncertain results contain at most three candidates.
 
-Globals: `nova`, `parallel`, `pipeline`, `console`, plus shorthand `read` (path or path array), `write`, `edit`, `patch`, `evidence`, `surface`, `snap`, `bash`, and `exec`.
+Identifier declarations take priority over callers and filenames. Natural-language selection uses text matches, not semantic inference. Use a symbol or a narrower directory when needed.
 
-Read discipline that keeps context small: `evidence(question)` across the repo, or `read(path, {about: question})` for one file (full structure, only relevant bodies expanded, ~65% fewer tokens than the file) → `read(path, offset, limit)` only for the lines you will edit.
+The confidence value is a ranking heuristic, not a measured probability. Duplicate declarations do not produce a confident winner.
 
-Results never repeat what the model already saw: a run of lines from an earlier result collapses to `⋯ 23 lines same as #12 · host-bridge.js:40–62 ⋯`; changed lines always show; `read(path, a, n)` shows a cited range again. `edit` returns the post-edit lines, a structural check, and who else references a changed declaration; a failing `bash` attaches the source behind the `path:line` it printed. A read→edit→verify loop costs ~15% of the naive token count.
+Search uses ripgrep without loading every file into the text cache. It can locate declarations beyond the 512 KiB whole-file cache limit.
 
-File search is an in-process port of [fff](https://github.com/dmtrKovalenko/fff): `glob("hostbrdge")` finds `host-bridge.js` (typo-tolerant, frecency- and git-status-ranked), `grep` is smart-case with declaration lines first and a fuzzy fallback. None of it spawns a process.
+Each candidate contains up to seven source lines. Signatures and individual lines have a 240-character limit, with explicit truncation markers.
+
+File-list and content-search output have separate 2,097,152-character budgets. Incomplete searches report their status instead of selecting a file.
+
+The measured 10,001-file fixture returned a 199-character result. This is about 50 tokens at four characters per token, not an exact token count.
+
+In the 23-question source check, 17 questions selected the correct file and six returned candidates. No result selected a wrong file.
+All 15 identifier questions selected the correct file. Natural-language questions can still miss the intended file in their candidates.
+
+Search scans disk on each question. Warm searches can be slower than the previous full-content cache, but do not retain every source file.
+
+Already-seen result lines collapse to references. `read(path, firstLine, lineCount)` shows a range again. `edit` returns changed lines without a verification read.
 
 The returned value is rendered as a compact JS literal (unquoted keys, one item per line only when a container exceeds 120 columns) and capped at `maxReturnChars`. Strings are returned raw. This costs ~43% fewer tokens than pretty JSON. Return small shaped values, not raw file dumps.
 
@@ -85,7 +107,7 @@ Expanded text wraps at the terminal width without a preview-line limit. Operatio
 
 ---
 
-## API
+## Optional APIs
 
 | API | Role |
 |-----|------|
@@ -94,9 +116,8 @@ Expanded text wraps at the terminal width without a preview-line limit. Operatio
 | `nova.call(name, args)` | Host tool or native adapter |
 | `nova.callMany([{name,args}])` | Auto parallel wave; iterable array with `.mode` / `.results` |
 | `nova.evidence(query, {k?, path?, maxChars?})` | Top-K source spans (path, lines, verbatim text) that answer a question. Zero-token evidence selection after Zero-Mem; ~68% fewer tokens than reading the files |
-| `read(path, {about})` | Whole-file outline with only the relevant bodies expanded; folded bodies show `line … N lines` |
 | `nova.surface(path)` | Structural outline for a source file |
-| `nova.snap(query, searchRoot?)` | Defining file (workspace-relative), line, signature, confidence, and context for a concept; served from the in-process index in well under 1ms |
+| `nova.snap(query, searchRoot?)` | Structured source-selection result; the same engine as a source question passed to `read` |
 | `nova.has(name)` | Whether a catalog or native tool is callable (sync) |
 | `parallel(thunks)` / `pipeline(items, …stages)` | Array-based helpers; pipeline stages must be functions |
 | `nova.speculate(fn)` | Counterfactual branch (rollback / commit) |
@@ -107,7 +128,9 @@ Expanded text wraps at the terminal width without a preview-line limit. Operatio
 
 `nova.describe` preserves required fields, unions, enums, nested objects, and numeric constraints. OMP ArkType and Zod schemas convert to JSON Schema.
 
-Root Snap searches ignore hidden files. Passing a hidden search root includes hidden files beneath that root; Git metadata is always excluded.
+Source questions ignore hidden files by default. An explicit hidden directory includes its hidden files. Git metadata stays excluded.
+
+An explicit test directory includes test files without extra query words. Directory reads include staged entries before commit.
 
 ---
 
@@ -165,7 +188,7 @@ Pair with DCE last if you use it: `omp install npm:pi-deferred-context-engine`.
 
 | Symptom | Fix |
 |---------|-----|
-| `unknown tool "…"` | Use `nova.search("")` and `/supernova`. Enable the tool in the current session. Restart after package changes. |
+| `unknown tool "…"` | Check `excludeTools` for native adapters. Enable delegated tools in the host. Restart after package changes. |
 | `Rendered line exceeds terminal width` | Install the current package and restart so the Unicode width code reloads. |
 | `callMany` / not iterable | ≥0.0.1; the return is an array with `.mode` / `.results` |
 | Extension missing on OMP | `omp install npm:pi-supernova` (needs `"omp".extensions`) |
@@ -194,7 +217,7 @@ Supernova's retrieval and result shaping implement published methods. Where a pa
 | Work | What we use it for | Where |
 |------|--------------------|-------|
 | **Zero-Mem: Zero-Token Memory Operations for LLM Agents**, Xiao, Zhu, Zhang, Chen, Hong, Zhuang, Zhang, Chen, Ouyang, Ren, Huang (arXiv:2607.29377) | `evidence(query)`: entity–context graph with co-occurrence weights (eq. 3–4), turn/window/episode hierarchy as line/span/file (eq. 5, 11), query profile and relational/local routing (eq. 6–7), lexical entity alignment and one propagation step (eq. 8–9), personalized PageRank over spans (eq. 10), per-view normalisation and ρ-weighted fusion (eq. 12–13), closure with bridges and neighbours (eq. 14), deterministic calibration (eq. 15). Top-K = 5 follows the paper's Top-5 ≈ Top-10 finding. | `evidence.js` |
-| **Agent Zero Memory: Provenance-Aware Long-Term Memory for LLM Agents**, Zhu, Wu (arXiv:2608.29606) | Every returned unit carries provenance (path, line range, verbatim text); the L0→L1→L2 read discipline (`surface` → `evidence`/`read(path, {about})` → `read(path, offset, limit)`); the citation-lock idea that a model should only cite what it actually opened. | `evidence.js`, `outline.js`, tool guidance |
+| **Agent Zero Memory: Provenance-Aware Long-Term Memory for LLM Agents**, Zhu, Wu (arXiv:2608.29606) | Every returned unit carries provenance (path, line range, verbatim text); the L0→L1→L2 read discipline (`read(query)` → `read(path, {about})` → `read(path, offset, limit)`); the citation-lock idea that a model should only cite what it actually opened. | `evidence.js`, `outline.js`, tool guidance |
 | **Harness-of-Harness: Multi-Day Autonomous Software Development with Continual Improvement**, Yan, Su, et al. (arXiv:2609.01481) | Progressive disclosure (index first, detail on demand) and carrying evidence forward instead of reconstructing it from code. | outline / result shaping |
 | **Act More, Decide Less: Skill-Guided Adaptive Action Chunking for Long-Horizon LLM Agents**, Yang, Jin, Zhao, et al. (arXiv:2609.02042) | Framing: one supernova program is an action chunk (one model decision, many primitive actions, stop at the first failing one). | runtime design |
 | **fff**, Dmitriy Kovalenko, MIT, <https://github.com/dmtrKovalenko/fff> | File search. We reimplemented fff's ranking in plain JavaScript after reading its Rust sources (`crates/fff-core/src/score.rs`, `dbs/frecency.rs`, `path_utils.rs`); the formulas and constants are fff's, the code is ours, and nothing runs out of process. Ported: typo-tolerant fuzzy path matching with boundary/consecutive/case bonuses and smart-case; exact-filename +40% and filename +20% bonuses; frecency boost `base·f/100` with fff's AI-mode decay (3-day half-life, 7-day window) and modification-recency steps (30s/5m/15m/1h/4h); git-modified +15%; directory-distance penalty from the current file (−1 per hop, floor −20); definition-first result hinting; fuzzy fallback on zero literal matches; weak-match cutoff; watcher-driven index refresh. Not ported: fff's SIMD/frizbee matcher (ours is an fzf-style greedy match with backward tightening), LMDB persistence (frecency is per session), and the MCP/Neovim surfaces. | `fuzzy.js`, `repo-index.js`, `host-bridge.js` |

package/catalog.js

@@ -4,13 +4,13 @@ import { isString, isObject } from "./decode.js";
 const NATIVE_TOOL_DEFINITIONS = [
   {
     name: "read",
-    description: "Read UTF-8 workspace files by path, or resolve a concept query to source. Supports path arrays, offset, and limit.",
+    description: "Read files, directories, or source questions. Directory questions use about. Source selection reports uncertainty instead of guessing.",
     parameters: { type: "object", properties: {
-      path: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }], description: "Workspace-relative file path, concept query, or array of paths" },
+      path: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }], description: "Workspace-relative file or directory, source question, or array of paths" },
       target: { anyOf: [{ type: "string" }, { type: "array" }], description: "File path/query or array of paths" },
       offset: { type: "number", description: "One-based starting line" },
       limit: { type: "number", description: "Maximum lines to return" },
-      about: { type: "string", description: "Question or symbol: returns the whole file as an outline with only the relevant bodies expanded" },
+      about: { type: "string", description: "Question or symbol: expand relevant file bodies, or select source inside a directory" },
     } },
   },
   {
@@ -28,7 +28,7 @@ const NATIVE_TOOL_DEFINITIONS = [
     parameters: { type: "object", properties: { path: { type: "string" }, patch: { type: "string" } }, required: ["patch"] },
   },
   {
-    name: "snap", description: "Resolve a concept query to the most relevant workspace source location.",
+    name: "snap", description: "Select source with found, ambiguous, not_found, or incomplete status. The read command uses the same engine.",
     parameters: { type: "object", properties: {
       query: { type: "string", description: "Source concept to resolve" },
       path: { type: "string", description: "Optional workspace search root; explicitly targeting a hidden directory includes its hidden files, but Git metadata is always excluded" },

package/host-bridge.js

@@ -55,15 +55,15 @@ function looksLikePath(target) {
   );
 }
 
-async function probeExistingFile(cwd, targetParam, vfs) {
-  const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
-  if (vfs.getOverlay(targetPath) !== undefined || vfs.cache.has(targetPath)) return targetPath;
+async function probeExistingPath(cwd, targetParam, vfs) {
+  const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", true);
+  if (vfs.getOverlay(targetPath) !== undefined || vfs.cache.has(targetPath)) return { path: targetPath, directory: false };
   try {
     const st = await fs.stat(targetPath);
-    if (st.isDirectory()) throw new Error(`read path is a directory, not a file: ${targetPath} (use ls)`);
-    return targetPath;
+    return { path: targetPath, directory: st.isDirectory() };
   } catch (err) {
     if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") throw err;
+    if (vfs.getOverlayPaths().some(file => file.startsWith(targetPath + path.sep))) return { path: targetPath, directory: true };
     return null;
   }
 }
@@ -96,6 +96,11 @@ function applyReplacements(target, content, requestedEdits) {
   return { updated, matches };
 }
 
+function formatDirectoryEntry(name, type, size = 0) {
+  const sizeSuffix = size ? `, ${size} bytes` : "";
+  return `${name}${type === "dir" ? "/" : ""} (${type}${sizeSuffix})`;
+}
+
 async function formatLsEntry(dirPath, entry) {
   const isDir = entry.isDirectory();
   const isSym = entry.isSymbolicLink();
@@ -107,47 +112,55 @@ async function formatLsEntry(dirPath, entry) {
       size = st.size;
     }
   } catch {}
-  const sizeSuffix = size ? `, ${size} bytes` : "";
-  return `${entry.name}${isDir ? "/" : ""} (${typeLabel}${sizeSuffix})`;
+  return formatDirectoryEntry(entry.name, typeLabel, size);
 }
 
 function createNativeAdapters(getCwd, vfs, config, index, ledger) {
-  async function readAdapter(params, signal) {
-      signal?.throwIfAborted();
-      const cwd = getCwd();
-      const targetParam = params?.path ?? params?.target;
-
-      if (Array.isArray(targetParam)) {
-        const results = await Promise.all(
-          targetParam.map((p) => readAdapter({ ...params, path: p }, signal)),
-        );
-        const items = results.map((r) => r.content[0].text);
-        return textResult("", { count: results.length, batch: true, items });
-      }
-
-      if (looksLikePath(targetParam)) {
-        const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
-        return readFile(targetPath, params);
-      }
-
-      const existing = await probeExistingFile(cwd, targetParam, vfs);
-      if (existing) return readFile(existing, params);
-
-      if (isString(targetParam) && targetParam.trim()) {
-        try {
-          const snapRes = await executeSnap({
-            query: targetParam,
-            searchDir: cwd,
-            index,
-            overlayText: (p) => vfs.getOverlay(p),
-            pendingPaths: vfs.getOverlayPaths(),
-          });
-          return textResult(JSON.stringify(snapRes, null, 2), { ...snapRes, isSnap: true });
-        } catch {}
-      }
+  async function sourceRead(query, searchDir, signal) {
+    const cwd = getCwd();
+    const includeHidden = path.relative(cwd, searchDir).split(path.sep)
+      .some(segment => segment.startsWith(".") && segment.length > 1);
+    const result = await executeSnap({ query, searchDir, root: cwd, includeHidden, index,
+      overlayText: p => vfs.getOverlay(p), pendingPaths: vfs.getOverlayPaths(), signal });
+    return textResult(JSON.stringify(result, null, 2), { ...result, isSnap: true });
+  }
+
+  async function readDirectory(dirPath, signal) {
+    signal?.throwIfAborted();
+    const rows = new Map();
+    for (const file of vfs.getOverlayPaths()) {
+      const relative = path.relative(dirPath, file);
+      if (!relative || relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) continue;
+      const [name, child] = relative.split(path.sep);
+      rows.set(name, child === undefined
+        ? formatDirectoryEntry(name, "file", Buffer.byteLength(vfs.getOverlay(file), "utf8"))
+        : formatDirectoryEntry(name, "dir"));
+    }
+    let entries;
+    try { entries = await fs.readdir(dirPath, { withFileTypes: true }); } catch (error) {
+      if (error.code !== "ENOENT" || rows.size === 0) throw error;
+      entries = [];
+    }
+    for (const entry of entries) if (!rows.has(entry.name)) rows.set(entry.name, await formatLsEntry(dirPath, entry));
+    return textResult([...rows.values()].join("\n"), { path: dirPath, count: rows.size });
+  }
 
-      const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
-      return readFile(targetPath, params);
+  async function readAdapter(params, signal) {
+    signal?.throwIfAborted();
+    const cwd = getCwd();
+    const targetParam = params?.path ?? params?.target;
+    if (Array.isArray(targetParam)) {
+      const results = await Promise.all(targetParam.map(p => readAdapter({ ...params, path: p }, signal)));
+      return textResult("", { count: results.length, batch: true, items: results.map(r => r.content[0].text) });
+    }
+    const existing = await probeExistingPath(cwd, targetParam, vfs);
+    if (existing) {
+      if (!existing.directory) return readFile(existing.path, params);
+      return isString(params?.about) ? sourceRead(params.about, existing.path, signal) : readDirectory(existing.path, signal);
+    }
+    if (!looksLikePath(targetParam)) return sourceRead(targetParam, cwd, signal);
+    const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
+    return readFile(targetPath, params);
   }
 
   /** Plain text, a line window, or (with `about`) a relevance-folded outline of the whole file. */
@@ -357,6 +370,7 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
         index,
         overlayText: (p) => vfs.getOverlay(p),
         pendingPaths: vfs.getOverlayPaths(),
+        signal,
       });
       return textResult(JSON.stringify(res, null, 2), res);
     },
@@ -464,13 +478,7 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
     async ls(params, signal) {
       const cwd = getCwd();
       const dirPath = params?.path ? await resolveWorkspacePath(cwd, params.path, "ls", true) : cwd;
-      if (signal?.aborted) throw new Error("aborted");
-      const entries = await fs.readdir(dirPath, { withFileTypes: true });
-      const lines = [];
-      for (const entry of entries) {
-        lines.push(await formatLsEntry(dirPath, entry));
-      }
-      return textResult(lines.join("\n"), { path: dirPath, count: entries.length });
+      return readDirectory(dirPath, signal);
     },
   };
 }
@@ -532,8 +540,12 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
 
   function isCallable(name) {
     if (name === "supernova" || (config.excludeTools ?? []).includes(name)) return false;
+    if (hostSession && (hostSession.isDisposed || hostSession.sessionManager.getSessionId() !== boundSessionId)) return false;
+    // An internal adapter belongs to Supernova, not the host's visible tool list.
+    const nativeOwned = Object.hasOwn(natives, name) && !executors.has(name)
+      && (!hostSession || !definitions.has(name) || definitions.get(name).sourceInfo?.source === "builtin");
+    if (nativeOwned) return true;
     if (hostSession) {
-      if (hostSession.isDisposed || hostSession.sessionManager.getSessionId() !== boundSessionId) return false;
       if (!hostSession.getEvalBridgeToolNames().includes(name) && definitions.has(name)) return false;
       return !!hostTool(name) || (Object.hasOwn(natives, name) && (!definitions.has(name) || definitions.get(name).sourceInfo?.source === "builtin"));
     }

package/index.js

@@ -85,19 +85,19 @@ function successText(outcome, call) {
   const hint = outcome.undefinedReturn ? " (no return statement; add `return` to get a value)" : "";
   return `ok #${call} ${outcome.wallMs}ms${truncated}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
 }
-const TOOL_DESCRIPTION = `Run one JavaScript program that composes host tools. Async body or arrow; \`return\` a small shaped value (compact literal, capped; strings raw; console.log is captured).
+const TOOL_DESCRIPTION = `Run one JavaScript program with four familiar commands: read, write, edit, bash. Use an async body or arrow. Return a small value; strings stay raw.
 
-Globals (async):
-read(path|paths, offset?, limit?) → text | text[] · read(path, {about}) → whole-file outline, only relevant bodies expanded
-write(path, text) · edit(path, oldText, newText) → post-edit lines (no re-read needed) · patch(path, unifiedDiff)
-bash(cmd, {cwd?, timeoutMs?}) → output, throws on non-zero exit · exec(cmd, argv?) quotes argv
-evidence(query, {k?}) → {spans: [{path, lines, name, text}]} top-K spans that answer a question; use before read
-snap(query, root?) → {path, line, signature, context} · surface(path) → {items: [{name, kind, line}]}
-nova.call(name, args) → {ok, value} for any host tool · nova.callMany([{name, args}]) parallel when read-only
-nova.search(query) → [{name, description}] · nova.describe(name) → parameters · nova.has(name) sync
-parallel(thunks) · pipeline(items, ...stages)
+Native commands (async):
+read(path|paths, offset?, limit?) → file text or text[]; read(directory) → directory entries
+read("symbol or question") → JSON text with source location and context; no separate search tool needed
+read(path, {about: question}) → relevant file bodies, or source selection inside a directory
+write(path, text) → write a file
+edit(path, oldText, newText) → post-edit lines, checks, and references; no verification read needed
+bash(command, {cwd?, timeoutMs?}) → bounded output; throws on non-zero exit
 
-Already-seen lines collapse to "⋯ N lines same as #12 · path:a–b ⋯"; read(path, a, n) re-shows them.`;
+Source selection reports found, ambiguous, not_found, or incomplete. Only found selects a path. Narrow the directory for uncertain results.
+Optional composition: parallel(thunks), pipeline(items, ...stages), nova.call(name, args), nova.callMany(calls). Use nova.search/describe only for other host tools.
+Already-seen lines collapse to references; read(path, firstLine, lineCount) shows them again. console.log is captured.`;
 
 export default function piSupernova(pi) {
   const config = loadConfig();
@@ -150,9 +150,9 @@ export default function piSupernova(pi) {
     name: "supernova",
     label: "Supernova",
     description: TOOL_DESCRIPTION,
-    promptSnippet: "Compose host tools in one JavaScript program",
+    promptSnippet: "Use read, write, edit, and bash in one program",
     promptGuidelines: [
-      "Use supernova for multi-step tool work: loops, filtering, parallel reads, read→edit chains. To understand code: evidence(question) across the repo, or read(path, {about: question}) for one file: full structure, only relevant bodies expanded. Plain read(path) only for lines you will edit. Return a compact shaped value; keep raw tool output inside the program.",
+      "Use read, write, edit, and bash inside supernova. Start with read(question), or read(directory, {about: question}) for scoped source selection. Read file bodies with read(file, {about: question}). Check source selection status before using its path. Return a compact value.",
     ],
     parameters: Type.Object({
       code: Type.String({ description: "JavaScript program: async body or arrow function." }),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-supernova",
-  "version": "0.1.0",
-  "description": "Dual-host CodeMode for Pi/OMP: progressive tool discovery, result bottleneck, and Amdahl Auto parallel.",
+  "version": "0.2.0",
+  "description": "CodeMode for Pi and OMP: read, write, edit, and bash with source selection and bounded results.",
   "type": "module",
   "author": "AdityaVG13",
   "license": "MIT",

package/repo-index.js

@@ -150,7 +150,7 @@ export class WorkspaceIndex {
   }
 
   /** Absolute, sorted file list for a root; gitignore-aware via rg; cached for LIST_TTL_MS. */
-  async files(root, includeHidden = false) {
+  async files(root, includeHidden = false, signal) {
     const key = root + "\0" + (includeHidden ? "h" : "");
     const cached = this.lists.get(key);
     const ttl = this.watch(root) ? WATCHED_TTL_MS : LIST_TTL_MS;
@@ -159,13 +159,21 @@ export class WorkspaceIndex {
     if (includeHidden) args.push("--hidden");
     args.push("-g", "!.git/**", "-g", "!**/.git/**", root);
     let files = [];
+    let error;
+    let truncated = false;
+    let missing = false;
     try {
-      const res = await this.runCommand(args, { cwd: root, timeoutMs: 15_000 });
-      files = res.stdout.split("\n").map((f) => f.trim()).filter(Boolean).map((f) => path.resolve(root, f)).sort();
-    } catch {
-      files = [];
+      const res = await this.runCommand(args, { cwd: root, timeoutMs: 15_000, signal });
+      if (res.exitCode !== 0 && res.exitCode !== 1) error = res.stderr.trim() || "rg exited with status " + res.exitCode;
+      truncated = res.outputTruncated === true;
+      const output = truncated && !res.stdout.endsWith("\n") ? res.stdout.slice(0, res.stdout.lastIndexOf("\n") + 1) : res.stdout;
+      files = output.split("\n").filter(Boolean).map(f => path.resolve(root, f)).sort();
+    } catch (err) {
+      signal?.throwIfAborted();
+      error = err.message;
+      missing = !fs.existsSync(root);
     }
-    this.lists.set(key, { files, at: Date.now() });
+    this.lists.set(key, { files, at: Date.now(), error, truncated, missing });
     return files;
   }
 

package/snap.js

@@ -1,7 +1,8 @@
-
 import * as path from "node:path";
 import { isString } from "./decode.js";
+import { truncateChars } from "./format.js";
 import { WorkspaceIndex } from "./repo-index.js";
+import { extractStructuralSurface } from "./surface.js";
 import { isTestPath } from "./workspace.js";
 
 const STOP_WORDS = new Set([
@@ -9,240 +10,208 @@ const STOP_WORDS = new Set([
   "by", "from", "is", "it", "this", "that", "where", "how", "what", "which",
   "file", "code", "function", "class", "method", "find", "get", "look",
 ]);
+const SOURCE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".rs", ".py", ".go"]);
+const TYPED_EXT = new Set([".ts", ".tsx", ".rs", ".go"]);
+const MAX_SEARCH_CHARS = 2 * 1024 * 1024;
+const MAX_ALTERNATIVES = 3;
 
 export function tokenizeQuery(query) {
-  if (!isString(query) || !query.trim()) {
-    return { tokens: [], wantsTest: false, wantsType: false, wantsDoc: false };
-  }
-
-  const raw = query
-    .replace(/([a-z])([A-Z])/g, "$1 $2")
-    .toLowerCase()
-    .split(/[^a-zA-Z0-9_]+/);
-
-  const tokens = raw.filter((t) => t.length > 1 && !STOP_WORDS.has(t));
-  const queryLower = query.toLowerCase();
-
+  if (!isString(query) || !query.trim()) return { tokens: [], wantsTest: false, wantsType: false, wantsDoc: false };
+  const words = query.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-zA-Z0-9_]+/);
   return {
-    tokens: [...new Set(tokens)],
-    wantsTest: queryLower.includes("test") || queryLower.includes("spec"),
-    wantsType: queryLower.includes("type") || queryLower.includes("interface") || queryLower.includes("schema"),
-    wantsDoc: queryLower.includes("doc") || queryLower.includes("readme"),
+    tokens: [...new Set(words.filter(word => word.length > 1 && !STOP_WORDS.has(word)))],
+    wantsTest: words.some(word => ["test", "tests", "testing", "spec", "specs"].includes(word)),
+    wantsType: words.some(word => ["type", "types", "interface", "interfaces", "schema", "schemas"].includes(word)),
+    wantsDoc: words.some(word => ["doc", "docs", "documentation", "readme"].includes(word)),
   };
 }
 
-const SOURCE_EXT = new Set([".ts", ".js", ".mjs", ".rs", ".py", ".go"]);
-const TYPED_EXT = new Set([".ts", ".d.ts", ".rs", ".go"]);
-const VENDOR_SEGMENTS = ["node_modules/", "dist/", "target/"];
-
-function tokenPathScore(token, basename, pathParts, norm) {
-  if (basename === token || basename.startsWith(token + ".")) return 60;
-  if (basename.includes(token)) return 30;
-  if (pathParts.includes(token)) return 15;
-  if (norm.includes(token)) return 5;
-  return 0;
-}
-
-function extensionBonus(ext, { wantsDoc, wantsType }) {
-  let bonus = 0;
-  if (SOURCE_EXT.has(ext) && !wantsDoc) bonus += 5;
-  if (wantsType && TYPED_EXT.has(ext)) bonus += 10;
-  return bonus;
-}
-
 export function scorePathTopology(filePath, tokens, flags) {
-  const norm = filePath.replaceAll("\\", "/").toLowerCase();
-  const isTest = norm.includes("test") || norm.includes("spec") || norm.includes("__tests__");
-  if (isTest && !flags.wantsTest) return -50;
-  if (!isTest && flags.wantsTest) return -20;
-  if (VENDOR_SEGMENTS.some((segment) => norm.includes(segment))) return -100;
-
-  const basename = path.basename(norm);
-  const pathParts = norm.split(/[^a-zA-Z0-9]+/);
-  let score = extensionBonus(path.extname(norm), flags);
-  for (const token of tokens) score += tokenPathScore(token, basename, pathParts, norm);
-  return score;
-}
-
-function isSkippableLine(lower) {
-  return !lower || lower.startsWith("//") || lower.startsWith("#") || lower.startsWith("*");
-}
-
-/** A line defines a token only when the declared name contains it; `const x = foo(token)` is a mention. */
-function lineScoreFor(lower, tokens, definedName) {
-  let lineScore = 0;
+  const normalized = filePath.replaceAll("\\", "/").toLowerCase();
+  const parts = normalized.split("/");
+  if (parts.some(part => ["node_modules", "dist", "target"].includes(part))) return -100;
+  const test = isTestPath(normalized);
+  if (test && !flags.wantsTest) return -50;
+  if (!test && flags.wantsTest) return -20;
+  const base = path.basename(normalized);
+  const words = normalized.split(/[^a-zA-Z0-9]+/);
+  const ext = path.extname(normalized);
+  let score = SOURCE_EXT.has(ext) && !flags.wantsDoc ? 5 : 0;
+  if (flags.wantsType && TYPED_EXT.has(ext)) score += 10;
   for (const token of tokens) {
-    if (!lower.includes(token)) continue;
-    lineScore += definedName.includes(token) ? 40 : 5;
+    if (base === token || base.startsWith(token + ".")) score += 60;
+    else if (base.includes(token)) score += 30;
+    else if (words.includes(token)) score += 15;
+    else if (normalized.includes(token)) score += 5;
   }
-  return lineScore;
+  return score;
 }
 
-// Mentions are capped so a file that calls a symbol many times cannot outrank the file that defines it.
-const MAX_MENTION_SCORE = 60;
-
-function scoreContentDefinitions(entry, tokens) {
-  const { lower, defNames } = WorkspaceIndex.linesOf(entry);
-  let defScore = 0;
-  let mentionScore = 0;
-  let bestLine = 1;
-  let bestLineScore = 0;
-  for (let i = 0; i < lower.length; i++) {
-    if (isSkippableLine(lower[i])) continue;
-    const lineScore = lineScoreFor(lower[i], tokens, defNames[i]);
-    if (lineScore > bestLineScore) {
-      bestLineScore = lineScore;
-      bestLine = i + 1;
+function inScope(filePath, dir, includeHidden) {
+  const relative = path.relative(dir, filePath);
+  if (relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) return false;
+  const parts = relative.split(path.sep);
+  return !parts.includes(".git") && (includeHidden || !parts.some(part => part.startsWith(".") && part.length > 1));
+}
+
+function makeCandidate(filePath, dir, query, tokens, flags) {
+  const relative = path.relative(dir, filePath);
+  const lower = relative.toLowerCase();
+  const base = path.basename(lower);
+  const exactPath = lower === query.toLowerCase() || base === query.toLowerCase()
+    || base.slice(0, -path.extname(base).length) === query.toLowerCase();
+  return { path: filePath, pathScore: scorePathTopology(relative, tokens, flags), exactPath,
+    pathCoverage: tokens.filter(token => lower.includes(token)).length,
+    matched: new Set(), exactDefinition: false, definitionCoverage: 0, lineCoverage: 0,
+    line: 1, signature: "", context: new Map(), recent: [], anchorScore: -1 };
+}
+
+function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
+  const text = raw.replace(/\r?\n$/, "");
+  const lower = text.toLowerCase();
+  if (isMatch) {
+    const matches = tokens.filter(token => lower.includes(token));
+    for (const token of matches) candidate.matched.add(token);
+    const ext = path.extname(candidate.path).toLowerCase();
+    const items = SOURCE_EXT.has(ext) ? extractStructuralSurface(text, ext).items : [];
+    let declaration;
+    let definitionCoverage = 0;
+    let exact = false;
+    for (const item of items) {
+      const name = item.name.toLowerCase();
+      const itemExact = name === query.toLowerCase();
+      const coverage = tokens.filter(token => name.includes(token)).length;
+      if (itemExact || coverage > definitionCoverage) { declaration = item; definitionCoverage = coverage; exact = itemExact; }
+      if (exact) break;
+    }
+    const score = (exact ? 10000 : 0) + definitionCoverage * 40 + matches.length;
+    if (score > candidate.anchorScore) {
+      candidate.anchorScore = score;
+      candidate.line = lineNumber;
+      candidate.signature = truncateChars(declaration?.signature ?? "", 240, "signature").text;
+      candidate.exactDefinition = exact;
+      candidate.definitionCoverage = definitionCoverage;
+      candidate.lineCoverage = matches.length;
+      candidate.context.clear();
+      for (const [number, line] of candidate.recent) if (number >= lineNumber - 2) candidate.context.set(number, line);
     }
-    if (defNames[i]) defScore += lineScore;
-    else mentionScore += lineScore;
-  }
-  return { totalScore: defScore + Math.min(mentionScore, MAX_MENTION_SCORE), bestLine, bestLineScore };
-}
-
-function relativeHasSegment(relativePath, segmentName) {
-  return relativePath.split(path.sep).includes(segmentName);
-}
-
-function relativeHasHiddenSegment(relativePath) {
-  return relativePath.split(path.sep).some((segment) => segment.startsWith(".") && segment.length > 1);
-}
-
-async function listCandidateFiles(dir, includeHidden, index) {
-  return (await index.files(dir, includeHidden)).slice();
-}
-
-function mergePendingPaths(fileList, pendingPaths, dir, includeHidden = false) {
-  const resolvedDir = path.resolve(dir);
-  const seenPaths = new Set(fileList.map((filePath) => path.resolve(filePath)));
-  for (const pendingPath of pendingPaths) {
-    const absolutePath = path.resolve(pendingPath);
-    const relativePath = path.relative(resolvedDir, absolutePath);
-    const escapesDir = relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
-    const hiddenRelativePath = relativeHasHiddenSegment(relativePath);
-    if (escapesDir || relativeHasSegment(relativePath, ".git") || (!includeHidden && hiddenRelativePath) || seenPaths.has(absolutePath)) continue;
-    seenPaths.add(absolutePath);
-    fileList.push(absolutePath);
-  }
-  return fileList;
-}
-
-function mergeGrepHits(candidates, grepHits) {
-  const seen = new Set(candidates);
-  for (const h of grepHits) {
-    if (seen.has(h)) continue;
-    seen.add(h);
-    candidates.push(h);
-    if (candidates.length >= 15) break;
   }
-  return candidates;
-}
-
-function expandCandidatesWithGrep(candidates, fileList, tokens, flags, index) {
-  if (candidates.length >= 5) return candidates;
-  const salient = tokens.filter((t) => t.length > 2).slice(0, 4);
-  const scope = flags.wantsTest ? fileList : fileList.filter((f) => !isTestPath(f));
-  const hits = index.filesContaining(scope, salient, true);
-  mergeGrepHits(candidates, hits);
-  if (candidates.length === 0) return fileList.slice(0, 5);
-  return candidates;
-}
-
-function scoreSurfaceItems(items, tokens, fallbackLine) {
-  let bonus = 0;
-  let best = null;
-  let bestMatches = 0;
-  for (const item of items) {
-    const nameLower = item.name.toLowerCase();
-    const matches = tokens.filter((token) => nameLower.includes(token)).length;
-    if (matches === 0) continue;
-    bonus += matches * (item.isExport ? 80 : 50);
-    if (matches > bestMatches) {
-      bestMatches = matches;
-      best = item;
+  const excerpt = truncateChars(text, 240, "source line").text;
+  if (lineNumber >= candidate.line - 2 && lineNumber <= candidate.line + 4) candidate.context.set(lineNumber, excerpt);
+  candidate.recent.push([lineNumber, excerpt]);
+  if (candidate.recent.length > 2) candidate.recent.shift();
+}
+
+function inspectOverlay(candidate, text, needles, query, tokens) {
+  const lines = text.split("\n");
+  const matches = [];
+  for (let i = 0; i < lines.length; i++) if (needles.some(needle => lines[i].toLowerCase().includes(needle))) matches.push(i);
+  for (const i of matches) inspectLine(candidate, i + 1, lines[i], query, tokens, true);
+  candidate.context.clear();
+  for (let i = Math.max(0, candidate.line - 3); i < Math.min(lines.length, candidate.line + 4); i++) candidate.context.set(i + 1, truncateChars(lines[i], 240, "source line").text);
+}
+
+async function contentCandidates({ dir, includeHidden, query, tokens, flags, fileSet, index, overlayText, signal, exact, diskFiles }) {
+  const needles = exact ? [query.toLowerCase()] : tokens;
+  const args = ["rg", "--json", "--fixed-strings", "--ignore-case", "--before-context", "2", "--after-context", "4"];
+  if (includeHidden) args.push("--hidden");
+  args.push("-g", "!.git/**", "-g", "!**/.git/**");
+  for (const needle of needles) args.push("-e", needle);
+  args.push("--", dir);
+  const response = diskFiles ? await index.runCommand(args, { cwd: dir, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS, signal })
+    : { stdout: "", stderr: "", exitCode: 1 };
+  if (response.exitCode !== 0 && response.exitCode !== 1) throw new Error("source search failed: " + response.stderr.trim());
+  const candidates = new Map();
+  const records = response.stdout.split("\n");
+  for (let i = 0; i < records.length; i++) {
+    if (!records[i]) continue;
+    let record;
+    try { record = JSON.parse(records[i]); } catch (error) {
+      if (response.outputTruncated && i === records.length - 1) break;
+      throw error;
     }
+    if (record.type !== "match" && record.type !== "context") continue;
+    const data = record.data;
+    if (!data?.path?.text || !isString(data.lines?.text)) continue;
+    const filePath = path.resolve(dir, data.path.text);
+    if (!fileSet.has(filePath) || overlayText(filePath) !== undefined) continue;
+    let candidate = candidates.get(filePath);
+    if (!candidate) {
+      candidate = makeCandidate(filePath, dir, query, tokens, flags);
+      candidates.set(filePath, candidate);
+    }
+    inspectLine(candidate, data.line_number, data.lines.text, query, tokens, record.type === "match");
   }
-  return { bonus, signature: best?.signature ?? "", anchorLine: best?.line ?? fallbackLine };
-}
-
-function scoreCandidateContents(candidates, tokens, flags, index, overlayText) {
-  const candidateScores = [];
-  for (const filePath of candidates) {
+  for (const filePath of fileSet) {
     const pending = overlayText(filePath);
-    const entry = pending === undefined ? index.entry(filePath) : WorkspaceIndex.fromText(filePath, pending);
-    if (!entry) continue;
-    const content = entry.text;
-    const { totalScore, bestLine, bestLineScore } = scoreContentDefinitions(entry, tokens);
-    const surface = WorkspaceIndex.surfaceOf(entry);
-    const { bonus: surfaceBonus, signature, anchorLine } = scoreSurfaceItems(surface.items, tokens, bestLine);
-    const lowerPath = filePath.toLowerCase();
-    const isTestFile = lowerPath.includes("test") || lowerPath.includes("spec");
-    const testAdjustment = !isTestFile ? 0 : (flags.wantsTest ? 100 : -200);
-    candidateScores.push({
-      path: filePath,
-      score: totalScore + surfaceBonus + (bestLineScore * 2) + testAdjustment,
-      anchorLine,
-      signature,
-      content,
-    });
+    if (pending === undefined) continue;
+    const candidate = makeCandidate(filePath, dir, query, tokens, flags);
+    inspectOverlay(candidate, pending, needles, query, tokens);
+    if (candidate.matched.size) candidates.set(filePath, candidate);
   }
-  candidateScores.sort((a, b) => b.score - a.score);
-  return candidateScores;
+  return { candidates, truncated: response.outputTruncated === true };
 }
 
-function rankCandidates(fileList, tokens, flags, index, overlayText) {
-  const scoredPaths = [];
-  for (const f of fileList) {
-    const score = scorePathTopology(f, tokens, flags);
-    if (score > 0) scoredPaths.push({ path: f, score });
-  }
-  scoredPaths.sort((a, b) => b.score - a.score);
-  const selected = scoredPaths.filter((p) => p.score >= 25).slice(0, 10).map((p) => p.path);
-  const candidates = expandCandidatesWithGrep(selected, fileList, tokens, flags, index);
-  const candidateScores = scoreCandidateContents(candidates, tokens, flags, index, overlayText);
-  return { candidates, candidateScores };
+function rankScore(candidate, tokenCount) {
+  return (candidate.exactDefinition ? 10000 : 0) + (candidate.exactPath ? 500 : 0)
+    + candidate.definitionCoverage / tokenCount * 100 + candidate.matched.size / tokenCount * 30
+    + candidate.pathCoverage / tokenCount * 20 + candidate.lineCoverage / tokenCount * 10
+    + Math.max(-40, Math.min(20, candidate.pathScore / 5));
 }
 
-function buildSnapResult(candidates, candidateScores, fileList, root) {
-  const relative = (p) => path.relative(root, p) || p;
-  if (candidateScores.length === 0 || candidateScores[0].score <= 0) {
-    return { path: relative(candidates[0] || fileList[0]), line: 1, signature: "", confidence: 0.3, context: [] };
-  }
-  const best = candidateScores[0];
-  const lines = best.content.split("\n");
-  // Two lines before and four after: enough to confirm the hit; read() is the tool for more.
-  const startLine = Math.max(1, best.anchorLine - 2);
-  const endLine = Math.min(lines.length, best.anchorLine + 4);
-  const context = [];
-  for (let l = startLine; l <= endLine; l++) {
-    const marker = l === best.anchorLine ? "►" : " ";
-    context.push(marker + l + " " + lines[l - 1]);
-  }
-  const confidence = Math.min(0.98, Math.max(0.65, best.score / 150));
-  return {
-    path: relative(best.path),
-    line: best.anchorLine,
-    signature: best.signature,
-    confidence: Number(confidence.toFixed(2)),
-    context,
-  };
-}
-
-export async function executeSnap({ query, searchDir, root, includeHidden = false, index, overlayText = () => undefined, pendingPaths = [] }) {
-  const { tokens, wantsTest, wantsType, wantsDoc } = tokenizeQuery(query);
-  if (tokens.length === 0) {
-    throw new Error("snap requires at least one searchable concept keyword");
-  }
-  const dir = searchDir || process.cwd();
-  if (path.resolve(dir).split(path.sep).includes(".git")) {
-    throw new Error("snap cannot search Git metadata");
+function location(candidate, root, index, overlayText) {
+  let context = candidate.context;
+  if (context.size === 0) {
+    const pending = overlayText(candidate.path);
+    const entry = pending === undefined ? index.entry(candidate.path) : WorkspaceIndex.fromText(candidate.path, pending);
+    const lines = entry?.text.split("\n") ?? [];
+    context = new Map(lines.slice(0, 7).map((line, i) => [i + 1, truncateChars(line, 240, "source line").text]));
   }
-  const fileList = await listCandidateFiles(dir, includeHidden, index);
-  mergePendingPaths(fileList, pendingPaths, dir, includeHidden);
-  if (fileList.length === 0) {
-    throw new Error(`no files found to search in ${dir}`);
+  return { path: path.relative(root, candidate.path), line: candidate.line, signature: candidate.signature,
+    context: [...context].sort((a, b) => a[0] - b[0]).map(([line, text]) => (line === candidate.line ? "►" : " ") + line + " " + text) };
+}
+
+export async function executeSnap({ query, searchDir, root, includeHidden = false, index, overlayText = () => undefined, pendingPaths = [], signal }) {
+  const flags = tokenizeQuery(query);
+  const { tokens } = flags;
+  if (tokens.length === 0) throw new Error("read requires a file path or a searchable source question");
+  if (tokens.length > 16) throw new Error("source question is too broad; use at most 16 keywords");
+  query = query.trim();
+  const dir = path.resolve(searchDir || process.cwd());
+  if (dir.split(path.sep).includes(".git")) throw new Error("cannot search Git metadata");
+  signal?.throwIfAborted();
+  flags.wantsTest ||= isTestPath(path.relative(root ?? dir, dir));
+  const files = await index.files(dir, includeHidden, signal);
+  const fileSet = new Set(files.filter(file => inScope(file, dir, includeHidden)));
+  for (const pending of pendingPaths) if (inScope(pending, dir, includeHidden)) fileSet.add(path.resolve(pending));
+  const listing = index.lists.get(dir + "\0" + (includeHidden ? "h" : ""));
+  if (listing?.error && !(listing.missing && fileSet.size)) throw new Error("source file listing failed: " + listing.error);
+  const empty = { path: null, line: null, signature: "", confidence: 0, context: [] };
+  if (fileSet.size === 0 && !listing?.truncated) return { ...empty, status: "not_found" };
+  const exact = /^[a-zA-Z_$][\w$]*$/.test(query);
+  const search = await contentCandidates({ dir, includeHidden, query, tokens, flags, fileSet, index, overlayText, signal, exact, diskFiles: files.length });
+  for (const filePath of fileSet) {
+    if (search.candidates.has(filePath)) continue;
+    const relative = path.relative(dir, filePath).toLowerCase();
+    if (!tokens.some(token => relative.includes(token))) continue;
+    if (exact && tokens.length > 1 && !relative.includes(query.toLowerCase())) continue;
+    const candidate = makeCandidate(filePath, dir, query, tokens, flags);
+    if (candidate.pathScore > 0) search.candidates.set(filePath, candidate);
   }
-  const flags = { wantsTest, wantsDoc, wantsType };
-  const { candidates, candidateScores } = rankCandidates(fileList, tokens, flags, index, overlayText);
-  return buildSnapResult(candidates, candidateScores, fileList, root ?? dir);
+  const ranked = [...search.candidates.values()].filter(candidate => candidate.pathScore > -50)
+    .map(candidate => ({ ...candidate, score: rankScore(candidate, tokens.length) }))
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+  const incomplete = search.truncated || listing?.truncated === true;
+  const relativeRoot = root ?? dir;
+  const candidates = ranked.slice(0, MAX_ALTERNATIVES).map(candidate => location(candidate, relativeRoot, index, overlayText));
+  if (incomplete) return { ...empty, status: "incomplete", candidates, message: "Search output exceeded its budget. Narrow the directory with read(path, {about: question})." };
+  if (!ranked.length) return { ...empty, status: "not_found" };
+  const best = ranked[0];
+  const second = ranked[1];
+  const margin = second ? (best.score - second.score) / Math.max(1, best.score) : 1;
+  const coverage = Math.max(best.matched.size, best.pathCoverage) / tokens.length;
+  const uniqueExact = best.exactDefinition && !second?.exactDefinition || best.exactPath && !second?.exactPath && !second?.exactDefinition;
+  if (!uniqueExact && (coverage < 0.6 || margin < 0.15 || best.definitionCoverage / tokens.length < 0.5)) return { ...empty, status: "ambiguous", candidates };
+  const confidence = uniqueExact ? 0.95 : Math.min(0.85, 0.5 + coverage * 0.2 + margin * 0.15);
+  return { ...candidates[0], status: "found", confidence: Number(confidence.toFixed(2)) };
 }