@intentius/chant 0.115.0 → 0.117.0

package/src/cli/main.ts

@@ -36,6 +36,7 @@ import { runGraph } from "./handlers/graph";
 import { runExplain } from "./handlers/explain";
 import { runSearch } from "./handlers/search";
 import { runOp, runOpList, runOpStatus, runOpApprove, runOpSignalRenamed, runOpCancel, runOpLog } from "./handlers/run";
+import { runOpWaveCommand } from "./handlers/run-wave";
 import { runOperator, runOperatorStatus, runOperatorLog, runApprove } from "./handlers/operator";
 import { runEmulator } from "./handlers/emulator";
 import { splitJoinedFlags, dispatchCommandGroup, collectCommandGroups, formatCommandGroupsHelp, type CommandGroup } from "./command-group";
@@ -106,6 +107,7 @@ const BOOLEAN_FLAGS = new Set([
   "--allow-code",
   "--root-only",
   "--generated",
+  "--decide",
 ]);
 
 /**
@@ -355,6 +357,13 @@ export function parseArgs(args: string[]): ParsedArgs {
       const wave = Number(raw);
       if (!Number.isInteger(wave) || wave < 1) throw new Error(`--wave needs a wave number from 1: got "${raw ?? ""}"`);
       result.wave = wave;
+    } else if (arg === "--decide") {
+      result.decide = true;
+    } else if (arg === "--share") {
+      const raw = args[++i];
+      const share = Number(raw);
+      if (!Number.isInteger(share) || share < 1) throw new Error(`--share needs a share number from 1: got "${raw ?? ""}"`);
+      result.share = share;
     } else if (arg === "--canary") {
       const raw = args[++i];
       if (!raw || raw.startsWith("-")) throw new Error("--canary needs a component name: --canary <name>[,<name>...]");
@@ -372,7 +381,11 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--pr-loop") {
       result.prLoop = true;
     } else if (arg === "--resume") {
-      result.resume = args[++i];
+      // `chant approve <op> <gate> --resume` (#3683) takes no value; the
+      // fan-out and pull-request apply take the attempt file they resume.
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith("-")) result.resumeRun = true;
+      else result.resume = args[++i];
     } else if (arg === "--local") {
       result.local = true;
     } else if (arg === "--json") {
@@ -909,6 +922,13 @@ Ops:
   run approve <op> <gate>  Record a gate's resolution and wake the runtime
   run cancel <name>     Cancel the active run (requires --force)
   run log <name>        Show run history for an Op
+  run wave --spec <file> --wave <k>  Plan, gate and apply wave k of an Op
+                        waves spec (#3679): the job a generated waves
+                        pipeline runs. --decide plans and decides only;
+                        --share <i> applies one share of a decided wave
+  run resume [--op <name>]  Start again each CI job that waits at a gate an
+                        approval now answers, through the forge's API
+                        (#3683); approves nothing. --dry-run lists them
   run --generate <provider>  Write one CI pipeline file per scheduled Op for
                         github, gitlab or forgejo (#2533), from every Op that
                         declares a schedule or from --spec <file.json>.
@@ -963,7 +983,10 @@ Ops:
                         counts only an approval sealed by a key the signers
                         file at base lists for --actor. --relayed-by
                         <principal> records who carried the approval to chant
-                        for --actor (a follower, a bot); --sign covers it
+                        for --actor (a follower, a bot); --sign covers it.
+                        --resume then starts the CI job that waits at the
+                        gate again (GitHub re-run, GitLab retry, Forgejo
+                        dispatch) with CHANT_FORGE_TOKEN
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,
@@ -1815,6 +1838,9 @@ export const commandRegistry: CommandDef[] = [
   { name: "run signal", handler: runOpSignalRenamed },
   { name: "run cancel", handler: runOpCancel },
   { name: "run log", handler: runOpLog },
+  { name: "run wave", handler: runOpWaveCommand },
+  // #3683 — start the CI jobs that wait at gates whose approval arrived. Imported on first use.
+  { name: "run resume", handler: async (ctx) => (await import("./handlers/gate-resume")).runResumeCommand(ctx) },
   { name: "run", handler: runOp },
 
   { name: "operator status", handler: runOperatorStatus },

package/src/cli/registry.ts

@@ -248,8 +248,12 @@ export interface ParsedArgs {
    * <name>`, which generates one CI job per wave.
    */
   waveGate?: string;
-  /** `chant components fan-out --wave <n>` (#3049) — run wave `n` of a `--wave-gate` fan-out and no other. */
+  /** `chant components fan-out --wave <n>` (#3049) — run wave `n` of a `--wave-gate` fan-out and no other. Also `chant run wave --wave <k>` (#3679). */
   wave?: number;
+  /** `chant run wave --decide` (#3679) — plan a wide wave and decide its gate, applying nothing. */
+  decide?: boolean;
+  /** `chant run wave --share <i>` (#3679) — apply share `i` of a decided wide wave. */
+  share?: number;
   /** `chant components fan-out --canary <component>` (#3049), repeatable — components that form wave 1. */
   canary?: string[];
   /**
@@ -287,6 +291,12 @@ export interface ParsedArgs {
    * partway under that approval.
    */
   resume?: string;
+  /**
+   * `chant approve <op> <gate> --resume` (#3683): after recording the
+   * approval, start the CI job that waits at the gate again through the
+   * forge's API. Set when `--resume` is given no value.
+   */
+  resumeRun?: boolean;
   /** `chant audit --tier merge-worthy|all` */
   tier?: string;
   /**

package/src/lexicon.ts

@@ -10,6 +10,7 @@ import type { AgentConfigImporter } from "./agents/importer";
 import type { ArtifactIntegrity } from "./lexicon-integrity";
 import type { GatedWavePipelineOptions } from "./components/gated-wave-pipeline";
 import type { PrLoopPipelineOptions } from "./components/pr-pipeline";
+import type { OpWaveJob, OpWavesSpec } from "./op/op-waves";
 import type { OkfFile } from "./okf";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
@@ -900,6 +901,23 @@ export interface OpPipelineResult {
   jobs: OpPipelineJob[];
 }
 
+/**
+ * Options for an Op waves pipeline (#3679): the generic knobs of
+ * {@link ComponentPipelineOptions} that apply to every wave job, and the path
+ * of the spec file the jobs read.
+ */
+export interface OpWavesPipelineOptions
+  extends Pick<ComponentPipelineOptions, "image" | "beforeScript" | "extraScript" | "variables" | "opsStage" | "opsFileName"> {
+  /** The spec's path from the repository root. Every job runs `chant run wave --spec <specFile>`. */
+  specFile: string;
+}
+
+/** An Op waves pipeline: one file, and its jobs in order. */
+export interface OpWavesPipelineResult {
+  files: OpPipelineFile[];
+  jobs: OpWaveJob[];
+}
+
 /**
  * Live status of a single deploy unit (a CloudFormation stack, a K8s release, …)
  * addressed by its deployed name — the per-component presence signal
@@ -1325,6 +1343,14 @@ export interface LexiconPlugin {
     options?: ComponentPipelineOptions,
   ): OpPipelineResult;
 
+  /**
+   * Render ordered waves of Op runs, each behind one gate (#3679,
+   * `./op/op-waves.ts`): one job per wave, or a deciding job and share jobs
+   * for a wide one, each wave needing the one before. Only CI-provider
+   * lexicons implement this.
+   */
+  generateOpWavesPipeline?(spec: OpWavesSpec, options: OpWavesPipelineOptions): OpWavesPipelineResult;
+
   /**
    * Host Op runs — the seam `chant run <op> --on <this lexicon>` dispatches to
    * (#2121, epic #2114). Core ships one provider of its own, `local`, and

package/src/lifecycle/gate-ledger.ts

@@ -46,6 +46,7 @@ import { samePlanDigest } from "./plan-digest";
 import { sortedJsonReplacer } from "../utils";
 import { currentGateOrigin, type GateOrigin } from "./gate-origin";
 import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../op/gate-approval";
+import type { GateRunLocator } from "../op/gate-resume";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
 const DIR = "_gates";
@@ -270,6 +271,12 @@ export interface PendingGateRecord {
   expiresAt: string;
   /** The address approval happens at, when the run knew one — see {@link resolveApprovalUrl}. */
   url?: string;
+  /**
+   * The CI job that reached this gate (#3683), when it ran in one: what
+   * `chant approve --resume` and `chant run resume` hand the forge to start
+   * that job again (`../op/gate-resume.ts`). Absent outside CI.
+   */
+  resume?: GateRunLocator;
   /**
    * The plan the run reached this gate with (#2300) — `computePlanDigest`'s
    * output (`./plan-digest.ts`). This is what `chant approve` copies onto the

package/src/op/gate-resume.e2e.test.ts

@@ -0,0 +1,135 @@
+/**
+ * #3683 end to end on a real Forgejo with a runner: a job waits at a gate
+ * (exit 3), an approval lands, and {@link resumeGateRun} starts the job again
+ * without a push, from the locator {@link resolveGateRunLocator} reads off the
+ * job's own environment. The resume call uses a token with the
+ * `write:repository` scope alone, the least Forgejo's dispatch accepts.
+ *
+ * The job stands in for `chant run wave`: it prints its environment and exits
+ * 3 until a file named `approved` exists on the `lifecycle` branch. What a
+ * chant gate records and decides is covered by the unit tests; this proves
+ * the forge's half.
+ *
+ * Runs only with CHANT_E2E_FORGEJO_URL and CHANT_E2E_FORGEJO_TOKEN (a token
+ * with every scope, which creates and deletes the repository), against a
+ * Forgejo whose runner takes `docker` jobs. CHANT_E2E_FORGEJO_RESUME_TOKEN is
+ * the token the resume calls with; mint it with the `write:repository` scope
+ * alone (Forgejo mints tokens only over basic auth). Without it the resume
+ * uses the first token.
+ */
+
+import { afterAll, describe, expect, test } from "vitest";
+import { resolveGateRunLocator, resumeGateRun } from "./gate-resume";
+
+const URL_ = process.env.CHANT_E2E_FORGEJO_URL?.replace(/\/+$/, "");
+const TOKEN = process.env.CHANT_E2E_FORGEJO_TOKEN;
+const RESUME_TOKEN = process.env.CHANT_E2E_FORGEJO_RESUME_TOKEN ?? TOKEN;
+const api = `${URL_}/api/v1`;
+
+const WORKFLOW = `name: gate
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+jobs:
+  wait:
+    runs-on: docker
+    steps:
+      - run: |
+          env | grep -E '^(GITHUB_|FORGEJO_|GITEA_)' | grep -v TOKEN | sort | sed 's/^/CHANT_E2E_ENV /'
+          code=$(curl -s -o /dev/null -w '%{http_code}' -H "Authorization: token \${{ secrets.GITHUB_TOKEN }}" "$GITHUB_API_URL/repos/$GITHUB_REPOSITORY/contents/approved?ref=lifecycle")
+          echo "approval lookup answered $code"
+          [ "$code" = 200 ] || exit 3
+`;
+
+async function call(method: string, path: string, body?: unknown, token = TOKEN!): Promise<any> { // eslint-disable-line @typescript-eslint/no-explicit-any -- untyped forge JSON
+  const res = await fetch(`${api}${path}`, {
+    method,
+    headers: { Authorization: `token ${token}`, "Content-Type": "application/json" },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`${method} ${path}: ${res.status} ${text.slice(0, 300)}`);
+  try {
+    return text ? JSON.parse(text) : null;
+  } catch {
+    return text;
+  }
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+interface Run {
+  id: number;
+  status: string;
+  event: string;
+  trigger_event?: string;
+}
+
+async function runs(repo: string): Promise<Run[]> {
+  const listed = await call("GET", `/repos/${repo}/actions/runs?limit=50`);
+  return (listed.workflow_runs ?? listed) as Run[];
+}
+
+async function finished(repo: string, pick: (r: Run) => boolean, timeoutMs = 240_000): Promise<Run> {
+  const end = Date.now() + timeoutMs;
+  while (Date.now() < end) {
+    const run = (await runs(repo)).find(pick);
+    if (run && !["waiting", "running", "blocked", "unknown"].includes(run.status)) return run;
+    await sleep(3000);
+  }
+  throw new Error(`no finished run in ${repo} within ${timeoutMs}ms`);
+}
+
+describe.skipIf(!URL_ || !TOKEN)("resume a waiting job on Forgejo (#3683)", () => {
+  const name = `chant-e2e-resume-${Date.now().toString(36)}`;
+  let owner = "";
+
+  afterAll(async () => {
+    if (owner) await call("DELETE", `/repos/${owner}/${name}`).catch(() => undefined);
+  });
+
+  test("the job waits, the approval lands, and a dispatch resumes it without a push", async () => {
+    owner = (await call("GET", "/user")).login;
+    await call("POST", "/user/repos", { name, auto_init: true, default_branch: "main", private: false });
+    const repo = `${owner}/${name}`;
+    await call("POST", `/repos/${repo}/branches`, { new_branch_name: "lifecycle", old_branch_name: "main" });
+    await call("POST", `/repos/${repo}/contents/.forgejo/workflows/gate.yml`, {
+      content: Buffer.from(WORKFLOW).toString("base64"),
+      message: "gate workflow",
+      branch: "main",
+    });
+
+    // The push runs the job, which waits at the gate.
+    const waited = await finished(repo, () => true);
+    expect(waited.status).toBe("failure");
+
+    // Its environment, as the job printed it, is what a pending fact records.
+    const jobs = await call("GET", `/repos/${repo}/actions/runs/${waited.id}/jobs`);
+    const jobId = (jobs.jobs ?? jobs)[0].id;
+    const log = String(await call("GET", `/repos/${repo}/actions/jobs/${jobId}/logs`));
+    const env: Record<string, string> = {};
+    for (const m of log.matchAll(/CHANT_E2E_ENV ([A-Z_]+)=(.*)/g)) env[m[1]!] = m[2]!.trim();
+    const loc = resolveGateRunLocator(env);
+    expect(loc).toMatchObject({ forge: "forgejo", repo, run: String(waited.id), workflow: "gate.yml", ref: "main" });
+
+    const token = RESUME_TOKEN!;
+    // The job reaches Forgejo by the address its runner uses, which on a
+    // local stack is a container name; this test reaches it by its own.
+    const reachable = { ...loc!, api };
+
+    // Approve (here: the file the job looks for), then resume.
+    const approvedAt = new Date().toISOString();
+    await call("POST", `/repos/${repo}/contents/approved`, { content: Buffer.from("yes").toString("base64"), message: "approve", branch: "lifecycle" });
+    const outcome = await resumeGateRun(reachable, { token, since: approvedAt });
+    expect(outcome).toMatchObject({ status: "resumed", how: "dispatched gate.yml on main" });
+
+    const resumed = await finished(repo, (r) => r.id > waited.id);
+    expect(resumed.status).toBe("success");
+    expect(resumed.trigger_event ?? resumed.event).toBe("workflow_dispatch");
+
+    // A second resume finds the run that already started and starts nothing.
+    expect(await resumeGateRun(reachable, { token, since: approvedAt })).toMatchObject({ status: "skipped" });
+    expect((await runs(repo)).filter((r) => r.id > waited.id)).toHaveLength(1);
+  }, 600_000);
+});

package/src/op/gate-resume.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, test } from "vitest";
+import type { ForgeFetch } from "../pr-forge";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+import { evaluateGate, memoryGateLedgerPort } from "./gate";
+import {
+  isGateRunLocator,
+  resolutionAnswering,
+  resolveGateRunLocator,
+  resumeGateRun,
+  resumeTokenFromEnv,
+  type GateRunLocator,
+} from "./gate-resume";
+
+/** A fake forge: answers by "METHOD path" and records every call. */
+function fakeForge(routes: Record<string, unknown>) {
+  const calls: Array<{ method: string; url: string; headers: Record<string, string>; body?: string }> = [];
+  const fetch: ForgeFetch = async (url, init) => {
+    calls.push({ method: init.method, url, headers: init.headers, ...(init.body ? { body: init.body } : {}) });
+    const key = `${init.method} ${new URL(url).pathname}${new URL(url).search}`;
+    const hit = Object.keys(routes).find((k) => key === k || key.startsWith(`${k}?`) || key.startsWith(k));
+    if (!hit) return { ok: false, status: 404, text: async () => `no route for ${key}` };
+    const body = routes[hit];
+    return { ok: true, status: 200, text: async () => (body === null ? "" : JSON.stringify(body)) };
+  };
+  return { fetch, calls };
+}
+
+const GITHUB_ENV = {
+  GITHUB_ACTIONS: "true",
+  GITHUB_REPOSITORY: "acme/db",
+  GITHUB_RUN_ID: "42",
+  GITHUB_RUN_ATTEMPT: "1",
+  GITHUB_SERVER_URL: "https://github.com",
+  GITHUB_API_URL: "https://api.github.com",
+};
+
+describe("resolveGateRunLocator", () => {
+  test("GitHub Actions: the run and the attempt that waited", () => {
+    expect(resolveGateRunLocator(GITHUB_ENV)).toEqual({
+      forge: "github",
+      api: "https://api.github.com",
+      repo: "acme/db",
+      run: "42",
+      attempt: 1,
+      url: "https://github.com/acme/db/actions/runs/42",
+    });
+  });
+
+  test("Forgejo Actions: the workflow file and branch a dispatch names", () => {
+    const loc = resolveGateRunLocator({
+      ...GITHUB_ENV,
+      FORGEJO_ACTIONS: "true",
+      GITHUB_SERVER_URL: "https://code.example.org",
+      GITHUB_API_URL: "https://code.example.org/api/v1",
+      GITHUB_WORKFLOW: "migrations.yml",
+      GITHUB_REF_NAME: "main",
+    });
+    expect(loc).toMatchObject({ forge: "forgejo", api: "https://code.example.org/api/v1", workflow: "migrations.yml", ref: "main", run: "42" });
+    expect(isGateRunLocator(loc)).toBe(true);
+  });
+
+  test("GitLab CI: the pipeline, the job and its name", () => {
+    expect(
+      resolveGateRunLocator({
+        GITLAB_CI: "true",
+        CI_API_V4_URL: "https://gitlab.example.com/api/v4/",
+        CI_PROJECT_ID: "7",
+        CI_PIPELINE_ID: "100",
+        CI_JOB_ID: "555",
+        CI_JOB_NAME: "wave-2-staging",
+      }),
+    ).toEqual({ forge: "gitlab", api: "https://gitlab.example.com/api/v4", repo: "7", run: "100", job: "555", jobName: "wave-2-staging" });
+  });
+
+  test("outside CI, or missing a part a resume needs, there is none", () => {
+    expect(resolveGateRunLocator({})).toBeUndefined();
+    expect(resolveGateRunLocator({ GITHUB_ACTIONS: "true", GITHUB_REPOSITORY: "a/b" })).toBeUndefined();
+    expect(resolveGateRunLocator({ ...GITHUB_ENV, GITEA_ACTIONS: "true", GITHUB_WORKFLOW: "Deploy" })).toBeUndefined();
+  });
+});
+
+describe("resumeGateRun", () => {
+  const github: GateRunLocator = { forge: "github", api: "https://api.github.com", repo: "acme/db", run: "42", attempt: 1 };
+
+  test("GitHub: re-runs the failed jobs of a finished run, with a bearer token", async () => {
+    const forge = fakeForge({
+      "GET /repos/acme/db/actions/runs/42": { status: "completed", conclusion: "failure", run_attempt: 1 },
+      "POST /repos/acme/db/actions/runs/42/rerun-failed-jobs": null,
+    });
+    const out = await resumeGateRun(github, { token: "t", fetch: forge.fetch });
+    expect(out).toMatchObject({ status: "resumed", how: "re-ran the failed jobs of run 42" });
+    expect(forge.calls.map((c) => c.method)).toEqual(["GET", "POST"]);
+    expect(forge.calls[1]!.headers.Authorization).toBe("Bearer t");
+  });
+
+  test("GitHub: a run still going, or already re-run, is left alone", async () => {
+    const running = fakeForge({ "GET /repos/acme/db/actions/runs/42": { status: "in_progress", run_attempt: 1 } });
+    expect(await resumeGateRun(github, { token: "t", fetch: running.fetch })).toMatchObject({ status: "skipped" });
+    const rerun = fakeForge({ "GET /repos/acme/db/actions/runs/42": { status: "completed", conclusion: "failure", run_attempt: 2 } });
+    const out = await resumeGateRun(github, { token: "t", fetch: rerun.fetch });
+    expect(out).toMatchObject({ status: "skipped", reason: expect.stringContaining("already re-run") });
+    expect(rerun.calls.some((c) => c.method === "POST")).toBe(false);
+  });
+
+  test("GitLab: retries the waiting job, unless a newer job of its name exists", async () => {
+    const gitlab: GateRunLocator = { forge: "gitlab", api: "https://gl/api/v4", repo: "7", run: "100", job: "555", jobName: "wave-2-staging" };
+    const forge = fakeForge({
+      "GET /api/v4/projects/7/jobs/555": { status: "failed", name: "wave-2-staging" },
+      "GET /api/v4/projects/7/pipelines/100/jobs": [{ id: 555, name: "wave-2-staging" }],
+      "POST /api/v4/projects/7/jobs/555/retry": { id: 556 },
+    });
+    expect(await resumeGateRun(gitlab, { token: "t", fetch: forge.fetch })).toMatchObject({ status: "resumed", how: "retried job 555 as job 556" });
+    expect(forge.calls[2]!.headers["PRIVATE-TOKEN"]).toBe("t");
+
+    const retried = fakeForge({
+      "GET /api/v4/projects/7/jobs/555": { status: "failed", name: "wave-2-staging" },
+      "GET /api/v4/projects/7/pipelines/100/jobs": [{ id: 556, name: "wave-2-staging" }],
+    });
+    expect(await resumeGateRun(gitlab, { token: "t", fetch: retried.fetch })).toMatchObject({ status: "skipped", reason: expect.stringContaining("job 556") });
+  });
+
+  test("Forgejo: dispatches the workflow on its branch, unless a run of it started after the approval", async () => {
+    const forgejo: GateRunLocator = { forge: "forgejo", api: "https://fj/api/v1", repo: "acme/db", run: "9", workflow: "migrations.yml", ref: "main" };
+    const forge = fakeForge({
+      "GET /api/v1/repos/acme/db/actions/runs/9": { status: "failure" },
+      "GET /api/v1/repos/acme/db/actions/runs": { workflow_runs: [{ id: 9, prettyref: "main", created: "2026-10-01T00:00:00Z" }] },
+      "POST /api/v1/repos/acme/db/actions/workflows/migrations.yml/dispatches": null,
+    });
+    const out = await resumeGateRun(forgejo, { token: "t", since: "2026-10-02T00:00:00Z", fetch: forge.fetch });
+    expect(out).toMatchObject({ status: "resumed", how: "dispatched migrations.yml on main" });
+    expect(JSON.parse(forge.calls[2]!.body!)).toEqual({ ref: "main" });
+    expect(forge.calls[2]!.headers.Authorization).toBe("token t");
+
+    const again = fakeForge({
+      "GET /api/v1/repos/acme/db/actions/runs/9": { status: "failure" },
+      "GET /api/v1/repos/acme/db/actions/runs": { workflow_runs: [{ id: 10, prettyref: "main", created: "2026-10-02T00:01:00Z" }] },
+    });
+    expect(await resumeGateRun(forgejo, { token: "t", since: "2026-10-02T00:00:00Z", fetch: again.fetch })).toMatchObject({ status: "skipped" });
+  });
+
+  test("a refusal from the forge is thrown with its status", async () => {
+    const fetch: ForgeFetch = async () => ({ ok: false, status: 403, text: async () => "Resource not accessible by integration" });
+    await expect(resumeGateRun(github, { token: "t", fetch })).rejects.toThrow(/403/);
+  });
+});
+
+describe("the pending fact and its answer", () => {
+  test("a gate reached in CI records where its job runs", async () => {
+    const saved = { ...process.env };
+    try {
+      Object.assign(process.env, GITHUB_ENV);
+      const port = memoryGateLedgerPort();
+      await evaluateGate(port, { op: "migrations", gate: "migrations-wave-2", planDigest: `sha256:${"a".repeat(64)}`, now: "2026-10-01T00:00:00Z" });
+      expect(port.appended[0]!.resume).toMatchObject({ forge: "github", run: "42", attempt: 1 });
+    } finally {
+      for (const key of Object.keys(GITHUB_ENV)) if (!(key in saved)) delete process.env[key];
+      Object.assign(process.env, saved);
+    }
+  });
+
+  test("an approval answers the standing fact only for its plan", () => {
+    const digest = `sha256:${"a".repeat(64)}`;
+    const standing: PendingGateRecord = {
+      version: 1, kind: "pending", op: "m", gate: "g", timestamp: "2026-10-01T00:00:00Z", expiresAt: "2026-10-03T00:00:00Z", planDigest: digest,
+    };
+    const approve = (planDigest: string, timestamp = "2026-10-01T01:00:00Z"): GateResolutionRecord => ({ version: 1, op: "m", gate: "g", resolvedBy: "alice", timestamp, planDigest });
+    expect(resolutionAnswering([approve(`sha256:${"b".repeat(64)}`)], standing)).toBeUndefined();
+    expect(resolutionAnswering([approve(digest, "2026-09-30T00:00:00Z")], standing)).toBeUndefined();
+    expect(resolutionAnswering([approve(digest)], standing)?.resolvedBy).toBe("alice");
+  });
+
+  test("the token: CHANT_FORGE_TOKEN first, then the forge's own", () => {
+    expect(resumeTokenFromEnv("github", { GITHUB_TOKEN: "g", CHANT_FORGE_TOKEN: "c" })).toBe("c");
+    expect(resumeTokenFromEnv("forgejo", { GITHUB_TOKEN: "g" })).toBe("g");
+    expect(resumeTokenFromEnv("gitlab", { GITHUB_TOKEN: "g" })).toBeUndefined();
+  });
+});