@intentius/chant 0.116.0 → 0.117.0

package/src/cli/main.ts

@@ -381,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") {
@@ -922,6 +926,9 @@ Ops:
                         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>.
@@ -976,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,
@@ -1829,6 +1839,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/registry.ts

@@ -291,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/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();
+  });
+});

package/src/op/gate-resume.ts

@@ -0,0 +1,267 @@
+/**
+ * Resume the job that waits at a gate (#3683).
+ *
+ * A CI job that reaches a gate nobody approved records a pending fact on
+ * `chant/lifecycle` and exits 3. Nothing re-runs it when the approval lands,
+ * because a push to the ledger branch starts no pipeline. This module closes
+ * that loop through the forge's API.
+ *
+ * When the job runs in CI, the pending fact it records carries a
+ * {@link GateRunLocator}, read from the job's environment by
+ * {@link resolveGateRunLocator}: which forge, the API base, the repository,
+ * the run, and what the forge needs to start it again. After an approval,
+ * {@link resumeGateRun} starts it again:
+ *
+ * | Forge | Call | Token |
+ * |---|---|---|
+ * | GitHub | `POST /repos/{repo}/actions/runs/{run}/rerun-failed-jobs` | `actions: write` (the job's `GITHUB_TOKEN` with that permission, or a fine-grained token with Actions read and write) |
+ * | GitLab | `POST /projects/{id}/jobs/{job}/retry` | a project or personal access token with the `api` scope and the Developer role; `CI_JOB_TOKEN` cannot retry jobs |
+ * | Forgejo | `POST /repos/{repo}/actions/workflows/{file}/dispatches` on the run's branch | a token with the `write:repository` scope; Forgejo has no API to re-run a run, so it starts a new run of the workflow |
+ *
+ * GitHub re-runs the failed job and the jobs that need it, at the same
+ * commit. GitLab retries the job, and the jobs it skipped run after it. A
+ * Forgejo dispatch runs the whole workflow again at the branch's head, so the
+ * jobs before the gate run again too; they must be safe to repeat (a wave
+ * whose runs already applied plans nothing and applies nothing new).
+ *
+ * Resuming approves nothing. The resumed job decides the gate again from the
+ * ledger, so resuming a run whose approval does not count only makes it wait
+ * again. {@link resumeGateRun} skips a run that is still going, that ended
+ * well, or that was already resumed (a later GitHub attempt, a newer GitLab
+ * job of the same name, a newer Forgejo run of the workflow), so a scheduled
+ * resume job can call it every few minutes without starting a run twice.
+ */
+
+import { ForgeApiError, type ForgeFetch, type ForgeKind } from "../pr-forge";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+import { latestResolutionForPlan } from "../lifecycle/gate-ledger";
+import { tallyGateApprovals } from "./gate";
+
+/** Where the job that recorded a pending fact runs, and what its forge needs to start it again. */
+export interface GateRunLocator {
+  forge: ForgeKind;
+  /** The forge's API base: `$GITHUB_API_URL` (GitHub and Forgejo) or `$CI_API_V4_URL` (GitLab). */
+  api: string;
+  /** `owner/name` on GitHub and Forgejo, the project id on GitLab. */
+  repo: string;
+  /** The run: GitHub's and Forgejo's run id, GitLab's pipeline id. */
+  run: string;
+  /** GitHub: the run attempt that waited. A later attempt means it was already re-run. */
+  attempt?: number;
+  /** GitLab: the job that waited. */
+  job?: string;
+  /** GitLab: that job's name, to find a retry of it. */
+  jobName?: string;
+  /** Forgejo: the workflow file the run came from, which a dispatch names. */
+  workflow?: string;
+  /** Forgejo: the branch a dispatch runs on. */
+  ref?: string;
+  /** The run's page, for a person. */
+  url?: string;
+}
+
+const trimSlash = (s: string): string => s.replace(/\/+$/, "");
+
+/**
+ * The locator of the CI job this process runs in, or undefined outside CI or
+ * when the environment lacks a part a resume needs. Forgejo Actions sets the
+ * `GITHUB_*` variables too, and is told apart by `FORGEJO_ACTIONS` or
+ * `GITEA_ACTIONS`.
+ */
+export function resolveGateRunLocator(env: Record<string, string | undefined> = process.env): GateRunLocator | undefined {
+  if (env.GITLAB_CI === "true") {
+    if (!env.CI_API_V4_URL || !env.CI_PROJECT_ID || !env.CI_PIPELINE_ID || !env.CI_JOB_ID) return undefined;
+    return {
+      forge: "gitlab",
+      api: trimSlash(env.CI_API_V4_URL),
+      repo: env.CI_PROJECT_ID,
+      run: env.CI_PIPELINE_ID,
+      job: env.CI_JOB_ID,
+      ...(env.CI_JOB_NAME ? { jobName: env.CI_JOB_NAME } : {}),
+      ...(env.CI_JOB_URL ? { url: env.CI_JOB_URL } : {}),
+    };
+  }
+  if (env.GITHUB_ACTIONS !== "true" || !env.GITHUB_REPOSITORY || !env.GITHUB_RUN_ID) return undefined;
+  const forgejo = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true";
+  const server = env.GITHUB_SERVER_URL ? trimSlash(env.GITHUB_SERVER_URL) : undefined;
+  const url = server ? `${server}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}` : undefined;
+  if (forgejo) {
+    const workflow = forgejoWorkflowFile(env);
+    const api = env.GITHUB_API_URL ?? (server ? `${server}/api/v1` : undefined);
+    if (!api || !workflow || !env.GITHUB_REF_NAME) return undefined;
+    return {
+      forge: "forgejo",
+      api: trimSlash(api),
+      repo: env.GITHUB_REPOSITORY,
+      run: env.GITHUB_RUN_ID,
+      workflow,
+      ref: env.GITHUB_REF_NAME,
+      ...(url ? { url } : {}),
+    };
+  }
+  const attempt = Number(env.GITHUB_RUN_ATTEMPT);
+  return {
+    forge: "github",
+    api: trimSlash(env.GITHUB_API_URL ?? "https://api.github.com"),
+    repo: env.GITHUB_REPOSITORY,
+    run: env.GITHUB_RUN_ID,
+    ...(Number.isInteger(attempt) && attempt > 0 ? { attempt } : {}),
+    ...(url ? { url } : {}),
+  };
+}
+
+/**
+ * The workflow file a Forgejo run came from, by its base name. Forgejo names
+ * a workflow by its file (`GITHUB_WORKFLOW`, `deploy.yml`); `GITHUB_WORKFLOW_REF`
+ * (`owner/repo/.forgejo/workflows/deploy.yml@refs/heads/main`) says it too.
+ */
+function forgejoWorkflowFile(env: Record<string, string | undefined>): string | undefined {
+  const fromRef = env.GITHUB_WORKFLOW_REF?.split("@")[0]?.split("/").pop();
+  if (fromRef && /\.ya?ml$/.test(fromRef)) return fromRef;
+  const name = env.GITHUB_WORKFLOW;
+  return name && /\.ya?ml$/.test(name) ? name.split("/").pop() : undefined;
+}
+
+/** Whether `value` is a {@link GateRunLocator} a resume can use. */
+export function isGateRunLocator(value: unknown): value is GateRunLocator {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.api !== "string" || typeof v.repo !== "string" || typeof v.run !== "string") return false;
+  if (v.forge === "github") return true;
+  if (v.forge === "gitlab") return typeof v.job === "string";
+  if (v.forge === "forgejo") return typeof v.workflow === "string" && typeof v.ref === "string";
+  return false;
+}
+
+/** What {@link resumeGateRun} did. */
+export type GateResumeOutcome =
+  | { status: "resumed"; forge: ForgeKind; how: string; url?: string }
+  | { status: "skipped"; forge: ForgeKind; reason: string; url?: string };
+
+export interface ResumeGateRunOptions {
+  token: string;
+  /** The approval's time. A Forgejo run of the workflow created after it means the run was already resumed. */
+  since?: string;
+  fetch?: ForgeFetch;
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+function client(base: string, headers: Record<string, string>, fetchImpl: ForgeFetch) {
+  return async (method: string, path: string, body?: unknown): Promise<unknown> => {
+    const url = `${trimSlash(base)}${path}`;
+    const res = await fetchImpl(url, {
+      method,
+      headers: { ...headers, ...(body !== undefined ? { "Content-Type": "application/json" } : {}) },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await res.text();
+    if (!res.ok) throw new ForgeApiError(method, url, res.status, text);
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  };
+}
+
+/**
+ * Start the job a pending fact's locator names again, or say why not. Throws
+ * {@link ForgeApiError} when the forge refuses a call, such as a token
+ * without the access the table in the module doc lists.
+ */
+export async function resumeGateRun(loc: GateRunLocator, opts: ResumeGateRunOptions): Promise<GateResumeOutcome> {
+  const fetchImpl = opts.fetch ?? (globalThis.fetch as unknown as ForgeFetch);
+  const url = loc.url ? { url: loc.url } : {};
+  const skip = (reason: string): GateResumeOutcome => ({ status: "skipped", forge: loc.forge, reason, ...url });
+
+  if (loc.forge === "github") {
+    const call = client(loc.api, { Authorization: `Bearer ${opts.token}`, Accept: "application/vnd.github+json" }, fetchImpl);
+    const path = `/repos/${loc.repo}/actions/runs/${loc.run}`;
+    const run = await call("GET", path);
+    if (!isObject(run)) throw new Error(`GET ${path} returned no run`);
+    if (run.status !== "completed") return skip(`run ${loc.run} is ${String(run.status)}, not finished`);
+    const attempt = typeof run.run_attempt === "number" ? run.run_attempt : undefined;
+    if (loc.attempt !== undefined && attempt !== undefined && attempt > loc.attempt) {
+      return skip(`run ${loc.run} was already re-run (attempt ${attempt}; attempt ${loc.attempt} waited)`);
+    }
+    if (run.conclusion === "success") return skip(`run ${loc.run} succeeded`);
+    await call("POST", `${path}/rerun-failed-jobs`, {});
+    return { status: "resumed", forge: "github", how: `re-ran the failed jobs of run ${loc.run}`, ...url };
+  }
+
+  if (loc.forge === "gitlab") {
+    const call = client(loc.api, { "PRIVATE-TOKEN": opts.token }, fetchImpl);
+    const project = `/projects/${encodeURIComponent(decodeURIComponent(loc.repo))}`;
+    const job = await call("GET", `${project}/jobs/${loc.job}`);
+    if (!isObject(job)) throw new Error(`GET ${project}/jobs/${loc.job} returned no job`);
+    const status = String(job.status);
+    if (status === "success") return skip(`job ${loc.job} succeeded`);
+    if (!["failed", "canceled", "skipped"].includes(status)) return skip(`job ${loc.job} is ${status}, not finished`);
+    const name = loc.jobName ?? (typeof job.name === "string" ? job.name : undefined);
+    if (name) {
+      // The pipeline's jobs list leaves retried jobs out, so the job of this name is its newest try.
+      const jobs = await call("GET", `${project}/pipelines/${loc.run}/jobs?per_page=100`);
+      const newest = Array.isArray(jobs) ? jobs.find((j) => isObject(j) && j.name === name) : undefined;
+      if (isObject(newest) && String(newest.id) !== String(loc.job)) {
+        return skip(`job ${loc.job} (${name}) was already retried as job ${String(newest.id)}`);
+      }
+    }
+    const retried = await call("POST", `${project}/jobs/${loc.job}/retry`);
+    const id = isObject(retried) && retried.id !== undefined ? ` as job ${String(retried.id)}` : "";
+    return { status: "resumed", forge: "gitlab", how: `retried job ${loc.job}${id}`, ...url };
+  }
+
+  const call = client(loc.api, { Authorization: `token ${opts.token}`, Accept: "application/json" }, fetchImpl);
+  const repo = `/repos/${loc.repo}`;
+  const run = await call("GET", `${repo}/actions/runs/${loc.run}`);
+  if (!isObject(run)) throw new Error(`GET ${repo}/actions/runs/${loc.run} returned no run`);
+  const status = String(run.status);
+  if (status === "success") return skip(`run ${loc.run} succeeded`);
+  if (["waiting", "running", "blocked", "unknown"].includes(status)) return skip(`run ${loc.run} is ${status}, not finished`);
+  const listed = await call("GET", `${repo}/actions/runs?workflow_id=${encodeURIComponent(loc.workflow!)}&limit=50`);
+  const runs = isObject(listed) && Array.isArray(listed.workflow_runs) ? listed.workflow_runs : Array.isArray(listed) ? listed : [];
+  // Forgejo reports `created` in whole seconds.
+  const since = opts.since ? Math.floor(new Date(opts.since).getTime() / 1000) * 1000 : undefined;
+  const later = runs.find(
+    (r) =>
+      isObject(r) && Number(r.id) > Number(loc.run) &&
+      (r.prettyref === undefined || r.prettyref === loc.ref) &&
+      (since === undefined || (typeof r.created === "string" && new Date(r.created).getTime() >= since)),
+  );
+  if (isObject(later)) return skip(`run ${String(later.id)} of ${loc.workflow} started after the approval`);
+  await call("POST", `${repo}/actions/workflows/${encodeURIComponent(loc.workflow!)}/dispatches`, { ref: loc.ref });
+  return { status: "resumed", forge: "forgejo", how: `dispatched ${loc.workflow} on ${loc.ref}`, ...url };
+}
+
+/**
+ * The resolution that answers `standing`, read the way a run decides the gate
+ * (the plan, the environment, the quorum), or undefined. A workspace's
+ * `identity.gates` rule is not applied here: the resumed job applies it, and
+ * waits again when the approval does not count.
+ */
+export function resolutionAnswering(
+  resolutions: readonly GateResolutionRecord[],
+  standing: PendingGateRecord,
+): GateResolutionRecord | undefined {
+  const env = standing.environment;
+  const mine = resolutions.filter((r) => env === undefined || r.environment === env);
+  if (standing.approval) {
+    const tally = tallyGateApprovals(mine, standing.gate, standing.timestamp, standing.planDigest, standing.approval);
+    if (tally.permit) return tally.permit;
+    return tally.counted.length >= tally.need ? tally.counted[tally.counted.length - 1] : undefined;
+  }
+  return latestResolutionForPlan(mine, standing.gate, standing.timestamp, standing.planDigest).resolution;
+}
+
+/**
+ * The token a resume uses: `CHANT_FORGE_TOKEN`, else the forge's own
+ * (`GITHUB_TOKEN` or `GH_TOKEN` on GitHub and Forgejo, `GITLAB_TOKEN` on
+ * GitLab), the same order the pull-request loop reads (`../pr-forge.ts`).
+ */
+export function resumeTokenFromEnv(forge: ForgeKind, env: Record<string, string | undefined> = process.env): string | undefined {
+  if (env.CHANT_FORGE_TOKEN) return env.CHANT_FORGE_TOKEN;
+  return forge === "gitlab" ? env.GITLAB_TOKEN : env.GITHUB_TOKEN ?? env.GH_TOKEN;
+}
+