@intentius/chant 0.19.0 → 0.20.0

package/src/discovery/sandbox/bundle.ts

@@ -0,0 +1,218 @@
+import * as esbuild from "esbuild";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve as resolvePath } from "node:path";
+
+/**
+ * chant #1045 Phase 2 — bundles the generated sandbox driver (`./driver.ts`)
+ * into one self-contained ESM file with esbuild, so the sandboxed child never
+ * needs to resolve a module from disk at runtime (see `./driver.ts`'s doc for
+ * why that's what lets the permission allowlist stay this narrow).
+ *
+ * A fresh temp directory per call — not a shared cache directory — keeps
+ * concurrent builds (nested stacks, parallel test workers) from racing on the
+ * same output path; callers are responsible for cleaning it up (`./run.ts`
+ * does, in a `finally`) once the child has reported back.
+ */
+
+const HERE = import.meta.dirname;
+const require = createRequire(import.meta.url);
+
+/**
+ * Packages that must NOT be bundled — see {@link resolveExternalPackages}'s
+ * doc for why. Every lexicon that ships a lint rule doing AST-based analysis
+ * (`aws`, `azure`, `fly`, `gcp`, `github`, `gitlab`, `helm`, `k8s` all do)
+ * imports `typescript` at the top of that rule module, and lexicon plugin
+ * objects re-export their lint rules eagerly — so bundling ANY run-fallback
+ * file that imports a lexicon package pulls `typescript` in transitively,
+ * every time, not just for the rare file that uses the compiler itself.
+ */
+const EXTERNAL_PACKAGES = ["typescript"];
+
+/**
+ * Resolve each of {@link EXTERNAL_PACKAGES} to its real, absolute path on
+ * disk (from THIS file's own location — the same package.json dependency
+ * chant's own `fold-import.ts` already resolves "typescript" through) and
+ * return an esbuild plugin that rewrites any import of that bare specifier
+ * to the resolved absolute path, marked external.
+ *
+ * Why external at all: `typescript` is itself a large, over-eager CJS
+ * package — its own internal `getNodeSystem()`-style helpers call
+ * `require("fs")`/`require("path")` from deep inside factory functions, not
+ * from top-level imports esbuild can safely rewrite. Bundled into ESM
+ * output, that nested `require` has no real binding and esbuild's shim
+ * throws `Dynamic require of "fs" is not supported` — a build that just
+ * transitively imports `typescript` never even gets to execute the run-
+ * fallback file it was meant for. Left external and resolved to an absolute
+ * path, Node loads the REAL `typescript` package directly (no bare-specifier
+ * `node_modules` walk needed, so no broader `--allow-fs-read` grant beyond
+ * that one resolved path — see `./run.ts`), with its own native `require`
+ * intact — no interop shim, no problem.
+ *
+ * `typescript` is trusted, chant-shipped infrastructure (a dependency of
+ * chant itself and every lexicon that lints), never something project
+ * source controls the content of, so resolving and exposing it this way
+ * doesn't weaken the boundary around untrusted project code.
+ */
+/**
+ * chant #1020 hang fix — process-wide memo for resolving {@link
+ * EXTERNAL_PACKAGES} from {@link HERE}. Both are fixed constants (this
+ * file's own location, and a hardcoded package list) — the answer can never
+ * change for the lifetime of the process, so caching it is exactly as safe
+ * as Node's own assumption that a running process's `node_modules` doesn't
+ * shift under it. `require.resolve(name, { paths: [HERE] })` is ordinarily
+ * cheap, but profiling traced it to the same pathological slowness (upwards
+ * of a minute) as `../fold-import.ts`'s `resolveModulePath` — see that
+ * file's `bareSpecifierPathCache` doc for the full mechanism: this is the
+ * SAME underlying cost (`createRequire`/`require.resolve`'s bare-specifier
+ * branch, first call inside a session started right after vitest's
+ * `vi.resetModules()`), just reached via `bundleDriver()` (called once per
+ * `runFallbackFilesSandboxed()`) instead of a cross-file fold resolution.
+ *
+ * Parked on `globalThis`, not a plain module-level `const`: unlike
+ * `fold-import.ts` (reached only via a STATIC import chain from the test
+ * file's own top-level import, so vite-node never re-evaluates it),
+ * `./bundle.ts` is reached only through `./run.ts`'s dynamic
+ * `await import("./sandbox/run")` (deliberately dynamic — see that file's
+ * own doc on why). `vi.resetModules()` DOES re-evaluate a module reached
+ * only dynamically, which would re-run this file's whole top level and
+ * silently replace a plain module-level cache with a fresh, empty `Map` on
+ * every retry — measured to happen intermittently (which call site hits the
+ * slow, uncached path first varies run to run), reproducing the exact same
+ * multi-minute stall this fix exists to remove. A `globalThis` slot is
+ * outside any module's own scope, so it survives being re-evaluated.
+ */
+function getExternalPackagePathCache(): Map<string, string | undefined> {
+  const g = globalThis as { __chantExternalPackagePathCache?: Map<string, string | undefined> };
+  return (g.__chantExternalPackagePathCache ??= new Map());
+}
+
+/**
+ * chant #1020 hang fix — best-effort fast path mirroring
+ * `../fold-import.ts`'s `fastResolveBareSpecifier` (see its own doc for the
+ * full mechanism and why this is faster than `require.resolve` at all):
+ * walks `node_modules` from `fromDir` with plain `existsSync`/`readFileSync`
+ * and reads `package.json`'s "main" field by hand (`typescript` ships no
+ * "exports" field, just "main" — verified), never throwing. Returns
+ * `undefined` for anything it doesn't confidently recognize, so the caller
+ * falls back to the slow-but-authoritative `require.resolve`.
+ */
+function fastResolvePackage(specifier: string, fromDir: string): string | undefined {
+  let dir = fromDir;
+  for (;;) {
+    const packageDir = join(dir, "node_modules", specifier);
+    if (existsSync(packageDir)) {
+      const pkgJsonPath = join(packageDir, "package.json");
+      if (!existsSync(pkgJsonPath)) return undefined;
+      let pkg: unknown;
+      try {
+        pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+      } catch {
+        return undefined;
+      }
+      if (typeof pkg !== "object" || pkg === null || (pkg as Record<string, unknown>).exports !== undefined) {
+        return undefined; // has an "exports" field — not the simple shape this fast path handles
+      }
+      const main = (pkg as Record<string, unknown>).main;
+      const entry = typeof main === "string" ? main : "index.js";
+      const resolved = resolvePath(packageDir, entry);
+      if (!existsSync(resolved) || !statSync(resolved).isFile()) return undefined;
+      try {
+        return realpathSync(resolved);
+      } catch {
+        return undefined;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+function externalTrustedPackagesPlugin(): { plugin: esbuild.Plugin; readPaths: string[] } {
+  const readPaths: string[] = [];
+  const resolved = new Map<string, string>();
+  const pathCache = getExternalPackagePathCache();
+
+  for (const name of EXTERNAL_PACKAGES) {
+    try {
+      let path = pathCache.get(name);
+      if (path === undefined && !pathCache.has(name)) {
+        // chant #1020 hang fix — try the same fast, plain-fs node_modules
+        // walk `../fold-import.ts`'s `fastResolveBareSpecifier` uses before
+        // falling back to `require.resolve`'s pathologically-slow-when-cold
+        // path (see this file's own `getExternalPackagePathCache` doc).
+        path = fastResolvePackage(name, HERE) ?? require.resolve(name, { paths: [HERE] });
+        pathCache.set(name, path);
+      }
+      if (path === undefined) continue; // cached miss — see the catch below
+      resolved.set(name, path);
+      readPaths.push(dirname(path));
+    } catch {
+      pathCache.set(name, undefined);
+      // Not installed/resolvable from here — nothing to externalize; a run-
+      // fallback file that imports it will simply fail to resolve inside the
+      // sandbox, same as any other genuinely missing dependency would.
+    }
+  }
+
+  const plugin: esbuild.Plugin = {
+    name: "chant-sandbox-external-trusted-packages",
+    setup(build) {
+      for (const [name, path] of resolved) {
+        const filter = new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`);
+        build.onResolve({ filter }, () => ({ path, external: true }));
+      }
+    },
+  };
+
+  return { plugin, readPaths };
+}
+
+export interface BundleResult {
+  /** Absolute, REALPATH'd path to the bundled entry file — this and {@link bundleDir} are what the caller grants `--allow-fs-read` to. macOS's `/tmp` is a symlink to `/private/tmp`; an un-canonicalized path here would silently fail to match Node's own (already-canonicalized) permission check. */
+  bundlePath: string;
+  /** Absolute, REALPATH'd directory containing {@link bundlePath} — remove with `rmSync(bundleDir, { recursive: true, force: true })` once done. */
+  bundleDir: string;
+  /** Directories the child ALSO needs `--allow-fs-read` for — the resolved locations of {@link EXTERNAL_PACKAGES}, which are deliberately left unbundled (see {@link externalTrustedPackagesPlugin}'s doc). Empty when none of those packages were actually imported. */
+  externalReadPaths: string[];
+  /** Wall-clock bundling time — chant#1045 asks this be measured and reported, not silently accepted. */
+  durationMs: number;
+  /** Bundle size in bytes. */
+  bytes: number;
+}
+
+/**
+ * Bundle `driverSource` (see {@link import("./driver").generateDriverSource})
+ * into a single self-contained ESM file.
+ */
+export async function bundleDriver(driverSource: string): Promise<BundleResult> {
+  const bundleDir = realpathSync(mkdtempSync(join(tmpdir(), "chant-sandbox-")));
+  const entryPath = join(bundleDir, "driver.mts");
+  writeFileSync(entryPath, driverSource, "utf-8");
+  const outfile = join(bundleDir, "child.mjs");
+
+  const { plugin, readPaths } = externalTrustedPackagesPlugin();
+
+  const start = performance.now();
+  try {
+    await esbuild.build({
+      entryPoints: [entryPath],
+      outfile,
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      absWorkingDir: bundleDir,
+      logLevel: "silent",
+      plugins: [plugin],
+    });
+  } catch (err) {
+    rmSync(bundleDir, { recursive: true, force: true });
+    throw err;
+  }
+  const durationMs = performance.now() - start;
+  const bytes = statSync(outfile).size;
+
+  return { bundlePath: outfile, bundleDir, externalReadPaths: readPaths, durationMs, bytes };
+}

package/src/discovery/sandbox/child-errors.ts

@@ -0,0 +1,65 @@
+import { DiscoveryError, type DiscoveryErrorType } from "../../errors";
+
+/**
+ * chant #1045 Phase 2 — turns whatever the sandboxed child's per-file import
+ * (or its own collect/resolve/encode step) throws into an actionable chant
+ * {@link DiscoveryError} that names the file AND the operation, instead of
+ * leaking a raw `ERR_ACCESS_DENIED` with no context.
+ *
+ * This module is bundled INTO the generated sandbox driver (see `./driver.ts`)
+ * — it runs inside the sandboxed child, alongside the untrusted project
+ * source it's classifying errors for — so it must not import anything that
+ * isn't already safe to bundle (no filesystem/process access of its own).
+ */
+
+/**
+ * Node's Permission Model error shape for `ERR_ACCESS_DENIED` — see
+ * https://nodejs.org/api/permissions.html#error-classes. `permission` names
+ * the guarded API family (`FileSystemRead`, `FileSystemWrite`,
+ * `ChildProcess`, `WorkerThreads`, `SqliteWrite`, …); `resource` is the
+ * specific path or target that was denied. Verified empirically on Node
+ * v24.13.1 (chant#1045 Phase 2 prototype) — both fields are present on the
+ * thrown `Error` alongside `code`.
+ */
+interface NodePermissionError {
+  code?: unknown;
+  permission?: unknown;
+  resource?: unknown;
+  message?: unknown;
+}
+
+function isPermissionDenied(err: unknown): err is NodePermissionError {
+  return typeof err === "object" && err !== null && (err as NodePermissionError).code === "ERR_ACCESS_DENIED";
+}
+
+/**
+ * Classify one error raised while executing run-fallback project source (or
+ * chant's own collect/resolve/encode step) inside the sandboxed child.
+ *
+ * @param file - The project source file being executed when `err` was
+ *   thrown, or `""` for an error not attributable to one specific file (e.g.
+ *   `collectEntities`/`resolveAttrRefs` over the whole batch).
+ * @param fallbackType - The {@link DiscoveryErrorType} to use when `err`
+ *   isn't a permission denial — mirrors how `discover()` itself types a
+ *   plain import failure `"import"` vs. a collection/resolution failure
+ *   `"resolution"`.
+ */
+export function classifyChildError(
+  file: string,
+  err: unknown,
+  fallbackType: DiscoveryErrorType = "import",
+): DiscoveryError {
+  if (isPermissionDenied(err)) {
+    const operation = typeof err.permission === "string" ? err.permission : "an unrecognized sandboxed operation";
+    const resource = typeof err.resource === "string" ? ` (${err.resource})` : "";
+    const where = file ? `"${file}"` : "sandboxed run-fallback code";
+    return new DiscoveryError(
+      file,
+      `sandbox denied ${operation}${resource}: ${where} attempted an operation outside the sandbox's allowlist`,
+      "permission",
+    );
+  }
+
+  const message = err instanceof Error ? err.message : String(err);
+  return new DiscoveryError(file, message, fallbackType);
+}

package/src/discovery/sandbox/driver.ts

@@ -0,0 +1,147 @@
+import { dirname, join } from "node:path";
+
+/**
+ * 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.
+ */
+
+const HERE = import.meta.dirname;
+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");
+
+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`. */
+  files: readonly string[];
+  /** The build root — threaded to `collectEntities` exactly as `discover()` threads its own `path` argument, so cross-directory stack-prefix disambiguation (chant #932) is computed the same way for this subset. */
+  buildRoot: string;
+}
+
+/** Escape a value for embedding as a JS/TS source-level literal. */
+function lit(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+/**
+ * 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: GenerateDriverOptions): string {
+  const { files, buildRoot } = options;
+
+  const lines: string[] = [
+    `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)};`,
+    ``,
+    `const BUILD_ROOT = ${lit(buildRoot)};`,
+    ``,
+    `function send(payload) {`,
+    `  if (typeof process.send === "function") process.send(payload);`,
+    `  else console.log(JSON.stringify(payload));`,
+    `}`,
+    ``,
+    // 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(
+      `  try {`,
+      `    const mod = await import(${lit(file)});`,
+      `    modules.push({ file: ${lit(file)}, exports: mod });`,
+      `  } catch (err) {`,
+      `    errors.push(classifyChildError(${lit(file)}, err).toJSON());`,
+      `  }`,
+    );
+  }
+
+  lines.push(
+    ``,
+    `  let entities = new Map();`,
+    `  try {`,
+    `    entities = collectEntities(modules, BUILD_ROOT);`,
+    `  } catch (err) {`,
+    `    errors.push(classifyChildError(errFile(err), err, "resolution").toJSON());`,
+    `    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());`,
+    `  }`,
+    ``,
+    `  try {`,
+    `    const entitySet = encodeEntitySet(entities);`,
+    `    send({ entitySet, errors, provenanceByName });`,
+    `  } catch (err) {`,
+    `    errors.push(classifyChildError("", err, "resolution").toJSON());`,
+    `    send({ entitySet: { entities: [] }, errors, provenanceByName });`,
+    `  }`,
+    `}`,
+    ``,
+    `main().catch((err) => {`,
+    `  send({ entitySet: { entities: [] }, errors: [classifyChildError("", err).toJSON()], provenanceByName: {}, fatal: true });`,
+    `});`,
+  );
+
+  return lines.join("\n");
+}

package/src/discovery/sandbox/run.test.ts

@@ -0,0 +1,179 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { runFallbackFilesSandboxed } from "./run";
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+/** Absolute path to `packages/core/src/runtime.ts` — the real `createResource`
+ * factory, imported by the cross-file fixture below exactly as a lexicon
+ * package would be imported by real chant source. */
+const runtimePath = resolve(thisDir, "../../runtime");
+
+/**
+ * chant #1045 Phase 2 — proves the actual isolation properties (not just
+ * byte-identical output, which `examples/sandbox-differential.test.ts`
+ * already covers): a run-fallback file cannot read outside the project
+ * directory, write anywhere, spawn a process, or read the ambient
+ * environment, and a permission denial names the file and the operation
+ * rather than leaking a raw `ERR_ACCESS_DENIED`.
+ *
+ * Fixtures are written to a fresh tmpdir per test, never into the source
+ * tree — a real chant convention here (never write test fixtures into the
+ * source tree), doubly so for this module, whose whole point is running
+ * untrusted-shaped project source.
+ */
+describe("runFallbackFilesSandboxed — isolation", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = await realpath(
+      await (async () => {
+        const dir = join(tmpdir(), `chant-sandbox-run-test-${Date.now()}-${Math.random()}`);
+        await mkdir(dir, { recursive: true });
+        return dir;
+      })(),
+    );
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("denies filesystem reads outside the project directory, naming the file and the operation", async () => {
+    const file = join(testDir, "evil.ts");
+    await writeFile(
+      file,
+      `
+        import { readFileSync } from "node:fs";
+        readFileSync("/etc/hosts", "utf-8");
+        export const value = "unreachable";
+      `,
+    );
+
+    const result = await runFallbackFilesSandboxed([file], testDir);
+
+    expect(result.entities.size).toBe(0);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].file).toBe(file);
+    expect(result.errors[0].type).toBe("permission");
+    expect(result.errors[0].message).toMatch(/FileSystemRead/);
+    expect(result.errors[0].message).toContain(file);
+  });
+
+  test("denies filesystem writes anywhere", async () => {
+    const file = join(testDir, "evil.ts");
+    const targetPath = join(testDir, "..", "escaped.txt");
+    await writeFile(
+      file,
+      `
+        import { writeFileSync } from "node:fs";
+        writeFileSync(${JSON.stringify(targetPath)}, "pwned");
+        export const value = "unreachable";
+      `,
+    );
+
+    const result = await runFallbackFilesSandboxed([file], testDir);
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].type).toBe("permission");
+    expect(result.errors[0].message).toMatch(/FileSystemWrite/);
+    expect(existsSync(targetPath)).toBe(false);
+  });
+
+  test("denies spawning a child process", async () => {
+    const file = join(testDir, "evil.ts");
+    const markerPath = join(testDir, "spawned.txt");
+    await writeFile(
+      file,
+      `
+        import { execSync } from "node:child_process";
+        execSync(${JSON.stringify(`touch ${markerPath}`)});
+        export const value = "unreachable";
+      `,
+    );
+
+    const result = await runFallbackFilesSandboxed([file], testDir);
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].type).toBe("permission");
+    expect(result.errors[0].message).toMatch(/ChildProcess/);
+    expect(existsSync(markerPath)).toBe(false);
+  });
+
+  test("scrubs the ambient environment — a real secret set on the parent's process.env is invisible to project source", async () => {
+    const file = join(testDir, "evil.ts");
+    await writeFile(
+      file,
+      `
+        const seen = process.env.CHANT_SANDBOX_TEST_SECRET;
+        if (seen !== undefined) {
+          throw new Error("ambient env leaked: " + seen);
+        }
+        export const value = { envKeyCount: Object.keys(process.env).length };
+      `,
+    );
+
+    const previous = process.env.CHANT_SANDBOX_TEST_SECRET;
+    process.env.CHANT_SANDBOX_TEST_SECRET = "super-secret-should-not-cross-the-boundary";
+    try {
+      const result = await runFallbackFilesSandboxed([file], testDir);
+      // No error means the fixture's own "if visible, throw" branch never
+      // fired — the plain-object export itself isn't a Declarable, so it
+      // doesn't land in `result.entities` (collectEntities only collects
+      // Declarable/array/composite/LexiconOutput values); absence of the
+      // thrown error is the actual proof here.
+      expect(result.errors).toEqual([]);
+    } finally {
+      if (previous === undefined) delete process.env.CHANT_SANDBOX_TEST_SECRET;
+      else process.env.CHANT_SANDBOX_TEST_SECRET = previous;
+    }
+  });
+
+  test("runs multiple run-fallback files together, sharing module identity for a cross-file reference", async () => {
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    await writeFile(
+      join(testDir, "storage.ts"),
+      `
+        import { Bucket } from "./resources";
+        export const dataBucket = new Bucket({ name: "data" });
+      `,
+    );
+    const policyFile = join(testDir, "policy.ts");
+    await writeFile(
+      policyFile,
+      `
+        import { dataBucket } from "./storage";
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        const Policy = createResource("Test::Policy", "aws", {});
+        export const readPolicy = new Policy({ resource: dataBucket.arn });
+      `,
+    );
+
+    const result = await runFallbackFilesSandboxed(
+      [join(testDir, "resources.ts"), join(testDir, "storage.ts"), policyFile],
+      testDir,
+    );
+
+    expect(result.errors).toEqual([]);
+    expect([...result.entities.keys()].sort()).toEqual(["dataBucket", "readPolicy"]);
+
+    // The cross-file AttrRef (policy.ts's `dataBucket.arn`) must resolve to
+    // storage.ts's `dataBucket` BY NAME — proof the two files shared one
+    // module graph inside the child, not two separately-imported copies
+    // (see ../fold-import.ts's `planFoldTaint` doc for why that distinction
+    // is exactly what would otherwise break).
+    const readPolicy = result.entities.get("readPolicy") as unknown as { props: { resource: unknown } };
+    const ref = readPolicy.props.resource as { getLogicalName?: () => string | undefined; attribute?: string };
+    expect(ref.getLogicalName?.()).toBe("dataBucket");
+    expect(ref.attribute).toBe("Arn");
+  });
+});