pi-supernova 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -2,9 +2,25 @@
 
 ## [Unreleased]
 
+## [0.0.5] - 2026-09-03
+
 ### Fixed
 
 - Native adapters are now included in `nova.search` / `nova.describe` with schemas matching the callable adapter, even when the host catalog omits parameters or the adapter name.
+- `snap` discovers explicitly targeted hidden paths outside `.git` and sees files written earlier in the same speculative invocation.
+- Top-level `snap()` and `surface()` helpers return structured objects, enabling an immediate `edit(hit.path, ...)` handoff.
+- Live command activity remains visible across partial updates and final merged cards.
+- Collapsed cards show a compact, correctly labeled call ledger with paths and change counts; diff hunks are bounded and shown only when expanded.
+- Multi-replacement edits report only the changed hunks instead of presenting the entire file as replaced.
+- Syntax errors now roll back the outer VFS transaction instead of leaking speculative depth into the next Supernova call.
+- Root-level Snap searches continue to ignore hidden files; hidden discovery is enabled only when the caller explicitly targets a hidden search root, while Git metadata remains excluded.
+- Command cards cover custom tools, mark failed traces accurately, sanitize terminal controls, and remain width-safe for narrow terminals and wide emoji.
+
+## [0.0.4] - 2026-09-03
+
+### Fixed
+
+- OMP no longer hangs on "Loading plugins…" — removed top-level import of `@oh-my-pi/pi-coding-agent/tui` from the extension (portable framed chrome only).
 
 ## [0.0.3] - 2026-09-03
 

package/README.md

@@ -46,16 +46,20 @@ async () => {
 }
 ```
 
-Globals: `nova` / `tools`, `parallel`, `pipeline`, `console`, plus shorthand `read` / `write` / `edit` / `bash` / …
+Globals: `nova` / `tools`, `parallel`, `pipeline`, `console`, plus shorthand `read`, `write`, `edit`, `patch`, `surface`, `snap`, `bash`, and `exec`.
 
 Terminal card (muted violet / grey-blue — not a raw JSON args dump):
 
 ```text
-  nova · 84ms
-    ▤ read  packages/pi-supernova/host-bridge.js
-    ✎ edit  packages/pi-supernova/diff.js
+╭─── nova: 3 calls · 84ms ───────────────────────╮
+│ ✓ read    packages/pi-supernova/host-bridge.js │
+│ ✓ edit    packages/pi-supernova/diff.js +2/-1  │
+│ ✓ snap    "render lifecycle" → packages        │
+╰────────────────────────────────────────────────╯
 ```
 
+Collapsed cards keep this command ledger visible. Press Enter to inspect bounded diff hunks, logs, and the returned value.
+
 ---
 
 ## API
@@ -66,9 +70,14 @@ Terminal card (muted violet / grey-blue — not a raw JSON args dump):
 | `nova.describe(name)` | Parameter summary on demand |
 | `nova.call(name, args)` | Host tool or native adapter |
 | `nova.callMany([{name,args}])` | Auto parallel wave — iterable array with `.mode` / `.results` |
+| `nova.surface(path)` | Structural outline for a source file |
+| `nova.snap(query, searchRoot?)` | Most relevant source path, line, signature, confidence, and context |
+| `nova.has(name)` | Whether a catalog or native tool is callable |
 | `parallel(thunks)` / `pipeline(items, …stages)` | Raw `Promise.all` helpers |
 | `nova.speculate(fn)` | Counterfactual branch (rollback / commit) |
 
+Root Snap searches ignore hidden files. Passing a hidden search root includes hidden files beneath that root; Git metadata is always excluded.
+
 ---
 
 ## Configuration
@@ -126,7 +135,7 @@ Pair with DCE last if you use it: `omp install npm:pi-deferred-context-engine`.
 
 - Guest JS is **unsandboxed**. Adapter path jails are not a boundary against `import("node:fs")`.
 - `bash` / mutating tools flush speculative writes (transaction barrier); error rollback cannot undo that.
-- First public cut (`0.0.1`) — APIs and TUI will iterate.
+- Pre-1.0 package — APIs and TUI may still evolve between minor releases.
 
 ## License
 

package/catalog.js

@@ -28,7 +28,10 @@ export const NATIVE_TOOL_DEFINITIONS = [
   },
   {
     name: "snap", description: "Resolve a concept query to the most relevant workspace source location.",
-    parameters: { type: "object", properties: { query: { type: "string" }, path: { type: "string" } }, required: ["query"] },
+    parameters: { type: "object", properties: {
+      query: { type: "string", description: "Source concept to resolve" },
+      path: { type: "string", description: "Optional workspace search root; explicitly targeting a hidden directory includes its hidden files, but Git metadata is always excluded" },
+    }, required: ["query"] },
   },
   {
     name: "surface", description: "Extract a structural outline from a workspace source file.",

package/diff.js

@@ -35,6 +35,27 @@ export function buildEditDiff(filePath, originalText, oldText, newText) {
   };
 }
 
+export function buildMultiEditDiff(filePath, originalText, replacements) {
+  const parts = replacements.map(({ oldText, newText }) =>
+    buildEditDiff(filePath, originalText, oldText, newText),
+  );
+  const lines = [];
+  for (const part of parts) {
+    for (const line of part.lines) {
+      const previous = lines.at(-1);
+      if (previous?.type === "context" && line.type === "context" && previous.lineNum === line.lineNum) continue;
+      lines.push(line);
+    }
+  }
+  return {
+    path: filePath,
+    op: "edit",
+    added: parts.reduce((sum, part) => sum + part.added, 0),
+    removed: parts.reduce((sum, part) => sum + part.removed, 0),
+    lines,
+  };
+}
+
 export function buildPatchDiff(filePath, patchText) {
   const patchLines = isString(patchText) ? patchText.replace(/\r\n/g, "\n").split("\n") : [];
   const lines = [];

package/host-bridge.js

@@ -6,7 +6,7 @@ import { packageHostResult } from "./bottleneck.js";
 import { isString, isNumber, isFunction } from "./decode.js";
 import { isMutatingTool, runParallelWave } from "./parallel.js";
 import { extractStructuralSurface } from "./surface.js";
-import { buildEditDiff, buildPatchDiff, buildWriteDiff } from "./diff.js";
+import { buildEditDiff, buildMultiEditDiff, buildPatchDiff, buildWriteDiff } from "./diff.js";
 import { executeSnap } from "./snap.js";
 
 function textResult(text, details) {
@@ -33,7 +33,7 @@ async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false) {
   const resolvedCwd = getResolvedCwd(cwd);
   const target = path.resolve(resolvedCwd, inputPath.trim());
   const rel = path.relative(resolvedCwd, target);
-  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+  if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
     throw new Error(`${opName} path escapes workspace`);
   }
   if (!allowRoot && target === resolvedCwd) {
@@ -54,7 +54,7 @@ async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false) {
     }
   }
   const realRel = path.relative(realRoot, probe);
-  if (realRel.startsWith("..") || path.isAbsolute(realRel)) {
+  if (realRel === ".." || realRel.startsWith(`..${path.sep}`) || path.isAbsolute(realRel)) {
     throw new Error(`${opName} path escapes workspace through symlink`);
   }
   return target;
@@ -242,6 +242,14 @@ class CausalVfs {
     return undefined;
   }
 
+  getOverlayPaths() {
+    const paths = new Set();
+    for (const overlay of this.overlays) {
+      for (const target of overlay.keys()) paths.add(target);
+    }
+    return [...paths];
+  }
+
   async read(target) {
     const overlay = this.getOverlay(target);
     if (overlay !== undefined) return overlay;
@@ -501,7 +509,7 @@ function createNativeAdapters(getCwd, vfs, config) {
       const diff =
         matches.length === 1
           ? buildEditDiff(target, content, matches[0].oldText, matches[0].newText)
-          : { ...buildWriteDiff(target, content, updated), op: "edit" };
+          : buildMultiEditDiff(target, content, matches);
       const tag = speculative ? " (speculative)" : "";
       return textResult(`edited ${target}${tag}`, { path: target, speculative, diff });
     },
@@ -537,9 +545,14 @@ function createNativeAdapters(getCwd, vfs, config) {
       }
       if (signal?.aborted) throw new Error("aborted");
       const snapTarget = params?.path ? await resolveWorkspacePath(cwd, params.path, "snap", true) : cwd;
+      const relativeRoot = path.relative(cwd, snapTarget);
+      const includeHidden = Boolean(params?.path) && relativeRoot
+        .split(path.sep)
+        .some((segment) => segment.startsWith(".") && segment.length > 1);
       const res = await executeSnap({
         query: params.query,
         searchDir: snapTarget,
+        includeHidden,
         vfs: {
           read: async (candidate) => {
             // Jail each snap candidate (symlink files must not escape the workspace).
@@ -548,6 +561,7 @@ function createNativeAdapters(getCwd, vfs, config) {
           },
         },
         runCommand: (argv, opts) => runCommand(argv, { cwd: snapTarget, signal, ...opts }),
+        pendingPaths: vfs.getOverlayPaths(),
       });
       return textResult(JSON.stringify(res, null, 2), res);
     },
@@ -726,6 +740,13 @@ export function createHostBridge({ pi, config, getCwd }) {
     vfs.clear();
   }
 
+  function notifyCall(record) {
+    if (!callListener) return;
+    try {
+      callListener(record, [...trace]);
+    } catch {}
+  }
+
   async function invokeRaw(name, args) {
     const maxCalls = config.maxBridgeCalls ?? 256;
     callCount += 1;
@@ -746,33 +767,33 @@ export function createHostBridge({ pi, config, getCwd }) {
     const record = { name, args: args || {}, time: Date.now() };
     trace.push(record);
 
-    const exec = executors.get(name);
-    if (exec) {
-      if (isMutatingTool(name, config)) await vfs.prepareExternalMutation(name);
-      const res = await exec(`supernova:${name}:${callCount}`, args || {}, activeSignal, undefined, activeCtx);
-      if (callListener) {
-        try {
-          callListener(record, [...trace]);
-        } catch {}
+    try {
+      const exec = executors.get(name);
+      if (exec) {
+        if (isMutatingTool(name, config)) await vfs.prepareExternalMutation(name);
+        const res = await exec(`supernova:${name}:${callCount}`, args || {}, activeSignal, undefined, activeCtx);
+        record.ok = res?.isError !== true && res?.details?.ok !== false;
+        notifyCall(record);
+        return res;
       }
-      return res;
-    }
 
-    const native = natives[name];
-    if (native) {
-      const res = await native(args || {}, activeSignal);
-      if (res?.details?.diff) record.diff = res.details.diff;
-      if (callListener) {
-        try {
-          callListener(record, [...trace]);
-        } catch {}
+      const native = natives[name];
+      if (native) {
+        const res = await native(args || {}, activeSignal);
+        if (res?.details?.diff) record.diff = res.details.diff;
+        record.ok = res?.isError !== true && res?.details?.ok !== false;
+        notifyCall(record);
+        return res;
       }
-      return res;
-    }
 
-    throw new Error(
-      `no executor for tool "${name}" (not captured via registerTool and no native adapter). Use nova.describe to inspect; ensure pi-supernova loads before other extensions, or call a core adapter: ${Object.keys(natives).join(", ")}`,
-    );
+      throw new Error(
+        `no executor for tool "${name}" (not captured via registerTool and no native adapter). Use nova.describe to inspect; ensure pi-supernova loads before other extensions, or call a core adapter: ${Object.keys(natives).join(", ")}`,
+      );
+    } catch (error) {
+      record.ok = false;
+      notifyCall(record);
+      throw error;
+    }
   }
 
   async function call(name, args) {

package/index.js

@@ -1,16 +1,4 @@
-
-let Type;
-try {
-  Type = (await import("typebox")).Type;
-} catch {
-  Type = {
-    Object: (props, opts) => ({ type: "object", properties: props || {}, additionalProperties: false, ...opts }),
-    String: (opts) => ({ type: "string", ...opts }),
-    Integer: (opts) => ({ type: "integer", ...opts }),
-    Optional: (s) => ({ ...s }),
-  };
-}
-
+import { createRequire } from "node:module";
 import { isString, isFunction } from "./decode.js";
 import { buildCatalog, searchCatalog, describeTool, mergeNativeToolDefinitions } from "./catalog.js";
 import { loadConfig } from "./config.js";
@@ -25,6 +13,20 @@ import {
 
 export { extractOperationsFromCode, renderSupernovaCall, renderSupernovaResult, SafeText };
 
+// Sync only — never top-level await. Dynamic import of host/deps hung OMP plugin load.
+const require = createRequire(import.meta.url);
+let Type;
+try {
+  Type = require("typebox").Type;
+} catch {
+  Type = {
+    Object: (props, opts) => ({ type: "object", properties: props || {}, additionalProperties: false, ...opts }),
+    String: (opts) => ({ type: "string", ...opts }),
+    Integer: (opts) => ({ type: "integer", ...opts }),
+    Optional: (s) => ({ ...s }),
+  };
+}
+
 function result(text, details) {
   return { content: [{ type: "text", text }], details };
 }
@@ -36,8 +38,12 @@ Inside the program you get:
   nova.describe(name)          — full parameter summary on demand
   nova.call(name, args)        — invoke a host tool (or native adapter)
   nova.callMany([{name,args}]) — Auto parallel wave (serial if any mutating)
+  nova.snap(query, root?)       — resolve a concept to a source location
+  nova.surface(path)            — structural source outline
+  nova.has(name)                — test host-tool availability
   parallel(thunks) / pipeline(items, ...stages)
 
+Shorthand globals: read, write, edit, patch, exec, snap, surface.
 Prefer search→describe→call. Keep intermediates in the program; return a shaped value.
 Schemas are NOT dumped into the system prompt — discover them inside the runtime.`;
 
@@ -162,6 +168,7 @@ export default function piSupernova(pi) {
         timeoutMs: Number.isInteger(params?.timeoutMs) ? params.timeoutMs : config.timeoutMs,
       };
 
+      const runStartedAt = performance.now();
       let outcome;
       try {
         outcome = await runGuestProgram({
@@ -171,7 +178,15 @@ export default function piSupernova(pi) {
           signal: runController.signal,
           onTimeout: abortRun,
         });
+      } catch (error) {
+        outcome = {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+          logs: [],
+          wallMs: Math.round(performance.now() - runStartedAt),
+        };
       } finally {
+        bridge.setCallListener(null);
         signal?.removeEventListener("abort", abortRun);
       }
 

package/omp-frame.js

@@ -1,10 +1,8 @@
 /**
- * OMP-native tool chrome for supernova.
+ * OMP-style rounded tool chrome for supernova.
  *
- * Prefer host `framedBlock` + `renderStatusLine` from
- * `@oh-my-pi/pi-coding-agent/tui` (same path read/write/edit use). Fall back to a
- * portable rounded frame that matches that look when the import is unavailable
- * (Pi path-install / unit tests).
+ * Intentionally self-contained — never dynamic-imports `@oh-my-pi/pi-coding-agent`
+ * (that hung OMP plugin load). Geometry matches native write/edit framedBlock.
  */
 
 import { clampLine, measureWidth, wrapPlainToWidth } from "./render-measure.js";
@@ -20,32 +18,12 @@ const DEFAULT_BOX = {
 	teeRight: "├",
 };
 
-let hostFramedBlock = null;
-let hostRenderStatusLine = null;
-let hostMarkFramed = null;
-let hostResolved = false;
-
-export async function ensureOmpChrome() {
-	if (hostResolved) return;
-	hostResolved = true;
-	for (const spec of ["@oh-my-pi/pi-coding-agent/tui", "@oh-my-pi/pi-coding-agent/tui/index.js"]) {
-		try {
-			const tui = await import(spec);
-			if (typeof tui.framedBlock === "function") hostFramedBlock = tui.framedBlock;
-			if (typeof tui.renderStatusLine === "function") hostRenderStatusLine = tui.renderStatusLine;
-			if (typeof tui.markFramedBlockComponent === "function") hostMarkFramed = tui.markFramedBlockComponent;
-			if (hostFramedBlock && hostRenderStatusLine) return;
-		} catch {
-			// Pi / tests / plain node — use portable frame.
-		}
-	}
+export function hasHostFramedBlock() {
+	return false;
 }
 
-/** Kick off resolution at module load (extension hosts support top-level await). */
-await ensureOmpChrome();
-
-export function hasHostFramedBlock() {
-	return typeof hostFramedBlock === "function" && typeof hostRenderStatusLine === "function";
+export async function ensureOmpChrome() {
+	// No-op: portable frame only. Kept so call sites stay stable.
 }
 
 function boxOf(theme) {
@@ -69,8 +47,6 @@ function borderPaint(theme, state, borderColor) {
 }
 
 function statusHeader(theme, { title, description, state, spinnerFrame, icon, iconOverride }) {
-	// Match native Write/Edit: framed call heads omit the pending hourglass; only
-	// pass an icon when the caller sets one (error / running / success glyph).
 	const resolvedIcon =
 		iconOverride !== undefined
 			? undefined
@@ -79,21 +55,12 @@ function statusHeader(theme, { title, description, state, spinnerFrame, icon, ic
 				: state === "error"
 					? "error"
 					: undefined;
-	if (hostRenderStatusLine) {
-		return hostRenderStatusLine(
-			{
-				icon: resolvedIcon,
-				iconOverride,
-				spinnerFrame,
-				title,
-				description,
-			},
-			theme,
-		);
-	}
 	const titleText = theme?.fg ? theme.fg("accent", title) : title;
 	const descText = description ? (theme?.fg ? theme.fg("muted", description) : description) : "";
-	const prefix = state === "error" ? (theme?.fg ? theme.fg("error", "✗ ") : "✗ ") : "";
+	let prefix = "";
+	if (iconOverride) prefix = `${iconOverride} `;
+	else if (resolvedIcon === "error") prefix = theme?.fg ? theme.fg("error", "✗ ") : "✗ ";
+	else if (resolvedIcon === "running" || spinnerFrame) prefix = theme?.fg ? theme.fg("dim", "… ") : "… ";
 	return descText ? `${prefix}${titleText}: ${descText}` : `${prefix}${titleText}`;
 }
 
@@ -135,11 +102,16 @@ function bgFnForState(theme, state) {
 	return undefined;
 }
 
-/**
- * Portable rounded frame matching OMP output-block geometry.
- */
 export function renderPortableFrame(theme, { header, sections = [], state = "pending", borderColor, width }) {
-	const w = Math.max(8, width | 0);
+	const w = Math.max(1, width | 0);
+	if (w < 8) {
+		const rawLines = [header];
+		for (const section of sections) {
+			if (section.label) rawLines.push(section.label);
+			rawLines.push(...(section.lines || []));
+		}
+		return rawLines.filter(Boolean).map((line) => clampLine(line, w));
+	}
 	const box = boxOf(theme);
 	const border = borderPaint(theme, state, borderColor);
 	const bgFn = bgFnForState(theme, state);
@@ -161,7 +133,7 @@ export function renderPortableFrame(theme, { header, sections = [], state = "pen
 		return padLine(`${border(left)}${trimmed}${border(h.repeat(fill))}${border(right)}`, w, bgFn);
 	};
 
-	const contentWidth = Math.max(1, w - 2 - 2); // borders + 1-col pad each side
+	const contentWidth = Math.max(1, w - 2 - 2);
 	const lines = [];
 	lines.push(paintBar(box.topLeft, box.topRight, header));
 
@@ -188,7 +160,7 @@ export function createPortableFramedComponent(theme, build) {
 	let cacheWidth;
 	let cacheKey;
 	let cacheLines;
-	const comp = {
+	return {
 		render(width) {
 			const opts = build(width);
 			const key = `${opts.state}|${opts.borderColor}|${opts.header}|${(opts.sections || [])
@@ -206,17 +178,9 @@ export function createPortableFramedComponent(theme, build) {
 			cacheWidth = undefined;
 		},
 	};
-	if (hostMarkFramed) return hostMarkFramed(comp);
-	return comp;
 }
 
-/**
- * Build a framed nova card. Uses host framedBlock when available (OMP).
- */
 export function novaFramedBlock(theme, build) {
-	if (hostFramedBlock) {
-		return hostFramedBlock(theme, build);
-	}
 	return createPortableFramedComponent(theme, build);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-supernova",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Dual-host CodeMode for Pi/OMP: progressive tool discovery, result bottleneck, and Amdahl Auto parallel.",
   "type": "module",
   "author": "AdityaVG13",

package/render-measure.js

@@ -27,6 +27,10 @@ export function measureWidth(text) {
 
 function codePointWidth(cp) {
 	if (cp <= 0x1f || (cp >= 0x7f && cp <= 0x9f)) return 0;
+	if (cp === 0xfe0f) return 1; // Emoji presentation can widen an otherwise narrow symbol.
+	if (cp === 0x200d || (cp >= 0x0300 && cp <= 0x036f) || (cp >= 0x1ab0 && cp <= 0x1aff) ||
+		(cp >= 0x1dc0 && cp <= 0x1dff) || (cp >= 0x20d0 && cp <= 0x20ff) ||
+		(cp >= 0xfe00 && cp <= 0xfe0e) || (cp >= 0xfe20 && cp <= 0xfe2f)) return 0;
 	// Fullwidth / wide ranges (CJK, Hangul, emoji blocks we actually emit).
 	if (cp >= 0x1100 && cp <= 0x115f) return 2;
 	if (cp === 0x2329 || cp === 0x232a) return 2;
@@ -37,8 +41,7 @@ function codePointWidth(cp) {
 	if (cp >= 0xfe30 && cp <= 0xfe6f) return 2;
 	if (cp >= 0xff00 && cp <= 0xff60) return 2;
 	if (cp >= 0xffe0 && cp <= 0xffe6) return 2;
-	if (cp >= 0x1f300 && cp <= 0x1f64f) return 2;
-	if (cp >= 0x1f900 && cp <= 0x1f9ff) return 2;
+	if (cp >= 0x1f000 && cp <= 0x1faff) return 2;
 	if (cp >= 0x20000 && cp <= 0x3fffd) return 2;
 	// Ambiguous emoji/symbols pi-tui treats as wide (⚡ U+26A1 was the 92>91 footgun).
 	if (cp === 0x26a1 || cp === 0x2b50 || cp === 0x2728) return 2;
@@ -107,18 +110,21 @@ export function wrapPlainToWidth(plain, width) {
 		let visible = 0;
 		let lastBreak = -1;
 		while (end < text.length) {
-			const ch = text[end];
+			const cp = text.codePointAt(end);
+			const ch = String.fromCodePoint(cp);
 			const cw = measureWidth(ch);
 			if (visible + cw > w) break;
 			visible += cw;
-			if (ch === "/" || ch === " ") lastBreak = end + 1;
-			end++;
+			end += ch.length;
+			if (ch === "/" || ch === " ") lastBreak = end;
 		}
 		if (end === i) {
-			end = i + 1;
-		} else if (end < text.length && lastBreak > i + Math.floor(w * 0.35)) {
-			end = lastBreak;
+			const ch = String.fromCodePoint(text.codePointAt(i));
+			lines.push(hardTruncate(ch, w));
+			i += ch.length;
+			continue;
 		}
+		if (end < text.length && lastBreak > i + Math.floor(w * 0.35)) end = lastBreak;
 		lines.push(text.slice(i, end));
 		i = end;
 	}

package/render.js

@@ -19,7 +19,7 @@ import {
 	wrapPlainToWidth,
 	fitPath,
 } from "./render-measure.js";
-import { ensureOmpChrome, hasHostFramedBlock, novaFramedBlock, novaStatusLine } from "./omp-frame.js";
+import { novaFramedBlock, novaStatusLine } from "./omp-frame.js";
 
 export { measureWidth, hardTruncate, clampLine, wrapPlainToWidth, fitPath };
 
@@ -185,18 +185,20 @@ export function extractOperationsFromCode(code) {
 
 	const namedCalls = [
 		{ regex: /(?:^|[^\w$.])(?:nova\.)?read\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "read", wrap: (p) => p },
-		{ regex: /(?:^|[^\w$.])(?:nova\.)?write\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "edit", wrap: (p) => p },
+		{ regex: /(?:^|[^\w$.])(?:nova\.)?write\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "write", wrap: (p) => p },
 		{ regex: /(?:^|[^\w$.])(?:nova\.)?edit\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "edit", wrap: (p) => p },
-		{ regex: /(?:^|[^\w$.])(?:nova\.)?patch\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "edit", wrap: (p) => p },
+		{ regex: /(?:^|[^\w$.])(?:nova\.)?patch\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "patch", wrap: (p) => p },
 		{
 			regex: /(?:^|[^\w$.])(?:nova\.)?bash\s*\(\s*["'`]([^"'`]+)["'`]/gm,
 			tool: "bash",
 			wrap: (c) => (c.length > 32 ? c.slice(0, 29) + "…" : c),
 		},
-		{ regex: /(?:^|[^\w$.])(?:nova\.)?exec\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "bash", wrap: (c) => c },
-		{ regex: /(?:nova\.)?search\s*\(\s*["'`]([^"'`]+)["'`]/g, tool: "read", wrap: (q) => `"${q}"` },
-		{ regex: /(?:nova\.)?surface\s*\(\s*["'`]([^"'`]+)["'`]/g, tool: "read", wrap: (p) => p },
-		{ regex: /(?:nova\.)?snap\s*\(\s*["'`]([^"'`]+)["'`]/g, tool: "read", wrap: (q) => `"${q}"` },
+		{ regex: /(?:^|[^\w$.])(?:nova\.)?exec\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "exec", wrap: (c) => c },
+		{ regex: /(?:^|[^\w$.])(?:nova\.)?search\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "search", wrap: (q) => `"${q}"` },
+		{ regex: /(?:^|[^\w$.])nova\.describe\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "describe", wrap: (name) => name },
+		{ regex: /(?:^|[^\w$.])nova\.has\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "has", wrap: (name) => name },
+		{ regex: /(?:^|[^\w$.])(?:nova\.)?surface\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "surface", wrap: (p) => p },
+		{ regex: /(?:^|[^\w$.])(?:nova\.)?snap\s*\(\s*["'`]([^"'`]+)["'`]/gm, tool: "snap", wrap: (q) => `"${q}"` },
 	];
 	for (const item of namedCalls) {
 		while ((match = item.regex.exec(trimmed)) !== null) {
@@ -238,7 +240,7 @@ export function renderDiffBox(diff, theme, width = 60) {
 	const divWidth = Math.min(w, Math.max(20, Math.min(70, w)));
 	const divider = theme.fg("borderMuted", "─".repeat(divWidth));
 
-	const maxShown = 8;
+	const maxShown = 6;
 	const shownLines = diff.lines.slice(0, maxShown);
 	const body = [];
 
@@ -248,17 +250,17 @@ export function renderDiffBox(diff, theme, width = 60) {
 		if (item.type === "remove") {
 			const gut = theme.fg("toolDiffRemoved", `-${num}`.padStart(5));
 			const sep = theme.fg("borderMuted", " │ ");
-			const txt = theme.fg("toolDiffRemoved", `- ${item.text}`);
+			const txt = theme.fg("toolDiffRemoved", `- ${cleanInlineText(item.text)}`);
 			row = `${gut}${sep}${txt}`;
 		} else if (item.type === "add") {
 			const gut = theme.fg("toolDiffAdded", `+${num}`.padStart(5));
 			const sep = theme.fg("borderMuted", " │ ");
-			const txt = theme.fg("toolDiffAdded", `+ ${item.text}`);
+			const txt = theme.fg("toolDiffAdded", `+ ${cleanInlineText(item.text)}`);
 			row = `${gut}${sep}${txt}`;
 		} else {
 			const gut = theme.fg("dim", ` ${num}`.padStart(5));
 			const sep = theme.fg("borderMuted", " │ ");
-			const txt = theme.fg("toolDiffContext", `  ${item.text}`);
+			const txt = theme.fg("toolDiffContext", `  ${cleanInlineText(item.text)}`);
 			row = `${gut}${sep}${txt}`;
 		}
 		body.push(row);
@@ -272,16 +274,26 @@ export function renderDiffBox(diff, theme, width = 60) {
 	return `${header}\n${divider}\n${body.join("\n")}\n${divider}`;
 }
 
-function displayOperation(tool, target) {
-	if (["write", "edit", "apply_patch", "patch"].includes(tool)) return { tool: "edit", target };
-	if (["bash", "exec"].includes(tool)) return { tool: "bash", target };
-	if (["read", "surface", "snap", "search", "grep", "find", "ls"].includes(tool))
-		return { tool: "read", target };
-	return null;
+function cleanBlockText(value) {
+	return stripVTControlCharacters(String(value ?? ""))
+		.replace(/\r\n?/g, "\n")
+		.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, "")
+		.replace(/[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "");
+}
+
+function cleanInlineText(value) {
+	return cleanBlockText(value).replace(/\s*\n\s*/g, " ").trim();
+}
+
+function displayOperation(tool, target, diff, ok) {
+	const rawName = cleanInlineText(tool);
+	if (!rawName) return null;
+	const normalized = rawName === "apply_patch" ? "patch" : rawName;
+	return { tool: normalized, target, diff, ok };
 }
 
 function formatOpTarget(raw, tool) {
-	const text = String(raw ?? "");
+	const text = cleanInlineText(raw);
 	if (!text) return "";
 	if (tool === "bash") {
 		// Keep commands readable; wrap handles the rest at render time.
@@ -348,7 +360,6 @@ function detectResultHost(options, ctxOrArgs) {
 	) {
 		return "omp";
 	}
-	if (hasHostFramedBlock()) return "omp";
 	return "pi";
 }
 
@@ -373,6 +384,7 @@ export function normalizeResultRenderArgs(result, options, themeOrCtx, ctxOrArgs
 			isPartial: !!opts.isPartial,
 			theme: themeOrCtx,
 			context,
+			args: ctxOrArgs?.code ? ctxOrArgs : context.args,
 			host: detectResultHost(options, ctxOrArgs),
 			options: opts,
 		};
@@ -387,6 +399,7 @@ export function normalizeResultRenderArgs(result, options, themeOrCtx, ctxOrArgs
 			isPartial: !!context.isPartial,
 			theme: options,
 			context,
+			args: context.args,
 			host: "pi",
 			options: {},
 		};
@@ -394,20 +407,33 @@ export function normalizeResultRenderArgs(result, options, themeOrCtx, ctxOrArgs
 	throw new Error("supernova renderResult: theme missing (expected Pi or OMP signature)");
 }
 
+function operationTarget(item) {
+	const args = item?.args || {};
+	const name = item?.name;
+	if (name === "snap") {
+		const query = args.query ? `"${args.query}"` : "";
+		return args.path ? `${query} → ${args.path}` : query;
+	}
+	if (name === "search") return args.query ? `"${args.query}"` : "";
+	if (args.path) return String(args.path);
+	if (item?.diff?.path) return String(item.diff.path);
+	if (args.target && isString(args.target)) return args.target;
+	if (args.command) return String(args.command);
+	if (args.pattern) return String(args.pattern);
+	if (args.query) return String(args.query);
+	return "";
+}
+
+function operationsFromTrace(trace) {
+	if (!Array.isArray(trace)) return [];
+	return trace
+		.map((item) => displayOperation(item?.name || "tool", operationTarget(item), item?.diff, item?.ok))
+		.filter(Boolean);
+}
+
 function collectCallOps(args, context) {
-	const stateTrace = context?.state?.trace;
-	if (Array.isArray(stateTrace) && stateTrace.length > 0) {
-		return stateTrace
-			.map((item) => {
-				const tool = item?.name || "tool";
-				let target = "";
-				if (item?.args?.path) target = String(item.args.path);
-				else if (item?.args?.command) target = String(item.args.command);
-				else if (item?.args?.pattern) target = String(item.args.pattern);
-				return displayOperation(tool, target);
-			})
-			.filter(Boolean);
-	}
+	const traced = operationsFromTrace(context?.state?.trace);
+	if (traced.length > 0) return traced;
 	return extractOperationsFromCode(args?.code)
 		.map((op) => displayOperation(op.tool, op.target))
 		.filter(Boolean);
@@ -438,14 +464,14 @@ function tickCallTimer(context) {
 function formatOpBodyLine(theme, op) {
 	const icon = ACTION_ICONS[op.tool] || "✦ ";
 	const bullet = theme.fg("accent", icon);
-	const toolName = theme.fg("syntaxFunction", op.tool.padEnd(4, " "));
+	const toolName = theme.fg("syntaxFunction", op.tool.padEnd(7, " "));
 	const rawTarget = formatOpTarget(op.target, op.tool);
 	const target = rawTarget ? " " + theme.fg("muted", rawTarget) : "";
 	return `${bullet}${toolName}${target}`;
 }
 
 function shouldUseOmpFrame(host) {
-	return host === "omp" || hasHostFramedBlock();
+	return host === "omp";
 }
 
 /**
@@ -453,10 +479,7 @@ function shouldUseOmpFrame(host) {
  * Pending call has no hourglass on the head row (same as native Write/Edit).
  */
 function renderOmpCallCard(theme, { ops, timeStr, expanded, code }) {
-	const opSummary =
-		ops.length === 0
-			? "composing"
-			: ops.map((op) => op.tool).join(theme.sep?.dot ? ` ${theme.sep.dot} ` : " · ");
+	const opSummary = ops.length === 0 ? "composing" : `${ops.length} call${ops.length === 1 ? "" : "s"}`;
 	const description = timeStr ? `${opSummary} · ${timeStr}` : opSummary;
 	// No pending icon on the framed head row — matches native Write/Edit.
 	const header = novaStatusLine(theme, {
@@ -467,9 +490,9 @@ function renderOmpCallCard(theme, { ops, timeStr, expanded, code }) {
 		const bodyLines = ops.map((op) => formatOpBodyLine(theme, op));
 		if (expanded && code) {
 			bodyLines.push(theme.fg("dim", "── source ──"));
-			for (const line of String(code).trim().split("\n")) {
-				bodyLines.push(theme.fg("toolOutput", line));
-			}
+			const sourceLines = cleanBlockText(code).trim().split("\n");
+			for (const line of sourceLines.slice(0, 24)) bodyLines.push(theme.fg("toolOutput", line));
+			if (sourceLines.length > 24) bodyLines.push(theme.fg("dim", `… ${sourceLines.length - 24} more lines`));
 		}
 		return {
 			header,
@@ -481,18 +504,20 @@ function renderOmpCallCard(theme, { ops, timeStr, expanded, code }) {
 	});
 }
 
-function renderOmpResultCard(theme, { isErr, payload, expanded, bodyText, isPartial, spinnerFrame }) {
+function renderOmpResultCard(theme, { isErr, payload, expanded, bodyText, isPartial, spinnerFrame, opCount = 0 }) {
 	if (isErr) {
-		const errLines = [];
-		if (payload?.error) errLines.push(theme.fg("error", String(payload.error)));
+		const errLines = String(bodyText || "").trim() ? String(bodyText).split("\n") : [];
+		if (payload?.error) errLines.push(theme.fg("error", cleanBlockText(payload.error)));
 		if (expanded && payload?.logs?.length) {
 			errLines.push(theme.fg("dim", "── logs ──"));
-			for (const log of payload.logs) errLines.push(theme.fg("dim", String(log)));
+			for (const log of payload.logs.slice(0, 24)) errLines.push(theme.fg("dim", cleanBlockText(log)));
 		}
+		const wall = payload?.wallMs != null ? `${payload.wallMs}ms` : "";
+		const calls = opCount > 0 ? `${opCount} call${opCount === 1 ? "" : "s"}` : "";
 		const header = novaStatusLine(theme, {
 			icon: "error",
 			title: "nova",
-			description: payload?.error ? String(payload.error).split("\n")[0] : "error",
+			description: [calls, "failed", wall].filter(Boolean).join(" · "),
 		});
 		return novaFramedBlock(theme, (width) => ({
 			header,
@@ -504,11 +529,13 @@ function renderOmpResultCard(theme, { isErr, payload, expanded, bodyText, isPart
 	}
 
 	const wall = payload?.wallMs != null ? `${payload.wallMs}ms` : "";
+	const calls = opCount > 0 ? `${opCount} call${opCount === 1 ? "" : "s"}` : "";
+	const description = [calls, isPartial ? "running" : "", wall].filter(Boolean).join(" · ");
 	const header = novaStatusLine(theme, {
 		icon: isPartial ? "running" : undefined,
 		spinnerFrame,
 		title: "nova",
-		description: wall || undefined,
+		description: description || undefined,
 	});
 	const bodyLines = String(bodyText || "").split("\n");
 	while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
@@ -529,7 +556,6 @@ export function renderSupernovaCall(a, b, c) {
 	const timeStr = formatElapsed(context?.state);
 
 	if (shouldUseOmpFrame(host)) {
-		void ensureOmpChrome();
 		return renderOmpCallCard(theme, {
 			ops,
 			timeStr,
@@ -558,7 +584,7 @@ export function renderSupernovaCall(a, b, c) {
 
 	if (context?.expanded && args?.code) {
 		out += "\n" + theme.fg("dim", "── source ──");
-		out += "\n" + theme.fg("toolOutput", String(args.code).trim());
+		out += "\n" + theme.fg("toolOutput", cleanBlockText(args.code).trim());
 	}
 
 	if (context?.isError) comp.setTone("error");
@@ -569,51 +595,75 @@ export function renderSupernovaCall(a, b, c) {
 	return comp;
 }
 
-function buildResultBody(theme, { payload, context, expanded }) {
+function formatDiffStats(theme, diff) {
+	if (!diff || !isObject(diff)) return "";
+	return " " + theme.fg("toolDiffAdded", `+${diff.added || 0}`) + theme.fg("dim", "/") + theme.fg("toolDiffRemoved", `-${diff.removed || 0}`);
+}
+
+function formatResultOperation(theme, op, isPartial, isError) {
+	const marker = op.ok === false
+		? theme.fg("error", "× ")
+		: isPartial && op.ok !== true
+			? theme.fg("dim", "· ")
+			: isError && op.ok !== true
+				? theme.fg("error", "× ")
+				: theme.fg("success", "✓ ");
+	const tool = theme.fg("syntaxFunction", op.tool.padEnd(7, " "));
+	const targetText = formatOpTarget(op.target, op.tool);
+	const target = targetText ? theme.fg("muted", targetText) : theme.fg("dim", "done");
+	return `${marker}${tool} ${target}${formatDiffStats(theme, op.diff)}`;
+}
+
+function boundedResult(value) {
+	let text;
+	try {
+		text = isString(value) ? value : JSON.stringify(value, null, 2);
+	} catch {
+		text = String(value);
+	}
+	const lines = cleanBlockText(text).split("\n");
+	const clipped = lines.slice(0, 24).join("\n");
+	const suffix = lines.length > 24 ? `\n… ${lines.length - 24} more lines` : "";
+	return (clipped + suffix).slice(0, 4000);
+}
+
+function buildResultBody(theme, { payload, context, args, expanded, isPartial, isError }) {
 	let out = "";
 	const trace = payload?.trace || context?.state?.trace || [];
-	const diffs = trace.filter((t) => t?.diff && isObject(t.diff)).map((t) => t.diff);
+	const tracedOps = operationsFromTrace(trace);
+	const ops = tracedOps.length > 0
+		? tracedOps
+		: extractOperationsFromCode(args?.code).map((op) => displayOperation(op.tool, op.target)).filter(Boolean);
+	const maxOps = expanded ? 12 : 8;
+	for (const op of ops.slice(0, maxOps)) {
+		out += (out ? "\n" : "") + formatResultOperation(theme, op, isPartial, isError);
+	}
+	if (ops.length > maxOps) out += `\n${theme.fg("dim", `… ${ops.length - maxOps} more calls`)}`;
 
-	if (diffs.length > 0) {
-		const maxDiffsShown = expanded ? diffs.length : 2;
-		const shownDiffs = diffs.slice(0, maxDiffsShown);
-		for (const diff of shownDiffs) {
+	if (expanded) {
+		const diffs = ops.filter((op) => op.diff && isObject(op.diff)).map((op) => op.diff);
+		const maxDiffs = 4;
+		if (diffs.length > 0) out += (out ? "\n" : "") + theme.fg("dim", "── changes ──");
+		for (const diff of diffs.slice(0, maxDiffs)) {
 			const box = renderDiffBox(diff, theme, 120);
-			if (box) out += (out ? "\n\n" : "") + box;
-		}
-		if (!expanded && diffs.length > maxDiffsShown) {
-			const remaining = diffs.length - maxDiffsShown;
-			out +=
-				"\n\n" +
-				theme.fg(
-					"dim",
-					`… ${remaining} more file edit${remaining === 1 ? "" : "s"} (press Enter to expand)`,
-				);
+			if (box) out += "\n" + box;
 		}
-	}
+		if (diffs.length > maxDiffs) out += `\n${theme.fg("dim", `… ${diffs.length - maxDiffs} more changed files`)}`;
 
-	if (expanded) {
-		const resVal = payload?.result;
-		if (resVal !== undefined) {
-			let formatted;
-			try {
-				formatted = isString(resVal) ? resVal : JSON.stringify(resVal, null, 2);
-			} catch {
-				formatted = String(resVal);
-			}
+		if (payload?.result !== undefined) {
 			out += (out ? "\n" : "") + theme.fg("dim", "── result ──");
-			out += "\n" + theme.fg("toolOutput", formatted);
+			out += "\n" + theme.fg("toolOutput", boundedResult(payload.result));
 		}
-		if (payload?.logs?.length) {
+		if (!isError && payload?.logs?.length) {
 			out += (out ? "\n" : "") + theme.fg("dim", "── logs ──");
-			for (const log of payload.logs) out += `\n  ${theme.fg("dim", String(log))}`;
+			for (const log of payload.logs.slice(0, 24)) out += `\n  ${theme.fg("dim", cleanBlockText(log))}`;
 		}
 	}
-	return out;
+	return { body: out, opCount: ops.length };
 }
 
 export function renderSupernovaResult(resultArg, optionsArg, themeArg, contextArg) {
-	const { result, expanded, isPartial, theme, context, options, host } = normalizeResultRenderArgs(
+	const { result, expanded, isPartial, theme, context, args, options, host } = normalizeResultRenderArgs(
 		resultArg,
 		optionsArg,
 		themeArg,
@@ -639,52 +689,17 @@ export function renderSupernovaResult(resultArg, optionsArg, themeArg, contextAr
 	}
 
 	const isErr = result?.isError || payload?.ok === false;
-	const useOmp = shouldUseOmpFrame(host);
-
-	if (useOmp) {
-		void ensureOmpChrome();
-		if (isPartial && !isErr) {
-			// Streaming partials stay quiet until body content exists — same as Pi.
-			const partialBody = buildResultBody(theme, { payload, context, expanded });
-			if (!partialBody.trim()) {
-				return {
-					render: () => [],
-					invalidate() {},
-				};
-			}
-			return renderOmpResultCard(theme, {
-				isErr: false,
-				payload,
-				expanded,
-				bodyText: partialBody,
-				isPartial: true,
-				spinnerFrame: options?.spinnerFrame,
-			});
-		}
-		if (isErr) {
-			return renderOmpResultCard(theme, {
-				isErr: true,
-				payload,
-				expanded,
-				bodyText: "",
-				isPartial: false,
-				spinnerFrame: options?.spinnerFrame,
-			});
-		}
-		const out = buildResultBody(theme, { payload, context, expanded });
-		if (!out.trim()) {
-			return {
-				render: () => [],
-				invalidate() {},
-			};
-		}
+	const view = buildResultBody(theme, { payload, context, args, expanded, isPartial, isError: isErr });
+
+	if (shouldUseOmpFrame(host)) {
 		return renderOmpResultCard(theme, {
-			isErr: false,
+			isErr,
 			payload,
 			expanded,
-			bodyText: out,
-			isPartial: false,
+			bodyText: view.body,
+			isPartial: isPartial && !isErr,
 			spinnerFrame: options?.spinnerFrame,
+			opCount: view.opCount,
 		});
 	}
 
@@ -692,32 +707,22 @@ export function renderSupernovaResult(resultArg, optionsArg, themeArg, contextAr
 	if (options) options.lastComponent = comp;
 	else if (context) context.lastComponent = comp;
 
-	if (isPartial) {
-		comp.setText("");
-		return comp;
-	}
+	const wall = payload?.wallMs != null ? `${payload.wallMs}ms` : "";
+	const calls = view.opCount > 0 ? `${view.opCount} call${view.opCount === 1 ? "" : "s"}` : "complete";
+	let out = theme.fg("toolTitle", theme.bold("nova"));
+	out += " " + theme.fg("dim", `· ${[calls, isErr ? "failed" : isPartial ? "running" : "", wall].filter(Boolean).join(" · ")}`);
+	if (view.body) out += `\n  ${view.body.replaceAll("\n", "\n  ")}`;
 
 	if (isErr) {
-		let out = theme.fg("error", "✗ error");
-		if (payload?.error) {
-			out += `\n  ${theme.fg("error", String(payload.error))}`;
-		}
+		out += `\n  ${theme.fg("error", payload?.error ? cleanBlockText(payload.error) : "error")}`;
 		if (expanded && payload?.logs?.length) {
 			out += `\n${theme.fg("dim", "── logs ──")}`;
-			for (const log of payload.logs) out += `\n  ${theme.fg("dim", String(log))}`;
+			for (const log of payload.logs.slice(0, 24)) out += `\n  ${theme.fg("dim", cleanBlockText(log))}`;
 		}
 		comp.setTone("error");
-		comp.setFraming(true);
-		comp.setText(out);
-		return comp;
-	}
-
-	const out = buildResultBody(theme, { payload, context, expanded });
-	if (!out.trim()) {
-		comp.setText("");
-		return comp;
+	} else {
+		comp.setTone(isPartial ? "pending" : "success");
 	}
-	comp.setTone("success");
 	comp.setFraming(true);
 	comp.setText(out);
 	return comp;

package/runtime.js

@@ -59,23 +59,32 @@ export async function runGuestProgram(options) {
 
   let compiled = compiledCache.get(body);
   if (!compiled) {
-    compiled = new AsyncFunction(
-      "nova",
-      "tools",
-      "console",
-      "parallel",
-      "pipeline",
-      "read",
-      "write",
-      "edit",
-      "patch",
-      "surface",
-      "snap",
-      "bash",
-      "exec",
-      "speculate",
-      body,
-    );
+    try {
+      compiled = new AsyncFunction(
+        "nova",
+        "tools",
+        "console",
+        "parallel",
+        "pipeline",
+        "read",
+        "write",
+        "edit",
+        "patch",
+        "surface",
+        "snap",
+        "bash",
+        "exec",
+        "speculate",
+        body,
+      );
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+        logs,
+        wallMs: Math.round(performance.now() - started),
+      };
+    }
     if (compiledCache.size >= COMPILED_CACHE_MAX) {
       const first = compiledCache.keys().next().value;
       if (first !== undefined) compiledCache.delete(first);
@@ -108,6 +117,16 @@ export async function runGuestProgram(options) {
     return res;
   };
 
+  const unwrapJsonValue = (res) => {
+    const value = unwrapValue(res);
+    if (!isString(value)) return value;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  };
+
   const guestRead = async (p, off, lim) => {
     if (Array.isArray(p)) {
       return await Promise.all(p.map((item) => guestRead(item, off, lim)));
@@ -123,11 +142,11 @@ export async function runGuestProgram(options) {
   const guestPatch = async (p, d) => unwrapValue(await nova.call("apply_patch", { path: p, patch: d }));
   const guestSurface = async (p) => {
     const res = await (isFunction(nova.surface) ? nova.surface(p) : nova.call("surface", { path: p }));
-    return unwrapValue(res);
+    return unwrapJsonValue(res);
   };
   const guestSnap = async (q, p) => {
     const res = await (isFunction(nova.snap) ? nova.snap(q, p) : nova.call("snap", { query: q, path: p }));
-    return unwrapValue(res);
+    return unwrapJsonValue(res);
   };
   const guestBash = async (cmd, opts) => {
     const res = await nova.call("bash", { command: cmd, ...opts });

package/snap.js

@@ -94,21 +94,46 @@ function scoreContentDefinitions(content, tokens) {
   return { totalScore: score, bestLine, bestLineScore };
 }
 
-export async function executeSnap({ query, searchDir, vfs, runCommand }) {
+function relativeHasSegment(relativePath, segmentName) {
+  return relativePath.split(path.sep).includes(segmentName);
+}
+
+function relativeHasHiddenSegment(relativePath) {
+  return relativePath.split(path.sep).some((segment) => segment.startsWith(".") && segment.length > 1);
+}
+
+export async function executeSnap({ query, searchDir, includeHidden = false, vfs, runCommand, pendingPaths = [] }) {
   const { tokens, wantsTest, wantsType, wantsDoc } = tokenizeQuery(query);
   if (tokens.length === 0) {
     throw new Error("snap requires at least one searchable concept keyword");
   }
 
   const dir = searchDir || process.cwd();
+  if (path.resolve(dir).split(path.sep).includes(".git")) {
+    throw new Error("snap cannot search Git metadata");
+  }
   let fileList = [];
   try {
-    const res = await runCommand(["rg", "--files", dir], { timeoutMs: 15_000 });
+    const rgArgs = ["rg", "--files"];
+    if (includeHidden) rgArgs.push("--hidden");
+    rgArgs.push("-g", "!.git/**", "-g", "!**/.git/**", dir);
+    const res = await runCommand(rgArgs, { timeoutMs: 15_000 });
     fileList = res.stdout.split("\n").map((f) => f.trim()).filter(Boolean);
   } catch {
     fileList = [];
   }
 
+  const seenPaths = new Set(fileList.map((filePath) => path.resolve(filePath)));
+  for (const pendingPath of pendingPaths) {
+    const absolutePath = path.resolve(pendingPath);
+    const relativePath = path.relative(path.resolve(dir), absolutePath);
+    const escapesDir = relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
+    const hiddenRelativePath = relativeHasHiddenSegment(relativePath);
+    if (escapesDir || relativeHasSegment(relativePath, ".git") || (!includeHidden && hiddenRelativePath) || seenPaths.has(absolutePath)) continue;
+    seenPaths.add(absolutePath);
+    fileList.push(absolutePath);
+  }
+
   if (fileList.length === 0) {
     throw new Error(`no files found to search in ${dir}`);
   }
@@ -125,7 +150,8 @@ export async function executeSnap({ query, searchDir, vfs, runCommand }) {
 
   if (candidates.length < 5) {
     try {
-      const grepArgs = ["-l", "--max-count=1"];
+      const grepArgs = ["-l", "--max-count=1", "-g", "!.git/**", "-g", "!**/.git/**"];
+      if (includeHidden) grepArgs.push("--hidden");
       if (!wantsTest) {
         grepArgs.push("-g", "!test/**", "-g", "!tests/**", "-g", "!*.test.*", "-g", "!*.spec.*");
       }