@intentius/chant 0.24.0 → 0.25.0

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

@@ -0,0 +1,130 @@
+import { realpathSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { bundleDriver } from "./bundle";
+import { generateConfigDriverSource } from "./driver";
+import { formatConfigWireOffenders, type ConfigWireOffender } from "./config-wire";
+import { forkSandboxed } from "./fork";
+import { ENV_VAR } from "../../env";
+
+/**
+ * chant #1113 — evaluates a project's `chant.config.ts` inside the same
+ * sandboxed child `--sandbox` already uses for run-fallback source, and brings
+ * back plain JSON.
+ *
+ * This closes the residual chant #1093 documented and #1113 filed: `loadConfig`
+ * imported the project's own `chant.config.ts` into the CLI process, so a
+ * hostile repo's config executed with full CLI trust even under `--sandbox`.
+ * The config is project-authored code like any other file in the repo; the
+ * only reason it was ever treated differently is that the CLI has to read it
+ * before it knows anything else about the project.
+ *
+ * Deliberately the same machinery, not a parallel one:
+ *  - `./bundle.ts` bundles the generated driver (`./driver.ts`'s
+ *    `generateConfigDriverSource`) with esbuild, so the child needs no runtime
+ *    module resolution and no TypeScript loader.
+ *  - `./fork.ts` spawns it with the identical `--permission` profile
+ *    `runFallbackFilesSandboxed` uses — one function, so the two cannot drift.
+ *  - `./child-errors.ts` classifies whatever it throws, so a permission denial
+ *    names the config file instead of leaking `ERR_ACCESS_DENIED`.
+ *
+ * The one deliberate difference from the run-fallback child is `CHANT_ENV`.
+ * `../../cli/main.ts` sets it from `--env` *before* loading the config,
+ * specifically because a config may branch on the environment; dropping it
+ * would silently produce a different configuration under `--sandbox` than
+ * without. It is a value the user typed on the command line, not an ambient
+ * secret, so forwarding exactly that one key — and nothing else from
+ * `process.env` — keeps the scrub meaningful while keeping `--env` honest.
+ */
+
+/** How long to wait for the config child. A config is one small module; anything approaching this is hung, not slow. */
+const CONFIG_CHILD_TIMEOUT_MS = 60_000;
+
+interface ConfigChildResponse {
+  kind: "chant-config";
+  ok: boolean;
+  config?: unknown;
+  offenders?: ConfigWireOffender[];
+  error?: { name: string; file: string; message: string; type: string };
+}
+
+function isConfigChildResponse(value: unknown): value is ConfigChildResponse {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { kind?: unknown }).kind === "chant-config" &&
+    typeof (value as { ok?: unknown }).ok === "boolean"
+  );
+}
+
+export interface SandboxConfigResult {
+  /** The evaluated configuration, as plain JSON. Interpreted (default/config/namespace selection already applied in the child; Zod validation still to come) by `../../config.ts`'s `normalizeConfig`, in the parent, unchanged. */
+  config: unknown;
+  /** esbuild bundling wall-clock time. */
+  bundleMs: number;
+  /** Bundle size in bytes. */
+  bundleBytes: number;
+}
+
+/**
+ * Evaluate `configPath` in a sandboxed child and return its configuration as
+ * plain data.
+ *
+ * Throws — rather than degrading to an in-process import or to defaults — when
+ * the config cannot be evaluated inside the boundary or cannot cross it as
+ * JSON. Under `--sandbox` a config that "almost" loaded is not a safe thing to
+ * proceed with, and quietly falling back would give away the property the flag
+ * exists to provide.
+ *
+ * @param configPath - Absolute path to the project's `chant.config.ts`.
+ * @param projectRoot - Directory the child is granted `--allow-fs-read` for
+ *   (the config's own project root, i.e. `findProjectConfig`'s `dir`).
+ */
+export async function evaluateConfigSandboxed(
+  configPath: string,
+  projectRoot: string,
+): Promise<SandboxConfigResult> {
+  const driverSource = generateConfigDriverSource(configPath);
+  const { bundlePath, bundleDir, externalReadPaths, durationMs, bytes } = await bundleDriver(driverSource);
+
+  try {
+    let projectRealpath: string;
+    try {
+      projectRealpath = realpathSync(resolve(projectRoot));
+    } catch {
+      projectRealpath = resolve(projectRoot);
+    }
+
+    const env: Record<string, string> = { PATH: process.env.PATH ?? "" };
+    // See the module doc: the one forwarded variable, and only when set.
+    const activeEnv = process.env[ENV_VAR];
+    if (activeEnv) env[ENV_VAR] = activeEnv;
+
+    const response = await forkSandboxed(
+      {
+        bundlePath,
+        bundleDir,
+        projectRealpath,
+        externalReadPaths,
+        env,
+        timeoutMs: CONFIG_CHILD_TIMEOUT_MS,
+        label: `sandboxed evaluation of ${configPath}`,
+      },
+      isConfigChildResponse,
+    );
+
+    if (!response.ok) {
+      if (response.offenders && response.offenders.length > 0) {
+        throw new Error(formatConfigWireOffenders(configPath, response.offenders));
+      }
+      throw new Error(
+        response.error?.message
+          ? `Failed to evaluate ${configPath} inside the --sandbox boundary: ${response.error.message}`
+          : `Failed to evaluate ${configPath} inside the --sandbox boundary`,
+      );
+    }
+
+    return { config: response.config ?? {}, bundleMs: durationMs, bundleBytes: bytes };
+  } finally {
+    rmSync(bundleDir, { recursive: true, force: true });
+  }
+}

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()}` : ""}`,
+        ),
+      );
+    });
+  });
+}