@intentius/chant 0.124.13 → 0.124.14

package/dist/discovery/sandbox/driver.js

@@ -0,0 +1,333 @@
+import { dirname, join } from "node:path";
+import { params as currentBuildParams } from "../../params.js";
+import { chantSourceDir } from "../../ts-loader.js";
+/**
+ * chant #1045 Phase 2 — generates the source of the "driver" module that runs
+ * INSIDE the sandboxed child. See `./run.ts` for the orchestration this feeds
+ * (bundle the generated source with esbuild, then spawn a permission-limited
+ * child on the bundle) and `../fold-import.ts`'s long doc comment for why
+ * every run-fallback file for a build must execute together, in one process,
+ * sharing one module graph.
+ *
+ * The driver imports each run-fallback file via a LITERAL string specifier
+ * dynamic `import()` — not a variable — so esbuild's bundler can still trace
+ * and inline it (verified: esbuild lowers a literal-specifier `import()` to a
+ * lazily-invoked local module initializer, not a runtime resolution), while
+ * keeping the SAME per-file try/catch resilience `discover()`'s own run loop
+ * has today (one file throwing at import time doesn't take down the whole
+ * batch). A literal, per-build-generated import graph is exactly what lets
+ * the whole bundle be self-contained: esbuild resolves every project file,
+ * lexicon package, and node_modules dependency transitively, ONCE, so the
+ * sandboxed child never needs to resolve a module from disk at runtime.
+ *
+ * Chant's own trusted collection/resolution/encoding step
+ * (`collectEntities`/`resolveAttrRefs`/`encodeEntitySet`) runs INSIDE the
+ * child too, after every file has been imported — this is what lets naming
+ * and AttrRef resolution happen "inside the boundary" for the run-fallback
+ * set (mirrors `discoverEntitySetJson`'s doc in `../entity-wire.ts`), so the
+ * child can hand back a fully-named, ref-resolved `EntitySetWire` rather than
+ * raw, identity-bearing module exports that couldn't cross the process
+ * boundary at all.
+ */
+// #3878: the TypeScript source, also when this module runs compiled from dist/.
+const HERE = chantSourceDir(import.meta.url);
+const DISCOVERY_DIR = join(HERE, "..");
+/** Absolute paths to chant's OWN trusted modules the generated driver imports — always resolved relative to THIS file's own location on disk, so this works whether chant is running from the monorepo or from a consumer's `node_modules` (both route runtime resolution at `src/*.ts` — see `packages/core/package.json`'s `development`/`default` export conditions). */
+const COLLECT_MODULE = join(DISCOVERY_DIR, "collect.ts");
+const RESOLVE_MODULE = join(DISCOVERY_DIR, "resolve.ts");
+// The pure codec, NOT `entity-wire.ts` — that file also exports
+// `discoverEntitySetJson`, which pulls in `discover()` → `fold-import` →
+// the `typescript` compiler package. See `../entity-wire.ts`'s module doc.
+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");
+// 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");
+// chant #1108 — the shared build-time params module (../params.ts). The child
+// process starts with its own, EMPTY copy of that module's `params` object;
+// without re-binding, every run-fallback file imported in the child would see
+// `params.* === undefined` while the fold path (which substitutes values in
+// the PARENT) sees the resolved values — the exact split-brain #1064 exists
+// to prevent. esbuild resolves a project file's own
+// `import { params } from "@intentius/chant/params"` to this same absolute
+// file, so the driver's `setBuildParams` call below mutates the one object
+// every bundled import observes.
+const PARAMS_MODULE = join(dirname(DISCOVERY_DIR), "params.ts");
+/** Escape a value for embedding as a JS/TS source-level literal. */
+function lit(value) {
+    return JSON.stringify(value);
+}
+/**
+ * chant#2461 — the `send` every driver uses, as generated source lines.
+ *
+ * `process.send` is asynchronous: it queues the message on the IPC channel and
+ * returns. Node's contract is that the optional callback runs once the message
+ * has been written, or with an error if it could not be. Without the callback a
+ * failed send is not reported to the caller at all, so the driver could return
+ * from `main()` believing it had answered.
+ *
+ * So `send` returns a promise that settles only when the write has completed,
+ * and every call site awaits it before `main()` returns. A send that fails, or
+ * throws synchronously (a payload that cannot be serialized), writes the reason
+ * to stderr with a synchronous `writeSync` and exits 1. That way a result that
+ * never left the child cannot end as exit 0 with empty stderr, which is the
+ * signature that looks like success went missing.
+ *
+ * `before` is spliced in at the top of the function body (the run driver marks
+ * itself `reported` there).
+ */
+export function sendFunctionSource(before = []) {
+    return [
+        `function send(payload) {`,
+        ...before.map((line) => `  ${line}`),
+        `  if (typeof process.send !== "function") {`,
+        `    console.log(JSON.stringify(payload));`,
+        `    return Promise.resolve();`,
+        `  }`,
+        `  return new Promise((resolve) => {`,
+        `    const lost = (err) => {`,
+        `      writeSync(2, "chant: the sandboxed child could not hand its result to the parent: " +`,
+        `        (err && err.message ? err.message : String(err)) + " (chant#2461)\\n");`,
+        `      process.exit(1);`,
+        `    };`,
+        `    try {`,
+        `      process.send(payload, (err) => (err ? lost(err) : resolve()));`,
+        `    } catch (err) {`,
+        `      lost(err);`,
+        `    }`,
+        `  });`,
+        `}`,
+    ];
+}
+/**
+ * Generate the driver module's full TypeScript source. Written to a tmp file
+ * and bundled (see `./bundle.ts`) before being handed to a sandboxed child —
+ * never executed directly by the parent process.
+ */
+export function generateDriverSource(options) {
+    const { files, buildRoot } = options;
+    const lines = [
+        `import { collectEntities } from ${lit(COLLECT_MODULE)};`,
+        `import { resolveAttrRefs } from ${lit(RESOLVE_MODULE)};`,
+        `import { encodeEntitySet } from ${lit(ENTITY_WIRE_CODEC_MODULE)};`,
+        `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
+        `import { getProvenance } from ${lit(PROVENANCE_MODULE)};`,
+        `import { setBuildParams } from ${lit(PARAMS_MODULE)};`,
+        `import { writeSync } from "node:fs";`,
+        ``,
+        `const BUILD_ROOT = ${lit(buildRoot)};`,
+        ``,
+        // chant #1108 — a snapshot of the PARENT's resolved build-time parameter
+        // values, embedded as a literal at generation time (the parent bound them
+        // via applyBuildParams/discover() before this source was generated).
+        // Values are declared-scalar only (BuildParamValue), so JSON round-trips
+        // them exactly. Bound before any project import below.
+        `setBuildParams(${lit({ ...currentBuildParams })});`,
+        ``,
+        // chant#2461 — which file was being imported when the loop drained.
+        //
+        // A project file whose module scope awaits something that never settles
+        // makes its `await import(...)` never complete. Nothing keeps the loop
+        // alive, so Node exits 0 having sent nothing, and `main().catch` never
+        // fires because an unsettled promise is not a rejection. The parent then
+        // knows only that the child vanished.
+        //
+        // The child DOES know, right up to the moment it exits. `process.on("exit")`
+        // runs synchronously, so it cannot `process.send` — that is asynchronous and
+        // the channel will never be serviced — but a synchronous `writeSync` to fd 2
+        // lands, and the parent already captures and forwards stderr.
+        `let importing;`,
+        `let reported = false;`,
+        `process.on("exit", () => {`,
+        `  if (reported || importing === undefined) return;`,
+        `  writeSync(2, "chant: this file's module scope never finished evaluating, so the build could not " +`,
+        `    "report anything: " + importing + "\\n  A top-level \`await\` that never settles does this. " +`,
+        `    "Nothing is thrown, so nothing else can name it (chant#2461).\\n");`,
+        `});`,
+        ``,
+        ...sendFunctionSource([`reported = true;`]),
+        ``,
+        // collectEntities (bundled, real DiscoveryError instances) already names
+        // the exact offending file on a same-directory duplicate — reuse that
+        // instead of reporting an empty file, which is what forwarding a bare ""
+        // through classifyChildError would otherwise do.
+        `function errFile(err) {`,
+        `  return err && typeof err === "object" && typeof err.file === "string" ? err.file : "";`,
+        `}`,
+        ``,
+        `async function main() {`,
+        `  const modules = [];`,
+        `  const errors = [];`,
+    ];
+    for (const file of files) {
+        lines.push(`  importing = ${lit(file)};`, `  try {`, `    const mod = await import(${lit(file)});`, `    modules.push({ file: ${lit(file)}, exports: mod });`, `  } catch (err) {`, `    errors.push(classifyChildError(${lit(file)}, err).toJSON());`, `  }`, `  importing = undefined;`);
+    }
+    lines.push(``, `  let entities = new Map();`, `  try {`, `    entities = collectEntities(modules, BUILD_ROOT);`, `  } catch (err) {`, `    errors.push(classifyChildError(errFile(err), err, "resolution").toJSON());`, `    await send({ entitySet: { entities: [] }, errors, provenanceByName: {} });`, `    return;`, `  }`, ``, 
+    // Recorded BEFORE resolveAttrRefs/encode — not for the parent's own
+    // entities (it never sees this subset's raw exports at all), but so a
+    // parent-side merge collision against the fold-only set (chant#1045
+    // Phase 2 — a same-directory bare name genuinely exported twice, once
+    // folded, once run) can name the real run-fallback file instead of the
+    // entity name. See discover()'s merge step in ../index.ts.
+    `  const provenanceByName = {};`, `  for (const [name, entity] of entities) {`, `    const prov = getProvenance(entity);`, `    if (prov?.sourceFile) provenanceByName[name] = prov.sourceFile;`, `  }`, ``, `  try {`, `    resolveAttrRefs(entities);`, `  } catch (err) {`, `    errors.push(classifyChildError("", err, "resolution").toJSON());`, `  }`, ``, `  let entitySet;`, `  try {`, `    entitySet = encodeEntitySet(entities);`, `  } catch (err) {`, `    errors.push(classifyChildError("", err, "resolution").toJSON());`, `    await send({ entitySet: { entities: [] }, errors, provenanceByName });`, `    return;`, `  }`, `  await send({ entitySet, errors, provenanceByName });`, `}`, ``, `main().catch((err) =>`, `  send({ entitySet: { entities: [] }, errors: [classifyChildError("", err).toJSON()], provenanceByName: {}, fatal: true }),`, `);`);
+    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) {
+    return [
+        `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
+        `import { scanConfigWireSafety } from ${lit(CONFIG_WIRE_MODULE)};`,
+        `import { writeSync } from "node:fs";`,
+        ``,
+        ...sendFunctionSource(),
+        ``,
+        `async function main() {`,
+        `  let namespace;`,
+        `  try {`,
+        `    namespace = await import(${lit(configPath)});`,
+        `  } catch (err) {`,
+        `    await 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) {`,
+        `    await send({ kind: "chant-config", ok: false, offenders });`,
+        `    return;`,
+        `  }`,
+        ``,
+        `  let config;`,
+        `  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.
+        `    config = JSON.parse(JSON.stringify(selected ?? {}));`,
+        `  } catch (err) {`,
+        `    await send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err, "resolution").toJSON() });`,
+        `    return;`,
+        `  }`,
+        `  await send({ kind: "chant-config", ok: true, config });`,
+        `}`,
+        ``,
+        `main().catch((err) =>`,
+        `  send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err).toJSON() }),`,
+        `);`,
+    ].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) {
+    const lines = [
+        `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
+        `import { decodePolicyBuildResult, scanPolicyDiagnostics, PolicyWireError } from ${lit(POLICY_WIRE_MODULE)};`,
+        `import { runPostSynthChecks, isPostSynthCheck } from ${lit(POST_SYNTH_MODULE)};`,
+        `import { writeSync } from "node:fs";`,
+        ``,
+        ...sendFunctionSource(),
+        ``,
+        `function fail(file, err, type) {`,
+        `  if (err instanceof PolicyWireError) {`,
+        `    return 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) {`,
+        `    await 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) {`, `    await fail(${lit(policyPath)}, err, "import");`, `    return;`, `  }`);
+    }
+    lines.push(``, `  let diagnostics;`, `  try {`, `    diagnostics = runPostSynthChecks(checks, buildResult, request.env ?? undefined);`, `  } catch (err) {`, `    await fail("", err, "resolution");`, `    return;`, `  }`, ``, `  await 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/dist/discovery/sandbox/fork.js

@@ -0,0 +1,229 @@
+import { fork } from "node:child_process";
+/**
+ * chant #1148 — buffers arbitrary chunks and calls `emit` once per complete
+ * line, never on a chunk boundary that happens to split a line in two (a
+ * pipe makes no promise that one `write()` on the child's side arrives as one
+ * `data` event on ours). `flush()` emits whatever partial line never got a
+ * trailing newline, so the last unterminated write doesn't silently vanish
+ * when the stream ends — the same no-dropping stance this whole feature
+ * exists for.
+ */
+function lineBuffered(emit) {
+    let pending = "";
+    return {
+        push(chunk) {
+            pending += chunk.toString();
+            let newlineAt = pending.indexOf("\n");
+            while (newlineAt !== -1) {
+                emit(pending.slice(0, newlineAt));
+                pending = pending.slice(newlineAt + 1);
+                newlineAt = pending.indexOf("\n");
+            }
+        },
+        flush() {
+            if (pending.length > 0) {
+                emit(pending);
+                pending = "";
+            }
+        },
+    };
+}
+/**
+ * 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).
+ */
+/**
+ * Why a child ended without a usable result, in terms a reader can act on.
+ *
+ * chant#2461 — this used to be one sentence, `child exited before reporting
+ * results (code N, signal S)`, for three unrelated situations. The one that
+ * was observed in the wild is the hardest to read: exit code 0, empty stderr,
+ * no message. That reads like the child was cut off, and it was not: it ran
+ * to completion.
+ *
+ * The observed case turned out to be the parent's fault. A config child that
+ * sent its result and exited could have its `exit` dispatched here BEFORE its
+ * already-written `message`, and the old `exit` handler settled on the spot.
+ * The payload arrived a moment later and was ignored. Stress runs of the real
+ * `evaluateConfigSandboxed`, 24 at a time under 16 CPU hogs, lost 3 of 800 and
+ * 13 of 1500 that way. An earlier test that blocked the parent had seen
+ * `message` win 60 of 60, which is why this was ruled out for a while.
+ * {@link settleOnExitAfterChannelDrains} closes it by not reading the exit
+ * until the IPC channel has drained. Every driver also awaits its
+ * `process.send` callback and exits 1 with a stderr line if the send fails
+ * (see `./driver.ts`'s `sendFunctionSource`), so a result that never left the
+ * child cannot look like exit 0 either.
+ *
+ * With both of those in place, exit 0 with nothing on stderr and nothing
+ * received has one known cause left: an `await` that never settles.
+ * `main().catch(...)` catches a REJECTION, and a promise that never settles is
+ * not one, so if nothing keeps the loop alive Node drains it and exits 0
+ * having sent nothing. On the RUN path that is reproducible: the driver does
+ * `await import(<project file>)` per run-fallback file, module scope is
+ * arbitrary project source, and a file whose top level never settles makes
+ * that import never complete (the run driver names the file on stderr in that
+ * case). The CONFIG driver bundles to one microtask over synchronous code with
+ * no runtime imports, so on that path the cause is not known, and the message
+ * says so rather than guessing.
+ */
+function describeSilentExit(label, code, signal, stderrBuf, unrecognised) {
+    const stderr = stderrBuf.trim();
+    const head = `${label}: child exited before reporting results (code ${code}, signal ${signal})`;
+    if (unrecognised.length > 0) {
+        // It DID send. The parent refused the shape, which is a bug in one of them
+        // and not the child dying early.
+        const shapes = unrecognised
+            .map((m) => (m && typeof m === "object" ? `{${Object.keys(m).join(", ")}}` : typeof m))
+            .join(", ");
+        return (`${head}. It sent ${unrecognised.length} message(s) the parent did not recognise (${shapes}), ` +
+            `so the payload shape and the parent's check disagree` +
+            (stderr ? `: ${stderr}` : ""));
+    }
+    if (stderr)
+        return `${head}: ${stderr}`;
+    if (code !== 0 || signal !== null)
+        return head;
+    // Exit 0, nothing on stderr, and nothing received even after the IPC
+    // channel drained. See this function's doc for what is and is not left.
+    return (`${head}. It exited cleanly with nothing on stderr, and no message arrived even after its ` +
+        `IPC channel closed, so it never sent one: something it awaited never settled. On the run ` +
+        `path the usual cause is a project file with a top-level \`await\` that does not settle. ` +
+        `Module scope is arbitrary project source, an import of such a file never completes, and a ` +
+        `promise that never settles is not a rejection, so the driver's own \`main().catch\` does ` +
+        `not see it either. The config driver has nothing to await that can hang, and a failed ` +
+        `send exits non-zero with a reason on stderr, so on the config path this has no known ` +
+        `cause: please report it with the command that produced it (chant#2461).`);
+}
+/** How long {@link settleOnExitAfterChannelDrains} waits, after exit, for the IPC channel to report closed. Normally it takes well under a millisecond; this only bounds a channel that never does. */
+const EXIT_DRAIN_GRACE_MS = 2000;
+/**
+ * chant#2461 — call `onExit` once `child` has exited AND its IPC channel has
+ * drained, so a message the child wrote before exiting is always dispatched
+ * first.
+ *
+ * Node does not order `exit` after `message`. The child's exit and the last
+ * bytes on the IPC socket reach the parent's event loop as separate events,
+ * and under load the exit can be handled first even though the child wrote
+ * the message before it exited. Settling on `exit` alone then drops a payload
+ * that is already sitting in the socket. The channel reports `disconnect`
+ * only after it has read EOF, which comes after every message the child
+ * wrote, so waiting for it is exact.
+ *
+ * This is deliberately not `close`. `close` also waits for stdout and stderr
+ * to end, and a grandchild holding those pipes would turn a fast failure into
+ * the full timeout. The wait here is on the IPC channel alone, and is bounded
+ * by `graceMs` in case that channel never reports closed.
+ */
+export function settleOnExitAfterChannelDrains(child, onExit, graceMs = EXIT_DRAIN_GRACE_MS) {
+    child.on("exit", (code, signal) => {
+        let done = false;
+        let grace;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            if (grace !== undefined)
+                clearTimeout(grace);
+            onExit(code, signal);
+        };
+        if (!child.connected) {
+            finish();
+            return;
+        }
+        child.once("disconnect", finish);
+        grace = setTimeout(finish, graceMs);
+    });
+}
+export function forkSandboxed(options, isResponse) {
+    const { bundlePath, bundleDir, projectRealpath, externalReadPaths, env, timeoutMs, label, send, outputPrefix } = 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 = "";
+        /** Messages the child sent that `isResponse` refused — see the `message` handler. */
+        const unrecognised = [];
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill();
+            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}`));
+            });
+        }
+        // chant #1148 — forward, don't just capture. Both streams write to THIS
+        // process's stderr, prefixed and line-buffered, independent of
+        // `stderrBuf` below (which keeps accumulating raw stderr for
+        // `classifyChildError`'s use — forwarded and captured are not mutually
+        // exclusive, the same bytes feed both).
+        const forwardLine = (line) => {
+            process.stderr.write(`${outputPrefix} ${line}\n`);
+        };
+        const stdoutForwarder = lineBuffered(forwardLine);
+        const stderrForwarder = lineBuffered(forwardLine);
+        child.stdout?.on("data", (chunk) => {
+            stdoutForwarder.push(chunk);
+        });
+        child.stdout?.on("end", () => stdoutForwarder.flush());
+        child.stderr?.on("data", (chunk) => {
+            stderrBuf += chunk.toString();
+            stderrForwarder.push(chunk);
+        });
+        child.stderr?.on("end", () => stderrForwarder.flush());
+        child.on("message", (msg) => {
+            if (settled)
+                return;
+            if (!isResponse(msg)) {
+                // chant#2461 — remember it rather than dropping it. A child that sent
+                // something the parent does not recognise is a different failure from
+                // a child that sent nothing, and both used to arrive as "exited before
+                // reporting results" with no way to tell them apart.
+                unrecognised.push(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);
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            reject(err);
+        });
+        // chant#2461 — not `child.on("exit")`: a payload can still be in the IPC
+        // socket when the exit is handled. See settleOnExitAfterChannelDrains.
+        settleOnExitAfterChannelDrains(child, (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            reject(new Error(describeSilentExit(label, code, signal, stderrBuf, unrecognised)));
+        });
+    });
+}