pi-supernova 0.0.8 → 0.0.15

package/CHANGELOG.md

@@ -2,12 +2,95 @@
 
 ## [Unreleased]
 
+## [0.0.15] - 2026-09-04
+
+### Removed
+
+- Dead code (−638 lines net): the static `extractOperationsFromCode` source-regex preview (the live trace superseded it), `SafeText`/`fitOutputLines`/`wrapPlainToWidth` (the call slot is always empty), `shutdownGuestWorkers`, `decode.js` helpers nobody imported, `vfs.clear`, the `tools` alias for `nova`, unused bridge methods (`hasExecutor`, `clearVfsCache`, `isMutating`), `test/verify-width-crash.mjs`, and unused status-header knobs (`spinnerFrame`, `iconOverride`).
+- `edit` no longer accepts a unified diff (`patch`/`oldText` starting with `@@`); `apply_patch` / `patch()` is the one way to apply a diff.
+- `nova.surface`/`nova.snap` host-side unwrapping and their dedicated RPC methods: both route through `nova.call` and the guest unwraps once.
+
+### Changed
+
+- One `relativeSlash`, one `isTestPath`, one declaration-span computation (`WorkspaceIndex.spansOf`, cached per file) instead of three copies each; search adapters (fuzzy find, grep, glob listing) live in `search.js`; internal-only names are no longer exported.
+- Render computes the card body once per width (was twice); fuzzy find stats only matched paths (was every file); results shorter than a collapsible run skip ledger hashing.
+
+### Fixed
+
+- `nova.speculate` end-to-end (an end-to-end test now covers rollback and commit through the worker RPC).
+
+## [0.0.14] - 2026-09-04
+
+### Added
+
+- **Seen-ledger.** The model's context window is treated as memory: a result never re-sends a run of lines (≥6, mostly substantive) that an earlier result in the session already contained. The run collapses to `⋯ N lines same as #12 · path:a–b ⋯`, citing the earlier program and, when the lines came from a file, the exact range, so one `read(path, a, n)` recovers them. Changed lines are never collapsed, so a re-read after an edit is exactly the delta. Lines the current program read with an explicit `offset`/`limit` are pinned and always shown. Programs are numbered (`ok #12 3ms`) to anchor the citations; the window is `seenWindow` programs (default 40) and resets on `session_start`. Not compression: every collapsed line already exists verbatim in the model's context. `/supernova` reports the session's returned vs. not-re-sent tokens.
+- **Edits close the loop.** `edit` returns the post-edit lines with numbers (±2 context, ≤40 lines) so no verification re-read is needed; a quick structural check (`check: unclosed '{' opened at line 1`, JSON parsed exactly; brackets/strings/templates/regex-aware, 0 false positives over 6,100 source files); and `X also referenced in a.js:12, b.js:40` for every declaration the edit changed, so callers are not forgotten.
+- **Failures carry their source.** A failing `bash` appends `--- source` with ±2 lines around each `path:line` it printed (≤4 sites), so a stack trace or test failure does not cost a read turn.
+- **Outlines carry relations.** Expanded spans in `read(path, {about})` end with `// used by: a.js:12, b.js:40`.
+
+Measured on a read→edit→verify→edit→verify→outline→outline loop: 20,967 tokens naive vs **3,098** (−85%); the verification re-read costs 49 tokens instead of 1,078.
+
+### Changed
+
+- README documents the research (Zero-Mem, Agent Zero Memory, Harness-of-Harness, SPACE) and the fff port precisely: which formulas and constants are fff's, what was not ported, and that the code was reimplemented in JavaScript after reading fff's Rust sources.
+
+## [0.0.13] - 2026-09-04
+
+### Fixed
+
+- A program that made no host calls rendered an empty frame (`╭─ nova: complete ─╮ / ╰──╯`); it is now a single status line. Expanded view still frames the returned value.
+
+## [0.0.12] - 2026-09-04
+
+### Added
+
+- `read(path, {about})`: one call returns the whole file as an outline: every declaration (including nested object/class methods) with its signature and line range, and only the bodies relevant to `about` expanded, with line numbers, under a character budget (default 8000, 6 spans, weak-match cutoff at 40% of the best span). A folded body reads `  75 function applyReplacements(target, content, edits) … 26 lines`, so the follow-up `read(path, 75, 26)` is known without another search. Across 5 files/questions: **65% fewer tokens** than reading the file (23,968 → 8,477), correct spans expanded.
+- fff (dmtrKovalenko/fff) ported to plain JS in `fuzzy.js`, no binary and no spawn:
+  - `glob`/`find` with free text (no glob characters) is a typo-tolerant, frecency-ranked path search: up to 2 skipped characters, smart-case, +40%/+20% exact/any filename bonus, frecency boost `base·f/100` with fff's AI-mode decay (3-day half-life, 7-day window, 30s…4h modification steps), +15% for git-modified files, directory-distance penalty from the last touched file.
+  - `grep` is smart-case, groups rows under one path header, lists files that *declare* the name first with declaration lines marked `*` (definition-first hinting), accepts `limit`, and falls back to a fuzzy line match when the literal has no hits (`CausualVfs` → `class CausalVfs`).
+  - The workspace index watches the tree with `fs.watch` (recursive) and refreshes on change instead of every 10s; TTL remains the fallback when watching is unavailable.
+- Structural surface detects indented methods (`async bash(params, signal) {`, `name: (a) => {`), so adapters and class members are their own spans for `evidence`, `snap`, and outlines.
+
+### Changed
+
+- Tool guidance: `evidence(question)` across the repo or `read(path, {about})` for one file; plain `read(path)` only for lines you will edit.
+
+## [0.0.11] - 2026-09-04
+
+### Added
+
+- `evidence(query, {k?, path?, maxChars?})`: zero-token evidence selection over the codebase after Zero-Mem (arXiv:2607.29377), implemented 1:1 with the paper's non-generative pipeline: declared spans are the context units and identifiers the entities (eq.3), entity–span weights `w(d,e)=c(e,d)/Σc` (eq.4), file→span→line hierarchy (eq.5, eq.11), a deterministic query profile and relational/local route (eq.6–7), lexical entity alignment and one IDF-damped co-occurrence propagation step (eq.8–9), personalized PageRank `π=(1−γ)r+γPᵀπ` over spans (eq.10, γ=0.85, 10 iterations, factored through the entity layer so it is O(nnz)), per-view min-max normalisation and ρ-weighted fusion (eq.12–13, ρ=0.7), closure with definition bridges and in-file neighbours (eq.14), and calibration that filters by boundary/answer type/lexical support and ranks by type compatibility (eq.15). Returns top-K (default 5, per the paper's Top-5 ≈ Top-10 finding) verbatim source spans with path and line provenance under a 6000-char budget. Across 8 understanding questions on this repo the correct span ranks first and the result costs **68% fewer tokens** than reading the files the question spans (43,916 → 14,147). Warm latency 1–4ms.
+- Structural surface now records column-0 `const/let/var` bindings, so module-level tables are their own spans (also sharpens `snap`).
+
+### Changed
+
+- Tool guidance: "To understand code, call `evidence(question)` and read only the returned spans; read whole files only to edit them" (Agent Zero Memory's L0→L1→L2 read discipline; Harness-of-Harness progressive disclosure).
+
+## [0.0.10] - 2026-09-04
+
+### Changed
+
+- In-process workspace index (`repo-index.js`): one gitignore-aware `rg --files` per 10s window, then file text, lowercase lines, declared names, and structural surfaces are cached per path and validated by mtime. `snap`, `grep`, `glob`, and `find` are served from it without spawning (trees over 4000 files fall back to `rg`). Warm latencies: snap 14ms → 0.36ms, grep 4.8ms → 0.15ms, glob 4.7ms → 0.06ms; a warm `nova.call` is ~20µs and the program floor is ~50µs.
+- `bash` and any on-disk write or commit invalidate the file list, so a file created by a shell command is visible to the next `glob` in the same program.
+- Workspace-path realpath checks are cached per program (two syscalls per call before).
+- Live card updates are coalesced to one host re-render per 40ms frame; a tight loop of calls no longer pays a TUI render per call.
+- Fewer result tokens: `snap` returns a workspace-relative path and a 7-line context window (`►36 text`); `grep` rows are relative; `nova.search` hits drop `callable:true`; `nova.describe` omits `required:false` and the redundant `signature` line.
+
+## [0.0.9] - 2026-09-04
+
+### Fixed
+
+- `snap` returns the defining file and line. `const x = fn(...)` call sites matched the definition regex and earned definition credit, so the busiest caller outranked the definer; definition credit now requires the declared name to contain a query token, mention credit is capped per file, and the anchor is the surface item with the most token matches (`resolveWorkspacePath`, not `getResolvedCwd`).
+- Success cards draw a visible frame. `borderMuted` is background-level in OMP themes, so only error cards had a border; success uses `dim`.
+- Failed calls show their error on the row instead of `done`; rows with no target show nothing.
+- `read([...paths])` rows read `2 files: a.js, b.js` instead of a comma-joined path list.
+
 ## [0.0.8] - 2026-09-04
 
 ### Changed
 
 - Result card redesigned as an aligned ledger: one row per call (status · tool · duration · `exit N` · `+a/-r` · target), no tree stems or spacer rows, durations humanized (`6.2s`), multi-line commands shown as their first line plus `…+N lines`, and paths fitted to width with the basename kept. Trace records now carry per-call `ms` and non-zero `exitCode`.
-- Guest programs run in a warm worker thread. A hard timeout or abort now terminates synchronous loops (`while (true) {}`), `process.exit()` only ends the program, and `maxHeapMb` (V8 `resourceLimits` plus a process-RSS watchdog for Bun) stops memory blow-ups — none of these can take the host down anymore. Warm-worker overhead is ~0.1ms per program and ~20µs per `nova.call`.
+- Guest programs run in a warm worker thread. A hard timeout or abort now terminates synchronous loops (`while (true) {}`), `process.exit()` only ends the program, and `maxHeapMb` (V8 `resourceLimits` plus a process-RSS watchdog for Bun) stops memory blow-ups. None of these can take the host down anymore. Warm-worker overhead is ~0.1ms per program and ~20µs per `nova.call`.
 - Result text is a compact JS literal (`ok 12ms` header, unquoted keys, no separator whitespace, one item per line only past 120 columns): ~43% fewer tokens than the previous pretty JSON. Logs appear under `--- logs` only when present.
 - `maxReturnChars` default lowered from 200000 to 32000.
 - Return values that JSON cannot express are rendered instead of collapsing to `[object Object]`: circular references, `Map`, `Set`, `BigInt`, `Error`, functions, typed arrays.
@@ -66,7 +149,7 @@
 
 ### Fixed
 
-- OMP no longer hangs on "Loading plugins…" — removed top-level import of `@oh-my-pi/pi-coding-agent/tui` from the extension (portable framed chrome only).
+- OMP no longer hangs on "Loading plugins…": removed top-level import of `@oh-my-pi/pi-coding-agent/tui` from the extension (portable framed chrome only).
 
 ## [0.0.3] - 2026-09-03
 

package/README.md

@@ -25,7 +25,7 @@ Load **before** other tool-owning packages so `registerTool` capture works. Rest
 | Parallel reads | Ad hoc | `callMany` Auto / `parallel()` |
 | Hosts | Separate packages | Same tarball for Pi **and** OMP |
 
-Guest code runs as an `AsyncFunction` in a worker thread (same trust class as host `bash`) — not an OS/VM sandbox. Tool calls go through `nova.call` RPC to the host thread; a hard timeout, abort, `process.exit`, or a memory blow-up terminates the worker without touching the harness.
+Guest code runs as an `AsyncFunction` in a worker thread (same trust class as host `bash`), not an OS/VM sandbox. Tool calls go through `nova.call` RPC to the host thread; a hard timeout, abort, `process.exit`, or a memory blow-up terminates the worker without touching the harness.
 
 ---
 
@@ -46,11 +46,17 @@ async () => {
 }
 ```
 
-Globals: `nova` / `tools`, `parallel`, `pipeline`, `console`, plus shorthand `read` (path or path array), `write`, `edit`, `patch`, `surface`, `snap`, `bash`, and `exec`.
+Globals: `nova`, `parallel`, `pipeline`, `console`, plus shorthand `read` (path or path array), `write`, `edit`, `patch`, `evidence`, `surface`, `snap`, `bash`, and `exec`.
 
-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.
+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.
 
-Unified Pi/OMP card — one aligned row per call (status · tool · duration · target) with bounded mutation diffs:
+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.
+
+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.
+
+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.
+
+Unified Pi/OMP card: one aligned row per call (status · tool · duration · target) with bounded mutation diffs.
 
 ```text
 ╭─── nova: 4 calls · 6.9s ─────────────────────────────────────╮
@@ -74,9 +80,11 @@ Multi-line commands show their first line plus a hidden-line count. Press Enter
 | `nova.search(query, limit?)` | Thin catalog hits |
 | `nova.describe(name)` | Parameter summary on demand |
 | `nova.call(name, args)` | Host tool or native adapter |
-| `nova.callMany([{name,args}])` | Auto parallel wave — iterable array with `.mode` / `.results` |
+| `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?)` | Most relevant source path, line, signature, confidence, and context |
+| `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.has(name)` | Whether a catalog or native tool is callable (sync) |
 | `parallel(thunks)` / `pipeline(items, …stages)` | Raw `Promise.all` helpers |
 | `nova.speculate(fn)` | Counterfactual branch (rollback / commit) |
@@ -98,16 +106,17 @@ Optional `~/.pi/agent/supernova.json` or `~/.omp/agent/supernova.json`
   "maxCallResultChars": 65536,
   "maxReturnChars": 32000,
   "maxHeapMb": 512,
+  "seenWindow": 40,
   "maxSearchResults": 12,
   "spillDir": null
 }
 ```
 
-`maxHeapMb` caps the guest worker heap (V8 `resourceLimits` on Node) and arms a process-RSS watchdog that terminates a runaway program on both Node and Bun.
+`seenWindow` is how many programs back the seen-ledger remembers (set 0 to disable collapsing). `maxHeapMb` caps the guest worker heap (V8 `resourceLimits` on Node) and arms a process-RSS watchdog that terminates a runaway program on both Node and Bun.
 
-Defaults also set `excludeTools` (includes `supernova` and DCE helpers). An empty `"excludeTools": []` **replaces** those defaults — omit the key unless you mean that.
+Defaults also set `excludeTools` (includes `supernova` and DCE helpers). An empty `"excludeTools": []` **replaces** those defaults, so omit the key unless you mean that.
 
-Slash: `/supernova` — catalog size + captured executors.
+Slash command `/supernova`: catalog size, captured executors, and session token stats.
 
 ---
 
@@ -134,17 +143,32 @@ Pair with DCE last if you use it: `omp install npm:pi-deferred-context-engine`.
 |---------|-----|
 | `unknown tool "…"` | Follow the `Did you mean` hint, or `nova.search("")`; for host tools install supernova **first**; restart; `/supernova` |
 | `Rendered line exceeds terminal width` | ≥0.0.1 and restart so `render.js` reloads |
-| `callMany` / not iterable | ≥0.0.1 — return is an array with `.mode` / `.results` |
+| `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`) |
 
 ---
 
 ## Limitations
 
-- Guest JS is **unsandboxed**. Adapter path jails are not a boundary against `import("node:fs")`. The worker only contains hangs, exits, and memory — not intent.
+- Guest JS is **unsandboxed**. Adapter path jails are not a boundary against `import("node:fs")`. The worker only contains hangs, exits, and memory, not intent.
 - Guest error messages carry `(line:col)` on Node; Bun's engine does not expose guest-relative positions.
 - `bash` / mutating tools flush speculative writes (transaction barrier); error rollback cannot undo that.
-- Pre-1.0 package — APIs and TUI may still evolve between minor releases.
+- The workspace index refreshes its file list every 10s or on any supernova mutation; a file created by an external process can take up to 10s to appear in `glob`/`snap` (`read` is never stale).
+- Pre-1.0 package: APIs and TUI may still evolve between minor releases.
+
+## Research and prior art
+
+Supernova's retrieval and result shaping implement published methods. Where a paper's mechanism needs a model call it stays out of the tool; only the deterministic parts are implemented, and each is cited at the code that implements it.
+
+| 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 |
+| **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` |
+
+fff is © Dmitriy Kovalenko and contributors, released under the MIT License; this package is also MIT. If you install fff's own Pi extension (`@ff-labs/pi-fff`) alongside supernova, its `ffgrep`/`fffind` tools are captured and callable through `nova.call` like any other host tool.
 
 ## License
 

package/bottleneck.js

@@ -4,7 +4,7 @@ import { randomUUID } from "node:crypto";
 import { isString, isObject } from "./decode.js";
 import { truncateChars, formatValue } from "./format.js";
 
-export function serializeBounded(value, maxChars, label = "value") {
+function serializeBounded(value, maxChars, label = "value") {
   let serialized;
   try {
     serialized = isString(value) ? value : JSON.stringify(value);

package/catalog.js

@@ -1,7 +1,7 @@
 
 import { isString, isObject } from "./decode.js";
 
-export const NATIVE_TOOL_DEFINITIONS = [
+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.",
@@ -10,6 +10,7 @@ export const NATIVE_TOOL_DEFINITIONS = [
       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" },
     } },
   },
   {
@@ -17,9 +18,9 @@ export const NATIVE_TOOL_DEFINITIONS = [
     parameters: { type: "object", properties: { path: { type: "string" }, content: { type: "string" } }, required: ["path", "content"] },
   },
   {
-    name: "edit", description: "Apply unique text replacements, or a unified diff, to a workspace file.",
+    name: "edit", description: "Apply unique text replacements to a workspace file; returns the post-edit lines, a structural check, and references to changed declarations.",
     parameters: { type: "object", properties: {
-      path: { type: "string" }, oldText: { type: "string" }, newText: { type: "string" }, edits: { type: "array" }, patch: { type: "string" },
+      path: { type: "string" }, oldText: { type: "string" }, newText: { type: "string" }, edits: { type: "array", description: "[{oldText, newText}] for several replacements in one call" },
     }, required: ["path"] },
   },
   {
@@ -33,6 +34,15 @@ export const NATIVE_TOOL_DEFINITIONS = [
       path: { type: "string", description: "Optional workspace search root; explicitly targeting a hidden directory includes its hidden files, but Git metadata is always excluded" },
     }, required: ["query"] },
   },
+  {
+    name: "evidence", description: "Top-K source spans (with path and line provenance) that answer a concept question; read these instead of whole files.",
+    parameters: { type: "object", properties: {
+      query: { type: "string", description: "Concept, symbol, or question" },
+      path: { type: "string", description: "Optional search root" },
+      k: { type: "number", description: "Main spans to return (default 5)" },
+      maxChars: { type: "number", description: "Total text budget (default 6000)" },
+    }, required: ["query"] },
+  },
   {
     name: "surface", description: "Extract a structural outline from a workspace source file.",
     parameters: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
@@ -42,13 +52,13 @@ export const NATIVE_TOOL_DEFINITIONS = [
     parameters: { type: "object", properties: { command: { type: "string" }, cwd: { type: "string" }, timeoutMs: { type: "number" } }, required: ["command"] },
   },
   {
-    name: "grep", description: "Search workspace file contents by pattern.",
+    name: "grep", description: "Search file contents. Smart-case regex; definition lines first (marked *); fuzzy fallback when nothing matches literally.",
     parameters: { type: "object", properties: {
-      pattern: { type: "string" }, path: { type: "string" }, glob: { type: "string" }, caseSensitive: { type: "boolean" },
+      pattern: { type: "string" }, path: { type: "string" }, glob: { type: "string" }, caseSensitive: { type: "boolean" }, limit: { type: "number" },
     }, required: ["pattern"] },
   },
   {
-    name: "glob", description: "List workspace files matching a glob pattern.",
+    name: "glob", description: "Find files: a glob pattern, or free text for typo-tolerant, frecency-ranked path search.",
     parameters: { type: "object", properties: { pattern: { type: "string" } }, required: ["pattern"] },
   },
   {
@@ -142,12 +152,7 @@ export function searchCatalog(catalog, query, limit = 12) {
   for (const row of catalog) {
     const score = scoreRow(row, tokens);
     if (score <= 0 && tokens.length > 0) continue;
-    scored.push({
-      name: row.name,
-      description: row.description.slice(0, 160),
-      score,
-      callable: true,
-    });
+    scored.push({ name: row.name, description: row.description.slice(0, 160), score });
   }
   scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
   return scored.slice(0, Math.max(1, limit)).map(({ score: _s, ...hit }) => hit);
@@ -155,9 +160,10 @@ export function searchCatalog(catalog, query, limit = 12) {
 
 function fieldSummary(key, schema, required) {
   const s = schema && isObject(schema) ? schema : {};
+  // Only signal-bearing keys: `required:false` and empty descriptions cost tokens and say nothing.
   return {
     type: s.type || (Array.isArray(s.anyOf) ? "union" : "unknown"),
-    required: required.has(key),
+    required: required.has(key) || undefined,
     description: isString(s.description) ? s.description.slice(0, 120) : undefined,
   };
 }
@@ -195,7 +201,7 @@ function editDistance(a, b) {
 }
 
 /** Closest tool names for a mistyped name: substring hits first, then a length-scaled edit distance. */
-export function suggestNames(name, candidates, limit = 3) {
+function suggestNames(name, candidates, limit = 3) {
   const needle = String(name || "").toLowerCase();
   if (!needle) return [];
   const maxDistance = Math.max(1, Math.floor(needle.length / 3));
@@ -233,7 +239,6 @@ export function describeTool(catalog, name) {
       description: row.description,
       parameters: schemaSummary(row.parameters),
       sourcePath: row.sourcePath,
-      signature: `await nova.call(${JSON.stringify(row.name)}, args)`,
     };
   }
   return row._described;

package/check.js

@@ -0,0 +1,166 @@
+// Quick structural check after an edit, not a parser. Catches the edit failures models make
+// most: an unbalanced brace/bracket/paren or an unterminated string, with the line it happened
+// on, so a broken edit is known now instead of after a test run. JSON is checked exactly.
+
+const OPEN = { "{": "}", "[": "]", "(": ")" };
+const CLOSE = new Set(["}", "]", ")"]);
+const REGEX_PRECEDERS = new Set(["(", ",", "=", ":", "[", "!", "&", "|", "?", "{", "}", ";", "+", "-", "*", "%", "<", ">", "~", "^", "return", "typeof", "case", "do", "else", "in", "of"]);
+
+function skipString(text, i, quote) {
+  for (let j = i + 1; j < text.length; j++) {
+    if (text[j] === "\\") {
+      j++;
+      continue;
+    }
+    if (text[j] === quote) return j + 1;
+    if (quote !== "`" && text[j] === "\n") return -1;
+  }
+  return -1;
+}
+
+function skipTemplate(text, i, stack) {
+  for (let j = i + 1; j < text.length; j++) {
+    if (text[j] === "\\") {
+      j++;
+      continue;
+    }
+    if (text[j] === "`") return j + 1;
+    if (text[j] === "$" && text[j + 1] === "{") {
+      const end = balancedEnd(text, j + 1, stack);
+      if (end < 0) return -1;
+      j = end - 1; // loop increment lands on the char after "}"
+    }
+  }
+  return -1;
+}
+
+/** Index just past the "}" matching the "{" at i, scanning nested code; −1 when unbalanced. */
+function balancedEnd(text, i, stack) {
+  const depth = stack.length;
+  const r = scan(text, i, stack, depth);
+  return r.error ? -1 : r.end;
+}
+
+function skipComment(text, i) {
+  if (text[i + 1] === "/") {
+    const nl = text.indexOf("\n", i);
+    return nl < 0 ? text.length : nl;
+  }
+  const end = text.indexOf("*/", i + 2);
+  return end < 0 ? text.length : end + 2;
+}
+
+function skipRegex(text, i) {
+  let inClass = false;
+  for (let j = i + 1; j < text.length; j++) {
+    const c = text[j];
+    if (c === "\\") {
+      j++;
+      continue;
+    }
+    if (c === "\n") return -1;
+    if (c === "[") inClass = true;
+    else if (c === "]") inClass = false;
+    else if (c === "/" && !inClass) return j + 1;
+  }
+  return -1;
+}
+
+function lineOf(text, i) {
+  let n = 1;
+  for (let j = 0; j < i && j < text.length; j++) if (text[j] === "\n") n++;
+  return n;
+}
+
+const IDENT_START = /[A-Za-z_$]/;
+const IDENT_PART = /[\w$]/;
+
+function readIdentifier(text, i) {
+  let j = i + 1;
+  while (j < text.length && IDENT_PART.test(text[j])) j++;
+  return j;
+}
+
+function consumeQuoted(text, i, stack) {
+  const c = text[i];
+  if (c === "`") {
+    const end = skipTemplate(text, i, stack);
+    return end < 0 ? { error: "unterminated template literal", at: i } : { end, prev: "value" };
+  }
+  const end = skipString(text, i, c);
+  return end < 0 ? { error: "unterminated string", at: i } : { end, prev: "value" };
+}
+
+/** Try to consume a comment, string, template, or regex at i. Returns { end, prev } | { error, at } | null. */
+function consumeLiteral(text, i, stack, prev) {
+  const c = text[i];
+  if (c === '"' || c === "'" || c === "`") return consumeQuoted(text, i, stack);
+  if (c !== "/") return null;
+  if (text[i + 1] === "/" || text[i + 1] === "*") return { end: skipComment(text, i), prev };
+  if (prev !== "" && !REGEX_PRECEDERS.has(prev)) return null;
+  const end = skipRegex(text, i);
+  return end > 0 ? { end, prev: "value" } : null;
+}
+
+/** Push/pop a bracket; returns an error, a stop, or null to continue. */
+function bracket(c, i, stack, stopDepth) {
+  if (OPEN[c]) {
+    stack.push({ c, at: i });
+    return null;
+  }
+  if (!CLOSE.has(c)) return null;
+  const top = stack.pop();
+  if (!top || OPEN[top.c] !== c) return { error: "unexpected '" + c + "'", at: i };
+  if (stopDepth !== undefined && stack.length <= stopDepth) return { end: i + 1 };
+  return null;
+}
+
+/** Skips comments, strings, templates and regex literals; `prev` is the last code token, which decides regex-vs-division. */
+function scan(text, start, stack, stopDepth) {
+  let i = start;
+  let prev = "";
+  while (i < text.length) {
+    const c = text[i];
+    const literal = consumeLiteral(text, i, stack, prev);
+    if (literal) {
+      if (literal.error) return literal;
+      i = literal.end;
+      prev = literal.prev;
+      continue;
+    }
+    if (IDENT_START.test(c)) {
+      const j = readIdentifier(text, i);
+      prev = text.slice(i, j);
+      i = j;
+      continue;
+    }
+    const outcome = bracket(c, i, stack, stopDepth);
+    if (outcome) return outcome;
+    if (!/\s/.test(c)) prev = c;
+    i++;
+  }
+  return { end: i };
+}
+
+const CODE_EXT = new Set([".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".mts", ".cts", ".java", ".kt", ".c", ".cc", ".cpp", ".h", ".hpp", ".cs", ".go", ".rs", ".swift", ".css", ".scss"]);
+
+/** { ok: true } | { ok: false, message }; message names the problem and line. */
+export function quickCheck(text, ext) {
+  if (ext === ".json") {
+    try {
+      JSON.parse(text);
+      return { ok: true, kind: "json" };
+    } catch (err) {
+      return { ok: false, kind: "json", message: String(err.message).replace(/^JSON\.parse: /, "") };
+    }
+  }
+  if (!CODE_EXT.has(ext)) return null;
+  const stack = [];
+  const r = scan(text, 0, stack);
+  if (r.error) return { ok: false, kind: "balance", message: r.error + " at line " + lineOf(text, r.at) };
+  if (stack.length) {
+    const top = stack[stack.length - 1];
+    return { ok: false, kind: "balance", message: "unclosed '" + top.c + "' opened at line " + lineOf(text, top.at) };
+  }
+  return { ok: true, kind: "balance" };
+}

package/config.default.json

@@ -5,6 +5,7 @@
   "maxCallResultChars": 65536,
   "maxReturnChars": 32000,
   "maxHeapMb": 512,
+  "seenWindow": 40,
   "maxLogLines": 100,
   "maxLogLineChars": 4096,
   "maxSearchResults": 12,

package/config.js

@@ -18,6 +18,7 @@ const POSITIVE_INTEGER_KEYS = new Set([
   "maxLogLineChars",
   "maxSearchResults",
   "maxHeapMb",
+  "seenWindow",
 ]);
 
 const VALIDATORS = {
@@ -81,4 +82,3 @@ export function loadConfig() {
   return mergeConfig(packageDefaults(), user ?? null);
 }
 
-export { userConfigPath, KNOWN_KEYS };

package/decode.js

@@ -1,16 +1,6 @@
-
 const toStr = Object.prototype.toString;
 
 export const isString = (v) => toStr.call(v) === "[object String]";
 export const isObject = (v) => toStr.call(v) === "[object Object]";
 export const isFunction = (v) => toStr.call(v) === "[object Function]" || v instanceof Function;
 export const isNumber = (v) => toStr.call(v) === "[object Number]" && Number.isFinite(v);
-export const isRecord = (v) => v !== null && isObject(v);
-
-export function parseString(v, fallback = "") {
-  return isString(v) ? v : fallback;
-}
-
-export function parseNonEmptyString(v) {
-  return isString(v) && v.trim().length > 0 ? v.trim() : null;
-}