@intentius/chant 0.124.10 → 0.124.12

package/src/cli/handlers/gate-resume.test.ts

@@ -1,8 +1,22 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test, vi } from "vitest";
 import type { GateResolutionRecord, PendingGateRecord } from "../../lifecycle/gate-ledger";
 import type { ForgeFetch } from "../../pr-forge";
 import { parseArgs } from "../main";
-import { resumeStanding } from "./gate-resume";
+import type { GateResumeCandidate } from "../../op/gate-resume-plan";
+import { resumeCandidate, resumeStanding, resumeWaitingGates } from "./gate-resume";
+
+// The ledgers `resumeWaitingGates` reads, without a `chant/lifecycle` branch.
+const ledgers = vi.hoisted(() => new Map<string, { resolutions: unknown[]; pending: unknown[]; malformed: number }>());
+vi.mock("../../lifecycle/gate-ledger", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../lifecycle/gate-ledger")>()),
+  readGateLedger: async (op: string) => ledgers.get(op) ?? { resolutions: [], pending: [], malformed: 0 },
+}));
+vi.mock("../../lifecycle/git", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../lifecycle/git")>()),
+  listFilesInDir: async () => [...ledgers.keys()].map((op) => `${op}.jsonl`),
+  // No `_gates/<op>/applied.jsonl` (#3858).
+  readBlobFromPath: async () => null,
+}));
 
 const DIGEST = `sha256:${"a".repeat(64)}`;
 const standing: PendingGateRecord = {
@@ -48,4 +62,128 @@ describe("resumeStanding (#3683)", () => {
     expect(parseArgs(["approve", "migrations", "g", "--resume", "--sign"])).toMatchObject({ resumeRun: true, sign: true });
     expect(parseArgs(["components", "pr-apply", "--resume", "attempt.json"]).resume).toBe("attempt.json");
   });
+
+  test("dry run: a waiting job would resume without a forge call", async () => {
+    const fetch: ForgeFetch = async () => {
+      throw new Error("no call expected");
+    };
+    expect(await resumeStanding(standing, [approval], { env: {}, fetch, dryRun: true })).toMatchObject({
+      status: "would-resume",
+      resumable: true,
+      reason: "approved",
+      source: "pending",
+      planDigest: DIGEST,
+      run: { run: "42" },
+    });
+  });
+
+  test("an approval a wave already applied under is spent: no call, in a dry run or not (#3858)", async () => {
+    const fetch: ForgeFetch = async () => {
+      throw new Error("no call expected");
+    };
+    const applied = [{ version: 1 as const, kind: "applied" as const, op: "migrations", gate: "migrations-wave-2", planDigest: DIGEST, approvedAt: approval.timestamp, approvedBy: "alice", timestamp: "2026-10-01T02:00:00Z" }];
+    for (const dryRun of [true, false]) {
+      expect(await resumeStanding(standing, [approval], { env: { GITHUB_TOKEN: "t" }, fetch, dryRun, applied })).toMatchObject({
+        status: "spent",
+        resumable: false,
+        reason: "spent",
+        spent: { appliedAt: "2026-10-01T02:00:00Z" },
+      });
+    }
+  });
+});
+
+describe("a stopped apply (#3858)", () => {
+  const stopped: GateResumeCandidate = {
+    source: "stopped",
+    op: "tf-apply",
+    gate: "wave-2",
+    planDigest: DIGEST,
+    resumable: true,
+    reason: "stopped",
+    message: "the apply stopped",
+    approvedBy: "alice",
+    approvedAt: "2026-10-01T01:00:00Z",
+    run: { forge: "github", api: "https://api.github.com", repo: "acme/infra", run: "57", attempt: 1 },
+    stopped: { appliedAt: "2026-10-01T02:00:00Z", approvedAt: "2026-10-01T01:00:00Z", kind: "changes" },
+  };
+  const forge = (run: Record<string, unknown>) => {
+    const calls: string[] = [];
+    const fetch: ForgeFetch = async (url, init) => {
+      calls.push(`${init.method} ${new URL(url).pathname}`);
+      return { ok: true, status: 200, text: async () => (init.method === "GET" ? JSON.stringify(run) : "") };
+    };
+    return { calls, fetch };
+  };
+
+  test("its run is gone: a dry run says it would resume and starts nothing; a real run re-runs it", async () => {
+    const gone = forge({ status: "completed", conclusion: "cancelled", run_attempt: 1 });
+    expect(await resumeCandidate(stopped, { env: { GITHUB_TOKEN: "t" }, fetch: gone.fetch, dryRun: true })).toMatchObject({
+      status: "would-resume",
+      resumable: true,
+      stopped: { runGone: true },
+    });
+    expect(gone.calls).toEqual(["GET /repos/acme/infra/actions/runs/57"]);
+    expect(await resumeCandidate(stopped, { env: { GITHUB_TOKEN: "t" }, fetch: gone.fetch })).toMatchObject({ status: "resumed", resumable: true });
+    expect(gone.calls.at(-1)).toBe("POST /repos/acme/infra/actions/runs/57/rerun-failed-jobs");
+  });
+
+  test("its run still runs: left alone, not resumable", async () => {
+    const live = forge({ status: "in_progress", run_attempt: 1 });
+    expect(await resumeCandidate(stopped, { env: { GITHUB_TOKEN: "t" }, fetch: live.fetch, dryRun: true })).toMatchObject({
+      status: "skipped",
+      resumable: false,
+      stopped: { runGone: false },
+    });
+    expect(live.calls).toEqual(["GET /repos/acme/infra/actions/runs/57"]);
+  });
+
+  test("no token: a dry run cannot tell whether the run is gone, and says so", async () => {
+    const report = await resumeCandidate(stopped, { env: {}, dryRun: true });
+    expect(report).toMatchObject({ status: "no-token", resumable: false, reason: "stopped" });
+    expect(report.stopped?.runGone).toBeUndefined();
+  });
+});
+
+describe("resume one gate's job (#3854)", () => {
+  const wave = (k: number, run: string, op = "tf-apply"): PendingGateRecord => ({
+    ...standing,
+    op,
+    gate: `${op}-wave-${k}`,
+    expiresAt: "2099-01-01T00:00:00Z",
+    resume: { forge: "github", api: "https://api.github.com", repo: "acme/infra", run, attempt: 1 },
+  });
+  const approve = (p: PendingGateRecord): GateResolutionRecord => ({ ...approval, op: p.op, gate: p.gate });
+  ledgers.set("tf-apply", {
+    pending: [wave(2, "20"), wave(3, "30")],
+    resolutions: [approve(wave(2, "20")), approve(wave(3, "30"))],
+    malformed: 0,
+  });
+  ledgers.set("other", { pending: [wave(1, "10", "other")], resolutions: [approve(wave(1, "10", "other"))], malformed: 0 });
+
+  test("without a gate, every approved job of the op is resumed", async () => {
+    const reports = await resumeWaitingGates({ op: "tf-apply", dryRun: true });
+    expect(reports.map((r) => r.gate).sort()).toEqual(["tf-apply-wave-2", "tf-apply-wave-3"]);
+  });
+
+  test("with a gate, only that gate's job is touched", async () => {
+    const calls: string[] = [];
+    const fetch: ForgeFetch = async (url, init) => {
+      calls.push(`${init.method} ${new URL(url).pathname}`);
+      const body = init.method === "GET" ? { status: "completed", conclusion: "failure", run_attempt: 1 } : null;
+      return { ok: true, status: 200, text: async () => (body ? JSON.stringify(body) : "") };
+    };
+    const reports = await resumeWaitingGates({ op: "tf-apply", gate: "tf-apply-wave-3", env: { GITHUB_TOKEN: "t" }, fetch });
+    expect(reports).toEqual([expect.objectContaining({ gate: "tf-apply-wave-3", status: "resumed" })]);
+    expect(calls).toEqual(["GET /repos/acme/infra/actions/runs/30", "POST /repos/acme/infra/actions/runs/30/rerun-failed-jobs"]);
+  });
+
+  test("a gate without an op looks in every ledger; an unknown gate resumes nothing", async () => {
+    expect((await resumeWaitingGates({ gate: "other-wave-1", dryRun: true })).map((r) => `${r.op}/${r.gate}`)).toEqual(["other/other-wave-1"]);
+    expect(await resumeWaitingGates({ op: "tf-apply", gate: "tf-apply-wave-9", dryRun: true })).toEqual([]);
+  });
+
+  test("`chant run resume` takes --op and --gate", () => {
+    expect(parseArgs(["run", "resume", "--op", "tf-apply", "--gate", "tf-apply-wave-3"])).toMatchObject({ op: "tf-apply", gate: "tf-apply-wave-3" });
+  });
 });

package/src/cli/handlers/gate-resume.ts

@@ -10,51 +10,71 @@
  * question has an answer that passes the gate (`pointGateResumable`, #3835),
  * and `chant workspace points answer --resume` resumes the job right after
  * the answer.
+ *
+ * What to resume is decided from the ledger by `planGateResumes`
+ * (`../../op/gate-resume-plan.ts`, #3858): an approval a wave already applied
+ * under is spent and resumes nothing, and an apply under an approval that
+ * stopped (an applied line with a run locator and no finished line) resumes
+ * once the forge says its run is gone.
  */
 
 import {
   GATES_DIR,
-  isPendingGateExpired,
   readGateLedger,
   type GateResolutionRecord,
   type PendingGateRecord,
 } from "../../lifecycle/gate-ledger";
-import { listFilesInDir, pushLifecycleStatus, requireLifecycleLedger } from "../../lifecycle/git";
+import { appliedGatePath, parseAppliedGateFile, type AppliedGateLine, type FinishedGateRecord } from "../../lifecycle/gate-applied";
+import { listFilesInDir, pushLifecycleStatus, readBlobFromPath, requireLifecycleLedger } from "../../lifecycle/git";
 import { parseGateSubject } from "../../op/gate-point";
 import {
-  isGateRunLocator,
   resolutionAnswering,
   resumeGateRun,
   resumeTokenFromEnv,
   type GateResumeOutcome,
 } from "../../op/gate-resume";
-import { pointGateResumable, type PointQuestionState } from "../../point-decision";
+import { planGateResumes, type GateResumeCandidate, type GateResumeReason } from "../../op/gate-resume-plan";
+import type { GateRunLocator } from "../../op/gate-run-locator";
+import type { PointQuestionState } from "../../point-decision";
 import type { ForgeFetch } from "../../pr-forge";
 import { formatError, formatInfo, formatSuccess, formatWarning } from "../format";
 import type { CommandContext } from "../registry";
 
-/** One waiting gate and what resuming it did. */
+/**
+ * One gate a resume looked at and what it did. With `--json`, `chant run
+ * resume` prints these as `{ reports }`; under `--dry-run` it starts nothing,
+ * so a product that resumes in its own job reads `resumable` and `reason`
+ * (#3858).
+ */
 export interface GateResumeReport {
   op: string;
   gate: string;
   environment?: string;
-  /** `resumed` and `skipped` come from the forge; the rest are decided before any call. */
-  status: GateResumeOutcome["status"] | "not-approved" | "no-job" | "no-token" | "failed";
+  /** A standing pending fact, or an apply under an approval that stopped (#3858). */
+  source: GateResumeCandidate["source"];
+  /**
+   * What happened. `resumed`, `skipped` and `would-resume` (`--dry-run`) come
+   * from the forge; the rest are decided before any call.
+   */
+  status: GateResumeOutcome["status"] | "not-approved" | "spent" | "no-job" | "no-token" | "failed";
+  /** Why, from the ledger: `approved`, `answered`, `not-approved`, `spent` or `stopped`. */
+  reason: GateResumeReason;
+  /**
+   * Whether the gate's job should start again: an approval or a passing
+   * answer stands and is not spent, or an apply stopped and the run that
+   * applied is gone. A product that applies in its own job acts on these.
+   */
+  resumable: boolean;
   message: string;
+  planDigest?: string;
   approvedBy?: string;
+  approvedAt?: string;
   url?: string;
-}
-
-/** The newest pending fact per gate and environment: the facts a run still waits on. */
-function standingFacts(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 || new Date(p.timestamp).getTime() >= new Date(prior.timestamp).getTime()) newest.set(key, p);
-  }
-  return [...newest.values()];
+  /** The job a resume starts again. */
+  run?: GateRunLocator;
+  spent?: GateResumeCandidate["spent"];
+  /** `runGone` is what the forge said about the run that applied; absent when it was not asked. */
+  stopped?: GateResumeCandidate["stopped"] & { runGone?: boolean };
 }
 
 export interface ResumeGateOptions {
@@ -68,6 +88,9 @@ export interface ResumeGateOptions {
    * when a fact needs them and none are given.
    */
   questions?: ReadonlyMap<string, PointQuestionState>;
+  /** The lines of `_gates/<op>/applied.jsonl` (#3858). Read from `chant/lifecycle` by {@link resumeOpGates} when not given. */
+  applied?: readonly AppliedGateLine[];
+  finished?: readonly FinishedGateRecord[];
 }
 
 /** Every question the workspace at `cwd` lists, by id, the lifecycle ledger's included. Empty when the workspace can't be read. */
@@ -78,64 +101,117 @@ export async function workspaceQuestions(cwd: string): Promise<Map<string, Point
   return new Map(doc.questions.map((q) => [q.id, { id: q.id, state: q.state, answer: q.answer, answeredBy: q.answeredBy, answeredOn: q.answeredOn }]));
 }
 
-/** Resume the job behind one standing pending fact, when an approval answers it. */
+/** Resume the job behind one standing pending fact, when an approval answers it and is not spent. */
 export async function resumeStanding(
   standing: PendingGateRecord,
   resolutions: readonly GateResolutionRecord[],
   opts: ResumeGateOptions = {},
   pending: readonly PendingGateRecord[] = [standing],
 ): Promise<GateResumeReport> {
-  const base = {
+  const [candidate] = planGateResumes({
     op: standing.op,
-    gate: standing.gate,
-    ...(standing.environment !== undefined ? { environment: standing.environment } : {}),
-    ...(standing.resume?.url ? { url: standing.resume.url } : {}),
+    pending: [standing],
+    resolutions,
+    applied: opts.applied ?? [],
+    now: standing.timestamp,
+    ...(opts.questions ? { questions: opts.questions } : {}),
+    answering: (r, s) => resolutionAnswering(r, s, pending),
+  });
+  return resumeCandidate(candidate!, opts);
+}
+
+/**
+ * Act on one candidate {@link planGateResumes} decided: start its job again
+ * through the forge, or under `dryRun` ask the forge whether it would. A
+ * stopped apply is resumed only once the forge says its run is gone.
+ */
+export async function resumeCandidate(c: GateResumeCandidate, opts: ResumeGateOptions = {}): Promise<GateResumeReport> {
+  const base: GateResumeReport = {
+    op: c.op,
+    gate: c.gate,
+    ...(c.environment !== undefined ? { environment: c.environment } : {}),
+    source: c.source,
+    status: "not-approved",
+    reason: c.reason,
+    resumable: c.resumable,
+    message: c.message,
+    ...(c.planDigest !== undefined ? { planDigest: c.planDigest } : {}),
+    ...(c.approvedBy !== undefined ? { approvedBy: c.approvedBy } : {}),
+    ...(c.approvedAt !== undefined ? { approvedAt: c.approvedAt } : {}),
+    ...(c.run?.url ? { url: c.run.url } : {}),
+    ...(c.run ? { run: c.run } : {}),
+    ...(c.spent ? { spent: c.spent } : {}),
+    ...(c.stopped ? { stopped: { ...c.stopped } } : {}),
   };
-  let approvedBy: { approvedBy: string };
-  let since: string | undefined;
-  if (standing.answer) {
-    // A gate that asks a decision point waits on its question (#3835).
-    const check = pointGateResumable(standing, opts.questions?.get(standing.answer.id));
-    if (!check.resumable) return { ...base, status: "not-approved", message: check.message };
-    approvedBy = { approvedBy: check.answeredBy };
-    since = check.answeredOn ?? undefined;
-  } else {
-    const answer = resolutionAnswering(resolutions, standing, pending);
-    if (!answer) return { ...base, status: "not-approved", message: "no approval answers it yet" };
-    approvedBy = { approvedBy: answer.resolvedBy };
-    since = answer.timestamp;
-  }
-  if (!isGateRunLocator(standing.resume)) {
-    return { ...base, ...approvedBy, status: "no-job", message: "its pending fact names no CI job (it was recorded outside CI); run it again by hand" };
+  if (c.reason === "spent") return { ...base, status: "spent" };
+  if (!c.resumable) return base;
+  if (!c.run) {
+    return { ...base, status: "no-job", message: "its pending fact names no CI job (it was recorded outside CI); run it again by hand" };
   }
-  const loc = standing.resume;
-  if (opts.dryRun) return { ...base, ...approvedBy, status: "skipped", message: `would resume ${loc.forge} run ${loc.run} (--dry-run)` };
-  const token = resumeTokenFromEnv(loc.forge, opts.env ?? process.env);
+  const stopped = c.source === "stopped";
+  const token = resumeTokenFromEnv(c.run.forge, opts.env ?? process.env);
+  // A waiting job needs no forge call to say it would resume; a stopped apply needs one to know its run is gone.
+  if (opts.dryRun && !stopped) return { ...base, status: "would-resume", message: `would resume ${c.run.forge} run ${c.run.run}; ${c.message}` };
   if (!token) {
+    const need = `${c.run.forge === "gitlab" ? "GITLAB_TOKEN" : "GITHUB_TOKEN"}`;
     return {
       ...base,
-      ...approvedBy,
+      ...(stopped ? { resumable: false } : {}),
       status: "no-token",
-      message: `no token to call ${loc.forge} with: set CHANT_FORGE_TOKEN (or ${loc.forge === "gitlab" ? "GITLAB_TOKEN" : "GITHUB_TOKEN"})`,
+      message: stopped
+        ? `${c.message}; whether run ${c.run.run} is gone needs a token to read ${c.run.forge} with: set CHANT_FORGE_TOKEN (or ${need})`
+        : `no token to call ${c.run.forge} with: set CHANT_FORGE_TOKEN (or ${need})`,
     };
   }
   try {
-    const outcome = await resumeGateRun(loc, { token, ...(since ? { since } : {}), ...(opts.fetch ? { fetch: opts.fetch } : {}) });
-    return { ...base, ...approvedBy, status: outcome.status, message: outcome.status === "resumed" ? outcome.how : outcome.reason };
+    const since = stopped ? c.stopped!.appliedAt : c.approvedAt;
+    const outcome = await resumeGateRun(c.run, { token, ...(since ? { since } : {}), ...(opts.fetch ? { fetch: opts.fetch } : {}), ...(opts.dryRun ? { dryRun: true } : {}) });
+    const message = outcome.status === "skipped" ? outcome.reason : outcome.how;
+    if (!stopped) return { ...base, status: outcome.status, message };
+    const gone = outcome.status !== "skipped";
+    return {
+      ...base,
+      status: outcome.status,
+      resumable: gone,
+      message: gone ? `the apply that began at ${c.stopped!.appliedAt} stopped and its run is gone: ${message}` : `the apply that began at ${c.stopped!.appliedAt} is left alone: ${message}`,
+      stopped: { ...c.stopped!, runGone: gone },
+    };
   } catch (err) {
-    return { ...base, ...approvedBy, status: "failed", message: err instanceof Error ? err.message : String(err) };
+    return { ...base, status: "failed", message: err instanceof Error ? err.message : String(err) };
   }
 }
 
-/** Resume every job waiting on `op`'s gates (or one gate) whose approval arrived. */
+/** The `applied` and `finished` lines of `_gates/<op>/applied.jsonl` on `chant/lifecycle`. */
+export async function readAppliedGateFile(op: string): Promise<{ applied: AppliedGateLine[]; finished: FinishedGateRecord[] }> {
+  const { dir, file } = appliedGatePath(op);
+  const text = await readBlobFromPath(dir, file);
+  return text ? parseAppliedGateFile(text) : { applied: [], finished: [] };
+}
+
+/**
+ * Resume every job waiting on `op`'s gates (or one gate) whose approval
+ * arrived and is not spent, and every apply under an approval that stopped
+ * once its run is gone (#3858).
+ */
 export async function resumeOpGates(op: string, gate: string | undefined, opts: ResumeGateOptions = {}): Promise<GateResumeReport[]> {
   const ledger = await readGateLedger(op);
+  const lines = opts.applied ? { applied: opts.applied, finished: opts.finished ?? [] } : await readAppliedGateFile(op);
   const now = opts.now ?? new Date().toISOString();
-  const reports: GateResumeReport[] = [];
-  const standing = standingFacts(ledger.pending, gate).filter((p) => !isPendingGateExpired(p, now));
   // Read the workspace's questions once, and only when a fact waits on one (#3835).
-  const questions = opts.questions ?? (standing.some((p) => p.answer) ? await workspaceQuestions(process.cwd()) : undefined);
-  for (const p of standing) reports.push(await resumeStanding(p, ledger.resolutions, { ...opts, ...(questions ? { questions } : {}) }, ledger.pending));
+  const questions = opts.questions ?? (ledger.pending.some((p) => p.answer) ? await workspaceQuestions(process.cwd()) : undefined);
+  const candidates = planGateResumes({
+    op,
+    pending: ledger.pending,
+    resolutions: ledger.resolutions,
+    applied: lines.applied,
+    finished: lines.finished,
+    now,
+    ...(gate !== undefined ? { gate } : {}),
+    ...(questions ? { questions } : {}),
+    answering: resolutionAnswering,
+  });
+  const reports: GateResumeReport[] = [];
+  for (const c of candidates) reports.push(await resumeCandidate(c, opts));
   return reports;
 }
 
@@ -144,6 +220,7 @@ function printReport(r: GateResumeReport): void {
   const by = r.approvedBy ? `, approved by ${r.approvedBy}` : "";
   const link = r.url ? ` ${r.url}` : "";
   if (r.status === "resumed") console.error(formatSuccess(`${where}${by}: ${r.message}${link}`));
+  else if (r.status === "would-resume") console.error(formatInfo(`${where}${by}: ${r.message}${link}`));
   else if (r.status === "failed" || r.status === "no-token") {
     console.error(formatError({
       message: `${where}${by}: not resumed: ${r.message}`,
@@ -212,11 +289,40 @@ export async function resumeAfterAnswer(question: { id: string; subject: string
   return reports.some((r) => r.status === "failed" || r.status === "no-token") ? 1 : 0;
 }
 
+/** What {@link resumeWaitingGates} reads. */
+export interface ResumeWaitingOptions extends ResumeGateOptions {
+  /** One op's gate ledger; absent, every gate ledger on `chant/lifecycle`. */
+  op?: string;
+  /** Only this gate's waiting job (#3854); absent, every gate's. */
+  gate?: string;
+}
+
 /**
- * `chant run resume [--op <op>] [--dry-run] [--json]`: the scheduled job.
- * Reads every gate ledger on `chant/lifecycle` (or `--op`'s), and starts
- * again each CI job that waits at a gate an approval now answers, or at a
- * gate whose decision point now has an answer that passes it (#3835).
+ * What `chant run resume` does, callable in process: read the gate ledgers
+ * (`op`'s alone, when given) and start again each CI job that waits at a
+ * gate an approval now answers. With `gate`, only that gate's job is touched,
+ * so a caller that just approved one wave resumes that wave's job and no
+ * other (#3854). The lifecycle ledger has to be readable
+ * (`requireLifecycleLedger`).
+ */
+export async function resumeWaitingGates(opts: ResumeWaitingOptions = {}): Promise<GateResumeReport[]> {
+  const { op, gate, ...rest } = opts;
+  const ops = op ? [op] : (await listFilesInDir(GATES_DIR)).filter((f) => f.endsWith(".jsonl")).map((f) => f.slice(0, -".jsonl".length));
+  const reports: GateResumeReport[] = [];
+  for (const o of ops) reports.push(...(await resumeOpGates(o, gate, rest)));
+  return reports;
+}
+
+/**
+ * `chant run resume [--op <op>] [--gate <gate>] [--dry-run] [--json]`: the
+ * scheduled job. Reads every gate ledger on `chant/lifecycle` (or `--op`'s),
+ * and starts again each CI job that waits at a gate (or at `--gate` alone)
+ * an approval now answers, or at a gate whose decision point now has an
+ * answer that passes it (#3835), unless a wave already applied under that
+ * approval (#3858). It also starts again the run of an apply under an
+ * approval that stopped, once that run is gone. `--dry-run --json` starts
+ * nothing and says, per gate, whether it would resume and why, for a product
+ * that resumes in its own job.
  */
 export async function runResumeCommand(ctx: CommandContext): Promise<number> {
   try {
@@ -225,16 +331,19 @@ export async function runResumeCommand(ctx: CommandContext): Promise<number> {
     console.error(formatError({ message: `Cannot read the gate ledgers: ${err instanceof Error ? err.message : String(err)}` }));
     return 1;
   }
-  const ops = ctx.args.op
-    ? [ctx.args.op]
-    : (await listFilesInDir(GATES_DIR)).filter((f) => f.endsWith(".jsonl")).map((f) => f.slice(0, -".jsonl".length));
-  const reports: GateResumeReport[] = [];
-  for (const op of ops) reports.push(...(await resumeOpGates(op, undefined, { dryRun: ctx.args.dryRun === true })));
-  if (ctx.args.json) console.log(JSON.stringify({ reports }, null, 2));
+  const dryRun = ctx.args.dryRun === true;
+  const reports = await resumeWaitingGates({
+    ...(ctx.args.op ? { op: ctx.args.op } : {}),
+    ...(ctx.args.gate ? { gate: ctx.args.gate } : {}),
+    dryRun,
+  });
+  if (ctx.args.json) console.log(JSON.stringify({ dryRun, reports }, null, 2));
   else {
     for (const r of reports.filter((r) => r.status !== "not-approved")) printReport(r);
     const waiting = reports.filter((r) => r.status === "not-approved").length;
-    console.error(formatInfo(`${reports.filter((r) => r.status === "resumed").length} resumed, ${waiting} still waiting for an approval or a passing answer.`));
+    const done = dryRun ? `${reports.filter((r) => r.resumable).length} would resume` : `${reports.filter((r) => r.status === "resumed").length} resumed`;
+    console.error(formatInfo(`${done}, ${waiting} still waiting for an approval or a passing answer.`));
   }
-  return reports.some((r) => r.status === "failed" || r.status === "no-token") ? 1 : 0;
+  // A dry run reads; a missing token only leaves a stopped apply unchecked, which its report says.
+  return reports.some((r) => r.status === "failed" || (!dryRun && r.status === "no-token")) ? 1 : 0;
 }

package/src/cli/main.ts

@@ -952,9 +952,14 @@ Ops:
                         --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 resume [--op <name>] [--gate <name>]  Start again each CI job that
+                        waits at a gate an approval now answers, through the
+                        forge's API (#3683); approves nothing. --gate resumes
+                        that gate's job alone (#3854). Skips an approval a
+                        wave already applied under; restarts an apply that
+                        stopped once its run is gone (#3858). --dry-run
+                        starts nothing; with --json it says per gate whether
+                        it would resume and why
   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>.

package/src/codegen/pinned-upgrade.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, beforeAll } from "vitest";
 import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
@@ -185,6 +185,13 @@ function makeWorkingLexicon(
 }
 
 describe("checkPinnedUpgrade — no upgrade paths", () => {
+  // The first checkPinnedUpgrade loads the k8s lexicon plugin from source, which
+  // takes 1.6s on a quiet machine and over the 5s unit budget on a loaded CI
+  // shard. beforeAll is outside the per-test budget, so pay it there once.
+  beforeAll(async () => {
+    await loadUpstreamPin("k8s");
+  }, 60_000);
+
   test("reports no upgrade when upstream equals pin", async () => {
     const root = mkdtempSync(join(tmpdir(), "chant-up-"));
     try {

package/src/gate-decision-bundle.test.ts

@@ -44,6 +44,7 @@ describe("the gate-decision bundle", () => {
       "packages/core/src/lifecycle/plan-digest.ts",
       "packages/core/src/notify-verify.ts",
       "packages/core/src/notify.ts",
+      "packages/core/src/op/gate-point.ts",
       "packages/core/src/op/op-waves.ts",
       "packages/core/src/workspace/jsonc.ts",
       "packages/core/src/workspace/trust/gate-seal.ts",

package/src/gate-resume-run-bundle.test.ts

@@ -0,0 +1,49 @@
+/**
+ * The gate resume bundles small (#3854).
+ *
+ * terragucci ships one bundled file, and importing `resumeGateRun` from
+ * `@intentius/chant/op/gate-resume` brought Ajv along, through `./op/gate`
+ * and the workspace's identity rules. `@intentius/chant/gate-resume-run` holds
+ * the forge calls, the token lookup and the run locator alone. This bundles it
+ * the way terragucci would and reads esbuild's own list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+const FORBIDDEN = [/node_modules\//, /\/src\/workspace\//, /\/src\/lifecycle\//, /\/src\/cli\//, /\/src\/op\/gate\.ts$/];
+
+describe("the gate-resume-run bundle", () => {
+  test("holds the forge calls and the locator, and no package, workspace, ledger or git code", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "gate-resume-run.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    for (const pattern of FORBIDDEN) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/gate-resume-run.ts",
+      "packages/core/src/op/gate-run-locator.ts",
+      "packages/core/src/pr-forge.ts",
+    ]);
+    const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+    expect(bytes).toBeLessThan(40 * 1024);
+  });
+
+  test("@intentius/chant/op/gate-resume still exports what it did", async () => {
+    const mod = await import("./op/gate-resume");
+    for (const name of ["resumeGateRun", "resumeTokenFromEnv", "resolutionAnswering", "isGateRunLocator", "resolveGateRunLocator"]) {
+      expect(typeof (mod as Record<string, unknown>)[name], name).toBe("function");
+    }
+  });
+});