@intentius/chant 0.124.10 → 0.124.12

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

@@ -0,0 +1,228 @@
+/**
+ * What a resume would start again, decided from the ledger alone (#3858).
+ *
+ * `chant run resume` starts again the CI job behind a gate an approval now
+ * answers (`./gate-resume.ts`). A product that resumes in its own job, such
+ * as terragucci's GitHub and Forgejo resume job, which applies the waves
+ * itself from wave 1 with a read-only token, needs the same decision without
+ * the forge call. {@link planGateResumes} makes it, per gate:
+ *
+ * - A standing pending fact (the newest per gate and environment, not
+ *   expired) is resumable when an approval answers it, or when the decision
+ *   point it cites has an answer the gate passes on. One whose answering
+ *   approval a wave already applied under (`approvals.spend`,
+ *   `_gates/<op>/applied.jsonl`, #3784) is `spent`: that apply ran, so there
+ *   is nothing to resume, and a resumed run would only wait again.
+ * - An apply that stopped: the newest applied line of a gate carries a run
+ *   locator (`resume`), no `finished` line says how it ended, and no pending
+ *   fact of the gate is newer. It is resumable once the run that applied is
+ *   gone, which only the forge can say: the caller checks that
+ *   (`resumeGateRun` does, and `chant run resume --dry-run` asks it without
+ *   starting anything). The resumed wave applies the rest under the same
+ *   approval.
+ *
+ * Pure: no git, no forge, no clock, no Ajv. It imports the run locator's
+ * check, the ledger's selection rules and `pointGateResumable`, all of which
+ * bundle on their own, so a product can bundle
+ * `@intentius/chant/op/gate-resume-plan` (`gate-resume-plan-bundle.test.ts`).
+ */
+
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+import { isPendingGateExpired, latestResolutionForPlan } from "../lifecycle/gate-ledger-select";
+import { finishedApply, isApprovalSpent, type AppliedGateLine, type FinishedGateRecord } from "../lifecycle/gate-applied";
+import { samePlanDigest } from "../lifecycle/plan-digest";
+import { pointGateResumable, type PointQuestionState } from "../point-decision";
+import { isGateRunLocator, type GateRunLocator } from "./gate-run-locator";
+
+/**
+ * Why a gate would or would not resume:
+ *
+ * - `approved`: an approval answers its standing pending fact, and no wave applied under it yet.
+ * - `answered`: the decision point it waits on has an answer the gate passes on.
+ * - `not-approved`: nothing answers it yet.
+ * - `spent`: the approval that answers it is spent; a wave already applied under it.
+ * - `stopped`: an apply under an approval stopped before it said how it ended.
+ */
+export type GateResumeReason = "approved" | "answered" | "not-approved" | "spent" | "stopped";
+
+/** One gate a resume looks at, and what the ledger says about it. */
+export interface GateResumeCandidate {
+  /** A standing pending fact, or an apply under an approval that stopped. */
+  source: "pending" | "stopped";
+  op: string;
+  gate: string;
+  environment?: string;
+  planDigest?: string;
+  /**
+   * The ledger says to resume it. For `stopped`, only once the run that
+   * applied is gone, which the caller checks with the forge.
+   */
+  resumable: boolean;
+  reason: GateResumeReason;
+  message: string;
+  approvedBy?: string;
+  /** The answering approval's timestamp, or the answer's date. A Forgejo run created after it was already resumed. */
+  approvedAt?: string;
+  /** The job to start again: the pending fact's `resume`, or the stopped apply's. */
+  run?: GateRunLocator;
+  /** The wave applied under the answering approval at `appliedAt`. */
+  spent?: { appliedAt: string; approvedAt: string; wave?: { number: number; name: string } };
+  /** The apply that stopped: when it began, the approval it ran under, and its wave. */
+  stopped?: { appliedAt: string; approvedAt: string; kind: AppliedGateLine["kind"]; wave?: { number: number; name: string } };
+  /** The standing pending fact, for a product that reads its own fields (a commit, a description). */
+  pending?: PendingGateRecord;
+}
+
+/** The resolution that answers `standing` under its approval block (`resolutionAnswering` in `./gate-resume.ts`). */
+export type GateAnswering = (
+  resolutions: readonly GateResolutionRecord[],
+  standing: PendingGateRecord,
+  pending: readonly PendingGateRecord[],
+) => GateResolutionRecord | undefined;
+
+export interface PlanGateResumesInput {
+  /** The op whose ledger these are. */
+  op: string;
+  pending: readonly PendingGateRecord[];
+  resolutions: readonly GateResolutionRecord[];
+  /** The `applied` and `changes` lines of `_gates/<op>/applied.jsonl` (`parseAppliedGateFile`). */
+  applied?: readonly AppliedGateLine[];
+  /** Its `finished` lines. */
+  finished?: readonly FinishedGateRecord[];
+  now: string;
+  /** Only this gate. */
+  gate?: string;
+  /** The workspace's questions by id, for a fact that cites a decision point. */
+  questions?: ReadonlyMap<string, PointQuestionState>;
+  /**
+   * Which resolution answers a fact. Default: the newest approval of its plan
+   * since the fact. A fact with an `approval` block (a quorum, a policy)
+   * needs chant's tally: pass `resolutionAnswering` from
+   * `@intentius/chant/op/gate-resume`, which `chant run resume` uses.
+   */
+  answering?: GateAnswering;
+}
+
+const time = (iso: string): number => new Date(iso).getTime();
+
+/** The newest pending fact per gate and environment: the facts a run still waits on. */
+export function standingGateFacts(pending: readonly PendingGateRecord[], gate?: string): PendingGateRecord[] {
+  const newest = new Map<string, PendingGateRecord>();
+  for (const p of pending) {
+    if (gate !== undefined && p.gate !== gate) continue;
+    const key = `${p.gate}\u0000${p.environment ?? ""}`;
+    const prior = newest.get(key);
+    if (!prior || time(p.timestamp) >= time(prior.timestamp)) newest.set(key, p);
+  }
+  return [...newest.values()];
+}
+
+/** The newest approval of the fact's plan since the fact, when it has no approval block. */
+const defaultAnswering: GateAnswering = (resolutions, standing) => {
+  if (standing.approval) return undefined;
+  const mine = resolutions.filter((r) => standing.environment === undefined || r.environment === standing.environment);
+  return latestResolutionForPlan(mine, standing.gate, standing.timestamp, standing.planDigest).resolution;
+};
+
+/** The applied line that spent an approval of `gate` and `digest` made at `approvedAt`, if one did. */
+function spentBy(applied: readonly AppliedGateLine[], gate: string, digest: string | undefined, approval: GateResolutionRecord): AppliedGateLine | undefined {
+  if (digest === undefined) return undefined;
+  const probe = { gate, planDigest: digest, timestamp: approval.timestamp, ...(approval.review ? { review: { pr: approval.review.pr, head: approval.review.head } } : {}) };
+  if (!isApprovalSpent(applied, probe)) return undefined;
+  return applied.find((a) => isApprovalSpent([a], probe));
+}
+
+/** Decide, for each standing pending fact and each stopped apply of an op, whether a resume would start its job again and why. */
+export function planGateResumes(input: PlanGateResumesInput): GateResumeCandidate[] {
+  const applied = input.applied ?? [];
+  const finished = input.finished ?? [];
+  const answering = input.answering ?? defaultAnswering;
+  const out: GateResumeCandidate[] = [];
+
+  const standing = standingGateFacts(input.pending, input.gate).filter((p) => !isPendingGateExpired(p, input.now));
+  for (const p of standing) {
+    const base = {
+      source: "pending" as const,
+      op: p.op || input.op,
+      gate: p.gate,
+      ...(p.environment !== undefined ? { environment: p.environment } : {}),
+      ...(p.planDigest !== undefined ? { planDigest: p.planDigest } : {}),
+      ...(isGateRunLocator(p.resume) ? { run: p.resume } : {}),
+      pending: p,
+    };
+    if (p.answer) {
+      const check = pointGateResumable(p, input.questions?.get(p.answer.id));
+      if (!check.resumable) {
+        out.push({ ...base, resumable: false, reason: "not-approved", message: check.message });
+        continue;
+      }
+      // The resolution a wave recorded when it went through on this answer, if one did, is what an apply spends.
+      const cited = input.resolutions.filter((r) => r.gate === p.gate && r.answer?.id === p.answer!.id && samePlanDigest(r.planDigest, p.planDigest));
+      const used = cited.map((r) => ({ r, by: spentBy(applied, p.gate, p.planDigest, r) })).find((x) => x.by);
+      if (used?.by) {
+        out.push({ ...base, resumable: false, reason: "spent", approvedBy: check.answeredBy, approvedAt: used.r.timestamp, message: spentMessage(used.by), spent: spentOf(used.by) });
+        continue;
+      }
+      out.push({ ...base, resumable: true, reason: "answered", approvedBy: check.answeredBy, ...(check.answeredOn ? { approvedAt: check.answeredOn } : {}), message: `question ${p.answer.id} has an answer the gate passes on` });
+      continue;
+    }
+    const answer = answering(input.resolutions, p, input.pending);
+    if (!answer) {
+      out.push({ ...base, resumable: false, reason: "not-approved", message: p.approval && !input.answering ? "its gate has an approval block, which needs chant's tally (pass answering)" : "no approval answers it yet" });
+      continue;
+    }
+    const by = spentBy(applied, p.gate, p.planDigest, answer);
+    if (by) {
+      out.push({ ...base, resumable: false, reason: "spent", approvedBy: answer.resolvedBy, approvedAt: answer.timestamp, message: spentMessage(by), spent: spentOf(by) });
+      continue;
+    }
+    out.push({ ...base, resumable: true, reason: "approved", approvedBy: answer.resolvedBy, approvedAt: answer.timestamp, message: `approved by ${answer.resolvedBy} at ${answer.timestamp}` });
+  }
+
+  for (const line of stoppedApplies(applied, finished, input.pending, input.gate)) {
+    out.push({
+      source: "stopped",
+      op: line.op || input.op,
+      gate: line.gate,
+      planDigest: line.planDigest,
+      resumable: true,
+      reason: "stopped",
+      approvedBy: line.approvedBy,
+      approvedAt: line.approvedAt,
+      run: line.resume!,
+      stopped: { appliedAt: line.timestamp, approvedAt: line.approvedAt, kind: line.kind, ...(line.wave ? { wave: line.wave } : {}) },
+      message: `the apply of ${line.planDigest} under the approval by ${line.approvedBy || "?"} began at ${line.timestamp} and never recorded how it ended; it resumes once run ${line.resume!.run} is gone`,
+    });
+  }
+  return out;
+}
+
+const spentOf = (a: AppliedGateLine): NonNullable<GateResumeCandidate["spent"]> => ({ appliedAt: a.timestamp, approvedAt: a.approvedAt, ...(a.wave ? { wave: a.wave } : {}) });
+const spentMessage = (a: AppliedGateLine): string =>
+  `the approval that answers it is spent: ${a.wave ? `wave ${a.wave.number} (${a.wave.name})` : "a wave"} applied under it at ${a.timestamp}`;
+
+/**
+ * Per gate, the apply that may have stopped: the gate's newest applied line,
+ * or the line that names the same approval and carries a run locator, with
+ * no finished line for it and no pending fact of the gate since.
+ */
+function stoppedApplies(applied: readonly AppliedGateLine[], finished: readonly FinishedGateRecord[], pending: readonly PendingGateRecord[], gate?: string): AppliedGateLine[] {
+  const newest = new Map<string, AppliedGateLine>();
+  for (const a of applied) {
+    if (gate !== undefined && a.gate !== gate) continue;
+    const prior = newest.get(a.gate);
+    if (!prior || time(a.timestamp) >= time(prior.timestamp)) newest.set(a.gate, a);
+  }
+  const out: AppliedGateLine[] = [];
+  for (const [g, last] of newest) {
+    const sameApply = applied.filter(
+      (a) => a.gate === g && samePlanDigest(a.planDigest, last.planDigest) && time(a.approvedAt) === time(last.approvedAt) && isGateRunLocator(a.resume),
+    );
+    const line = sameApply.reduce<AppliedGateLine | undefined>((n, a) => (!n || time(a.timestamp) >= time(n.timestamp) ? a : n), undefined);
+    if (!line) continue;
+    if (sameApply.some((a) => finishedApply(finished, a))) continue;
+    if (pending.some((p) => p.gate === g && time(p.timestamp) > time(line.timestamp))) continue;
+    out.push(line);
+  }
+  return out;
+}

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

@@ -138,6 +138,24 @@ describe("resumeGateRun", () => {
     expect(await resumeGateRun(forgejo, { token: "t", since: "2026-10-02T00:00:00Z", fetch: again.fetch })).toMatchObject({ status: "skipped" });
   });
 
+  test("dryRun reads each forge as a resume would and starts nothing (#3858)", async () => {
+    const gh = fakeForge({ "GET /repos/acme/db/actions/runs/42": { status: "completed", conclusion: "failure", run_attempt: 1 } });
+    expect(await resumeGateRun(github, { token: "t", fetch: gh.fetch, dryRun: true })).toMatchObject({ status: "would-resume", how: "would re-run the failed jobs of run 42" });
+    const gitlab: GateRunLocator = { forge: "gitlab", api: "https://gl/api/v4", repo: "7", run: "100", job: "555", jobName: "wave-2-staging" };
+    const gl = fakeForge({
+      "GET /api/v4/projects/7/jobs/555": { status: "canceled", name: "wave-2-staging" },
+      "GET /api/v4/projects/7/pipelines/100/jobs": [{ id: 555, name: "wave-2-staging" }],
+    });
+    expect(await resumeGateRun(gitlab, { token: "t", fetch: gl.fetch, dryRun: true })).toMatchObject({ status: "would-resume", how: "would retry job 555" });
+    const forgejo: GateRunLocator = { forge: "forgejo", api: "https://fj/api/v1", repo: "acme/db", run: "9", workflow: "migrations.yml", ref: "main" };
+    const fj = fakeForge({
+      "GET /api/v1/repos/acme/db/actions/runs/9": { status: "cancelled" },
+      "GET /api/v1/repos/acme/db/actions/runs": { workflow_runs: [] },
+    });
+    expect(await resumeGateRun(forgejo, { token: "t", fetch: fj.fetch, dryRun: true })).toMatchObject({ status: "would-resume", how: "would dispatch migrations.yml on main" });
+    expect([...gh.calls, ...gl.calls, ...fj.calls].every((c) => c.method === "GET")).toBe(true);
+  });
+
   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/);

package/src/op/gate-resume.ts

@@ -1,149 +1,26 @@
 /**
- * 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.
+ * Resume the job that waits at a gate (#3683). The forge calls,
+ * {@link resumeGateRun} and {@link resumeTokenFromEnv}, live in
+ * `../gate-resume-run.ts`, which bundles without the workspace code (#3854),
+ * and are re-exported here so `@intentius/chant/op/gate-resume` keeps working.
+ * This module adds {@link resolutionAnswering}, which decides whether an
+ * approval answers a pending fact the way a run decides the gate, and so reads
+ * `./gate`'s quorum rules.
  */
 
-import { ForgeApiError, type ForgeFetch, type ForgeKind } from "../pr-forge";
 import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
 import { latestResolutionForPlan } from "../lifecycle/gate-ledger";
 import { humanQuorumSince, tallyGateApprovals } from "./gate";
-import type { GateRunLocator } from "./gate-run-locator";
 
-// The locator is read where a pending fact is recorded, which `@intentius/chant/point-decision` does too, so it lives on its own (#3835).
-export { isGateRunLocator, resolveGateRunLocator, type GateRunLocator } from "./gate-run-locator";
-
-/** 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 trimSlash = (s: string): string => s.replace(/\/+$/, "");
-
-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 };
-}
+export {
+  isGateRunLocator,
+  resolveGateRunLocator,
+  resumeGateRun,
+  resumeTokenFromEnv,
+  type GateResumeOutcome,
+  type GateRunLocator,
+  type ResumeGateRunOptions,
+} from "../gate-resume-run";
 
 /**
  * The resolution that answers `standing`, read the way a run decides the gate
@@ -167,14 +44,3 @@ export function resolutionAnswering(
   }
   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;
-}
-

package/src/op/gate-review.ts

@@ -70,23 +70,9 @@ export function bothRules(a: GateApprovalRule | null, b: GateApprovalRule | null
 
 // ── pr-review ─────────────────────────────────────────────────────────────
 
-/** The digests each wave planned at one commit, recorded for a review of it to approve. */
-export interface HeadPlans {
-  version: 1;
-  /** The Op waves spec's name. */
-  name: string;
-  /** The commit the waves were planned at: a pull request's head. */
-  head: string;
-  timestamp: string;
-  waves: Array<{ wave: number; name: string; digest: string }>;
-}
+// The record and its reader live apart, so a bundle can import them without git (#3865).
+export { HEAD_PLANS_DIR, headPlansPath, type HeadPlans } from "../lifecycle/wave-plans";
 
-/** Where {@link HeadPlans} for `head` live on `chant/lifecycle`: `_wave-plans/<name>/<head>.json`. */
-export const HEAD_PLANS_DIR = "_wave-plans";
-
-export function headPlansPath(name: string, head: string): { dir: string; file: string } {
-  return { dir: `${HEAD_PLANS_DIR}/${name}`, file: `${head}.json` };
-}
 
 /** The merged pull request's review, as a `pr-review` gate reads it. */
 export interface MergedReview {

package/src/op/gate-run-locator.ts

@@ -1,7 +1,7 @@
 /**
  * Where a CI job that waits at a gate runs, and what its forge needs to start
  * it again (#3683). Read from the job's environment when a pending fact is
- * recorded; `./gate-resume.ts` uses it to resume the job. It imports nothing
+ * recorded; `../gate-resume-run.ts` uses it to resume the job. It imports nothing
  * at run time, so `@intentius/chant/point-decision` records it on the pending
  * fact of a gate that asks a decision point too (#3835).
  */

package/src/op/gate.ts

@@ -53,7 +53,7 @@ import { sortedJsonReplacer } from "../utils";
 import { gateContextDigest, type GateApprover, type ResolvedGateApproval } from "./gate-approval";
 import { pushLifecycleReport, readBlobBySha, readBlobFromPath, readPathSha, requireLifecycleLedger, writeBlobToPath, RefCASConflictError } from "../lifecycle/git";
 import { parseDuration } from "./duration";
-import { resolveGateRunLocator } from "./gate-resume";
+import { resolveGateRunLocator } from "./gate-run-locator";
 
 /**
  * What appending a pending fact learned about reaching the remote.

package/src/op/index.ts

@@ -121,6 +121,8 @@ export type { OpRunContext, PassedGate } from "./run-context";
 export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand, describeGateMismatch, gateIsSealed } from "./gate";
 export type { GateLedgerPort, GateCheck, GateCheckInput, PendingGatePush, GateDigestMismatch, GateQuorumProgress, GateTally } from "./gate";
 export { tallyGateApprovals, humanQuorumSince, approverOf } from "./gate";
+export { planGateResumes, standingGateFacts } from "./gate-resume-plan";
+export type { GateResumeCandidate, GateResumeReason, GateAnswering, PlanGateResumesInput } from "./gate-resume-plan";
 export {
   gateApprovalProblems, gateContextDigest, gatePolicyRequest, gatePolicyVersion, isGatePolicyRef, loadGatePolicyEvaluator, GATE_APPROVAL_MODES,
 } from "./gate-approval";

package/src/op/op-waves-point-mcp.e2e.test.ts

@@ -0,0 +1,148 @@
+/**
+ * #3863: a wave gate that asks a decision point (#3836) under a spec that is
+ * `neverOverMcp` records that on its pending fact, so an answer to its
+ * question over MCP is refused (`answer-never-over-mcp`, #3817) and the same
+ * answer from a shell passes the wave.
+ *
+ * The workspace is real (a git repository with the reference workspace's
+ * answer kind, a points file and a trust policy at base), and so is the
+ * asker. The run's pending facts go to the workspace's own `chant/lifecycle`,
+ * where `points answer` reads them; the run reads them back from memory, as a
+ * repository without a remote cannot fetch the ledger branch.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, describe, expect, test, vi } from "vitest";
+import { cleanScratch, git, workspace } from "../workspace/__fixtures__/decide-workspace";
+import { runWorkspacePoints } from "../workspace/points-cli";
+import type { CommandContext } from "../cli/registry";
+import { createWorkspaceTools } from "../cli/mcp/workspace-tools";
+import { resetGateOrigin, setGateOrigin } from "../lifecycle/gate-origin";
+import { appendPendingGate } from "../lifecycle/gate-ledger";
+import { memoryGateLedgerPort, type GateLedgerPort } from "./gate";
+import type { OpWavesSpec } from "./op-waves";
+import { runOpWave, type OpWaveExec, type OpWaveRunsFile, type OpWaveShowAtBase } from "./op-waves-run";
+import { workspaceGatePointAsker } from "./gate-point-run";
+
+const digest = (n: string) => `sha256:${n.repeat(64)}`;
+
+const POINTS = {
+  points: {
+    "prod-apply": {
+      title: "Apply this plan to prod",
+      question: { type: "noul", instructions: "Should this plan be applied to prod?", criteria: { true: "Apply it.", false: "Do not apply it." } },
+      inputs: { "gate.component": "the Op the gate belongs to", "gate.planDigest": "the plan the gate binds" },
+      deciders: [{ kind: "quorum", count: 2, roles: ["lead"] }],
+    },
+  },
+};
+
+const spec: OpWavesSpec = {
+  name: "tf-apply",
+  op: "tf-apply",
+  gateName: "wave-{k}",
+  planWave: ["tg", "plan", "{wave}", "{runs}", "{plans}"],
+  applyWave: ["tg", "apply", "{wave}", "{runs}", "{plans}"],
+  point: { name: "prod-apply" },
+  neverOverMcp: true,
+  waves: [{ name: "net", runs: [{ target: "vpc" }, { target: "nat" }] }],
+};
+
+let root: string;
+const applied: string[] = [];
+
+const exec: OpWaveExec = (argv, dir) => {
+  const runs = JSON.parse(readFileSync(join(dir, argv[3]!), "utf-8")) as OpWaveRunsFile;
+  if (argv[1] === "plan") {
+    writeFileSync(join(dir, argv[4]!), JSON.stringify({
+      runs: runs.runs.map((r, i) => ({ target: r.target, planDigest: digest(String(i + 1)) })),
+      pending: { commit: "c".repeat(40) },
+    }));
+  }
+  if (argv[1] === "apply") applied.push(...runs.runs.map((r) => r.target));
+  return 0;
+};
+const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(spec) });
+
+/** The in-memory port, with each pending fact also appended to the workspace's chant/lifecycle. */
+function ledgerPort(): GateLedgerPort & { appended: ReturnType<typeof memoryGateLedgerPort>["appended"] } {
+  const memory = memoryGateLedgerPort();
+  return {
+    ...memory,
+    async appendPending(input) {
+      await appendPendingGate(input, { cwd: root });
+      return memory.appendPending(input);
+    },
+  };
+}
+
+type Doc = Record<string, unknown> & { error?: { code: string; message: string } };
+
+/** The `points-answer` tool, as `chant serve mcp` serves it in the workspace. */
+async function overMcp(params: Record<string, unknown>): Promise<Doc> {
+  const tool = createWorkspaceTools({ cwd: root }).find((t) => t.definition.name === "points-answer")!;
+  return (await tool.handler(params, {} as never)) as Doc;
+}
+
+/** `chant workspace points answer <id> ...` through the command's handler, in the workspace. */
+async function shell(id: string, by: string[], answer: string): Promise<Doc> {
+  const printed: string[] = [];
+  const log = vi.spyOn(console, "log").mockImplementation((line: unknown) => {
+    printed.push(String(line));
+  });
+  const err = vi.spyOn(console, "error").mockImplementation(() => {});
+  const was = process.cwd();
+  process.chdir(root);
+  try {
+    const ctx = { args: { extraPositional: "answer", extraPositional2: id, answer, bys: by, json: true }, plugins: [], serializers: [] } as unknown as CommandContext;
+    await runWorkspacePoints(ctx);
+  } finally {
+    process.chdir(was);
+    log.mockRestore();
+    err.mockRestore();
+  }
+  return JSON.parse(printed.join("\n")) as Doc;
+}
+
+beforeAll(() => {
+  root = workspace(POINTS);
+  vi.stubEnv("CI", "");
+  mkdirSync(join(root, ".chant"), { recursive: true });
+  writeFileSync(join(root, ".chant", "trust.json"), JSON.stringify({ schema: 1, roles: { agent: ["bot"], lead: ["alice", "bob"] } }));
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "trust");
+});
+
+afterEach(() => resetGateOrigin());
+afterAll(cleanScratch);
+
+describe("a neverOverMcp wave's point gate is not answered over MCP (#3863)", () => {
+  test("the pending fact carries neverOverMcp and the plans file's fields; an MCP answer is refused; a shell answer passes the wave", async () => {
+    const gates = ledgerPort();
+    const asker = workspaceGatePointAsker(root);
+    const run = (now: string) => runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: root, exec, show, gates, points: asker, now, log: () => {} });
+
+    const waiting = await run("2026-10-11T10:00:00.000Z");
+    expect(waiting.exitCode).toBe(3);
+    const id = waiting.decision!.point!.question!.id;
+    expect(gates.appended[0]).toMatchObject({ op: "tf-apply", gate: "wave-1", commit: "c".repeat(40), neverOverMcp: true, answer: { point: "prod-apply", id } });
+
+    setGateOrigin("mcp");
+    const refused = await overMcp({ id, answer: true, by: ["alice", "bob"] });
+    expect(refused.error?.code).toBe("answer-never-over-mcp");
+    expect(refused.error?.message).toContain('gate "wave-1" on "tf-apply"');
+    setGateOrigin("acp");
+    expect((await overMcp({ id, answer: true, by: ["alice", "bob"] })).error?.code).toBe("answer-never-over-mcp");
+    resetGateOrigin();
+
+    expect((await run("2026-10-11T10:05:00.000Z")).exitCode).toBe(3);
+    expect(applied).toEqual([]);
+
+    const answered = await shell(id, ["alice", "bob"], "yes");
+    expect(answered).toMatchObject({ verb: "answer", id, written: true, question: { state: "answered", answer: true } });
+    const passed = await run("2026-10-11T10:10:00.000Z");
+    expect(passed).toMatchObject({ exitCode: 0, decision: { status: "approved", via: "point" } });
+    expect(applied).toEqual(["vpc", "nat"]);
+  });
+});