@intentius/chant 0.72.2 → 0.72.4

package/src/cli/mcp-config.test.ts

@@ -0,0 +1,168 @@
+import { describe, test, expect } from "vitest";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { initCommand } from "./commands/init";
+import { doctorCommand } from "./commands/doctor";
+import { updateCommand } from "./commands/update";
+import { parseArgs, commandRegistry } from "./main";
+import { MCP_CONFIG_FILENAME, MCP_SETUP_COMMAND, mcpConfigPath } from "./mcp-config";
+
+/**
+ * chant #2383. `chant init` used to write `mcp.json` into the user's home
+ * directory while `chant doctor` looked for `<project>/.mcp.json` and told
+ * you to run `chant agent setup`, a command the registry never had. Three
+ * sites, three answers, and a project chant had just scaffolded failed
+ * chant's own doctor with an unrunnable fix.
+ *
+ * These tests are written against the agreement rather than against today's
+ * string: the round trip below fails if init and doctor ever pick different
+ * paths again, and the registry check fails if the remediation ever names a
+ * command that is not registered. Neither can be satisfied by editing one
+ * site in isolation.
+ */
+describe("MCP config: one location, three agreeing sites (#2383)", () => {
+  test("init then doctor round-trips: mcp-config passes with no manual step", async () => {
+    await withTestDir(async (testDir) => {
+      const result = await initCommand({
+        path: testDir,
+        lexicon: "aws",
+        skipInstall: true,
+      });
+      expect(result.success).toBe(true);
+
+      const report = await doctorCommand(testDir);
+      const check = report.checks.find((c) => c.name === "mcp-config");
+      expect(check).toBeDefined();
+      expect(check!.status).toBe("pass");
+    });
+  });
+
+  test("init writes the MCP config inside the project it was pointed at", async () => {
+    await withTestDir(async (testDir) => {
+      const result = await initCommand({
+        path: testDir,
+        lexicon: "aws",
+        skipInstall: true,
+      });
+
+      expect(existsSync(mcpConfigPath(testDir))).toBe(true);
+      expect(result.createdFiles).toContain(MCP_CONFIG_FILENAME);
+
+      const config = JSON.parse(readFileSync(mcpConfigPath(testDir), "utf-8"));
+      expect(config.mcpServers.chant.args).toEqual(["chant", "serve", "mcp"]);
+
+      // Every path init reports as created is relative to the project. A
+      // `~/` or absolute entry means init reached outside the directory it
+      // was handed, which is the half of #2383 worth not regressing.
+      for (const file of result.createdFiles) {
+        expect(file.startsWith("~"), `${file} escapes the project`).toBe(false);
+        expect(file.startsWith("/"), `${file} escapes the project`).toBe(false);
+        expect(file.includes(homedir()), `${file} escapes the project`).toBe(false);
+      }
+    });
+  });
+
+  test("--skip-mcp parses and suppresses the write", async () => {
+    // The flag was documented and typed long before anything parsed it, so
+    // assert the parse and the effect together — either one alone passed
+    // while `chant init --skip-mcp` still wrote the file.
+    expect(parseArgs(["init", ".", "--lexicon", "aws", "--skip-mcp"]).skipMcp).toBe(true);
+    expect(parseArgs(["init", ".", "--lexicon", "aws"]).skipMcp).toBeUndefined();
+
+    await withTestDir(async (testDir) => {
+      const result = await initCommand({
+        path: testDir,
+        lexicon: "aws",
+        skipMcp: true,
+        skipInstall: true,
+      });
+      expect(existsSync(mcpConfigPath(testDir))).toBe(false);
+      expect(result.createdFiles).not.toContain(MCP_CONFIG_FILENAME);
+    });
+  });
+
+  test("the doctor's remediation names a registered command", async () => {
+    // Reconstruct the warning the doctor actually emits, then check that the
+    // command inside it exists. `chant agent setup` satisfied neither.
+    await withTestDir(async (testDir) => {
+      writeFileSync(join(testDir, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      const report = await doctorCommand(testDir);
+      const check = report.checks.find((c) => c.name === "mcp-config");
+      expect(check!.status).toBe("warn");
+      expect(check!.message).toContain(MCP_SETUP_COMMAND);
+
+      const named = check!.message!.match(/run ([a-z][a-z -]*)/)?.[1].trim();
+      expect(named).toBeDefined();
+      expect(named!.startsWith("chant ")).toBe(true);
+      const registered = commandRegistry.map((c) => c.name);
+      expect(registered).toContain(named!.slice("chant ".length));
+    });
+  });
+
+  test("the remediation command restores a deleted config", async () => {
+    await withTestDir(async (testDir) => {
+      // A project that has everything except the MCP config: exactly the
+      // state the doctor warns about. `chant init` refuses this directory
+      // without --force, so the remediation has to be something else.
+      mkdirSync(join(testDir, "src"), { recursive: true });
+      writeFileSync(join(testDir, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      writeFileSync(join(testDir, "package.json"), JSON.stringify({ name: "p", type: "module" }));
+
+      expect(MCP_SETUP_COMMAND).toBe("chant update");
+      const result = await updateCommand({ path: testDir });
+      expect(result.success).toBe(true);
+
+      const report = await doctorCommand(testDir);
+      expect(report.checks.find((c) => c.name === "mcp-config")!.status).toBe("pass");
+    });
+  });
+
+  test("update leaves an existing config alone", async () => {
+    await withTestDir(async (testDir) => {
+      writeFileSync(join(testDir, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      writeFileSync(join(testDir, "package.json"), JSON.stringify({ name: "p", type: "module" }));
+      const hand = JSON.stringify({ mcpServers: { chant: { command: "custom" } } }, null, 2);
+      writeFileSync(mcpConfigPath(testDir), hand);
+
+      await updateCommand({ path: testDir });
+
+      expect(readFileSync(mcpConfigPath(testDir), "utf-8")).toBe(hand);
+    });
+  });
+
+  test("every chant command a doctor check tells you to run is registered", async () => {
+    // Broader than the mcp-config check that prompted #2383: whatever the
+    // doctor prints as `run chant <something>`, the registry has to have it.
+    // `chant agent setup` shipped as advice for a command that never existed;
+    // this fails the moment any check does that again.
+    const registered = commandRegistry.map((c) => c.name);
+    expect(registered).not.toContain("agent");
+    expect(registered).not.toContain("agent setup");
+
+    const messages: string[] = [];
+    await withTestDir(async (empty) => {
+      messages.push(...(await doctorCommand(empty)).checks.flatMap((c) => c.message ?? []));
+    });
+    await withTestDir(async (partial) => {
+      writeFileSync(join(partial, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      writeFileSync(join(partial, "package.json"), JSON.stringify({ name: "p" }));
+      mkdirSync(join(partial, "src"), { recursive: true });
+      messages.push(...(await doctorCommand(partial)).checks.flatMap((c) => c.message ?? []));
+    });
+
+    const named = messages.flatMap((m) => [...m.matchAll(/run `?(chant [a-z][a-z0-9 -]*)/g)].map((x) => x[1]));
+    expect(named.length).toBeGreaterThan(0);
+    for (const advice of named) {
+      // Drop flags and the trailing prose the regex may have swept up, then
+      // keep the longest registered name that prefixes what was advised.
+      const words = advice.slice("chant ".length).split(/\s+/).filter((w) => w && !w.startsWith("-"));
+      const match = registered.find((name) => {
+        const parts = name.split(" ");
+        return parts.every((p, i) => words[i] === p);
+      });
+      expect(match, `doctor advises "${advice}", which no registered command matches`).toBeDefined();
+    }
+  });
+});

package/src/cli/mcp-config.ts

@@ -0,0 +1,76 @@
+import { existsSync, writeFileSync } from "fs";
+import { join } from "path";
+
+/**
+ * The one place chant decides where a project's MCP server registration
+ * lives, what goes in it, and which command writes it (chant #2383).
+ *
+ * Before this module the three sites disagreed: `chant init` wrote
+ * `mcp.json` into the user's home directory (picking a harness directory
+ * that happened to exist), `chant doctor` looked for `<project>/.mcp.json`,
+ * and the doctor's remediation named `chant agent setup`, which was never
+ * registered in `./main.ts`. A project chant had just scaffolded therefore
+ * failed chant's own doctor, and the fix the warning named could not be run.
+ *
+ * Project scope wins. The file versions with the project it describes, it
+ * keeps `chant init <dir>` from writing outside `<dir>`, and it is already
+ * what `../agents/discover.ts` treats as the project-scope location when
+ * chant audits an agent installation it did not create. Every consumer must
+ * go through the constants here rather than rebuilding the path, so the
+ * three sites cannot drift apart again without the shared test in
+ * ./mcp-config.test.ts noticing.
+ */
+
+/** Filename of the project-scoped MCP server registration. */
+export const MCP_CONFIG_FILENAME = ".mcp.json";
+
+/**
+ * The command a user runs to (re)write a missing {@link MCP_CONFIG_FILENAME}
+ * in an existing project. `chant init` also writes it, but init refuses a
+ * non-empty directory without `--force`, so the remediation an already
+ * scaffolded project needs is `chant update` — which is also what the
+ * doctor's neighbouring skills check tells you to run for the same reason.
+ * Kept as a constant so ./mcp-config.test.ts can assert it is a command
+ * `commandRegistry` actually registers.
+ */
+export const MCP_SETUP_COMMAND = "chant update";
+
+/** Absolute (or caller-relative) path to a project's MCP config. */
+export function mcpConfigPath(projectDir: string): string {
+  return join(projectDir, MCP_CONFIG_FILENAME);
+}
+
+/**
+ * Detect whether a project uses bun or npm, from its lock file. Lives here
+ * because the package manager is the only variable in the generated config.
+ */
+export function detectPackageManager(dir?: string): "bun" | "npm" {
+  if (dir && (existsSync(join(dir, "bun.lockb")) || existsSync(join(dir, "bun.lock")))) return "bun";
+  return "npm";
+}
+
+/** The MCP registration chant writes: one stdio server named `chant`. */
+export function generateMcpConfig(pm: "bun" | "npm"): string {
+  const config = {
+    mcpServers: {
+      chant: {
+        command: pm === "bun" ? "bunx" : "npx",
+        args: ["chant", "serve", "mcp"],
+      },
+    },
+  };
+
+  return JSON.stringify(config, null, 2);
+}
+
+/**
+ * Write `<projectDir>/.mcp.json` unless one is already there. Returns the
+ * relative path when a file was created, `undefined` when an existing config
+ * was left alone — callers report that difference to the user.
+ */
+export function writeProjectMcpConfig(projectDir: string): string | undefined {
+  const path = mcpConfigPath(projectDir);
+  if (existsSync(path)) return undefined;
+  writeFileSync(path, generateMcpConfig(detectPackageManager(projectDir)));
+  return MCP_CONFIG_FILENAME;
+}

package/src/cli/registry.ts

@@ -101,6 +101,12 @@ export interface ParsedArgs {
   reportFile?: string;
   /** `chant init --skill <name>` filter (added in #95 commit) */
   skill?: string;
+  /**
+   * `chant init --skip-mcp` (#2383) — scaffold without writing the project's
+   * `.mcp.json`. The option existed on `InitOptions` and was documented long
+   * before anything parsed it, so there was no way to decline the write.
+   */
+  skipMcp?: boolean;
   /** `chant import --type <ResourceType>` selector */
   selectType?: string;
   /** `chant import --name <name>` selector */
@@ -341,6 +347,12 @@ export interface ParsedArgs {
   note?: string;
   /** `chant approve <op> <gate> --expire` (#2119) — clear the gate's standing pending fact instead of approving it, so the next run decides the gate from scratch and records a fresh one. Writes no resolution: nothing is approved, the wait is only restarted. */
   expire?: boolean;
+  /**
+   * `chant approve --allow-same-origin` (chant#2384) — record a resolution
+   * from the same channel that reached the gate, which is refused by default
+   * on a model-authored channel.
+   */
+  allowSameOrigin?: boolean;
   /** `chant approve <op> <gate> --plan <digest>` (#2300) — the plan this approval is for, as `sha256:<64 hex>`. Omitted, the digest is taken from the gate's standing pending fact, which is the plan the run that stopped at the gate actually produced; pass it to approve a plan explicitly, or to approve one before any run has recorded a pending fact. */
   plan?: string;
   /** `chant operator log --op <name>` (#2029) — restrict the tick history to one ConvergeOp by name. Omitted, every discovered ConvergeOp's ticks are merged into one timeline. */

package/src/discovery/fold-executing-mode.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { foldProject, foldExecutionCounts, resetFoldExecutionCounts } from "../index";
+
+/**
+ * chant#2455 — `ι = executing`, the third isolation mode (spec `1.8`).
+ *
+ * chant#2453 made the default strict: a declarator call to a declared project
+ * function whose body cannot fold refuses the file rather than importing and
+ * invoking it. That closed a real leak — the fold of a file reading
+ * `process.env` carried the folding shell's environment, under a `fold`
+ * verdict that read as "determined statically".
+ *
+ * The old behaviour is worth having when the caller means it, so it comes back
+ * as a mode. What it cannot be is implicit. `open` is the default and is
+ * strict; a build that wants what a run would compute has to ask, and the
+ * asking is what makes the environment dependence visible.
+ */
+describe("the executing isolation mode (chant#2455)", () => {
+  let root: string;
+  let app: string;
+  let params: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "chant-executing-"));
+    params = join(root, "params.ts");
+    app = join(root, "app.ts");
+    writeFileSync(
+      params,
+      'export function fromEnv() {\n  return { prefix: process.env.CHANT_TEST_MODE ?? "fallback" };\n}\n',
+    );
+    writeFileSync(app, 'import { fromEnv } from "./params";\nexport const v = fromEnv();\n');
+    resetFoldExecutionCounts();
+    process.env.CHANT_TEST_MODE = "from-the-environment";
+  });
+
+  afterEach(() => {
+    delete process.env.CHANT_TEST_MODE;
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  test("the default refuses, and nothing of the project runs", async () => {
+    const verdict = (await foldProject([app, params], [], {})).get(app)!;
+
+    expect(verdict.verdict).toBe("run");
+    expect(foldExecutionCounts().projectFactoryInvocations).toBe(0);
+  });
+
+  test("executing invokes it, and the fold carries what a run would compute", async () => {
+    const verdict = (await foldProject([app, params], [], { executing: true })).get(app)!;
+
+    expect(verdict.verdict).toBe("fold");
+    expect(JSON.parse(JSON.stringify(Object.fromEntries(verdict.exports!)))).toEqual({
+      v: { prefix: "from-the-environment" },
+    });
+    // The counter is how the mode is observable from outside: this is a
+    // project-owned invocation, which is what F-Call step 6 counts.
+    expect(foldExecutionCounts().projectFactoryInvocations).toBe(1);
+  });
+
+  test("the environment dependence is real, which is why the mode has to be asked for", async () => {
+    process.env.CHANT_TEST_MODE = "one";
+    const first = (await foldProject([app, params], [], { executing: true })).get(app)!;
+    process.env.CHANT_TEST_MODE = "two";
+    const second = (await foldProject([app, params], [], { executing: true })).get(app)!;
+
+    // Under `executing` the same source folds to different values in different
+    // environments. That is the mode behaving as specified, not a defect — and
+    // it is exactly what must not happen by default.
+    expect(JSON.stringify([...first.exports!])).not.toBe(JSON.stringify([...second.exports!]));
+  });
+
+  test("sandbox still refuses, and is unchanged by the new mode", async () => {
+    const verdict = (await foldProject([app, params], [], { sandbox: true })).get(app)!;
+
+    expect(verdict.verdict).toBe("run");
+    expect(foldExecutionCounts().projectFactoryInvocations).toBe(0);
+  });
+
+  test("asking for both sandbox and executing is refused rather than resolved", async () => {
+    // Not a preference between two readings — a contradiction. One refuses to
+    // import project code, the other exists to invoke it, and silently picking
+    // either would make the fold's meaning depend on which.
+    await expect(foldProject([app, params], [], { sandbox: true, executing: true })).rejects.toThrow(
+      /mutually exclusive/,
+    );
+  });
+
+  test("the default's reason names the mode that would have folded it", async () => {
+    const reason = (await foldProject([app, params], [], {})).get(app)!.reason!;
+
+    // The body's own diagnostic is kept — it is the actionable half, and here
+    // it says to use a build parameter rather than reach for the new mode.
+    expect(reason).toContain('ambient "process" read is not foldable');
+    expect(reason).toContain("executing");
+  });
+
+  test("a function whose body folds is untouched by the mode", async () => {
+    const helper = join(root, "helper.ts");
+    writeFileSync(helper, 'export function j() {\n  return { j: ["a", "b"].join("-") };\n}\n');
+    const caller = join(root, "caller.ts");
+    writeFileSync(caller, 'import { j } from "./helper";\nexport const v = j();\n');
+
+    for (const options of [{}, { executing: true }]) {
+      resetFoldExecutionCounts();
+      const verdict = (await foldProject([caller, helper], [], options)).get(caller)!;
+      expect(verdict.verdict).toBe("fold");
+      // Interpreted in both modes: `executing` is a fallback for a body that
+      // did NOT fold, not a shortcut past interpretation.
+      expect(foldExecutionCounts().projectFactoryInvocations).toBe(0);
+    }
+  });
+});

package/src/discovery/fold-import.ts

@@ -261,6 +261,8 @@ export interface FoldSession {
    * only the fold half would buy nothing there.
    */
   readonly sandbox: boolean;
+  /** chant#2455 — `ι = executing`: invoke a declared project function whose body did not fold. */
+  readonly executing: boolean;
   /**
    * chant #1023 — per-build memo for {@link readFactoryModule}, keyed by the
    * resolved absolute path of a module that DEFINES a composite. A composite
@@ -322,6 +324,8 @@ export function createFoldSession(
    * named as a specifier rather than only as a lexicon.
    */
   lexiconPackages: readonly string[] = [],
+  /** chant#2455 — `ι = executing`. Mutually exclusive with `sandbox`. */
+  executing = false,
 ): FoldSession {
   return {
     intrinsics,
@@ -332,6 +336,7 @@ export function createFoldSession(
     buildParams,
     lexiconPackages: new Set([...lexicons.map(lexiconPackageName), ...lexiconPackages]),
     sandbox,
+    executing,
     factoryModules: new Map(),
   };
 }
@@ -1275,6 +1280,8 @@ interface ResolveCtx {
   lexiconPackages: ReadonlySet<string>;
   /** chant #1093 — see {@link FoldSession.sandbox}. */
   sandbox: boolean;
+  /** chant#2455 — see {@link FoldSession.executing}. */
+  executing: boolean;
   /**
    * chant #1023 — the whole build session, for the two things composite-factory
    * interpretation needs that a per-file context cannot carry: the
@@ -1458,24 +1465,57 @@ async function resolveCallExpression(node: ts.CallExpression, ctx: ResolveCtx):
       if (!(err instanceof Error)) throw err;
       foldFailure = err;
     }
-    if (!binding) throw foldFailure;
-    // chant#2441 — `F-Div-Depth` is a refusal, not a failure to try hard
-    // enough. The fallback below imports the callee and invokes it, which is
-    // right when its body merely did not fold; here the folder has DECLINED,
-    // and invoking anyway produces exactly the envelope the specification says
-    // must not appear — a value the file's own declarators never produced.
+    // chant#2453 — a DECLARED function is judged by its body, and that is the
+    // whole answer. There is no invocation arm here any more.
     //
-    // Every other `F-Div` row is a fallback and `divergence.md` says so
-    // outright, which is what makes the direction safe. This one is not, so it
-    // propagates and the file runs, which is what the reference does.
-    if (foldFailure instanceof FoldError && foldFailure.refusedAtDepth) throw foldFailure;
-    try {
-      return await resolveImportedCall(node, calleeName, binding, ctx);
-    } catch (err) {
+    // There used to be: when the body did not fold, an imported callee was
+    // imported and invoked instead. chant#2441 narrowed that to stop it
+    // rescuing a depth refusal. The external corpus then showed what the rest
+    // of it does, in a project nobody here maintains
+    // (jhgaylor/infisical-chant, INTENTIUS/typescript-as-data#129):
+    //
+    //     export const namingParams = namingParamsFromEnv();
+    //
+    // whose body reads `process.env`. `F-Eval-Ident` step 4 rejects `process`,
+    // so the body does not fold — and chant imported the module and ran it,
+    // folding the file to whatever the FOLDING PROCESS's environment held. The
+    // file reported `fold`, which reads as "determined statically". Two people
+    // folding the same source got different output and nothing said so.
+    //
+    // That is wrong in chant's own terms before it is wrong in J1's: `--fold`
+    // is the value you would get by running, WITHOUT running, and this ran. So
+    // the rejection propagates and the file runs, carrying the reason
+    // `F-Eval-CallLocal` gives.
+    //
+    // `F-Call` step 6's invocation is for a binding that is neither a declared
+    // function nor an interpretable composite, and it still happens — below,
+    // in the arm this one is not. A composite factory is not a
+    // `FoldableFunction`, so `resolveImportedCall` still interprets it and
+    // still invokes it when interpretation declines.
+    //
+    // chant#2455 — unless the caller asked for `ι = executing` (spec 1.8),
+    // which is this behaviour as a MODE rather than as a silent default. The
+    // value is then what a run would compute in this process, environment and
+    // all, which is exactly why it cannot be implicit.
+    if (ctx.executing && binding) {
+      try {
+        return await resolveImportedCall(node, calleeName, binding, ctx);
+      } catch (err) {
+        throw cheapError(
+          `${foldFailure.message}; invoking it instead failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+    // Name the mode that would have folded it, so the reason is actionable
+    // rather than only correct. Not under `sandbox`, where `executing` is not
+    // an option the caller could take.
+    if (binding && !ctx.sandbox) {
       throw cheapError(
-        `${foldFailure.message}; invoking it instead failed: ${err instanceof Error ? err.message : String(err)}`,
+        `${foldFailure.message} (the default mode does not invoke a declared project function; ` +
+          "`executing` would run it and fold what it returns)",
       );
     }
+    throw foldFailure;
   }
 
   if (!binding) {
@@ -2356,6 +2396,7 @@ async function interpretCompositeFactory(
     resolvePathCache: ctx.resolvePathCache,
     lexiconPackages: ctx.lexiconPackages,
     sandbox: ctx.sandbox,
+    executing: ctx.executing,
     session: ctx.session,
     interpretDepth: ctx.interpretDepth + 1,
     // chant #2161 — set unconditionally, and NOT inherited from `ctx`: a nested
@@ -3668,6 +3709,7 @@ async function tryFoldFileCore(file: string, session: FoldSession): Promise<Fold
       resolvePathCache: session.resolvePathCache,
       lexiconPackages: session.lexiconPackages,
       sandbox: session.sandbox,
+      executing: session.executing,
       session,
       interpretDepth: 0,
       // chant#2423 — filled by the pre-build below, read by
@@ -4102,6 +4144,25 @@ export interface FoldProjectOptions {
   readonly buildParams?: Readonly<Record<string, BuildParamValue>>;
   /** chant #1093: this build asked for the sandbox, so fold may not reach outside the trusted allowlist. */
   readonly sandbox?: boolean;
+  /**
+   * chant#2455 — opt in to `ι = executing`, the third isolation mode
+   * (typescript-as-data spec `1.8`).
+   *
+   * Under it, a declarator call to a declared project function whose body
+   * cannot fold continues at `F-Call` step 6 and is invoked, so the fold's
+   * value is what a run would compute **in the folding process's
+   * environment**. That is the behaviour chant had before #2453, where it was
+   * the silent default and leaked the folding shell's `process.env` into the
+   * output of a file reported as `fold`.
+   *
+   * It is here as a mode rather than gone, because the value is real when the
+   * caller means it. What it cannot be is implicit: `open` is the default and
+   * is strict, so a build that wants a run's answer has to say so.
+   *
+   * Mutually exclusive with {@link sandbox}, which refuses to import project
+   * code at all. Asking for both is a contradiction and refuses.
+   */
+  readonly executing?: boolean;
   /**
    * chant#2438 — package specifiers to follow a bare import into, verbatim,
    * alongside whatever `lexicons` names.
@@ -4158,12 +4219,24 @@ export async function foldProject(
   intrinsics: readonly IntrinsicDef[] = [],
   options: FoldProjectOptions = {},
 ): Promise<Map<string, FoldProjectVerdict>> {
+  // chant#2455 — `sandbox` refuses to import project code at all and
+  // `executing` exists to invoke it. Asking for both is not a preference
+  // between two readings, it is a contradiction, and silently picking one would
+  // make the fold's meaning depend on which.
+  if (options.sandbox === true && options.executing === true) {
+    throw new Error(
+      "foldProject: `sandbox` and `executing` are mutually exclusive — the first refuses to import " +
+        "project code and the second exists to invoke it. Pass one.",
+    );
+  }
+
   const session = createFoldSession(
     intrinsics,
     options.buildParams,
     options.lexicons ?? [],
     options.sandbox ?? false,
     options.lexiconPackages ?? [],
+    options.executing ?? false,
   );
   const attempts = new Map<string, FoldFileResult>();
   for (const file of files) attempts.set(file, await tryFoldFile(file, intrinsics, session));