@intentius/chant 0.116.0 → 0.118.0

package/src/cli/handlers/run-wave.ts

@@ -5,13 +5,25 @@
 
 import { readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
-import { parseOpWavesSpec, runOpWave } from "../../op/op-waves-run";
+import { parseOpWavesSpec, recordOpWaveHeadPlans, runOpWave } from "../../op/op-waves-run";
 import { formatError } from "../format";
 import type { CommandContext } from "../registry";
 
 export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const specFile = args.opsSpec;
+  if (specFile && args.recordPlans) {
+    try {
+      const spec = parseOpWavesSpec(readFileSync(resolve(specFile), "utf-8"), `--spec ${specFile}`);
+      const plans = await recordOpWaveHeadPlans({ spec });
+      if (args.json) console.log(JSON.stringify(plans, null, 2));
+      else for (const w of plans.waves) console.error(`wave ${w.wave} (${w.name}) at ${plans.head.slice(0, 12)}: ${w.digest}`);
+      return 0;
+    } catch (err) {
+      console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+      return 1;
+    }
+  }
   if (!specFile || args.wave === undefined) {
     console.error(formatError({
       message: "`chant run wave` needs --spec <file> and --wave <k>",

package/src/cli/main.ts

@@ -108,6 +108,7 @@ const BOOLEAN_FLAGS = new Set([
   "--root-only",
   "--generated",
   "--decide",
+  "--record-plans",
 ]);
 
 /**
@@ -359,6 +360,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.wave = wave;
     } else if (arg === "--decide") {
       result.decide = true;
+    } else if (arg === "--record-plans") {
+      result.recordPlans = true;
     } else if (arg === "--share") {
       const raw = args[++i];
       const share = Number(raw);
@@ -381,7 +384,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") {
@@ -921,7 +928,13 @@ Ops:
   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
+                        --share <i> applies one share of a decided wave.
+                        --record-plans (no --wave), in a pull request's
+                        pipeline: plan every wave at its head and record the
+                        digests a pr-review approval mode compares
+  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>.
@@ -976,7 +989,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,
@@ -1829,6 +1845,8 @@ export const commandRegistry: CommandDef[] = [
   { 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/plugins.ts

@@ -211,7 +211,7 @@ export function collectBuildRootContributors(
     .filter((plugin) => typeof plugin.buildRoots === "function")
     // `entities` is not bindable here — discovery has not run — so the merge
     // hands it in when it calls the closure (#1828 / SOPS provenance).
-    .map((plugin): import("../lexicon").BuildRootContributor => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities }));
+    .map((plugin): import("../lexicon").BuildRootContributor => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities, ...(ctx?.sourceDir !== undefined ? { sourceDir: ctx.sourceDir } : {}) }));
   return [...codegen, ...roots];
 }
 

package/src/cli/registry.ts

@@ -252,6 +252,8 @@ export interface ParsedArgs {
   wave?: number;
   /** `chant run wave --decide` (#3679) — plan a wide wave and decide its gate, applying nothing. */
   decide?: boolean;
+  /** `chant run wave --record-plans` (#3684) — plan every wave at a pull request's head and record the digests for a `pr-review` gate. */
+  recordPlans?: 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. */
@@ -291,6 +293,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/discovery/files.ts

@@ -116,3 +116,21 @@ export async function findInfraFiles(path: string, options?: FindInfraFilesOptio
     accept: (name, full) => isSourceFileName(name) && !hasDiscoveryMarkerSync(full),
   });
 }
+
+/**
+ * Find the files under `path` that `accept` wants, through the same walk and
+ * the same project globs as {@link findInfraFiles}: a lexicon that reads
+ * source of its own beside the TypeScript (the sql lexicon's `.sql` files)
+ * sees exactly the tree source discovery sees, so `dist`, git-ignored paths,
+ * child projects and the project's `exclude` globs are left out for it too.
+ */
+export async function findSourceFiles(path: string, accept: (name: string, full: string) => boolean, options?: FindInfraFilesOptions): Promise<string[]> {
+  const globs = options?.globs === null ? undefined : (options?.globs ?? (await resolveDiscoveryGlobs(path)));
+  return walkDiscovery({
+    walker: "source",
+    root: path,
+    globs,
+    excludeDirs: await workspaceMemberDirs(path),
+    accept,
+  });
+}

package/src/lexicon.ts

@@ -984,6 +984,15 @@ export interface BuildRootContext {
    * treat an absent map as an empty one.
    */
   entities?: ReadonlyMap<string, Declarable>;
+  /**
+   * The directory this build discovered its source in (the path handed to
+   * `build()`, which `--src` or `sourceDir` chose), absolute. A contributor
+   * that reads files beside the typed source (the sql lexicon's `.sql`
+   * files) reads them here, so it sees the tree discovery saw. Optional: a
+   * caller that is not a build (the graph paths) omits it, and a hook then
+   * falls back to `sourceDir` in `config`, resolved against `projectRoot`.
+   */
+  sourceDir?: string;
 }
 
 /**
@@ -1003,7 +1012,7 @@ export interface BuildRootContribution {
  * the argument is still assignable, which is what every pre-#1828 hook does.
  */
 export type BuildRootContributor = (
-  ctx: Pick<BuildRootContext, "entities">,
+  ctx: Pick<BuildRootContext, "entities" | "sourceDir">,
 ) => Promise<BuildRootContribution>;
 
 /**

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";
@@ -221,6 +222,13 @@ export interface GateResolutionRecord {
    * verifies. Absent on an unsigned approval.
    */
   seal?: GateApprovalSeal;
+  /**
+   * The forge review this approval came from (#3684): a wave whose approval
+   * mode is `pr-review` writes it when the merged pull request's head was
+   * approved by a writer other than its author and planned this digest.
+   * `resolvedBy` is the first of `approvers`.
+   */
+  review?: { pr: number; head: string; approvers: string[] };
   /**
    * The answer record that passed the gate, on a gate that asks a decision
    * point (#3170). The run writes this resolution itself when the point's
@@ -270,6 +278,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();
+  });
+});