@intentius/chant 0.23.0 → 0.25.0

package/src/discovery/sandbox/config-wire.test.ts

@@ -0,0 +1,110 @@
+import { describe, test, expect } from "vitest";
+import { scanConfigWireSafety, formatConfigWireOffenders } from "./config-wire";
+
+/**
+ * chant #1113 — the contract for what a `chant.config.ts` may hold if it is to
+ * be evaluated inside the `--sandbox` boundary. Only JSON crosses a process
+ * boundary, and `JSON.stringify` is lossy without complaining, so this scan is
+ * what turns "silently dropped" into "named and refused".
+ */
+describe("scanConfigWireSafety", () => {
+  test("a real ChantConfig has nothing that cannot cross", () => {
+    expect(
+      scanConfigWireSafety({
+        lexicons: ["aws", "k8s"],
+        environments: ["staging", "prod"],
+        sourceDir: "src",
+        stacks: [{ name: "net", src: "src/net" }],
+        ownership: { stack: "storefront", env: "prod", enabled: true },
+        build: { fold: true, sandbox: true },
+        buildParams: { tier: { type: "string", default: "light", enum: ["light", "prod"] } },
+        lint: { rules: { COR001: "error", COR002: ["warning", { max: 3 }] }, policies: ["policies/org.ts"] },
+        vulnPolicy: { failSeverity: "critical", license: { allow: ["MIT"], deny: [] } },
+        // A lexicon's passthrough extension (the temporal lexicon's shape) —
+        // still pure data.
+        temporal: { profiles: { local: { address: "localhost:7233", tls: false } }, defaultProfile: "local" },
+      }),
+    ).toEqual([]);
+  });
+
+  test("null, empty objects and empty arrays are data", () => {
+    expect(scanConfigWireSafety({ a: null, b: {}, c: [], d: 0, e: false, f: "" })).toEqual([]);
+  });
+
+  test.each([
+    ["a function", { hooks: { before: () => 1 } }, "hooks.before", "a function"],
+    ["a Date", { meta: { at: new Date(0) } }, "meta.at", "a Date"],
+    ["a RegExp", { match: /x/ }, "match", "a RegExp"],
+    ["a Map", { m: new Map() }, "m", "a Map"],
+    ["a Set", { s: new Set() }, "s", "a Set"],
+    ["a bigint", { n: 1n }, "n", "a bigint"],
+    ["NaN", { n: Number.NaN }, "n", "NaN"],
+    ["Infinity", { n: Number.POSITIVE_INFINITY }, "n", "a non-finite number"],
+    ["a symbol", { s: Symbol("x") }, "s", "a symbol"],
+  ])("%s is reported with its key path", (_label, config, path, found) => {
+    expect(scanConfigWireSafety(config)).toEqual([{ path, found }]);
+  });
+
+  test("array positions are reported with an index", () => {
+    expect(scanConfigWireSafety({ stacks: [{ name: "a", src: "s" }, { name: "b", src: () => "s" }] })).toEqual([
+      { path: "stacks[1].src", found: "a function" },
+    ]);
+  });
+
+  test("a class instance is reported by its constructor name", () => {
+    class Policy {
+      value = 1;
+    }
+    expect(scanConfigWireSafety({ p: new Policy() })).toEqual([{ path: "p", found: "a Policy instance" }]);
+  });
+
+  test("a circular reference is reported, not walked forever", () => {
+    const a: Record<string, unknown> = { name: "a" };
+    a.self = a;
+    expect(scanConfigWireSafety({ a })).toEqual([{ path: "a.self", found: "a circular reference" }]);
+  });
+
+  test("every offender is reported, not just the first", () => {
+    expect(scanConfigWireSafety({ a: () => 1, b: { c: new Date(0) } })).toEqual([
+      { path: "a", found: "a function" },
+      { path: "b.c", found: "a Date" },
+    ]);
+  });
+
+  /**
+   * The one accepted lossy case, and its boundary: `{ x: undefined }` reads
+   * identically to `{}` for every consumer of `ChantConfig` (every field is
+   * optional), while an `undefined` in an ARRAY becomes `null` and changes the
+   * element — so only the latter is reported. See the module doc.
+   */
+  test("an undefined property is dropped like an omitted key; an undefined array slot is not", () => {
+    expect(scanConfigWireSafety({ sourceDir: undefined, lexicons: ["aws"] })).toEqual([]);
+    expect(scanConfigWireSafety({ lexicons: ["aws", undefined] })).toEqual([
+      { path: "lexicons[1]", found: "undefined" },
+    ]);
+  });
+
+  test("a module namespace (a config of top-level named exports) is walked, not rejected wholesale", () => {
+    const namespace = Object.create(null) as Record<string, unknown>;
+    namespace.lexicons = ["aws"];
+    expect(scanConfigWireSafety(namespace)).toEqual([]);
+  });
+
+  test("a non-object config says nothing about serializability — normalizeConfig rejects it", () => {
+    expect(scanConfigWireSafety("nope")).toEqual([]);
+    expect(scanConfigWireSafety(null)).toEqual([]);
+  });
+});
+
+describe("formatConfigWireOffenders", () => {
+  test("names the config file, every offending key, and what to do", () => {
+    const message = formatConfigWireOffenders("/p/chant.config.ts", [
+      { path: "hooks.before", found: "a function" },
+      { path: "meta.at", found: "a Date" },
+    ]);
+    expect(message).toContain("/p/chant.config.ts");
+    expect(message).toContain("hooks.before: a function");
+    expect(message).toContain("meta.at: a Date");
+    expect(message).toContain("drop --sandbox");
+  });
+});

package/src/discovery/sandbox/config-wire.ts

@@ -0,0 +1,174 @@
+/**
+ * chant #1113 — what a `chant.config.ts` may contain if it is to be evaluated
+ * inside the sandbox boundary and handed back to the CLI as data.
+ *
+ * Under `--sandbox` the config file is evaluated in a child process (see
+ * `./config-run.ts`), so the only thing that can come back is what survives a
+ * process boundary: JSON. Node's IPC channel serializes with `JSON.stringify`
+ * by default, and `JSON.stringify` is *lossy without complaining* — a function
+ * property vanishes, a `Date` becomes a string, a `Map` becomes `{}`, `NaN`
+ * becomes `null`. Silently handing the CLI a config that differs from the one
+ * the project wrote is the worst available outcome for a security feature, so
+ * this module walks the value FIRST and reports every offending key path.
+ * `./config-run.ts` turns a non-empty report into a build error that names the
+ * keys; nothing is ever dropped quietly.
+ *
+ * This module is bundled INTO the generated config driver (`./driver.ts`'s
+ * `generateConfigDriverSource`) and runs inside the sandboxed child, next to
+ * the project code it is inspecting — so it must not import anything, and must
+ * not touch the filesystem, the environment or the process.
+ *
+ * ## What `ChantConfig` legally holds
+ *
+ * Every field of `ChantConfig` (`../../config.ts`) is JSON data: string arrays
+ * (`lexicons`, `capabilities`, `environments`), strings (`sourceDir`), nested
+ * plain objects of strings/booleans (`ownership`, `build`, `release`, `sbom`,
+ * `signing`, `vulnPolicy`), arrays of plain objects (`stacks`), and records of
+ * plain objects (`buildParams`). `lint` is a `LintConfig`, whose rule values
+ * are a severity string or a `[severity, options]` tuple, and whose `plugins`
+ * / `policies` are file *paths* — chant loads those modules itself, they are
+ * not functions embedded in the config. So the declared type admits nothing
+ * that fails the check below.
+ *
+ * The one way to get there is `ChantConfigSchema`'s `.passthrough()`, which
+ * accepts unknown extra keys of any type (that is how a lexicon extends the
+ * config — `temporal:` in the temporal lexicon's `TemporalChantConfig`, itself
+ * pure data). A project that parks a function under such a key gets a clear
+ * error naming it, rather than a config that silently lost it.
+ *
+ * ## The one accepted lossy case: `undefined` object properties
+ *
+ * `{ sourceDir: undefined }` and `{}` are indistinguishable to every reader of
+ * `ChantConfig` — each field is optional and every resolver tests
+ * `config.x === undefined` / `?.` — so an `undefined`-valued property is
+ * dropped rather than rejected, exactly as omitting the key would be. An
+ * `undefined` inside an ARRAY is a different story (`JSON.stringify` rewrites
+ * it to `null`, changing the element), and is reported.
+ */
+
+/** One value in the config that cannot cross the sandbox boundary as data. */
+export interface ConfigWireOffender {
+  /** Dotted/bracketed path from the config root, e.g. `lint.rules.foo` or `stacks[0].name`. */
+  path: string;
+  /** What was found there, phrased for an error message (e.g. `a function`, `a Date`). */
+  found: string;
+}
+
+/** Deepest nesting `scanConfigWireSafety` will walk before reporting the path as too deep (also the cycle backstop for exotic self-referential structures). */
+const MAX_DEPTH = 64;
+
+function describe(value: unknown): string {
+  const t = typeof value;
+  if (t === "function") return "a function";
+  if (t === "symbol") return "a symbol";
+  if (t === "bigint") return "a bigint";
+  if (t === "number") return Number.isNaN(value) ? "NaN" : "a non-finite number";
+  if (value instanceof Date) return "a Date";
+  if (value instanceof RegExp) return "a RegExp";
+  if (value instanceof Map) return "a Map";
+  if (value instanceof Set) return "a Set";
+  if (value instanceof Promise) return "a Promise";
+  if (value instanceof Error) return "an Error";
+  const ctor = (value as { constructor?: { name?: unknown } })?.constructor?.name;
+  return typeof ctor === "string" && ctor !== "Object" ? `a ${ctor} instance` : "a non-plain object";
+}
+
+/** A plain object literal (or a null-prototype object) — anything else with `typeof "object"` is a class instance chant refuses to guess at. */
+function isPlainObject(value: object): boolean {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function walk(
+  value: unknown,
+  path: string,
+  depth: number,
+  seen: Set<object>,
+  out: ConfigWireOffender[],
+): void {
+  if (value === null) return;
+
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return;
+  if (t === "number") {
+    if (!Number.isFinite(value as number)) out.push({ path, found: describe(value) });
+    return;
+  }
+  if (t === "function" || t === "symbol" || t === "bigint" || t === "undefined") {
+    // `undefined` reaches here only from an array slot — an object property
+    // holding `undefined` is skipped by the caller (see the module doc).
+    out.push({ path, found: t === "undefined" ? "undefined" : describe(value) });
+    return;
+  }
+
+  const obj = value as object;
+  if (seen.has(obj)) {
+    out.push({ path, found: "a circular reference" });
+    return;
+  }
+  if (depth > MAX_DEPTH) {
+    out.push({ path, found: `nested more than ${MAX_DEPTH} levels deep` });
+    return;
+  }
+
+  if (Array.isArray(obj)) {
+    seen.add(obj);
+    for (let i = 0; i < obj.length; i++) walk(obj[i], `${path}[${i}]`, depth + 1, seen, out);
+    seen.delete(obj);
+    return;
+  }
+
+  if (!isPlainObject(obj)) {
+    out.push({ path, found: describe(obj) });
+    return;
+  }
+
+  seen.add(obj);
+  for (const key of Object.keys(obj)) {
+    const child = (obj as Record<string, unknown>)[key];
+    if (child === undefined) continue; // dropped, equivalent to omitting the key — see the module doc
+    const childPath = path ? `${path}.${key}` : key;
+    walk(child, childPath, depth + 1, seen, out);
+  }
+  seen.delete(obj);
+}
+
+/**
+ * Report every value in `config` that cannot cross the sandbox boundary as
+ * JSON. An empty array means a `JSON.parse(JSON.stringify(config))` round-trip
+ * preserves the configuration exactly (modulo `undefined` object properties,
+ * which are dropped — see the module doc).
+ *
+ * `config` itself may be a module namespace object (`await import(...)` with
+ * no `default` export), which is not a plain object; its own enumerable keys
+ * are walked the same way rather than being reported wholesale.
+ */
+export function scanConfigWireSafety(config: unknown): ConfigWireOffender[] {
+  const out: ConfigWireOffender[] = [];
+  if (config === null || typeof config !== "object") {
+    // A non-object config is what `normalizeConfig` already rejects in the
+    // parent; nothing to say about serializability.
+    return out;
+  }
+  const seen = new Set<object>();
+  seen.add(config);
+  for (const key of Object.keys(config as Record<string, unknown>)) {
+    const child = (config as Record<string, unknown>)[key];
+    if (child === undefined) continue;
+    walk(child, key, 1, seen, out);
+  }
+  return out;
+}
+
+/** Render a {@link ConfigWireOffender} list as the body of a build error — one line per offending key, most specific information first. */
+export function formatConfigWireOffenders(
+  configPath: string,
+  offenders: readonly ConfigWireOffender[],
+): string {
+  const lines = offenders.map((o) => `  ${o.path || "<root>"}: ${o.found}`);
+  return [
+    `Cannot evaluate ${configPath} inside the --sandbox boundary: it holds values that are not data.`,
+    ...lines,
+    `Under --sandbox the config is evaluated in an isolated child process and only JSON crosses back, so every value must be a string, number, boolean, null, array or plain object. Move the offending value out of chant.config.ts (lint rule plugins and policy checks are referenced by path, not embedded), or drop --sandbox for this build.`,
+  ].join("\n");
+}

package/src/discovery/sandbox/driver.ts

@@ -41,6 +41,8 @@ const RESOLVE_MODULE = join(DISCOVERY_DIR, "resolve.ts");
 const ENTITY_WIRE_CODEC_MODULE = join(DISCOVERY_DIR, "entity-wire-codec.ts");
 const CHILD_ERRORS_MODULE = join(HERE, "child-errors.ts");
 const PROVENANCE_MODULE = join(dirname(DISCOVERY_DIR), "provenance.ts");
+// chant #1113 — the config driver's serializability contract (see ./config-wire.ts).
+const CONFIG_WIRE_MODULE = join(HERE, "config-wire.ts");
 
 export interface GenerateDriverOptions {
   /** Absolute paths to the run-fallback files this build decided NOT to fold — see `discover()`'s fold/taint loop in `../index.ts`. */
@@ -145,3 +147,69 @@ export function generateDriverSource(options: GenerateDriverOptions): string {
 
   return lines.join("\n");
 }
+
+/**
+ * chant #1113 — generate the driver module that evaluates a project's
+ * `chant.config.ts` INSIDE the sandboxed child and hands back plain JSON.
+ *
+ * Same machinery as {@link generateDriverSource} above, deliberately: one
+ * literal-specifier dynamic `import()` esbuild can trace and inline, one IPC
+ * message back, `./child-errors.ts` for classification so a permission denial
+ * names the config file rather than leaking `ERR_ACCESS_DENIED`. The only
+ * difference is what crosses — a config is data, not an entity graph, so there
+ * is no naming/`AttrRef` step and no `EntitySetWire`; the child instead runs
+ * `./config-wire.ts`'s serializability scan and refuses to hand back a config
+ * that `JSON.stringify` would silently mangle.
+ *
+ * The child returns the raw module namespace's chosen export as-is — the
+ * `default ?? config ?? namespace` selection and Zod validation
+ * (`normalizeConfig`) stay in the parent, where they were, so `--sandbox`
+ * changes where the file is *evaluated* and nothing about how its result is
+ * interpreted.
+ */
+export function generateConfigDriverSource(configPath: string): string {
+  return [
+    `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
+    `import { scanConfigWireSafety } from ${lit(CONFIG_WIRE_MODULE)};`,
+    ``,
+    `function send(payload) {`,
+    `  if (typeof process.send === "function") process.send(payload);`,
+    `  else console.log(JSON.stringify(payload));`,
+    `}`,
+    ``,
+    `async function main() {`,
+    `  let namespace;`,
+    `  try {`,
+    `    namespace = await import(${lit(configPath)});`,
+    `  } catch (err) {`,
+    `    send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err).toJSON() });`,
+    `    return;`,
+    `  }`,
+    ``,
+    // Mirrors loadChantConfig's own selection so the scan sees exactly the
+    // object the parent will normalize. A namespace object is not a plain
+    // object; scanConfigWireSafety walks its own keys rather than rejecting it.
+    `  const selected = namespace.default ?? namespace.config ?? namespace;`,
+    ``,
+    `  const offenders = scanConfigWireSafety(selected);`,
+    `  if (offenders.length > 0) {`,
+    `    send({ kind: "chant-config", ok: false, offenders });`,
+    `    return;`,
+    `  }`,
+    ``,
+    `  try {`,
+    // Round-trip here, not just at the IPC boundary: this is what proves the
+    // payload really is JSON before it leaves the child, and turns anything
+    // the scan somehow missed into a named error instead of a quiet drop.
+    `    const config = JSON.parse(JSON.stringify(selected ?? {}));`,
+    `    send({ kind: "chant-config", ok: true, config });`,
+    `  } catch (err) {`,
+    `    send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err, "resolution").toJSON() });`,
+    `  }`,
+    `}`,
+    ``,
+    `main().catch((err) => {`,
+    `  send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err).toJSON() });`,
+    `});`,
+  ].join("\n");
+}

package/src/discovery/sandbox/fork.ts

@@ -0,0 +1,110 @@
+import { fork } from "node:child_process";
+
+/**
+ * The one place chant starts a sandboxed child process.
+ *
+ * Extracted from `./run.ts` by chant #1113, which added a SECOND thing that
+ * has to run behind the same boundary (`chant.config.ts` evaluation, see
+ * `./config-run.ts`). Both callers must get the identical `--permission`
+ * profile and the identical environment scrub — if the two drifted, the
+ * weaker one would silently become the boundary. Keeping the spawn itself in
+ * one function is the cheapest way to make "same profile" a fact rather than
+ * a claim.
+ *
+ * Isolation mechanics (verified on Node v24.13.1 — see the chant#1045 PR
+ * description for the full write-up):
+ *  - `--permission --allow-fs-read=<bundle dir>,<project dir>[,<trusted
+ *    external package dirs>]` — no filesystem write, no child-process, no
+ *    worker-thread access. Bundling with esbuild first (`./bundle.ts`) means
+ *    the child needs NO TypeScript loader (no `tsx`, so no `--allow-worker`
+ *    and no writable temp dir either).
+ *  - The env is a spawn-time scrub, not `--permission`: Node's Permission
+ *    Model does not gate `process.env` at all (confirmed: every key stays
+ *    readable even under `--permission`). See {@link SandboxForkOptions.env}.
+ *  - Network egress is NOT addressed — Node has no flag for it. See
+ *    `docs/.../architecture/sandbox.mdx` for the residual-risk statement.
+ */
+
+export interface SandboxForkOptions {
+  /** Absolute, realpath'd path to the bundled ESM entry file to run. */
+  bundlePath: string;
+  /** Absolute, realpath'd directory holding {@link bundlePath} — granted `--allow-fs-read`. */
+  bundleDir: string;
+  /** Absolute, realpath'd project directory — granted `--allow-fs-read`. */
+  projectRealpath: string;
+  /** Additional directories to grant `--allow-fs-read` (the resolved locations of `./bundle.ts`'s deliberately-unbundled trusted packages). */
+  externalReadPaths: readonly string[];
+  /**
+   * The child's ENTIRE environment. Callers pass an explicit, closed set —
+   * never a spread of `process.env`. `./run.ts` passes `PATH` only;
+   * `./config-run.ts` adds `CHANT_ENV` (see its doc for why that one
+   * variable, and only that one, is forwarded).
+   */
+  env: Record<string, string>;
+  /** How long to wait for the child's one IPC message before killing it. */
+  timeoutMs: number;
+  /** What timed out / exited early, for the error message (e.g. `"sandboxed run"`). */
+  label: string;
+}
+
+/**
+ * Fork `bundlePath` under `--permission` with a scrubbed environment, and
+ * resolve with the first IPC message that satisfies `isResponse` (or reject
+ * on crash / timeout / fork error).
+ */
+export function forkSandboxed<T>(
+  options: SandboxForkOptions,
+  isResponse: (value: unknown) => value is T,
+): Promise<T> {
+  const { bundlePath, bundleDir, projectRealpath, externalReadPaths, env, timeoutMs, label } = options;
+
+  return new Promise((resolvePromise, reject) => {
+    const readAllowances = [bundleDir, projectRealpath, ...externalReadPaths].map(
+      (p) => `--allow-fs-read=${p}`,
+    );
+    const child = fork(bundlePath, [], {
+      execArgv: ["--permission", ...readAllowances],
+      env,
+      stdio: ["ignore", "pipe", "pipe", "ipc"],
+    });
+
+    let settled = false;
+    let stderrBuf = "";
+
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill();
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderrBuf += chunk.toString();
+    });
+
+    child.on("message", (msg: unknown) => {
+      if (settled || !isResponse(msg)) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolvePromise(msg);
+    });
+
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(err);
+    });
+
+    child.on("exit", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(
+        new Error(
+          `${label}: child exited before reporting results (code ${code}, signal ${signal})${stderrBuf.trim() ? `: ${stderrBuf.trim()}` : ""}`,
+        ),
+      );
+    });
+  });
+}

package/src/discovery/sandbox/run.ts

@@ -1,4 +1,3 @@
-import { fork } from "node:child_process";
 import { realpathSync, rmSync } from "node:fs";
 import { resolve } from "node:path";
 import type { Declarable } from "../../declarable";
@@ -7,6 +6,7 @@ import { decodeEntitySet, type EntitySetWire } from "../entity-wire-codec";
 import { bundleDriver } from "./bundle";
 import { classifyChildError } from "./child-errors";
 import { generateDriverSource } from "./driver";
+import { forkSandboxed } from "./fork";
 
 /**
  * chant #1045 Phase 2 — runs every run-fallback file for a build TOGETHER, as
@@ -14,26 +14,16 @@ import { generateDriverSource } from "./driver";
  * the same shape `discover()`'s own in-process run path would have produced:
  * a named, ref-resolved entities map plus any errors.
  *
- * Isolation mechanics (verified on Node v24.13.1 — see the chant#1045 PR
- * description for the full write-up):
- *  - `--permission --allow-fs-read=<bundle dir>,<project dir>[,<trusted
- *    external package dirs>]` — no filesystem write, no child-process, no
- *    worker-thread access. Bundling with esbuild first (not a packaging
- *    change — see `./bundle.ts`) means the child needs NO TypeScript loader
- *    (no `tsx`, so no `--allow-worker` and no writable temp dir either),
- *    unlike the plain `tsx`-based run path. The "trusted external package
- *    dirs" allowance is narrow and specific: `./bundle.ts` deliberately
- *    leaves a couple of chant/lexicon-internal dependencies (`typescript`)
- *    unbundled and resolves them to their real, fixed location instead —
- *    project source never controls what's installed there.
- *  - The env is a spawn-time scrub (`env: {}` below, plus `PATH` — see the
- *    option below), not `--permission`: Node's Permission Model does not gate
- *    `process.env` at all (confirmed: every key stays readable even under
- *    `--permission`).
- *  - Network egress is NOT addressed here — Node has no flag for it. See the
- *    chant#1045 PR description / docs for the residual-risk statement and
- *    deployment guidance (a container with no egress, a network namespace).
- *    This function does not claim to close that gap.
+ * Isolation mechanics live in `./fork.ts` — the one function that spawns a
+ * sandboxed child, shared with chant #1113's config evaluation
+ * (`./config-run.ts`) so the two cannot drift apart. In short:
+ * `--permission --allow-fs-read=<bundle dir>,<project dir>[,<trusted external
+ * package dirs>]`, a spawn-time environment scrub, no writes, no spawning, no
+ * worker threads, and no network guarantee. The "trusted external package
+ * dirs" allowance is narrow and specific: `./bundle.ts` deliberately leaves a
+ * couple of chant/lexicon-internal dependencies (`typescript`) unbundled and
+ * resolves them to their real, fixed location instead — project source never
+ * controls what's installed there.
  *
  * What does NOT run inside the child: fold (`tryFoldFile`, `../fold-import`)
  * stays exactly where it is today, in the parent, unsandboxed — fold already
@@ -108,7 +98,23 @@ export async function runFallbackFilesSandboxed(
       projectRealpath = resolve(buildRoot);
     }
 
-    const response = await runChildProcess(bundlePath, bundleDir, projectRealpath, externalReadPaths);
+    const response = await forkSandboxed(
+      {
+        bundlePath,
+        bundleDir,
+        projectRealpath,
+        externalReadPaths,
+        // chant #1045 Phase 2 — Node's Permission Model does not gate
+        // `process.env`; scrubbing it at spawn is the only way to keep the
+        // ambient environment out of untrusted project source's reach. `PATH`
+        // is kept only because some platforms' module resolution/dynamic
+        // linking consults it; it carries no project secrets.
+        env: { PATH: process.env.PATH ?? "" },
+        timeoutMs: CHILD_TIMEOUT_MS,
+        label: "sandboxed run",
+      },
+      isChildResponse,
+    );
 
     const errors = (response.errors ?? []).map(
       (e) => new DiscoveryError(e.file, e.message, e.type),
@@ -131,66 +137,3 @@ export async function runFallbackFilesSandboxed(
     rmSync(bundleDir, { recursive: true, force: true });
   }
 }
-
-/** Fork the bundle under `--permission`, with a scrubbed environment, and resolve with its one IPC message (or reject on crash/timeout/fork error). */
-function runChildProcess(
-  bundlePath: string,
-  bundleDir: string,
-  projectRealpath: string,
-  externalReadPaths: readonly string[],
-): Promise<ChildResponse> {
-  return new Promise((resolvePromise, reject) => {
-    const readAllowances = [bundleDir, projectRealpath, ...externalReadPaths].map(
-      (p) => `--allow-fs-read=${p}`,
-    );
-    const child = fork(bundlePath, [], {
-      execArgv: ["--permission", ...readAllowances],
-      // chant #1045 Phase 2 — Node's Permission Model does not gate
-      // `process.env`; scrubbing it here is the only way to keep the ambient
-      // environment out of untrusted project source's reach. `PATH` is kept
-      // only because some platforms' module resolution/dynamic linking
-      // consults it; it carries no project secrets.
-      env: { PATH: process.env.PATH ?? "" },
-      stdio: ["ignore", "pipe", "pipe", "ipc"],
-    });
-
-    let settled = false;
-    let stderrBuf = "";
-
-    const timeout = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      child.kill();
-      reject(new Error(`sandboxed run timed out after ${CHILD_TIMEOUT_MS}ms`));
-    }, CHILD_TIMEOUT_MS);
-
-    child.stderr?.on("data", (chunk: Buffer) => {
-      stderrBuf += chunk.toString();
-    });
-
-    child.on("message", (msg: unknown) => {
-      if (settled || !isChildResponse(msg)) return;
-      settled = true;
-      clearTimeout(timeout);
-      resolvePromise(msg);
-    });
-
-    child.on("error", (err) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeout);
-      reject(err);
-    });
-
-    child.on("exit", (code, signal) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeout);
-      reject(
-        new Error(
-          `sandboxed child exited before reporting results (code ${code}, signal ${signal})${stderrBuf.trim() ? `: ${stderrBuf.trim()}` : ""}`,
-        ),
-      );
-    });
-  });
-}