pi-supernova 0.9.1 → 0.10.0

package/src/fs/background.js

@@ -0,0 +1,304 @@
+import { spawnCommand, commandSpawnError } from "./workspace.js";
+import { retireProcessTree } from "./process-tree.js";
+import { randomUUID } from "node:crypto";
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+
+const MAX_RUNNING = 8;
+
+const MAX_RETAINED = 32;
+
+const OUTPUT_CHARS = 65536;
+
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+
+function terminalArgv(argv) {
+  // The PTY child is a process-group leader. Capture that identity before exec,
+  // then close the control FD so commands cannot hold it open or forge messages.
+  const command = ["/bin/sh", "-c", 'printf "group:%s\\n" "$$" >&3; /bin/stty cols 80 rows 24 || exit; exec "$@" 3>&-', "supernova-command", ...argv];
+
+  // Node uses socketpairs for stdio; macOS script needs a real input pipe.
+  // Report script's exit separately from the feeder, which may still await input.
+  if (process.platform === "darwin") return ["/bin/sh", "-c", '/bin/cat | { "$@"; code=$?; printf "exit:%s\\n" "$code" >&3; }', "supernova-pty", "/usr/bin/script", "-q", "-F", "/dev/null", ...command];
+  const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+
+  return ["/usr/bin/script", "-q", "-e", "-f", "-c", "exec " + command.map(quote).join(" "), "/dev/null"];
+}
+
+function notifyChanged(job) {
+  // Advisory invalidation must not prevent resource cleanup or escape an event.
+  try { job.changed?.(); } catch {}
+
+  if (job.cleaned) job.changed = undefined;
+}
+
+function wake(job) {
+  for (const notify of job.waiters) notify();
+}
+
+function appendOutput(job, chunk) {
+  job.total += chunk.length;
+  job.output = (job.output + chunk).slice(-OUTPUT_CHARS);
+  wake(job);
+}
+
+function snapshot(job, cursor = 0) {
+  if (cursor > job.total) throw new Error("terminal cursor is beyond available output");
+  const start = job.total - job.output.length;
+  const outputStart = Math.max(start, cursor);
+
+  const result = {
+    sessionId:job.id, pid:job.child.pid, status:job.status, pty:job.pty,
+    exitCode:job.exitCode, signal:job.signal, outputStart, cursor:job.total,
+    truncated:cursor < start, output:job.output.slice(outputStart-start),
+  };
+
+  if (job.error) result.error = job.error;
+
+  return result;
+}
+
+function waitForChange(job, waitMs, signal) {
+  signal?.throwIfAborted();
+
+  return new Promise((resolve, reject) => {
+    const done = error => {
+      clearTimeout(timer);
+      job.waiters.delete(changed);
+      signal?.removeEventListener("abort", aborted);
+
+      if (error) reject(error); else resolve();
+    };
+
+    const changed = () => done();
+    const aborted = () => done(new Error("terminal poll aborted; job remains running"));
+    const timer = setTimeout(changed, waitMs);
+    job.waiters.add(changed);
+    signal?.addEventListener("abort", aborted, {once:true});
+  });
+}
+
+function sendInput(job, input, signal) {
+  signal?.throwIfAborted();
+
+  if (job.child.stdin.writableLength > OUTPUT_CHARS) throw new Error("terminal input queue is full; wait before writing more");
+
+  return new Promise((resolve, reject) => {
+    const done = error => {
+      signal?.removeEventListener("abort", aborted);
+
+      if (error) reject(error); else resolve();
+    };
+
+    const aborted = () => done(new Error("terminal input aborted; input may have been sent"));
+    signal?.addEventListener("abort", aborted, {once:true});
+    job.child.stdin.write(input, done);
+  });
+}
+
+export function createBackgroundTerminals() {
+  const jobs = new Map();
+  let closed = false;
+  let generation = 0;
+  let closing;
+
+  function lookup(id, owner) {
+    const job = jobs.get(id);
+
+    if (!job || job.owner !== owner) throw new Error("unknown background terminal session: " + id);
+
+    return job;
+  }
+
+  function assertCapacity(expectedGeneration) {
+    if (closed || expectedGeneration !== generation) throw new Error("background terminal session changed or closed; start a new call");
+
+    if ([...jobs.values()].filter(job=>!job.cleaned).length >= MAX_RUNNING) throw new Error("background terminal limit reached (8 running); stop a session first");
+  }
+
+  async function validateStart(params, expectedGeneration = generation) {
+    assertCapacity(expectedGeneration);
+
+    if (params.pty) {
+      if (!["darwin","linux"].includes(process.platform)) throw new Error("PTY background terminals require macOS or Linux; use pty:false for pipes");
+      await access("/usr/bin/script", constants.X_OK).catch(()=>{throw new Error("PTY background terminals require executable /usr/bin/script; use pty:false for pipes");});
+    }
+  }
+
+  async function terminate(job, status) {
+    if (job.stopping) return job.stopping;
+
+    if (job.cleaned) return;
+    job.stopping = (async () => {
+      clearTimeout(job.timer);
+      await retireProcessTree(job);
+      job.cleaned = true;
+      job.error = job.processError;
+      job.status = job.error ? "failed" : status;
+      notifyChanged(job);
+      wake(job);
+    })().catch(error => {
+      job.stopping = null; // A later stop/shutdown must be able to retry cleanup.
+      job.status = "failed";
+      job.error = "terminal cleanup failed: " + error.message;
+      notifyChanged(job);
+      wake(job);
+      throw error;
+    });
+
+    return job.stopping;
+  }
+
+  async function start(argv, options) {
+    const startedGeneration = options.generation ?? generation;
+    await validateStart(options, startedGeneration);
+    options.signal?.throwIfAborted();
+    // Capacity and lifecycle can change while the PTY capability check awaits.
+    assertCapacity(startedGeneration);
+
+    while (jobs.size >= MAX_RETAINED) {
+      const old = [...jobs.values()].find(job=>job.cleaned);
+
+      if (!old) break;
+      jobs.delete(old.id);
+    }
+
+    const command = options.pty ? terminalArgv(argv) : argv;
+
+    const child = spawnCommand(command, {
+      cwd:options.cwd, env:options.pty ? {...options.env,TERM:options.env.TERM || "xterm-256color"} : options.env,
+      stdio:options.pty ? ["pipe","pipe","pipe","pipe"] : ["pipe","pipe","pipe"],
+    });
+
+    const job = {
+      id:randomUUID(), owner:options.owner, child, pty:options.pty === true,
+      status:"running", output:"", total:0, exitCode:null, signal:null,
+      waiters:new Set(), changed:options.changed, groups:new Set(child.pid ? [child.pid] : []), killedGroups:new Set(), cleaned:false,
+    };
+
+    jobs.set(job.id,job);
+    child.stdin.on("error",()=>{}); // EPIPE is delivered to each write callback, never uncaught.
+
+    if (job.pty) {
+      let control = "";
+      child.stdio[3].setEncoding("utf8");
+      child.stdio[3].on("data",chunk=>{
+        control += chunk;
+
+        if (control.length > 128) {
+          job.processError = "invalid PTY control message";
+          void terminate(job,"failed").catch(()=>{});
+
+          return;
+        }
+
+        let newline;
+
+        while ((newline = control.indexOf("\n")) >= 0) {
+          const message = control.slice(0,newline);
+          control = control.slice(newline+1);
+
+          if (/^group:[1-9]\d*$/.test(message)) job.groups.add(Number(message.slice(6)));
+          else if (/^exit:\d+$/.test(message)) {
+            job.commandExitCode = Number(message.slice(5));
+            void terminate(job,"exited").catch(()=>{});
+          } else job.processError = "invalid PTY control message";
+        }
+      });
+      child.stdio[3].on("error",error=>{
+        job.processError = error.message;
+        void terminate(job,"failed").catch(()=>{});
+      });
+    }
+
+    for (const stream of [child.stdout,child.stderr]) {
+      stream.setEncoding("utf8");
+      stream.on("data",chunk=>appendOutput(job,chunk));
+    }
+
+    child.once("exit",(code,signal)=>{
+      job.processExited = true;
+      job.exitCode = job.commandExitCode ?? code;
+      job.signal = job.commandExitCode === undefined ? signal : null;
+      void terminate(job,"exited").catch(()=>{});
+    });
+    child.once("close",(code,signal)=>{
+      job.processClosed = true;
+      job.exitCode = job.commandExitCode ?? code;
+      job.signal = job.commandExitCode === undefined ? signal : null;
+    });
+
+    try {
+      await new Promise((resolve,reject)=>{
+        child.once("spawn",resolve);
+        child.once("error",error=>{const mapped=commandSpawnError(error,command[0]);job.error=mapped.message;reject(mapped);});
+      });
+
+      if (options.signal?.aborted || closed || startedGeneration !== generation) {
+        await terminate(job,"stopped");
+        throw new Error("background terminal start aborted");
+      }
+    } catch (error) {
+      if (!child.pid || job.cleaned) jobs.delete(job.id);
+      throw error;
+    }
+
+    job.timer = setTimeout(()=>{void terminate(job,"timed_out").catch(()=>{});},options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    job.timer.unref?.();
+
+    return snapshot(job);
+  }
+
+  function validateControl(params, owner, expectedGeneration = generation) {
+    if (expectedGeneration !== generation) throw new Error("background terminal session changed; start a new call");
+
+    if (params.action === "list") return;
+    const job = lookup(params.sessionId,owner);
+
+    if (params.action === "write" && (job.status !== "running" || job.stopping)) throw new Error("background terminal is not running");
+
+    if (params.cursor !== undefined && params.cursor > job.total) throw new Error("terminal cursor is beyond available output");
+  }
+
+  async function control(params, owner, signal, expectedGeneration = generation) {
+    validateControl(params,owner,expectedGeneration);
+    signal?.throwIfAborted();
+
+    if (params.action === "list") return [...jobs.values()].flatMap(job=>job.owner === owner ? [snapshot(job,job.total)] : []);
+    const job = lookup(params.sessionId,owner);
+
+    if (params.action === "write") await sendInput(job,params.input,signal);
+    else if (params.action === "stop") await terminate(job,"stopped");
+    else if (job.status === "running" && (params.cursor ?? 0) === job.total && params.waitMs) await waitForChange(job,params.waitMs,signal);
+
+    // Polls, writes and stops can cross a session shutdown while awaiting I/O.
+    // Do not return a result owned by the session that just closed.
+    // Polls, writes and stops can cross a session shutdown while awaiting I/O.
+    // Do not return a result owned by the session that just closed.
+    if (expectedGeneration !== generation) throw new Error("background terminal session changed; start a new call");
+
+    return snapshot(job,params.cursor);
+  }
+
+  function shutdown() {
+    if (closing) return closing;
+    closed = true;
+    generation++;
+    const retiring = [...jobs.values()];
+    closing = Promise.allSettled(retiring.map(job=>terminate(job,"stopped"))).then(results=>{
+      for (const job of retiring) if (job.cleaned) jobs.delete(job.id);
+      const failure = results.find(result=>result.status === "rejected");
+
+      if (failure) throw failure.reason;
+    }).finally(()=>{closing=undefined;});
+
+    return closing;
+  }
+
+  function reopen() {
+    if (closing || [...jobs.values()].some(job=>!job.cleaned)) throw new Error("background terminal session cleanup is incomplete");
+    closed = false;
+  }
+
+  return {start, control, validateStart, validateControl, shutdown, reopen, getGeneration:()=>generation};
+}

package/src/fs/commit.js

@@ -60,7 +60,9 @@ async function writeTemporary(entry, content, stat) {
   } catch (error) {
     // Never leak the temporary name: name the destination and the real cause.
     if (error?.code === "EACCES" || error?.code === "EPERM") throw new Error("permission denied writing " + entry.target + ": the directory or file is not writable");
+
     if (error?.code === "EROFS") throw new Error("cannot write " + entry.target + ": the file system is read-only");
+
     if (error?.code === "ENOSPC") throw new Error("cannot write " + entry.target + ": no space left on device");
 
     throw error;
@@ -130,6 +132,9 @@ async function assertExpectedSignature(vfs, logicalPath, target, stat) {
 
 async function installStaged(vfs, staged) {
   for (const entry of staged) {
+    // Staging and earlier renames await I/O. Recheck before each disk effect;
+    // failCommit restores earlier replacements if ownership changed mid-commit.
+    vfs.assertCurrent?.();
     vfs.signal?.throwIfAborted();
     await fs.rename(entry.temporary, entry.target);
     entry.replaced = true;
@@ -158,4 +163,5 @@ async function failCommit(vfs, staged, error) {
   if (recoveryErrors.length) throw new AggregateError([error, ...recoveryErrors.map(message => new Error(message))], "commit failed: " + error.message + "; recovery failed: " + recoveryErrors.join("; "));
   throw error;
 }
+
 export {assertExpectedSignature,collectMissingAncestors,makeStageEntry,stageReplacement,installStaged,failCommit,cleanupStaged};

package/src/fs/file-io.js

@@ -1,4 +1,5 @@
 import * as fs from 'node:fs/promises';
+import path from 'node:path';
 import {createHash} from 'node:crypto';
 
 function textSignature(text) {
@@ -19,6 +20,7 @@ async function* fileChunks(file, signal, maxBytes = Infinity) {
     signal?.throwIfAborted();
     const { bytesRead } = await file.read(buffer, 0, Math.min(buffer.length, remaining), null);
     signal?.throwIfAborted();
+
     if (!bytesRead) break;
     remaining -= bytesRead;
     // Consumers retaining a chunk must copy it before the next read.
@@ -33,6 +35,7 @@ async function fileSignature(target, signal, observed) {
     const actual = await file.stat();
 
     if (!actual.isFile()) throw new Error("read requires a regular file: " + target);
+
     if (observed && !sameFileVersion(observed, actual)) throw new Error("file changed while reading: " + target);
     const hash = createHash("sha256");
 
@@ -83,10 +86,21 @@ async function readLimitedBytes(file, stat, maxBytes, label, signal, overflow =
   return Buffer.concat(chunks);
 }
 
-function remapReadError(err, target) {
+async function hasFileParent(target) {
+  for (let parent = path.dirname(target); ; parent = path.dirname(parent)) {
+    try { return !(await fs.stat(parent)).isDirectory(); }
+    catch (error) { if (error.code !== "ENOENT" && error.code !== "ENOTDIR") return false; }
+
+    if (parent === path.dirname(parent)) return false;
+  }
+}
+
+async function remapReadError(err, target) {
   if (err.code === "EISDIR") throw new Error("path is a directory, not a file: " + target);
 
-  if (err.code === "ENOTDIR") throw new Error("cannot use path: a parent component of " + target + " is a file, not a directory");
+  // Windows returns ENOENT, not ENOTDIR, for a file used as a parent.
+  if (err.code === "ENOTDIR" || err.code === "ENOENT" && await hasFileParent(target)) throw new Error("cannot use path: a parent component of " + target + " is a file, not a directory");
+
   if (err.code === "EACCES" || err.code === "EPERM") throw new Error("permission denied reading " + target + ": check the file mode (for example bash chmod)");
 
   if (err.code === "ENOENT") {
@@ -97,4 +111,5 @@ function remapReadError(err, target) {
 
   throw err;
 }
+
 export { textSignature, sameFileVersion, fileChunks, fileSignature, sameSignature, tooLargeRead, overlayOrThrow, assertReadableFile, readLimitedBytes, remapReadError };

package/src/fs/process-tree.js

@@ -0,0 +1,92 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+
+const exec = promisify(execFile);
+
+// PTYs and shell job control can create groups distinct from the original
+// leader. Record those groups while ancestry exists, before signalling parents.
+async function descendantGroups(pid) {
+  const { stdout } = await exec("ps", ["-ax", "-o", "pid=,ppid=,pgid="], {timeout:1000, maxBuffer:4*1024*1024});
+  const children = new Map();
+
+  for (const line of stdout.trim().split("\n")) {
+    const [child, parent, group] = line.trim().split(/\s+/).map(Number);
+
+    if (!children.has(parent)) children.set(parent, []);
+    children.get(parent).push({pid:child,group});
+  }
+
+  const found = [];
+  const pending = [...(children.get(pid) ?? [])];
+
+  while (pending.length) {
+    const child = pending.pop();
+
+    if (child.group > 0) found.push(child.group);
+    pending.push(...(children.get(child.pid) ?? []));
+  }
+
+  return found;
+}
+
+function signalGroups(job, signal) {
+  for (const group of job.groups) {
+    // Once SIGKILL was delivered, wait for reaping. Darwin can return EPERM
+    // when signalling a zombie again; newly discovered groups still need a kill.
+    if (signal === "SIGKILL" && job.killedGroups.has(group)) continue;
+
+    try {
+      process.kill(-group, signal);
+
+      if (signal === "SIGKILL") job.killedGroups.add(group);
+    } catch (error) {
+      if (error.code === "EPERM") {
+        // Even signal 0 can encounter that race. Keep ownership until ESRCH;
+        // an inaccessible live group must fail at the deadline, not look gone.
+        job.signalError = `cannot signal process group ${group} with ${signal}: ${error.message}`;
+        continue;
+      }
+
+      if (error.code !== "ESRCH") throw error;
+      job.groups.delete(group);
+    }
+  }
+}
+
+// Both foreground and background commands own their POSIX groups until they
+// disappear, not merely until the leader exits or inherited output pipes close.
+// Callers update processExited/processClosed from the real child events and may
+// add PTY group identities while cleanup awaits. Windows remains best-effort.
+export async function retireProcessTree(job) {
+  let discoveryError;
+
+  if (process.platform === "win32") {
+    if (!job.processExited) await exec("taskkill", ["/pid", String(job.child.pid), "/t", "/f"], {timeout:2000,windowsHide:true});
+  } else {
+    if (!job.processExited) {
+      try { for (const group of await descendantGroups(job.child.pid)) job.groups.add(group); }
+      catch (error) { discoveryError = error; }
+    }
+
+    signalGroups(job, "SIGTERM");
+
+    if (job.groups.size) await delay(150);
+    signalGroups(job, "SIGKILL");
+  }
+
+  const deadline = Date.now() + 1000;
+
+  while (true) {
+    if (process.platform !== "win32") signalGroups(job, 0);
+
+    if (job.processClosed && (process.platform === "win32" || job.groups.size === 0)) break;
+
+    if (Date.now() >= deadline) throw new Error("owned process group or output pipes did not close" + (job.signalError ? ": " + job.signalError : ""));
+
+    if (process.platform !== "win32") signalGroups(job, "SIGKILL");
+    await delay(10);
+  }
+
+  if (discoveryError) throw new Error("descendant discovery failed: " + discoveryError.message);
+}

package/src/fs/read-window.js

@@ -7,67 +7,84 @@ import { fileChunks, remapReadError } from "./file-io.js";
 function advanceLines(bytes, start, remaining) {
   while (remaining > 0) {
     const newline = bytes.indexOf(10, start);
+
     if (newline < 0) return { offset: bytes.length, remaining };
     start = newline + 1;
     remaining--;
   }
+
   return { offset: start, remaining };
 }
 
 async function scanWindow(file, stat, startLine, lineCount, maxBytes, signal) {
   const scan = { parts: [], collected: 0, startByte: undefined, endByte: undefined };
   let skip = startLine - 1, take = lineCount ?? Infinity, position = 0;
+
   for await (const chunk of fileChunks(file, signal, stat.size)) {
     const head = advanceLines(chunk, 0, skip);
     skip = head.remaining;
     const start = position;
     position += chunk.length;
+
     if (skip) continue;
     scan.startByte ??= start + head.offset;
     const tail = advanceLines(chunk, head.offset, take);
     take = tail.remaining;
+
     if (take === 0) scan.endByte = start + tail.offset;
     const end = Math.min(tail.offset, head.offset + maxBytes + 1 - scan.collected);
+
     if (end > head.offset) {
       scan.parts.push(Buffer.from(chunk.subarray(head.offset, end)));
       scan.collected += end - head.offset;
     }
+
     if (take === 0 || scan.collected > maxBytes) break;
   }
+
   return scan;
 }
 
 function overlayWindow(overlay, startLine, lineCount) {
   const window = sliceLinesRawInfo(overlay, startLine, lineCount);
   const satisfied = lineCount === undefined || lineCount === 0 || window.text === "" || window.count >= lineCount || window.eof;
+
   return { text: window.text, satisfied, whole: window.whole };
 }
 
 async function openReadFile(target) {
   try { return await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0)); }
-  catch (error) { remapReadError(error, target); }
+  catch (error) { await remapReadError(error, target); }
 }
 
 export function createWindowReader(vfs) {
   return async function readWindow(target, startLine, lineCount, maxBytes, signal) {
     const overlay = vfs.getOverlay(target);
+
     if (overlay !== undefined) {
       const window = overlayWindow(overlay,startLine,lineCount);
       window.satisfied &&= Buffer.byteLength(window.text,"utf8") <= maxBytes;
+
       return window;
     }
+
     const file = await openReadFile(target);
+
     try {
       const stat = await file.stat();
+
       if (!stat.isFile()) throw new Error("read requires a regular file: " + target);
+
       if (lineCount === 0) return { text: "", satisfied: true, whole: stat.size === 0 };
       const scan = await scanWindow(file, stat, startLine, lineCount, maxBytes, signal);
+
       if (scan.startByte === undefined) return { text: "", satisfied: true, whole: stat.size === 0 };
       const bytes = Buffer.concat(scan.parts, scan.collected);
       const end = scan.startByte + scan.collected;
       const eof = end >= stat.size;
       const text = eof ? decodeUtf8Strict(bytes, target) : decodeUtf8Window(bytes);
       await vfs.recordExpected(target, stat);
+
       return { text, satisfied: end >= scan.endByte || eof, whole: startLine === 1 && scan.startByte === 0 && eof };
     } finally { await file.close(); }
   };

package/src/fs/vfs.js

@@ -1,6 +1,8 @@
 import {textSignature,sameFileVersion,fileSignature,tooLargeRead,overlayOrThrow,assertReadableFile,readLimitedBytes,remapReadError} from './file-io.js';
 import {resolveCommitTarget,assertExpectedSignature,collectMissingAncestors,makeStageEntry,stageReplacement,installStaged,failCommit,cleanupStaged} from './commit.js';
+
 export {resolveCommitTarget} from './commit.js';
+
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isString } from "../shared/decode.js";
@@ -10,8 +12,9 @@ import { decodeUtf8Strict } from "../shared/utf8.js";
 let commitTail = Promise.resolve();
 
 export class CausalVfs {
-  constructor(onNewFile, validateWrite) {
+  constructor(onNewFile, validateWrite, assertCurrent) {
     this.validateWrite = validateWrite;
+    this.assertCurrent = assertCurrent;
     // No body cache: every read hits disk (or its overlay) so observed bytes
     // are never stale. CAS baselines in `expected` are the only retained
     // per-file state, cleared only at external-mutation boundaries.
@@ -24,6 +27,8 @@ export class CausalVfs {
   }
 
   assertWritable() {
+    this.assertCurrent?.();
+
     if (this.closed) throw new Error("program is already complete");
     this.signal?.throwIfAborted();
   }
@@ -55,6 +60,7 @@ export class CausalVfs {
         bytes = maxBytes === undefined
           ? await file.readFile({ signal: this.signal })
           : await readLimitedBytes(file, stat, maxBytes, label, this.signal, () => tooLargeRead(label,maxBytes,target));
+
         if (!sameFileVersion(stat, await file.stat())) throw new Error("file changed while reading: " + target);
       } finally { await file.close(); }
 
@@ -63,7 +69,7 @@ export class CausalVfs {
 
       return strict ? decodeUtf8Strict(bytes, target) : bytes.toString("utf8");
     } catch (err) {
-      remapReadError(err, target);
+      await remapReadError(err, target);
     }
   }
 
@@ -139,6 +145,9 @@ export class CausalVfs {
     let failed = false;
 
     try {
+      // Admission may have preceded another transaction's asynchronous commit.
+      this.assertCurrent?.();
+
       for (const [logicalPath, content] of writes) {
         this.signal?.throwIfAborted();
         const { target, stat } = await resolveCommitTarget(logicalPath);
@@ -193,10 +202,14 @@ export class CausalVfs {
     return { rolledBack: top?.size ?? 0, depth: this.overlays.length };
   }
 
-  async prepareExternalMutation(name) {
+  assertExternalAllowed(name) {
     this.assertWritable();
 
-    if (this.overlays.length > 1) throw new Error(name + " cannot run inside an edit checkpoint because external mutations cannot be rolled back");
+    if (this.overlays.length > 1) throw new Error(name + " cannot run inside an edit checkpoint because external mutations cannot be rolled back; run bash after the checkpoint, or use explicit restoration outside checkpoints for mutation tests");
+  }
+
+  async prepareExternalMutation(name) {
+    this.assertExternalAllowed(name);
 
     if (!this.overlays.length) { this.mutations.external++;