@intentius/chant 0.25.0 → 0.26.0

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

@@ -18,6 +18,12 @@
  * the project code it is inspecting — so it must not import anything, and must
  * not touch the filesystem, the environment or the process.
  *
+ * chant #1131 reuses the same walk for the OTHER direction: a `lint.policies`
+ * check runs inside a sandboxed child and its `PostSynthDiagnostic[]` has to
+ * come back as data (`./policy-wire.ts`). That is the same "JSON is lossy
+ * without complaining" problem with a different root value, so the walk is
+ * exported as {@link scanValueWireSafety} rather than copied.
+ *
  * ## What `ChantConfig` legally holds
  *
  * Every field of `ChantConfig` (`../../config.ts`) is JSON data: string arrays
@@ -133,6 +139,21 @@ function walk(
   seen.delete(obj);
 }
 
+/**
+ * chant #1131 — report every value ANYWHERE in `value` that cannot cross the
+ * sandbox boundary as JSON, with paths rooted at `rootPath`.
+ *
+ * {@link scanConfigWireSafety} is the config-shaped entry point (it tolerates a
+ * module namespace object at the root); this one takes the value as given, so
+ * an array root (`diagnostics`) or a plain object root both work. Same rules,
+ * same `undefined`-object-property allowance — see the module doc.
+ */
+export function scanValueWireSafety(value: unknown, rootPath = ""): ConfigWireOffender[] {
+  const out: ConfigWireOffender[] = [];
+  walk(value, rootPath, 0, new Set<object>(), out);
+  return out;
+}
+
 /**
  * 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

package/src/discovery/sandbox/driver.ts

@@ -43,6 +43,9 @@ 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");
+// chant #1131 — the policy driver's build-result decoding + diagnostics contract.
+const POLICY_WIRE_MODULE = join(HERE, "policy-wire.ts");
+const POST_SYNTH_MODULE = join(dirname(DISCOVERY_DIR), "lint", "post-synth.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`. */
@@ -213,3 +216,132 @@ export function generateConfigDriverSource(configPath: string): string {
     `});`,
   ].join("\n");
 }
+
+/**
+ * chant #1131 — generate the driver module that imports a project's
+ * `lint.policies` modules INSIDE the sandboxed child, runs their checks over
+ * the build result the parent hands it, and sends back plain
+ * `PostSynthDiagnostic`s.
+ *
+ * Same machinery again: literal-specifier dynamic `import()`s esbuild can trace
+ * and inline, `./child-errors.ts` for classification so a permission denial
+ * names the policy file, one IPC message back. Two things are specific to this
+ * one:
+ *
+ *  - **It receives before it sends.** The run and config drivers are fully
+ *    parameterized by their generated source; a policy check needs the finished
+ *    build result, which is neither known at bundle time nor something to bake
+ *    into a source literal. It arrives as one IPC message (see `./fork.ts`'s
+ *    `send`). The `process.on("message", …)` registration is top-level and
+ *    synchronous, so it is in place before the event loop can deliver anything
+ *    — a message the parent sent before the child finished booting is queued on
+ *    the channel, not lost.
+ *  - **Checks run wrapped, not raw.** `runPostSynthChecks` (chant's own, from
+ *    `../../lint/post-synth.ts`) is invoked ONCE over every check from every
+ *    policy module, exactly as `cli/commands/build.ts` invokes it in-process —
+ *    so the checks share one `PostSynthContext` and run in one order, and the
+ *    diagnostics come back in the same sequence. The wrapper around each check
+ *    is what makes a bad return value attributable: it scans that check's own
+ *    output and throws a `PolicyWireError` naming the module the check was
+ *    loaded from, rather than reporting an offending index in a merged array.
+ */
+export function generatePolicyDriverSource(policyPaths: readonly string[]): string {
+  const lines: string[] = [
+    `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
+    `import { decodePolicyBuildResult, scanPolicyDiagnostics, PolicyWireError } from ${lit(POLICY_WIRE_MODULE)};`,
+    `import { runPostSynthChecks, isPostSynthCheck } from ${lit(POST_SYNTH_MODULE)};`,
+    ``,
+    `function send(payload) {`,
+    `  if (typeof process.send === "function") process.send(payload);`,
+    `  else console.log(JSON.stringify(payload));`,
+    `}`,
+    ``,
+    `function fail(file, err, type) {`,
+    `  if (err instanceof PolicyWireError) {`,
+    `    send({ kind: "chant-policy", ok: false, offenders: err.offenders });`,
+    `    return;`,
+    `  }`,
+    `  send({ kind: "chant-policy", ok: false, error: classifyChildError(file, err, type).toJSON() });`,
+    `}`,
+    ``,
+    // The wrapper described in the doc above: same id/description so any
+    // chant-side reporting keyed off them is unchanged, same ctx, same return
+    // value — plus the per-check serializability scan.
+    `function guard(check, policy) {`,
+    `  return {`,
+    `    id: check.id,`,
+    `    description: check.description,`,
+    `    check(ctx) {`,
+    `      const produced = check.check(ctx);`,
+    `      const offenders = scanPolicyDiagnostics(produced, policy);`,
+    `      if (offenders.length > 0) throw new PolicyWireError(offenders);`,
+    `      return produced;`,
+    `    },`,
+    `  };`,
+    `}`,
+    ``,
+    `async function main(request) {`,
+    `  let buildResult;`,
+    `  try {`,
+    `    buildResult = decodePolicyBuildResult(request.buildResult);`,
+    `  } catch (err) {`,
+    `    fail("", err, "resolution");`,
+    `    return;`,
+    `  }`,
+    ``,
+    `  const checks = [];`,
+  ];
+
+  // One block per policy module, in the order `lint.policies` declares them —
+  // the same order `loadPolicyChecks` collects in, so the diagnostics sequence
+  // matches the in-process one exactly.
+  for (const policyPath of policyPaths) {
+    lines.push(
+      `  try {`,
+      `    const mod = await import(${lit(policyPath)});`,
+      `    for (const value of Object.values(mod)) {`,
+      `      if (isPostSynthCheck(value)) checks.push(guard(value, ${lit(policyPath)}));`,
+      `    }`,
+      `  } catch (err) {`,
+      `    fail(${lit(policyPath)}, err, "import");`,
+      `    return;`,
+      `  }`,
+    );
+  }
+
+  lines.push(
+    ``,
+    `  let diagnostics;`,
+    `  try {`,
+    `    diagnostics = runPostSynthChecks(checks, buildResult, request.env ?? undefined);`,
+    `  } catch (err) {`,
+    `    fail("", err, "resolution");`,
+    `    return;`,
+    `  }`,
+    ``,
+    `  send({ kind: "chant-policy", ok: true, diagnostics });`,
+    `}`,
+    ``,
+    // Registered synchronously at module top level — see the doc above on why
+    // that is what makes the parent's send-before-boot safe.
+    //
+    // Removed again as soon as the input arrives, and that is not tidiness: a
+    // `message` listener REFS the IPC channel, so leaving it registered would
+    // keep this child's event loop alive after it had already answered — and a
+    // live channel keeps the PARENT's alive too. `chant build` would not have
+    // noticed (`cli/main.ts` ends in `process.exit`); anything embedding chant
+    // as a library would have hung. `./fork.ts` kills the child on receipt as
+    // the other half of the same fix.
+    `let started = false;`,
+    `function onRequest(request) {`,
+    `  if (started) return;`,
+    `  if (!request || request.kind !== "chant-policy-request") return;`,
+    `  started = true;`,
+    `  process.off("message", onRequest);`,
+    `  main(request).catch((err) => fail("", err, "resolution"));`,
+    `}`,
+    `process.on("message", onRequest);`,
+  );
+
+  return lines.join("\n");
+}

package/src/discovery/sandbox/fork.ts

@@ -45,6 +45,24 @@ export interface SandboxForkOptions {
   timeoutMs: number;
   /** What timed out / exited early, for the error message (e.g. `"sandboxed run"`). */
   label: string;
+  /**
+   * chant #1131 — an optional payload sent to the child over the SAME IPC
+   * channel its response comes back on, immediately after the fork.
+   *
+   * The run and config children are fully described by their generated driver
+   * source, so they need nothing inbound. The policy child does: its input is
+   * the finished build result, which exists only after the parent has merged
+   * and serialized, long after the bundle was built. Sending it rather than
+   * baking it into a source literal keeps the bundle small (esbuild would
+   * otherwise parse a multi-megabyte literal) and keeps it off disk.
+   *
+   * Safe to send before the child has booted: `child.send` writes to the IPC
+   * pipe and Node queues the message until the child's channel is read, and
+   * the driver registers its `process.on("message", …)` synchronously at module
+   * top level — before the event loop can deliver anything. This is NOT a
+   * second protocol: same channel, same JSON, same one-message-back response.
+   */
+  send?: Record<string, unknown>;
 }
 
 /**
@@ -56,7 +74,7 @@ export function forkSandboxed<T>(
   options: SandboxForkOptions,
   isResponse: (value: unknown) => value is T,
 ): Promise<T> {
-  const { bundlePath, bundleDir, projectRealpath, externalReadPaths, env, timeoutMs, label } = options;
+  const { bundlePath, bundleDir, projectRealpath, externalReadPaths, env, timeoutMs, label, send } = options;
 
   return new Promise((resolvePromise, reject) => {
     const readAllowances = [bundleDir, projectRealpath, ...externalReadPaths].map(
@@ -78,6 +96,16 @@ export function forkSandboxed<T>(
       reject(new Error(`${label} timed out after ${timeoutMs}ms`));
     }, timeoutMs);
 
+    if (send !== undefined) {
+      child.send(send, (err) => {
+        if (settled || !err) return;
+        settled = true;
+        clearTimeout(timeout);
+        child.kill();
+        reject(new Error(`${label}: failed to send the child its input: ${err.message}`));
+      });
+    }
+
     child.stderr?.on("data", (chunk: Buffer) => {
       stderrBuf += chunk.toString();
     });
@@ -86,6 +114,16 @@ export function forkSandboxed<T>(
       if (settled || !isResponse(msg)) return;
       settled = true;
       clearTimeout(timeout);
+      // chant #1131 — the child's entire job is to send this one message, so
+      // once it has arrived there is nothing left to wait for. Killing it here
+      // rather than hoping it exits on its own closes a real hang: an open
+      // handle on the child side (a `setInterval` in project source, an
+      // `http.Server` a policy started, or simply an IPC listener the driver
+      // registered to RECEIVE its input) keeps the child's event loop alive,
+      // and a live IPC channel then keeps the PARENT's alive too. `chant build`
+      // never noticed because `cli/main.ts` ends with `process.exit`; anything
+      // embedding chant as a library would have hung forever.
+      child.kill();
       resolvePromise(msg);
     });
 

package/src/discovery/sandbox/policy-boundary.test.ts

@@ -0,0 +1,325 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, writeFile, rm, realpath, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
+import type { Declarable } from "../../declarable";
+import { createResource } from "../../runtime";
+import { resolveAttrRefs } from "../resolve";
+import { ENV_VAR } from "../../env";
+import { loadPolicyChecks } from "../../lint/policy";
+import {
+  armSandboxPolicyExecution,
+  isSandboxPolicyExecutionArmed,
+  resetSandboxPolicyExecutionForTests,
+  runProjectPolicies,
+  type ProjectPolicyRun,
+} from "../../lint/policy-sandbox";
+
+/**
+ * chant #1131 — a `lint.policies` module is project-authored code, and under
+ * `--sandbox` neither its top level nor its `check` function may run in the
+ * CLI's process.
+ *
+ * Same shape of proof as `./fold-boundary.test.ts` (#1093) and
+ * `./config-boundary.test.ts` (#1113): the fixture policy sets a `globalThis`
+ * marker at module top level and another inside `check`, and a marker set in
+ * the sandboxed child cannot reach this process. **The unarmed half is asserted
+ * first**, so the probe is proven capable of firing before the armed half
+ * asserts it stays clean.
+ *
+ * Fixtures go to a fresh tmpdir per test — never the source tree — so no two
+ * tests share a module path and nothing bleeds through Node's module cache.
+ */
+
+const TOP_MARKER = "__chant1131PolicyTopLevel";
+const CHECK_MARKER = "__chant1131PolicyCheckRan";
+
+type MarkerHost = Record<string, boolean | undefined>;
+
+function marker(name: string): boolean | undefined {
+  return (globalThis as unknown as MarkerHost)[name];
+}
+
+/** A small, realistic build result: two entities with a cross-reference, plus one lexicon's serialized output. */
+function buildResultFixture(): ProjectPolicyRun["buildResult"] {
+  const Vpc = createResource("Test::Vpc", "test", { vpcId: "VpcId" });
+  const Ingress = createResource("Test::Ingress", "test", {});
+  const vpc = new Vpc({ CidrBlock: "10.0.0.0/16" });
+  const ingress = new Ingress({ VpcId: (vpc as unknown as Record<string, unknown>).vpcId, tls: [] });
+  const entities = new Map<string, Declarable>([
+    ["Vpc", vpc as unknown as Declarable],
+    ["Ingress", ingress as unknown as Declarable],
+  ]);
+  resolveAttrRefs(entities);
+
+  return {
+    outputs: new Map<string, string>([["test", "kind: Ingress\nmetadata:\n  name: storefront\n"]]),
+    entities,
+    warnings: [],
+    errors: [],
+    sourceFileCount: 2,
+  } as unknown as ProjectPolicyRun["buildResult"];
+}
+
+describe("lint.policies execution under --sandbox (chant #1131)", () => {
+  let testDir: string;
+  let savedEnv: string | undefined;
+
+  beforeEach(async () => {
+    const dir = join(tmpdir(), `chant-1131-policy-${Date.now()}-${Math.random()}`);
+    await mkdir(dir, { recursive: true });
+    testDir = await realpath(dir);
+    delete (globalThis as unknown as MarkerHost)[TOP_MARKER];
+    delete (globalThis as unknown as MarkerHost)[CHECK_MARKER];
+    savedEnv = process.env[ENV_VAR];
+    resetSandboxPolicyExecutionForTests();
+  });
+
+  afterEach(async () => {
+    delete (globalThis as unknown as MarkerHost)[TOP_MARKER];
+    delete (globalThis as unknown as MarkerHost)[CHECK_MARKER];
+    if (savedEnv === undefined) delete process.env[ENV_VAR];
+    else process.env[ENV_VAR] = savedEnv;
+    resetSandboxPolicyExecutionForTests();
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  /** A policy that announces its own execution twice: once at module top level, once per check call. */
+  async function writeMarkerPolicy(name = "org.ts", body?: string): Promise<string> {
+    await writeFile(
+      join(testDir, name),
+      body ??
+        `globalThis[${JSON.stringify(TOP_MARKER)}] = true;\n` +
+          `export const tlsRequired = {\n` +
+          `  id: "ORG-TLS",\n` +
+          `  description: "ingress must terminate TLS",\n` +
+          `  check(ctx) {\n` +
+          `    globalThis[${JSON.stringify(CHECK_MARKER)}] = true;\n` +
+          `    const out = [];\n` +
+          `    for (const [entityName, entity] of ctx.entities) {\n` +
+          `      const tls = entity.props && entity.props.tls;\n` +
+          `      if (Array.isArray(tls) && tls.length === 0) {\n` +
+          `        out.push({ checkId: "ORG-TLS", severity: "error", message: entityName + " has no TLS in " + ctx.env, entity: entityName });\n` +
+          `      }\n` +
+          `    }\n` +
+          `    if (ctx.outputs.get("test").includes("storefront")) {\n` +
+          `      out.push({ checkId: "ORG-TLS", severity: "warning", message: "saw storefront in the output" });\n` +
+          `    }\n` +
+          `    return out;\n` +
+          `  },\n` +
+          `};\n`,
+    );
+    return name;
+  }
+
+  function run(policies: string[], env = "prod"): ReturnType<typeof runProjectPolicies> {
+    return runProjectPolicies({ policies, configDir: testDir, buildResult: buildResultFixture(), env });
+  }
+
+  test("without --sandbox the policy DOES run in this process (both probes fire)", async () => {
+    await writeMarkerPolicy();
+
+    const diags = await run(["org.ts"]);
+
+    expect(isSandboxPolicyExecutionArmed()).toBe(false);
+    expect(marker(TOP_MARKER), "the policy module's top level ran in this process").toBe(true);
+    expect(marker(CHECK_MARKER), "the check function ran in this process").toBe(true);
+    expect(diags).toEqual([
+      { checkId: "ORG-TLS", severity: "error", message: "Ingress has no TLS in prod", entity: "Ingress" },
+      { checkId: "ORG-TLS", severity: "warning", message: "saw storefront in the output" },
+    ]);
+  });
+
+  test("armed, the same policy runs in the child: no markers here, IDENTICAL diagnostics", async () => {
+    await writeMarkerPolicy();
+    const plain = await run(["org.ts"]);
+
+    delete (globalThis as unknown as MarkerHost)[TOP_MARKER];
+    delete (globalThis as unknown as MarkerHost)[CHECK_MARKER];
+    armSandboxPolicyExecution();
+    const sandboxed = await run(["org.ts"]);
+
+    expect(marker(TOP_MARKER), "the policy module's top level must NOT run in the CLI process").toBeUndefined();
+    expect(marker(CHECK_MARKER), "the check function must NOT run in the CLI process").toBeUndefined();
+    expect(sandboxed).toEqual(plain);
+  });
+
+  test("several policy modules keep their declaration order across the boundary", async () => {
+    for (const [file, id] of [
+      ["a.ts", "A"],
+      ["b.ts", "B"],
+    ] as const) {
+      await writeFile(
+        join(testDir, file),
+        `export const c = { id: ${JSON.stringify(id)}, description: "d", check: () => [{ checkId: ${JSON.stringify(id)}, severity: "info", message: "m" }] };\n`,
+      );
+    }
+
+    const plain = await run(["a.ts", "b.ts"]);
+    armSandboxPolicyExecution();
+    const sandboxed = await run(["a.ts", "b.ts"]);
+
+    expect(plain.map((d) => d.checkId)).toEqual(["A", "B"]);
+    expect(sandboxed).toEqual(plain);
+  });
+
+  test("a policy that reads outside the project is denied, naming the policy file", async () => {
+    await writeMarkerPolicy(
+      "org.ts",
+      `import { readFileSync } from "node:fs";\n` +
+        `const stolen = readFileSync("/etc/hosts", "utf-8");\n` +
+        `export const c = { id: "X", description: "d", check: () => [{ checkId: "X", severity: "info", message: stolen.slice(0, 3) }] };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/sandbox denied FileSystemRead \(\/etc\/hosts\)/);
+    await expect(run(["org.ts"])).rejects.toThrow(/org\.ts/);
+  });
+
+  test("a policy that writes a file is denied — the boundary costs this pattern, deliberately", async () => {
+    // A policy that drops a compliance report next to the build is a plausible
+    // thing to have written. Under `--sandbox` it fails, loudly, rather than
+    // succeeding and making the flag a lie.
+    await writeMarkerPolicy(
+      "org.ts",
+      `import { writeFileSync } from "node:fs";\n` +
+        `export const c = { id: "X", description: "d", check: () => { writeFileSync(${JSON.stringify(join(testDir, "report.json"))}, "{}"); return []; } };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/sandbox denied FileSystemWrite/);
+    await expect(readFile(join(testDir, "report.json"))).rejects.toThrow();
+  });
+
+  test("a policy that tries to spawn a process is denied", async () => {
+    await writeMarkerPolicy(
+      "org.ts",
+      `import { execSync } from "node:child_process";\n` +
+        `export const c = { id: "X", description: "d", check: () => { execSync("echo pwned"); return []; } };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/sandbox denied/);
+  });
+
+  test("the child's environment is scrubbed — but --env still reaches a policy", async () => {
+    process.env[ENV_VAR] = "prod";
+    process.env.CHANT_1131_SECRET = "hunter2";
+    try {
+      await writeMarkerPolicy(
+        "org.ts",
+        `export const c = {\n` +
+          `  id: "ENV", description: "d",\n` +
+          `  check: (ctx) => [\n` +
+          `    { checkId: "ENV", severity: "info", message: "ctx.env=" + ctx.env },\n` +
+          `    { checkId: "ENV", severity: "info", message: "CHANT_ENV=" + (process.env[${JSON.stringify(ENV_VAR)}] ?? "unset") },\n` +
+          `    { checkId: "ENV", severity: "info", message: "secret=" + (process.env.CHANT_1131_SECRET ?? "scrubbed") },\n` +
+          `  ],\n` +
+          `};\n`,
+      );
+      armSandboxPolicyExecution();
+
+      const diags = await run(["org.ts"], "prod");
+
+      expect(diags.map((d) => d.message)).toEqual(["ctx.env=prod", "CHANT_ENV=prod", "secret=scrubbed"]);
+    } finally {
+      delete process.env.CHANT_1131_SECRET;
+    }
+  });
+
+  test("a diagnostic that is not data is refused, naming the policy module and the key path", async () => {
+    await writeMarkerPolicy(
+      "org.ts",
+      `export const c = { id: "X", description: "d", check: () => [{ checkId: "X", severity: "error", message: "m", fix: () => 1 }] };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    const promise = run(["org.ts"]);
+    await expect(promise).rejects.toThrow(/org\.ts \[0\]\.fix: a function/);
+    await expect(run(["org.ts"])).rejects.toThrow(/Cannot run lint\.policies inside the --sandbox boundary/);
+  });
+
+  test("a diagnostic with a bad severity is refused rather than printed as one", async () => {
+    await writeMarkerPolicy(
+      "org.ts",
+      `export const c = { id: "X", description: "d", check: () => [{ checkId: "X", severity: "fatal", message: "m" }] };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/severity: not one of "error", "warning", "info"/);
+  });
+
+  test("a policy module that throws at import fails naming the file", async () => {
+    await writeMarkerPolicy("org.ts", `throw new Error("policy exploded");\n`);
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/policy exploded/);
+  });
+
+  test("a check that throws fails the build rather than silently producing nothing", async () => {
+    await writeMarkerPolicy(
+      "org.ts",
+      `export const c = { id: "X", description: "d", check: () => { throw new Error("check exploded"); } };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/check exploded/);
+  });
+
+  test("armed, loadPolicyChecks refuses rather than importing project code here", async () => {
+    await writeMarkerPolicy();
+    armSandboxPolicyExecution();
+
+    await expect(loadPolicyChecks(["org.ts"], testDir)).rejects.toThrow(/Cannot load lint\.policies .* under --sandbox/);
+    expect(marker(TOP_MARKER)).toBeUndefined();
+  });
+
+  test("no policies declared means no child at all", async () => {
+    armSandboxPolicyExecution();
+
+    expect(await run([])).toEqual([]);
+  });
+
+  test("a program that runs a policy child EXITS — the child is not left holding the event loop", async () => {
+    // Found the hard way while measuring #1131's cost: unlike the run and
+    // config drivers, the policy driver keeps a `message` listener registered
+    // in order to RECEIVE its input, and a `message` listener refs the IPC
+    // channel — so the child stayed alive after answering, and its live channel
+    // kept the parent alive too. `chant build` hid it (`cli/main.ts` ends in
+    // `process.exit`); anything embedding chant as a library hung forever.
+    //
+    // Asserted the only way that actually proves it: run a real program in a
+    // real process and require it to exit on its own.
+    await writeFile(
+      join(testDir, "org.ts"),
+      `export const c = { id: "X", description: "d", check: () => [] };\n`,
+    );
+    const script = join(testDir, "driver.mts");
+    await writeFile(
+      script,
+      `import { runPoliciesSandboxed } from ${JSON.stringify(join(import.meta.dirname, "policy-run.ts"))};\n` +
+        `await runPoliciesSandboxed({\n` +
+        `  policyPaths: [${JSON.stringify(join(testDir, "org.ts"))}],\n` +
+        `  buildResult: { outputs: new Map(), entities: new Map(), warnings: [], errors: [], sourceFileCount: 0 },\n` +
+        `  projectRoot: ${JSON.stringify(testDir)},\n` +
+        `});\n` +
+        `console.log("done");\n`,
+    );
+
+    const exited = await new Promise<{ code: number | null; timedOut: boolean }>((resolvePromise) => {
+      const child = spawn(process.execPath, ["--import", "tsx", script], { stdio: "ignore" });
+      const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        resolvePromise({ code: null, timedOut: true });
+      }, 60_000);
+      child.on("exit", (code) => {
+        clearTimeout(timer);
+        resolvePromise({ code, timedOut: false });
+      });
+    });
+
+    expect(exited.timedOut, "the process did not exit — a sandbox child is holding the event loop open").toBe(false);
+    expect(exited.code).toBe(0);
+  });
+});