pi-supernova 0.4.0 → 0.6.0

package/src/fs/patch.js

@@ -67,7 +67,9 @@ function findHunkMatch(fileLines, expectedOld, nominal) {
 
   if (!expectedOld.length) return -1;
 
-  for (let delta = 1; delta <= Math.max(fileLines.length, 100); delta++) {
+  const maxDrift = Math.min(Math.max(fileLines.length, 100), 200);
+
+  for (let delta = 1; delta <= maxDrift; delta++) {
     if (matchAt(nominal + delta)) return nominal + delta;
 
     if (matchAt(nominal - delta)) return nominal - delta;
@@ -103,7 +105,7 @@ export function applyPatchToText(originalText, patchText) {
       const line = hunk.lines[i];
 
       if (line[0] === "+") {
-        replacement.push({ text: textOf(line), ending: hunk.noNewline.includes(i) ? "" : line.endsWith("\r") ? "\r\n" : ending });
+        replacement.push({ text: textOf(line), ending: hunk.noNewline.includes(i) ? "" : ending });
       } else {
         const original = fileLines[oldIndex++];
 

package/src/fs/vfs.js

@@ -1,17 +1,73 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isString } from "../shared/decode.js";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 
 const VFS_CACHE_MAX = 1024;
 
+const VFS_CACHE_MAX_BYTES = 64 * 1024 * 1024;
+
 // Serialize validation + replacement across Supernova transactions in this host.
 let commitTail = Promise.resolve();
 
+function textSignature(text) {
+  return { size: Buffer.byteLength(text, "utf8"), sha256: createHash("sha256").update(text, "utf8").digest("hex") };
+}
+
+function sameFileVersion(a, b) {
+  return ["dev", "ino", "size", "mtimeMs", "ctimeMs"].every(key => a[key] === b[key]);
+}
+
+async function fileSignature(target, signal, observed) {
+  const file = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+
+  try {
+    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");
+
+    for await (const chunk of file.createReadStream({ autoClose: false, signal })) hash.update(chunk);
+    const after = await file.stat();
+
+    if (!after.isFile() || !sameFileVersion(actual, after)) throw new Error("file changed while signing: " + target);
+
+    return { size: actual.size, sha256: hash.digest("hex") };
+  } finally {
+    await file.close();
+  }
+}
+
+// realpath() cannot resolve a missing leaf. Canonicalize its nearest existing
+// ancestor so two symlink spellings still share one commit destination.
+async function canonicalNewPath(target) {
+  let ancestor = path.dirname(target);
+
+  for (;;) {
+    try { return path.join(await fs.realpath(ancestor), path.relative(ancestor, target)); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const parent = path.dirname(ancestor);
+
+      if (parent === ancestor) throw error;
+      ancestor = parent;
+    }
+  }
+}
+
+function sameSignature(a, b) {
+  return a === b || (a !== null && b !== null && a.size === b.size && a.sha256 === b.sha256);
+}
+
 export class CausalVfs {
   constructor(onNewFile, validateWrite) {
     this.validateWrite = validateWrite;
+    // Optional receipt bodies, never the authority for CAS. Signatures survive
+    // body eviction. Explicit reads hit disk and replace the observed snapshot;
+    // internal receipt reads preserve it until an external-mutation boundary.
     this.cache = new Map();
+    this.cacheBytes = 0;
     this.overlays = [];
     this.expected = new Map();
     this.onNewFile = onNewFile;
@@ -25,9 +81,31 @@ export class CausalVfs {
     this.signal?.throwIfAborted();
   }
 
+  dropCache(target) {
+    const previous = this.cache.get(target);
+
+    if (previous !== undefined && this.cache.delete(target)) this.cacheBytes -= Buffer.byteLength(previous, "utf8");
+  }
+
   setCache(target, content) {
-    if (this.cache.size >= VFS_CACHE_MAX && !this.cache.has(target)) this.cache.delete(this.cache.keys().next().value);
+    const bytes = Buffer.byteLength(content, "utf8");
+
+    if (bytes > VFS_CACHE_MAX_BYTES) {
+      this.dropCache(target);
+      return;
+    }
+
+    this.dropCache(target);
+
+    while ((this.cache.size >= VFS_CACHE_MAX || this.cacheBytes + bytes > VFS_CACHE_MAX_BYTES) && this.cache.size) {
+      const oldest = this.cache.keys().next().value;
+
+      this.cacheBytes -= Buffer.byteLength(this.cache.get(oldest), "utf8");
+      this.cache.delete(oldest);
+    }
+
     this.cache.set(target, content);
+    this.cacheBytes += bytes;
   }
 
   getOverlay(target) {
@@ -40,28 +118,30 @@ export class CausalVfs {
     return [...new Set(this.overlays.flatMap(overlay => [...overlay.keys()]))];
   }
 
-  async read(target, { preserveRead = false, maxBytes } = {}) {
+  async read(target, { preserveRead = false, maxBytes, label = "read input" } = {}) {
     const overlay = this.getOverlay(target);
 
     if (overlay !== undefined) {
-      if (maxBytes !== undefined && Buffer.byteLength(overlay, "utf8") > maxBytes) throw new Error("JSON input exceeds " + maxBytes + " bytes; use a streaming parser through bash");
+      if (maxBytes !== undefined && Buffer.byteLength(overlay, "utf8") > maxBytes) throw new Error(label + " exceeds " + maxBytes + " bytes; use a streaming parser through bash");
 
       return overlay;
     }
 
     // External editors and captured tools can change a file between any two reads.
+    // Open once with O_NONBLOCK so a FIFO or device cannot park a host I/O worker.
     try {
-      let text;
+      const file = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+      let bytes;
 
-      if (maxBytes === undefined) text = await fs.readFile(target, "utf8");
-      else {
-        const file = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+      try {
+        const stat = await file.stat();
 
-        try {
-          const stat = await file.stat();
+        if (stat.isDirectory()) throw new Error("read path is a directory, not a file: " + target);
+        if (!stat.isFile()) throw new Error("read requires a regular file: " + target);
 
-          if (!stat.isFile()) throw new Error("JSON read requires a regular file: " + target);
-          const tooLarge = () => new Error("JSON input exceeds " + maxBytes + " bytes; use a streaming parser through bash");
+        if (maxBytes === undefined) bytes = await file.readFile({ signal: this.signal });
+        else {
+          const tooLarge = () => new Error(label + " exceeds " + maxBytes + " bytes; use a streaming parser through bash");
 
           if (stat.size > maxBytes) throw tooLarge();
           const chunks = [];
@@ -74,15 +154,19 @@ export class CausalVfs {
             chunks.push(chunk);
           }
 
-          text = Buffer.concat(chunks).toString("utf8");
-        } finally { await file.close(); }
-      }
+          bytes = Buffer.concat(chunks);
+        }
+        if (!sameFileVersion(stat, await file.stat())) throw new Error("file changed while reading: " + target);
+      } finally { await file.close(); }
 
-      if (!preserveRead || !this.cache.has(target)) this.setCache(target, text);
+      // Hash the actual bytes, not a lossy UTF-8 decode/re-encode.
+      if (!preserveRead || !this.expected.has(target)) this.expected.set(target, textSignature(bytes));
+      const text = bytes.toString("utf8");
+      this.setCache(target, text);
 
       return text;
     } catch (err) {
-      this.cache.delete(target);
+      this.dropCache(target);
 
       if (err.code === "EISDIR") throw new Error("read path is a directory, not a file: " + target);
 
@@ -96,6 +180,27 @@ export class CausalVfs {
     }
   }
 
+  async #diskSignature(target) {
+    let stat;
+
+    try { stat = await fs.stat(target); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+
+    return stat?.isFile() ? await fileSignature(target, this.signal, stat) : null;
+  }
+
+  async captureExpected(target) {
+    if (this.getOverlay(target) !== undefined || this.expected.has(target)) return;
+
+    this.expected.set(target, await this.#diskSignature(target));
+  }
+
+  async recordExpected(target, observed) {
+    if (this.getOverlay(target) !== undefined) return;
+    const signature = observed ? await fileSignature(target, this.signal, observed) : await this.#diskSignature(target);
+    this.expected.set(target, signature);
+  }
+
   async write(target, content) {
     this.assertWritable();
 
@@ -109,14 +214,7 @@ export class CausalVfs {
 
     this.assertWritable();
 
-    if (this.getOverlay(target) === undefined) {
-      let original;
-
-      try { original = this.cache.has(target) ? this.cache.get(target) : await fs.readFile(target, "utf8"); }
-      catch (error) { if (error.code !== "ENOENT") throw error; original = null; }
-
-      this.expected.set(target, original);
-    }
+    await this.captureExpected(target);
 
     this.assertWritable();
 
@@ -166,6 +264,7 @@ export class CausalVfs {
           if (!stat.isFile()) throw new Error("cannot write to a non-file: " + logicalPath);
         } catch (err) {
           if (err.code !== "ENOENT") throw err;
+          target = await canonicalNewPath(logicalPath);
         }
 
         await this.validateWrite?.(logicalPath);
@@ -174,9 +273,9 @@ export class CausalVfs {
         targets.add(target);
 
         if (this.expected.has(logicalPath)) {
-          const current = stat ? await fs.readFile(target, "utf8") : null;
+          const current = stat ? await fileSignature(target, this.signal) : null;
 
-          if (current !== this.expected.get(logicalPath)) {
+          if (!sameSignature(current, this.expected.get(logicalPath))) {
             throw new Error("write conflict: file changed since it was read: " + logicalPath + "; read it again before retrying");
           }
         }
@@ -224,10 +323,12 @@ export class CausalVfs {
 
       for (const entry of staged) {
         this.setCache(entry.logicalPath, entry.content);
-        this.expected.delete(entry.logicalPath);
+        this.expected.set(entry.logicalPath, textSignature(entry.content));
       }
 
-      if (staged.length) this.onNewFile?.(staged.map(entry => entry.target));
+      // Canonical commit destinations must not rewrite established event paths
+      // for newly created files, whose callers supplied a logical cwd spelling.
+      if (staged.length) this.onNewFile?.(staged.map(entry => entry.existed ? entry.target : entry.logicalPath));
       this.mutations.committed += staged.length;
     } catch (error) {
       failed = true;
@@ -288,9 +389,8 @@ export class CausalVfs {
     const top = this.overlays.pop();
     this.mutations.rolledBack += top?.size ?? 0;
 
-    for (const target of top?.keys() ?? []) {
-      if (this.getOverlay(target) === undefined) this.expected.delete(target);
-    }
+    // Rolling back staged writes does not undo observations of disk. Keep the
+    // read snapshot, including for files without a surviving parent overlay.
 
     return { rolledBack: top?.size ?? 0, depth: this.overlays.length };
   }
@@ -313,7 +413,7 @@ export class CausalVfs {
     return pending.size > 0;
   }
 
-  invalidateCache() { this.cache.clear(); }
+  invalidateCache() { this.cache.clear(); this.cacheBytes = 0; this.expected.clear(); }
   getCacheSize() { return this.cache.size; }
   getOverlayDepth() { return this.overlays.length; }
 }

package/src/fs/workspace.js

@@ -16,6 +16,9 @@ const realNearest = new Map();
 const PATH_CACHE_MAX = 2048;
 
 export function clearPathCache() {
+  cachedCwd = null;
+  cachedResolvedCwd = null;
+  realRoots.clear();
   realNearest.clear();
 }
 
@@ -64,14 +67,38 @@ export function isTestPath(filePath) {
   return segments.some((s) => TEST_SEGMENTS.has(s)) || /\.(test|spec)\./.test(base);
 }
 
-export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false, fresh = false) {
+/** Reject scheme:// and scheme:/ paths. A single-letter drive (C:/) stays a filesystem path. */
+export function assertFilesystemPath(inputPath, opName, allowSessionRead = false) {
   if (inputPath == null || !isString(inputPath) || !inputPath.trim()) {
     throw new Error(`${opName} requires path`);
   }
 
-  if (/^(?:agent|artifact):\/\//i.test(inputPath.trim())) throw new Error(`${opName} requires a filesystem path; session resource URIs are read-only`);
+  const trimmed = inputPath.trim();
+
+  if (/^(?:agent|artifact):\/\//i.test(trimmed)) {
+    if (allowSessionRead) return trimmed;
+    throw new Error(`${opName} requires a filesystem path; session resource URIs are read-only`);
+  }
+
+  const uri = /^([a-zA-Z][a-zA-Z0-9+.-]*):(.*)$/.exec(trimmed);
+
+  if (uri) {
+    const scheme = uri[1];
+    const rest = uri[2];
+    const windowsDrive = scheme.length === 1 && (rest.startsWith("/") || rest.startsWith("\\"));
+
+    if (!windowsDrive && (rest.startsWith("//") || rest.startsWith("/"))) {
+      throw new Error(`${opName} does not accept ${scheme}: URI paths; use a workspace filesystem path`);
+    }
+  }
+
+  return trimmed;
+}
+
+export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false, fresh = false) {
+  const trimmed = assertFilesystemPath(inputPath, opName);
   const resolvedCwd = getResolvedCwd(cwd);
-  const target = path.resolve(resolvedCwd, inputPath.trim());
+  const target = path.resolve(resolvedCwd, trimmed);
   assertInside(path.relative(resolvedCwd, target), `${opName} path escapes workspace: paths resolve relative to ${resolvedCwd}`);
 
   if (!allowRoot && target === resolvedCwd) {
@@ -102,7 +129,10 @@ export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = f
 export async function runCommand(argv, options = {}) {
   options.signal?.throwIfAborted();
   const cwd = options.cwd || process.cwd();
-  const timeoutMs = options.timeoutMs ?? 60_000;
+  const requestedTimeout = Number(options.timeoutMs === undefined ? 60_000 : options.timeoutMs);
+
+  if (!Number.isFinite(requestedTimeout) || requestedTimeout <= 0) throw new Error("command timeoutMs must be a positive finite number");
+  const timeoutMs = Math.max(1, Math.min(2_147_483_647, Math.floor(requestedTimeout)));
   const maxOutputChars = options.maxOutputChars ?? 2 * 1024 * 1024;
 
   return new Promise((resolve, reject) => {

package/src/output/bottleneck.js

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import { isString, isObject } from "../shared/decode.js";
-import { truncateChars, formatReturn } from "./format.js";
+import { truncateChars, formatReturn, formatBoundedStringArray } from "./format.js";
 
 function json(value) {
   try { return JSON.stringify(value) ?? "null"; } catch { return JSON.stringify(String(value)); }
@@ -19,7 +19,7 @@ function detailsOf(raw) {
 export function hostResultFailed(raw) {
   const details = detailsOf(raw);
 
-  return raw?.isError === true || details?.ok === false || (Number.isInteger(details?.exitCode) && details.exitCode !== 0);
+  return raw?.isError === true || raw?.ok === false || details?.ok === false || (Number.isInteger(details?.exitCode) && details.exitCode !== 0);
 }
 
 function extractRawString(raw) {
@@ -92,12 +92,16 @@ function summarizeDetails(value, budget = 2000) {
 }
 
 function spill(fullText, config) {
-  if (!isString(config.spillDir) || !config.spillDir) return undefined;
-  fs.mkdirSync(config.spillDir, { recursive: true, mode: 0o700 });
-  const file = path.join(config.spillDir, Date.now() + "-" + randomUUID().slice(0, 8) + ".txt");
-  fs.writeFileSync(file, fullText, { encoding: "utf8", mode: 0o600, flag: "wx" });
-
-  return file;
+  try {
+    if (!isString(config.spillDir) || !config.spillDir) return undefined;
+    fs.mkdirSync(config.spillDir, { recursive: true, mode: 0o700 });
+    const file = path.join(config.spillDir, Date.now() + "-" + randomUUID().slice(0, 8) + ".txt");
+    fs.writeFileSync(file, fullText, { encoding: "utf8", mode: 0o600, flag: "wx" });
+
+    return file;
+  } catch {
+    return undefined;
+  }
 }
 
 export function packageHostResult(raw, config) {
@@ -108,7 +112,10 @@ export function packageHostResult(raw, config) {
   const capped = truncateChars(text, maxChars, "host-result");
   let truncated = capped.truncated || details?.outputTruncated === true;
   const image = raw?.content?.find(part => part?.type === "image");
-  const result = { ok: !hostResultFailed(raw), value: image ?? capped.text, truncated };
+  const directoryEntries = image === undefined && details?.directory === true && Array.isArray(details.entries) && json(details.entries).length <= maxChars
+    ? details.entries
+    : undefined;
+  const result = { ok: !hostResultFailed(raw), value: image ?? directoryEntries ?? capped.text, truncated };
 
   if (details !== undefined) result.details = summarizeDetails(batch ? { ...details, items: undefined } : details);
 
@@ -117,7 +124,25 @@ export function packageHostResult(raw, config) {
     let remaining = maxChars;
     result.items = batch.map((item, index) => {
       if (item?.type === "image") return item;
-      const bounded = truncateChars(item, details.independent === true ? maxChars : Math.floor(remaining / (batch.length - index)), "host-result");
+      const share = details.independent === true ? maxChars : Math.floor(remaining / (batch.length - index));
+
+      if (!isString(item)) {
+        const encoded = json(item);
+
+        if (encoded.length <= share) {
+          remaining -= encoded.length;
+
+          return item;
+        }
+
+        const bounded = truncateChars(encoded, share, "host-result");
+        remaining -= bounded.text.length;
+        truncated ||= bounded.truncated;
+
+        return bounded.text;
+      }
+
+      const bounded = truncateChars(item, share, "host-result");
       remaining -= bounded.text.length;
       truncated ||= bounded.truncated;
 
@@ -128,10 +153,10 @@ export function packageHostResult(raw, config) {
   result.truncated = truncated;
 
   if (truncated) {
-    result.originalChars = batch ? batch.reduce((sum, item) => sum + String(item).length, 0) : text.length;
+    result.originalChars = batch ? batch.reduce((sum, item) => sum + (isString(item) ? item.length : json(item).length), 0) : text.length;
 
     if (config.spillDir) {
-      const pointer = spill(batch ? batch.join("\n---\n") : text, config);
+      const pointer = spill(batch ? batch.map(item => isString(item) ? item : json(item)).join("\n---\n") : text, config);
 
       if (pointer) {
         result.spill = pointer;
@@ -152,12 +177,19 @@ export function packageHostResult(raw, config) {
 export function packageFinalReturn(value, logs, config) {
   const images = [];
   let imageBytes = 0;
+  let imageOverflow = false;
 
   const collect = input => {
     if (input?.type === "image" && isString(input.data) && isString(input.mimeType) && input.mimeType.startsWith("image/")) {
-      imageBytes += Buffer.byteLength(input.data, "base64");
+      const size = Buffer.byteLength(input.data, "base64");
+
+      if (images.length >= 16 || imageBytes + size > 20 * 1024 * 1024) {
+        imageOverflow = true;
+
+        return "[image omitted: exceeds 16 attachments or 20 MiB]";
+      }
 
-      if (images.length >= 16 || imageBytes > 20 * 1024 * 1024) throw new Error("returned images exceed 16 attachments or 20 MiB; return fewer or smaller images");
+      imageBytes += size;
       images.push({ type: "image", data: input.data, mimeType: input.mimeType });
 
       return `[image ${images.length}: ${input.mimeType}]`;
@@ -171,7 +203,13 @@ export function packageFinalReturn(value, logs, config) {
   };
 
   value = collect(value);
-  const serialized = truncateChars(formatReturn(value), config.maxReturnChars ?? 32000, "return");
+  const maxReturn = config.maxReturnChars ?? 32000;
+  const formatted = formatReturn(value);
+  const serialized = formatted.length <= maxReturn
+    ? { text: formatted, truncated: imageOverflow }
+    : Array.isArray(value) && value.length && value.every(isString)
+      ? { text: formatBoundedStringArray(value, maxReturn), truncated: true }
+      : { ...truncateChars(formatted, maxReturn, "return"), truncated: true };
   const maxLines = config.maxLogLines ?? 100;
   let logTruncated = logs.length > maxLines;
 

package/src/output/format.js

@@ -71,6 +71,25 @@ function hasWellFormedStrings(values) {
   return true;
 }
 
+/** Keep every array item in an oversized return by giving each a fair truncated share. */
+export function formatBoundedStringArray(values, budget) {
+  const n = values.length;
+  const header = "strings[" + n + "]\n";
+  let remaining = Math.max(0, budget - header.length);
+  let out = header;
+
+  for (let i = 0; i < n; i++) {
+    const itemHeader = "[" + i + "] " + values[i].length + " UTF-16 units\n";
+    const per = Math.max(32, Math.floor(remaining / (n - i)) - itemHeader.length - 1);
+    const bounded = truncateChars(values[i], per, "return");
+    const chunk = itemHeader + bounded.text + "\n";
+    remaining = Math.max(0, remaining - chunk.length);
+    out += chunk;
+  }
+
+  return out;
+}
+
 /** Lossless framing for source arrays, not string escaping or source compression. */
 export function formatReturn(value) {
   if (isString(value)) return value;
@@ -124,7 +143,8 @@ function formatPrimitive(value) {
 
   if (Number.isNaN(value) || value === Infinity || value === -Infinity) return String(value);
 
-  return JSON.stringify(value) ?? String(value);
+  try { return JSON.stringify(value) ?? String(value); }
+  catch { return String(value); }
 }
 
 /**
@@ -149,39 +169,46 @@ function formatFlatWithin(value, limit) {
     return true;
   };
 
-  return walkFlat(value, push) ? parts.join("") : null;
+  return walkFlat(value, push, new Set()) ? parts.join("") : null;
 }
 
-function walkFlat(value, push) {
+function walkFlat(value, push, seen) {
   if (value?.[RAW_TEXT] !== undefined) return push(value[RAW_TEXT]);
 
   if (!isObject(value) && !Array.isArray(value)) return push(formatPrimitive(value));
 
-  if (Array.isArray(value)) {
-    if (value.length === 0) return push("[]");
+  if (seen.has(value)) return push("[Circular]");
+  seen.add(value);
 
-    if (!push("[")) return false;
+  try {
+    if (Array.isArray(value)) {
+      if (value.length === 0) return push("[]");
 
-    for (let i = 0; i < value.length; i++) {
-      if (i && !push(",")) return false;
+      if (!push("[")) return false;
 
-      if (!walkFlat(value[i] === undefined ? null : value[i], push)) return false;
+      for (let i = 0; i < value.length; i++) {
+        if (i && !push(",")) return false;
+
+        if (!walkFlat(value[i] === undefined ? null : value[i], push, seen)) return false;
+      }
+
+      return push("]");
     }
 
-    return push("]");
-  }
+    const keys = Object.keys(value).filter((key) => value[key] !== undefined);
 
-  const keys = Object.keys(value).filter((key) => value[key] !== undefined);
+    if (keys.length === 0) return push("{}");
 
-  if (keys.length === 0) return push("{}");
+    for (let i = 0; i < keys.length; i++) {
+      if (!push((i ? "," : "{") + formatKey(keys[i]) + ":")) return false;
 
-  for (let i = 0; i < keys.length; i++) {
-    if (!push((i ? "," : "{") + formatKey(keys[i]) + ":")) return false;
+      if (!walkFlat(value[keys[i]], push, seen)) return false;
+    }
 
-    if (!walkFlat(value[keys[i]], push)) return false;
+    return push("}");
+  } finally {
+    seen.delete(value);
   }
-
-  return push("}");
 }
 
 /**
@@ -190,24 +217,31 @@ function walkFlat(value, push) {
  * indent is one space. Whitespace is what costs tokens: this measures ~43% fewer
  * than JSON.stringify(value, null, 2) on typical shaped returns (gpt-tokenizer).
  */
-export function formatValue(value, indent = "", width = FORMAT_WIDTH) {
+export function formatValue(value, indent = "", width = FORMAT_WIDTH, seen = new Set()) {
   if (value?.[RAW_TEXT] !== undefined) return value[RAW_TEXT];
 
   if (!isObject(value) && !Array.isArray(value)) return formatPrimitive(value);
-  const flat = formatFlatWithin(value, width - indent.length);
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
 
-  if (flat !== null) return flat;
-  const pad = indent + " ";
+  try {
+    const flat = formatFlatWithin(value, width - indent.length);
 
-  if (Array.isArray(value)) {
-    if (value.length === 0) return "[]";
+    if (flat !== null) return flat;
+    const pad = indent + " ";
 
-    return "[\n" + value.map((item) => pad + formatValue(item === undefined ? null : item, pad, width)).join(",\n") + "\n" + indent + "]";
-  }
+    if (Array.isArray(value)) {
+      if (value.length === 0) return "[]";
 
-  const keys = Object.keys(value).filter((key) => value[key] !== undefined);
+      return "[\n" + value.map((item) => pad + formatValue(item === undefined ? null : item, pad, width, seen)).join(",\n") + "\n" + indent + "]";
+    }
+
+    const keys = Object.keys(value).filter((key) => value[key] !== undefined);
 
-  if (keys.length === 0) return "{}";
+    if (keys.length === 0) return "{}";
 
-  return "{\n" + keys.map((key) => pad + formatKey(key) + ":" + formatValue(value[key], pad, width)).join(",\n") + "\n" + indent + "}";
+    return "{\n" + keys.map((key) => pad + formatKey(key) + ":" + formatValue(value[key], pad, width, seen)).join(",\n") + "\n" + indent + "}";
+  } finally {
+    seen.delete(value);
+  }
 }