pi-supernova 0.5.0 → 0.6.0

package/README.md

@@ -12,6 +12,20 @@ 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.
 
+## What is new in 0.6.0
+
+- **Shared batch input:** supply top-level `data` once; each program gets an
+  independent copy unless it supplies its own replacement data.
+- **Conflict protection:** byte snapshots survive partial reads and body-cache
+  eviction; receipt generation cannot silently rebase a pending write.
+- **Read fidelity:** staged declarations remain discoverable in large/new files,
+  line windows preserve source endings, and `complete` always means the whole file.
+- **Explicit failures:** incompatible read modes, budget-limited matches, captured
+  overrides and conflicting new-file aliases no longer silently change outcomes.
+
+See the [changelog](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/CHANGELOG.md)
+and [token measurements](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/TOKEN_COSTS.md).
+
 ## Install and update
 
 Install the published package in your host:
@@ -29,9 +43,19 @@ pi install /path/to/pi-stack/packages/pi-supernova
 
 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`).
+range excludes the new minor version (`^0.5.0` excludes `0.6.0`). After 0.6.0 is
+published, pin that release with:
+
+```bash
+pi install npm:pi-supernova@0.6.0
+omp install npm:pi-supernova@0.6.0
+```
 
-Both package manifests use `index.js`. The old `src/bridge/pi-extension.ts` path
+In Pi, `pi list` shows the configured package sources. A local path uses that
+checkout directly; an npm source uses the installed npm copy. Do not assume that
+pushing a checkout or running `/reload` updates the copy executing in your host.
+
+Both host 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
@@ -54,7 +78,7 @@ settings. The runtime does not silently rewrite your tool policy.
 | `read` | `read({query,resolve:true})`; same view as `read("symbol")`: status, path, line, lines, text, complete |
 | `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 |
+| `read` | `read([path1,path2])`; up to 64 paths, ordered values; rejects if any path fails |
 | `edit` | `edit(path,oldText,newText)`, `edit({path,edits:[{oldText,newText}]})`; unique in the file |
 | `edit` | `edit(view,text)` CAS-replaces that span; `edit(view,old,new)` is unique inside it |
 | `edit` | `edit({path,patch})`; unified patch application |
@@ -75,7 +99,8 @@ Source questions locate a declaration 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.
+questions reuse lexical stemming. Source questions and focused `about` reads
+accept at most 16 keywords. Ripgrep must be available on PATH.
 
 `read(path)` stays raw text. `read("symbol")` is the same view as
 `read({query, resolve:true})` — not the file, not a path/range header:
@@ -90,7 +115,13 @@ The view contains `status`, `path`, the matching `line`, span `lines`, unchanged
 `text`, `complete`, and `nextOffset` when a budget clip continues. A declaration
 snap is that span (`complete` is false unless the span is the whole file). Uncertain
 results report `ambiguous`, `not_found` or `incomplete` with no selected path.
-Use `{path: directory, about: question}` to narrow the scope.
+Use `{path: directory, about: question}` to narrow the scope. Scoping a query
+does not relabel a selected span as a complete file. Newly staged files and large
+staged source participate in discovery before commit. Raw offset/limit windows
+preserve LF/CRLF endings and the final newline; focused views add line labels.
+A matching window too large for the output budget is reported as budget-limited,
+not as an absent match. Do not combine incompatible modes such as `outline:true`
+and `evidence:true`.
 
 Ordinary reads stay self-contained. Outlines and graph evidence remain explicit
 options, not mandatory stages of source resolution. Ordinary calls also get:
@@ -122,6 +153,14 @@ For intentionally writing literal marker documentation only, opt in with
 `write({path,content,allowReadArtifacts:true})`. This is a data-loss guard, not
 full dataflow tracking or a security sandbox.
 
+Read/modify/write conflict checks retain a signature of the actual disk bytes,
+including for partial and large-file reads. A fresh explicit text read refreshes
+that observation; internal receipt reads and body-cache eviction do not. Commits
+reject changed content and conflicting symlink aliases, including new file paths.
+These checks do not provide a cross-process lock or make shell/import mutations
+transactional. Extensionless filenames also support `complete:true`, for example
+`read({path:"LICENSE",complete:true})`.
+
 Explicit read arrays reject missing/failed paths. For typed partial outcomes use
 `Promise.allSettled(paths.map(path => read(path)))`. Successful arrays remain arrays.
 For literal file content or scripts, prefer the optional tool-level `data` parameter:
@@ -136,8 +175,9 @@ For literal file content or scripts, prefer the optional tool-level `data` param
 }
 ```
 
-`data` crosses the worker boundary as JSON, never as JavaScript source. Its
-JSON-encoded length is capped separately at `maxCodeChars`; split larger inputs.
+`data` crosses the worker boundary as JSON, never as JavaScript source. For a
+single program its JSON-encoded length is capped separately at `maxCodeChars`;
+batches use the combined admission budget described below. Split larger inputs.
 The binding exists only when supplied, so older programs declaring their own `data`
 remain valid. Syntax errors run no commands and give quoting guidance. For inline
 source, use `String.raw` (escaping backtick delimiters) or JSON-quoted strings.
@@ -179,7 +219,7 @@ no truncated prefix is executed. Review untrusted source before running it.
 Use ordinary `edit` to revise saved programs. This is explicit source reuse, not
 conversation compression: prior calls and read results remain intact. Creation
 costs an additional call unless combined with other work, so prefer inline code
-for short one-off operations. See [token measurements](docs/TOKEN_COSTS.md).
+for short one-off operations. See [token measurements](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/TOKEN_COSTS.md).
 
 ### Batch already-known continuations
 
@@ -194,12 +234,32 @@ for short one-off operations. See [token measurements](docs/TOKEN_COSTS.md).
 }
 ~~~
 
-Use programs instead of top-level code/file/data. Supply 1--32 entries, each with
-code OR file and optional data; the JSON-encoded array must fit maxCodeChars.
+Use programs instead of top-level code/file. Supply 1--32 entries, each with
+code OR file and optional data. Top-level data supplies an optional default for
+each entry; explicit entry data replaces it entirely, including null, false, 0
+and empty strings. Every guest receives its own copy, not a shared mutable heap.
+The JSON-encoded array (or `{programs,data}` when defaults are supplied) must fit
+maxCodeChars. Common input counts once; result representations and output limits are unchanged.
 Entries run sequentially in fresh guests and commit separately. A successful
 entry can create the file executed by a later entry. No implicit retries,
 reordering, shared heap or nested batches are introduced.
 
+For independent audits that use the same inputs, send them once:
+
+```json
+{
+  "data": {"paths": ["src/a.js", "src/b.js"]},
+  "programs": [
+    {"code": "return await read(data.paths);"},
+    {"code": "return await Promise.all(data.paths.map(path => read({path, outline:true})));"}
+  ]
+}
+```
+
+This avoids repeating literal arguments, without a compression codec or result elision.
+Mutating `data` in one guest cannot affect the next. An entry with `data:null`
+receives null, not the shared object; there is no implicit object merge.
+
 The batch stops on the first failed entry, cancellation/deadline, or exhausted
 output/log/image budget. Earlier successful commits remain; only the active
 program's uncommitted writes roll back. Admission errors throw before any program.
@@ -266,6 +326,8 @@ plain .json reads also fail with a projection hint. Explicit offset/limit or
 resolve:true still allow raw inspection, but line windows are not JSON documents.
 Do not combine json with complete, line windows, or source views. External read
 overrides reject JSON projection rather than silently ignoring the option.
+Other read options, even false-valued flags, do not bypass a captured external
+read executor; its policy, transforms and failures remain authoritative.
 
 For large Markdown/log path audits, use read(path,{about:"document path"}) or
 explicit offset/limit, not complete:true. Larger JSON needs a streaming parser via
@@ -424,7 +486,7 @@ not hard real-time guarantees.
 It excludes model latency, provider tokens and prewarm time; it is not a universal
 comparison against every CodeMode implementation.
 
-See [the changelog](docs/CHANGELOG.md) for changes and compatibility notes.
+See [the changelog](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/CHANGELOG.md) for changes and compatibility notes.
 
 ## Research and prior art
 

package/docs/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.6.0] - 2026-09-15
+
+### Added
+
+- Shared literal input for `programs`: top-level `data` defaults each entry, while
+  explicit entry data replaces it entirely, including falsy values. Every fresh
+  guest receives its own copy. The combined JSON admission budget counts common
+  input once; deadlines, host-call limits, separate commits and stop reports stay
+  unchanged. No implicit object merge, shared heap or inferred plan is introduced.
+
+### Hardened execution and reads
+
+- Keep byte-accurate conflict snapshots independent of receipt/body caches.
+  Explicit rereads refresh observations; internal diff reads and cache eviction do
+  not rebase pending writes. Partial and focused reads retain full-file signatures,
+  including above 16 MiB, and invalid UTF-8 no longer causes a false conflict.
+- Canonicalize new-file destinations before checking conflicting symlink aliases,
+  while preserving the existing logical paths in workspace-change notifications.
+- Preserve read/mutation/checkpoint ordering across coalesced read waves. Tighten
+  input validation, cancellation handling and bounded output without reusing an
+  executed worker or reducing individual independent-read budgets.
+- Keep captured read overrides authoritative when options are supplied. Align
+  native/guest evidence results and path-array aliases; reject incompatible modes
+  and enforce the same focused-query keyword cap for disk and staged content.
+- Discover newly staged declarations in file-scoped queries and large overlays.
+  Preserve line endings, EOF characters and post-edit line coordinates. Distinguish
+  absent matches from matches that exceed the view budget. `complete` consistently
+  means the whole file; extensionless paths support `complete:true`.
+
+### Documentation and verification
+
+- Document shared-input examples, commit/rollback and override boundaries, and the
+  need for a full host restart after JavaScript updates. `/reload` can retain old
+  native ESM modules; pushing GitHub does not update an npm installation.
+- Restore the historical token fixture and hash-lock it. Version the single
+  terminating-newline expectation separately, without changing historical traffic,
+  programs, decision boundaries or acceptance thresholds.
+- Add failure-first regressions for reviewed and newly found defects. Correct
+  oversized fixtures, non-finite timeout inputs and misleading test descriptions.
+- Measure shared-input audits with identical complete outputs: 16,309 to 5,499
+  tokens (o200k_base) and 14,649 to 5,197 (cl100k_base), including replay, result
+  framing and added standing guidance. These are workload-specific non-compressive
+  savings, not provider-billing or live-model quality claims. See
+  [token measurements](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/TOKEN_COSTS.md)
+  for the unchanged historical gates, accounting and reproduction commands.
+
 ## [0.5.0] - 2026-09-12
 
 - Report overlapping `supernova` calls from every participant in the wave, including the first-started call that finishes last. Start-order or finish-order counters missed that side; a peak concurrent count resets when the wave drains. Sequential calls, `programs` batches, and failed programs still do not leak a split hint. The regression forces the slower first program so the last-finisher case cannot flake under load.

package/docs/TOKEN_COSTS.md

@@ -1,11 +1,12 @@
 # Token usage and benchmarks
 
-Supernova reduces repeated tool traffic through explicit program reuse and batching.
+Supernova reduces repeated tool traffic through explicit program reuse, batching
+and shared batch input defaults.
 It can also reduce escaping in nested multiline results with lossless text framing.
 These mechanisms do not summarize results, rewrite conversation history, or change
 reasoning settings. Savings depend on the workload.
 
-See the [API guide](../README.md) for program-file and batch usage.
+See the [API guide](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/README.md) for program-file and batch usage.
 
 ## Reproduce
 
@@ -69,12 +70,12 @@ text contributes to totals through later history, not as a second charge.
 
 ## Measured results
 
-Observed on macOS with Node v26.7.0.
+Observed for 0.6.0 on 2026-09-15, on an Apple M5 Max running macOS and Node v26.7.0.
 
 | Tokenizer | Non-batched baseline | Batched baseline (d444eb7) | Current | Further reduction | Total reduction |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| o200k_base | 28,130 | 18,535 | 9,537 | **48.55%** | **66.10%** |
-| cl100k_base | 27,841 | 18,310 | 9,420 | **48.55%** | **66.17%** |
+| o200k_base | 28,130 | 18,535 | 9,843 | **46.90%** | **65.01%** |
+| cl100k_base | 27,841 | 18,310 | 9,726 | **46.88%** | **65.07%** |
 
 The gate requires at least 40% reduction on **each tokenizer for the complete
 workload**, not for every scenario individually. Token counts and reductions are
@@ -83,15 +84,12 @@ returned by the runtime. A second gate requires another 19% against the measured
 batched baseline from commit d444eb7. Its six-call argument hash is pinned as well
 as the original workload: removing a decision boundary cannot satisfy this gate.
 
-### What changed after the batched baseline
+### Definition and result accounting
 
-The serialized definition falls from 1,068 to 577 tokens with o200k_base and from
-1,057 to 572 with cl100k_base. Duplicate object-form restatements, parameter
-prose already covered by the command list, and discoverable operational asides
-were removed; command signatures and safety rules (`complete:true`, JSON 16 MiB /
-no jq, array-read rejection, transactions, `programs` batch, edit oldText as an
-exact substring, `edit(view,text)`) remain in the standing reference. No source
-text or independent result is removed or compressed.
+The current serialized definition is 631 tokens with o200k_base and 626 with
+cl100k_base, versus 908 and 901 in the frozen non-batched baseline. It retains
+command signatures, complete-read and JSON limits, array-read failure rules,
+transaction boundaries, batch defaults and edit/view guidance on every request.
 
 For the fixed six-call schedule, the accounting can also be written as:
 
@@ -99,17 +97,9 @@ For the fixed six-call schedule, the accounting can also be written as:
 Total = (N+1)*D + sum((N-i+2)*A_i + (N-i+1)*R_i, i = 1..N)
 ~~~
 
-Seven definition appearances still save 7*491 = 3,437 tokens with o200k_base versus
-d444eb7's 1,068-token definition. Snap-to-span then changed the first repair
-observation from a whole-file view to the `MAX_JSON_BYTES` declaration
-(`lines:[3,3]`, `complete:false`). That smaller result is replayed through later
-requests; no source or independent result is compressed or dropped. Frozen
-programs, arguments and decision boundaries are unchanged. Combined with
-batching, current o200k traffic is 9,558 vs d444eb7's 18,535 (48.43%).
-
-The current definition is now *below* the non-batched baseline (577 vs 908
-o200k_base). Batching still adds result framing. One-off calls should not be
-assumed to benefit from the batch API.
+The definition is counted seven times, including the final handoff. Batch result
+framing and every attempted program's text are counted too. One-off calls should
+not be assumed to benefit from batching.
 
 The report also includes separate source-framing and argument-reuse comparisons.
 Those component measurements are not total-session savings, and the reported
@@ -117,28 +107,70 @@ argument-only break-even excludes other request costs. Text framing is selected
 by character length, not a runtime tokenizer; it need not reduce tokens for every
 input or encoding.
 
+## Shared batch input: a separate 0.6.0 measurement
+
+Eight independent audit programs use the same list of 48 source paths. The before
+arm repeats the literal `data` in every entry; the after arm supplies it once at
+the top level. Both execute the same programs and return the same complete source
+strings and typed results. The before request fits the existing admission cap;
+this is not a comparison against a hypothetical request that could never run.
+
+| Tokenizer | Repeated-input traffic | Shared-input traffic | Reduction | Arguments before / after | Unchanged result tokens |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| o200k_base | 16,309 | 5,499 | **66.28%** | 6,461 / 1,043 | 2,151 |
+| cl100k_base | 14,649 | 5,197 | **64.52%** | 5,684 / 945 | 2,055 |
+
+Each arm has one tool invocation followed by the final answer request:
+
+~~~text
+Total = 2*D + 2*A + R
+~~~
+
+Arguments are charged when generated and when replayed; the complete result is
+charged on handoff. The new standing guidance adds 13 definition tokens per
+request (618 to 631 / 613 to 626), and that cost is included in the after totals.
+There is no source compression, result elision, hidden output or lost decision
+boundary. Programs receive fresh data copies, not a shared mutable heap.
+
+The gate requires at least 70% less argument traffic and 60% less replay-inclusive
+traffic in each encoding, plus equality of the complete normalized output. This
+workload deliberately exercises repeated input; it is not an average task-cost
+estimate. The original 13-program/six-call benchmark remains separate and intact.
+
 ## Benchmark integrity
 
-The [baseline fixture](../tests/efficiency/token-baseline.json) contains the source
+The [baseline fixture](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/tests/efficiency/token-baseline.json) contains the source
 inputs, definition, workload hash, arguments and complete outputs. The
-[runner](../tests/efficiency/workflow.mjs) executes the registered tool with real
+[runner](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/tests/efficiency/workflow.mjs) executes the registered tool with real
 workers and filesystem operations. It checks that:
 
 - The workload hash matches the frozen baseline, and the six-call argument hash
   matches the prior batched execution.
-- Every original argument, complete logical result and expected failure matches.
+- Every original argument and expected failure matches; complete logical results
+  match the explicit current newline contract described below.
 - Batched output contains every original result, with no unaccounted outer text.
 - No result is truncated, and final repaired source and JSON contents match.
 
 Only run IDs, elapsed times and temporary workspace prefixes in write receipts
 are normalized. Batch framing lengths are adjusted to match that normalized text.
 The workload, batch schedule, recorded comparison totals and acceptance thresholds
-are fixed test inputs, not production execution rules. The baseline is not regenerated by the benchmark.
+are fixed test inputs, not production execution rules. The baseline is not regenerated
+by the benchmark and is checked against its SHA-256 before execution.
+
+Contract v2 preserves the terminating newline of one selected source line. The
+runner derives that single expected-output correction from the frozen input, not
+from candidate output. The historical fixture and its traffic counts stay
+untouched; programs, arguments, failures and decision boundaries are unchanged.
+The shared-input comparison separately requires equal complete result text in
+both arms, after only run-metadata normalization.
+
+The README and these docs ship in the npm tarball. Benchmarks and test fixtures
+remain in the GitHub checkout, so their links above use GitHub URLs.
 
 Recorded baseline SHA-256:
 
 ~~~text
-79a819eca82c8a5ff381e96b7669d8a5bf04fabbc8c10cf02f3a7c8817171b62
+96964f990f481ac05afaefdd02001bd15f61835a8381349a61e38c06209d7508
 ~~~
 
 ## Limitations
@@ -150,6 +182,8 @@ Recorded baseline SHA-256:
   reasoning settings does not establish unchanged end-to-end task quality.
 - Batching is appropriate only for already-chosen continuations. Actions requiring
   a new model decision must remain separate calls.
+- The report also has an experimental citation-elision arm. It is disabled by
+  default and is not the source of the non-compressive savings reported here.
 - Existing read, output, log, image and execution limits still apply. The
   benchmark does not obtain savings by lowering them or hiding truncation.
 

package/index.js

@@ -67,7 +67,10 @@ export function progressEmitter(onUpdate) {
     const wait = PROGRESS_FRAME_MS - (performance.now() - lastSent);
 
     if (wait <= 0) send();
-    else timer = setTimeout(send, wait);
+    else {
+      timer = setTimeout(send, wait);
+      timer.unref?.();
+    }
   };
 
   emit.flush = () => {
@@ -228,7 +231,7 @@ export function registerCodeMode(pi) {
     execute: async function execute(_id, params, signal, onUpdate, ctx, budget) {
       if (params?.programs !== undefined) return runProgramBatch(_id,params,signal,onUpdate,ctx,config,execute);
       cancelWarmTimer();
-      const runCwd = ctx?.cwd || cwd;
+      const runCwd = isString(ctx?.cwd) && ctx.cwd ? ctx.cwd : cwd;
       const runController = new AbortController();
       const abortRun = () => runController.abort(signal?.reason);
 
@@ -258,7 +261,7 @@ export function registerCodeMode(pi) {
           cwd: runCwd,
           data: params?.data,
           nova: makeNovaApi(runBridge, abortRun),
-          config: { ...config, maxLogLines: Math.max(0,config.maxLogLines-(budget?.logLines ?? 0)), timeoutMs: Number.isInteger(params?.timeoutMs) ? params.timeoutMs : config.timeoutMs },
+          config: { ...config, maxLogLines: Math.max(0,config.maxLogLines-(budget?.logLines ?? 0)), timeoutMs: params?.timeoutMs === undefined ? config.timeoutMs : Number(params.timeoutMs) },
           signal: runController.signal,
           onTimeout: abortRun,
         });
@@ -347,7 +350,7 @@ export function registerCodeMode(pi) {
   pi.on("session_start", (_event, ctx) => {
     stopped = false;
 
-    if (ctx && isString(ctx.cwd) && ctx.cwd) cwd = ctx.cwd;
+    cwd = ctx && isString(ctx.cwd) && ctx.cwd ? ctx.cwd : process.cwd();
     // A new session is a new model context: nothing has been seen yet.
     bridge.bindCallContext(ctx);
     bridge.ledger.reset();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-supernova",
-  "version": "0.5.0",
-  "description": "One CodeMode invocation for Pi and OMP, with four guest commands, automatic read batching and source context.",
+  "version": "0.6.0",
+  "description": "CodeMode for Pi and OMP: read, edit, write and bash, with transactional files, source views and shared-input program batches.",
   "type": "module",
   "author": "AdityaVG13",
   "license": "MIT",

package/src/bridge/catalog.js

@@ -4,22 +4,24 @@ import { isString, isObject } from "../shared/decode.js";
 const NATIVE_TOOL_DEFINITIONS = [
   {
     name: "read",
-    description: "Read files, images or directories. JSON selectors project full documents within output budgets. Source questions locate and open source directly; resolve returns structured source/status without guessing.",
+    description: "Read files, images or directories (directory reads return entries). JSON selectors project full documents within output budgets. Source questions locate and open source directly; resolve returns structured source/status without guessing.",
     parameters: { type: "object", properties: {
-      path: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }], description: "Workspace-relative file or directory, source question, or array of paths" },
+      path: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" }, maxItems: 64 }], description: "Workspace-relative file or directory, source question, or up to 64 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: expand file bodies, or locate and open source inside a directory" },
-      query: { type: "string", description: "Source question; optional path scopes the search directory" },
+      about: { type: "string", description: "Question or symbol (at most 16 keywords): expand file bodies, or locate/open source inside a directory" },
+      query: { type: "string", description: "Source question (at most 16 keywords); optional path scopes the search directory" },
+      outline: { type: "boolean", description: "Return a compact structural outline for the target file" },
+      evidence: { type: "boolean", description: "Rank source spans answering the target/path question" },
       resolve: { type: "boolean", description: "Return structured source/status for a direct resolve-to-edit handoff" },
       complete: { type: "boolean", description: "Fail unless the entire requested file fits without clipping" },
-      json: { anyOf: [{ type: "boolean" }, { type: "string" }, { type: "array", items: { type: "string" } }], description: "Parse the complete JSON input (up to 16 MiB), then select .field, .items[0:3], or quoted keys. A selector array returns an array of values; true selects the root. Oversized selections fail, never clip." },
+      json: { anyOf: [{ type: "boolean" }, { type: "string" }, { type: "array", items: { type: "string" }, minItems: 1, maxItems: 64 }], description: "Parse complete JSON input up to 16 MiB, then select .field, .items[0:3], quoted keys, true, or 1-64 selectors. Oversized selections fail, never clip." },
     } },
   },
   {
     name: "write", description: "Write UTF-8 content to a workspace file.",
-    parameters: { type: "object", properties: { path: { type: "string" }, content: { type: "string" }, allowReadArtifacts: { type: "boolean", description: "Explicit opt-in for intentionally writing literal truncation-marker text" } }, required: ["path", "content"] },
+    parameters: { type: "object", properties: { path: { type: "string" }, content: { type: "string" }, append: { type: "boolean", description: "Append to an existing file instead of replacing it" }, allowReadArtifacts: { type: "boolean", description: "Explicit opt-in for intentionally writing literal truncation-marker text" } }, required: ["path", "content"] },
   },
   {
     name: "edit", description: "Apply unique text replacements to a workspace file; returns the post-edit lines, a structural check, and references to changed declarations.",
@@ -53,7 +55,7 @@ const NATIVE_TOOL_DEFINITIONS = [
   },
   {
     name: "bash", description: "Run a shell command inside the workspace and capture bounded output.",
-    parameters: { type: "object", properties: { command: { type: "string" }, cwd: { type: "string" }, timeoutMs: { type: "number" } }, required: ["command"] },
+    parameters: { type: "object", properties: { command: { type: "string" }, args: { type: "array", items: { type: "string" }, description: "Literal argv without shell interpretation (POSIX)" }, cwd: { type: "string" }, timeoutMs: { type: "number" } }, required: ["command"] },
   },
   {
     name: "grep", description: "Search file contents. Smart-case regex; definition lines first (marked *); fuzzy fallback when nothing matches literally.",
@@ -178,7 +180,9 @@ export function searchCatalog(catalog, query, limit = 12) {
 
   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);
+  const capped = Math.min(64, Math.max(1, Math.floor(Number(limit)) || 1));
+
+  return scored.slice(0, capped).map(({ score: _s, ...hit }) => hit);
 }
 
 /** Optimal string alignment distance: insert/delete/substitute/adjacent-transpose cost 1. */
@@ -202,7 +206,7 @@ function editDistance(a, b) {
 
 /** Closest tool names for a mistyped name: substring hits first, then a length-scaled edit distance. */
 function suggestNames(name, candidates, limit = 3) {
-  const needle = String(name || "").toLowerCase();
+  const needle = String(name || "").toLowerCase().slice(0, 128);
 
   if (!needle) return [];
   const maxDistance = Math.max(1, Math.floor(needle.length / 3));
@@ -228,7 +232,7 @@ function suggestNames(name, candidates, limit = 3) {
 }
 
 export function unknownToolMessage(name, candidates) {
-  const close = suggestNames(name, candidates);
+  const close = suggestNames(name, candidates.filter(isString));
   const hint = close.length ? ` Did you mean ${close.map((c) => JSON.stringify(c)).join(", ")}?` : "";
 
   return `unknown tool "${name}".${hint} Check the command name and configured tool exclusions.`;