@intentius/chant 0.72.2 → 0.72.4

package/src/discovery/fold-no-invoke-declared.test.ts

@@ -0,0 +1,118 @@
+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#2453 — a declared function is judged by its body, never invoked.
+ *
+ * `resolveCallExpression` used to catch a fold failure on an imported callee
+ * and fall back to importing and invoking it. chant#2441 stopped that rescuing
+ * a depth refusal. The external corpus then showed what the rest of it did, in
+ * a project nobody here maintains (jhgaylor/infisical-chant, via
+ * 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 reason this is a correctness bug and not only a conformance divergence:
+ * the file reported `fold`, which reads as "determined statically". Two people
+ * folding the same source got different output, and nothing said so. `--fold`
+ * is the value you would get by running, without running. This ran.
+ */
+describe("a declared function is folded or refused, never invoked (chant#2453)", () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "chant-no-invoke-"));
+    resetFoldExecutionCounts();
+  });
+
+  afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+  const write = (name: string, source: string): string => {
+    const p = join(root, name);
+    writeFileSync(p, source);
+    return p;
+  };
+
+  test("an ambient read inside an imported function refuses, rather than folding the shell's environment in", async () => {
+    const params = write(
+      "params.ts",
+      'export function namingParamsFromEnv() {\n  return { prefix: process.env.CHANT_TEST_PREFIX ?? "fallback" };\n}\n',
+    );
+    const app = write(
+      "app.ts",
+      'import { namingParamsFromEnv } from "./params";\nexport const namingParams = namingParamsFromEnv();\n',
+    );
+
+    process.env.CHANT_TEST_PREFIX = "leaked-from-the-test-runner";
+    try {
+      const verdict = (await foldProject([app, params], [], {})).get(app)!;
+
+      // Before the fix this was `fold` with prefix "leaked-from-the-test-runner".
+      expect(verdict.verdict).toBe("run");
+      expect(verdict.reason).toContain("namingParamsFromEnv");
+
+      // The counter is the direct evidence: nothing of the project was run.
+      expect(foldExecutionCounts().projectFactoryInvocations).toBe(0);
+    } finally {
+      delete process.env.CHANT_TEST_PREFIX;
+    }
+  });
+
+  test("the folded output never depends on the environment, which is the property at stake", async () => {
+    const params = write(
+      "params.ts",
+      'export function fromEnv() {\n  return { v: process.env.CHANT_TEST_SWING ?? "d" };\n}\n',
+    );
+    const app = write("app.ts", 'import { fromEnv } from "./params";\nexport const c = fromEnv();\n');
+
+    // Fold the same source twice under different environments. Before the fix
+    // these disagreed, which is the part no reader of a `fold` verdict could
+    // have known.
+    process.env.CHANT_TEST_SWING = "one";
+    const first = (await foldProject([app, params], [], {})).get(app)!;
+    process.env.CHANT_TEST_SWING = "two";
+    const second = (await foldProject([app, params], [], {})).get(app)!;
+    delete process.env.CHANT_TEST_SWING;
+
+    expect(first.verdict).toBe(second.verdict);
+    expect(first.verdict).toBe("run");
+  });
+
+  test("a function whose body does fold still folds, so this narrows nothing it should not", async () => {
+    const helper = write(
+      "helper.ts",
+      'export function joined() {\n  const parts = ["a", "b"];\n  return { joined: parts.join("-") };\n}\n',
+    );
+    const app = write("app.ts", 'import { joined } from "./helper";\nexport const v = joined();\n');
+
+    const verdict = (await foldProject([app, helper], [], {})).get(app)!;
+
+    expect(verdict.verdict).toBe("fold");
+    expect(JSON.parse(JSON.stringify(Object.fromEntries(verdict.exports!)))).toEqual({
+      v: { joined: "a-b" },
+    });
+    // Folded by interpretation, not by running it.
+    expect(foldExecutionCounts().projectFactoryInvocations).toBe(0);
+  });
+
+  test("a same-file callee behaves the same as an imported one", async () => {
+    // Before the fix these two differed for no reason a reader could defend: a
+    // same-file callee had nothing to import, so its rejection was the verdict,
+    // while the identical function one file over got invoked instead.
+    const app = write(
+      "app.ts",
+      'function fromEnv() {\n  return { v: process.env.CHANT_TEST_SAME ?? "d" };\n}\nexport const c = fromEnv();\n',
+    );
+
+    const verdict = (await foldProject([app], [], {})).get(app)!;
+
+    expect(verdict.verdict).toBe("run");
+  });
+});

package/src/discovery/sandbox/fork-diagnostic.test.ts

@@ -0,0 +1,117 @@
+import { describe, test, expect } from "vitest";
+import { fork } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runFallbackFilesSandboxed } from "./run";
+
+/**
+ * chant#2461 — a child that ends without a usable result says which way it did.
+ *
+ * The parent had one sentence for three unrelated situations: `child exited
+ * before reporting results (code N, signal S)`. The one seen in the wild is the
+ * hardest to read — exit code 0, empty stderr, no message — because it reads as
+ * if the child was cut off, and it was not. It ran to completion and sent
+ * nothing.
+ *
+ * These tests pin the two mechanisms that produce that signature, against real
+ * forked children rather than a mock, because the whole question is what Node
+ * actually does:
+ *
+ *   - an `await` that never settles, which drains the loop and exits 0
+ *   - a payload the parent's `isResponse` refuses, which used to be dropped in
+ *     silence and then reported as though nothing had been sent
+ *
+ * A third mechanism was proposed in the issue and is NOT covered, because it
+ * was measured and does not happen: `process.send` racing the child's reap so
+ * that `exit` is dispatched before an already-queued `message`. With the parent
+ * blocked so both were certainly pending, `message` won 60 times out of 60. The
+ * live IPC channel keeps the child alive until the payload flushes, and the
+ * driver has no `process.exit()` to cut that short. The last test here records
+ * that, so the disproof is not lost with the transcript.
+ */
+function runChild(source: string): Promise<{ code: number | null; message: unknown; stderr: string }> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-fork-diag-"));
+  const file = join(dir, "child.mjs");
+  writeFileSync(file, source);
+  return new Promise((resolve) => {
+    const child = fork(file, [], { stdio: ["ignore", "pipe", "pipe", "ipc"] });
+    let stderr = "";
+    let message: unknown;
+    child.stderr?.on("data", (d: Buffer) => { stderr += d.toString(); });
+    child.on("message", (m) => { message = m; });
+    child.on("exit", (code) => {
+      rmSync(dir, { recursive: true, force: true });
+      resolve({ code, message, stderr });
+    });
+  });
+}
+
+describe("why a sandboxed child ends without a result (chant#2461)", () => {
+  test("an await that never settles exits 0, silently, having sent nothing", async () => {
+    // The observed signature, reproduced. `main().catch(...)` catches a
+    // REJECTION; a promise that never settles is not one, so the driver's own
+    // fatal-payload path never runs either.
+    const r = await runChild(
+      'async function main() { await new Promise(() => {}); process.send({ ok: true }); }\n' +
+        "main().catch((e) => process.send({ fatal: String(e) }));\n",
+    );
+
+    expect(r.code).toBe(0);
+    expect(r.message).toBeUndefined();
+    expect(r.stderr.trim()).toBe("");
+  });
+
+  test("a child that sends and falls off the end always gets its message through", async () => {
+    // The disproof, kept as a test. If this ever fails, the race the issue
+    // proposed is real after all and the diagnostic's wording needs revisiting.
+    const results = await Promise.all(
+      Array.from({ length: 12 }, () => runChild("process.send({ ok: true });\n")),
+    );
+
+    for (const r of results) {
+      expect(r.code).toBe(0);
+      expect(r.message).toEqual({ ok: true });
+    }
+  });
+
+  test("a rejection still reaches the parent, so the fatal path is not what broke", async () => {
+    // Establishes the contrast: the driver's catch works. It is specifically an
+    // unsettled promise that escapes it.
+    const r = await runChild(
+      'async function main() { throw new Error("boom"); }\n' +
+        "main().catch((e) => process.send({ fatal: String(e) }));\n",
+    );
+
+    expect(r.message).toEqual({ fatal: "Error: boom" });
+  });
+
+  test("a project file with an unsettled top-level await reproduces it end to end", async () => {
+    // The run path's real mechanism, not a stand-in. `main()` does
+    // `await import(<project file>)` per run-fallback file, module scope is
+    // arbitrary project source, and a top level that awaits something which
+    // never settles makes that import never complete. Nothing keeps the loop
+    // alive, so Node exits 0 having sent nothing.
+    //
+    // This is what the diagnostic's wording is checked against. Before
+    // chant#2461 it said only "child exited before reporting results", which
+    // gave a reader nothing to look at.
+    const root = mkdtempSync(join(tmpdir(), "chant-tla-"));
+    try {
+      mkdirSync(join(root, "src"), { recursive: true });
+      writeFileSync(
+        join(root, "src", "hangs.ts"),
+        "await new Promise<void>(() => {});\nexport const never = { reached: true };\n",
+      );
+
+      const result = await runFallbackFilesSandboxed([join(root, "src", "hangs.ts")], root);
+
+      const message = result.errors.map((e) => e.message).join("\n");
+      expect(message).toContain("child exited before reporting results (code 0, signal null)");
+      expect(message).toContain("drained its loop without sending");
+      expect(message).toContain("top-level");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }, 120_000);
+});

package/src/discovery/sandbox/fork.ts

@@ -125,6 +125,86 @@ function lineBuffered(emit: (line: string) => void) {
  * 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 and sent nothing.
+ *
+ * Two mechanisms produce it, and the driver decides which is possible.
+ *
+ * The first is 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 and written
+ * nothing. Nothing else in the process reports that.
+ *
+ * On the RUN path that is not hypothetical, and it is reproducible: the driver
+ * does `await import(<project file>)` for each run-fallback file, module scope
+ * is arbitrary project source, and a file whose top level awaits something that
+ * never settles makes that import never complete. A fixture doing exactly that
+ * yields this error, which is how the wording here was checked rather than
+ * guessed.
+ *
+ * The second is the payload being lost between `process.send` and exit.
+ *
+ * For the CONFIG driver the first is impossible, which is worth stating because
+ * it was the working hypothesis until the bundle was read. Its `await
+ * import(configPath)` bundles to `await Promise.resolve().then(() =>
+ * (init_chant_config(), chant_config_exports))` — one microtask over
+ * synchronous code — and the bundle has no runtime imports, no dynamic
+ * `import(`, and exactly one `process.send`. There is nothing there to hang on.
+ * So a config child that exits 0 with nothing sent DID send, and the payload
+ * did not arrive.
+ *
+ * The exit/message race originally proposed in chant#2461 is a third thing and
+ * is not it: with the parent blocked so a queued payload and the reap were both
+ * pending, `message` was dispatched first 60 times out of 60, because the live
+ * IPC channel keeps the child alive until the payload flushes.
+ */
+function describeSilentExit(
+  label: string,
+  code: number | null,
+  signal: NodeJS.Signals | null,
+  stderrBuf: string,
+  unrecognised: readonly unknown[],
+): string {
+  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 as object).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, nothing sent. The child finished normally and
+  // the parent has nothing. Two mechanisms produce exactly this, and which one
+  // it is depends on the driver — see this function's doc.
+  return (
+    `${head}. It exited cleanly with nothing on stderr and sent no message, so the child drained ` +
+    `its loop without sending: 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, and an import of such a file never completes. A promise that ` +
+    `never settles is not a rejection, so the driver's own \`main().catch\` does not see it ` +
+    `either, which is why nothing is written anywhere. The config driver bundles to one ` +
+    `microtask over synchronous code with no runtime I/O, so on THAT path nothing can hang and ` +
+    `the payload was lost between \`process.send\` and exit instead (chant#2461).`
+  );
+}
+
 export function forkSandboxed<T>(
   options: SandboxForkOptions,
   isResponse: (value: unknown) => value is T,
@@ -144,6 +224,8 @@ export function forkSandboxed<T>(
 
     let settled = false;
     let stderrBuf = "";
+    /** Messages the child sent that `isResponse` refused — see the `message` handler. */
+    const unrecognised: unknown[] = [];
 
     const timeout = setTimeout(() => {
       if (settled) return;
@@ -185,7 +267,15 @@ export function forkSandboxed<T>(
     child.stderr?.on("end", () => stderrForwarder.flush());
 
     child.on("message", (msg: unknown) => {
-      if (settled || !isResponse(msg)) return;
+      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
@@ -212,11 +302,7 @@ export function forkSandboxed<T>(
       if (settled) return;
       settled = true;
       clearTimeout(timeout);
-      reject(
-        new Error(
-          `${label}: child exited before reporting results (code ${code}, signal ${signal})${stderrBuf.trim() ? `: ${stderrBuf.trim()}` : ""}`,
-        ),
-      );
+      reject(new Error(describeSilentExit(label, code, signal, stderrBuf, unrecognised)));
     });
   });
 }

package/src/graph-ir.ts

@@ -725,7 +725,7 @@ export function buildLiveGraphIr(observations: LiveObservation[]): GraphIR {
   for (const observation of observations) {
     for (const edge of observation.edges ?? []) {
       if (!observedIds.has(edge.from) || !observedIds.has(edge.to)) continue;
-      const key = `${edge.from}${edge.to}${edge.viaAttr ?? ""}${edge.toAttr ?? ""}`;
+      const key = `${edge.from}\u0000${edge.to}\u0000${edge.viaAttr ?? ""}\u0000${edge.toAttr ?? ""}`;
       if (seen.has(key)) continue;
       seen.add(key);
       edges.push(edge);

package/src/lifecycle/gate-ledger.ts

@@ -42,6 +42,7 @@
  * `"resolution"` is the default reading).
  */
 import { sortedJsonReplacer } from "../utils";
+import { currentGateOrigin, type GateOrigin } from "./gate-origin";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
 const DIR = "_gates";
@@ -138,6 +139,27 @@ export interface GateResolutionRecord {
    * such a record proves is that somebody approved *something*.
    */
   planDigest?: string;
+  /**
+   * The channel this resolution was authored on (chant#2384) — set by the
+   * writer, never by the caller. `chant approve` records `"cli"`, the
+   * `op-approve` MCP tool records `"mcp"`, an ACP-driven approve records
+   * `"acp"`.
+   *
+   * Absent on every resolution written before chant#2384, and absent is not
+   * `"cli"`: an old record simply does not say. `sameOriginRefusal`
+   * (./gate-origin.ts) refuses only on a positive match, so an unlabelled
+   * record is never refused on this ground.
+   */
+  origin?: GateOrigin;
+  /**
+   * This resolution was recorded from the same channel that reached the gate,
+   * deliberately (chant#2384's `--allow-same-origin`).
+   *
+   * On the record rather than only in the console, because the point of the
+   * refusal is that someone chose to bypass it. A reader auditing the ledger
+   * later should see which approvals had a second party and which did not.
+   */
+  sameOriginOverride?: boolean;
 }
 
 export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">;
@@ -183,6 +205,13 @@ export interface PendingGateRecord {
    * step with no `plan`), which is the shape every gate had before #2300.
    */
   planDigest?: string;
+  /**
+   * The channel the run that reached this gate was driven from (chant#2384).
+   *
+   * This is the half a resolution is compared against: a gate reached over MCP
+   * and resolved over MCP has one author, not two.
+   */
+  origin?: GateOrigin;
 }
 
 export type PendingGateInput = Omit<PendingGateRecord, "version" | "kind">;
@@ -233,7 +262,16 @@ export async function appendPendingGate(
   input: PendingGateInput,
   opts?: { cwd?: string },
 ): Promise<{ commit: string; record: PendingGateRecord }> {
-  const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
+  // chant#2384 — stamped here rather than at each caller, because every pending
+  // fact goes through this function and a channel is a property of the process
+  // rather than of the call. An explicit `origin` on the input still wins, so a
+  // caller that knows better can say so.
+  const record: PendingGateRecord = {
+    version: 1,
+    kind: "pending",
+    origin: currentGateOrigin(),
+    ...input,
+  };
   const commit = await appendGateLine(record, "Pending gate record", opts);
   return { commit, record };
 }

package/src/lifecycle/gate-origin.test.ts

@@ -0,0 +1,93 @@
+import { describe, test, expect, afterEach } from "vitest";
+import {
+  currentGateOrigin,
+  setGateOrigin,
+  resetGateOrigin,
+  isModelAuthored,
+  sameOriginRefusal,
+  UNATTESTED_APPROVER,
+} from "./gate-origin";
+
+/**
+ * chant#2384 — the gate's two halves must have different authors.
+ *
+ * The gate as a durable, plan-bound fact is the strongest thing chant says
+ * about agent-driven change: a run reaching an unapproved gate records a
+ * pending fact and exits 3, and since #2300 a resolution counts only for the
+ * plan it names. All of that rests on the run and the approval being authored
+ * by different parties.
+ *
+ * At a shell they are, and the ledger's existing stance is right there: anyone
+ * who can run `chant approve` can also run `chant run`, the same trust boundary
+ * a local commit has. On MCP and ACP it stops being right, because the person's
+ * only act was launching the server — `op-run` returns the gate it stopped on
+ * and `op-approve` resolves it, both authored by the same model in the same
+ * session, and #2300's plan binding does not close it because the digest comes
+ * off the pending fact that same caller produced one tool call earlier.
+ */
+describe("gate origin (chant#2384)", () => {
+  afterEach(() => resetGateOrigin());
+
+  test("the process serves one channel, and it is the CLI unless an entry point says otherwise", () => {
+    expect(currentGateOrigin()).toBe("cli");
+    setGateOrigin("mcp");
+    expect(currentGateOrigin()).toBe("mcp");
+    resetGateOrigin();
+    expect(currentGateOrigin()).toBe("cli");
+  });
+
+  test("only MCP and ACP are model-authored", () => {
+    expect(isModelAuthored("mcp")).toBe(true);
+    expect(isModelAuthored("acp")).toBe(true);
+    // The distinction the whole rule rests on: at a shell a person typed each
+    // command, so the two halves already have different authors.
+    expect(isModelAuthored("cli")).toBe(false);
+    expect(isModelAuthored(undefined)).toBe(false);
+  });
+
+  describe("the same-origin rule", () => {
+    test("refuses a gate reached and resolved on the same model-authored channel", () => {
+      expect(sameOriginRefusal("mcp", "mcp")).toContain("the same caller wrote both halves");
+      expect(sameOriginRefusal("acp", "acp")).toContain("the same caller wrote both halves");
+    });
+
+    test("allows run-then-approve at a shell, which is the intended workflow", () => {
+      // Both halves are `cli` and that is fine. This is the case the issue is
+      // explicit about keeping: `chant approve` typed at a shell followed by
+      // `chant run` still walks through.
+      expect(sameOriginRefusal("cli", "cli")).toBeUndefined();
+    });
+
+    test("allows a model's run approved by a person, which is the separation the gate is for", () => {
+      expect(sameOriginRefusal("mcp", "cli")).toBeUndefined();
+      expect(sameOriginRefusal("acp", "cli")).toBeUndefined();
+    });
+
+    test("allows a person's run approved over MCP, since a person still authored one half", () => {
+      expect(sameOriginRefusal("cli", "mcp")).toBeUndefined();
+    });
+
+    test("refuses across the two model channels only when they are the same one", () => {
+      // Distinct model channels are two sessions, not one caller writing both
+      // halves — so this is permitted, and deliberately so.
+      expect(sameOriginRefusal("mcp", "acp")).toBeUndefined();
+      expect(sameOriginRefusal("acp", "mcp")).toBeUndefined();
+    });
+
+    test("an unlabelled pending fact is never refused, so old ledgers keep working", () => {
+      // Every record written before this change has no origin. Absent is not
+      // "cli" and not a wildcard: the rule fires on a positive match only, so a
+      // pre-#2384 pending fact cannot start refusing approvals retroactively.
+      expect(sameOriginRefusal(undefined, "mcp")).toBeUndefined();
+      expect(sameOriginRefusal(undefined, "acp")).toBeUndefined();
+      expect(sameOriginRefusal(undefined, "cli")).toBeUndefined();
+    });
+  });
+
+  test("the unattested approver is a fixed marker, not a name anyone chose", () => {
+    // `op-approve` took a free-text `approver` on a channel that cannot verify
+    // one, so the model named itself whatever it liked and the ledger recorded
+    // it indistinguishably from a name a person gave.
+    expect(UNATTESTED_APPROVER).toBe("unattested");
+  });
+});

package/src/lifecycle/gate-origin.ts

@@ -0,0 +1,113 @@
+/**
+ * Which channel a gate fact was authored on — chant#2384.
+ *
+ * The gate is the strongest thing chant says about agent-driven change: a run
+ * that reaches an unapproved gate records a pending fact and exits 3, and since
+ * #2300 a resolution counts only for the plan it names. That property rests on
+ * the two halves being authored by different parties.
+ *
+ * `gate-ledger.ts` already states the trust boundary, and is right about it:
+ *
+ * > this record is *not* itself an authorization check — anyone who can run
+ * > `chant approve` locally can write one, the same trust boundary a local
+ * > commit already has.
+ *
+ * That holds at a shell. A person who can run `chant approve` can also run
+ * `chant run`, and the ledger records what they did. It stops holding on MCP
+ * and ACP, because the person's only act was launching the server once; every
+ * call after that is authored by the model. `op-run` returns the gate it
+ * stopped on and `op-approve` resolves it, so the same caller writes both
+ * halves and the separation is gone.
+ *
+ * The ledger could not tell those situations apart, because both produce a
+ * `resolvedBy` string with no record of where it came from. This records the
+ * where.
+ *
+ * ## Why an ambient value rather than a parameter
+ *
+ * A channel is a property of the process, not of a call. A `chant mcp` server
+ * is launched once by a person and then serves a model for its lifetime; there
+ * is no call on it that is not model-authored. So the origin is established at
+ * the entry point and read by whoever writes a ledger line, rather than
+ * threaded through every runtime, executor and step that sits between them.
+ *
+ * This is provenance, not authentication. It records the door a fact came
+ * through. It does not prove who was behind it, and nothing here should be read
+ * as if it did — see {@link UNATTESTED_APPROVER}.
+ */
+
+/** A channel a gate fact can be authored on. */
+export type GateOrigin = "cli" | "mcp" | "acp";
+
+/**
+ * Channels where the caller is a model rather than a person.
+ *
+ * The distinction this type exists to draw. On `cli` a human typed each
+ * command and the existing trust boundary is the right one. On `mcp` and `acp`
+ * a human launched a server and a model authored everything after, so a gate
+ * resolved from the same channel that produced it has no second party in it.
+ */
+const MODEL_AUTHORED: ReadonlySet<GateOrigin> = new Set<GateOrigin>(["mcp", "acp"]);
+
+/** Whether a channel's calls are authored by a model rather than by a person. */
+export function isModelAuthored(origin: GateOrigin | undefined): boolean {
+  return origin !== undefined && MODEL_AUTHORED.has(origin);
+}
+
+/**
+ * What `resolvedBy` says for a resolution recorded on a channel that cannot
+ * attest to a name.
+ *
+ * `op-approve` used to take a free-text `approver` and write it down. Recording
+ * a name the model chose is worse than recording nothing, because it reads in
+ * the ledger exactly like a name a person gave. This is the honest value.
+ */
+export const UNATTESTED_APPROVER = "unattested";
+
+let ambient: GateOrigin = "cli";
+
+/**
+ * Declare the channel this process serves. Called once at an entry point, not
+ * per call: `chant mcp` sets `"mcp"` before it serves anything, `chant acp`
+ * sets `"acp"`, and the CLI leaves the default.
+ */
+export function setGateOrigin(origin: GateOrigin): void {
+  ambient = origin;
+}
+
+/** The channel this process serves. `"cli"` unless an entry point said otherwise. */
+export function currentGateOrigin(): GateOrigin {
+  return ambient;
+}
+
+/** Restore the default. For tests, which must not leak a channel into each other. */
+export function resetGateOrigin(): void {
+  ambient = "cli";
+}
+
+/**
+ * Why a resolution from this origin cannot answer a pending fact from the same
+ * one, or `undefined` when it can.
+ *
+ * The rule, and the two cases it deliberately leaves alone:
+ *
+ *   - Same channel, model-authored. Refused. `op-run` produced the pending
+ *     fact and `op-approve` would resolve it, both authored by the same model
+ *     in the same session. Nothing about that is an approval.
+ *   - Same channel, `cli`. Allowed. A person ran `chant run`, read the plan and
+ *     ran `chant approve`. That is the intended workflow and the trust boundary
+ *     the ledger already documents.
+ *   - Different channels. Allowed, and the point: a model's run approved by a
+ *     person at a shell is exactly the separation the gate is for.
+ */
+export function sameOriginRefusal(
+  pendingOrigin: GateOrigin | undefined,
+  resolutionOrigin: GateOrigin,
+): string | undefined {
+  if (!isModelAuthored(resolutionOrigin)) return undefined;
+  if (pendingOrigin !== resolutionOrigin) return undefined;
+  return (
+    `the gate was reached over ${resolutionOrigin} and this resolution arrived over ${resolutionOrigin} too, ` +
+    "so the same caller wrote both halves"
+  );
+}