pi-supernova 0.9.1 → 0.10.1

package/src/bridge/host-bridge.js

@@ -1,3 +1,4 @@
+import { createBackgroundTerminals } from "../fs/background.js";
 import {createToolRegistry} from './tool-registry.js';
 import {traceArgs,finishRecord} from './trace.js';
 import * as fs from "node:fs/promises";
@@ -16,20 +17,23 @@ import { resolveWorkspacePath, runCommand, clearPathCache, relativeSlash } from
 import { createNativeAdapters } from "../adapters/index.js";
 import { resultDiff, boundedWriteDiff, writeSnapshot } from "../fs/text-ops.js";
 
-export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedger, budget }) {
+export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedger, budget, terminalIdentity }) {
   const index = registry?.index ?? new WorkspaceIndex((argv, opts) => runCommand(argv, opts));
   const ledger = runLedger ?? new SeenLedger({ window: config.seenWindow ?? 0 });
 
   const vfs = new CausalVfs(paths => {
     index.invalidate();
     notifyWorkspaceChanged(paths);
-  }, target => resolveWorkspacePath(getCwd(), target, "commit", false, true));
+  }, target => resolveWorkspacePath(getCwd(), target, "commit", false, true), assertSession);
 
   const executors = registry?.executors ?? new Map();
   const definitions = registry?.definitions ?? new Map();
   const sharedRegistry = registry ?? { executors, definitions, index, callSeq: 0 };
+  sharedRegistry.terminals ??= createBackgroundTerminals();
   let closed = false;
-  const hooks = {};
+  const hooks = { terminals: sharedRegistry.terminals, terminalGeneration: terminalIdentity?.generation ?? sharedRegistry.terminals.getGeneration() };
+  const ownerOf = ctx => JSON.stringify([ctx?.sessionManager?.getSessionId?.() ?? null, path.resolve(getCwd())]);
+  let terminalOwner = terminalIdentity?.owner ?? ownerOf(null);
   const natives = createNativeAdapters(getCwd, vfs, config, index, ledger, hooks);
   let callCount = 0;
   let activeCtx = null;
@@ -51,9 +55,16 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     try { pi.events.emit("workspace:changed", event)?.catch?.(() => {}); } catch {}
   }
 
+  hooks.terminalOwner = () => terminalOwner;
   hooks.workspaceChanged = notifyWorkspaceChanged;
-  hooks.artifactsDir = () => activeCtx?.sessionManager?.getArtifactsDir?.();
+  hooks.artifactsDir = () => {
+    assertSession();
+
+    return activeCtx?.sessionManager?.getArtifactsDir?.();
+  };
+
   hooks.commandEnv = () => {
+    assertSession();
     const env = { ...process.env };
 
     const current = {
@@ -77,6 +88,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
 
   function bindCallContext(ctx, signal) {
     activeCtx = ctx || null;
+    terminalOwner = terminalIdentity?.owner ?? ownerOf(ctx);
     tools.bindSession(ctx);
     activeSignal = signal;
     vfs.signal = signal;
@@ -100,8 +112,15 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     } catch {}
   }
 
+  function assertSession() {
+    if (hooks.terminalGeneration !== sharedRegistry.terminals.getGeneration() || terminalOwner !== ownerOf(activeCtx)) {
+      throw new Error("host session changed; start a new call");
+    }
+  }
+
   function assertRunOpen(name) {
     if (closed) throw new Error("program is already complete");
+    assertSession();
 
     if (activeSignal?.aborted) throw new Error("aborted");
 
@@ -149,7 +168,10 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
   }
 
   function assertOwnedOverride(name, args) {
+    if (name === "bash" && (args?.background === true || args?.action !== undefined)) throw new Error("background terminals require the Supernova-owned bash adapter, not an external override");
+
     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");
   }
 
@@ -159,8 +181,11 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     const mutating = isMutatingTool(name, config, args, definitions.get(name));
 
     if (mutating) await vfs.prepareExternalMutation(name);
+
     if (activeSignal?.aborted || closed) throw new Error("aborted");
+
     if (!isCallable(name)) throw new Error("tool is no longer enabled in this session: " + name);
+    assertSession();
 
     try {
       const res = await target.exec(`supernova:${name}:${callId}`, args || {}, activeSignal, undefined, target.delegated
@@ -176,6 +201,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
   }
 
   async function invokeNative(target, args, record, onItem) {
+    assertSession();
     const res = await target.native(target.argvOwned ? { ...args, args: args.args.map(String) } : args || {}, activeSignal, onItem);
     completeRecord(record, res);
 
@@ -207,6 +233,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
       const target = resolveInvokeTarget(name, args, { hostTool, hostSession: tools.session, executors, natives });
 
       if (target.kind === "override") return await invokeOverride(target, name, args, record, callId);
+
       if (target.kind === "native") return await invokeNative(target, args, record, onItem);
 
       throw new Error(unknownToolMessage(name, [...executors.keys(), ...Object.keys(natives)]));
@@ -218,11 +245,13 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
 
   function fileMutationKey(name, args) {
     if (!["edit", "write", "apply_patch"].includes(name) || !isString(args?.path)) return;
+
     // Overrides can mutate more than their declared path: keep them global.
     if (hostTool(name) || executors.has(name)) return;
 
     return async () => {
       const target = await resolveWorkspacePath(getCwd(), args.path, name, false, true);
+
       // Share the commit identity, including symlinks and not-yet-created files.
       return (await resolveCommitTarget(target)).target;
     };
@@ -296,8 +325,14 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     fork(options) {
       const runConfig = options.timeoutMs === undefined ? config : { ...config, timeoutMs: Number(options.timeoutMs) };
 
-      return createHostBridge({ pi, config: runConfig, getCwd: options.getCwd, registry: sharedRegistry, ledger: ledger.fork(), budget: options.budget });
+      return createHostBridge({ pi, config: runConfig, getCwd: options.getCwd, registry: sharedRegistry, ledger: ledger.fork(), budget: options.budget, terminalIdentity:options.terminalIdentity });
     },
+    captureTerminalIdentity: (ctx, runCwd) => ({
+      generation:sharedRegistry.terminals.getGeneration(),
+      owner:JSON.stringify([ctx?.sessionManager?.getSessionId?.() ?? null, path.resolve(runCwd)]),
+    }),
+    shutdownTerminals: () => sharedRegistry.terminals.shutdown(),
+    reopenTerminals: () => sharedRegistry.terminals.reopen(),
     close() { closed = true; vfs.closed = true; },
     bindCallContext,
     resetCallBudget,
@@ -305,8 +340,16 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     getMutations: () => ({ ...vfs.mutations }),
     setCallListener: fn => { callListener = isFunction(fn) ? fn : null; },
     barrier: run => scheduler.schedule("write", run, activeSignal),
-    beginSpeculation: () => vfs.begin(),
-    commitSpeculation: async () => await vfs.commit(),
+    beginSpeculation() {
+      assertSession();
+
+      return vfs.begin();
+    },
+    async commitSpeculation() {
+      assertSession();
+
+      return await vfs.commit();
+    },
     rollbackSpeculation: () => vfs.rollback(),
     getOverlayDepth: () => vfs.getOverlayDepth(),
     call,

package/src/bridge/invoke.js

@@ -3,15 +3,18 @@ import { isString } from "../shared/decode.js";
 /** Ordered permission rules. First decisive answer wins. */
 export function toolIsCallable(name, env) {
   if (name === "supernova" || env.excluded.has(name)) return false;
+
   if (env.sessionInvalid()) return false;
+
   if (env.nativeOwned(name)) return true;
+
   if (env.hostSession) return env.evalAllows(name);
 
   return env.listed(name);
 }
 
 function isArgvOwned(name, args) {
-  return name === "bash" && Array.isArray(args?.args) && process.platform !== "win32"
+  return name === "bash" && args?.background !== true && args?.action === undefined && Array.isArray(args?.args)
     && args.args.length === Object.keys(args.args).length && args.args.every(isString);
 }
 
@@ -19,6 +22,7 @@ function hostExecutor(name, env) {
   const delegated = env.hostTool(name);
 
   if (delegated) return { exec: delegated.execute.bind(delegated), delegated };
+
   if (env.hostSession) return { exec: undefined, delegated };
 
   return { exec: env.executors.get(name), delegated };
@@ -29,6 +33,7 @@ export function resolveInvokeTarget(name, args, env) {
   const { exec, delegated } = hostExecutor(name, env);
 
   if (exec && !argvOwned) return { kind: "override", exec, delegated, argvOwned: false };
+
   if (env.natives[name]) return { kind: "native", native: env.natives[name], argvOwned };
 
   return { kind: "unknown" };

package/src/bridge/trace.js

@@ -7,7 +7,7 @@ function traceArgs(args) {
   if (!isObject(args)) return {};
   const out = {};
 
-  for (const key of ["path", "target", "query", "pattern", "command", "cwd", "glob", "action", "op"]) {
+  for (const key of ["path", "target", "query", "pattern", "command", "cwd", "glob", "action", "sessionId", "op"]) {
     const value = args[key];
 
     if (isString(value)) out[key] = truncateChars(value, 240, "trace").text;
@@ -16,7 +16,9 @@ function traceArgs(args) {
   }
 
   if (isString(args.content)) out.content = args.content.length + " chars";
+
   if (Array.isArray(args.edits)) out.edits = args.edits.length + " edits";
+
   if (Array.isArray(args.args)) out.args = args.args.length + " argv";
 
   return out;
@@ -38,4 +40,5 @@ function finishRecord(record, res) {
 
   if (text) record.resultText = truncateChars(text, 4096, "trace").text;
 }
+
 export { traceArgs, finishRecord };

package/src/context/evidence.js

@@ -3,6 +3,7 @@ import {pendingInScope,overlaySearchEntry} from './search-files.js';
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { WorkspaceIndex } from "./repo-index.js";
+import { relativeSlash } from "../fs/workspace.js";
 import { tokenizeQuery, scorePathTopology, stem } from "./query.js";
 
 // Zero-token evidence selection over source code, after Zero-Mem (arXiv:2607.29377).
@@ -148,15 +149,18 @@ function render(spans, picks, fused, opts, root) {
     const lastLine = span.start + text.split("\n").length - 1;
     const truncated = lastLine < span.sourceEnd;
     budget -= text.length;
+
     const rendered = {
-      path: path.relative(root, span.path) || span.path,
+      path: relativeSlash(root, span.path),
       lines: [span.start, lastLine],
       name: span.name,
       kind: span.kind,
       why,
       text,
     };
+
     if (truncated) { rendered.truncated = true; rendered.nextOffset = lastLine+1; }
+
     out.push(rendered);
 
     if (budget <= 0) break;
@@ -206,15 +210,20 @@ function collectSpans(chosenFiles, overlayText, index, maxSpanLines) {
 // its declaration. Keep the matching line in the bounded window, even in long bodies.
 function usageSpans(spans, profile, maxSpanLines) {
   if (profile.answerType !== "usage" || !profile.subjects.length) return spans;
+
   return spans.flatMap(span => {
     for (let i = span.start - 1; i < span.sourceEnd; i++) {
       const words = span.lines.idents[i];
+
       const matched = profile.subjects.some(subject =>
         words.filter(word => word === subject).length > Number(span.lines.defNames[i] === subject.toLowerCase()));
+
       if (!matched) continue;
       const start = Math.max(span.start, i - 1);
+
       return [{ ...span, start, end: Math.min(span.sourceEnd, start + maxSpanLines - 1) }];
     }
+
     return [];
   });
 }

package/src/context/snap.js

@@ -1,6 +1,8 @@
 import {inScope,makeCandidate,contentCandidates,MAX_SEARCH_CHARS} from './snap-search.js';
 import { tokenizeQuery, stem } from "./query.js";
+
 export {tokenizeQuery,scorePathTopology,stem} from './query.js';
+
 import * as path from "node:path";
 
 import * as fs from "node:fs/promises";
@@ -22,13 +24,13 @@ function rankScore(candidate, tokenCount) {
 function location(candidate, root) {
   const context = candidate.context;
 
-  return { path: path.relative(root, candidate.path), line: candidate.line, signature: candidate.signature,
+  return { path: relativeSlash(root, candidate.path), line: candidate.line, signature: candidate.signature,
     context: [...context].sort((a, b) => a[0] - b[0]).map(([line, text]) => (line === candidate.line ? "►" : " ") + line + " " + text) };
 }
 
 async function spanCandidates(filePath, lines, root, overlayText, signal) {
   const staged = overlayText(filePath);
-  const rel = path.relative(root, filePath);
+  const rel = relativeSlash(root, filePath);
   let text = staged;
 
   if (text === undefined) {
@@ -38,10 +40,12 @@ async function spanCandidates(filePath, lines, root, overlayText, signal) {
       const stat = await file.stat();
 
       if (!stat.isFile()) throw new Error("source candidate is not a regular file: " + filePath);
+
       if (stat.size > 512 * 1024) return lines.map(line => ({ path: rel, line, signature: "", context: [] }));
       text = await file.readFile({ encoding: "utf8", signal });
     } finally { await file.close(); }
   }
+
   const spans = WorkspaceIndex.spansOf(WorkspaceIndex.fromText(filePath, text));
 
   return lines.map(line => {
@@ -68,6 +72,7 @@ async function rankedSpanCandidates(ranked, root, overlayText, signal) {
       try { out.push(...await spanCandidates(candidate.path, lines, root, overlayText, signal)); }
       catch { signal?.throwIfAborted(); out.push(location(candidate, root)); }
     }
+
     if (out.length >= MAX_ALTERNATIVES) break;
   }
 
@@ -104,7 +109,9 @@ function listedSnapPaths(listing, dir, includeHidden, focusFile, pendingPaths) {
 
 function filenameEligible(search, filePath, relative, tokens, exact, queryLower) {
   if (search.candidates.has(filePath)) return false;
+
   if (!tokens.some(token => relative.includes(token))) return false;
+
   if (exact && tokens.length > 1 && !relative.includes(queryLower)) return false;
 
   return true;
@@ -174,6 +181,7 @@ async function decideSnapResult(ranked, tokens, empty, candidates, relativeRoot,
 function fuzzySnapMiss(exact, query, paths, pathContext, relativeRoot, empty) {
   const eligible = exact && query.length >= 4 && query.length <= 64;
   const limited = eligible && paths.length > 1024;
+
   const fuzzy = eligible ? rankPaths(query, paths.slice(0, 1024).map(file => relativeSlash(relativeRoot, file)),
     { ...pathContext, maxTypos: 1 }).filter(hit => hit.score > 0).slice(0, MAX_ALTERNATIVES) : [];
 
@@ -209,6 +217,7 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
   signal?.throwIfAborted();
 
   const empty = emptySnap();
+
   const dirStat = await fs.stat(dir).catch(error => {
     if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error;
 

package/src/contract/bash.js

@@ -2,13 +2,10 @@ import { isString, isObject } from "../shared/decode.js";
 
 const ARGV_ERROR = "bash argv requires a command string and an array of string args";
 
-function quoteShellArg(value) {
-  return "'" + String(value).replaceAll("'", "'\\''") + "'";
-}
-
 /** Normalize guest bash(command, opts) / bash({command, args}) into host args. */
 function normalizeArgv(args) {
   if (args.args === undefined) return;
+
   if (!isString(args.command) || !Array.isArray(args.args)) throw new Error(ARGV_ERROR);
 
   for (let i = 0; i < args.args.length; i++) {
@@ -17,30 +14,39 @@ function normalizeArgv(args) {
       throw new Error(`${ARGV_ERROR}; args[${i}] is ${type}; check the supplied data fields and pass each argument as a string`);
     }
   }
+
   args.args = args.args.map((arg, i) => {
     if (arg.includes("\0")) throw new Error(`bash args[${i}] must not contain null bytes`);
+
     return String(arg);
   });
 
-  if (process.platform === "win32") {
-    delete args._directArgv;
-    args.command = [args.command, ...args.args].map(quoteShellArg).join(" ");
-    delete args.args;
-  } else args._directArgv = true;
+  args._directArgv = true;
 }
 
-const BASH_OPTION_KEYS = ["command", "args", "cwd", "timeout", "timeoutMs", "_directArgv"];
+const BASH_OPTION_KEYS = ["command", "args", "cwd", "timeout", "timeoutMs", "_directArgv", "background", "pty"];
 
 /** Unknown options used to be dropped silently: env/maxOutputChars never applied. */
 function assertBashOptions(args) {
   const unknown = Object.keys(args).filter(key => !BASH_OPTION_KEYS.includes(key));
 
-  if (unknown.length) throw new Error("bash does not accept option " + unknown.map(key => JSON.stringify(key)).join(", ") + "; supported options are command, args, cwd, timeout, timeoutMs");
+  if (unknown.length) throw new Error("bash does not accept option " + unknown.map(key => JSON.stringify(key)).join(", ") + "; supported options are command, args, cwd, timeout, timeoutMs, background, pty");
 }
+
 export function normalizeBash(command, opts) {
   const args = isObject(command) ? { ...opts, ...command } : { command, ...opts };
+
+  if (args.action !== undefined || args.sessionId !== undefined) return normalizeTerminalControl(args);
   assertBashOptions(args);
+
+  for (const key of ["background", "pty"]) {
+    if (args[key] !== undefined && args[key] !== true && args[key] !== false) throw new Error(`bash ${key} must be boolean`);
+  }
+
+  if (args.pty !== undefined && args.background !== true) throw new Error("bash pty requires background:true");
+
   if (!isString(args.command) || !args.command.trim()) throw new Error("bash requires a non-empty command string");
+
   if (args.command.includes("\0")) throw new Error("bash command must not contain null bytes");
   normalizeArgv(args);
 
@@ -49,11 +55,37 @@ export function normalizeBash(command, opts) {
   return args;
 }
 
+function normalizeTerminalControl(args) {
+  const fields = {
+    list: ["action"],
+    poll: ["action", "sessionId", "cursor", "waitMs"],
+    write: ["action", "sessionId", "input"],
+    stop: ["action", "sessionId"],
+  };
+
+  if (!Object.hasOwn(fields, args.action)) throw new Error("bash terminal action must be list, poll, write or stop");
+  const unknown = Object.keys(args).filter(key => !fields[args.action].includes(key));
+
+  if (unknown.length) throw new Error(`bash ${args.action} does not accept option ${unknown.join(", ")}`);
+
+  if (args.action !== "list" && (!isString(args.sessionId) || !args.sessionId.trim())) throw new Error("bash terminal action requires sessionId");
+
+  if (args.action === "write" && (!isString(args.input) || args.input.length > 16384)) throw new Error("bash terminal input must be a string of at most 16384 characters");
+
+  if (args.cursor !== undefined && (!Number.isSafeInteger(args.cursor) || args.cursor < 0)) throw new Error("bash terminal cursor must be a non-negative safe integer");
+
+  if (args.waitMs !== undefined && (!Number.isInteger(args.waitMs) || args.waitMs < 0 || args.waitMs > 30000)) throw new Error("bash terminal waitMs must be an integer from 0 to 30000");
+
+  return args;
+}
+
 function normalizeTimeout(args) {
   if (args.timeout !== undefined && args.timeoutMs === undefined) args.timeoutMs = args.timeout * 1000;
+
   // Reject before the host's external-mutation barrier can flush staged files.
   if (args.timeoutMs !== undefined) {
     const timeout = Number(args.timeoutMs);
+
     if (!Number.isFinite(timeout) || timeout <= 0) throw new Error("command timeoutMs must be a positive finite number");
     args.timeoutMs = Math.max(1, Math.min(2_147_483_647, Math.floor(timeout)));
   }

package/src/contract/read.js

@@ -1,5 +1,5 @@
 import { errorMessage, isString, isObject, isNumber, looksLikePath } from "../shared/decode.js";
-import { sessionJsonArgs, validateJsonRead } from "../fs/json-read.js";
+import { foldJsonSelectorAlias, sessionJsonArgs, validateJsonRead } from "../fs/json-read.js";
 
 export const SESSION_URI = /^(?:agent|artifact):\/\//i;
 
@@ -12,6 +12,7 @@ function assertReadOptions(args) {
   const unknown = Object.keys(args).filter(key => !READ_OPTION_KEYS.includes(key));
 
   if (unknown.length === 0) return;
+
   const windowHint = unknown.some(key => key === "start" || key === "end")
     ? " For a line window use read(path, {offset:1, limit:80}): offset is the first line and limit is the line count."
     : "";
@@ -33,11 +34,14 @@ export function gatherReadArgs(p, a, b) {
     return args;
   }
 
-  return isObject(a) && !Array.isArray(a) ? { path: p, ...a } : { path: p, offset: a, limit: b };
+  // Only the string shorthand guesses between a path and a symbol. Explicit
+  // path/target objects and path arrays must not turn missing files into search.
+  return autoResolve(isObject(a) && !Array.isArray(a) ? { path: p, ...a } : { path: p, offset: a, limit: b });
 }
 
 export function assertReadPaths(targetParam) {
   if (!Array.isArray(targetParam)) return;
+
   if (targetParam.length > 64) throw new Error("read accepts at most 64 paths per batch");
 
   for (const item of targetParam) if (!isString(item) || !item.trim()) throw new Error("read paths must be non-empty strings");
@@ -49,6 +53,7 @@ function assertReadFlags(args) {
   }
 
   if (args.about !== undefined && !isString(args.about)) throw new Error("read about must be a string");
+
   if (args.query !== undefined && !isString(args.query)) throw new Error("read query must be a string");
 }
 
@@ -56,32 +61,38 @@ function assertExclusiveRead(args) {
   const focusModes = [args.about !== undefined, args.query !== undefined, args.outline === true].filter(Boolean).length;
 
   if (focusModes > 1 || (args.outline === true && args.evidence === true)) throw new Error("read accepts only one of about, query, outline, or evidence");
+
   if (args.resolve === true && args.complete === true) throw new Error("read accepts either resolve or complete, not both");
+
   if ((focusModes === 1 || args.evidence === true) && args.complete === true) throw new Error("complete:true requires a raw file read, not a source view");
 }
 
 function autoResolve(args) {
   if (!isString(args.path) || args.resolve !== undefined || args.complete === true || args.json !== undefined) return args;
-  if (args.about !== undefined || args.query !== undefined || looksLikePath(args.path) || isSessionUri(args.path)) return args;
+
+  if (args.about !== undefined || args.query !== undefined || args.offset !== undefined || args.limit !== undefined || looksLikePath(args.path) || isSessionUri(args.path)) return args;
 
   return { ...args, resolve: true };
 }
 
-/** Exclusive-mode + JSON + auto-resolve. Same rules for guest and host. */
+/** Preserve explicit intent across guest, host, and coalesced batch normalization. */
 export function normalizeRead(params) {
   if (!isObject(params)) throw new Error("read requires an options object");
-  if (params.path !== undefined && params.target !== undefined && params.path !== params.target) {
+
+  const folded = foldJsonSelectorAlias(params);
+
+  if (folded.path !== undefined && folded.target !== undefined && folded.path !== folded.target) {
     throw new Error("read accepts either path or target, not both");
   }
 
-  const args = sessionJsonArgs({ ...params, path: params.path ?? params.target });
+  const args = sessionJsonArgs({ ...folded, path: folded.path ?? folded.target });
   validateJsonRead(args);
   assertReadOptions(args);
   assertReadFlags(args);
   assertExclusiveRead(args);
   assertReadPaths(args.path);
 
-  return autoResolve(args);
+  return args;
 }
 
 export function needsProbe(params) {
@@ -126,7 +137,7 @@ function classifyEvidence(params, target) {
 }
 
 function classifyBarePath(params, target) {
-  if (params.json === undefined && !looksLikePath(target)) {
+  if (params.resolve === true && params.json === undefined && !looksLikePath(target)) {
     return { kind: "snap", query: isString(params.about) ? params.about : target, scoped: isString(params.about) };
   }
 
@@ -139,9 +150,13 @@ export function classifyRead(params, existing) {
   const target = params.path;
 
   if (isSessionUri(target)) return classifySession(params);
+
   if (params.evidence === true) return classifyEvidence(params, target);
+
   if (isString(params.query)) return { kind: "snap", query: params.query, scoped: Boolean(target && target !== params.query) };
+
   if (params.outline === true) return { kind: "outline" };
+
   if (existing) return classifyExisting(params, existing);
 
   return classifyBarePath(params, target);
@@ -186,5 +201,6 @@ export function decodeReadValue(args, value) {
 
 function jsonReadError(args, error) {
   const target = String(args.path ?? args.target ?? "resource");
+
   return new Error("JSON read failed for " + target + jsonSelectorNote(args) + ": " + errorMessage(error));
 }