pi-supernova 0.6.0 → 0.7.0

package/README.md

@@ -12,6 +12,24 @@ Ordinary JavaScript control flow remains available; the guest command bindings
 are only `read`, `edit`, `write`, and `bash`. Supernova supplies retrieval,
 transactional file operations, batching, bounded results and the grouped nova UI.
 
+## Unreleased
+
+- **`parallel: true` on `programs`:** independent entries run at once (up to 8),
+  keep result order, and do not stop siblings on failure. Sequential is still
+  the default.
+- **JSON `.length`:** `read({path, json:".items.length"})` returns the array
+  length without dumping the array.
+- Prefer `edit` for a file you already read; `write` still replaces the file.
+
+## What is new in 0.7.0
+
+- **Faster batches:** guest workers pipeline their successor, so sequential
+  programs run about twice as fast with no token cost.
+- **Hardened guest:** `process.kill` is sealed out; patch hunks report
+  relocation and ambiguous hunks fail instead of misapplying.
+- **Leaner receipts:** multi-edit output caps at 32 matches with exact totals,
+  write receipts go workspace-relative, evidence/outline reads go compact.
+
 ## What is new in 0.6.0
 
 - **Shared batch input:** supply top-level `data` once; each program gets an
@@ -43,12 +61,12 @@ pi install /path/to/pi-stack/packages/pi-supernova
 
 Git pushes do not update npm installations. Publish the new npm version first;
 then reinstall it in the host. Reinstall explicitly when an existing version
-range excludes the new minor version (`^0.5.0` excludes `0.6.0`). After 0.6.0 is
+range excludes the new minor version (`^0.6.0` excludes `0.7.0`). After 0.7.0 is
 published, pin that release with:
 
 ```bash
-pi install npm:pi-supernova@0.6.0
-omp install npm:pi-supernova@0.6.0
+pi install npm:pi-supernova@0.7.0
+omp install npm:pi-supernova@0.7.0
 ```
 
 In Pi, `pi list` shows the configured package sources. A local path uses that
@@ -268,6 +286,12 @@ results/images: isError and details.ok identify failure, details.programs contai
 every attempted result, and details.attempted/total identifies unstarted work.
 Single code/file invocations retain their existing throwing behavior.
 
+Set `parallel: true` with `programs` to run independent entries concurrently
+(up to 8 at once). Each still gets a fresh guest and its own commit; results stay
+in submission order. A failed entry does not stop siblings. Two entries writing
+the same file race: the losing commit reports a conflict. Sequential remains the
+default. `parallel` is invalid on a lone `code` or `file` call.
+
 The outer deadline, host-call budget, log allowance, text budget and image limits
 are shared across the batch. Individual read budgets are not reduced. Every
 attempted program's original text is returned in length-delimited blocks; ordinary

package/docs/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## Unreleased
+
+## [0.7.0] - 2026-09-17
+
+### Internals
+
+- Shared `src/contract/` for read/edit/bash shapes. Guest and host classify once;
+  guest no longer reimplements exclusive-mode routing before RPC.
+- Read dispatch is `classifyRead` → kind table. Disk vs staged `about` focus share
+  one `focusAbout` helper.
+- Invoke permission/target resolution lives in `bridge/invoke.js`.
+- Native adapters live in `src/adapters/{read,write,edit,bash,list}.js`;
+  `createNativeAdapters` is a 30-line assembler. The host kernel stays in
+  `host-bridge.js`.
+- Line/edit helpers in `fs/text-ops.js`. Unused catalog search/describe APIs and
+  the unused native-tool registrar are gone.
+- Per-function cyclomatic complexity is under 10: guest lifecycle is `GuestRun`,
+  program batches are `ProgramBatch`, snap ranking/read/edit/bash/VFS/evidence/
+  output/UI are extracted helpers and classify tables. Same public behavior;
+  BIND DAG unchanged.
+- Guest isolate: no `fs` / `child_process` / `import` / `require`. After `read()`
+  of a path, `write()` of that path throws (use `edit`, or `replace:true`).
+  Raw reads of large source require `about` / offset or `complete:true`;
+  large JSON returns a shape routing value (top-level keys, or length for
+  arrays) instead of throwing.
+- Standing reference stays one nova invocation: prefer `edit` after `read`,
+  `json`/about/`complete:true` for large files, no guest `fs`, and
+  `programs`/`parallel:true` for independent work *inside* one call. Overlapping
+  sibling `supernova` calls still hint that independent work belongs in one
+  program.
+
+### Added
+
+- `parallel: true` on `programs`: independent entries run concurrently (up to 8
+  lanes) in fresh guests, results keep submission order, and a failed entry does
+  not stop siblings. Two entries writing the same file race; the losing commit
+  reports a conflict. Sequential batches still stop on the first failure.
+  `parallel` is rejected on a lone `code` or `file` call.
+- JSON selectors accept array `.length` (for example `.items.length`) so a
+  catalog count does not require dumping the array. String `.length` is still
+  rejected; this is not jq.
+- Raw reads of JSON above the bound return a shape routing value instead of
+  throwing: `{status:"too_large", path, chars, keys}` for objects (`length`
+  for top-level arrays), so the same program can project with `json:".field"`
+  and array reads survive one oversize member. Malformed JSON still throws;
+  non-JSON text still returns verbatim.
+
+### Changed
+
+- Prefer `edit` for a file already read; `write` remains replace-the-file.
+- Overlapping sibling `supernova` calls hint to batch independent work as
+  `programs` with `parallel:true`.
+- Empty programs (no adapter calls) still draw a nova card with a result preview
+  instead of a one-line `complete` status.
+- Shorter standing tool reference: 68 fewer tokens per request with the same
+  commands and surface needles. Wording compression plus dropped peripheral
+  clauses; the JSON/about signatures, prefer-edit rule, and batching nudge
+  stay. Ablation family verified live over 12 green gpt-6-astra runs.
+- Standing tool reference trimmed by 120 more tokens per request (o200k_base),
+  below the previous release baseline: limits and failure patterns already
+  taught by engine errors are no longer repeated proactively, and the batching
+  nudge, guest-confinement rule, and checkpoint clause are compressed. All
+  surface needles, the prefer-edit rule, and the oversize-JSON routing line
+  stay. Live-verified over 2 green gpt-6-astra runs against 2 task-matched
+  controls with no strategy change.
+- An acquired guest worker pipelines its successor while the run executes, so
+  back-to-back programs share construction cost: sequential batches run ~2x
+  faster (22.4ms to 10.5ms per realistic program). Isolated cold starts are
+  unchanged apart from the deferred successor spawn.
+- Multi-edit receipts render the first 32 matches with exact totals and an
+  `…N more matches` note instead of unbounded lines.
+- Write receipts report workspace-relative paths, matching `edited <rel>`.
+- Evidence and outline reads return compact JSON instead of pretty-printed.
+- Refused bridge calls (unknown or excluded tools) no longer consume the host
+  call budget; routing validation runs before charging.
+- The VFS body cache is gone: every read hits disk or its overlay, and CAS
+  baselines are the only retained per-file state.
+
+### Fixed
+
+- `bash({command, args}, opts)` no longer drops the second options argument:
+  `cwd` (and `timeoutMs`) merge in, with the params object's own keys winning
+  on conflict. Covered by argv-form tests.
+- Over-budget JSON selections return an in-band routing value
+  (`{status:"too_large", path, selector, chars}` with `keys` or `length`)
+  instead of throwing, so one oversize field no longer kills the read and
+  small sibling selections flow through. The standing reference line covers
+  raw and selection routing at the same token cost; live-verified over 3
+  green runs (top-level keys now answer in 1 call instead of 2).
+- Memory-limit failures now report the RSS growth, the in-flight operation,
+  host-call count, and tracked host bytes (index entries, overlays),
+  splitting tracked from untracked growth so host-side pressure
+  is distinguishable from tool-side growth.
+- `process.kill` is sealed out of the guest realm: signals are process-wide
+  and could terminate the host. Stop processes with `bash`.
+- Patch hunks that drift report their relocation per hunk, and a hunk whose
+  context matches more than one location fails with a disambiguation error
+  instead of applying at the first candidate.
+- A failed commit keeps CAS baselines for files it never touched, so a later
+  write to a diverged path fails loudly instead of re-capturing unknown
+  bytes as the new truth.
+- The workspace index reuses one scratch read buffer instead of allocating
+  512 KiB per file, bounding transient RSS on large-tree scans.
+
 ## [0.6.0] - 2026-09-15
 
 ### Added

package/docs/TOKEN_COSTS.md

@@ -86,7 +86,7 @@ as the original workload: removing a decision boundary cannot satisfy this gate.
 
 ### Definition and result accounting
 
-The current serialized definition is 631 tokens with o200k_base and 626 with
+The current serialized definition is 602 tokens with o200k_base and 595 with
 cl100k_base, versus 908 and 901 in the frozen non-batched baseline. It retains
 command signatures, complete-read and JSON limits, array-read failure rules,
 transaction boundaries, batch defaults and edit/view guidance on every request.
@@ -117,8 +117,8 @@ this is not a comparison against a hypothetical request that could never run.
 
 | Tokenizer | Repeated-input traffic | Shared-input traffic | Reduction | Arguments before / after | Unchanged result tokens |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| o200k_base | 16,309 | 5,499 | **66.28%** | 6,461 / 1,043 | 2,151 |
-| cl100k_base | 14,649 | 5,197 | **64.52%** | 5,684 / 945 | 2,055 |
+| o200k_base | 16,309 | 5,441 | **66.64%** | 6,461 / 1,043 | 2,151 |
+| cl100k_base | 14,649 | 5,135 | **64.95%** | 5,684 / 945 | 2,055 |
 
 Each arm has one tool invocation followed by the final answer request:
 
@@ -127,8 +127,9 @@ Total = 2*D + 2*A + R
 ~~~
 
 Arguments are charged when generated and when replayed; the complete result is
-charged on handoff. The new standing guidance adds 13 definition tokens per
-request (618 to 631 / 613 to 626), and that cost is included in the after totals.
+charged on handoff. The standing guidance measures 602 definition tokens per
+request with o200k_base (595 with cl100k_base), and that cost is included in
+the after totals.
 There is no source compression, result elision, hidden output or lost decision
 boundary. Programs receive fresh data copies, not a shared mutable heap.
 
@@ -164,6 +165,13 @@ untouched; programs, arguments, failures and decision boundaries are unchanged.
 The shared-input comparison separately requires equal complete result text in
 both arms, after only run-metadata normalization.
 
+Contract v3 reports write receipts relative to the workspace (`wrote rel/path`,
+matching the long-standing `edited <rel>` form) instead of absolute paths. The
+runner strips the frozen `/workspace/` prefix from baseline outputs; the
+historical fixture and its traffic counts stay untouched. Temporary workspace
+prefixes no longer appear in live receipts, so that normalization only applies
+to the frozen baseline side.
+
 The README and these docs ship in the npm tarball. Benchmarks and test fixtures
 remain in the GitHub checkout, so their links above use GitHub URLs.
 

package/index.js

@@ -25,6 +25,7 @@ try {
     Array: (items, opts) => ({ type: "array", items, ...opts }),
     Integer: (opts) => ({ type: "integer", ...opts }),
     Optional: (s) => ({ ...s }),
+    Boolean: (opts) => ({ type: "boolean", ...opts }),
   };
 }
 
@@ -127,8 +128,10 @@ error: ${outcome.error}${logsBlock(outcome)}`;
 function successText(outcome, call) {
   const truncated = outcome.returnTruncated ? " [return truncated]" : "";
   const hint = outcome.undefinedReturn ? " (no return statement; add `return` to get a value)" : "";
+  const m = outcome.mutations;
+  const showMutations = m && (m.committed || m.rolledBack || m.external || m.pendingCommits || m.recoveryFailed) ? mutationText(outcome) : "";
 
-  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}`;
+  return `ok #${call} ${outcome.wallMs}ms${truncated}${showMutations}${splitTurnHint(outcome)}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
 }
 
 function fitOutput(outcome, call, limit, format) {
@@ -200,12 +203,119 @@ export function registerCodeMode(pi) {
       speculateCommit: () => runBridge.barrier(() => runBridge.commitSpeculation()),
       speculateRollback: () => runBridge.barrier(() => runBridge.rollbackSpeculation()),
       names: () => ["read", "edit", "write", "bash"],
+      describeMemory: () => runBridge.describeMemory?.() ?? null,
       batchRead: runBridge.supportsBatchRead(),
       nativeArgv: runBridge.supportsNativeArgv?.() === true,
       cancel,
     };
   }
 
+  function rejectLoneParallel(params) {
+    if (params?.parallel !== undefined) throw new Error("parallel applies to the programs array; no commands ran");
+  }
+
+  function bindRunSignal(signal) {
+    const runController = new AbortController();
+    const abortRun = () => runController.abort(signal?.reason);
+
+    if (signal?.aborted) abortRun();
+    else signal?.addEventListener("abort", abortRun, { once: true });
+
+    return { runController, abortRun };
+  }
+
+  function openRunBridge(ctx, runCwd, budget, runController) {
+    const runBridge = bridge.fork({ getCwd: () => runCwd, budget });
+    runBridge.bindCallContext(ctx, runController.signal);
+    runBridge.resetCallBudget();
+
+    return runBridge;
+  }
+
+  async function runAndCommit(params, runCwd, runBridge, abortRun, runController, budget) {
+    refreshCatalog(runBridge);
+    runBridge.beginSpeculation();
+    const outcome = await runGuestProgram({
+      code: params?.code,
+      file: params?.file,
+      cwd: runCwd,
+      data: params?.data,
+      nova: makeNovaApi(runBridge, abortRun),
+      config: { ...config, maxLogLines: Math.max(0,config.maxLogLines-(budget?.logLines ?? 0)), timeoutMs: params?.timeoutMs === undefined ? config.timeoutMs : Number(params.timeoutMs) },
+      signal: runController.signal,
+      onTimeout: abortRun,
+    });
+    runBridge.close();
+
+    if (outcome.ok) {
+      if (runBridge.getOverlayDepth() !== 1) throw new Error("program ended with an unfinished edit checkpoint; await it before returning");
+      await runBridge.commitSpeculation();
+    }
+    else while (runBridge.getOverlayDepth()) runBridge.rollbackSpeculation();
+
+    return outcome;
+  }
+
+  function scheduleWarm(runController) {
+    cancelWarmTimer();
+
+    if (!stopped && !runController.signal.aborted) {
+      // Deliver the result before paying for another Worker constructor.
+      warmTimer = setImmediate(() => {
+        warmTimer = undefined;
+
+        if (!stopped && !runController.signal.aborted) warmGuestWorker(config).catch(() => {});
+      });
+      warmTimer.unref?.();
+    }
+  }
+
+  function finishRun(runBridge, emitProgress, signal, abortRun, runController) {
+    runBridge.setCallListener(null);
+    emitProgress.flush();
+    signal?.removeEventListener("abort", abortRun);
+    // Prepare one pristine worker during the model's next decision. Never
+    // recycle a worker that has executed arbitrary guest JavaScript.
+    scheduleWarm(runController);
+  }
+
+  function attachReceipts(outcome, trace) {
+    if (outcome.ok && outcome.result === undefined) {
+      const receipts = mutationReceipts(trace);
+
+      if (receipts) {
+        outcome.resultText = receipts;
+        outcome.undefinedReturn = false;
+      }
+    }
+  }
+
+  function throwIfFailed(outcome, visible, response) {
+    if (outcome.ok) return response;
+    const error = new Error(visible);
+    Object.defineProperty(error,"supernovaResult",{value:response});
+    throw error;
+  }
+
+  function packExecuteResult(outcome, call, runBridge, budget, runOpts, peakSeen) {
+    if (budget) budget.logLines += outcome.logs?.length ?? 0;
+    outcome.overlappedTurn = !runOpts?.parallel && peakSeen > 1 ? peakSeen : 0;
+    outcome.mutations = runBridge.getMutations();
+    const trace = runBridge.getTrace();
+    attachReceipts(outcome, trace);
+    const bounded = fitOutput(outcome, call, config.maxReturnChars, outcome.ok ? successText : errorText);
+    const visible = runBridge.ledger.dedupe(bounded, call);
+    const response = result(visible, {
+      ok: outcome.ok, error: outcome.error, wallMs: outcome.wallMs,
+      returnTruncated: outcome.returnTruncated, logTruncated: outcome.logTruncated,
+      logs: outcome.logs, result: outcome.result, trace, mutations: outcome.mutations,
+    });
+
+    if (outcome.images?.length) response.content.push(...outcome.images);
+
+    return throwIfFailed(outcome, visible, response);
+  }
+
   pi.registerTool({
     name: "supernova",
     label: "Supernova",
@@ -221,6 +331,7 @@ export function registerCodeMode(pi) {
         file: Type.Optional(Type.String({ minLength: 1 })),
         data: Type.Optional(Type.Unknown()),
       }, {additionalProperties:false}), {minItems:1,maxItems:32})),
+      parallel: Type.Optional(Type.Boolean()),
     }),
     // One self-owned result frame is shared by Pi and OMP; renderCall stays empty
     // so separate call/result slots cannot duplicate the lifecycle card.
@@ -228,50 +339,26 @@ export function registerCodeMode(pi) {
     mergeCallAndResult: true,
     renderCall: renderSupernovaCall,
     renderResult: renderSupernovaResult,
-    execute: async function execute(_id, params, signal, onUpdate, ctx, budget) {
+    execute: async function execute(_id, params, signal, onUpdate, ctx, budget, runOpts) {
       if (params?.programs !== undefined) return runProgramBatch(_id,params,signal,onUpdate,ctx,config,execute);
+      rejectLoneParallel(params);
       cancelWarmTimer();
       const runCwd = isString(ctx?.cwd) && ctx.cwd ? ctx.cwd : cwd;
-      const runController = new AbortController();
-      const abortRun = () => runController.abort(signal?.reason);
-
-      if (signal?.aborted) abortRun();
-      else signal?.addEventListener("abort", abortRun, { once: true });
-      const runBridge = bridge.fork({ getCwd: () => runCwd, budget });
-      runBridge.bindCallContext(ctx, runController.signal);
-      runBridge.resetCallBudget();
-
+      const { runController, abortRun } = bindRunSignal(signal);
+      const runBridge = openRunBridge(ctx, runCwd, budget, runController);
       const call = ++programSeq;
       runBridge.ledger.beginProgram(call);
       const emitProgress = progressEmitter(onUpdate);
       runBridge.setCallListener((_record, trace) => emitProgress(trace));
       emitProgress([]);
       const started = performance.now();
-      let outcome;
       inFlight += 1;
       overlapPeak = Math.max(overlapPeak, inFlight);
       let peakSeen = overlapPeak;
+      let outcome;
 
       try {
-        refreshCatalog(runBridge);
-        runBridge.beginSpeculation();
-        outcome = await runGuestProgram({
-          code: params?.code,
-          file: params?.file,
-          cwd: runCwd,
-          data: params?.data,
-          nova: makeNovaApi(runBridge, abortRun),
-          config: { ...config, maxLogLines: Math.max(0,config.maxLogLines-(budget?.logLines ?? 0)), timeoutMs: params?.timeoutMs === undefined ? config.timeoutMs : Number(params.timeoutMs) },
-          signal: runController.signal,
-          onTimeout: abortRun,
-        });
-        runBridge.close();
-
-        if (outcome.ok) {
-          if (runBridge.getOverlayDepth() !== 1) throw new Error("program ended with an unfinished edit checkpoint; await it before returning");
-          await runBridge.commitSpeculation();
-        }
-        else while (runBridge.getOverlayDepth()) runBridge.rollbackSpeculation();
+        outcome = await runAndCommit(params, runCwd, runBridge, abortRun, runController, budget);
       } catch (error) {
         abortRun();
         runBridge.close();
@@ -282,56 +369,10 @@ export function registerCodeMode(pi) {
         peakSeen = Math.max(peakSeen, overlapPeak);
         inFlight -= 1;
         if (inFlight === 0) overlapPeak = 0;
-        runBridge.setCallListener(null);
-        emitProgress.flush();
-        signal?.removeEventListener("abort", abortRun);
-        // Prepare one pristine worker during the model's next decision. Never
-        // recycle a worker that has executed arbitrary guest JavaScript.
-        cancelWarmTimer();
-
-        if (!stopped && !runController.signal.aborted) {
-          // Deliver the result before paying for another Worker constructor.
-          warmTimer = setImmediate(() => {
-            warmTimer = undefined;
-
-            if (!stopped && !runController.signal.aborted) warmGuestWorker(config).catch(() => {});
-          });
-          warmTimer.unref?.();
-        }
-      }
-
-      if (budget) budget.logLines += outcome.logs?.length ?? 0;
-      outcome.overlappedTurn = peakSeen > 1 ? peakSeen : 0;
-      outcome.mutations = runBridge.getMutations();
-      const trace = runBridge.getTrace();
-
-      if (outcome.ok && outcome.result === undefined) {
-        const receipts = mutationReceipts(trace);
-
-        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, {
-        ok: outcome.ok, error: outcome.error, wallMs: outcome.wallMs,
-        returnTruncated: outcome.returnTruncated, logTruncated: outcome.logTruncated,
-        logs: outcome.logs, result: outcome.result, trace, mutations: outcome.mutations,
-      });
-
-      if (outcome.images?.length) response.content.push(...outcome.images);
-
-      if (!outcome.ok) {
-        const error = new Error(visible);
-        Object.defineProperty(error,"supernovaResult",{value:response});
-        throw error;
+        finishRun(runBridge, emitProgress, signal, abortRun, runController);
       }
 
-      return response;
+      return packExecuteResult(outcome, call, runBridge, budget, runOpts, peakSeen);
     },
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-supernova",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "CodeMode for Pi and OMP: read, edit, write and bash, with transactional files, source views and shared-input program batches.",
   "type": "module",
   "author": "AdityaVG13",

package/src/adapters/bash.js

@@ -0,0 +1,73 @@
+import { isString } from "../shared/decode.js";
+import { unwrapIfFullyQuoted } from "../fs/text-ops.js";
+import { sourceForReferences } from "../fs/source-window.js";
+import { resolveWorkspacePath, runCommand, clearPathCache } from "../fs/workspace.js";
+
+export function createBash(ctx) {
+  const { getCwd, vfs, config, index, ledger, hooks } = ctx;
+  function combineBashText(stdout, stderr) {
+    return stdout && stderr ? stdout + (stdout.endsWith("\n") ? "" : "\n") + stderr : stdout || stderr;
+  }
+
+  function isLiteralArgv(params) {
+    return Array.isArray(params?.args) && process.platform !== "win32" && params.args.length === Object.keys(params.args).length && params.args.every(isString);
+  }
+
+  function bashCommand(params, literal) {
+    if (params?.command !== undefined && !isString(params.command)) throw new Error("bash command must be a string");
+    if (literal && (!isString(params.command) || 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());
+
+    if (!command.trim()) throw new Error("bash requires command");
+
+    return command;
+  }
+
+  function parseBash(params) {
+    const literal = isLiteralArgv(params);
+    const command = bashCommand(params, literal);
+
+    return { literal, command, argv: literal ? [command, ...params.args] : ["bash", "-c", command] };
+  }
+
+  async function bash(params, signal) {
+      const cwd = getCwd();
+      const { literal, command, argv } = parseBash(params);
+      const targetCwd = params?.cwd ? await resolveWorkspacePath(cwd, params.cwd, "bash cwd", true) : cwd;
+
+      const transactionBarrier = await vfs.prepareExternalMutation("bash");
+      let res;
+
+      try {
+        res = await runCommand(argv, {
+          cwd: targetCwd,
+          env: hooks.commandEnv(),
+          commandLabel: literal ? command : undefined,
+          timeoutMs: params?.timeoutMs,
+          signal,
+          maxOutputChars: config.maxCallResultChars,
+        });
+      } catch (error) {
+        if (!signal?.aborted) error.message += await sourceForReferences(cwd, targetCwd, error.message, signal, ledger);
+        throw error;
+      } finally {
+        vfs.invalidateObserved();
+        index.invalidate();
+        clearPathCache();
+        hooks.workspaceChanged();
+      }
+
+      const { stdout, stderr } = res;
+      let text = combineBashText(stdout, stderr);
+
+      if (res.exitCode !== 0) text += await sourceForReferences(cwd, targetCwd, text, signal, ledger);
+
+      return {
+        content: [{ type: "text", text }],
+        details: { exitCode: res.exitCode, signal: res.signal, outputTruncated: res.outputTruncated, transactionBarrier },
+        isError: res.exitCode !== 0,
+      };
+  }
+
+  return { bash };
+}