pi-supernova 0.4.0 → 0.5.0

package/README.md

@@ -50,12 +50,13 @@ settings. The runtime does not silently rewrite your tool policy.
 | `read` | `read(path, offset?, limit?)`, `read({path,offset,limit})`; one-based line windows |
 | `read` | `return await read("plot.png")`; displays images directly, without a browser |
 | `read` | `read({path,json:".verdict"})`; parse full JSON before bounded field selection |
-| `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(directory)`, `read("symbol or question")`, `read(path,{about:question})`; a path is raw text, a symbol is a view |
+| `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 |
-| `edit` | `edit(path,oldText,newText)`, `edit({path,edits:[{oldText,newText}]})`; related edits validated against one original file |
+| `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 |
 | `edit` | `edit(async () => {...})`; filesystem-only checkpoint, described below |
 | `write` | `write(path,text)`, `write({path,content})`; atomic replacement |
@@ -70,27 +71,26 @@ 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
+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.
 
-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:
+`read(path)` stays raw text. `read("symbol")` is the same view as
+`read({query, resolve:true})` — not the file, not a path/range header:
 
 ```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");
+const v = await read("validateRefreshToken");
+if (v.status !== "found") return v;
+await edit(v, v.text.replace("token.length > 3", "token.length > 5"));
 ```
 
-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
+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, resolve: true}` to narrow the scope.
+Use `{path: directory, about: question}` 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:

package/docs/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [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.
+
+- Shrink the standing tool definition without compressing source or results. Duplicate object-form restatements, schema prose already covered by the command list, and discoverable operational asides are gone; signatures and safety rules stay in the always-sent reference. Frozen six-call traffic is 14,970 / 14,787 tokens (o200k / cl100k): 19.23% / 19.24% below d444eb7. The current-pass gate now requires 19% vs d444eb7.
+
+- An unmatched or non-unique edit keeps the file and returns a numbered window of the actual source (16-line cap, same coordinates as a successful edit) so the next program can copy oldText without a blind re-read. Successful read/write/edit results are unchanged.
+
+- A program that writes or edits and returns nothing still delivers those mutation receipts (numbered post-edit lines, `wrote` paths). Reads without a return stay a no-return hint and do not dump file contents. Explicit `return await edit(...)` is not duplicated.
+
+- `edit(view, text)` replaces a `resolve:true` window by line span with CAS against the viewed bytes. Duplicate substrings no longer block a ranged edit; a stale view fails and rolls back. The silent receipt names that span (`edited path:2-2`), not a ±2 context window.
+
+- A `resolve:true` snap of a declaration is that declaration's span, not the whole file just because the file fits the read budget. `edit(view, text)` then replaces the function, not the file. `edit(view, old, new)` is unique inside that span. A budget-clipped view (`nextOffset`) is not editable.
+
+- Gravity: `read("symbol")` is the same view as `read({query, resolve:true})`. `read(path)` stays raw text. `looksLikePath` lives in `shared/decode.js` so guest and host share the identifier-vs-path rule.
+
+- Nested declaration spans: a parent still includes its body (brace-matched from the opening line), one-line class methods resolve, and two exact same-name declarations in one file are ambiguous instead of snapping the first. Ambiguous candidates (same-file or cross-file) are that hit's span (signature, lines, text, context), not a clone of the first match's window. Span pick/slice live in `src/context/spans.js` for locate + host resolve.
+
+- Do not subscribe a `context` observer when `seenWindow` is 0. A no-op listener still ran on every provider context event; opt-in retention windows still register.
+
+- Encode the module BIND spine as a regression: acyclic imports, no upward edges, context and runtime stay siblings. host-bridge remains the fused INVOKE kernel.
+
+- Drop guest/host RPC for `search` and `describe`, and stop returning unused `exec`/`patch`/`nova` bindings from the worker API. The guest still injects only read, write, edit, bash.
+
 ## [0.4.0] - 2026-09-10
 
 - Disable citation elision by default (`seenWindow: 0`), including direct bridge/ledger defaults. A failure-first integration regression preserves complete results across hidden, reordered and removed context. Positive windows remain an explicit research opt-in, not a validated retention guarantee. The historical ledger measurements below describe that experimental mode only.

package/docs/TOKEN_COSTS.md

@@ -69,30 +69,29 @@ text contributes to totals through later history, not as a second charge.
 
 ## Measured results
 
-Observed on macOS with Node v26.7.0 and Linux aarch64 with Node v24.16.0; both
-produced the same token counts.
+Observed on macOS with Node v26.7.0.
 
 | Tokenizer | Non-batched baseline | Batched baseline (d444eb7) | Current | Further reduction | Total reduction |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| o200k_base | 40,129 | 18,535 | 17,581 | **5.15%** | **56.19%** |
-| cl100k_base | 39,697 | 18,310 | 17,363 | **5.17%** | **56.26%** |
+| o200k_base | 28,130 | 18,535 | 9,537 | **48.55%** | **66.10%** |
+| cl100k_base | 27,841 | 18,310 | 9,420 | **48.55%** | **66.17%** |
 
 The gate requires at least 40% reduction on **each tokenizer for the complete
 workload**, not for every scenario individually. Token counts and reductions are
 computed from the recorded baseline and fresh execution results, not constants
-returned by the runtime. A second gate requires another 5% against the measured
+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
 
-The serialized definition falls from 1,068 to 947 tokens with o200k_base and from
-1,057 to 937 with cl100k_base. Repeated guidance now has one model-visible home;
-the command reference, safety rules and schema constraints remain available.
-Batch framing declares UTF-16 length units once instead of on every entry and
-omits redundant aggregate mutation totals from the wrapper. Every original
-per-program result, including its mutation report, remains intact. Structured
-aggregate counters are unchanged. No source text or independent result is removed.
+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.
 
 For the fixed six-call schedule, the accounting can also be written as:
 
@@ -100,14 +99,17 @@ 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 save 7*121 = 847 tokens with o200k_base. The smaller
-batch wrappers save another 107 after history replay, for 954/18,535 = 5.15%.
-For cl100k_base the corresponding saving is 7*120 + 107 = 947 tokens. The logical
-programs, their arguments, complete results and decision boundaries are unchanged.
-
-There are still costs: the current definition exceeds the non-batched baseline
-by 39/36 tokens per request, and batching adds result framing. One-off calls should
-not be assumed to benefit from the batch API.
+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 report also includes separate source-framing and argument-reuse comparisons.
 Those component measurements are not total-session savings, and the reported

package/index.js

@@ -4,7 +4,7 @@ import { REFERENCE } from "./src/runtime/reference.js";
 import { isString, isFunction } from "./src/shared/decode.js";
 import { loadConfig } from "./src/config/config.js";
 import { createHostBridge } from "./src/bridge/host-bridge.js";
-import { truncateChars } from "./src/output/format.js";
+import { truncateChars, formatBoundedStringArray } from "./src/output/format.js";
 import { runGuestProgram, warmGuestWorker, stopWarmGuestWorker } from "./src/runtime/runtime.js";
 import { renderSupernovaCall, renderSupernovaResult } from "./src/ui/render.js";
 
@@ -99,6 +99,15 @@ function mutationText(outcome) {
   return "\nmutations: committed=" + m.committed + " rolledBack=" + m.rolledBack + " (file versions)" + external + uncertain;
 }
 
+function mutationReceipts(trace) {
+  if (!Array.isArray(trace)) return "";
+
+  return trace
+    .filter(row => row?.ok && (row.name === "write" || row.name === "edit") && isString(row.resultText) && row.resultText)
+    .map(row => row.resultText)
+    .join("\n");
+}
+
 // Corrective hint, emitted only when a turn actually split. Independent work
 // belongs in one program: a split cannot use the single prewarmed worker and pays
 // one extra spawn per sibling. Costs nothing until it fires, so it needs no room in
@@ -119,6 +128,25 @@ function successText(outcome, call) {
   return `ok #${call} ${outcome.wallMs}ms${truncated}${outcome.mutations?.committed || outcome.mutations?.rolledBack || outcome.mutations?.external ? mutationText(outcome) : ""}${splitTurnHint(outcome)}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
 }
 
+function fitOutput(outcome, call, limit, format) {
+  let text = format(outcome, call);
+
+  if (text.length <= limit) return text;
+  outcome.returnTruncated = true;
+  const wrapper = format({ ...outcome, resultText: "", logs: [] }, call);
+  const room = Math.max(256, limit - wrapper.length);
+
+  if (Array.isArray(outcome.result) && outcome.result.length && outcome.result.every(isString)) {
+    outcome.resultText = formatBoundedStringArray(outcome.result, room);
+  } else if (isString(outcome.resultText) && outcome.resultText.length > room) {
+    outcome.resultText = truncateChars(outcome.resultText, room, "output").text;
+  }
+
+  text = format(outcome, call);
+
+  return text.length <= limit ? text : truncateChars(text, limit, "output").text;
+}
+
 const TOOL_DESCRIPTION = REFERENCE;
 
 export default function piSupernova(pi) {
@@ -140,6 +168,9 @@ export function registerCodeMode(pi) {
   // Counting them lets a result say so without adding standing guidance to the
   // tool definition, which is resent on every request.
   let inFlight = 0;
+  // Peak concurrent execute() bodies in the current wave. Start-order or
+  // finish-order alone cannot see a first-started call that finishes last.
+  let overlapPeak = 0;
 
   function cancelWarmTimer() {
     if (warmTimer !== undefined) clearImmediate(warmTimer);
@@ -176,17 +207,17 @@ export function registerCodeMode(pi) {
     name: "supernova",
     label: "Supernova",
     description: TOOL_DESCRIPTION,
-    promptSnippet: "JavaScript with read, write, edit, and bash",
+    promptSnippet: "read, write, edit, bash",
     parameters: Type.Object({
       code: Type.Optional(Type.String({ maxLength: config.maxCodeChars ?? 48000 })),
       file: Type.Optional(Type.String({ minLength: 1 })),
-      data: Type.Optional(Type.Unknown({ description: "Literal JSON input available as data in the program; put Markdown, scripts or argv here instead of nesting JavaScript quoting. JSON-encoded size is limited to the code character budget." })),
-      timeoutMs: Type.Optional(Type.Integer({ minimum: 1000, description: "Hard timeout in ms." })),
+      data: Type.Optional(Type.Unknown()),
+      timeoutMs: Type.Optional(Type.Integer({ minimum: 1000 })),
       programs: Type.Optional(Type.Array(Type.Object({
         code: Type.Optional(Type.String({ maxLength: config.maxCodeChars ?? 48000 })),
         file: Type.Optional(Type.String({ minLength: 1 })),
         data: Type.Optional(Type.Unknown()),
-      }, {additionalProperties:false}), {minItems:1,maxItems:32,description:"Instead of top-level code/file/data. JSON-encoded array shares the code character cap."})),
+      }, {additionalProperties:false}), {minItems:1,maxItems:32})),
     }),
     // One self-owned result frame is shared by Pi and OMP; renderCall stays empty
     // so separate call/result slots cannot duplicate the lifecycle card.
@@ -214,8 +245,9 @@ export function registerCodeMode(pi) {
       emitProgress([]);
       const started = performance.now();
       let outcome;
-      const overlappedTurn = inFlight > 0 ? inFlight + 1 : 0;
       inFlight += 1;
+      overlapPeak = Math.max(overlapPeak, inFlight);
+      let peakSeen = overlapPeak;
 
       try {
         refreshCatalog(runBridge);
@@ -244,7 +276,9 @@ export function registerCodeMode(pi) {
         while (runBridge.getOverlayDepth()) runBridge.rollbackSpeculation();
         outcome = { ok: false, error: error instanceof Error ? error.message : String(error), logs: outcome?.logs ?? [], wallMs: Math.round(performance.now() - started) };
       } finally {
+        peakSeen = Math.max(peakSeen, overlapPeak);
         inFlight -= 1;
+        if (inFlight === 0) overlapPeak = 0;
         runBridge.setCallListener(null);
         emitProgress.flush();
         signal?.removeEventListener("abort", abortRun);
@@ -264,21 +298,20 @@ export function registerCodeMode(pi) {
       }
 
       if (budget) budget.logLines += outcome.logs?.length ?? 0;
-      // inFlight has dropped by now, so a non-zero value means a sibling is still
-      // running: report the overlap from either side so the hint does not depend on
-      // which invocation happened to start first.
-      outcome.overlappedTurn = overlappedTurn || (inFlight > 0 ? inFlight + 1 : 0);
+      outcome.overlappedTurn = peakSeen > 1 ? peakSeen : 0;
       outcome.mutations = runBridge.getMutations();
       const trace = runBridge.getTrace();
-      const format = outcome.ok ? successText : errorText;
-      let text = format(outcome, call);
 
-      if (text.length > config.maxReturnChars) {
-        outcome.returnTruncated = true;
-        text = format(outcome, call);
-      }
+      if (outcome.ok && outcome.result === undefined) {
+        const receipts = mutationReceipts(trace);
 
-      const bounded = truncateChars(text, config.maxReturnChars, "output").text;
+        if (receipts) {
+          outcome.resultText = receipts;
+          outcome.undefinedReturn = false;
+        }
+      }
+      const format = outcome.ok ? successText : errorText;
+      const bounded = fitOutput(outcome, call, config.maxReturnChars, format);
       const visible = runBridge.ledger.dedupe(bounded, call);
 
       const response = result(visible, {
@@ -300,10 +333,13 @@ export function registerCodeMode(pi) {
   });
 
   // This is a pre-conversion observation, not a final-payload retention proof.
-  // With the shipping seenWindow:0 default, observe is a no-op.
-  pi.on("context", event => {
-    try { bridge.ledger.observe(event?.messages); } catch {}
-  });
+  // Shipping seenWindow:0 must not subscribe: a no-op listener still runs on every
+  // provider context event. Opt-in windows register here.
+  if ((config.seenWindow ?? 0) > 0) {
+    pi.on("context", event => {
+      try { bridge.ledger.observe(event?.messages); } catch {}
+    });
+  }
 
   pi.on("session_shutdown", () => { stopped = true; cancelWarmTimer();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-supernova",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "One CodeMode invocation for Pi and OMP, with four guest commands, automatic read batching and source context.",
   "type": "module",
   "author": "AdityaVG13",

package/src/bridge/host-bridge.js

@@ -3,10 +3,11 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { homedir } from "node:os";
 import { packageHostResult, hostResultFailed } from "../output/bottleneck.js";
-import { isString, isNumber, isFunction, isObject } from "../shared/decode.js";
+import { isString, isNumber, isFunction, isObject, looksLikePath } from "../shared/decode.js";
 import { isMutatingTool, runParallelWave, createNativeScheduler } from "../runtime/parallel.js";
 import { unknownToolMessage } from "./catalog.js";
 import { extractStructuralSurface } from "../context/surface.js";
+import { pickSpan } from "../context/spans.js";
 import { buildEditDiff, buildMultiEditDiff, buildPatchDiff, buildWriteDiff } from "../fs/diff.js";
 import { executeSnap } from "../context/snap.js";
 import { selectEvidence } from "../context/evidence.js";
@@ -18,7 +19,7 @@ import { declaredName } from "../context/repo-index.js";
 import { CausalVfs } from "../fs/vfs.js";
 import { MAX_JSON_BYTES, jsonProjector, sessionJsonArgs, validateJsonRead } from "../fs/json-read.js";
 import { applyPatchToText } from "../fs/patch.js";
-import { resolveWorkspacePath, runCommand, clearPathCache, relativeSlash } from "../fs/workspace.js";
+import { resolveWorkspacePath, runCommand, clearPathCache, relativeSlash, assertFilesystemPath } from "../fs/workspace.js";
 import { fuzzyFind, grepIndexed, listIndexed, listWithTools, rgGrepArgs, referencesForNames } from "../context/search.js";
 
 function textResult(text, details) {
@@ -28,6 +29,20 @@ function textResult(text, details) {
   };
 }
 
+function resultDiff(response) {
+  let details = response?.details;
+
+  if (isString(details)) {
+    try {
+      details = JSON.parse(details);
+    } catch {
+      return undefined;
+    }
+  }
+
+  return isObject(details) ? details.diff : undefined;
+}
+
 /** Unwrap a single matching quote pair around the whole string (`'git status'`). */
 function unwrapIfFullyQuoted(s) {
   if (s.length < 2) return s;
@@ -52,19 +67,9 @@ function sliceLines(text, offset, limit) {
   return lines.slice(startIndex, startIndex + count).join("\n");
 }
 
-function looksLikePath(target) {
-  return (
-    isString(target) &&
-    (target.includes("/") ||
-      target.includes("\\") ||
-      target.startsWith(".") ||
-      (!/\s/.test(target) && path.extname(target).length > 0))
-  );
-}
-
 function resolveReadPath(cwd, target) {
   if (!isString(target) || !target.trim()) throw new Error("read requires path");
-  const input = target.trim();
+  const input = assertFilesystemPath(target, "read");
 
   return path.resolve(cwd, input === "~" ? homedir() : input.startsWith("~/") ? path.join(homedir(), input.slice(2)) : input);
 }
@@ -87,6 +92,39 @@ async function probeExistingPath(cwd, targetParam, vfs) {
   }
 }
 
+const EDIT_PREVIEW_LINES = 16;
+
+function sourceLines(content) {
+  const raw = content.split("\n");
+
+  if (raw.at(-1) === "") raw.pop();
+
+  return raw;
+}
+
+function lineNumberAt(content, index) {
+  let line = 1;
+
+  for (let i = 0; i < index; i++) if (content.charCodeAt(i) === 10) line++;
+
+  return line;
+}
+
+function formatNumberedLine(n, text) {
+  return String(n).padStart(5) + " " + text;
+}
+
+function numberedPreview(content, cap = EDIT_PREVIEW_LINES) {
+  const lines = sourceLines(content);
+
+  if (lines.length === 0) return "0 lines";
+  const shown = lines.slice(0, cap);
+  const body = shown.map((line, i) => formatNumberedLine(i + 1, line)).join("\n");
+  const suffix = lines.length > cap ? lines.length + " lines total" : lines.length + " lines";
+
+  return body + "\n" + suffix;
+}
+
 function applyReplacements(target, content, requestedEdits) {
   if (requestedEdits.length === 0) throw new Error("edit requires at least one replacement");
 
@@ -99,11 +137,16 @@ function applyReplacements(target, content, requestedEdits) {
     const index = content.indexOf(replacement.oldText);
 
     if (index < 0) {
-      throw new Error(`edit target not found in ${target}: oldText must match the file byte-for-byte (read() it first; check whitespace and quotes)`);
+      throw new Error("edit target not found in " + target + ": oldText must match the file byte-for-byte\n" + numberedPreview(content));
     }
+    const second = content.indexOf(replacement.oldText, index + 1);
 
-    if (content.indexOf(replacement.oldText, index + 1) >= 0) {
-      throw new Error(`edit target is not unique in ${target}: include more surrounding lines in oldText, or pass edits:[{oldText,newText},…]`);
+    if (second >= 0) {
+      const lines = sourceLines(content);
+      const a = lineNumberAt(content, index);
+      const b = lineNumberAt(content, second);
+
+      throw new Error("edit target is not unique in " + target + ": lines " + a + " and " + b + "; include more surrounding lines in oldText, or pass edits:[{oldText,newText},…]\n" + formatNumberedLine(a, lines[a - 1] ?? "") + "\n" + formatNumberedLine(b, lines[b - 1] ?? ""));
     }
 
     return { ...replacement, index, end: index + replacement.oldText.length };
@@ -125,6 +168,27 @@ function applyReplacements(target, content, requestedEdits) {
   return { updated, matches };
 }
 
+function applyViewReplace(target, content, start, end, oldText, newText) {
+  const current = sliceLines(content, start, end - start + 1);
+
+  if (current !== oldText) {
+    const shown = current.length ? current : content;
+
+    throw new Error("edit view is stale in " + target + ": lines " + start + "-" + end + " changed\n" + numberedPreview(shown));
+  }
+
+  const hadTrail = content.endsWith("\n");
+  const lines = content.split("\n");
+
+  if (hadTrail && lines.at(-1) === "") lines.pop();
+  const insert = newText.split("\n");
+
+  if (newText.endsWith("\n") && insert.at(-1) === "") insert.pop();
+  const updated = [...lines.slice(0, start - 1), ...insert, ...lines.slice(end)].join("\n") + (hadTrail ? "\n" : "");
+
+  return { updated, oldText, newText };
+}
+
 function formatDirectoryEntry(name, type, size = 0) {
   const sizeSuffix = size ? `, ${size} bytes` : "";
 
@@ -151,6 +215,7 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
   const reads = createNativeScheduler();
 
   async function sourceRead(query, searchDir, signal, params = {}) {
+    params = { ...params, resolve: params.resolve !== false };
     const cwd = getCwd();
 
     const includeHidden = path.relative(cwd, searchDir).split(path.sep)
@@ -160,15 +225,15 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
       pathContext: { frecency: index.frecency, currentFile: index.lastTouched },
       overlayText: p => vfs.getOverlay(p), pendingPaths: vfs.getOverlayPaths(), signal });
 
-    return openSource(result, params, signal);
+    return openSource(result, params, signal, undefined, query);
   }
 
-  async function openSource(result, params, signal, resolvedPath) {
+  async function openSource(result, params, signal, resolvedPath, query) {
     const cwd = getCwd();
 
     if (result.status !== "found") return textResult(JSON.stringify(result), { isSnap: true });
     signal?.throwIfAborted();
-    const opened = await readFile(resolvedPath ?? path.resolve(cwd, result.path), { ...params, about: undefined }, result.line, result.path);
+    const opened = await readFile(resolvedPath ?? path.resolve(cwd, result.path), { ...params, about: undefined }, result.line, result.path, query);
     const block = opened.content[0];
 
     if (block.type !== "text") throw new Error("source resolution requires a text file; read the image path directly");
@@ -318,7 +383,7 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
   }
 
   /** Plain text, a line window, or (with `about`) a relevance-folded outline of the whole file. */
-  async function readFile(targetPath, params, sourceLine, displayPath) {
+  async function readFile(targetPath, params, sourceLine, displayPath, query) {
     const cwd = getCwd();
     const rel = displayPath ?? relativeSlash(cwd, targetPath);
 
@@ -371,9 +436,22 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
 
     const explicit = isNumber(params?.offset) || isNumber(params?.limit);
     const budget = Math.max(1, Math.min(config.maxCallResultChars ?? 65536, config.maxReturnChars ?? 32000) - (params.resolve ? 1024 : 256));
-    const offset = params?.offset ?? (sourceLine && text.length > budget ? Math.max(1, sourceLine - 2) : 1);
+    let offset = params?.offset;
+    let limit = params?.limit;
+
+    if (!explicit && params.resolve) {
+      const spans = WorkspaceIndex.spansOf(WorkspaceIndex.fromText(targetPath, text));
+      const span = pickSpan(spans, { line: sourceLine, name: query });
+
+      if (span) {
+        offset = span.start;
+        limit = span.end - span.start + 1;
+      }
+    }
+
+    offset ??= sourceLine && text.length > budget ? Math.max(1, sourceLine - 2) : 1;
     const firstLine = isNumber(offset) ? Math.max(1, Math.floor(offset)) : 1;
-    const sliced = sliceLines(text, offset, params?.limit);
+    const sliced = sliceLines(text, offset, limit);
 
     if (params.complete === true && (sliced !== text || sliced.length > budget || (params.resolve && JSON.stringify(sliced).length > budget))) {
       throw new Error(`incomplete read of ${rel}: complete:true requires the entire file within the read budget; use json:".field" for JSON reports, about for text selection, edit() for replacements, or reconstruct resolve:true source windows`);
@@ -416,19 +494,23 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
    * lines with numbers, a quick structural check, and bounded lexical reference hints.
    * These do not replace tests or semantic caller resolution.
    */
-  async function editSummary(cwd, target, original, updated, diff, signal) {
+  async function editSummary(cwd, target, original, updated, diff, signal, span) {
     const rel = relativeSlash(cwd, target);
     const newLines = updated.split("\n");
     const ranges = [];
 
-    const positions = diff.lines.filter(row => row.type !== "context")
-      .map(row => Math.min(newLines.length, row.newLineNum ?? row.lineNum)).sort((a, b) => a - b);
+    if (span && Number.isInteger(span.start) && Number.isInteger(span.end) && span.start >= 1 && span.end >= span.start) {
+      ranges.push({ start: span.start, end: Math.min(newLines.length, span.end) });
+    } else {
+      const positions = diff.lines.filter(row => row.type !== "context")
+        .map(row => Math.min(newLines.length, row.newLineNum ?? row.lineNum)).sort((a, b) => a - b);
 
-    for (const line of positions) {
-      const start = Math.max(1, line - 2), end = Math.min(newLines.length, line + 2);
+      for (const line of positions) {
+        const start = Math.max(1, line - 2), end = Math.min(newLines.length, line + 2);
 
-      if (ranges.length && start <= ranges.at(-1).end + 1) ranges.at(-1).end = Math.max(ranges.at(-1).end, end);
-      else ranges.push({ start, end });
+        if (ranges.length && start <= ranges.at(-1).end + 1) ranges.at(-1).end = Math.max(ranges.at(-1).end, end);
+        else ranges.push({ start, end });
+      }
     }
 
     const blocks = [];
@@ -625,11 +707,28 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
 
       if (signal?.aborted) throw new Error("aborted");
 
+      const content = await vfs.read(target);
+
+      if (isNumber(params?.viewStart) && isNumber(params?.viewEnd) && isString(params?.viewText) && isString(params?.newText)) {
+        const windowNext = isString(params.oldText)
+          ? applyReplacements(target, params.viewText, [{ oldText: params.oldText, newText: params.newText }]).updated
+          : params.newText;
+        const { updated } = applyViewReplace(target, content, params.viewStart, params.viewEnd, params.viewText, windowNext);
+        const { speculative } = await vfs.write(target, updated);
+        index.touch(relativeSlash(cwd, target));
+        const diffFrom = isString(params.oldText) ? params.oldText : params.viewText;
+        const diffTo = isString(params.oldText) ? params.newText : windowNext;
+        const diff = buildEditDiff(target, content, diffFrom, diffTo);
+        const inserted = sourceLines(windowNext);
+        const spanEnd = params.viewStart + Math.max(inserted.length, 1) - 1;
+        const summary = await editSummary(cwd, target, content, updated, diff, signal, { start: params.viewStart, end: spanEnd });
+
+        return textResult(summary, { path: target, speculative, diff });
+      }
+
       const requestedEdits = Array.isArray(params?.edits)
         ? params.edits
         : [{ oldText: params?.oldText, newText: params?.newText }];
-
-      const content = await vfs.read(target);
       const { updated, matches } = applyReplacements(target, content, requestedEdits);
       const { speculative } = await vfs.write(target, updated);
       index.touch(relativeSlash(cwd, target));
@@ -733,7 +832,7 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
     },
     async bash(params, signal) {
       const cwd = getCwd();
-      const literal = params?._directArgv === true;
+      const literal = Array.isArray(params?.args) && process.platform !== "win32" && params.args.length === Object.keys(params.args).length && params.args.every(isString);
 
       if (literal && (!isString(params.command) || !Array.isArray(params.args) || params.args.some(arg => !isString(arg)))) throw new Error("bash argv requires a command string and an array of string args");
       const command = literal ? String(params.command) : unwrapIfFullyQuoted(String(params?.command ?? "").trim());
@@ -850,6 +949,11 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
   };
 }
 
+/**
+ * Fused INVOKE kernel. Guest RPC is the only caller; fuel is cwd + vfs + signal.
+ * BIND stays downward (see tests/contracts/layers.test.mjs). Do not split this
+ * closure into pass-through files that re-import each other.
+ */
 export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedger, budget }) {
   const index = registry?.index ?? new WorkspaceIndex((argv, opts) => runCommand(argv, opts));
   const ledger = runLedger ?? new SeenLedger({ window: config.seenWindow ?? 0 });
@@ -1018,20 +1122,6 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     return vfs.rollback();
   }
 
-  function resultDiff(response) {
-    let details = response?.details;
-
-    if (isString(details)) {
-      try {
-        details = JSON.parse(details);
-      } catch {
-        return undefined;
-      }
-    }
-
-    return isObject(details) ? details.diff : undefined;
-  }
-
   function notifyCall(record) {
     if (!callListener) return;
 
@@ -1106,8 +1196,9 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     try {
       const delegated = hostTool(name);
       const exec = delegated ? delegated.execute.bind(delegated) : hostSession ? undefined : executors.get(name);
+      const argvOwned = name === "bash" && Array.isArray(args?.args) && process.platform !== "win32" && args.args.length === Object.keys(args.args).length && args.args.every(isString);
 
-      if (exec) {
+      if (exec && !argvOwned) {
         if (name === "read" && (args?.json !== undefined || /^(agent|artifact):\/\/.*\?/i.test(String(args?.path)))) throw new Error("JSON projection requires the Supernova-owned read adapter, not an external override");
 
         if (name === "write" && args?.append === true) throw new Error("append requires the Supernova-owned write adapter, not an external override");
@@ -1158,6 +1249,11 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     const exitCode = isObject(res?.details) ? res.details.exitCode : undefined;
 
     if (Number.isInteger(exitCode) && exitCode !== 0) record.exitCode = exitCode;
+    const text = isObject(res) && Array.isArray(res.content)
+      ? res.content.filter(part => part?.type === "text" && isString(part.text)).map(part => part.text).join("\n")
+      : undefined;
+
+    if (text) record.resultText = text;
   }
 
   async function call(name, args) {

package/src/context/repo-index.js

@@ -96,6 +96,42 @@ export function globToRegExp(glob) {
   return new RegExp(glob.includes("/") ? "^" + body + "$" : "(?:^|/)" + body + "$");
 }
 
+function declarationEnd(raw, lower, start, lineCount, ext) {
+  if (ext === ".py") {
+    const indentOf = (i) => raw[i].length - raw[i].trimStart().length;
+    const base = indentOf(start - 1);
+    let end = start;
+
+    for (let i = start; i < lineCount; i++) {
+      if (lower[i] === "") { end = i + 1; continue; }
+      if (indentOf(i) <= base) break;
+      end = i + 1;
+    }
+
+    return Math.min(end, lineCount);
+  }
+
+  let depth = 0;
+
+  for (const ch of raw[start - 1] ?? "") {
+    if (ch === "{") depth++;
+    else if (ch === "}") depth--;
+  }
+
+  if (depth <= 0) return start;
+
+  for (let i = start; i < raw.length; i++) {
+    for (const ch of raw[i]) {
+      if (ch === "{") depth++;
+      else if (ch === "}") depth--;
+    }
+
+    if (depth <= 0) return i + 1;
+  }
+
+  return lineCount;
+}
+
 export class WorkspaceIndex {
   constructor(runCommand) {
     this.runCommand = runCommand;
@@ -274,18 +310,18 @@ export class WorkspaceIndex {
   }
 
   /**
-   * Declaration spans [start, end] (1-based, inclusive) in file order, trailing blank lines trimmed.
-   * A span runs to the line before the next declaration; the file's leading header is not a span.
+   * Declaration spans [start, end] (1-based, inclusive). Nested bodies stay inside the parent
+   * (brace-matched for JS-like, indent for Python). The file's leading header is not a span.
    */
   static spansOf(entry) {
     if (entry.spans) return entry.spans;
     const { items, lineCount } = WorkspaceIndex.surfaceOf(entry);
-    const { lower } = WorkspaceIndex.linesOf(entry);
+    const { lower, raw } = WorkspaceIndex.linesOf(entry);
     const spans = [];
 
     for (let i = 0; i < items.length; i++) {
       const start = items[i].line;
-      let end = Math.min(i + 1 < items.length ? items[i + 1].line - 1 : lineCount, lineCount);
+      let end = declarationEnd(raw, lower, start, lineCount, entry.ext);
 
       while (end > start && lower[end - 1] === "") end--;
       spans.push({ start, end, name: items[i].name, kind: items[i].kind, isExport: items[i].isExport === true });

package/src/context/snap.js

@@ -3,6 +3,8 @@ import { isString } from "../shared/decode.js";
 import { truncateChars } from "../output/format.js";
 import * as fs from "node:fs/promises";
 import { extractStructuralSurface } from "./surface.js";
+import { WorkspaceIndex } from "./repo-index.js";
+import { pickSpan, spanCandidate, spanWindow } from "./spans.js";
 import { rankPaths } from "./fuzzy.js";
 import { isTestPath, runCommand, relativeSlash } from "../fs/workspace.js";
 
@@ -86,7 +88,7 @@ function makeCandidate(filePath, dir, query, tokens, flags) {
   return { path: filePath, pathScore: scorePathTopology(relative, tokens, flags), exactPath,
     pathCoverage: tokens.filter(token => lower.includes(token)).length,
     matched: new Set(), exactDefinition: false, definitionCoverage: 0, lineCoverage: 0,
-    line: 1, signature: "", context: new Map(), recent: [], anchorScore: -1 };
+    line: 1, signature: "", context: new Map(), recent: [], anchorScore: -1, exactLines: new Set() };
 }
 
 function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
@@ -115,6 +117,8 @@ function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
 
     const score = (exact ? 10000 : 0) + definitionCoverage * 40 + matches.length;
 
+    if (exact) candidate.exactLines.add(lineNumber);
+
     if (score > candidate.anchorScore) {
       candidate.anchorScore = score;
       candidate.line = lineNumber;
@@ -220,6 +224,31 @@ function location(candidate, root) {
     context: [...context].sort((a, b) => a[0] - b[0]).map(([line, text]) => (line === candidate.line ? "►" : " ") + line + " " + text) };
 }
 
+async function spanCandidates(filePath, lines, root, overlayText) {
+  const staged = overlayText(filePath);
+  const text = staged !== undefined ? staged : await fs.readFile(filePath, "utf8");
+  const spans = WorkspaceIndex.spansOf(WorkspaceIndex.fromText(filePath, text));
+  const rel = path.relative(root, filePath);
+
+  return lines.map(line => {
+    const span = pickSpan(spans, { line }) ?? { start: line, end: line };
+
+    return spanCandidate(rel, line, spanWindow(text, span.start, span.end));
+  });
+}
+
+async function rankedSpanCandidates(ranked, root, overlayText) {
+  const out = [];
+
+  for (const candidate of ranked) {
+    const lines = candidate.exactLines?.size ? [...candidate.exactLines].sort((a, b) => a - b) : [candidate.line];
+    out.push(...await spanCandidates(candidate.path, lines, root, overlayText));
+    if (out.length >= MAX_ALTERNATIVES) break;
+  }
+
+  return out.slice(0, MAX_ALTERNATIVES);
+}
+
 export async function executeSnap({ query, searchDir, root, includeHidden = false, run = runCommand, overlayText = () => undefined, pendingPaths = [], pathContext = {}, signal }) {
   const flags = tokenizeQuery(query);
   const tokens = [...new Set(flags.tokens.map(stem))];
@@ -306,7 +335,14 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
   const coverage = Math.max(best.matched.size, best.pathCoverage) / tokens.length;
   const uniqueExact = best.exactDefinition && !second?.exactDefinition || best.exactPath && !second?.exactPath && !second?.exactDefinition;
 
-  if (!uniqueExact && (coverage < 0.6 || margin < 0.15 || best.definitionCoverage / tokens.length < 0.5)) return { ...empty, status: "ambiguous", candidates };
+  if (!uniqueExact && (coverage < 0.6 || margin < 0.15 || best.definitionCoverage / tokens.length < 0.5)) {
+    return { ...empty, status: "ambiguous", candidates: await rankedSpanCandidates(ranked, relativeRoot, overlayText) };
+  }
+
+  if (best.exactLines.size > 1) {
+    return { ...empty, status: "ambiguous", candidates: await rankedSpanCandidates([best], relativeRoot, overlayText) };
+  }
+
   const confidence = uniqueExact ? 0.95 : Math.min(0.85, 0.5 + coverage * 0.2 + margin * 0.15);
 
   return { ...candidates[0], status: "found", confidence: Number(confidence.toFixed(2)) };

package/src/context/spans.js

@@ -0,0 +1,39 @@
+import { truncateChars } from "../output/format.js";
+
+export function pickSpan(spans, { line, name } = {}) {
+  const needle = typeof name === "string" && /^[A-Za-z_$][\w$]*$/.test(name.trim()) ? name.trim().toLowerCase() : "";
+  const named = needle ? spans.filter(item => item.name.toLowerCase() === needle) : [];
+
+  if (named.length === 1) return named[0];
+  if (!line) return;
+
+  return spans.find(item => item.start === line)
+    ?? spans.filter(item => item.start <= line && line <= item.end).sort((a, b) => (a.end - a.start) - (b.end - b.start))[0];
+}
+
+export function spanWindow(text, start, end) {
+  const raw = text.split("\n");
+
+  return {
+    start,
+    end,
+    text: raw.slice(start - 1, end).join("\n"),
+    signature: truncateChars((raw[start - 1] ?? "").trim().replace(/\{.*$/, "").trim(), 240, "signature").text,
+    context: Array.from({ length: Math.max(0, end - start + 1) }, (_, i) => {
+      const n = start + i;
+
+      return { line: n, text: raw[n - 1] ?? "" };
+    }),
+  };
+}
+
+export function spanCandidate(relPath, line, window) {
+  return {
+    path: relPath,
+    line,
+    lines: [window.start, window.end],
+    text: window.text,
+    signature: window.signature,
+    context: window.context.map(row => (row.line === line ? "►" : " ") + row.line + " " + row.text),
+  };
+}

package/src/context/surface.js

@@ -81,10 +81,10 @@ const JS_DECL_PATTERNS = [
 // Module-level tables/constants (column 0 only): without them the previous declaration's span swallows them.
 const JS_TOP_LEVEL_BINDING = /^(const|let|var)\s+([a-zA-Z0-9_$]+)\s*=/;
 
-// Indented methods (object-literal adapters, class members) that open a block on the same line.
-const JS_METHOD = /^(?:static\s+)?(?:async\s+)?(?:get\s+|set\s+)?\*?([a-zA-Z_$][\w$]*)\s*\([^()]*\)\s*\{$/;
+// Indented methods (object-literal adapters, class members), including one-liners.
+const JS_METHOD = /^(?:static\s+)?(?:async\s+)?(?:get\s+|set\s+)?\*?([a-zA-Z_$][\w$]*)\s*\([^()]*\)\s*\{/;
 
-const JS_ARROW_PROPERTY = /^([a-zA-Z_$][\w$]*)\s*[:=]\s*(?:async\s+)?(?:\([^()]*\)|[a-zA-Z_$][\w$]*)\s*=>\s*\{$/;
+const JS_ARROW_PROPERTY = /^([a-zA-Z_$][\w$]*)\s*[:=]\s*(?:async\s+)?(?:\([^()]*\)|[a-zA-Z_$][\w$]*)\s*=>\s*\{/;
 
 const NOT_METHOD_NAMES = new Set(["if", "for", "while", "switch", "catch", "function", "return", "else", "do", "try", "with", "await", "typeof", "new", "constructor"]);
 
@@ -93,16 +93,18 @@ function methodItem(line, lineNumber, depth) {
 
   if (!match || NOT_METHOD_NAMES.has(match[1])) return null;
 
-  return { kind: "method", name: match[1], isExport: false, signature: line.replace(/\s*\{$/, ""), line: lineNumber, depth };
+  return { kind: "method", name: match[1], isExport: false, signature: line.replace(/\s*\{.*$/, "").trim(), line: lineNumber, depth };
 }
 
 function declarationItem(line, rawLine, lineNumber) {
+  const indent = rawLine.length - rawLine.trimStart().length;
+  const depth = Math.floor(indent / 2);
   const patterns = /^\S/.test(rawLine) ? [...JS_DECL_PATTERNS, [JS_TOP_LEVEL_BINDING, false]] : JS_DECL_PATTERNS;
 
   for (const [pattern, isExport] of patterns) {
     const match = pattern.exec(line);
 
-    if (match) return { kind: match[1], name: match[2], isExport, signature: line.replace(/\{.*$/, "").trim(), line: lineNumber, depth: 0 };
+    if (match) return { kind: match[1], name: match[2], isExport, signature: line.replace(/\{.*$/, "").trim(), line: lineNumber, depth };
   }
 
   return null;
@@ -116,7 +118,7 @@ function scanJavaScript(lines) {
 
     if (!line || line.startsWith("//") || line.startsWith("/*") || line.startsWith("*")) continue;
     const indent = lines[i].length - lines[i].trimStart().length;
-    const item = declarationItem(line, lines[i], i + 1) || (indent > 0 && indent <= 8 ? methodItem(line, i + 1, 1) : null);
+    const item = declarationItem(line, lines[i], i + 1) || (indent > 0 && indent <= 8 ? methodItem(line, i + 1, Math.max(1, Math.floor(indent / 2))) : null);
 
     if (item) items.push(item);
   }

package/src/fs/json-read.js

@@ -43,7 +43,11 @@ export function jsonProjector(json) {
   return function* (root) {
     for (const steps of plans) yield steps.reduce((value, step) => {
       if (step.key !== undefined) {
-        if (!isObject(value) || !Object.hasOwn(value, step.key)) throw new Error("JSON field not found: " + JSON.stringify(step.key));
+        if (!isObject(value) || !Object.hasOwn(value, step.key)) {
+          const keys = isObject(value) ? Object.keys(value) : [];
+          const preview = keys.length ? "; available keys: " + keys.slice(0, 24).map(key => JSON.stringify(key)).join(", ") + (keys.length > 24 ? ", …" : "") : "";
+          throw new Error("JSON field not found: " + JSON.stringify(step.key) + preview);
+        }
 
         return value[step.key];
       }

package/src/fs/vfs.js

@@ -11,6 +11,9 @@ let commitTail = Promise.resolve();
 export class CausalVfs {
   constructor(onNewFile, validateWrite) {
     this.validateWrite = validateWrite;
+    // Last-seen original bytes for write CAS, not a read cache. read() always
+    // hits disk unless an overlay is staged. Serving cache on read would be a
+    // false-valid against editors/git between two reads.
     this.cache = new Map();
     this.overlays = [];
     this.expected = new Map();

package/src/fs/workspace.js

@@ -64,14 +64,38 @@ export function isTestPath(filePath) {
   return segments.some((s) => TEST_SEGMENTS.has(s)) || /\.(test|spec)\./.test(base);
 }
 
-export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false, fresh = false) {
+/** Reject scheme:// and scheme:/ paths. A single-letter drive (C:/) stays a filesystem path. */
+export function assertFilesystemPath(inputPath, opName, allowSessionRead = false) {
   if (inputPath == null || !isString(inputPath) || !inputPath.trim()) {
     throw new Error(`${opName} requires path`);
   }
 
-  if (/^(?:agent|artifact):\/\//i.test(inputPath.trim())) throw new Error(`${opName} requires a filesystem path; session resource URIs are read-only`);
+  const trimmed = inputPath.trim();
+
+  if (/^(?:agent|artifact):\/\//i.test(trimmed)) {
+    if (allowSessionRead) return trimmed;
+    throw new Error(`${opName} requires a filesystem path; session resource URIs are read-only`);
+  }
+
+  const uri = /^([a-zA-Z][a-zA-Z0-9+.-]*):(.*)$/.exec(trimmed);
+
+  if (uri) {
+    const scheme = uri[1];
+    const rest = uri[2];
+    const windowsDrive = scheme.length === 1 && (rest.startsWith("/") || rest.startsWith("\\"));
+
+    if (!windowsDrive && (rest.startsWith("//") || rest.startsWith("/"))) {
+      throw new Error(`${opName} does not accept ${scheme}: URI paths; use a workspace filesystem path`);
+    }
+  }
+
+  return trimmed;
+}
+
+export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false, fresh = false) {
+  const trimmed = assertFilesystemPath(inputPath, opName);
   const resolvedCwd = getResolvedCwd(cwd);
-  const target = path.resolve(resolvedCwd, inputPath.trim());
+  const target = path.resolve(resolvedCwd, trimmed);
   assertInside(path.relative(resolvedCwd, target), `${opName} path escapes workspace: paths resolve relative to ${resolvedCwd}`);
 
   if (!allowRoot && target === resolvedCwd) {

package/src/output/bottleneck.js

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import { isString, isObject } from "../shared/decode.js";
-import { truncateChars, formatReturn } from "./format.js";
+import { truncateChars, formatReturn, formatBoundedStringArray } from "./format.js";
 
 function json(value) {
   try { return JSON.stringify(value) ?? "null"; } catch { return JSON.stringify(String(value)); }
@@ -152,12 +152,19 @@ export function packageHostResult(raw, config) {
 export function packageFinalReturn(value, logs, config) {
   const images = [];
   let imageBytes = 0;
+  let imageOverflow = false;
 
   const collect = input => {
     if (input?.type === "image" && isString(input.data) && isString(input.mimeType) && input.mimeType.startsWith("image/")) {
-      imageBytes += Buffer.byteLength(input.data, "base64");
+      const size = Buffer.byteLength(input.data, "base64");
 
-      if (images.length >= 16 || imageBytes > 20 * 1024 * 1024) throw new Error("returned images exceed 16 attachments or 20 MiB; return fewer or smaller images");
+      if (images.length >= 16 || imageBytes + size > 20 * 1024 * 1024) {
+        imageOverflow = true;
+
+        return "[image omitted: exceeds 16 attachments or 20 MiB]";
+      }
+
+      imageBytes += size;
       images.push({ type: "image", data: input.data, mimeType: input.mimeType });
 
       return `[image ${images.length}: ${input.mimeType}]`;
@@ -171,7 +178,13 @@ export function packageFinalReturn(value, logs, config) {
   };
 
   value = collect(value);
-  const serialized = truncateChars(formatReturn(value), config.maxReturnChars ?? 32000, "return");
+  const maxReturn = config.maxReturnChars ?? 32000;
+  const formatted = formatReturn(value);
+  const serialized = formatted.length <= maxReturn
+    ? { text: formatted, truncated: imageOverflow }
+    : Array.isArray(value) && value.length && value.every(isString)
+      ? { text: formatBoundedStringArray(value, maxReturn), truncated: true }
+      : { ...truncateChars(formatted, maxReturn, "return"), truncated: true };
   const maxLines = config.maxLogLines ?? 100;
   let logTruncated = logs.length > maxLines;
 

package/src/output/format.js

@@ -71,6 +71,25 @@ function hasWellFormedStrings(values) {
   return true;
 }
 
+/** Keep every array item in an oversized return by giving each a fair truncated share. */
+export function formatBoundedStringArray(values, budget) {
+  const n = values.length;
+  const header = "strings[" + n + "]\n";
+  let remaining = Math.max(0, budget - header.length);
+  let out = header;
+
+  for (let i = 0; i < n; i++) {
+    const itemHeader = "[" + i + "] " + values[i].length + " UTF-16 units\n";
+    const per = Math.max(32, Math.floor(remaining / (n - i)) - itemHeader.length - 1);
+    const bounded = truncateChars(values[i], per, "return");
+    const chunk = itemHeader + bounded.text + "\n";
+    remaining = Math.max(0, remaining - chunk.length);
+    out += chunk;
+  }
+
+  return out;
+}
+
 /** Lossless framing for source arrays, not string escaping or source compression. */
 export function formatReturn(value) {
   if (isString(value)) return value;

package/src/runtime/guest-worker.js

@@ -1,6 +1,6 @@
 import { parentPort } from "node:worker_threads";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { isString, isObject, isFunction, toPlain } from "../shared/decode.js";
+import { isString, isObject, isFunction, isNumber, toPlain, looksLikePath } from "../shared/decode.js";
 import { truncateChars } from "../output/format.js";
 import { sessionJsonArgs, validateJsonRead } from "../fs/json-read.js";
 
@@ -94,7 +94,11 @@ function leanEnvelope(res) {
   return res;
 }
 
-function buildGuestApi(available, batchRead, runId, nativeArgv) {
+function quoteShellArg(value) {
+  return "'" + String(value).replaceAll("'", "'\\''") + "'";
+}
+
+function buildGuestApi(available, batchRead, runId, _nativeArgv) {
   const rpc = (method, args) => callRpc(runId, method, args);
   const availableSet = new Set(available);
   const checkpointScope = new AsyncLocalStorage();
@@ -107,8 +111,6 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
   };
 
   const nova = {
-    search: (query, limit) => rpc("search", [query, limit]),
-    describe: (name) => rpc("describe", [name]),
     call: async (name, args) => leanEnvelope(await rpc("call", [name, args])),
     async callMany(calls) {
       const wave = await rpc("callMany", [calls]);
@@ -191,6 +193,9 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
   const read = async (p, a, b) => {
     assertScope();
     const args = sessionJsonArgs(readArgs(p, a, b));
+    if (isString(args.path) && args.resolve === undefined && args.json === undefined && !looksLikePath(args.path) && !/^(?:agent|artifact):\/\//i.test(args.path)) {
+      args.resolve = true;
+    }
     validateJsonRead(args);
     const decode = value => args.resolve || args.json !== undefined ? JSON.parse(value) : value;
 
@@ -241,10 +246,31 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
 
   const write = async (p, content) => unwrapValue(await invoke("write", isObject(p) ? p : { path: p, content }));
 
+  const viewSpan = (value) => {
+    const start = isNumber(value.start) ? value.start : Array.isArray(value.lines) ? value.lines[0] : value.line;
+    const end = isNumber(value.end) ? value.end : Array.isArray(value.lines) && value.lines.length > 1 ? value.lines[1] : start;
+
+    if (!isNumber(start) || !isNumber(end) || start < 1 || end < start) return null;
+
+    return { start: Math.floor(start), end: Math.floor(end) };
+  };
+
+  const isView = (value) => isObject(value) && !Array.isArray(value) && isString(value.path) && value.path.trim() && isString(value.text) && (value.status === undefined || value.status === "found") && viewSpan(value);
+
   const edit = async (p, oldText, newText) => {
     if (isFunction(p)) return nova.speculate(p);
     const usage = 'invalid edit signature; use edit(path,oldText,newText), edit({path,edits:[{oldText,newText}]}), or edit({path,patch:"@@ -1 +1 @@\n-old\n+new\n"})';
 
+    if (isView(p) && isString(oldText) && (newText === undefined || isString(newText))) {
+      if (isNumber(p.nextOffset)) throw new Error("edit view is incomplete");
+      const span = viewSpan(p);
+      const args = { path: p.path, viewStart: span.start, viewEnd: span.end, viewText: p.text, newText: newText === undefined ? oldText : newText };
+
+      if (newText !== undefined) args.oldText = oldText;
+
+      return unwrapValue(await invoke("edit", args));
+    }
+
     if (isObject(p) && (Array.isArray(p) || oldText !== undefined || newText !== undefined)) throw new Error(usage);
 
     if (!isObject(p) && isObject(oldText) && !Array.isArray(oldText)) throw new Error(usage);
@@ -268,19 +294,21 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
     return unwrapValue(await invoke(args.patch === undefined ? "edit" : "apply_patch", args));
   };
 
-  const patch = async (p, diff) => unwrapValue(await nova.call("apply_patch", { path: p, patch: diff }));
-
   const bash = async (command, opts) => {
     const args = isObject(command) ? { ...command } : { command, ...opts };
 
     if (args.args !== undefined) {
-      if (!isString(args.command) || !Array.isArray(args.args) || args.args.some(arg => !isString(arg))) throw new Error("bash argv requires a command string and an array of string args");
+      if (!isString(args.command) || !Array.isArray(args.args)) throw new Error("bash argv requires a command string and an array of string args");
 
-      if (nativeArgv) args._directArgv = true;
-      else {
+      for (let i = 0; i < args.args.length; i++) if (!isString(args.args[i])) throw new Error("bash argv requires a command string and an array of string args");
+
+      // Literal argv is a Supernova-owned contract. Host bash tools often ignore
+      // `args` and would run only `command` (bare `ssh`). Windows still needs a shell.
+      if (process.platform === "win32") {
         delete args._directArgv;
         args.command = [args.command, ...args.args].map(quoteShellArg).join(" ");
-      }
+        delete args.args;
+      } else args._directArgv = true;
     }
 
     command = args.command;
@@ -307,20 +335,7 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
     return text;
   };
 
-  const quoteShellArg = (value) => "'" + String(value).replaceAll("'", "'\\''") + "'";
-
-  const exec = async (cmd, args, opts) => {
-    const command = String(cmd ?? "").trim();
-
-    if (!command) throw new Error("exec requires command");
-
-    // exec("git status") is a shell line; exec("git", ["status"]) is argv.
-    if (!Array.isArray(args) || args.length === 0) return bash(command, opts);
-
-    return bash([command, ...args].map(quoteShellArg).join(" "), opts);
-  };
-
-  return { nova, read, write, edit, patch, surface: nova.surface, snap: nova.snap, evidence: nova.evidence, bash, exec, speculate: nova.speculate };
+  return { read, write, edit, bash };
 }
 
 function makeConsole(runId, limits) {

package/src/runtime/reference.js

@@ -1,25 +1,18 @@
 // Complete model-facing API reference; kept in every request, not moved into history.
-export const REFERENCE = `Run a JavaScript async body or arrow with read, write, edit and bash. Strings stay raw. Single program: exactly one of code or file; file rereads a workspace program with the same limits, bindings, calling-workspace cwd and fresh guest. Code and data character caps use UTF-16 units. Split large writes using append.
+export const REFERENCE = `JavaScript async body or arrow with read, write, edit, bash. Strings stay raw. Exactly one of code or file; file rereads that program (same limits, cwd, fresh guest). Caps are UTF-16. Put Markdown/scripts/argv in data.
 
-Native commands (async):
-read(path|paths, offset?, limit?) → file text or text[]; read(directory) → directory entries
-read(imagePath) → image attachment when returned (PNG/JPEG/GIF/WebP/BMP); no browser needed
-read({path,json:".field"}) → parsed JSON field; supports .items[0:3], quoted keys, selector arrays, or true for the whole JSON value
-read("agent://id?q=.answer") → JSON field from a calling-session resource (when host artifacts are available)
-read("symbol or question") → locate and open source in one call, without an index; selected file text stays raw
-read({query, resolve:true}) → {status,path,line,lines,text,complete,nextOffset?} for a direct resolve→edit handoff
-read(path, {about: question}) → relevant file bodies, or source selection inside a directory
-read({query, evidence:true}) → ranked evidence; read({path, outline:true}) → structural declarations
-write(path, text) → write a file; write({path,content,append:true}) appends a chunk without a bounded read
-edit(path, oldText, newText) → post-edit lines, checks, and references
-edit(async () => {...}) → filesystem checkpoint: commit on success, rollback on throw; no shell commands, nesting, or concurrent outside commands
-bash(command, {cwd?, timeoutMs?}) → bounded output; throws on non-zero exit
-bash({command, args:[...]}) → literal argv without shell expansion of arguments
+read(path|paths, offset?, limit?) → raw text or text[]; read(directory) → entries
+read(imagePath) → image (PNG/JPEG/GIF/WebP/BMP)
+read({path,json:".field"}) → parsed JSON; .items[0:3], quoted keys, selector arrays, or true; 16 MiB cap; no jq
+read("agent://id?q=.answer") → JSON field from session artifacts
+read("symbol or question") → same view as resolve:true
+read({query,resolve:true}) → {status,path,line,lines,text,complete,nextOffset?}
+read(path,{about}) → matching windows; read({query,evidence:true}) → ranked evidence; read({path,outline:true}) → declarations
+write(path, text) → replace; write({path,content,append:true}) → append without a prior read
+edit(path,oldText,newText) | edit({path,edits}) | edit({path,patch}) → numbered post-edit lines, checks, references
+edit(async () => {...}) → checkpoint: commit on success, rollback on throw; no shell, nesting, or outside commands
+bash(command,{cwd?,timeoutMs?}) → bounded output; nonzero throws
+bash({command,args}) → literal argv, no shell expansion of args
 
-Start with a source question or scoped about read; do not redundantly reopen selected source. Only found selects and opens a file. Uncertain reads return ambiguous, not_found, or incomplete with no selected path. Use resolve:true to check status before editing its path; narrow the directory with path+about when uncertain.
-For read-modify-write, use read({path,complete:true}); it rejects partial output. JSON selectors parse the full document (16 MiB cap); selections must fit the read budget. No full jq; do not JSON.parse line windows. For large text audits use about or offset/limit, not complete:true. Prefer edit for large files. Array reads reject failures; use Promise.allSettled for per-path outcomes.
-Object arguments also work: read({path, offset?, limit?, about?, outline?, evidence?, resolve?, complete?}), edit({path, edits:[{oldText,newText}]}), edit({path,patch}), write({path,content}), bash({command,timeoutMs?}).
-File changes stage until program success; later errors roll them back. Shell calls commit preceding writes and cannot be rolled back. Outcomes report committed/rolledBack file versions and external-call attempts.
-Independent read starts batch automatically. Mutations preserve submission order. Plain reads remain self-contained; oversized reads provide continuation offsets. Return only what the model needs. console.log is captured.
-
-For known continuations use programs:[{code|file,data?},...]. Entries run sequentially in fresh guests with separate commits. The batch stops on failure and returns all attempted results, including a typed stop report; earlier commits remain. Deadlines, host calls, logs and output are shared across the batch. Use separate calls when the next action needs model reasoning.`;
+edit oldText is an exact substring of read(); a miss includes a numbered window. Found is a span, not the file; uncertain returns ambiguous, not_found, or incomplete. Check resolve:true status; edit(view,text) replaces that window; edit(view,old,new) is unique inside it. complete:true rejects partial files; use about or offset/limit for large audits. Array reads reject failures; Promise.allSettled for per-path outcomes. Edits stage until success; bash commits preceding writes.
+programs:[{code|file,data?},...] sequential fresh guests, separate commits; stop on failure keeps earlier commits. Separate calls when the next step needs a model decision.`;

package/src/runtime/runtime.js

@@ -154,8 +154,6 @@ const RPC_METHODS = {
 
     return Array.isArray(wave) ? { results: [...wave], mode: wave.mode, reason: wave.reason } : wave;
   },
-  search: (nova, args) => nova.search(args[0], args[1]),
-  describe: (nova, args) => nova.describe(args[0]),
   speculateBegin: (nova) => nova.speculateBegin(),
   speculateCommit: (nova) => nova.speculateCommit(),
   speculateRollback: (nova) => nova.speculateRollback(),

package/src/shared/decode.js

@@ -8,6 +8,17 @@ export const isFunction = (v) => toStr.call(v) === "[object Function]" || v inst
 
 export const isNumber = (v) => toStr.call(v) === "[object Number]" && Number.isFinite(v);
 
+/** Path-shaped if it has a slash, is relative, or has a file extension. Identifiers are not paths. */
+export function looksLikePath(target) {
+  return (
+    isString(target) &&
+    (target.includes("/") ||
+      target.includes("\\") ||
+      target.startsWith(".") ||
+      (!/\s/.test(target) && /\.[A-Za-z0-9]+$/.test(target)))
+  );
+}
+
 const MAX_DEPTH = 64;
 
 const MAX_TYPED_ARRAY = 4096;