pi-supernova 0.2.0 → 0.3.1

package/README.md

@@ -1,229 +1,229 @@
 # pi-supernova
 
-[![npm](https://img.shields.io/npm/v/pi-supernova.svg)](https://www.npmjs.com/package/pi-supernova)
-[![license](https://img.shields.io/npm/l/pi-supernova.svg)](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/LICENSE)
-[![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)
+**One nova / `supernova({code})` invocation. Four commands inside CodeMode.**
 
-**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
-omp install npm:pi-supernova
+```javascript
+const source = await read("validateRefreshToken");
+return source;
 ```
 
-Restart the host after install. OMP uses the current session’s enabled tool registry, independent of extension load order.
-
-Pi 0.85.0 supplies tool schemas but has no cross-extension execution API. Supernova uses native adapters and executors registered through its API instance.
-
-An unrelated Pi extension’s tools are not callable through Supernova. OMP 18.1.10 supports those calls through its session registry.
-
-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.
+The model submits JavaScript, not four separately advertised native tools.
+Ordinary JavaScript control flow remains available; the guest command bindings
+are only `read`, `edit`, `write`, and `bash`. Supernova supplies retrieval,
+transactional file operations, batching, bounded results and the grouped nova UI.
 
----
+## Install and update
 
-## Why
+Install the published package in your host:
 
-| | Stock multi-tool prompt | **pi-supernova** |
-|--|-------------------------|------------------|
-| 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 |
-
-Guest code runs as an `AsyncFunction` in a new worker for each program. It has the same trust level as host `bash`.
-
-The host parses the bounded source with Acorn before execution. Tool calls use RPC. Deadlines and cancellation cover worker startup, tool discovery, and execution.
-
-A completed worker cannot supply callbacks or globals to another program. Concurrent programs have separate transactions, traces, cancellation signals, and call budgets.
-
----
-
-## Quick example
-
-```js
-const hit = JSON.parse(await read("src", {about: "validateJwtRefreshToken"}));
-if (hit.status !== "found") return hit;
-return await read(hit.path, {about: "expired tokens"});
+```bash
+pi install npm:pi-supernova
+omp install npm:pi-supernova
 ```
 
-No catalog lookup or separate search command is needed.
-
-| 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.
-
-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.
-
-The confidence value is a ranking heuristic, not a measured probability. Duplicate declarations do not produce a confident winner.
-
-Search uses ripgrep without loading every file into the text cache. It can locate declarations beyond the 512 KiB whole-file cache limit.
-
-Each candidate contains up to seven source lines. Signatures and individual lines have a 240-character limit, with explicit truncation markers.
+Local checkout installs are for development, not distribution:
 
-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.
-
-Unified Pi/OMP card: one aligned row per call (status · tool · duration · target) with bounded mutation diffs.
-
-```text
-╭─── nova: 4 calls · 6.9s ─────────────────────────────────────╮
-│ ✓ bash      6.2s  python3 - <<'EOF' …+3 lines                 │
-│ × bash     120ms  exit 3  pytest -q                           │
-│ ✓ read       3ms  packages/pi-supernova/host-bridge.js        │
-│ ✓ edit       4ms  +1/-1 src/a.ts                              │
-│    -143 │ - const oldValue = before;                          │
-│    +143 │ + const newValue = after;                           │
-╰───────────────────────────────────────────────────────────────╯
+```bash
+pi install /path/to/pi-stack/packages/pi-supernova
 ```
 
-Multi-line commands show their first line and a hidden-line count. Expand the card to show the complete bounded return value and logs.
-
-Expanded text wraps at the terminal width without a preview-line limit. Operation lists and mutation diffs keep their separate 24-row budgets.
-
----
-
-## Optional APIs
-
-| API | Role |
-|-----|------|
-| `nova.search(query, limit?)` | Thin catalog hits |
-| `nova.describe(name)` | Complete JSON input schema on demand; explicit failure when no usable schema is available |
-| `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 |
-| `nova.surface(path)` | Structural outline for a source file |
-| `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) |
-
-`nova.call` returns an explicit `{ok, value}` envelope. Convenience helpers throw when a host tool reports failure.
-
-`callMany` runs known read-only tools concurrently. Unknown tools and mutating actions run in order, including LSP rename operations.
-
-`nova.describe` preserves required fields, unions, enums, nested objects, and numeric constraints. OMP ArkType and Zod schemas convert to JSON Schema.
-
-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.
-
----
-
-## Configuration
-
-Optional `~/.pi/agent/supernova.json` or `~/.omp/agent/supernova.json`  
-(or `PI_SUPERNOVA_CONFIG` / `PI_CONFIG_DIR` / `OMP_CONFIG_DIR`):
-
-```json
-{
-  "timeoutMs": 60000,
-  "maxCodeChars": 48000,
-  "maxBridgeCalls": 256,
-  "maxCallResultChars": 65536,
-  "maxReturnChars": 32000,
-  "maxHeapMb": 512,
-  "seenWindow": 40,
-  "maxSearchResults": 12,
-  "spillDir": null
-}
+Git pushes do not update npm installations. Publish the new npm version first;
+then reinstall it in the host. Reinstall explicitly when an existing version
+range excludes the new minor version (for example, `^0.2.0` excludes `0.3.0`).
+
+Both package manifests use `index.js`. The old `src/bridge/pi-extension.ts` path
+remains a compatibility entrypoint but no longer imports Pi tool factories.
+After updating JavaScript sources, fully exit Pi and resume in a new process.
+Pi 0.85.1 can retain native ESM modules across `/reload`, even after its extension
+factory cache is cleared; `/reload` alone is not sufficient in that case.
+OMP uses the same shared engine; restart it after updating the link as well.
+
+For deferred-context-engine, pin `supernova` in `alwaysActive` and `neverDefer`.
+Remove the four native names from those pins and restore their previous blocks
+if you want the wrapper to be the only file/shell surface. Preserve unrelated
+settings. The runtime does not silently rewrite your tool policy.
+
+## Four guest commands
+
+| Function | Examples and behavior |
+| --- | --- |
+| `read` | `read(path, offset?, limit?)`, `read({path,offset,limit})`; one-based line windows |
+| `read` | `read(directory)`, `read("symbol or question")`, `read(path,{about:question})`; questions locate and open source directly |
+| `read` | `read({query,resolve:true})`; structured source and status for a resolve-to-edit handoff |
+| `read` | `read({query,evidence:true})`; ranked evidence with provenance; optional `path` scopes discovery |
+| `read` | `read({path,outline:true})`; structural declarations |
+| `read` | `read([path1,path2])`; up to 64 paths, ordered values with labelled individual failures |
+| `edit` | `edit(path,oldText,newText)`, `edit({path,edits:[{oldText,newText}]})`; related edits validated against one original file |
+| `edit` | `edit({path,patch})`; unified patch application |
+| `edit` | `edit(async () => {...})`; filesystem-only checkpoint, described below |
+| `write` | `write(path,text)`, `write({path,content})`; atomic replacement |
+| `bash` | `bash(command,{cwd,timeoutMs})`, `bash({command,timeoutMs})`; bounded output, nonzero exits throw |
+| `bash` | `bash({command,args:[...]})`; literal executable argv, without shell expansion of argument strings |
+
+`bash` also accepts `timeout` in seconds for familiar object arguments. `timeoutMs`
+is milliseconds and takes precedence. The owned POSIX adapter launches executable
+argv directly; use the string form for shell builtins, functions or startup hooks.
+Windows and delegated/older executors retain quoted-shell compatibility. Argument
+payloads are not repeated in owned direct-execution errors;
+stdout/stderr, exit status and source context remain. Session environment variables are taken
+from the current execution context, not inherited from a different parent session.
+
+Source questions resolve and open the selected file in one command. An exact
+declaration match uses one bounded direct ripgrep search, without a prerequisite
+file listing, persistent index, embeddings or summarization. A transient filename
+listing is a fallback for unmatched content or unresolved bare filenames. Natural-language
+questions reuse lexical stemming. Ripgrep must be available on PATH.
+
+Successful question reads return raw source with a path/range header, not the old
+JSON location preview. Use the structured form when code needs the path:
+
+```javascript
+const source = await read({query: "validateRefreshToken", resolve: true});
+if (source.status !== "found") return source;
+return await edit(source.path, "token.length > 3", "token.length > 5");
 ```
 
-`maxCallResultChars` bounds text per call. A batch shares one text budget across all items; it does not repeat a joined copy.
-
-Envelope fields and JSON encoding add overhead. Details have a separate 2,000-character JSON budget. Truncation flags cover returns, raw objects, and logs.
-
-An optional `spillDir` retains complete truncated text. Inline spill footers and truncation markers fit within the configured text limit.
-
-`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, so omit the key unless you mean that.
-
-Slash command `/supernova`: callable catalog size, external tools, native adapters, and session token stats.
-
----
-
-## Install variants
+The structured result contains `status`, `path`, the matching `line`, delivered
+`lines`, unchanged `text`, `complete`, and `nextOffset` when more source follows.
+Files that fit the output budget are returned in full. Oversized files open near
+the matching line and give a continuation; they are not summarized. Uncertain
+results report `ambiguous`, `not_found` or `incomplete` with no selected path.
+Use `{path: directory, about: question, resolve: true}` to narrow the scope.
+
+Ordinary reads stay self-contained. Outlines and graph evidence remain explicit
+options, not mandatory stages of source resolution. Ordinary calls also get:
+
+- Bounded fuzzy filename hints when a bare source name has no literal match. Existing
+  frecency/directory ranking orders hints; fuzzy matches never select a path. This
+  reuses filename discovery, examines at most 1024 paths and reports incomplete hints.
+- Post-edit source windows and structural warnings for both replacement and patch
+  edits. Body-only edits reuse local declaration spans for lexical reference hints.
+  Up to three names share one bounded, cancellable search; staged callers override disk.
+  These hints do not build an index, are not semantic caller resolution, and report
+  unavailable/truncated searches rather than silently claiming completeness.
+- Structural warnings on writes without echoing successful file contents.
+- Fresh workspace source around up to four failure locations, including shell
+  timeouts and paths relative to the command cwd. Implicit snippets exclude external
+  symlink targets and files over 1 MiB.
+
+Distant edit regions have separate windows and continuation pointers for omitted
+lines. Structural warnings and source windows are not substitutes for tests.
+
+## Execution and automatic batching
+
+Compatible independently started reads coalesce at the worker/host boundary.
+No additional batching command is required. Individual promises preserve their
+values, errors and per-read budgets. File reads have bounded parallelism; writes,
+edits, shell calls and checkpoint transitions form ordering barriers.
+
+This does **not** reorder sequential `await`s or predict future model decisions.
+An explicit path-array read uses an aggregate text budget; automatic coalescing
+retains each independent read's budget instead of silently shrinking its result.
+
+Every program runs in a fresh worker. One pristine worker is prepared for the next
+invocation, then disposed on session shutdown. Executed workers are never reused,
+so guest globals cannot leak into a later program. Worker preparation still costs
+CPU and memory; it is moved off the next invocation's critical path, not eliminated.
+
+File changes are staged until program success. A throw before an external-mutation
+barrier rolls them back. Shell execution flushes preceding changes; external shell
+side effects cannot be rolled back. Stale commits fail explicitly rather than
+silently overwriting successful concurrent changes. This is not a cross-process
+filesystem lock.
+
+`edit(async () => {...})` creates a nested filesystem checkpoint. It returns
+`{ok:true,committed:true,value}` on success or `{ok:false,committed:false,error}` on
+failure. Shell commands, overlapping/nested checkpoints, and concurrent commands
+outside the active callback are rejected. Await the checkpoint before proceeding.
+
+## Context, caching and failure fidelity
+
+- Plain reads are not replaced with earlier-context references. A local cache hit
+  is not proof the model still retains an earlier result after compaction.
+- Oversized text reads provide an exact next-line offset. A single line too large
+  for the budget fails explicitly instead of pretending it was read completely.
+- Returned images remain image content blocks, including in arrays/objects. Images
+  not returned by the program stay out of model output. Returned images are limited
+  to 16 attachments / 20 MiB; resize or return fewer when necessary.
+- Dense multiline string arrays can render as verbatim source blocks instead of
+  escaped string literals. Each block gives its array index and exact UTF-16 length;
+  strings and result types are unchanged. This is output framing, not source
+  compression. It is chosen only when shorter in characters than escaped output;
+  it does not guarantee lower billed tokens for every tokenizer or input.
+- Intermediate values stay inside CodeMode unless returned or logged. Final text,
+  errors and logs are bounded with explicit truncation. Details support rendering;
+  they are not a second model-facing transcript.
+- Source indexing/caching remains internal. Reads after mutations invalidate stale
+  state. There is no claim of provider-cache or total-task token savings.
+
+Default limits are in `src/config/config.default.json`. Configuration loads from
+`~/.pi/agent/supernova.json`, the configured host directory, or `PI_SUPERNOVA_CONFIG`.
+Text limits are character budgets, not tokenizer counts. `/supernova` reports
+programs and output characters without labelling characters as tokens.
+
+## Security and host boundary
+
+CodeMode executes trusted JavaScript in a terminable worker, **not a security
+sandbox**. The four adapters constrain writes/edits to the workspace and allow
+explicit external reads. JavaScript imports and shell commands still have process
+privileges. Do not run untrusted programs as though these adapters isolate them.
+
+Pi preflights the outer `supernova` call. Internal primitives do not emit ordinary
+native `tool_call` events, so third-party guards that only recognize top-level
+`edit` or `bash` need CodeMode-aware handling. Configured exclusions and supported
+host-session execution safeguards remain enforced. Actual-host smoke checks are
+not a claim that every third-party permission extension has been validated.
+
+## Development and evidence
+
+Implementation is grouped under `src/`; all replacement tests are under `tests/`.
+The original 12 red acceptance tests were left unchanged. Additional strict tests
+cover batching fidelity, image/context retention, checkpoints, mutation ordering,
+external symlinks, deadlines, worker isolation and execution-context environment.
+The former deleted suite has not been silently reinstated.
 
 ```bash
-# Path / dogfood
-pi install /path/to/pi-stack/packages/pi-supernova
-omp install /path/to/pi-stack/packages/pi-supernova
+npm test --prefix packages/pi-supernova
+npm run lint:supernova
+npm run measure --prefix packages/pi-supernova
 
-# Monorepo clone
-git clone https://github.com/AdityaVG13/pi-stack.git
-pi install ./pi-stack/packages/pi-supernova
-omp install ./pi-stack/packages/pi-supernova
+PI_SUPERNOVA_PI_ROOT=/path/to/pi-coding-agent \
+PI_SUPERNOVA_OMP=/path/to/omp \
+npm run test:hosts --prefix packages/pi-supernova
 ```
 
-Pair with DCE last if you use it: `omp install npm:pi-deferred-context-engine`.
-
----
-
-## Troubleshooting
+The explicit host runner requires macOS network sandboxing and fails, rather than
+skips, when prerequisites are absent. Verified locally against Pi 0.85.1 and OMP
+18.1.11: CodeMode execution, four primitives, automatic read coalescing, checkpoints,
+images and failed execution. Pi's actual loader/runner and TUI are exercised; OMP
+runs in a disposable process through its actual session registry, with networking
+denied. The Pi runner supplies a minimal tool registry, not a full provider session.
 
-| Symptom | Fix |
-|---------|-----|
-| `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`) |
+The local measurement compares identical eight-file programs with coalescing off,
+coalescing on, and a pristine-ready worker. It reports latency percentiles,
+observed maxima, raw samples and bridge calls. Set `SUPERNOVA_MEASURE_SAMPLES`
+(20 to 10000; default 200) for longer runs. Maxima describe the measured sample,
+not hard real-time guarantees.
+It excludes model latency, provider tokens and prewarm time; it is not a universal
+comparison against every CodeMode implementation.
 
----
-
-## 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 error messages carry `(line:col)` on Node; Bun's engine does not expose guest-relative positions.
-
-## Transactions and file freshness
-
-- `bash` and mutating host tools commit pending writes before execution. Later rollback cannot undo those changes or external effects.
-- Native commits stage replacements and backups before installation. A commit failure restores earlier replacements; a recovery failure reports retained backup paths.
-- A nested `nova.speculate` branch cannot call external mutators. Await each branch before returning.
-- Native reads use current disk content unless a staged write replaces it. Evidence search includes new staged files.
-- Workspace file-list updates use filesystem watchers. Without a working watcher, external new files can take 10 seconds to appear in indexed searches.
-
-This is a pre-1.0 package. APIs and the terminal display can change between minor releases.
+See [the changelog](docs/CHANGELOG.md) for changes and compatibility notes.
 
 ## 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.
+These references describe internal algorithms, not additional guest commands.
+
+The existing implementation references are retained below. Mechanisms requiring
+an additional model call are not silently invoked by the tools.
 
 | 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 (`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 |
+| **Zero-Mem: Zero-Token Memory Operations for LLM Agents**, Xiao, Zhu, Zhang, Chen, Hong, Zhuang, Zhang, Chen, Ouyang, Ren, Huang (arXiv:2607.29377) | Evidence selection: 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. | `src/context/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 (`read(query)` → `read(path, {about})` → `read(path, offset, limit)`); the citation-lock idea that a model should only cite what it actually opened. | `src/context/evidence.js`, `src/context/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.
+| **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. Bounded fuzzy filename hints now run automatically for unmatched bare source names, using in-memory frecency and directory distance without extra filesystem probes. The full internal search implementation also retains typo-tolerant fuzzy path matching with boundary/consecutive/case bonuses; 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. Git/mtime boosts and full indexed grep are not mandatory stages of ordinary reads. 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. | `src/context/fuzzy.js`, `src/context/repo-index.js`, `src/bridge/host-bridge.js` |
 
 ## License
 
-MIT · [AdityaVG13/pi-stack](https://github.com/AdityaVG13/pi-stack/tree/main/packages/pi-supernova)
+MIT. fff is © Dmitriy Kovalenko and contributors, also MIT.

package/{CHANGELOG.md → docs/CHANGELOG.md}

@@ -1,6 +1,59 @@
 # Changelog
 
-## [Unreleased]
+## [0.3.1] - 2026-09-06
+
+### Fixed
+
+- Preserve post-edit coordinates for patch deletions, including zero-length new ranges. After an earlier hunk inserts lines, the edit result now opens the actual deletion region rather than an unrelated earlier source window. File mutation semantics are unchanged.
+
+### Tests
+
+- Add a focused shifted-deletion regression and an opt-in stress runner that can target an isolated npm installation. Cover concurrent programs, 129-read batches, contended writes, cancellation after confirmed staging, immutable progress frames, source fidelity and cold lookup across 5,000 files.
+
+## [0.3.0] - 2026-09-05
+
+### Source operations
+
+- Source questions now locate and open the selected file in one read, using bounded direct ripgrep search without a prerequisite index. Successful reads return raw source rather than a JSON location preview; `read({query,resolve:true})` supplies structured source/status for resolve-to-edit programs. Filename discovery remains a transient fallback; ambiguous and incomplete searches never select a file.
+- Reuse lexical stemming for natural-language source questions. Preserve whole-file text when it fits, and exact line ranges/continuations for oversized files, including escaped structured output.
+- Return separate post-edit windows for distant changes; correct shifted multi-edit coordinates, staged caller references, focused-read freshness, outline header numbers and clipped evidence provenance. Admit lexical evidence hits before filling the candidate cap with unrelated paths.
+- Preserve original read expectations across write-diff reads. Revalidate mutation paths at commit and invalidate path checks after shell execution. Preserve diagnostics when hosts return text-only failure envelopes.
+- Keep outlines and graph evidence available through explicit read options, not mandatory stages of question reads. No context deduplication or source compression is enabled.
+
+### Automatic command integration
+
+- Route patch edits through the same post-edit source/check/reference summary as replacements. Infer lexical enclosing declaration hints for body-only changes from the edited file, not a repository build.
+- Search changed names together in one bounded, cancellable ripgrep call, overlay staged callers, and disclose partial/unavailable hints. Cold lookup avoids per-file JavaScript indexing; already-warm indexed scans can still be faster.
+- Reuse fuzzy/frecency/directory ranking automatically for unmatched bare source names, without extra search processes or arbitrary selection. Cap fuzzy work and disclose incomplete hints.
+- Report structural warnings on ordinary writes without repeating their payload. Attach fresh workspace source to shell failures/timeouts, respect command cwd and absolute locations, and exclude external symlink targets.
+
+### Performance
+
+- Render dense multiline string-array returns as unchanged, length-framed source when this avoids escaping overhead. Preserve values, sparse/mixed-array behavior and explicit truncation. No model-side join or source compression is required.
+- Negotiate direct executable argv for the owned POSIX shell adapter, avoiding shell startup and repeated argument payloads in failures/timeouts. Keep quoted-shell compatibility for older/delegated executors; string commands retain shell semantics.
+- On POSIX timeout/cancellation, skip the escalation delay only after the owned process group is proven absent. Surviving descendants still receive the existing escalation; Windows behavior is unchanged.
+- Bound and memoize terminal width measurements, with an oracle-checked single-column chrome fast path and full Unicode fallback. Avoid rebuilding already-clean terminal text.
+- Deliver completed results before preparing the next pristine worker; cancel scheduled preparation on shutdown. Worker isolation remains unchanged.
+- Overlap independent replacement/backup staging while settling both before cleanup. Avoid redundant cleanup probes without relaxing conflict detection, rollback or file-mode preservation.
+- Report configurable engine sample counts, raw latency samples, p99 and observed maxima. These are local measurements, not universal sub-millisecond or provider-latency guarantees.
+
+### Changed
+
+- Expose one `supernova({code})` tool on Pi and OMP. Only `read`, `edit`, `write`, and `bash` are guest commands; legacy guest aliases are removed.
+- Coalesce independently started reads while preserving per-call budgets, ordered values and structured failures. Preserve mutation/checkpoint barriers and prepare one pristine worker for the next invocation.
+- Fold outlines, evidence selection, multi-edits, patches and filesystem checkpoints into the four commands. Remove unrelated schema conversion from program startup.
+- Preserve returned image blocks, self-contained repeat reads and exact line continuations. Bound error output and signal failed executions by throwing. Shell environment reflects the current execution context.
+- Move implementation into `src/` and replace the old `test/` suite with `tests/`. The original 12 failure-first acceptance tests pass unchanged; additional strict regressions, explicit actual-host checks and local engine measurements are included.
+
+- Cache parsed text diffs with bounded retention, avoiding repeated normalization on repaint while preserving counts, previews and changed content.
+- Fully restart Pi/OMP after updating JavaScript sources; Pi 0.85.1 retains native ESM dependencies across `/reload`. Keep `supernova` pinned in deferred-tool setups, not the four guest commands.
+
+### Fixed
+
+- Partial batch reads retain successful files and label failures; explicit external reads work while writes remain workspace-scoped.
+- Concurrent edits no longer silently lose successful changes. Stale commits and conflicting symlink aliases fail explicitly.
+- Internal worker startup accepts stdin/eval host flags; command timeout errors retain bounded diagnostics.
+- Internal CodeMode cards bound hidden-diff processing and coalesce progress updates without back-to-back frames.
 
 ## [0.2.0] - 2026-09-04